@ironflow/node 0.20.2 → 0.21.0

package/dist/internal/errors.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Internal error classes for step execution (Node.js specific)
+ */
+/**
+ * Yield information union type
+ */
+export type YieldInfo = SleepYieldInfo | WaitEventYieldInfo | InvokeFunctionYieldInfo | InvokeFunctionAsyncYieldInfo;
+/**
+ * Sleep yield information
+ */
+export interface SleepYieldInfo {
+    step_id: string;
+    type: "sleep";
+    until: string;
+}
+/**
+ * Wait for event yield information
+ */
+export interface WaitEventYieldInfo {
+    step_id: string;
+    type: "wait_for_event";
+    event_filter: {
+        event: string;
+        match?: string;
+        timeout?: string;
+    };
+}
+/**
+ * Invoke function yield information
+ */
+export interface InvokeFunctionYieldInfo {
+    step_id: string;
+    type: "invoke_function";
+    function_id: string;
+    input?: unknown;
+    invoke_timeout_ms?: number;
+}
+/**
+ * Invoke function async yield information
+ */
+export interface InvokeFunctionAsyncYieldInfo {
+    step_id: string;
+    type: "invoke_function_async";
+    function_id: string;
+    input?: unknown;
+}
+/**
+ * Internal signal to yield execution (not a real error).
+ * Used internally to implement sleep and waitForEvent.
+ *
+ * @internal
+ */
+export declare class YieldSignal extends Error {
+    /** Information about the yield operation */
+    readonly yieldInfo: YieldInfo;
+    constructor(yieldInfo: YieldInfo);
+}
+/**
+ * Check if an error is a YieldSignal
+ *
+ * @param error - The error to check
+ * @returns true if the error is a YieldSignal
+ * @internal
+ */
+export declare function isYieldSignal(error: unknown): error is YieldSignal;
+//# sourceMappingURL=errors.d.ts.map

package/dist/internal/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/internal/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG,cAAc,GAAG,kBAAkB,GAAG,uBAAuB,GAAG,4BAA4B,CAAC;AAErH;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,OAAO,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,gBAAgB,CAAC;IACvB,YAAY,EAAE;QACZ,KAAK,EAAE,MAAM,CAAC;QACd,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,iBAAiB,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,4BAA4B;IAC3C,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,uBAAuB,CAAC;IAC9B,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;;;GAKG;AACH,qBAAa,WAAY,SAAQ,KAAK;IACpC,4CAA4C;IAC5C,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;gBAElB,SAAS,EAAE,SAAS;CAKjC;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,WAAW,CAElE"}

package/dist/internal/errors.js

@@ -0,0 +1,29 @@
+/**
+ * Internal error classes for step execution (Node.js specific)
+ */
+/**
+ * Internal signal to yield execution (not a real error).
+ * Used internally to implement sleep and waitForEvent.
+ *
+ * @internal
+ */
+export class YieldSignal extends Error {
+    /** Information about the yield operation */
+    yieldInfo;
+    constructor(yieldInfo) {
+        super("Yield signal");
+        this.name = "YieldSignal";
+        this.yieldInfo = yieldInfo;
+    }
+}
+/**
+ * Check if an error is a YieldSignal
+ *
+ * @param error - The error to check
+ * @returns true if the error is a YieldSignal
+ * @internal
+ */
+export function isYieldSignal(error) {
+    return error instanceof YieldSignal;
+}
+//# sourceMappingURL=errors.js.map

package/dist/internal/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/internal/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AAkDH;;;;;GAKG;AACH,MAAM,OAAO,WAAY,SAAQ,KAAK;IACpC,4CAA4C;IACnC,SAAS,CAAY;IAE9B,YAAY,SAAoB;QAC9B,KAAK,CAAC,cAAc,CAAC,CAAC;QACtB,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;QAC1B,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAC7B,CAAC;CACF;AAED;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,OAAO,KAAK,YAAY,WAAW,CAAC;AACtC,CAAC"}

