@trigger.dev/core 4.4.6 → 4.5.0-rc.0

package/dist/esm/v3/test/mock-task-context.d.ts

@@ -0,0 +1,123 @@
+import type { ServerBackgroundWorker, TaskRunContext } from "../schemas/index.js";
+import type { LocalsKey } from "../locals/types.js";
+import type { SessionChannelIO } from "../sessionStreams/types.js";
+/**
+ * Shallow-partial overrides applied on top of the default mock
+ * `TaskRunContext`. Each sub-object is a partial of its real shape —
+ * unset fields get sensible defaults.
+ */
+export type MockTaskRunContextOverrides = {
+    task?: Partial<TaskRunContext["task"]>;
+    attempt?: Partial<TaskRunContext["attempt"]>;
+    run?: Partial<TaskRunContext["run"]>;
+    machine?: Partial<TaskRunContext["machine"]>;
+    queue?: Partial<TaskRunContext["queue"]>;
+    environment?: Partial<TaskRunContext["environment"]>;
+    organization?: Partial<TaskRunContext["organization"]>;
+    project?: Partial<TaskRunContext["project"]>;
+    batch?: TaskRunContext["batch"];
+};
+/**
+ * Options for overriding parts of the mock task context.
+ */
+export type MockTaskContextOptions = {
+    /** Overrides applied on top of the default mock `TaskRunContext`. */
+    ctx?: MockTaskRunContextOverrides;
+    /** Overrides applied on top of the default `ServerBackgroundWorker`. */
+    worker?: Partial<ServerBackgroundWorker>;
+    /** Whether this is a warm start. */
+    isWarmStart?: boolean;
+};
+/**
+ * Drivers passed to the function running inside `runInMockTaskContext`.
+ */
+export type MockTaskContextDrivers = {
+    /** Push data into input streams — simulates realtime input from outside the task. */
+    inputs: {
+        /**
+         * Send `data` to the named input stream. Resolves when all `.on()`
+         * handlers have run.
+         */
+        send(streamId: string, data: unknown): Promise<void>;
+        /** Resolve any pending `.once()` waiters with a timeout error. */
+        close(streamId: string): void;
+    };
+    /** Inspect chunks written to output (realtime) streams. */
+    outputs: {
+        /** All chunks for a given stream, in the order they were written. */
+        chunks<T = unknown>(streamId: string): T[];
+        /** All chunks across every stream, keyed by stream id. */
+        all(): Record<string, unknown[]>;
+        /** Clear chunks for one stream, or all streams if no id is provided. */
+        clear(streamId?: string): void;
+        /**
+         * Register a listener fired for every chunk written to any stream.
+         * Returns an unsubscribe function.
+         */
+        onWrite(listener: (streamId: string, chunk: unknown) => void): () => void;
+    };
+    /** Read or seed locals for the run. */
+    locals: {
+        /** Read a local set by either the task or `set()` below. */
+        get<T>(key: LocalsKey<T>): T | undefined;
+        /**
+         * Pre-seed a local before the task runs. Use this for dependency
+         * injection — e.g. supply a test database client that the agent's
+         * hooks read via `locals.get()` instead of constructing the prod one.
+         */
+        set<T>(key: LocalsKey<T>, value: T): void;
+    };
+    /**
+     * Session-scoped channel drivers. The `.in` side is backed by a
+     * {@link TestSessionStreamManager} installed as the `sessionStreams`
+     * global — so the task's `session.in.on/once/peek/waitWithIdleTimeout`
+     * calls receive records sent through this driver.
+     */
+    sessions: {
+        in: {
+            /**
+             * Send a record onto `session.in` for the given session. Resolves
+             * pending `once()` waiters and fires all `on()` handlers.
+             */
+            send(sessionId: string, data: unknown, io?: SessionChannelIO): Promise<void>;
+            /** Close pending `once()` waiters with a timeout error. */
+            close(sessionId: string, io?: SessionChannelIO): void;
+        };
+    };
+    /** The mock `TaskRunContext` assembled from defaults + user overrides. */
+    ctx: TaskRunContext;
+};
+/**
+ * Run a function inside a fully mocked task runtime context.
+ *
+ * Installs in-memory test managers for `locals`, `inputStreams`,
+ * `realtimeStreams`, `lifecycleHooks`, and `runtime`, sets a mock
+ * `TaskContext`, and tears everything down when the function returns.
+ *
+ * Inside the function, any code that reads from `locals`, `inputStreams`,
+ * `realtimeStreams`, or `taskContext.ctx` will see the mock context —
+ * so you can directly invoke the internal `run` function of any task
+ * (including `chat.agent`) without hitting the Trigger.dev runtime.
+ *
+ * @example
+ * ```ts
+ * import { runInMockTaskContext } from "@trigger.dev/core/v3/test";
+ *
+ * await runInMockTaskContext(
+ *   async ({ inputs, outputs, ctx }) => {
+ *     // Fire an input stream from the "outside"
+ *     setTimeout(() => {
+ *       inputs.send("chat-messages", { messages: [], chatId: "c1" });
+ *     }, 0);
+ *
+ *     // Run task code that reads from inputStreams.once(...)
+ *     await myTask.fns.run(payload, { ctx, signal: new AbortController().signal });
+ *
+ *     // Inspect chunks written to the output stream
+ *     expect(outputs.chunks("chat")).toContainEqual({ type: "text-delta", delta: "hi" });
+ *   },
+ *   { ctx: { run: { id: "run_abc" } } }
+ * );
+ * ```
+ */
+export declare function runInMockTaskContext<T>(fn: (drivers: MockTaskContextDrivers) => T | Promise<T>, options?: MockTaskContextOptions): Promise<T>;

