@dudousxd/nestjs-durable-core 0.28.0 → 0.28.2

package/dist/index.d.cts

@@ -277,6 +277,28 @@ interface StateStore {
     transaction?<T>(work: (tx: StoreTransaction) => Promise<T>): Promise<T>;
     listRuns(query: RunQuery): Promise<WorkflowRun[]>;
     listCheckpoints(runId: string): Promise<StepCheckpoint[]>;
+    /**
+     * The LATEST checkpoint for `runId` whose `name` equals `name` exactly (highest `seq` wins), or
+     * `undefined` if none. A targeted read that avoids fetching + deserializing every checkpoint just to
+     * keep one match — the store does the filter (`WHERE name = … ORDER BY seq DESC LIMIT 1`). Preserves
+     * the "last in seq order wins" semantics the engine relies on for `getEvent` (a re-published key
+     * overwrites the prior value at a higher seq, so the highest-seq match is the current value).
+     *
+     * Optional: a store that omits it still works — the engine falls back to {@link listCheckpoints}
+     * plus an in-JS filter that produces the identical result.
+     */
+    getLatestCheckpointByName?(runId: string, name: string): Promise<StepCheckpoint | undefined>;
+    /**
+     * All checkpoints for `runId` whose `name` starts with ANY of `prefixes`, ordered by `seq` ascending
+     * (same order as {@link listCheckpoints}). A targeted read that avoids scanning every checkpoint just
+     * to keep the prefix matches — the store does the filter (`WHERE name LIKE 'prefix%' …`). Used by the
+     * run-tree to find a parent's child edges (`signal:child:` / `spawn:` checkpoints) without loading the
+     * whole history. An empty `prefixes` array matches nothing.
+     *
+     * Optional: a store that omits it still works — the engine falls back to {@link listCheckpoints}
+     * plus an in-JS prefix scan that produces the identical result.
+     */
+    listCheckpointsByNamePrefix?(runId: string, prefixes: string[]): Promise<StepCheckpoint[]>;
 }
 /** Typed, queryable per-run data — exact values for `eq`/`ne`, numbers/strings for range ops. */
 type SearchAttributes = Record<string, string | number | boolean>;
@@ -1792,6 +1814,8 @@ declare class CodecStateStore implements StateStore {
     } | null>;
     listRuns(query: RunQuery): Promise<WorkflowRun[]>;
     listCheckpoints(runId: string): Promise<StepCheckpoint[]>;
+    getLatestCheckpointByName(runId: string, name: string): Promise<StepCheckpoint | undefined>;
+    listCheckpointsByNamePrefix(runId: string, prefixes: string[]): Promise<StepCheckpoint[]>;
 }
 
 /** Token prefix for every waiter on `name` — used by `listSignalWaiters` to fan an event out. */
@@ -1960,6 +1984,16 @@ declare function attributeOperand(filter: AttributeFilter): string | number;
 /**
  * Dependency-injection tokens. Adapters bind their implementations to these so `core` and
  * `@dudousxd/nestjs-durable` depend only on the interfaces in `./interfaces`.
+ *
+ * These use `Symbol.for(key)` (the global symbol registry), NOT `Symbol(key)`, so the token is the
+ * SAME instance no matter how many times `core` is evaluated in a process. A consumer can hold more
+ * than one physical copy of `core` at runtime — pnpm peer-dependency multiplexing installs a
+ * separate virtual copy per distinct peer set, and the dual ESM/CJS build can be loaded once as
+ * `import` (`index.js`) and once as `require` (`index.cjs`). A plain `Symbol()` would mint a
+ * DISTINCT token per copy, so `DurableModule` (provider) and `DashboardService` / a store adapter
+ * (injector) could resolve different symbols → Nest can't satisfy the dependency
+ * (`STATE_STORE is not available in the DurableApiModule context`). A registered symbol collapses
+ * them to one. Mirrors the `CONTEXT_ACCESSOR` token in `@dudousxd/nestjs-durable`'s `tokens.ts`.
  */
 declare const STATE_STORE: unique symbol;
 declare const TRANSPORT: unique symbol;