package/dist/internal/run-context.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Execute a callback within a run context.
+ * Any createClient() calls inside will automatically include the run ID.
+ */
+export declare function withRunContext<T>(runId: string, fn: () => T): T;
+/**
+ * Get the current run ID from context, or undefined if not in a run.
+ */
+export declare function getCurrentRunId(): string | undefined;
+//# sourceMappingURL=run-context.d.ts.map

package/dist/internal/run-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-context.d.ts","sourceRoot":"","sources":["../../src/internal/run-context.ts"],"names":[],"mappings":"AAeA;;;GAGG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAE/D;AAED;;GAEG;AACH,wBAAgB,eAAe,IAAI,MAAM,GAAG,SAAS,CAEpD"}

package/dist/internal/run-context.js

@@ -0,0 +1,23 @@
+/**
+ * Run context propagation via AsyncLocalStorage.
+ *
+ * When a function handler executes, the SDK sets the current run ID.
+ * createClient() picks it up automatically and includes X-Ironflow-Run-ID
+ * header on all requests — linking entity events to the run that created them.
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+const runContextStorage = new AsyncLocalStorage();
+/**
+ * Execute a callback within a run context.
+ * Any createClient() calls inside will automatically include the run ID.
+ */
+export function withRunContext(runId, fn) {
+    return runContextStorage.run({ runId }, fn);
+}
+/**
+ * Get the current run ID from context, or undefined if not in a run.
+ */
+export function getCurrentRunId() {
+    return runContextStorage.getStore()?.runId;
+}
+//# sourceMappingURL=run-context.js.map

package/dist/internal/run-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-context.js","sourceRoot":"","sources":["../../src/internal/run-context.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAMrD,MAAM,iBAAiB,GAAG,IAAI,iBAAiB,EAAc,CAAC;AAE9D;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAI,KAAa,EAAE,EAAW;IAC1D,OAAO,iBAAiB,CAAC,GAAG,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,CAAC;AAC9C,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,eAAe;IAC7B,OAAO,iBAAiB,CAAC,QAAQ,EAAE,EAAE,KAAK,CAAC;AAC7C,CAAC"}

package/dist/kv.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Ironflow Node.js KV Client
+ *
+ * Key-Value store operations for the Ironflow server.
+ */
+import type { KVBucketConfig, KVBucketInfo, KVEntry, KVPutResult } from "@ironflow/core";
+import type { OnErrorHandler } from "./types.js";
+/**
+ * Configuration for the KV client (inherited from parent client).
+ */
+export interface KVClientConfig {
+    serverUrl: string;
+    apiKey?: string;
+    timeout: number;
+    onError?: OnErrorHandler;
+}
+/**
+ * KV bucket handle for key-level operations.
+ */
+export declare class KVBucketHandle {
+    private readonly bucketName;
+    private readonly config;
+    constructor(bucketName: string, config: KVClientConfig);
+    /**
+     * Get a value by key.
+     */
+    get(key: string): Promise<KVEntry>;
+    /**
+     * Put a value unconditionally.
+     */
+    put(key: string, value: unknown): Promise<KVPutResult>;
+    /**
+     * Create a value only if the key doesn't exist (if-not-exists).
+     * Throws on conflict (HTTP 412).
+     */
+    create(key: string, value: unknown): Promise<KVPutResult>;
+    /**
+     * Update a value only if the revision matches (compare-and-swap).
+     * Throws on mismatch (HTTP 412).
+     */
+    update(key: string, value: unknown, revision: number): Promise<KVPutResult>;
+    /**
+     * Delete a key (soft delete / tombstone).
+     */
+    delete(key: string): Promise<void>;
+    /**
+     * Purge a key and all its history.
+     */
+    purge(key: string): Promise<void>;
+    /**
+     * List keys with an optional wildcard filter.
+     */
+    listKeys(filter?: string): Promise<string[]>;
+    private callOnError;
+    private restRequest;
+}
+/**
+ * KV client for bucket management and key operations.
+ */
+export declare class KVClient {
+    private readonly config;
+    constructor(config: KVClientConfig);
+    /**
+     * Create a new bucket.
+     */
+    createBucket(config: KVBucketConfig): Promise<KVBucketInfo>;
+    /**
+     * Delete a bucket.
+     */
+    deleteBucket(name: string): Promise<void>;
+    /**
+     * List all buckets.
+     */
+    listBuckets(): Promise<KVBucketInfo[]>;
+    /**
+     * Get bucket info.
+     */
+    getBucketInfo(name: string): Promise<KVBucketInfo>;
+    /**
+     * Get a bucket handle for key-level operations.
+     */
+    bucket(name: string): KVBucketHandle;
+    private callOnError;
+    private restRequest;
+}
+//# sourceMappingURL=kv.d.ts.map

