@dudousxd/nestjs-durable 0.42.1 → 0.43.1

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { WorkflowCtx, SearchAttributes, WorkflowClass, StepError, WorkflowRef, SingletonConfig, SearchAttributesSchema, StateStore, Transport, NamedTransport, ControlPlane, ScheduledWorkflow, RetentionPolicy, QueueConfig, AdmissionBackend, WorkflowInputOf, StartOptions, RunResult, RunGateway, WorkflowEngine, EntityHandler, DurableTopology, RunDetail, RunQuery, RunListItem, RunFacetQuery, RunFacetRow, GroupHealth, RunWaiting, EngineEvent, RunRequest, RunReply, StepInvocation, TenantEvent } from '@dudousxd/nestjs-durable-core';
+import { WorkflowCtx, SearchAttributes, WorkflowClass, StepError, WorkflowRef, SingletonConfig, SearchAttributesSchema, StateStore, Transport, NamedTransport, ControlPlane, ScheduledWorkflow, RetentionPolicy, QueueConfig, AdmissionBackend, WorkflowInputOf, StartOptions, RunResult, RunGateway, WorkflowEngine, EntityHandler, DurableTopology, RunDetail, RunQuery, RunListItem, RunFacetQuery, RunFacetRow, RunValueAxis, RunValueFacetOptions, RunValueFacetRow, GroupHealth, RunWaiting, EngineEvent, RunRequest, RunReply, StepInvocation, TenantEvent } from '@dudousxd/nestjs-durable-core';
 export { AttributeFilter, EngineEvent, InferSearchAttributes, RunDetail, RunGateway, RunListItem, RunQuery, RunStatus, RunWaiting, SearchAttributes, SearchAttributesSchema, StepCheckpoint, StepEvent, StepLogger, WorkflowCtx, WorkflowEngine, WorkflowHandler, WorkflowRun, readSearchAttributes } from '@dudousxd/nestjs-durable-core';
 import { z } from 'zod';
 import { ConcurrencyOption, StartRunDeps, RunRedisWorkerOptions, RunningWorker, DurableWorkerRuntime } from '@dudousxd/durable-worker';