@@ -1982,6 +2016,13 @@ declare class InMemoryStateStore implements StateStore {
     private readonly attributeIndex;
     /** Test/observability hook: how many candidate runs the last attribute query's index produced. */
     lastAttributeCandidates: number;
+    /**
+     * Test/observability hook: how many checkpoint rows the LAST checkpoint read materialized (the rows
+     * actually returned to the caller). `listCheckpoints` returns all rows for the run; the targeted
+     * {@link getLatestCheckpointByName} / {@link listCheckpointsByNamePrefix} return only the matches —
+     * so this lets the benchmark contrast "fetch N, scan in JS" against "fetch the k that match".
+     */
+    lastCheckpointRowsRead: number;
     private key;
     /** Drop then re-add a run's normalized attribute rows so the index tracks its current attributes. */
     private reindexAttributes;
@@ -2016,6 +2057,8 @@ declare class InMemoryStateStore implements StateStore {
     private candidatesForFilter;
     listRuns(query: RunQuery): Promise<WorkflowRun[]>;
     listCheckpoints(runId: string): Promise<StepCheckpoint[]>;
+    getLatestCheckpointByName(runId: string, name: string): Promise<StepCheckpoint | undefined>;
+    listCheckpointsByNamePrefix(runId: string, prefixes: string[]): Promise<StepCheckpoint[]>;
 }
 
 /**

package/dist/index.d.ts

@@ -277,6 +277,28 @@ interface StateStore {
     transaction?<T>(work: (tx: StoreTransaction) => Promise<T>): Promise<T>;
     listRuns(query: RunQuery): Promise<WorkflowRun[]>;
     listCheckpoints(runId: string): Promise<StepCheckpoint[]>;
+    /**
+     * The LATEST checkpoint for `runId` whose `name` equals `name` exactly (highest `seq` wins), or
+     * `undefined` if none. A targeted read that avoids fetching + deserializing every checkpoint just to
+     * keep one match — the store does the filter (`WHERE name = … ORDER BY seq DESC LIMIT 1`). Preserves
+     * the "last in seq order wins" semantics the engine relies on for `getEvent` (a re-published key
+     * overwrites the prior value at a higher seq, so the highest-seq match is the current value).
+     *
+     * Optional: a store that omits it still works — the engine falls back to {@link listCheckpoints}
+     * plus an in-JS filter that produces the identical result.
+     */
+    getLatestCheckpointByName?(runId: string, name: string): Promise<StepCheckpoint | undefined>;
+    /**
+     * All checkpoints for `runId` whose `name` starts with ANY of `prefixes`, ordered by `seq` ascending
+     * (same order as {@link listCheckpoints}). A targeted read that avoids scanning every checkpoint just
+     * to keep the prefix matches — the store does the filter (`WHERE name LIKE 'prefix%' …`). Used by the
+     * run-tree to find a parent's child edges (`signal:child:` / `spawn:` checkpoints) without loading the
+     * whole history. An empty `prefixes` array matches nothing.
+     *
+     * Optional: a store that omits it still works — the engine falls back to {@link listCheckpoints}
+     * plus an in-JS prefix scan that produces the identical result.
+     */
+    listCheckpointsByNamePrefix?(runId: string, prefixes: string[]): Promise<StepCheckpoint[]>;
 }
 /** Typed, queryable per-run data — exact values for `eq`/`ne`, numbers/strings for range ops. */
 type SearchAttributes = Record<string, string | number | boolean>;
@@ -1792,6 +1814,8 @@ declare class CodecStateStore implements StateStore {
     } | null>;
     listRuns(query: RunQuery): Promise<WorkflowRun[]>;
     listCheckpoints(runId: string): Promise<StepCheckpoint[]>;
+    getLatestCheckpointByName(runId: string, name: string): Promise<StepCheckpoint | undefined>;
+    listCheckpointsByNamePrefix(runId: string, prefixes: string[]): Promise<StepCheckpoint[]>;
 }
 
 /** Token prefix for every waiter on `name` — used by `listSignalWaiters` to fan an event out. */
