@nodii/saga 0.0.2 → 0.2.0

package/dist/signal-bus/redis-stream.js

@@ -0,0 +1,189 @@
+// RedisSignalBus — real, Redis-Streams-backed implementation of
+// `SagaSignalBus`. Spec § 5.9 + comm doctrine § 9.2.
+//
+// Wire design:
+//   - One Redis stream per service: `nodii:<serviceId>:saga:signals`.
+//   - Each saga that calls `awaitSagaSignal` opens an XREAD with its own
+//     consumer group keyed by `saga:<sagaId>`. This gives per-saga
+//     isolation — a parent and child saga listening for the same event
+//     type don't steal each other's messages.
+//   - Sibling fan-out uses the `to` field on the message body; the
+//     consume() filter rejects messages addressed to a different saga.
+//   - We claim with a short block (50ms) so callers can poll without
+//     blocking forever; the higher-level `awaitSagaSignal` does the
+//     timeout-budget loop.
+export class RedisSignalBus {
+    redis;
+    stream;
+    blockMs;
+    // Consumer group / consumer name dedup. We attempt MKSTREAM-create
+    // lazily; second concurrent call collides but Redis errors are
+    // benignly ignored.
+    groupsEnsured = new Set();
+    constructor(opts) {
+        this.redis = opts.redis;
+        this.stream = opts.streamName ?? `nodii:${opts.serviceId}:saga:signals`;
+        this.blockMs = opts.blockMs ?? 50;
+    }
+    async emit(args) {
+        await this.redis.xadd(this.stream, "*", "saga_id", args.sagaId, "event_type", args.eventType, "payload", JSON.stringify(args.payload ?? null), "scope", args.scope ?? "siblings", "to", args.to ?? "");
+    }
+    async consume(args) {
+        const group = `saga:${args.sagaId}`;
+        await this.ensureGroup(group);
+        const consumer = `c:${args.sagaId}`;
+        // XREADGROUP with `>` to pick up new messages only. We pull up to 32
+        // and filter in-memory because Redis Streams don't support
+        // server-side payload predicates.
+        // biome-ignore lint/suspicious/noExplicitAny: ioredis XREADGROUP returns nested string arrays — we narrow to the structure we know
+        const raw = await this.redis.xreadgroup("GROUP", group, consumer, "COUNT", 32, "BLOCK", this.blockMs, "STREAMS", this.stream, ">");
+        if (!raw)
+            return null;
+        const messages = extractMessages(raw, this.stream);
+        for (const msg of messages) {
+            const sig = parseSignal(msg.id, msg.fields);
+            if (!sig) {
+                // Bad message — XACK + skip.
+                await this.redis.xack(this.stream, group, msg.id);
+                continue;
+            }
+            if (sig.eventType !== args.eventType) {
+                // Not what this caller wants — XACK so the same group doesn't
+                // see it again (it's addressed to the saga, not to a particular
+                // event-type subscription).
+                await this.redis.xack(this.stream, group, msg.id);
+                continue;
+            }
+            if (sig.to && sig.to !== args.sagaId) {
+                await this.redis.xack(this.stream, group, msg.id);
+                continue;
+            }
+            if (args.from && sig.sagaId !== args.from) {
+                await this.redis.xack(this.stream, group, msg.id);
+                continue;
+            }
+            if (args.predicate && !args.predicate(sig.payload)) {
+                await this.redis.xack(this.stream, group, msg.id);
+                continue;
+            }
+            await this.redis.xack(this.stream, group, msg.id);
+            return sig.payload;
+        }
+        return null;
+    }
+    async list(args) {
+        // XRANGE pulls the full stream; for v0.1.0 this is acceptable since
+        // saga.signals is per-service and bounded. Production may layer
+        // pagination on top.
+        // biome-ignore lint/suspicious/noExplicitAny: XRANGE returns [id, [field, value, ...]][]
+        const raw = await this.redis.xrange(this.stream, "-", "+");
+        const out = [];
+        if (!Array.isArray(raw))
+            return out;
+        for (const entry of raw) {
+            if (!Array.isArray(entry) || entry.length < 2)
+                continue;
+            const id = entry[0];
+            const fields = entry[1];
+            const sig = parseSignal(id, fields);
+            if (!sig)
+                continue;
+            if (sig.to && sig.to !== args.sagaId)
+                continue;
+            if (args.eventType && sig.eventType !== args.eventType)
+                continue;
+            out.push({
+                sagaId: sig.sagaId,
+                eventType: sig.eventType,
+                payload: sig.payload,
+            });
+        }
+        return out;
+    }
+    /** Test helper — drop the stream + reset ensure cache. */
+    async resetForTests() {
+        try {
+            await this.redis.del(this.stream);
+        }
+        catch {
+            /* swallow */
+        }
+        this.groupsEnsured.clear();
+    }
+    async close() {
+        /* leaves Redis connection management to the caller */
+    }
+    async ensureGroup(group) {
+        if (this.groupsEnsured.has(group))
+            return;
+        try {
+            await this.redis.xgroup("CREATE", this.stream, group, "0", "MKSTREAM");
+        }
+        catch (err) {
+            // BUSYGROUP is fine — group already exists.
+            const msg = err instanceof Error ? err.message : String(err);
+            if (!msg.includes("BUSYGROUP")) {
+                // Other errors are surfaced; XREADGROUP would also fail.
+            }
+        }
+        this.groupsEnsured.add(group);
+    }
+}
+function extractMessages(raw, expectedStream) {
+    // raw shape: [[ streamName, [[ id, [field, value, ...] ], ...] ], ...]
+    const out = [];
+    if (!Array.isArray(raw))
+        return out;
+    for (const streamEntry of raw) {
+        if (!Array.isArray(streamEntry) || streamEntry.length < 2)
+            continue;
+        const streamName = streamEntry[0];
+        if (streamName !== expectedStream)
+            continue;
+        const entries = streamEntry[1];
+        if (!Array.isArray(entries))
+            continue;
+        for (const entry of entries) {
+            if (!Array.isArray(entry) || entry.length < 2)
+                continue;
+            const id = entry[0];
+            const fields = entry[1];
+            if (typeof id === "string" && Array.isArray(fields)) {
+                out.push({ id, fields: fields });
+            }
+        }
+    }
+    return out;
+}
+function parseSignal(id, fields) {
+    const map = new Map();
+    for (let i = 0; i + 1 < fields.length; i += 2) {
+        const k = fields[i];
+        const v = fields[i + 1];
+        if (k !== undefined && v !== undefined)
+            map.set(k, v);
+    }
+    const sagaId = map.get("saga_id");
+    const eventType = map.get("event_type");
+    const payloadStr = map.get("payload");
+    if (!sagaId || !eventType || payloadStr === undefined)
+        return null;
+    let payload;
+    try {
+        payload = JSON.parse(payloadStr);
+    }
+    catch {
+        payload = payloadStr;
+    }
+    const scope = map.get("scope") === "global" ? "global" : "siblings";
+    const to = map.get("to");
+    return {
+        id,
+        sagaId,
+        eventType,
+        payload,
+        scope,
+        to: to === undefined || to === "" ? null : to,
+    };
+}
+//# sourceMappingURL=redis-stream.js.map

