@instruments/materialgraph 1.4.0 → 2.1.0

package/sse.js

@@ -1,167 +0,0 @@
-/**
- * A minimal, dependency-free Server-Sent Events reader — the primitive behind
- * {@link WorkflowsClient.streamRunEvents}. Hand-rolled (no `eventsource`,
- * no `undici`) so the SDK stays zero-runtime-dep and works unchanged inside
- * Node route handlers, where `fetch` yields a byte `ReadableStream`.
- *
- * The parser follows the WHATWG event-stream tokenizer closely enough for the
- * `/api/v1/workflows/{workflowId}/runs/{runId}/events` contract: `\n`, `\r\n`, and `\r` line endings,
- * multi-line `data:` accumulation, comment (`:`-prefixed) lines, and a single
- * optional leading space after the field colon. Frames split across network
- * chunks are held in an internal buffer until their terminating blank line.
- */
-/**
- * A push-based SSE line assembler. Feed it decoded text with {@link push}; it
- * returns any frames completed by that text. Call {@link flush} once the stream
- * ends to dispatch a final frame that had data but no terminating blank line.
- */
-export class SseDecoder {
-    #buffer = "";
-    #dataLines = [];
-    #id;
-    #event;
-    #hasFields = false;
-    push(text) {
-        this.#buffer += text;
-        const frames = [];
-        for (;;) {
-            const lineEnd = this.#nextLineEnd();
-            if (lineEnd === null) {
-                break;
-            }
-            const line = this.#buffer.slice(0, lineEnd.index);
-            this.#buffer = this.#buffer.slice(lineEnd.nextIndex);
-            const frame = this.#consumeLine(line);
-            if (frame) {
-                frames.push(frame);
-            }
-        }
-        return frames;
-    }
-    /** Dispatch a trailing frame that had fields but no closing blank line. */
-    flush() {
-        if (this.#buffer.length > 0) {
-            // At end of stream a deferred trailing CR is a real terminator, not data.
-            const line = this.#buffer.endsWith("\r")
-                ? this.#buffer.slice(0, -1)
-                : this.#buffer;
-            this.#buffer = "";
-            const frame = this.#consumeLine(line);
-            if (frame) {
-                return [frame];
-            }
-        }
-        const frame = this.#dispatch();
-        return frame ? [frame] : [];
-    }
-    /** Locate the next line terminator, deferring a lone trailing `\r` (may be `\r\n`). */
-    #nextLineEnd() {
-        for (let i = 0; i < this.#buffer.length; i += 1) {
-            const char = this.#buffer[i];
-            if (char === "\n") {
-                return { index: i, nextIndex: i + 1 };
-            }
-            if (char === "\r") {
-                if (i === this.#buffer.length - 1) {
-                    return null;
-                }
-                return this.#buffer[i + 1] === "\n"
-                    ? { index: i, nextIndex: i + 2 }
-                    : { index: i, nextIndex: i + 1 };
-            }
-        }
-        return null;
-    }
-    #consumeLine(line) {
-        if (line.length === 0) {
-            return this.#dispatch();
-        }
-        if (line.startsWith(":")) {
-            return undefined;
-        }
-        const colon = line.indexOf(":");
-        const field = colon === -1 ? line : line.slice(0, colon);
-        let value = colon === -1 ? "" : line.slice(colon + 1);
-        if (value.startsWith(" ")) {
-            value = value.slice(1);
-        }
-        if (field === "data") {
-            this.#dataLines.push(value);
-            this.#hasFields = true;
-        }
-        else if (field === "event") {
-            this.#event = value;
-            this.#hasFields = true;
-        }
-        else if (field === "id") {
-            this.#id = value;
-            this.#hasFields = true;
-        }
-        return undefined;
-    }
-    #dispatch() {
-        if (!this.#hasFields) {
-            return undefined;
-        }
-        const frame = { data: this.#dataLines.join("\n") };
-        if (this.#event !== undefined) {
-            frame.event = this.#event;
-        }
-        if (this.#id !== undefined) {
-            frame.id = this.#id;
-        }
-        this.#dataLines = [];
-        this.#event = undefined;
-        this.#id = undefined;
-        this.#hasFields = false;
-        return frame;
-    }
-}
-/**
- * Iterate the SSE frames of a byte stream. Stops cleanly when the stream ends
- * or `signal` aborts (mid-read abort rejections are swallowed once the signal
- * is set). Frames with no `data` field (comments, bare `id:`) are not yielded.
- * @yields {SseFrame} Each completed frame containing fields.
- */
-export const readSseFrames = async function* readSseFrames(body, signal) {
-    const isAborted = () => signal?.aborted === true;
-    const reader = body.getReader();
-    const decoder = new TextDecoder();
-    const sse = new SseDecoder();
-    try {
-        for (;;) {
-            if (isAborted()) {
-                return;
-            }
-            let result;
-            try {
-                result = await reader.read();
-            }
-            catch (error) {
-                if (isAborted()) {
-                    return;
-                }
-                throw error;
-            }
-            if (result.done) {
-                for (const frame of sse.push(decoder.decode())) {
-                    yield frame;
-                }
-                for (const frame of sse.flush()) {
-                    yield frame;
-                }
-                return;
-            }
-            const text = decoder.decode(result.value, { stream: true });
-            for (const frame of sse.push(text)) {
-                if (isAborted()) {
-                    return;
-                }
-                yield frame;
-            }
-        }
-    }
-    finally {
-        reader.releaseLock();
-    }
-};

