new locals API

Author: ericallam

packages/cli-v3/src/entryPoints/dev-run-worker.ts

@@ -20,6 +20,7 @@ import {
   runTimelineMetrics,
   lifecycleHooks,
   lifecycleHooksAdapters,
+  localsAPI,
 } from "@trigger.dev/core/v3";
 import { TriggerTracer } from "@trigger.dev/core/v3/tracer";
 import {
@@ -41,6 +42,7 @@ import {
   UsageTimeoutManager,
   StandardRunTimelineMetricsManager,
   StandardLifecycleHooksManager,
+  StandardLocalsManager,
 } from "@trigger.dev/core/v3/workers";
 import { ZodIpcConnection } from "@trigger.dev/core/v3/zodIpc";
 import { readFile } from "node:fs/promises";
@@ -92,6 +94,9 @@ process.on("uncaughtException", function (error, origin) {
 
 const heartbeatIntervalMs = getEnvVar("HEARTBEAT_INTERVAL_MS");
 
+const standardLocalsManager = new StandardLocalsManager();
+localsAPI.setGlobalLocalsManager(standardLocalsManager);
+
 const standardRunTimelineMetricsManager = new StandardRunTimelineMetricsManager();
 runTimelineMetrics.setGlobalManager(standardRunTimelineMetricsManager);
 standardRunTimelineMetricsManager.seedMetricsFromEnvironment();

packages/cli-v3/src/entryPoints/managed-run-worker.ts

@@ -18,6 +18,7 @@ import {
   waitUntil,
   apiClientManager,
   runTimelineMetrics,
+  localsAPI,
 } from "@trigger.dev/core/v3";
 import { TriggerTracer } from "@trigger.dev/core/v3/tracer";
 import {
@@ -39,6 +40,7 @@ import {
   StandardWaitUntilManager,
   ManagedRuntimeManager,
   StandardRunTimelineMetricsManager,
+  StandardLocalsManager,
 } from "@trigger.dev/core/v3/workers";
 import { ZodIpcConnection } from "@trigger.dev/core/v3/zodIpc";
 import { readFile } from "node:fs/promises";
@@ -93,6 +95,9 @@ const usageEventUrl = getEnvVar("USAGE_EVENT_URL");
 const triggerJWT = getEnvVar("TRIGGER_JWT");
 const heartbeatIntervalMs = getEnvVar("HEARTBEAT_INTERVAL_MS");
 
+const standardLocalsManager = new StandardLocalsManager();
+localsAPI.setGlobalLocalsManager(standardLocalsManager);
+
 const standardRunTimelineMetricsManager = new StandardRunTimelineMetricsManager();
 runTimelineMetrics.setGlobalManager(standardRunTimelineMetricsManager);
 standardRunTimelineMetricsManager.seedMetricsFromEnvironment();

packages/core/src/v3/index.ts

@@ -16,6 +16,7 @@ export * from "./wait-until-api.js";
 export * from "./timeout-api.js";
 export * from "./run-timeline-metrics-api.js";
 export * from "./lifecycle-hooks-api.js";
+export * from "./locals-api.js";
 export * from "./schemas/index.js";
 export { SemanticInternalAttributes } from "./semanticInternalAttributes.js";
 export * from "./resource-catalog-api.js";

packages/core/src/v3/locals-api.ts

@@ -0,0 +1,28 @@
+// Split module-level variable definition into separate files to allow
+// tree-shaking on each api instance.
+import { LocalsAPI } from "./locals/index.js";
+import type { LocalsKey } from "./locals/types.js";
+/** Entrypoint for runtime API */
+export const localsAPI = LocalsAPI.getInstance();
+
+export const locals = {
+  create<T>(id: string): LocalsKey<T> {
+    return localsAPI.createLocal(id);
+  },
+  get<T>(key: LocalsKey<T>): T | undefined {
+    return localsAPI.getLocal(key);
+  },
+  getOrThrow<T>(key: LocalsKey<T>): T {
+    const value = localsAPI.getLocal(key);
+    if (!value) {
+      throw new Error(`Local with id ${key.id} not found`);
+    }
+    return value;
+  },
+  set<T>(key: LocalsKey<T>, value: T): void {
+    localsAPI.setLocal(key, value);
+  },
+};
+
+export type Locals = typeof locals;
+export type { LocalsKey };

packages/core/src/v3/locals/index.ts

@@ -0,0 +1,45 @@
+const API_NAME = "locals";
+
+import { getGlobal, registerGlobal, unregisterGlobal } from "../utils/globals.js";
+import { NoopLocalsManager } from "./manager.js";
+import { LocalsKey, type LocalsManager } from "./types.js";
+
+const NOOP_LOCALS_MANAGER = new NoopLocalsManager();
+
+export class LocalsAPI implements LocalsManager {
+  private static _instance?: LocalsAPI;
+
+  private constructor() {}
+
+  public static getInstance(): LocalsAPI {
+    if (!this._instance) {
+      this._instance = new LocalsAPI();
+    }
+
+    return this._instance;
+  }
+
+  public setGlobalLocalsManager(localsManager: LocalsManager): boolean {
+    return registerGlobal(API_NAME, localsManager);
+  }
+
+  public disable() {
+    unregisterGlobal(API_NAME);
+  }
+
+  public createLocal<T>(id: string): LocalsKey<T> {
+    return this.#getManager().createLocal(id);
+  }
+
+  public getLocal<T>(key: LocalsKey<T>): T | undefined {
+    return this.#getManager().getLocal(key);
+  }
+
+  public setLocal<T>(key: LocalsKey<T>, value: T): void {
+    return this.#getManager().setLocal(key, value);
+  }
+
+  #getManager(): LocalsManager {
+    return getGlobal(API_NAME) ?? NOOP_LOCALS_MANAGER;
+  }
+}

packages/core/src/v3/locals/manager.ts

@@ -0,0 +1,37 @@
+import { LocalsKey, LocalsManager } from "./types.js";
+
+export class NoopLocalsManager implements LocalsManager {
+  createLocal<T>(id: string): LocalsKey<T> {
+    return {
+      __type: Symbol(),
+      id,
+    } as unknown as LocalsKey<T>;
+  }
+
+  getLocal<T>(key: LocalsKey<T>): T | undefined {
+    return undefined;
+  }
+
+  setLocal<T>(key: LocalsKey<T>, value: T): void {}
+}
+
+export class StandardLocalsManager implements LocalsManager {
+  private store: Map<symbol, unknown> = new Map();
+
+  createLocal<T>(id: string): LocalsKey<T> {
+    const key = Symbol.for(id);
+    return {
+      __type: key,
+      id,
+    } as unknown as LocalsKey<T>;
+  }
+
+  getLocal<T>(key: LocalsKey<T>): T | undefined {
+    return this.store.get(key.__type) as T | undefined;
+  }
+
+  setLocal<T>(key: LocalsKey<T>, value: T): void {
+    this.store.set(key.__type, value);
+  }
+}
+0;

packages/core/src/v3/locals/types.ts

@@ -0,0 +1,14 @@
+declare const __local: unique symbol;
+type BrandLocal<T> = { [__local]: T };
+
+// Create a type-safe store for your locals
+export type LocalsKey<T> = BrandLocal<T> & {
+  readonly id: string;
+  readonly __type: unique symbol;
+};
+
+export interface LocalsManager {
+  createLocal<T>(id: string): LocalsKey<T>;
+  getLocal<T>(key: LocalsKey<T>): T | undefined;
+  setLocal<T>(key: LocalsKey<T>, value: T): void;
+}

packages/core/src/v3/types/tasks.ts

@@ -264,11 +264,15 @@ type CommonTaskOptions<
 
   /**
    * init is called before the run function is called. It's useful for setting up any global state.
+   *
+   * @deprecated Use locals and middleware instead
    */
   init?: (payload: TPayload, params: InitFnParams) => Promise<TInitOutput>;
 
   /**
    * cleanup is called after the run function has completed.
+   *
+   * @deprecated Use middleware instead
    */
   cleanup?: (payload: TPayload, params: RunFnParams<TInitOutput>) => Promise<void>;
 

packages/core/src/v3/utils/globals.ts

@@ -1,6 +1,7 @@
 import { ApiClientConfiguration } from "../apiClientManager/types.js";
 import { Clock } from "../clock/clock.js";
 import { LifecycleHooksManager } from "../lifecycleHooks/types.js";
+import { LocalsManager } from "../locals/types.js";
 import { ResourceCatalog } from "../resource-catalog/catalog.js";
 import { RunMetadataManager } from "../runMetadata/types.js";
 import type { RuntimeManager } from "../runtime/manager.js";
@@ -64,4 +65,5 @@ type TriggerDotDevGlobalAPI = {
   ["wait-until"]?: WaitUntilManager;
   ["run-timeline-metrics"]?: RunTimelineMetricsManager;
   ["lifecycle-hooks"]?: LifecycleHooksManager;
+  ["locals"]?: LocalsManager;
 };

packages/core/src/v3/workers/index.ts

@@ -21,3 +21,4 @@ export * from "../runEngineWorker/index.js";
 export { StandardRunTimelineMetricsManager } from "../runTimelineMetrics/runTimelineMetricsManager.js";
 export { WarmStartClient, type WarmStartClientOptions } from "../workers/warmStartClient.js";
 export { StandardLifecycleHooksManager } from "../lifecycleHooks/manager.js";
+export { StandardLocalsManager } from "../locals/manager.js";