package/dist/signal-bus/redis-stream.js.map

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

package/dist/signals.d.ts

@@ -0,0 +1,29 @@
+export declare function emitSagaSignal(eventType: string, payload: unknown, opts?: {
+    to?: string;
+    scope?: "siblings" | "global";
+}): Promise<void>;
+export declare function awaitSagaSignal<T = unknown>(eventType: string, opts?: {
+    from?: string;
+    predicate?: (payload: unknown) => boolean;
+    /** Poll budget in milliseconds. Default 0 = single check. */
+    timeoutMs?: number;
+    /** Test hook — defaults to setTimeout. */
+    sleep?: (ms: number) => Promise<void>;
+}): Promise<T | null>;
+export declare function awaitChildren(childIds: readonly string[], opts?: {
+    status?: "completed" | "any-terminal";
+    timeoutMs?: number;
+    sleep?: (ms: number) => Promise<void>;
+}): Promise<void>;
+export declare function awaitAnySibling<T = unknown>(eventType: string, opts?: {
+    predicate?: (payload: unknown) => boolean;
+    timeoutMs?: number;
+    sleep?: (ms: number) => Promise<void>;
+}): Promise<T | null>;
+export declare function getSiblings(opts?: {
+    status?: string;
+}): Promise<{
+    id: string;
+    status: string;
+}[]>;
+//# sourceMappingURL=signals.d.ts.map