package/dist/esm/v3/test/mock-task-context.js

@@ -0,0 +1,190 @@
+import { inputStreams } from "../input-streams-api.js";
+import { realtimeStreams } from "../realtime-streams-api.js";
+import { sessionStreams } from "../session-streams-api.js";
+import { localsAPI } from "../locals-api.js";
+import { runMetadata } from "../run-metadata-api.js";
+import { taskContext } from "../task-context-api.js";
+import { lifecycleHooks } from "../lifecycle-hooks-api.js";
+import { runtime } from "../runtime-api.js";
+import { StandardLocalsManager } from "../locals/manager.js";
+import { StandardLifecycleHooksManager } from "../lifecycleHooks/manager.js";
+import { NoopRuntimeManager } from "../runtime/noopRuntimeManager.js";
+import { unregisterGlobal } from "../utils/globals.js";
+import { TestInputStreamManager } from "./test-input-stream-manager.js";
+import { TestRealtimeStreamsManager } from "./test-realtime-streams-manager.js";
+import { TestRunMetadataManager } from "./test-run-metadata-manager.js";
+import { TestSessionStreamManager } from "./test-session-stream-manager.js";
+function defaultTaskRunContext(overrides) {
+    return {
+        task: {
+            id: "test-task",
+            filePath: "test-task.ts",
+            ...overrides?.task,
+        },
+        attempt: {
+            number: 1,
+            startedAt: new Date(),
+            ...overrides?.attempt,
+        },
+        run: {
+            id: "run_test",
+            tags: [],
+            isTest: false,
+            isReplay: false,
+            createdAt: new Date(),
+            startedAt: new Date(),
+            ...overrides?.run,
+        },
+        machine: {
+            name: "micro",
+            cpu: 1,
+            memory: 0.5,
+            centsPerMs: 0,
+            ...overrides?.machine,
+        },
+        queue: {
+            name: "test-queue",
+            id: "test-queue-id",
+            ...overrides?.queue,
+        },
+        environment: {
+            id: "test-env-id",
+            slug: "test-env",
+            type: "DEVELOPMENT",
+            ...overrides?.environment,
+        },
+        organization: {
+            id: "test-org-id",
+            slug: "test-org",
+            name: "Test Org",
+            ...overrides?.organization,
+        },
+        project: {
+            id: "test-project-id",
+            ref: "test-project-ref",
+            slug: "test-project",
+            name: "Test Project",
+            ...overrides?.project,
+        },
+        batch: overrides?.batch,
+    };
+}
+function defaultWorker(overrides) {
+    return {
+        id: "test-worker-id",
+        version: "test-version",
+        contentHash: "test-content-hash",
+        engine: "V2",
+        ...overrides,
+    };
+}
+/**
+ * Run a function inside a fully mocked task runtime context.
+ *
+ * Installs in-memory test managers for `locals`, `inputStreams`,
+ * `realtimeStreams`, `lifecycleHooks`, and `runtime`, sets a mock
+ * `TaskContext`, and tears everything down when the function returns.
+ *
+ * Inside the function, any code that reads from `locals`, `inputStreams`,
+ * `realtimeStreams`, or `taskContext.ctx` will see the mock context —
+ * so you can directly invoke the internal `run` function of any task
+ * (including `chat.agent`) without hitting the Trigger.dev runtime.
+ *
+ * @example
+ * ```ts
+ * import { runInMockTaskContext } from "@trigger.dev/core/v3/test";
+ *
+ * await runInMockTaskContext(
+ *   async ({ inputs, outputs, ctx }) => {
+ *     // Fire an input stream from the "outside"
+ *     setTimeout(() => {
+ *       inputs.send("chat-messages", { messages: [], chatId: "c1" });
+ *     }, 0);
+ *
+ *     // Run task code that reads from inputStreams.once(...)
+ *     await myTask.fns.run(payload, { ctx, signal: new AbortController().signal });
+ *
+ *     // Inspect chunks written to the output stream
+ *     expect(outputs.chunks("chat")).toContainEqual({ type: "text-delta", delta: "hi" });
+ *   },
+ *   { ctx: { run: { id: "run_abc" } } }
+ * );
+ * ```
+ */
+export async function runInMockTaskContext(fn, options) {
+    const ctx = defaultTaskRunContext(options?.ctx);
+    const worker = defaultWorker(options?.worker);
+    const localsManager = new StandardLocalsManager();
+    const lifecycleManager = new StandardLifecycleHooksManager();
+    const runtimeManager = new NoopRuntimeManager();
+    const metadataManager = new TestRunMetadataManager();
+    const inputManager = new TestInputStreamManager();
+    const outputManager = new TestRealtimeStreamsManager();
+    const sessionStreamManager = new TestSessionStreamManager();
+    // Unregister any previously-installed managers so `setGlobal*` wins —
+    // `registerGlobal` returns false silently if an entry already exists.
+    unregisterGlobal("locals");
+    unregisterGlobal("lifecycle-hooks");
+    unregisterGlobal("runtime");
+    unregisterGlobal("run-metadata");
+    unregisterGlobal("input-streams");
+    unregisterGlobal("realtime-streams");
+    unregisterGlobal("session-streams");
+    unregisterGlobal("task-context");
+    localsAPI.setGlobalLocalsManager(localsManager);
+    lifecycleHooks.setGlobalLifecycleHooksManager(lifecycleManager);
+    runtime.setGlobalRuntimeManager(runtimeManager);
+    runMetadata.setGlobalManager(metadataManager);
+    inputStreams.setGlobalManager(inputManager);
+    realtimeStreams.setGlobalManager(outputManager);
+    sessionStreams.setGlobalManager(sessionStreamManager);
+    taskContext.setGlobalTaskContext({
+        ctx,
+        worker,
+        isWarmStart: options?.isWarmStart ?? false,
+    });
+    const drivers = {
+        inputs: {
+            send: (streamId, data) => inputManager.__sendFromTest(streamId, data),
+            close: (streamId) => inputManager.__closeFromTest(streamId),
+        },
+        outputs: {
+            chunks: (streamId) => outputManager.__chunksFromTest(streamId),
+            all: () => outputManager.__allChunksFromTest(),
+            clear: (streamId) => outputManager.__clearFromTest(streamId),
+            onWrite: (listener) => outputManager.onWrite(listener),
+        },
+        locals: {
+            get: (key) => localsManager.getLocal(key),
+            set: (key, value) => localsManager.setLocal(key, value),
+        },
+        sessions: {
+            in: {
+                send: (sessionId, data, io = "in") => sessionStreamManager.__sendFromTest(sessionId, io, data),
+                close: (sessionId, io = "in") => sessionStreamManager.__closeFromTest(sessionId, io),
+            },
+        },
+        ctx,
+    };
+    try {
+        return await fn(drivers);
+    }
+    finally {
+        localsAPI.disable();
+        lifecycleHooks.disable();
+        runtime.disable();
+        // taskContext.disable() only sets a flag — unregister the global so
+        // `taskContext.ctx` returns undefined after the harness returns.
+        unregisterGlobal("task-context");
+        unregisterGlobal("input-streams");
+        unregisterGlobal("realtime-streams");
+        unregisterGlobal("session-streams");
+        unregisterGlobal("run-metadata");
+        localsManager.reset();
+        inputManager.reset();
+        outputManager.reset();
+        sessionStreamManager.reset();
+        metadataManager.reset();
+    }
+}
+//# sourceMappingURL=mock-task-context.js.map