@@ -1960,6 +1984,16 @@ declare function attributeOperand(filter: AttributeFilter): string | number;
 /**
  * Dependency-injection tokens. Adapters bind their implementations to these so `core` and
  * `@dudousxd/nestjs-durable` depend only on the interfaces in `./interfaces`.
+ *
+ * These use `Symbol.for(key)` (the global symbol registry), NOT `Symbol(key)`, so the token is the
+ * SAME instance no matter how many times `core` is evaluated in a process. A consumer can hold more
+ * than one physical copy of `core` at runtime — pnpm peer-dependency multiplexing installs a
+ * separate virtual copy per distinct peer set, and the dual ESM/CJS build can be loaded once as
+ * `import` (`index.js`) and once as `require` (`index.cjs`). A plain `Symbol()` would mint a
+ * DISTINCT token per copy, so `DurableModule` (provider) and `DashboardService` / a store adapter
+ * (injector) could resolve different symbols → Nest can't satisfy the dependency
+ * (`STATE_STORE is not available in the DurableApiModule context`). A registered symbol collapses
+ * them to one. Mirrors the `CONTEXT_ACCESSOR` token in `@dudousxd/nestjs-durable`'s `tokens.ts`.
  */
 declare const STATE_STORE: unique symbol;
 declare const TRANSPORT: unique symbol;