package/dist/kv.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kv.d.ts","sourceRoot":"","sources":["../src/kv.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EACV,cAAc,EACd,YAAY,EACZ,OAAO,EACP,WAAW,EAGZ,MAAM,gBAAgB,CAAC;AAOxB,OAAO,KAAK,EAAE,cAAc,EAAgB,MAAM,YAAY,CAAC;AAE/D;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,cAAc,CAAC;CAC1B;AAED;;GAEG;AACH,qBAAa,cAAc;IAEvB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,MAAM;gBADN,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,cAAc;IAGzC;;OAEG;IACG,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAUxC;;OAEG;IACG,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,WAAW,CAAC;IAU5D;;;OAGG;IACG,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,WAAW,CAAC;IAU/D;;;OAGG;IACG,MAAM,CACV,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,WAAW,CAAC;IAUvB;;OAEG;IACG,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAUxC;;OAEG;IACG,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAUvC;;OAEG;IACG,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;YASpC,WAAW;YASX,WAAW;CAsE1B;AAED;;GAEG;AACH,qBAAa,QAAQ;IACP,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,cAAc;IAEnD;;OAEG;IACG,YAAY,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,YAAY,CAAC;IAgBjE;;OAEG;IACG,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAS/C;;OAEG;IACG,WAAW,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC;IAU5C;;OAEG;IACG,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IASxD;;OAEG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc;YAItB,WAAW;YASX,WAAW;CAyD1B"}

package/dist/kv.js