package/dist/signals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signals.d.ts","sourceRoot":"","sources":["../src/signals.ts"],"names":[],"mappings":"AAOA,wBAAsB,cAAc,CAClC,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,OAAO,EAChB,IAAI,GAAE;IAAE,EAAE,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,UAAU,GAAG,QAAQ,CAAA;CAAO,GACxD,OAAO,CAAC,IAAI,CAAC,CAkBf;AAED,wBAAsB,eAAe,CAAC,CAAC,GAAG,OAAO,EAC/C,SAAS,EAAE,MAAM,EACjB,IAAI,GAAE;IACJ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC;IAC1C,6DAA6D;IAC7D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,0CAA0C;IAC1C,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAClC,GACL,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CA8BnB;AAED,wBAAsB,aAAa,CACjC,QAAQ,EAAE,SAAS,MAAM,EAAE,EAC3B,IAAI,GAAE;IACJ,MAAM,CAAC,EAAE,WAAW,GAAG,cAAc,CAAC;IACtC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAClC,GACL,OAAO,CAAC,IAAI,CAAC,CA+Bf;AAYD,wBAAsB,eAAe,CAAC,CAAC,GAAG,OAAO,EAC/C,SAAS,EAAE,MAAM,EACjB,IAAI,GAAE;IACJ,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC;IAC1C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAClC,GACL,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAEnB;AAED,wBAAsB,WAAW,CAC/B,IAAI,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAA;CAAO,GAC7B,OAAO,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,EAAE,CAAC,CAc3C"}

package/dist/signals.js

@@ -0,0 +1,113 @@
+// Cross-saga primitives — § 5.9. Layered on the pluggable SagaSignalBus so
+// the v0.1.0 in-memory bus and the deferred Redis-stream bus expose the
+// same surface.
+import { requireSagaContext } from "./context";
+import { requireSaga } from "./init";
+export async function emitSagaSignal(eventType, payload, opts = {}) {
+    const cfg = requireSaga();
+    const ctx = requireSagaContext("emitSagaSignal");
+    await cfg.signalBus.emit({
+        sagaId: ctx.row.id,
+        eventType,
+        payload,
+        scope: opts.scope ?? "siblings",
+        to: opts.to,
+    });
+    if (cfg.telemetryAudit) {
+        await cfg.telemetryAudit.emit({
+            action: "saga_signal_emitted",
+            target_kind: "saga",
+            target_id: ctx.row.id,
+            payload: { event_type: eventType },
+        });
+    }
+}
+export async function awaitSagaSignal(eventType, opts = {}) {
+    const cfg = requireSaga();
+    const ctx = requireSagaContext("awaitSagaSignal");
+    const start = Date.now();
+    const timeoutMs = opts.timeoutMs ?? 0;
+    const sleep = opts.sleep ??
+        ((ms) => new Promise((res) => setTimeout(res, ms)));
+    for (;;) {
+        const hit = await cfg.signalBus.consume({
+            sagaId: ctx.row.id,
+            eventType,
+            from: opts.from,
+            predicate: opts.predicate,
+        });
+        if (hit !== null) {
+            if (cfg.telemetryAudit) {
+                await cfg.telemetryAudit.emit({
+                    action: "saga_signal_received",
+                    target_kind: "saga",
+                    target_id: ctx.row.id,
+                    payload: { event_type: eventType },
+                });
+            }
+            return hit;
+        }
+        if (Date.now() - start >= timeoutMs)
+            return null;
+        await sleep(10);
+    }
+}
+export async function awaitChildren(childIds, opts = {}) {
+    const cfg = requireSaga();
+    requireSagaContext("awaitChildren");
+    const want = opts.status ?? "any-terminal";
+    const start = Date.now();
+    const timeoutMs = opts.timeoutMs ?? 0;
+    const sleep = opts.sleep ??
+        ((ms) => new Promise((res) => setTimeout(res, ms)));
+    for (;;) {
+        let allDone = true;
+        for (const childId of childIds) {
+            const row = await cfg.stateStore.getSaga(childId);
+            if (!row) {
+                allDone = false;
+                break;
+            }
+            if (want === "completed" && row.status !== "completed") {
+                allDone = false;
+                break;
+            }
+            if (want === "any-terminal" && !TERMINAL_STATUSES.has(row.status)) {
+                allDone = false;
+                break;
+            }
+        }
+        if (allDone)
+            return;
+        if (Date.now() - start >= timeoutMs)
+            return;
+        await sleep(10);
+    }
+}
+const TERMINAL_STATUSES = new Set([
+    "completed",
+    "compensated",
+    "compensation_failed",
+    "compensated_with_errors",
+    "compensated_manual",
+    "technical_failure",
+    "cancelled",
+]);
+export async function awaitAnySibling(eventType, opts = {}) {
+    return awaitSagaSignal(eventType, opts);
+}
+export async function getSiblings(opts = {}) {
+    const cfg = requireSaga();
+    const ctx = requireSagaContext("getSiblings");
+    if (!ctx.row.parent_saga_id)
+        return [];
+    // SagaStateStore.list is the public async accessor (matches Py + Go).
+    // Awaiting is mandatory — earlier versions cast to sync and `.filter`'d
+    // a Promise; the resulting TypeError was hidden by the cast.
+    const all = (await cfg.stateStore.list?.({})) ?? [];
+    return all
+        .filter((r) => r.parent_saga_id === ctx.row.parent_saga_id && r.id !== ctx.row.id)
+        .filter((r) => !opts.status || r.status === opts.status)
+        .map((r) => ({ id: r.id, status: r.status }));
+}
+//# sourceMappingURL=signals.js.map

