@loomwork/ui-lineage 0.0.0-stage → 0.1.1

package/dist/esm/store.js

@@ -0,0 +1,172 @@
+import { DuplicateEnvelopeIdError, DuplicateSequenceError, headOf, } from "@loomwork/event-runtime";
+/**
+ * A lost slot, by class OR name (a store decorator or a second copy of the package throws an error
+ * that is not `instanceof` ours); mirrors the kernel's `isWriteConflict`.
+ */
+function isWriteConflict(err) {
+    if (err instanceof DuplicateSequenceError || err instanceof DuplicateEnvelopeIdError)
+        return true;
+    const name = err?.name;
+    return name === "DuplicateSequenceError" || name === "DuplicateEnvelopeIdError";
+}
+const clone = (v) => structuredClone(v);
+/** Reference in-memory store. Copies on the way in and out, so no caller can mutate the log. */
+export class InMemoryLineageStore {
+    lines = new Map();
+    async append(experienceId, expectedSequence, record) {
+        const line = this.lines.get(experienceId) ?? [];
+        if (line.length !== expectedSequence)
+            return { ok: false, tip: line.length };
+        const sequence = line.length + 1;
+        line.push(clone({ ...record, sequence }));
+        this.lines.set(experienceId, line);
+        return { ok: true, sequence };
+    }
+    async read(experienceId) {
+        return clone(this.lines.get(experienceId) ?? []);
+    }
+    async readTail(experienceId, limit) {
+        const line = this.lines.get(experienceId) ?? [];
+        return clone(limit >= line.length ? line : line.slice(line.length - Math.max(0, limit)));
+    }
+    async readAfter(experienceId, afterSequence, limit = Number.POSITIVE_INFINITY) {
+        // dense 1..n: the records after `a` start at index `a`
+        const line = this.lines.get(experienceId) ?? [];
+        const from = Math.max(0, afterSequence);
+        return clone(line.slice(from, Number.isFinite(limit) ? from + Math.max(0, limit) : undefined));
+    }
+    async *listStreams() {
+        for (const id of [...this.lines.keys()])
+            yield id;
+    }
+}
+/** The reserved-stream namespace a lineage's events live under in an `EventStore`. */
+export const LINEAGE_STREAM_PREFIX = "__loom_ui_lineage__:";
+/** The `workflowId` a lineage event is written under unless `eventStoreLineageStore` is given another. */
+export const LINEAGE_WORKFLOW_ID = "loom-ui.lineage";
+const WORKFLOW_ID = LINEAGE_WORKFLOW_ID;
+/** Every stream prefix this package may write under; the kernel's own reserved prefixes are not ours. */
+export const LOOM_UI_STREAM_NAMESPACE = "__loom_ui_";
+const WORKFLOW_ID_SHAPE = /^[A-Za-z0-9._:-]{1,128}$/;
+/**
+ * A `LineageStore` over loom's `EventStore`. One stream per experience
+ * (`__loom_ui_lineage__:<experienceId>`, a RESERVED stream so enumerators of real executions skip
+ * it; see the README for what a reserved stream costs); the lineage sequence IS the envelope sequence, so the CAS is the log's own
+ * `(executionId, sequence)` uniqueness. The adapter checks the tip first (a store enforces a
+ * taken slot, not a skipped one) and treats a `DuplicateSequenceError` from a racing writer as a
+ * lost CAS. Fencing, tenancy and sharding decorators wrap `store` as usual.
+ *
+ * `streamPrefix` must start with `__loom_ui_` (and say more): it is the namespace this package owns
+ * inside loom's reserved `__loom_` space, so a configuration can never write into the kernel's own
+ * control streams (`__loom_lifecycle__`, `__loom_erasure__`) or an execution's id space. `workflowId`
+ * is a short identifier. A bad value THROWS at construction (a misconfiguration, found at startup).
+ */
+export function eventStoreLineageStore(store, opts = {}) {
+    const prefix = opts.streamPrefix ?? LINEAGE_STREAM_PREFIX;
+    const workflowId = opts.workflowId ?? WORKFLOW_ID;
+    if (typeof prefix !== "string" ||
+        !prefix.startsWith(LOOM_UI_STREAM_NAMESPACE) ||
+        prefix.length <= LOOM_UI_STREAM_NAMESPACE.length ||
+        prefix.length > 128)
+        throw new Error(`streamPrefix must start with "${LOOM_UI_STREAM_NAMESPACE}" and name its stream (got ${JSON.stringify(String(prefix).slice(0, 40))})`);
+    if (typeof workflowId !== "string" || !WORKFLOW_ID_SHAPE.test(workflowId))
+        throw new Error("workflowId must be 1-128 characters of [A-Za-z0-9._:-]");
+    const streamOf = (experienceId) => `${prefix}${experienceId}`;
+    return {
+        streamPrefix: prefix,
+        workflowId,
+        async append(experienceId, expectedSequence, record) {
+            const executionId = streamOf(experienceId);
+            const tip = (await headOf(store, executionId)) ?? 0;
+            if (tip !== expectedSequence)
+                return { ok: false, tip };
+            const sequence = expectedSequence + 1;
+            try {
+                await store.append({
+                    id: `${executionId}#${sequence}`,
+                    workflowId,
+                    executionId,
+                    eventType: record.type,
+                    sequence,
+                    timestamp: Date.parse(record.at) || 0,
+                    payload: clone(record.payload),
+                    metadata: { at: record.at },
+                });
+            }
+            catch (err) {
+                if (isWriteConflict(err))
+                    return { ok: false, tip: (await headOf(store, executionId)) ?? sequence };
+                throw err;
+            }
+            return { ok: true, sequence };
+        },
+        async read(experienceId) {
+            return toRecords(await store.read(streamOf(experienceId)));
+        },
+        async readTail(experienceId, limit) {
+            const id = streamOf(experienceId);
+            const tip = (await headOf(store, id)) ?? 0;
+            if (tip === 0 || limit <= 0)
+                return [];
+            return toRecords(await readWindow(store, id, Math.max(1, tip - limit + 1), tip));
+        },
+        async readAfter(experienceId, afterSequence, limit = Number.POSITIVE_INFINITY) {
+            const id = streamOf(experienceId);
+            const tip = (await headOf(store, id)) ?? 0;
+            const from = Math.max(1, afterSequence + 1);
+            const to = Number.isFinite(limit) ? Math.min(tip, from + Math.max(0, limit) - 1) : tip;
+            if (to < from)
+                return [];
+            return toRecords(await readWindow(store, id, from, to));
+        },
+        ...(store.listExecutionsPage !== undefined || store.listExecutions !== undefined
+            ? {
+                async *listStreams() {
+                    // Reserved streams ARE surfaced by the SPI's enumeration (`__loom_*`), so ours are found
+                    // by prefix. Pages are keyset-ordered by code point, so with pages the scan starts just
+                    // before our prefix and stops once past it; the unpaged fallback filters the full list.
+                    if (store.listExecutionsPage === undefined) {
+                        for (const id of (await store.listExecutions?.()) ?? [])
+                            if (id.startsWith(prefix))
+                                yield id.slice(prefix.length);
+                        return;
+                    }
+                    let cursor = prefix.slice(0, -1);
+                    for (;;) {
+                        const page = await store.listExecutionsPage({
+                            ...(cursor !== undefined && { cursor }),
+                            limit: 500,
+                        });
+                        for (const id of page.executionIds) {
+                            if (id.startsWith(prefix))
+                                yield id.slice(prefix.length);
+                            else if (id > prefix)
+                                return;
+                        }
+                        if (page.nextCursor === undefined || page.nextCursor === cursor)
+                            return;
+                        cursor = page.nextCursor;
+                    }
+                },
+            }
+            : {}),
+    };
+}
+function toRecords(events) {
+    return events
+        .slice()
+        .sort((a, b) => a.sequence - b.sequence)
+        .map((e) => ({
+        sequence: e.sequence,
+        type: e.eventType,
+        payload: clone(e.payload),
+        at: typeof e.metadata?.at === "string" ? e.metadata.at : new Date(e.timestamp).toISOString(),
+    }));
+}
+/** Sequences `from..to` (inclusive) of a stream: the store's `readRange`, else `readFrom`/`read` filtered. */
+async function readWindow(store, id, from, to) {
+    if (store.readRange !== undefined)
+        return store.readRange(id, from, to);
+    return (await store.read(id)).filter((e) => e.sequence >= from && e.sequence <= to);
+}
+//# sourceMappingURL=store.js.map

package/dist/esm/store.js.map

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