package/dist/esm/v3/test/mock-task-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mock-task-context.js","sourceRoot":"","sources":["../../../../src/v3/test/mock-task-context.ts"],"names":[],"mappings":"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"}

package/dist/esm/v3/test/test-input-stream-manager.d.ts

@@ -0,0 +1,46 @@
+import type { InputStreamManager } from "../inputStreams/types.js";
+import { InputStreamOncePromise } from "../inputStreams/types.js";
+import type { InputStreamOnceOptions } from "../realtimeStreams/types.js";
+type Handler = (data: unknown) => void | Promise<void>;
+/**
+ * In-memory implementation of `InputStreamManager` for unit tests.
+ *
+ * Tests push data via the driver's `.send(streamId, data)` method. Any
+ * pending `.once()` waiters resolve immediately, and all `.on()` handlers
+ * fire synchronously (awaited if they return a promise).
+ *
+ * Use this alongside {@link runInMockTaskContext} — not directly.
+ */
+export declare class TestInputStreamManager implements InputStreamManager {
+    private handlers;
+    private onceWaiters;
+    private latest;
+    private lastSeqNums;
+    private pendingSends;
+    setRunId(_runId: string, _streamsVersion?: string): void;
+    on(streamId: string, handler: Handler): {
+        off: () => void;
+    };
+    once(streamId: string, options?: InputStreamOnceOptions): InputStreamOncePromise<unknown>;
+    peek(streamId: string): unknown | undefined;
+    lastSeqNum(streamId: string): number | undefined;
+    setLastSeqNum(streamId: string, seqNum: number): void;
+    shiftBuffer(_streamId: string): boolean;
+    disconnectStream(_streamId: string): void;
+    clearHandlers(): void;
+    reset(): void;
+    disconnect(): void;
+    connectTail(_runId: string, _fromSeq?: number): void;
+    /**
+     * Push data onto an input stream. Resolves pending `once()` waiters
+     * and fires all `on()` handlers (awaiting async handlers).
+     */
+    __sendFromTest(streamId: string, data: unknown): Promise<void>;
+    /**
+     * Immediately resolve every pending `once()` waiter for a stream with a
+     * timeout error. Used to simulate closed streams (e.g. `exitAfterPreloadIdle`).
+     */
+    __closeFromTest(streamId: string): void;
+    private removeWaiter;
+}
+export {};