package/dist/signals.js.map

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

package/dist/state-store/index.d.ts

@@ -0,0 +1,2 @@
+export { PostgresSagaStateStore, type PostgresSagaStateStoreOpts, } from "./postgres";
+//# sourceMappingURL=index.d.ts.map

package/dist/state-store/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/state-store/index.ts"],"names":[],"mappings":"AAKA,OAAO,EACL,sBAAsB,EACtB,KAAK,0BAA0B,GAChC,MAAM,YAAY,CAAC"}

package/dist/state-store/index.js

@@ -0,0 +1,6 @@
+// Production-bound state-store exports.
+//
+// `PostgresSagaStateStore` is the only state store production code should
+// use. For tests, see `@nodii/saga/test-doubles`.
+export { PostgresSagaStateStore, } from "./postgres";
+//# sourceMappingURL=index.js.map

package/dist/state-store/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/state-store/index.ts"],"names":[],"mappings":"AAAA,wCAAwC;AACxC,EAAE;AACF,0EAA0E;AAC1E,kDAAkD;AAElD,OAAO,EACL,sBAAsB,GAEvB,MAAM,YAAY,CAAC"}

package/dist/state-store/postgres.d.ts

@@ -0,0 +1,47 @@
+import type { CompensationLogEntry, ListSagasFilter, SagaStateRow, SagaStateStore } from "../types";
+type SqlClient = {
+    unsafe: (sql: string, args?: unknown[]) => Promise<any>;
+    end?: () => Promise<void>;
+};
+export interface PostgresSagaStateStoreOpts {
+    /** Live postgres.js client (or any object exposing `.unsafe(sql, args)`). */
+    sql: SqlClient;
+    /** Override the default table name; defaults to `saga_state`. */
+    tableName?: string;
+    /** Optional hook fired when an entry is truncated; used by tests + metrics. */
+    onTruncate?: (info: {
+        sagaId: string;
+        stepName: string;
+        originalBytes: number;
+    }) => void;
+}
+export declare class PostgresSagaStateStore implements SagaStateStore {
+    private readonly sql;
+    private readonly table;
+    private readonly onTruncate?;
+    constructor(opts: PostgresSagaStateStoreOpts);
+    createSaga(row: SagaStateRow): Promise<void>;
+    getSaga(sagaId: string): Promise<SagaStateRow | null>;
+    updateSagaStatus(sagaId: string, update: Partial<Pick<SagaStateRow, "status" | "current_step" | "completed_at" | "failure_reason" | "failure_step" | "last_admin_action" | "last_admin_actor_id" | "last_admin_at" | "cancel_reason" | "next_resume_at">>): Promise<void>;
+    appendStepOutput(sagaId: string, stepName: string, output: unknown): Promise<void>;
+    appendCompensationLog(sagaId: string, entry: CompensationLogEntry): Promise<void>;
+    list(filter?: ListSagasFilter): Promise<SagaStateRow[]>;
+    /** Reaper-side scan — used by `startSagaReaper`. */
+    listStalePaused(cutoffIso: string): Promise<SagaStateRow[]>;
+    /** Outbox helpers — see `async-step.ts`. */
+    writeOutboxBegin(args: {
+        sagaId: string;
+        stepName: string;
+        eventType: string;
+        payload: unknown;
+        tenantId: string | null;
+    }): Promise<void>;
+    readOutboxForSaga(sagaId: string): Promise<{
+        stepName: string;
+        eventType: string;
+        payload: unknown;
+        createdAt: string;
+    }[]>;
+}
+export {};
+//# sourceMappingURL=postgres.d.ts.map