@@ -0,0 +1,261 @@
+/**
+ * Ironflow Node.js KV Client
+ *
+ * Key-Value store operations for the Ironflow server.
+ */
+import { IronflowError, UnauthenticatedError, EnterpriseRequiredError, UnauthorizedError, } from "@ironflow/core";
+/**
+ * KV bucket handle for key-level operations.
+ */
+export class KVBucketHandle {
+    bucketName;
+    config;
+    constructor(bucketName, config) {
+        this.bucketName = bucketName;
+        this.config = config;
+    }
+    /**
+     * Get a value by key.
+     */
+    async get(key) {
+        return this.restRequest("GET", `/api/v1/kv/buckets/${enc(this.bucketName)}/keys/${key}`, undefined, undefined, "kv.bucket.get");
+    }
+    /**
+     * Put a value unconditionally.
+     */
+    async put(key, value) {
+        return this.restRequest("PUT", `/api/v1/kv/buckets/${enc(this.bucketName)}/keys/${key}`, value, undefined, "kv.bucket.put");
+    }
+    /**
+     * Create a value only if the key doesn't exist (if-not-exists).
+     * Throws on conflict (HTTP 412).
+     */
+    async create(key, value) {
+        return this.restRequest("PUT", `/api/v1/kv/buckets/${enc(this.bucketName)}/keys/${key}`, value, { "If-None-Match": "*" }, "kv.bucket.create");
+    }
+    /**
+     * Update a value only if the revision matches (compare-and-swap).
+     * Throws on mismatch (HTTP 412).
+     */
+    async update(key, value, revision) {
+        return this.restRequest("PUT", `/api/v1/kv/buckets/${enc(this.bucketName)}/keys/${key}`, value, { "If-Match": String(revision) }, "kv.bucket.update");
+    }
+    /**
+     * Delete a key (soft delete / tombstone).
+     */
+    async delete(key) {
+        await this.restRequest("DELETE", `/api/v1/kv/buckets/${enc(this.bucketName)}/keys/${key}`, undefined, undefined, "kv.bucket.delete");
+    }
+    /**
+     * Purge a key and all its history.
+     */
+    async purge(key) {
+        await this.restRequest("DELETE", `/api/v1/kv/buckets/${enc(this.bucketName)}/keys/${key}?purge=true`, undefined, undefined, "kv.bucket.purge");
+    }
+    /**
+     * List keys with an optional wildcard filter.
+     */
+    async listKeys(filter) {
+        let path = `/api/v1/kv/buckets/${enc(this.bucketName)}/keys`;
+        if (filter) {
+            path += `?filter=${encodeURIComponent(filter)}`;
+        }
+        const result = await this.restRequest("GET", path, undefined, undefined, "kv.bucket.listKeys");
+        return result.keys;
+    }
+    async callOnError(error, context) {
+        if (!this.config.onError)
+            return;
+        try {
+            await this.config.onError(error, context);
+        }
+        catch (callbackError) {
+            console.error("[ironflow] onError callback threw:", callbackError);
+        }
+    }
+    async restRequest(httpMethod, path, body, extraHeaders, clientMethod) {
+        const url = `${this.config.serverUrl}${path}`;
+        const headers = {};
+        if (body !== undefined) {
+            headers["Content-Type"] =
+                typeof body === "string" || body instanceof Uint8Array
+                    ? "application/octet-stream"
+                    : "application/json";
+        }
+        if (this.config.apiKey) {
+            headers["Authorization"] = `Bearer ${this.config.apiKey}`;
+        }
+        if (extraHeaders) {
+            Object.assign(headers, extraHeaders);
+        }
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.config.timeout);
+        let status;
+        try {
+            const response = await fetch(url, {
+                method: httpMethod,
+                headers,
+                body: body !== undefined
+                    ? typeof body === "string" || body instanceof Uint8Array
+                        ? body
+                        : JSON.stringify(body)
+                    : undefined,
+                signal: controller.signal,
+            });
+            status = response.status;
+            if (!response.ok) {
+                const errorBody = await response.text();
+                let errorMessage = `KV request failed with status ${response.status}`;
+                try {
+                    const errorJson = JSON.parse(errorBody);
+                    if (errorJson.error)
+                        errorMessage = errorJson.error;
+                }
+                catch {
+                    if (errorBody)
+                        errorMessage = errorBody;
+                }
+                throwTypedError(response.status, errorMessage);
+            }
+            if (response.status === 204) {
+                return undefined;
+            }
+            return response.json();
+        }
+        catch (error) {
+            if (clientMethod) {
+                await this.callOnError(error, { method: clientMethod, endpoint: path, statusCode: status });
+            }
+            throw error;
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    }
+}
+/**
+ * KV client for bucket management and key operations.
+ */
+export class KVClient {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    /**
+     * Create a new bucket.
+     */
+    async createBucket(config) {
+        const body = { name: config.name };
+        if (config.description)
+            body.description = config.description;
+        if (config.ttlSeconds)
+            body.ttl_seconds = config.ttlSeconds;
+        if (config.maxValueSize)
+            body.max_value_size = config.maxValueSize;
+        if (config.maxBytes)
+            body.max_bytes = config.maxBytes;
+        if (config.history)
+            body.history = config.history;
+        return this.restRequest("POST", "/api/v1/kv/buckets", body, "kv.createBucket");
+    }
+    /**
+     * Delete a bucket.
+     */
+    async deleteBucket(name) {
+        await this.restRequest("DELETE", `/api/v1/kv/buckets/${enc(name)}`, undefined, "kv.deleteBucket");
+    }
+    /**
+     * List all buckets.
+     */
+    async listBuckets() {
+        const result = await this.restRequest("GET", "/api/v1/kv/buckets", undefined, "kv.listBuckets");
+        return result.buckets;
+    }
+    /**
+     * Get bucket info.
+     */
+    async getBucketInfo(name) {
+        return this.restRequest("GET", `/api/v1/kv/buckets/${enc(name)}`, undefined, "kv.getBucketInfo");
+    }
+    /**
+     * Get a bucket handle for key-level operations.
+     */
+    bucket(name) {
+        return new KVBucketHandle(name, this.config);
+    }
+    async callOnError(error, context) {
+        if (!this.config.onError)
+            return;
+        try {
+            await this.config.onError(error, context);
+        }
+        catch (callbackError) {
+            console.error("[ironflow] onError callback threw:", callbackError);
+        }
+    }
+    async restRequest(httpMethod, path, body, clientMethod) {
+        const url = `${this.config.serverUrl}${path}`;
+        const headers = {};
+        if (body !== undefined) {
+            headers["Content-Type"] = "application/json";
+        }
+        if (this.config.apiKey) {
+            headers["Authorization"] = `Bearer ${this.config.apiKey}`;
+        }
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.config.timeout);
+        let status;
+        try {
+            const response = await fetch(url, {
+                method: httpMethod,
+                headers,
+                body: body !== undefined ? JSON.stringify(body) : undefined,
+                signal: controller.signal,
+            });
+            status = response.status;
+            if (!response.ok) {
+                const errorBody = await response.text();
+                let errorMessage = `KV request failed with status ${response.status}`;
+                try {
+                    const errorJson = JSON.parse(errorBody);
+                    if (errorJson.error)
+                        errorMessage = errorJson.error;
+                }
+                catch {
+                    if (errorBody)
+                        errorMessage = errorBody;
+                }
+                throwTypedError(response.status, errorMessage);
+            }
+            if (response.status === 204) {
+                return undefined;
+            }
+            return response.json();
+        }
+        catch (error) {
+            if (clientMethod) {
+                await this.callOnError(error, { method: clientMethod, endpoint: path, statusCode: status });
+            }
+            throw error;
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+    }
+}
+function enc(s) {
+    return encodeURIComponent(s);
+}
+function throwTypedError(status, message) {
+    switch (status) {
+        case 401:
+            throw new UnauthenticatedError(message);
+        case 402:
+            throw new EnterpriseRequiredError(message);
+        case 403:
+            throw new UnauthorizedError(message);
+        default:
+            throw new IronflowError(message, { code: `HTTP_${status}` });
+    }
+}
+//# sourceMappingURL=kv.js.map