@@ -900,6 +900,9 @@ declare class ProxyRunGateway implements RunGateway {
     listRuns(query: RunQuery): Promise<RunListItem[]>;
     /** Counted on the operator, over the same tenant-scoped predicates its `listRuns` reply obeys. */
     runFacets(query: RunFacetQuery): Promise<RunFacetRow[]>;
+    /** Enumerated on the operator, over the same tenant-scoped predicates its `listRuns` reply obeys —
+     *  so a tenant's pickers offer its own tenants/tags/attributes and never another's. */
+    runValueFacets(axis: RunValueAxis, query: RunFacetQuery, opts?: RunValueFacetOptions): Promise<RunValueFacetRow[]>;
     /** Round-trips to the operator, which scopes the result to this tenant's own `@<tenant>` groups. */
     workerHealth(): Promise<GroupHealth[]>;
     /** Bulk, one request for the whole id list (like `listRuns`, not one request per id). The operator
@@ -1000,6 +1003,14 @@ declare class StoreRunGateway implements RunGateway {
      * listing — correct, but the unbounded read this exists to avoid, so it is the last resort.
      */
     runFacets(query: RunFacetQuery): Promise<RunFacetRow[]>;
+    /**
+     * The distinct values behind a console's pickers, straight off the store's enumeration. A store
+     * without one answers `[]` rather than falling back to a listing: unlike the facet counts above —
+     * where a full listing is at least the RIGHT answer expensively — a picker built from an unbounded
+     * scan would be the same unbounded read on every keystroke, for a control whose free-text entry
+     * still works without it.
+     */
+    runValueFacets(axis: RunValueAxis, query: RunFacetQuery, opts?: RunValueFacetOptions): Promise<RunValueFacetRow[]>;
     /**
      * Bulk-resolve what each of `runIds` is currently parked on — for a consumer with its own filtered/
      * paginated run listing (e.g. "which of MY suspended runs are stuck at a breakpoint") without

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { WorkflowCtx, SearchAttributes, WorkflowClass, StepError, WorkflowRef, SingletonConfig, SearchAttributesSchema, StateStore, Transport, NamedTransport, ControlPlane, ScheduledWorkflow, RetentionPolicy, QueueConfig, AdmissionBackend, WorkflowInputOf, StartOptions, RunResult, RunGateway, WorkflowEngine, EntityHandler, DurableTopology, RunDetail, RunQuery, RunListItem, RunFacetQuery, RunFacetRow, GroupHealth, RunWaiting, EngineEvent, RunRequest, RunReply, StepInvocation, TenantEvent } from '@dudousxd/nestjs-durable-core';
+import { WorkflowCtx, SearchAttributes, WorkflowClass, StepError, WorkflowRef, SingletonConfig, SearchAttributesSchema, StateStore, Transport, NamedTransport, ControlPlane, ScheduledWorkflow, RetentionPolicy, QueueConfig, AdmissionBackend, WorkflowInputOf, StartOptions, RunResult, RunGateway, WorkflowEngine, EntityHandler, DurableTopology, RunDetail, RunQuery, RunListItem, RunFacetQuery, RunFacetRow, RunValueAxis, RunValueFacetOptions, RunValueFacetRow, GroupHealth, RunWaiting, EngineEvent, RunRequest, RunReply, StepInvocation, TenantEvent } from '@dudousxd/nestjs-durable-core';
 export { AttributeFilter, EngineEvent, InferSearchAttributes, RunDetail, RunGateway, RunListItem, RunQuery, RunStatus, RunWaiting, SearchAttributes, SearchAttributesSchema, StepCheckpoint, StepEvent, StepLogger, WorkflowCtx, WorkflowEngine, WorkflowHandler, WorkflowRun, readSearchAttributes } from '@dudousxd/nestjs-durable-core';
 import { z } from 'zod';
 import { ConcurrencyOption, StartRunDeps, RunRedisWorkerOptions, RunningWorker, DurableWorkerRuntime } from '@dudousxd/durable-worker';
@@ -900,6 +900,9 @@ declare class ProxyRunGateway implements RunGateway {
     listRuns(query: RunQuery): Promise<RunListItem[]>;
     /** Counted on the operator, over the same tenant-scoped predicates its `listRuns` reply obeys. */
     runFacets(query: RunFacetQuery): Promise<RunFacetRow[]>;
+    /** Enumerated on the operator, over the same tenant-scoped predicates its `listRuns` reply obeys —
+     *  so a tenant's pickers offer its own tenants/tags/attributes and never another's. */
+    runValueFacets(axis: RunValueAxis, query: RunFacetQuery, opts?: RunValueFacetOptions): Promise<RunValueFacetRow[]>;
     /** Round-trips to the operator, which scopes the result to this tenant's own `@<tenant>` groups. */
     workerHealth(): Promise<GroupHealth[]>;
     /** Bulk, one request for the whole id list (like `listRuns`, not one request per id). The operator
@@ -1000,6 +1003,14 @@ declare class StoreRunGateway implements RunGateway {
      * listing — correct, but the unbounded read this exists to avoid, so it is the last resort.
      */
     runFacets(query: RunFacetQuery): Promise<RunFacetRow[]>;
+    /**
+     * The distinct values behind a console's pickers, straight off the store's enumeration. A store
+     * without one answers `[]` rather than falling back to a listing: unlike the facet counts above —
+     * where a full listing is at least the RIGHT answer expensively — a picker built from an unbounded
+     * scan would be the same unbounded read on every keystroke, for a control whose free-text entry
+     * still works without it.
+     */
+    runValueFacets(axis: RunValueAxis, query: RunFacetQuery, opts?: RunValueFacetOptions): Promise<RunValueFacetRow[]>;
     /**
      * Bulk-resolve what each of `runIds` is currently parked on — for a consumer with its own filtered/
      * paginated run listing (e.g. "which of MY suspended runs are stuck at a breakpoint") without

package/dist/index.js

@@ -577,6 +577,9 @@ function unavailableRunGateway() {
     runFacets(_query) {
       return tenantGatewayUnavailable("runFacets");
     },
+    runValueFacets(_axis, _query, _opts) {
+      return tenantGatewayUnavailable("runValueFacets");
+    },
     waitingFor(_runIds) {
       return tenantGatewayUnavailable("waitingFor");
     },
@@ -1006,6 +1009,16 @@ var ProxyRunGateway = class {
       query
     });
   }
+  /** Enumerated on the operator, over the same tenant-scoped predicates its `listRuns` reply obeys —
+  *  so a tenant's pickers offer its own tenants/tags/attributes and never another's. */
+  runValueFacets(axis, query, opts) {
+    return this.request({
+      kind: "runValueFacets",
+      axis,
+      query,
+      opts
+    });
+  }
   /** Round-trips to the operator, which scopes the result to this tenant's own `@<tenant>` groups. */
   workerHealth() {
     return this.request({
@@ -1156,6 +1169,15 @@ var RetentionPoller = class {
   onModuleDestroy() {
     if (this.timer) clearInterval(this.timer);
   }
+  /**
+  * Prune one round.
+  *
+  * Never rejects, for the same reason {@link TimerPoller.poll} does not: it is awaited inside
+  * `onApplicationBootstrap` (so a rejection propagates into the host's `bootstrap()` and kills the
+  * process) and fired as `void` on the interval (so a rejection is an unhandled one, also fatal).
+  * Pruning history is the least urgent thing this package does — a `pruneTerminalRuns` that fails
+  * on a locked table must cost this sweep and nothing more.
+  */
   async sweep() {
     if (this.sweeping) return;
     const retention = this.options.retention;
@@ -1172,6 +1194,8 @@ var RetentionPoller = class {
           if (deleted < batchSize) break;
         }
       }
+    } catch (error) {
+      console.error("[nestjs-durable] retention sweep failed; retrying next interval:", error);
     } finally {
       this.sweeping = false;
     }
@@ -1235,6 +1259,19 @@ var RunRequestResponder = class {
         }
       };
     }
+    if (body.kind === "runValueFacets") {
+      const data = await this.gateway.runValueFacets(body.axis, {
+        ...body.query,
+        namespace: msg.tenant
+      }, body.opts);
+      return {
+        requestId: msg.requestId,
+        result: {
+          ok: true,
+          data
+        }
+      };
+    }
     if (body.kind === "workerHealth") {
       const all = await this.gateway.workerHealth();
       const data = all.filter((h) => h.group.endsWith(`@${msg.tenant}`));
@@ -1401,6 +1438,16 @@ var StoreRunGateway = class {
     })));
   }
   /**
+  * The distinct values behind a console's pickers, straight off the store's enumeration. A store
+  * without one answers `[]` rather than falling back to a listing: unlike the facet counts above —
+  * where a full listing is at least the RIGHT answer expensively — a picker built from an unbounded
+  * scan would be the same unbounded read on every keystroke, for a control whose free-text entry
+  * still works without it.
+  */
+  async runValueFacets(axis, query, opts) {
+    return this.store.runValueFacets?.(axis, query, opts) ?? [];
+  }
+  /**
   * Bulk-resolve what each of `runIds` is currently parked on — for a consumer with its own filtered/
   * paginated run listing (e.g. "which of MY suspended runs are stuck at a breakpoint") without
   * re-deriving `listRuns`' waiter scan or querying `durable_step_checkpoints` directly. Mirrors
@@ -1543,7 +1590,11 @@ var TimerPoller = class {
   }
   async onApplicationBootstrap() {
     if (!isDrivingOperator(this.options)) return;
-    this.unsubscribeEnqueued = this.engine.onEnqueued((runId) => void this.engine.runOne(runId));
+    this.unsubscribeEnqueued = this.engine.onEnqueued((runId) => {
+      void this.engine.runOne(runId).catch((error) => {
+        console.error(`[nestjs-durable] could not run enqueued run ${runId}:`, error);
+      });
+    });
     await this.poll();
     const intervalMs = this.options.timerPollMs ?? 1e3;
     if (intervalMs > 0) {
@@ -1555,22 +1606,45 @@ var TimerPoller = class {
     if (this.timer) clearInterval(this.timer);
     this.unsubscribeEnqueued?.();
   }
+  /**
+  * One sweep of the engine's recovery work.
+  *
+  * **This method never rejects, and that is a hard requirement rather than defensiveness.** It has
+  * exactly two callers and a rejection out of either one kills the process: on boot it is awaited
+  * inside `onApplicationBootstrap`, so the rejection propagates through `NestApplication.init()`
+  * into the host's `bootstrap()`; on the interval it is a fire-and-forget `void`, so it surfaces as
+  * an unhandled rejection. Both are fatal, and both re-occur on the next boot with the same state,
+  * so a single unrecoverable run crash-loops every worker in the deployment — taking down every
+  * other workflow with it. A poll that goes wrong must cost this tick, not the pod.
+  *
+  * Each sweep is isolated separately because they are independent: a store that fails
+  * `recoverIncomplete` says nothing about whether durable timers should still fire, and skipping
+  * the rest of the tick would silently widen one subsystem's outage into all of them.
+  */
   async poll() {
     if (this.polling) return;
     this.polling = true;
     try {
-      await this.engine.runPending();
-      await this.engine.recoverIncomplete();
-      await this.engine.resumeDueTimers();
-      await this.engine.sweepTimeouts();
+      await this.sweep("runPending", () => this.engine.runPending());
+      await this.sweep("recoverIncomplete", () => this.engine.recoverIncomplete());
+      await this.sweep("resumeDueTimers", () => this.engine.resumeDueTimers());
+      await this.sweep("sweepTimeouts", () => this.engine.sweepTimeouts());
       const schedules = this.options.schedules;
       if (schedules && schedules.length > 0) {
-        await runSchedules(this.engine, schedules, Date.now());
+        await this.sweep("schedules", () => runSchedules(this.engine, schedules, Date.now()));
       }
     } finally {
       this.polling = false;
     }
   }
+  /** Run one sweep, absorbing and reporting its failure — see {@link poll}. */
+  async sweep(name, run) {
+    try {
+      await run();
+    } catch (error) {
+      console.error(`[nestjs-durable] timer poll: ${name} failed; continuing:`, error);
+    }
+  }
 };
 TimerPoller = _ts_decorate9([
   Injectable9(),