package/dist/state-store/postgres.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"postgres.d.ts","sourceRoot":"","sources":["../../src/state-store/postgres.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EACV,oBAAoB,EACpB,eAAe,EACf,YAAY,EACZ,cAAc,EAEf,MAAM,UAAU,CAAC;AAIlB,KAAK,SAAS,GAAG;IAGf,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,GAAG,CAAC,CAAC;IACxD,GAAG,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B,CAAC;AAIF,MAAM,WAAW,0BAA0B;IACzC,6EAA6E;IAC7E,GAAG,EAAE,SAAS,CAAC;IACf,iEAAiE;IACjE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,+EAA+E;IAC/E,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE;QAClB,MAAM,EAAE,MAAM,CAAC;QACf,QAAQ,EAAE,MAAM,CAAC;QACjB,aAAa,EAAE,MAAM,CAAC;KACvB,KAAK,IAAI,CAAC;CACZ;AAED,qBAAa,sBAAuB,YAAW,cAAc;IAC3D,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAY;IAChC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,CAIjB;gBAEC,IAAI,EAAE,0BAA0B;IAMtC,UAAU,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IA2C5C,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC;IAmBrD,gBAAgB,CACpB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,OAAO,CACb,IAAI,CACF,YAAY,EACV,QAAQ,GACR,cAAc,GACd,cAAc,GACd,gBAAgB,GAChB,cAAc,GACd,mBAAmB,GACnB,qBAAqB,GACrB,eAAe,GACf,eAAe,GACf,gBAAgB,CACnB,CACF,GACA,OAAO,CAAC,IAAI,CAAC;IAkCV,gBAAgB,CACpB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,OAAO,GACd,OAAO,CAAC,IAAI,CAAC;IA6BV,qBAAqB,CACzB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,oBAAoB,GAC1B,OAAO,CAAC,IAAI,CAAC;IAQV,IAAI,CAAC,MAAM,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAmC7D,oDAAoD;IAC9C,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAiBjE,4CAA4C;IACtC,gBAAgB,CAAC,IAAI,EAAE;QAC3B,MAAM,EAAE,MAAM,CAAC;QACf,QAAQ,EAAE,MAAM,CAAC;QACjB,SAAS,EAAE,MAAM,CAAC;QAClB,OAAO,EAAE,OAAO,CAAC;QACjB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;KACzB,GAAG,OAAO,CAAC,IAAI,CAAC;IAYX,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAC9C;QACE,QAAQ,EAAE,MAAM,CAAC;QACjB,SAAS,EAAE,MAAM,CAAC;QAClB,OAAO,EAAE,OAAO,CAAC;QACjB,SAAS,EAAE,MAAM,CAAC;KACnB,EAAE,CACJ;CAiBF"}