@dudousxd/nestjs-durable-store-prisma 0.19.1 → 0.21.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, RetentionPolicy, StepCheckpoint, RunQuery, RunFacetQuery, RunFacetRow, RunValueAxis, RunValueFacetOptions, RunValueFacetRow, ScheduleRecord, ScheduleQuery, CheckpointStat, CheckpointQuery, SignalWaiter, ChildWait } from '@dudousxd/nestjs-durable-core';
 
 interface RunRow {
     id: string;
@@ -83,8 +83,8 @@ interface Delegate<Row> {
         count: number;
     }>;
     count(args?: Args): Promise<number>;
-    /** Aggregate form — used only by `runFacets`, whose rows are `(status, origin, count)` cells, not
-     *  model rows, so the result type is stated at the call site rather than derived from `Row`. */
+    /** Aggregate form — used by the run facets and `checkpointStats`, whose rows are aggregate cells,
+     *  not model rows, so the result type is stated at the call site rather than derived from `Row`. */
     groupBy(args: Args): Promise<Record<string, unknown>[]>;
 }
 interface ScheduleRow {
@@ -138,6 +138,8 @@ declare class PrismaStateStore implements StateStore {
     pruneTerminalRuns(policy: RetentionPolicy, nowMs: number, limit: number): Promise<number>;
     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>;
@@ -170,7 +172,27 @@ declare class PrismaStateStore implements StateStore {
     listSchedules(query: ScheduleQuery): Promise<ScheduleRecord[]>;
     listCheckpoints(runId: string): Promise<StepCheckpoint[]>;
     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[]>;
+    /**
+     * One `groupBy(parallelGroup, status)` per {@link CheckpointNameKind}, each narrowed to its kind by
+     * a name-prefix predicate, run concurrently — Prisma cannot group by a `CASE`, so the kind is the
+     * `where` instead. `minEnqueuedAt` reads a NULL `enqueuedAt` as `startedAt` (as
+     * {@link fromCheckpointRow} does): a bucket whose non-null `enqueuedAt` count falls short of its
+     * row count has such rows, and only for those kinds is the NULL subset's `min(startedAt)` asked for.
+     *
+     * On SQLite `startsWith` is a case-insensitive `LIKE`, as in {@link listCheckpointsByNamePrefix};
+     * the kind prefixes are lower-case and wildcard-free, so only a step whose name starts with one of
+     * them in another case would be classified differently there.
+     */
+    checkpointStats(runId: string, opts?: {
+        group?: string | undefined;
+    }): Promise<CheckpointStat[]>;
+    /** `min(startedAt)` per `(parallelGroup, status)` over the rows whose `enqueuedAt` is NULL. */
+    private unenqueuedStartedAt;
+    /** {@link CheckpointQuery} as one `findMany`, in `seq` order, paged by `skip`/`take`. Ungrouped rows
+     *  are kept past `excludeGroups` explicitly: `NOT IN` alone drops a NULL `parallelGroup`. */
+    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, RetentionPolicy, StepCheckpoint, RunQuery, RunFacetQuery, RunFacetRow, RunValueAxis, RunValueFacetOptions, RunValueFacetRow, ScheduleRecord, ScheduleQuery, CheckpointStat, CheckpointQuery, SignalWaiter, ChildWait } from '@dudousxd/nestjs-durable-core';
 
 interface RunRow {
     id: string;
@@ -83,8 +83,8 @@ interface Delegate<Row> {
         count: number;
     }>;
     count(args?: Args): Promise<number>;
-    /** Aggregate form — used only by `runFacets`, whose rows are `(status, origin, count)` cells, not
-     *  model rows, so the result type is stated at the call site rather than derived from `Row`. */
+    /** Aggregate form — used by the run facets and `checkpointStats`, whose rows are aggregate cells,
+     *  not model rows, so the result type is stated at the call site rather than derived from `Row`. */
     groupBy(args: Args): Promise<Record<string, unknown>[]>;
 }
 interface ScheduleRow {
@@ -138,6 +138,8 @@ declare class PrismaStateStore implements StateStore {
     pruneTerminalRuns(policy: RetentionPolicy, nowMs: number, limit: number): Promise<number>;
     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>;
@@ -170,7 +172,27 @@ declare class PrismaStateStore implements StateStore {
     listSchedules(query: ScheduleQuery): Promise<ScheduleRecord[]>;
     listCheckpoints(runId: string): Promise<StepCheckpoint[]>;
     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[]>;
+    /**
+     * One `groupBy(parallelGroup, status)` per {@link CheckpointNameKind}, each narrowed to its kind by
+     * a name-prefix predicate, run concurrently — Prisma cannot group by a `CASE`, so the kind is the
+     * `where` instead. `minEnqueuedAt` reads a NULL `enqueuedAt` as `startedAt` (as
+     * {@link fromCheckpointRow} does): a bucket whose non-null `enqueuedAt` count falls short of its
+     * row count has such rows, and only for those kinds is the NULL subset's `min(startedAt)` asked for.
+     *
+     * On SQLite `startsWith` is a case-insensitive `LIKE`, as in {@link listCheckpointsByNamePrefix};
+     * the kind prefixes are lower-case and wildcard-free, so only a step whose name starts with one of
+     * them in another case would be classified differently there.
+     */
+    checkpointStats(runId: string, opts?: {
+        group?: string | undefined;
+    }): Promise<CheckpointStat[]>;
+    /** `min(startedAt)` per `(parallelGroup, status)` over the rows whose `enqueuedAt` is NULL. */
+    private unenqueuedStartedAt;
+    /** {@link CheckpointQuery} as one `findMany`, in `seq` order, paged by `skip`/`take`. Ungrouped rows
+     *  are kept past `excludeGroups` explicitly: `NOT IN` alone drops a NULL `parallelGroup`. */
+    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

@@ -234,6 +234,37 @@ var PrismaStateStore = class {
       update: data
     });
   }
+  async saveCheckpointIfPending(checkpoint) {
+    const { runId, seq, ...data } = toCheckpointData(checkpoint);
+    const { count } = await this.db.durableStepCheckpoint.updateMany({
+      where: {
+        runId,
+        seq,
+        status: "pending"
+      },
+      data
+    });
+    return count > 0;
+  }
+  async saveCheckpointsIfPending(checkpoints) {
+    if (checkpoints.length === 0) return [];
+    return this.db.$transaction(async (tx) => {
+      const wrote = [];
+      for (const checkpoint of checkpoints) {
+        const { runId, seq, ...data } = toCheckpointData(checkpoint);
+        const { count } = await tx.durableStepCheckpoint.updateMany({
+          where: {
+            runId,
+            seq,
+            status: "pending"
+          },
+          data
+        });
+        wrote.push(count > 0);
+      }
+      return wrote;
+    });
+  }
   async transaction(work) {
     return this.db.$transaction(async (tx) => work({
       raw: tx,
@@ -568,6 +599,21 @@ var PrismaStateStore = class {
     });
     return row ? fromCheckpointRow(row) : void 0;
   }
+  async countCheckpoints(runId, fromSeq, toSeq, statuses) {
+    if (statuses.length === 0) return 0;
+    return this.db.durableStepCheckpoint.count({
+      where: {
+        runId,
+        seq: {
+          gte: fromSeq,
+          lte: toSeq
+        },
+        status: {
+          in: statuses
+        }
+      }
+    });
+  }
   async listCheckpointsByNamePrefix(runId, prefixes) {
     if (prefixes.length === 0) return [];
     const rows = await this.db.durableStepCheckpoint.findMany({
@@ -583,6 +629,137 @@ var PrismaStateStore = class {
         seq: "asc"
       }
     });
+    return rows.filter((r) => prefixes.some((p) => r.name.startsWith(p))).map(fromCheckpointRow);
+  }
+  /**
+  * One `groupBy(parallelGroup, status)` per {@link CheckpointNameKind}, each narrowed to its kind by
+  * a name-prefix predicate, run concurrently — Prisma cannot group by a `CASE`, so the kind is the
+  * `where` instead. `minEnqueuedAt` reads a NULL `enqueuedAt` as `startedAt` (as
+  * {@link fromCheckpointRow} does): a bucket whose non-null `enqueuedAt` count falls short of its
+  * row count has such rows, and only for those kinds is the NULL subset's `min(startedAt)` asked for.
+  *
+  * On SQLite `startsWith` is a case-insensitive `LIKE`, as in {@link listCheckpointsByNamePrefix};
+  * the kind prefixes are lower-case and wildcard-free, so only a step whose name starts with one of
+  * them in another case would be classified differently there.
+  */
+  async checkpointStats(runId, opts) {
+    const scope = opts?.group === void 0 ? {
+      runId
+    } : {
+      runId,
+      parallelGroup: opts.group
+    };
+    const grouped = await Promise.all(NAME_KINDS.map(async ({ kind, where }) => ({
+      kind,
+      where,
+      rows: await this.db.durableStepCheckpoint.groupBy({
+        by: [
+          "parallelGroup",
+          "status"
+        ],
+        where: {
+          ...scope,
+          ...where
+        },
+        _count: {
+          _all: true,
+          enqueuedAt: true
+        },
+        _min: {
+          seq: true,
+          name: true,
+          enqueuedAt: true,
+          startedAt: true
+        },
+        _max: {
+          seq: true,
+          name: true,
+          startedAt: true,
+          finishedAt: true
+        },
+        _sum: {
+          attempts: true
+        }
+      })
+    })));
+    const stats = await Promise.all(grouped.map(async ({ kind, where, rows }) => {
+      const unenqueued = rows.some((r) => r._count.enqueuedAt < r._count._all) ? await this.unenqueuedStartedAt({
+        ...scope,
+        ...where
+      }) : /* @__PURE__ */ new Map();
+      return rows.map((r) => toCheckpointStat(kind, r, unenqueued));
+    }));
+    return stats.flat();
+  }
+  /** `min(startedAt)` per `(parallelGroup, status)` over the rows whose `enqueuedAt` is NULL. */
+  async unenqueuedStartedAt(where) {
+    const rows = await this.db.durableStepCheckpoint.groupBy({
+      by: [
+        "parallelGroup",
+        "status"
+      ],
+      where: {
+        ...where,
+        enqueuedAt: null
+      },
+      _min: {
+        startedAt: true
+      }
+    });
+    return new Map(rows.map((r) => [
+      bucketKey(r.parallelGroup, r.status),
+      r._min.startedAt
+    ]));
+  }
+  /** {@link CheckpointQuery} as one `findMany`, in `seq` order, paged by `skip`/`take`. Ungrouped rows
+  *  are kept past `excludeGroups` explicitly: `NOT IN` alone drops a NULL `parallelGroup`. */
+  async queryCheckpoints(runId, query) {
+    if (query.statuses?.length === 0 || query.namePrefixes?.length === 0) return [];
+    const and = [];
+    if (query.excludeGroups?.length) {
+      and.push({
+        OR: [
+          {
+            parallelGroup: null
+          },
+          {
+            parallelGroup: {
+              notIn: query.excludeGroups
+            }
+          }
+        ]
+      });
+    }
+    if (query.namePrefixes) {
+      and.push({
+        OR: query.namePrefixes.map((p) => ({
+          name: {
+            startsWith: p
+          }
+        }))
+      });
+    }
+    const rows = await this.db.durableStepCheckpoint.findMany({
+      where: {
+        runId,
+        ...query.group === void 0 ? {} : {
+          parallelGroup: query.group
+        },
+        ...query.statuses ? {
+          status: {
+            in: query.statuses
+          }
+        } : {},
+        ...and.length ? {
+          AND: and
+        } : {}
+      },
+      orderBy: {
+        seq: "asc"
+      },
+      skip: query.offset,
+      take: query.limit
+    });
     return rows.map(fromCheckpointRow);
   }
   async putSignalWaiter(waiter) {
@@ -630,7 +807,7 @@ var PrismaStateStore = class {
         }
       }
     });
-    return rows.map((r) => ({
+    return rows.filter((r) => r.token.startsWith(prefix)).map((r) => ({
       token: r.token,
       runId: r.runId,
       seq: r.seq,
@@ -920,6 +1097,69 @@ function fromRunRow(row) {
   };
 }
 __name(fromRunRow, "fromRunRow");
+var KIND_PREFIXES = [
+  [
+    "child",
+    "signal:child:"
+  ],
+  [
+    "folded",
+    "fan:"
+  ],
+  [
+    "spawn",
+    "spawn:"
+  ]
+];
+var NAME_KINDS = [
+  ...KIND_PREFIXES.map(([kind, prefix]) => ({
+    kind,
+    where: {
+      name: {
+        startsWith: prefix
+      }
+    }
+  })),
+  {
+    kind: "step",
+    where: {
+      NOT: KIND_PREFIXES.map(([, prefix]) => ({
+        name: {
+          startsWith: prefix
+        }
+      }))
+    }
+  }
+];
+function bucketKey(group, status) {
+  return JSON.stringify([
+    group,
+    status
+  ]);
+}
+__name(bucketKey, "bucketKey");
+function toCheckpointStat(nameKind, r, unenqueued) {
+  const fallback = unenqueued.get(bucketKey(r.parallelGroup, r.status));
+  const enqueued = r._min.enqueuedAt;
+  const minEnqueuedAt = enqueued && fallback ? enqueued < fallback ? enqueued : fallback : enqueued ?? fallback;
+  return {
+    group: r.parallelGroup,
+    status: r.status,
+    nameKind,
+    count: r._count._all,
+    minSeq: r._min.seq,
+    maxSeq: r._max.seq,
+    minName: r._min.name,
+    maxName: r._max.name,
+    // Every row has `enqueuedAt` or is in the NULL subset, so one of the two is set.
+    minEnqueuedAt,
+    minStartedAt: r._min.startedAt,
+    maxStartedAt: r._max.startedAt,
+    maxFinishedAt: r._max.finishedAt,
+    sumAttempts: Number(r._sum.attempts ?? 0)
+  };
+}
+__name(toCheckpointStat, "toCheckpointStat");
 function toCheckpointData(cp) {
   return {
     runId: cp.runId,