package/dist/esm/v3/test/test-input-stream-manager.js

@@ -0,0 +1,188 @@
+import { InputStreamOncePromise, InputStreamTimeoutError } from "../inputStreams/types.js";
+/**
+ * In-memory implementation of `InputStreamManager` for unit tests.
+ *
+ * Tests push data via the driver's `.send(streamId, data)` method. Any
+ * pending `.once()` waiters resolve immediately, and all `.on()` handlers
+ * fire synchronously (awaited if they return a promise).
+ *
+ * Use this alongside {@link runInMockTaskContext} — not directly.
+ */
+export class TestInputStreamManager {
+    handlers = new Map();
+    onceWaiters = new Map();
+    latest = new Map();
+    lastSeqNums = new Map();
+    // Buffered sends that arrived before a `.once()` waiter was registered.
+    // `.once()` semantically means "wait for NEXT value" but tests often
+    // send data before the task has had a chance to reach the wait point.
+    // Buffering closes that race so the waiter picks up the pending send.
+    pendingSends = new Map();
+    setRunId(_runId, _streamsVersion) {
+        // No-op — the test driver tracks nothing about runs
+    }
+    on(streamId, handler) {
+        if (!this.handlers.has(streamId)) {
+            this.handlers.set(streamId, new Set());
+        }
+        this.handlers.get(streamId).add(handler);
+        return {
+            off: () => {
+                this.handlers.get(streamId)?.delete(handler);
+            },
+        };
+    }
+    once(streamId, options) {
+        return new InputStreamOncePromise((resolve) => {
+            if (options?.signal?.aborted) {
+                resolve({
+                    ok: false,
+                    error: new InputStreamTimeoutError(streamId, options.timeoutMs ?? 0),
+                });
+                return;
+            }
+            // Pick up any buffered send that arrived before this waiter.
+            const buffered = this.pendingSends.get(streamId);
+            if (buffered && buffered.length > 0) {
+                const next = buffered.shift();
+                if (buffered.length === 0)
+                    this.pendingSends.delete(streamId);
+                resolve({ ok: true, output: next });
+                return;
+            }
+            const waiter = {
+                resolve,
+                signal: options?.signal,
+            };
+            if (options?.timeoutMs !== undefined) {
+                waiter.timer = setTimeout(() => {
+                    this.removeWaiter(streamId, waiter);
+                    resolve({
+                        ok: false,
+                        error: new InputStreamTimeoutError(streamId, options.timeoutMs),
+                    });
+                }, options.timeoutMs);
+            }
+            if (options?.signal) {
+                const abortHandler = () => {
+                    this.removeWaiter(streamId, waiter);
+                    if (waiter.timer)
+                        clearTimeout(waiter.timer);
+                    resolve({
+                        ok: false,
+                        error: new InputStreamTimeoutError(streamId, options.timeoutMs ?? 0),
+                    });
+                };
+                waiter.abortHandler = abortHandler;
+                options.signal.addEventListener("abort", abortHandler, { once: true });
+            }
+            if (!this.onceWaiters.has(streamId)) {
+                this.onceWaiters.set(streamId, []);
+            }
+            this.onceWaiters.get(streamId).push(waiter);
+        });
+    }
+    peek(streamId) {
+        return this.latest.get(streamId);
+    }
+    lastSeqNum(streamId) {
+        return this.lastSeqNums.get(streamId);
+    }
+    setLastSeqNum(streamId, seqNum) {
+        this.lastSeqNums.set(streamId, seqNum);
+    }
+    shiftBuffer(_streamId) {
+        return false;
+    }
+    disconnectStream(_streamId) { }
+    clearHandlers() {
+        this.handlers.clear();
+    }
+    reset() {
+        // Cancel any pending waiters to avoid dangling promises leaking between tests
+        for (const waiters of this.onceWaiters.values()) {
+            for (const w of waiters) {
+                if (w.timer)
+                    clearTimeout(w.timer);
+                if (w.signal && w.abortHandler) {
+                    w.signal.removeEventListener("abort", w.abortHandler);
+                }
+            }
+        }
+        this.onceWaiters.clear();
+        this.handlers.clear();
+        this.latest.clear();
+        this.lastSeqNums.clear();
+        this.pendingSends.clear();
+    }
+    disconnect() {
+        this.reset();
+    }
+    connectTail(_runId, _fromSeq) { }
+    // ── Test driver API (not part of InputStreamManager interface) ──────────
+    /**
+     * Push data onto an input stream. Resolves pending `once()` waiters
+     * and fires all `on()` handlers (awaiting async handlers).
+     */
+    async __sendFromTest(streamId, data) {
+        this.latest.set(streamId, data);
+        const waiters = this.onceWaiters.get(streamId);
+        const handlers = this.handlers.get(streamId);
+        const hasWaiters = waiters && waiters.length > 0;
+        const hasHandlers = handlers && handlers.size > 0;
+        // If nothing is listening yet, buffer so the next `.once()` call picks it up.
+        if (!hasWaiters && !hasHandlers) {
+            if (!this.pendingSends.has(streamId)) {
+                this.pendingSends.set(streamId, []);
+            }
+            this.pendingSends.get(streamId).push(data);
+            return;
+        }
+        if (hasWaiters) {
+            // Drain every pending once() waiter — this mirrors the real manager's
+            // behavior where the stream tail delivers the same record to all listeners.
+            const pending = waiters.splice(0);
+            for (const w of pending) {
+                if (w.timer)
+                    clearTimeout(w.timer);
+                if (w.signal && w.abortHandler) {
+                    w.signal.removeEventListener("abort", w.abortHandler);
+                }
+                w.resolve({ ok: true, output: data });
+            }
+        }
+        if (hasHandlers) {
+            await Promise.all(Array.from(handlers).map((h) => Promise.resolve().then(() => h(data))));
+        }
+    }
+    /**
+     * Immediately resolve every pending `once()` waiter for a stream with a
+     * timeout error. Used to simulate closed streams (e.g. `exitAfterPreloadIdle`).
+     */
+    __closeFromTest(streamId) {
+        const waiters = this.onceWaiters.get(streamId);
+        if (!waiters)
+            return;
+        const pending = waiters.splice(0);
+        for (const w of pending) {
+            if (w.timer)
+                clearTimeout(w.timer);
+            if (w.signal && w.abortHandler) {
+                w.signal.removeEventListener("abort", w.abortHandler);
+            }
+            w.resolve({
+                ok: false,
+                error: new InputStreamTimeoutError(streamId, 0),
+            });
+        }
+    }
+    removeWaiter(streamId, waiter) {
+        const waiters = this.onceWaiters.get(streamId);
+        if (!waiters)
+            return;
+        const idx = waiters.indexOf(waiter);
+        if (idx >= 0)
+            waiters.splice(idx, 1);
+    }
+}
+//# sourceMappingURL=test-input-stream-manager.js.map

