@dudousxd/nestjs-durable-store-drizzle 0.20.0 → 0.22.0

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { StateStore, WorkflowRun, RetentionPolicy, StepCheckpoint, RunQuery, RunFacetQuery, RunFacetRow, RunValueAxis, RunValueFacetOptions, RunValueFacetRow, ScheduleRecord, ScheduleQuery, SignalWaiter, ChildWait } from '@dudousxd/nestjs-durable-core';
+import { StateStore, WorkflowRun, RunStatus, RetentionPolicy, StepCheckpoint, RunQuery, RunFacetQuery, RunFacetRow, RunValueAxis, RunValueFacetOptions, RunValueFacetRow, ScheduleRecord, ScheduleQuery, CheckpointStat, CheckpointQuery, SignalWaiter, ChildWait } from '@dudousxd/nestjs-durable-core';
 import * as drizzle_orm_sqlite_core from 'drizzle-orm/sqlite-core';
 import { BaseSQLiteDatabase } from 'drizzle-orm/sqlite-core';
 
@@ -14,6 +14,7 @@ declare class DrizzleStateStore implements StateStore {
     tryAdmitSingleton(runId: string, tag: string, workflow: string, limit: number, retryWakeAt?: number): Promise<boolean>;
     createRun(run: WorkflowRun): Promise<void>;
     updateRun(runId: string, inputPatch: Partial<WorkflowRun>): Promise<void>;
+    updateRunIf(runId: string, expectedStatuses: RunStatus[], inputPatch: Partial<WorkflowRun>): Promise<boolean>;
     /** Rewrite a run's normalized attribute rows: delete the old set, insert the current one. Mirrors
      *  the in-memory store's reindex so the side-table always reflects the run's live searchAttributes. */
     private reindexAttributes;
@@ -24,6 +25,7 @@ declare class DrizzleStateStore implements StateStore {
     getCheckpoint(runId: string, seq: number): Promise<StepCheckpoint | null>;
     saveCheckpoint(checkpoint: StepCheckpoint): Promise<void>;
     saveCheckpointIfPending(checkpoint: StepCheckpoint): Promise<boolean>;
+    saveCheckpointsIfPending(checkpoints: StepCheckpoint[]): Promise<boolean[]>;
     transaction<T>(work: (tx: {
         raw: unknown;
         saveCheckpoint: (cp: StepCheckpoint) => Promise<void>;
@@ -31,6 +33,7 @@ declare class DrizzleStateStore implements StateStore {
     /** Recovery on boot. Namespace-scoped: a worker re-drives only its own tenant's crashed runs.
      *  `and(...)` drops an `undefined` predicate, so an unscoped caller recovers every namespace. */
     listIncompleteRuns(namespace?: string): Promise<WorkflowRun[]>;
+    listOrphanedRuns(nowMs: number, limit: number, namespace?: string): Promise<WorkflowRun[]>;
     /** Dispatch pick-up. Namespace-scoped — without it a worker serving one tenant drains another
      *  tenant's queue, and the `limit` makes it worse: foreign runs consume the FIFO budget. */
     listPendingRuns(limit: number, namespace?: string): Promise<WorkflowRun[]>;
@@ -67,6 +70,14 @@ declare class DrizzleStateStore implements StateStore {
     getLatestCheckpointByName(runId: string, name: string): Promise<StepCheckpoint | undefined>;
     countCheckpoints(runId: string, fromSeq: number, toSeq: number, statuses: StepCheckpoint['status'][]): Promise<number>;
     listCheckpointsByNamePrefix(runId: string, prefixes: string[]): Promise<StepCheckpoint[]>;
+    /** {@link StateStore.checkpointStats}: one `GROUP BY parallel_group, status, name_kind` over the
+     *  run's checkpoints, so a wide fan comes back as a few bucket rows instead of every member. */
+    checkpointStats(runId: string, opts?: {
+        group?: string | undefined;
+    }): Promise<CheckpointStat[]>;
+    /** {@link StateStore.queryCheckpoints}: the run's checkpoints narrowed in SQL, in `seq` order and
+     *  paged there, so reading one page of a wide fan never loads the rest of it. */
+    queryCheckpoints(runId: string, query: CheckpointQuery): Promise<StepCheckpoint[]>;
     putSignalWaiter(waiter: SignalWaiter): Promise<void>;
     takeSignalWaiter(token: string): Promise<SignalWaiter | null>;
     listSignalWaiters(prefix: string): Promise<SignalWaiter[]>;

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { StateStore, WorkflowRun, RetentionPolicy, StepCheckpoint, RunQuery, RunFacetQuery, RunFacetRow, RunValueAxis, RunValueFacetOptions, RunValueFacetRow, ScheduleRecord, ScheduleQuery, SignalWaiter, ChildWait } from '@dudousxd/nestjs-durable-core';
+import { StateStore, WorkflowRun, RunStatus, RetentionPolicy, StepCheckpoint, RunQuery, RunFacetQuery, RunFacetRow, RunValueAxis, RunValueFacetOptions, RunValueFacetRow, ScheduleRecord, ScheduleQuery, CheckpointStat, CheckpointQuery, SignalWaiter, ChildWait } from '@dudousxd/nestjs-durable-core';
 import * as drizzle_orm_sqlite_core from 'drizzle-orm/sqlite-core';
 import { BaseSQLiteDatabase } from 'drizzle-orm/sqlite-core';
 
@@ -14,6 +14,7 @@ declare class DrizzleStateStore implements StateStore {
     tryAdmitSingleton(runId: string, tag: string, workflow: string, limit: number, retryWakeAt?: number): Promise<boolean>;
     createRun(run: WorkflowRun): Promise<void>;
     updateRun(runId: string, inputPatch: Partial<WorkflowRun>): Promise<void>;
+    updateRunIf(runId: string, expectedStatuses: RunStatus[], inputPatch: Partial<WorkflowRun>): Promise<boolean>;
     /** Rewrite a run's normalized attribute rows: delete the old set, insert the current one. Mirrors
      *  the in-memory store's reindex so the side-table always reflects the run's live searchAttributes. */
     private reindexAttributes;
@@ -24,6 +25,7 @@ declare class DrizzleStateStore implements StateStore {
     getCheckpoint(runId: string, seq: number): Promise<StepCheckpoint | null>;
     saveCheckpoint(checkpoint: StepCheckpoint): Promise<void>;
     saveCheckpointIfPending(checkpoint: StepCheckpoint): Promise<boolean>;
+    saveCheckpointsIfPending(checkpoints: StepCheckpoint[]): Promise<boolean[]>;
     transaction<T>(work: (tx: {
         raw: unknown;
         saveCheckpoint: (cp: StepCheckpoint) => Promise<void>;
@@ -31,6 +33,7 @@ declare class DrizzleStateStore implements StateStore {
     /** Recovery on boot. Namespace-scoped: a worker re-drives only its own tenant's crashed runs.
      *  `and(...)` drops an `undefined` predicate, so an unscoped caller recovers every namespace. */
     listIncompleteRuns(namespace?: string): Promise<WorkflowRun[]>;
+    listOrphanedRuns(nowMs: number, limit: number, namespace?: string): Promise<WorkflowRun[]>;
     /** Dispatch pick-up. Namespace-scoped — without it a worker serving one tenant drains another
      *  tenant's queue, and the `limit` makes it worse: foreign runs consume the FIFO budget. */
     listPendingRuns(limit: number, namespace?: string): Promise<WorkflowRun[]>;
@@ -67,6 +70,14 @@ declare class DrizzleStateStore implements StateStore {
     getLatestCheckpointByName(runId: string, name: string): Promise<StepCheckpoint | undefined>;
     countCheckpoints(runId: string, fromSeq: number, toSeq: number, statuses: StepCheckpoint['status'][]): Promise<number>;
     listCheckpointsByNamePrefix(runId: string, prefixes: string[]): Promise<StepCheckpoint[]>;
+    /** {@link StateStore.checkpointStats}: one `GROUP BY parallel_group, status, name_kind` over the
+     *  run's checkpoints, so a wide fan comes back as a few bucket rows instead of every member. */
+    checkpointStats(runId: string, opts?: {
+        group?: string | undefined;
+    }): Promise<CheckpointStat[]>;
+    /** {@link StateStore.queryCheckpoints}: the run's checkpoints narrowed in SQL, in `seq` order and
+     *  paged there, so reading one page of a wide fan never loads the rest of it. */
+    queryCheckpoints(runId: string, query: CheckpointQuery): Promise<StepCheckpoint[]>;
     putSignalWaiter(waiter: SignalWaiter): Promise<void>;
     takeSignalWaiter(token: string): Promise<SignalWaiter | null>;
     listSignalWaiters(prefix: string): Promise<SignalWaiter[]>;

package/dist/index.js

@@ -3,7 +3,7 @@ var __name = (target, value) => __defProp(target, "name", { value, configurable:
 
 // src/drizzle-state-store.ts
 import { RUN_VALUE_FACET_SCAN, SINGLETON_ACTIVE_STATUSES, TERMINAL_RUN_STATUSES, attributePredicateOperands, axisIsRunColumn, clearTerminalSingletonAdmission, mergeRunFacetRows, mergeRunValueFacetRows, normalizeAttributeRows, parseDuration, runValueFacetsFromRuns, singletonAdmissionDenialPatch, singletonAdmissionTags } from "@dudousxd/nestjs-durable-core";
-import { and, asc, desc, eq, exists, getTableColumns, gte, inArray, isNotNull, isNull, like, lt, lte, or, sql } from "drizzle-orm";
+import { and, asc, desc, eq, exists, getTableColumns, gte, inArray, isNotNull, isNull, like, lt, lte, notInArray, or, sql } from "drizzle-orm";
 
 // src/schema.ts
 import { getTableName } from "drizzle-orm";
@@ -119,7 +119,13 @@ var stepCheckpoints = sqliteTable("durable_step_checkpoints", {
       t.runId,
       t.seq
     ]
-  })
+  }),
+  // A run detail reads one fan at a time (`checkpointStats({ group })`, `queryCheckpoints({ group })`
+  // paged by seq). Like every index here, an already-deployed database needs it run by hand:
+  //
+  //     CREATE INDEX IF NOT EXISTS durable_step_checkpoints_group_idx
+  //       ON durable_step_checkpoints (run_id, parallel_group, seq);
+  index("durable_step_checkpoints_group_idx").on(t.runId, t.parallelGroup, t.seq)
 ]);
 var runAttributes = sqliteTable("durable_run_attributes", {
   runId: text("run_id").notNull(),
@@ -266,6 +272,21 @@ var DrizzleStateStore = class {
     if (Object.keys(row).length) await this.db.update(workflowRuns).set(row).where(eq(workflowRuns.id, runId));
     if ("searchAttributes" in patch) await this.reindexAttributes(runId, patch.searchAttributes);
   }
+  async updateRunIf(runId, expectedStatuses, inputPatch) {
+    if (expectedStatuses.length === 0) return false;
+    const patch = inputPatch.status && TERMINAL_RUN_STATUSES.includes(inputPatch.status) ? await clearTerminalSingletonAdmission(runId, inputPatch, (id) => this.getRun(id)) : inputPatch;
+    const row = toRunPatch(patch);
+    if (!Object.keys(row).length) {
+      const current = await this.getRun(runId);
+      if (!current || !expectedStatuses.includes(current.status)) return false;
+    } else {
+      const result = await this.db.update(workflowRuns).set(row).where(and(eq(workflowRuns.id, runId), inArray(workflowRuns.status, expectedStatuses)));
+      const { changes, rowsAffected } = result;
+      if ((changes ?? rowsAffected ?? 0) === 0) return false;
+    }
+    if ("searchAttributes" in patch) await this.reindexAttributes(runId, patch.searchAttributes);
+    return true;
+  }
   /** Rewrite a run's normalized attribute rows: delete the old set, insert the current one. Mirrors
   *  the in-memory store's reindex so the side-table always reflects the run's live searchAttributes. */
   async reindexAttributes(runId, attributes) {
@@ -341,6 +362,35 @@ var DrizzleStateStore = class {
     const { changes, rowsAffected } = result;
     return (changes ?? rowsAffected ?? 0) > 0;
   }
+  async saveCheckpointsIfPending(checkpoints) {
+    if (checkpoints.length === 0) return [];
+    const wrote = [];
+    await this.db.transaction((tx) => {
+      const update = /* @__PURE__ */ __name((checkpoint) => {
+        const { runId, seq, ...set } = toCheckpointRow(checkpoint);
+        return tx.update(stepCheckpoints).set(set).where(and(eq(stepCheckpoints.runId, runId), eq(stepCheckpoints.seq, seq), eq(stepCheckpoints.status, "pending"))).run();
+      }, "update");
+      const record = /* @__PURE__ */ __name((result) => {
+        const { changes, rowsAffected } = result;
+        wrote.push((changes ?? rowsAffected ?? 0) > 0);
+      }, "record");
+      const runFrom = /* @__PURE__ */ __name((from) => {
+        for (let i = from; i < checkpoints.length; i += 1) {
+          const result = update(checkpoints[i]);
+          if (result instanceof Promise) {
+            return result.then((r) => {
+              record(r);
+              return runFrom(i + 1);
+            });
+          }
+          record(result);
+        }
+        return void 0;
+      }, "runFrom");
+      return runFrom(0);
+    });
+    return wrote;
+  }
   async transaction(work) {
     return this.db.transaction(async (tx) => work({
       raw: tx,
@@ -365,6 +415,14 @@ var DrizzleStateStore = class {
     ]), namespaceFilter(namespace)));
     return rows.map(fromRunRow);
   }
+  async listOrphanedRuns(nowMs, limit, namespace) {
+    if (limit <= 0) return [];
+    const rows = await this.db.select().from(workflowRuns).where(and(inArray(workflowRuns.status, [
+      "running",
+      "cancelling"
+    ]), or(isNull(workflowRuns.lockedUntil), lte(workflowRuns.lockedUntil, nowMs)), namespaceFilter(namespace))).orderBy(asc(workflowRuns.createdAt)).limit(limit);
+    return rows.map(fromRunRow);
+  }
   /** Dispatch pick-up. Namespace-scoped — without it a worker serving one tenant drains another
   *  tenant's queue, and the `limit` makes it worse: foreign runs consume the FIFO budget. */
   async listPendingRuns(limit, namespace) {
@@ -543,6 +601,61 @@ var DrizzleStateStore = class {
   async listCheckpointsByNamePrefix(runId, prefixes) {
     if (prefixes.length === 0) return [];
     const rows = await this.db.select().from(stepCheckpoints).where(and(eq(stepCheckpoints.runId, runId), or(...prefixes.map((p) => like(stepCheckpoints.name, `${p}%`))))).orderBy(asc(stepCheckpoints.seq));
+    return rows.filter((r) => prefixes.some((p) => r.name.startsWith(p))).map(fromCheckpointRow);
+  }
+  /** {@link StateStore.checkpointStats}: one `GROUP BY parallel_group, status, name_kind` over the
+  *  run's checkpoints, so a wide fan comes back as a few bucket rows instead of every member. */
+  async checkpointStats(runId, opts) {
+    const c = stepCheckpoints;
+    const nameKind = sql`CASE
+      WHEN substr(${c.name}, 1, 13) = 'signal:child:' THEN 'child'
+      WHEN substr(${c.name}, 1, 4) = 'fan:' THEN 'folded'
+      WHEN substr(${c.name}, 1, 6) = 'spawn:' THEN 'spawn'
+      ELSE 'step' END`.as("name_kind");
+    const rows = await this.db.select({
+      group: c.parallelGroup,
+      status: c.status,
+      nameKind,
+      count: sql`count(*)`,
+      minSeq: sql`min(${c.seq})`,
+      maxSeq: sql`max(${c.seq})`,
+      minName: sql`min(${c.name})`,
+      maxName: sql`max(${c.name})`,
+      minEnqueuedAt: sql`min(coalesce(${c.enqueuedAt}, ${c.startedAt}))`,
+      minStartedAt: sql`min(${c.startedAt})`,
+      maxStartedAt: sql`max(${c.startedAt})`,
+      maxFinishedAt: sql`max(${c.finishedAt})`,
+      sumAttempts: sql`sum(${c.attempts})`
+    }).from(c).where(and(eq(c.runId, runId), opts?.group !== void 0 ? eq(c.parallelGroup, opts.group) : void 0)).groupBy(c.parallelGroup, c.status, sql`name_kind`);
+    return rows.map((r) => ({
+      group: r.group ?? null,
+      status: r.status,
+      nameKind: r.nameKind,
+      count: Number(r.count),
+      minSeq: Number(r.minSeq),
+      maxSeq: Number(r.maxSeq),
+      minName: r.minName,
+      maxName: r.maxName,
+      minEnqueuedAt: new Date(Number(r.minEnqueuedAt)),
+      minStartedAt: new Date(Number(r.minStartedAt)),
+      maxStartedAt: new Date(Number(r.maxStartedAt)),
+      maxFinishedAt: new Date(Number(r.maxFinishedAt)),
+      sumAttempts: Number(r.sumAttempts)
+    }));
+  }
+  /** {@link StateStore.queryCheckpoints}: the run's checkpoints narrowed in SQL, in `seq` order and
+  *  paged there, so reading one page of a wide fan never loads the rest of it. */
+  async queryCheckpoints(runId, query) {
+    if (query.statuses?.length === 0 || query.namePrefixes?.length === 0) return [];
+    const c = stepCheckpoints;
+    const rows = await this.db.select().from(c).where(and(
+      eq(c.runId, runId),
+      query.group !== void 0 ? eq(c.parallelGroup, query.group) : void 0,
+      // `NOT IN` is never true for a NULL group, so ungrouped rows are kept explicitly.
+      query.excludeGroups?.length ? or(isNull(c.parallelGroup), notInArray(c.parallelGroup, query.excludeGroups)) : void 0,
+      query.statuses ? inArray(c.status, query.statuses) : void 0,
+      query.namePrefixes ? or(...query.namePrefixes.map((p) => sql`substr(${c.name}, 1, length(${p})) = ${p}`)) : void 0
+    )).orderBy(asc(c.seq)).limit(query.limit ?? Number.MAX_SAFE_INTEGER).offset(query.offset ?? 0);
     return rows.map(fromCheckpointRow);
   }
   async putSignalWaiter(waiter) {
@@ -574,7 +687,7 @@ var DrizzleStateStore = class {
   }
   async listSignalWaiters(prefix) {
     const rows = await this.db.select().from(signalWaiters).where(like(signalWaiters.token, `${prefix}%`));
-    return rows.map((r) => ({
+    return rows.filter((r) => r.token.startsWith(prefix)).map((r) => ({
       token: r.token,
       runId: r.runId,
       seq: r.seq,