@dudousxd/nestjs-durable 0.49.0 → 0.51.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { WorkflowCtx, SearchAttributes, WorkflowClass, StandardSchemaV1, StepError, OnErrorInput, WorkflowRef, SingletonConfig, ConcurrencyConfig, SearchAttributesSchema, StateStore, Transport, NamedTransport, ControlPlane, ScheduledWorkflow, RetentionPolicy, QueueConfig, AdmissionBackend, WorkflowInputOf, StartOptions, RunResult, RunGateway, WorkflowEngine, EntityHandler, DurableTopology, RunDetailOptions, RunDetail, FanPageQuery, FanPage, RunQuery, RunListItem, RunFacetQuery, RunFacetRow, RunValueAxis, RunValueFacetOptions, RunValueFacetRow, GroupHealth, RunWaiting, EngineEvent, RunRequest, RunReply, StepInvocation, WorkflowRun, TenantEvent } from '@dudousxd/nestjs-durable-core';
-export { AttributeFilter, DynamicWorkflowCtx, EngineEvent, InferSearchAttributes, OnErrorInput, RunDetail, RunGateway, RunListItem, RunQuery, RunStatus, RunWaiting, SearchAttributes, SearchAttributesSchema, StepCheckpoint, StepEvent, StepLogger, WorkflowCtx, WorkflowEngine, WorkflowHandler, WorkflowRun, readSearchAttributes } from '@dudousxd/nestjs-durable-core';
+import { WorkflowCtx, SearchAttributes, WorkflowClass, StandardSchemaV1, StepError, OnErrorInput, WorkflowRef, SingletonConfig, ConcurrencyConfig, SearchAttributesSchema, StateStore, Transport, NamedTransport, ControlPlane, StalledRunInfo, ScheduledWorkflow, RetentionPolicy, QueueConfig, AdmissionBackend, WorkflowInputOf, StartOptions, RunResult, RunGateway, WorkflowEngine, EntityHandler, DurableTopology, RunDetailOptions, RunDetail, FanPageQuery, FanPage, RunQuery, RunListItem, RunFacetQuery, RunFacetRow, RunValueAxis, RunValueFacetOptions, RunValueFacetRow, GroupHealth, RunWaiting, EngineEvent, RunRequest, RunReply, StepInvocation, WorkflowRun, TenantEvent } from '@dudousxd/nestjs-durable-core';
+export { AttributeFilter, DynamicWorkflowCtx, EngineEvent, InferSearchAttributes, OnErrorInput, RunDetail, RunGateway, RunListItem, RunQuery, RunSchedulesOptions, RunStatus, RunWaiting, ScheduledWorkflow, SearchAttributes, SearchAttributesSchema, StepCheckpoint, StepEvent, StepLogger, WorkflowCtx, WorkflowEngine, WorkflowHandler, WorkflowRun, prevCronFireMs, readSearchAttributes, runSchedules, scheduleRunIdAt, scheduledRunId } from '@dudousxd/nestjs-durable-core';
 import { z } from 'zod';
 import { ConcurrencyOption, StartRunDeps, RunRedisWorkerOptions, RunningWorker, DurableWorkerRuntime } from '@dudousxd/durable-worker';
 import { DynamicModule, InjectionToken, OnModuleInit, OnApplicationBootstrap, OnApplicationShutdown, Provider } from '@nestjs/common';