package/dist/esm/v3/test/test-input-stream-manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-input-stream-manager.js","sourceRoot":"","sources":["../../../../src/v3/test/test-input-stream-manager.ts"],"names":[],"mappings":"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"}

package/dist/esm/v3/test/test-realtime-streams-manager.d.ts

@@ -0,0 +1,40 @@
+import type { RealtimeStreamInstance, RealtimeStreamOperationOptions, RealtimeStreamsManager } from "../realtimeStreams/types.js";
+/**
+ * In-memory implementation of `RealtimeStreamsManager` for unit tests.
+ * Collects every chunk that tasks write via `pipe()` or `append()` into
+ * per-stream buffers that tests can inspect.
+ *
+ * Use this alongside {@link runInMockTaskContext} — not directly.
+ */
+type WriteListener = (key: string, chunk: unknown) => void;
+export declare class TestRealtimeStreamsManager implements RealtimeStreamsManager {
+    private buffers;
+    private pipeWaits;
+    private writeListeners;
+    pipe<T>(key: string, source: AsyncIterable<T> | ReadableStream<T>, _options?: RealtimeStreamOperationOptions): RealtimeStreamInstance<T>;
+    append<TPart extends BodyInit>(key: string, part: TPart, _options?: RealtimeStreamOperationOptions): Promise<void>;
+    /**
+     * Register a listener fired for every chunk written to any stream.
+     * Returns an unsubscribe function.
+     *
+     * Intended for test harnesses that need to react to writes synchronously
+     * (e.g. resolving a "turn complete" latch).
+     */
+    onWrite(listener: WriteListener): () => void;
+    private notify;
+    /**
+     * Return all chunks written to the given stream key in order of write.
+     */
+    __chunksFromTest<T = unknown>(key: string): T[];
+    /**
+     * Return all chunks across every stream, keyed by stream id.
+     */
+    __allChunksFromTest(): Record<string, unknown[]>;
+    /**
+     * Clear the buffer for a specific stream or all streams.
+     */
+    __clearFromTest(key?: string): void;
+    reset(): void;
+    private getBuffer;
+}
+export {};