package/dist/kv.js.map

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

package/dist/projection-runner.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Projection Runner
+ *
+ * Processes events for a single projection using two strategies:
+ *
+ * 1. **Streaming (preferred):** Opens a persistent ConnectRPC server-stream
+ *    that receives events in real-time as they arrive. Uses micro-batching
+ *    (100ms window or batch_size events, whichever comes first) to amortize
+ *    state saves.
+ *
+ * 2. **Polling (fallback):** If streaming is unavailable (older server), falls
+ *    back to HTTP polling with exponential backoff (1s → 2s → 4s, max 10s).
+ *
+ * Both modes use the same handler execution and state persistence logic.
+ */
+import type { IronflowProjection, Logger } from "@ironflow/core";
+export interface ProjectionRunnerConfig {
+    projection: IronflowProjection<any, any>;
+    baseUrl: string;
+    headers: Record<string, string>;
+    logger: Logger;
+    signal?: AbortSignal;
+}
+export declare class ProjectionRunner {
+    private config;
+    private running;
+    private backoffMs;
+    private pendingEvents;
+    private flushTimer;
+    private flushChain;
+    private managedState;
+    private managedStateInitialized;
+    constructor(config: ProjectionRunnerConfig);
+    register(): Promise<void>;
+    /**
+     * Start in streaming mode (preferred). Opens a ConnectRPC server-stream
+     * that delivers events in real-time. Falls back to polling if the server
+     * returns Unimplemented or the stream fails to connect.
+     */
+    startStreaming(): Promise<void>;
+    /**
+     * Enqueue an event from the stream into the micro-batch.
+     * Flushes when batch is full or after FLUSH_INTERVAL_MS of inactivity.
+     * Flush calls are serialized via flushChain to prevent concurrent state mutations.
+     */
+    private enqueueEvent;
+    /** Serializes flush calls so only one runs at a time */
+    private scheduleFlush;
+    /**
+     * Flush pending events through the handler and persist state.
+     */
+    private flushPending;
+    /**
+     * Process a batch of events in managed mode: run reducer, save state.
+     */
+    private processManagedBatch;
+    /**
+     * Process a batch of events in external mode: run handler, ack.
+     */
+    private processExternalBatch;
+    /**
+     * Load existing projection state from the server so streaming resumes
+     * with the correct accumulated state.
+     */
+    private loadExistingState;
+    /**
+     * Start in poll mode (fallback). Uses the existing PollProjectionEvents RPC
+     * with exponential backoff.
+     */
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    private poll;
+    private buildContext;
+    private saveState;
+    private ackEvents;
+    private sleep;
+}
+/** Error thrown when the server doesn't support the streaming RPC */
+export declare class StreamingUnsupportedError extends Error {
+    constructor(message: string);
+}
+export declare function createProjectionRunner(config: ProjectionRunnerConfig): ProjectionRunner;
+//# sourceMappingURL=projection-runner.d.ts.map