@@ -1982,6 +2016,13 @@ declare class InMemoryStateStore implements StateStore {
     private readonly attributeIndex;
     /** Test/observability hook: how many candidate runs the last attribute query's index produced. */
     lastAttributeCandidates: number;
+    /**
+     * Test/observability hook: how many checkpoint rows the LAST checkpoint read materialized (the rows
+     * actually returned to the caller). `listCheckpoints` returns all rows for the run; the targeted
+     * {@link getLatestCheckpointByName} / {@link listCheckpointsByNamePrefix} return only the matches —
+     * so this lets the benchmark contrast "fetch N, scan in JS" against "fetch the k that match".
+     */
+    lastCheckpointRowsRead: number;
     private key;
     /** Drop then re-add a run's normalized attribute rows so the index tracks its current attributes. */
     private reindexAttributes;
@@ -2016,6 +2057,8 @@ declare class InMemoryStateStore implements StateStore {
     private candidatesForFilter;
     listRuns(query: RunQuery): Promise<WorkflowRun[]>;
     listCheckpoints(runId: string): Promise<StepCheckpoint[]>;
+    getLatestCheckpointByName(runId: string, name: string): Promise<StepCheckpoint | undefined>;
+    listCheckpointsByNamePrefix(runId: string, prefixes: string[]): Promise<StepCheckpoint[]>;
 }
 
 /**

package/dist/index.js

@@ -2039,7 +2039,12 @@ var WorkflowEngine = class {
     for (const w of await this.store.listSignalWaiters("child:")) {
       if (w.runId === parentRunId) childIds.add(w.token.slice("child:".length));
     }
-    for (const cp of await this.store.listCheckpoints(parentRunId)) {
+    const prefixes = [
+      "signal:child:",
+      "spawn:"
+    ];
+    const childCheckpoints = this.store.listCheckpointsByNamePrefix ? await this.store.listCheckpointsByNamePrefix(parentRunId, prefixes) : (await this.store.listCheckpoints(parentRunId)).filter((cp) => prefixes.some((p) => cp.name.startsWith(p)));
+    for (const cp of childCheckpoints) {
       if (cp.name.startsWith("signal:child:")) childIds.add(cp.name.slice("signal:child:".length));
       if (cp.name.startsWith("spawn:") && typeof cp.output === "string") childIds.add(cp.output);
     }
@@ -2830,9 +2835,12 @@ var WorkflowEngine = class {
   */
   async getEvent(runId, key) {
     const name = `event:${key}`;
-    const checkpoints = await this.store.listCheckpoints(runId);
+    if (this.store.getLatestCheckpointByName) {
+      const latest2 = await this.store.getLatestCheckpointByName(runId, name);
+      return latest2?.output;
+    }
     let latest;
-    for (const cp of checkpoints) if (cp.name === name) latest = cp.output;
+    for (const cp of await this.store.listCheckpoints(runId)) if (cp.name === name) latest = cp.output;
     return latest;
   }
   /**
@@ -3285,6 +3293,19 @@ var CodecStateStore = class {
   async listCheckpoints(runId) {
     return (await this.inner.listCheckpoints(runId)).map((c) => this.decCp(c));
   }
+  async getLatestCheckpointByName(runId, name) {
+    if (this.inner.getLatestCheckpointByName) {
+      const cp = await this.inner.getLatestCheckpointByName(runId, name);
+      return cp ? this.decCp(cp) : void 0;
+    }
+    let latest;
+    for (const cp of await this.inner.listCheckpoints(runId)) if (cp.name === name) latest = cp;
+    return latest ? this.decCp(latest) : void 0;
+  }
+  async listCheckpointsByNamePrefix(runId, prefixes) {
+    const matches = this.inner.listCheckpointsByNamePrefix ? await this.inner.listCheckpointsByNamePrefix(runId, prefixes) : (await this.inner.listCheckpoints(runId)).filter((cp) => prefixes.some((p) => cp.name.startsWith(p)));
+    return matches.map((c) => this.decCp(c));
+  }
 };
 
 // src/metrics.ts
@@ -3309,11 +3330,16 @@ function collectMetrics(engine) {
   };
   const wf = /* @__PURE__ */ __name((name) => {
     const k = name ?? "unknown";
-    return m.byWorkflow[k] ??= {
-      started: 0,
-      completed: 0,
-      failed: 0
-    };
+    let entry = m.byWorkflow[k];
+    if (!entry) {
+      entry = {
+        started: 0,
+        completed: 0,
+        failed: 0
+      };
+      m.byWorkflow[k] = entry;
+    }
+    return entry;
   }, "wf");
   const stop = engine.subscribe((e) => {
     switch (e.type) {
@@ -3539,9 +3565,9 @@ function attributeOperand(filter) {
 __name(attributeOperand, "attributeOperand");
 
 // src/tokens.ts
-var STATE_STORE = Symbol("nestjs-durable:STATE_STORE");
-var TRANSPORT = Symbol("nestjs-durable:TRANSPORT");
-var DURABLE_OPTIONS = Symbol("nestjs-durable:DURABLE_OPTIONS");
+var STATE_STORE = Symbol.for("nestjs-durable:STATE_STORE");
+var TRANSPORT = Symbol.for("nestjs-durable:TRANSPORT");
+var DURABLE_OPTIONS = Symbol.for("nestjs-durable:DURABLE_OPTIONS");
 
 // src/testing/in-memory-state-store.ts
 var InMemoryStateStore = class {
@@ -3560,6 +3586,13 @@ var InMemoryStateStore = class {
   attributeIndex = /* @__PURE__ */ new Map();
   /** Test/observability hook: how many candidate runs the last attribute query's index produced. */
   lastAttributeCandidates = 0;
+  /**
+  * Test/observability hook: how many checkpoint rows the LAST checkpoint read materialized (the rows
+  * actually returned to the caller). `listCheckpoints` returns all rows for the run; the targeted
+  * {@link getLatestCheckpointByName} / {@link listCheckpointsByNamePrefix} return only the matches —
+  * so this lets the benchmark contrast "fetch N, scan in JS" against "fetch the k that match".
+  */
+  lastCheckpointRowsRead = 0;
   key(runId, seq) {
     return `${runId}:${seq}`;
   }
@@ -3766,11 +3799,33 @@ var InMemoryStateStore = class {
     }));
   }
   async listCheckpoints(runId) {
-    return [
+    const rows = [
       ...this.checkpoints.values()
     ].filter((cp) => cp.runId === runId).sort((a, b) => a.seq - b.seq).map((cp) => ({
       ...cp
     }));
+    this.lastCheckpointRowsRead = rows.length;
+    return rows;
+  }
+  async getLatestCheckpointByName(runId, name) {
+    let latest;
+    for (const cp of this.checkpoints.values()) {
+      if (cp.runId !== runId || cp.name !== name) continue;
+      if (!latest || cp.seq > latest.seq) latest = cp;
+    }
+    this.lastCheckpointRowsRead = latest ? 1 : 0;
+    return latest ? {
+      ...latest
+    } : void 0;
+  }
+  async listCheckpointsByNamePrefix(runId, prefixes) {
+    const rows = [
+      ...this.checkpoints.values()
+    ].filter((cp) => cp.runId === runId && prefixes.some((p) => cp.name.startsWith(p))).sort((a, b) => a.seq - b.seq).map((cp) => ({
+      ...cp
+    }));
+    this.lastCheckpointRowsRead = rows.length;
+    return rows;
   }
 };