package/workflows-client.d.ts

@@ -1,54 +0,0 @@
-import type { HttpTransport } from "./http-transport.js";
-/**
- * The workflow Run surface, namespaced as `mg.workflows`. A Run is the start of
- * one registered Mastra workflow and nothing else: you name the workflow, hand
- * it its input, and follow the Run it returns. Replaces the flat `createRun()`,
- * `run()`, `streamRunEvents()` and `drainRunEvents()` methods, retired with no
- * shim when `/api/v1/runs` moved under `/api/v1/workflows/{workflowId}/runs`.
- *
- * THE QUESTION: "do a whole job for me" — the ASYNC lens. Everything else on
- * the client answers in one round trip; a Run may suspend for human input and
- * finish minutes later. `start()` acknowledges without executing, `run()` polls
- * the ledger, and `streamRunEvents()` follows it live.
- *
- * `workflowId` is the registered workflow's id, such as `edit-collection`. A
- * Run is read under the workflow that started it: asking for it under another
- * workflow's id is a 404.
- *
- * Starting a Run needs the `mg:compose` or `mg:write` scope, plus whatever
- * scope the workflow itself declares.
- */
-import type { RunId } from "./identifiers.js";
-import type { CreatePublicRunRequest, CreatePublicRunResponse, DrainRunEventsOptions, PublicRunResponse, RunEvent, StreamRunEventsOptions } from "./run-types.js";
-export declare class WorkflowsClient {
-    #private;
-    constructor(options: {
-        transport: HttpTransport;
-    });
-    /**
-     * Start an asynchronous Run of `workflowId` (POST
-     * `/api/v1/workflows/{workflowId}/runs`). Pass `idempotencyKey` so a retry
-     * replays rather than duplicates. Follow with {@link streamRunEvents} (live)
-     * or {@link run} (poll).
-     */
-    start(workflowId: string, body: CreatePublicRunRequest, signal?: AbortSignal): Promise<CreatePublicRunResponse>;
-    /**
-     * THE QUESTION: "where has this Run got to?" — the caller-owned, redacted
-     * ledger record. Polling; prefer {@link streamRunEvents} when a human is
-     * waiting.
-     */
-    run(workflowId: string, runId: RunId, signal?: AbortSignal): Promise<PublicRunResponse>;
-    /**
-     * Stream ordered Run events as an async iterator (GET
-     * `/api/v1/workflows/{workflowId}/runs/{runId}/events`, SSE). Iterates until
-     * the stream ends or the signal aborts; pass `after` to resume from the last
-     * observed sequence.
-     */
-    streamRunEvents(workflowId: string, runId: RunId, options?: StreamRunEventsOptions): AsyncGenerator<RunEvent>;
-    /**
-     * Collect Run events until a terminal event, the deadline, or the stream
-     * ends — the bounded events-log pattern (a single pass over
-     * {@link streamRunEvents}).
-     */
-    drainRunEvents(workflowId: string, runId: RunId, options: DrainRunEventsOptions): Promise<RunEvent[]>;
-}

package/workflows-client.js

@@ -1,41 +0,0 @@
-import { drainRunEvents, getWorkflowRun, startWorkflowRun, streamRunEvents, } from "./runs.js";
-export class WorkflowsClient {
-    #transport;
-    constructor(options) {
-        this.#transport = options.transport;
-    }
-    /**
-     * Start an asynchronous Run of `workflowId` (POST
-     * `/api/v1/workflows/{workflowId}/runs`). Pass `idempotencyKey` so a retry
-     * replays rather than duplicates. Follow with {@link streamRunEvents} (live)
-     * or {@link run} (poll).
-     */
-    async start(workflowId, body, signal) {
-        return await startWorkflowRun(this.#transport, workflowId, body, signal);
-    }
-    /**
-     * THE QUESTION: "where has this Run got to?" — the caller-owned, redacted
-     * ledger record. Polling; prefer {@link streamRunEvents} when a human is
-     * waiting.
-     */
-    async run(workflowId, runId, signal) {
-        return await getWorkflowRun(this.#transport, workflowId, runId, signal);
-    }
-    /**
-     * Stream ordered Run events as an async iterator (GET
-     * `/api/v1/workflows/{workflowId}/runs/{runId}/events`, SSE). Iterates until
-     * the stream ends or the signal aborts; pass `after` to resume from the last
-     * observed sequence.
-     */
-    streamRunEvents(workflowId, runId, options) {
-        return streamRunEvents(this.#transport, workflowId, runId, options);
-    }
-    /**
-     * Collect Run events until a terminal event, the deadline, or the stream
-     * ends — the bounded events-log pattern (a single pass over
-     * {@link streamRunEvents}).
-     */
-    async drainRunEvents(workflowId, runId, options) {
-        return await drainRunEvents(this.#transport, workflowId, runId, options);
-    }
-}