package/dist/projection-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"projection-runner.d.ts","sourceRoot":"","sources":["../src/projection-runner.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EACV,kBAAkB,EAElB,MAAM,EAGP,MAAM,gBAAgB,CAAC;AAExB,MAAM,WAAW,sBAAsB;IAErC,UAAU,EAAE,kBAAkB,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IACzC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAuCD,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,MAAM,CAAyB;IACvC,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,SAAS,CAAQ;IAGzB,OAAO,CAAC,aAAa,CAAmB;IACxC,OAAO,CAAC,UAAU,CAA8C;IAEhE,OAAO,CAAC,UAAU,CAAoC;IAEtD,OAAO,CAAC,YAAY,CAAiB;IACrC,OAAO,CAAC,uBAAuB,CAAS;gBAE5B,MAAM,EAAE,sBAAsB;IAIpC,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAqB/B;;;;OAIG;IACG,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC;IA4KrC;;;;OAIG;IACH,OAAO,CAAC,YAAY;IAgBpB,wDAAwD;IACxD,OAAO,CAAC,aAAa;IAIrB;;OAEG;YACW,YAAY;IAkB1B;;OAEG;YACW,mBAAmB;IA2CjC;;OAEG;YACW,oBAAoB;IAelC;;;OAGG;YACW,iBAAiB;IA6B/B;;;OAGG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAyBtB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;YAWb,IAAI;IA2FlB,OAAO,CAAC,YAAY;YAiBN,SAAS;YA0BT,SAAS;IAoBvB,OAAO,CAAC,KAAK;CAad;AAED,qEAAqE;AACrE,qBAAa,yBAA0B,SAAQ,KAAK;gBACtC,OAAO,EAAE,MAAM;CAI5B;AAED,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,sBAAsB,GAAG,gBAAgB,CAEvF"}