@@ -242,14 +242,16 @@ interface WorkflowOptions {
     inputSchema?: IoSchema;
     /**
      * A custom check at `start` (throw to reject) for a rule a schema can't express — a cross-field
-     * invariant, an async lookup. It sees the input as it was sent, and runs after `input` parses.
+     * invariant, an async lookup. It runs after `input` parses and receives the parsed value (the input
+     * as sent when there is no `input` schema).
      */
     validateInput?: (input: unknown) => void | Promise<void>;
     /**
      * Validate this workflow's {@link WorkflowCtx.upsertSearchAttributes} writes against a **Standard
      * Schema** (https://standardschema.dev — zod 3.24+, valibot, arktype, …). `ctx.upsertSearchAttributes`
      * validates the MERGED result (existing attributes shallow-merged with the patch) on every call —
-     * an invalid merge throws, naming this workflow, the offending key(s), and the schema's issues. The
+     * an invalid merge throws a `SchemaValidationError` (code `schema_validation`) naming this workflow,
+     * with the schema's issues. The
      * schema's inferred output must be search-attribute-shaped (flat `string`/`number`/`boolean` values
      * only) — a schema whose output has a nested object/array is a compile-time error here. Omit for
      * the prior unvalidated behavior.
@@ -597,6 +599,19 @@ interface DurableModuleOptions {
      * See `WorkflowEngineDeps.reconcileMs`. Operator only.
      */
     reconcileMs?: number;
+    /**
+     * Idle time (ms) before a stranded in-flight run is reported to {@link onStalled} listeners.
+     * Defaults to 900000 (15 min), floored at 60000. See `WorkflowEngineDeps.stalledAfterMs`.
+     * Operator only.
+     */
+    stalledAfterMs?: number;
+    /**
+     * Pager hook for stranded runs, registered on the engine as `engine.onStalled(...)`: a run
+     * suspended with no wake timer, or parked on an old pending remote step nothing is leasing. The
+     * timer poller sweeps once a minute and reports each stranded episode once per instance.
+     * Equivalent to calling `engine.onStalled` from a provider; only a DRIVING operator sweeps.
+     */
+    onStalled?: (info: StalledRunInfo) => void;
     /**
      * The most due timers one timer-poll pass loads and drives, most overdue first, so a wave of
      * thousands of due runs is worked through in batches. Defaults to 500; a non-finite or sub-1 value

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { WorkflowCtx, SearchAttributes, WorkflowClass, StandardSchemaV1, StepError, OnErrorInput, WorkflowRef, SingletonConfig, ConcurrencyConfig, SearchAttributesSchema, StateStore, Transport, NamedTransport, ControlPlane, ScheduledWorkflow, RetentionPolicy, QueueConfig, AdmissionBackend, WorkflowInputOf, StartOptions, RunResult, RunGateway, WorkflowEngine, EntityHandler, DurableTopology, RunDetailOptions, RunDetail, FanPageQuery, FanPage, RunQuery, RunListItem, RunFacetQuery, RunFacetRow, RunValueAxis, RunValueFacetOptions, RunValueFacetRow, GroupHealth, RunWaiting, EngineEvent, RunRequest, RunReply, StepInvocation, WorkflowRun, TenantEvent } from '@dudousxd/nestjs-durable-core';
-export { AttributeFilter, DynamicWorkflowCtx, EngineEvent, InferSearchAttributes, OnErrorInput, RunDetail, RunGateway, RunListItem, RunQuery, RunStatus, RunWaiting, SearchAttributes, SearchAttributesSchema, StepCheckpoint, StepEvent, StepLogger, WorkflowCtx, WorkflowEngine, WorkflowHandler, WorkflowRun, readSearchAttributes } from '@dudousxd/nestjs-durable-core';
+import { WorkflowCtx, SearchAttributes, WorkflowClass, StandardSchemaV1, StepError, OnErrorInput, WorkflowRef, SingletonConfig, ConcurrencyConfig, SearchAttributesSchema, StateStore, Transport, NamedTransport, ControlPlane, StalledRunInfo, ScheduledWorkflow, RetentionPolicy, QueueConfig, AdmissionBackend, WorkflowInputOf, StartOptions, RunResult, RunGateway, WorkflowEngine, EntityHandler, DurableTopology, RunDetailOptions, RunDetail, FanPageQuery, FanPage, RunQuery, RunListItem, RunFacetQuery, RunFacetRow, RunValueAxis, RunValueFacetOptions, RunValueFacetRow, GroupHealth, RunWaiting, EngineEvent, RunRequest, RunReply, StepInvocation, WorkflowRun, TenantEvent } from '@dudousxd/nestjs-durable-core';
+export { AttributeFilter, DynamicWorkflowCtx, EngineEvent, InferSearchAttributes, OnErrorInput, RunDetail, RunGateway, RunListItem, RunQuery, RunSchedulesOptions, RunStatus, RunWaiting, ScheduledWorkflow, SearchAttributes, SearchAttributesSchema, StepCheckpoint, StepEvent, StepLogger, WorkflowCtx, WorkflowEngine, WorkflowHandler, WorkflowRun, prevCronFireMs, readSearchAttributes, runSchedules, scheduleRunIdAt, scheduledRunId } from '@dudousxd/nestjs-durable-core';
 import { z } from 'zod';
 import { ConcurrencyOption, StartRunDeps, RunRedisWorkerOptions, RunningWorker, DurableWorkerRuntime } from '@dudousxd/durable-worker';
 import { DynamicModule, InjectionToken, OnModuleInit, OnApplicationBootstrap, OnApplicationShutdown, Provider } from '@nestjs/common';
@@ -242,14 +242,16 @@ interface WorkflowOptions {
     inputSchema?: IoSchema;
     /**
      * A custom check at `start` (throw to reject) for a rule a schema can't express — a cross-field
-     * invariant, an async lookup. It sees the input as it was sent, and runs after `input` parses.
+     * invariant, an async lookup. It runs after `input` parses and receives the parsed value (the input
+     * as sent when there is no `input` schema).
      */
     validateInput?: (input: unknown) => void | Promise<void>;
     /**
      * Validate this workflow's {@link WorkflowCtx.upsertSearchAttributes} writes against a **Standard
      * Schema** (https://standardschema.dev — zod 3.24+, valibot, arktype, …). `ctx.upsertSearchAttributes`
      * validates the MERGED result (existing attributes shallow-merged with the patch) on every call —
-     * an invalid merge throws, naming this workflow, the offending key(s), and the schema's issues. The
+     * an invalid merge throws a `SchemaValidationError` (code `schema_validation`) naming this workflow,
+     * with the schema's issues. The
      * schema's inferred output must be search-attribute-shaped (flat `string`/`number`/`boolean` values
      * only) — a schema whose output has a nested object/array is a compile-time error here. Omit for
      * the prior unvalidated behavior.
@@ -597,6 +599,19 @@ interface DurableModuleOptions {
      * See `WorkflowEngineDeps.reconcileMs`. Operator only.
      */
     reconcileMs?: number;
+    /**
+     * Idle time (ms) before a stranded in-flight run is reported to {@link onStalled} listeners.
+     * Defaults to 900000 (15 min), floored at 60000. See `WorkflowEngineDeps.stalledAfterMs`.
+     * Operator only.
+     */
+    stalledAfterMs?: number;
+    /**
+     * Pager hook for stranded runs, registered on the engine as `engine.onStalled(...)`: a run
+     * suspended with no wake timer, or parked on an old pending remote step nothing is leasing. The
+     * timer poller sweeps once a minute and reports each stranded episode once per instance.
+     * Equivalent to calling `engine.onStalled` from a provider; only a DRIVING operator sweeps.
+     */
+    onStalled?: (info: StalledRunInfo) => void;
     /**
      * The most due timers one timer-poll pass loads and drives, most overdue first, so a wave of
      * thousands of due runs is worked through in batches. Defaults to 500; a non-finite or sub-1 value

package/dist/index.js

@@ -393,34 +393,20 @@ import { Inject, Injectable as Injectable2 } from "@nestjs/common";
 import { DiscoveryService, MetadataScanner } from "@nestjs/core";
 
 // src/schema-parse.ts
-import { FatalError } from "@dudousxd/nestjs-durable-core";
+import { SchemaValidationError } from "@dudousxd/nestjs-durable-core";
 function schemaParser(schema, kind, label) {
   const code = kind === "input" ? "invalid_input" : "invalid_output";
   if (isStandardSchema(schema)) {
     return async (value) => {
       const result = await schema["~standard"].validate(value);
-      if (result.issues) {
-        const issues = result.issues.map((i) => ({
-          message: i.message,
-          ...i.path ? {
-            path: i.path.map((p) => String(typeof p === "object" ? p.key : p))
-          } : {}
-        }));
-        throw new FatalError(`invalid ${label}: ${formatIssues(issues)}`, code, issues);
-      }
+      if (result.issues) throw new SchemaValidationError(label, result.issues, code);
       return result.value;
     };
   }
   if (isZodLike(schema)) {
     return async (value) => {
       const result = schema.safeParse(value);
-      if (!result.success) {
-        const issues = result.error.issues.map((i) => ({
-          message: i.message,
-          path: i.path.map(String)
-        }));
-        throw new FatalError(`invalid ${label}: ${formatIssues(issues)}`, code, issues);
-      }
+      if (!result.success) throw new SchemaValidationError(label, result.error.issues, code);
       return result.data;
     };
   }
@@ -440,12 +426,11 @@ function classValidatorParser(cls, code, label) {
     }
     if (value === null || typeof value !== "object" || Array.isArray(value)) {
       const got = value === null ? "null" : Array.isArray(value) ? "an array" : typeof value;
-      const message = `expected an object, got ${got}`;
-      throw new FatalError(`invalid ${label}: ${message}`, code, [
+      throw new SchemaValidationError(label, [
         {
-          message
+          message: `expected an object, got ${got}`
         }
-      ]);
+      ], code);
     }
     const instance = ct.plainToInstance(cls, value);
     const errors = await cv.validate(instance, {
@@ -460,8 +445,8 @@ function classValidatorParser(cls, code, label) {
           String(e.property)
         ]
       }));
-      const message = issues.map((i) => i.message).join("; ");
-      throw new FatalError(`invalid ${label}: ${message}`, code, issues);
+      const summary = issues.map((i) => i.message).join("; ");
+      throw new SchemaValidationError(label, issues, code, summary);
     }
     return instance;
   };
@@ -475,10 +460,6 @@ function isZodLike(schema) {
   return typeof schema === "object" && schema !== null && typeof schema.safeParse === "function";
 }
 __name(isZodLike, "isZodLike");
-function formatIssues(issues) {
-  return issues.map((i) => i.path && i.path.length > 0 ? `${i.path.join(".")}: ${i.message}` : i.message).join("; ");
-}
-__name(formatIssues, "formatIssues");
 
 // src/discovery-helpers.ts
 function scanWorkflows(discovery, register) {
@@ -558,8 +539,8 @@ function workflowIo(meta) {
   const validateInput = meta.validateInput;
   return {
     validateAtStart: parseInput || validateInput ? async (input) => {
-      if (parseInput) await parseInput(input);
-      await validateInput?.(input);
+      const parsed = parseInput ? await parseInput(input) : input;
+      await validateInput?.(parsed);
     } : void 0,
     wrap: /* @__PURE__ */ __name((body) => !parseInput && !parseOutput ? body : async (ctx, input) => {
       const output = await body(ctx, parseInput ? await parseInput(input) : input);
@@ -2076,7 +2057,7 @@ var TenantEventRepublisher = class {
 };
 
 // src/timer-poller.ts
-import { DURABLE_OPTIONS_CANONICAL as DURABLE_OPTIONS_CANONICAL5, WorkflowEngine as WorkflowEngine3, runSchedules } from "@dudousxd/nestjs-durable-core";
+import { DURABLE_OPTIONS_CANONICAL as DURABLE_OPTIONS_CANONICAL5, WorkflowEngine as WorkflowEngine3, runSchedules, workflowName as workflowName3 } from "@dudousxd/nestjs-durable-core";
 import { Inject as Inject6, Injectable as Injectable9 } from "@nestjs/common";
 function _ts_decorate9(decorators, target, key, desc) {
   var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
@@ -2120,6 +2101,7 @@ var TimerPoller = class {
     this.options = options;
   }
   async onApplicationBootstrap() {
+    for (const s of this.options.schedules ?? []) workflowName3(s.workflow);
     if (!isDrivingOperator(this.options)) return;
     this.unsubscribeEnqueued = this.engine.onEnqueued((runId) => {
       void this.engine.runOne(runId).catch((error) => {
@@ -2186,6 +2168,7 @@ var TimerPoller = class {
       await this.sweep("recoverIncomplete", () => this.engine.recoverIncomplete());
       await this.sweep("resumeDueTimers", () => this.engine.resumeDueTimers());
       await this.sweep("sweepTimeouts", () => this.engine.sweepTimeouts());
+      await this.sweep("sweepStalled", async () => this.engine.sweepStalled?.());
       const schedules = this.options.schedules;
       if (schedules && schedules.length > 0) {
         await this.sweep("schedules", () => runSchedules(this.engine, schedules, Date.now()));
@@ -2220,7 +2203,7 @@ var CONTEXT_ACCESSOR = Symbol.for("@dudousxd/nestjs-context:accessor");
 var RUN_GATEWAY = RunGateway;
 
 // src/workflow.registrar.ts
-import { DURABLE_OPTIONS_CANONICAL as DURABLE_OPTIONS_CANONICAL6, RemoteWorkflowExecutor, STATE_STORE_CANONICAL as STATE_STORE_CANONICAL3, WorkflowEngine as WorkflowEngine4, bindWorkflowClass, parseDuration as parseDuration2, sanitizeQueueToken, tenantGroup, workflowName as workflowName3 } from "@dudousxd/nestjs-durable-core";
+import { DURABLE_OPTIONS_CANONICAL as DURABLE_OPTIONS_CANONICAL6, RemoteWorkflowExecutor, STATE_STORE_CANONICAL as STATE_STORE_CANONICAL3, WorkflowEngine as WorkflowEngine4, bindWorkflowClass, parseDuration as parseDuration2, sanitizeQueueToken, tenantGroup, workflowName as workflowName4 } from "@dudousxd/nestjs-durable-core";
 import { Inject as Inject7, Injectable as Injectable10 } from "@nestjs/common";
 import { DiscoveryService as DiscoveryService4, MetadataScanner as MetadataScanner4 } from "@nestjs/core";
 
@@ -2387,7 +2370,7 @@ var WorkflowRegistrar = class {
         });
         deadLetterByWorkflow.set(meta.name, dlqName);
       } else if (meta.deadLetterWorkflow) {
-        deadLetterByWorkflow.set(meta.name, workflowName3(meta.deadLetterWorkflow));
+        deadLetterByWorkflow.set(meta.name, workflowName4(meta.deadLetterWorkflow));
       }
     });
     this.reportUnattributed(unattributed);
@@ -2435,7 +2418,7 @@ var WorkflowRegistrar = class {
   * a `dlq:<runId>` id, so re-recovery never double-dispatches.
   */
   installDeadLetterRouting(byWorkflow) {
-    const fallback = this.options.deadLetterWorkflow ? workflowName3(this.options.deadLetterWorkflow) : void 0;
+    const fallback = this.options.deadLetterWorkflow ? workflowName4(this.options.deadLetterWorkflow) : void 0;
     if (byWorkflow.size === 0 && !fallback) return;
     this.engine.onDead((run) => {
       const target = byWorkflow.get(run.workflow) ?? fallback;
@@ -2884,6 +2867,7 @@ var DurableModule = class _DurableModule {
               remoteRedispatchMs: options.remoteRedispatchMs,
               remoteRedispatchMax: options.remoteRedispatchMax,
               reconcileMs: options.reconcileMs,
+              stalledAfterMs: options.stalledAfterMs,
               timerBatchSize: options.timerBatchSize,
               eventBufferTtlMs: options.eventBufferTtlMs,
               blockedPollMs: options.blockedPollMs,
@@ -2907,6 +2891,7 @@ var DurableModule = class _DurableModule {
               } : void 0
             });
             for (const queue of options.queues ?? []) engine.registerQueue(queue);
+            if (options.onStalled) engine.onStalled(options.onStalled);
             return engine;
           }, "useFactory"),
           inject: [
@@ -2969,7 +2954,7 @@ DurableModule = _ts_decorate12([
 ], DurableModule);
 
 // src/index.ts
-import { readSearchAttributes as readSearchAttributes2, RunGateway as RunGateway3, WorkflowEngine as WorkflowEngine7 } from "@dudousxd/nestjs-durable-core";
+import { prevCronFireMs, readSearchAttributes as readSearchAttributes2, RunGateway as RunGateway3, runSchedules as runSchedules2, scheduledRunId, scheduleRunIdAt, WorkflowEngine as WorkflowEngine7 } from "@dudousxd/nestjs-durable-core";
 export {
   CONTEXT_ACCESSOR,
   DEAD_LETTER_METADATA,
@@ -3025,7 +3010,11 @@ export {
   isOperatorRole,
   isStepInterceptor,
   onErrorCodesOf,
+  prevCronFireMs,
   readSearchAttributes2 as readSearchAttributes,
+  runSchedules2 as runSchedules,
+  scheduleRunIdAt,
+  scheduledRunId,
   thinWorkerProviders,
   unavailableRunGateway
 };