@dudousxd/nestjs-durable 0.44.0 → 0.45.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-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 { WorkflowCtx, SearchAttributes, WorkflowClass, StepError, WorkflowRef, SingletonConfig, ConcurrencyConfig, 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, DynamicWorkflowCtx, 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';
 import { DynamicModule, InjectionToken, OnModuleInit, OnApplicationBootstrap, OnApplicationShutdown, Provider } from '@nestjs/common';
@@ -112,6 +112,8 @@ interface WorkflowMeta {
     tags?: string[] | undefined;
     /** Per-key serialization (a durable mutex). See `WorkflowOptions`. */
     singleton?: SingletonConfig | undefined;
+    /** Start-time concurrency quota (rejecting). See `WorkflowOptions`. */
+    concurrency?: ConcurrencyConfig | undefined;
     /** Max wall-clock lifetime before a run is cancelled (e.g. `'2h'`). See `WorkflowOptions`. */
     executionTimeout?: string | number | undefined;
     /** class-validator DTO validated at start. See `WorkflowOptions`. */
@@ -156,6 +158,15 @@ interface WorkflowOptions {
      * 1) raises the concurrency.
      */
     singleton?: SingletonConfig;
+    /**
+     * A start-time concurrency QUOTA: at most `limit` runs sharing a key in flight, and a start over it
+     * is REJECTED (`ConcurrencyLimitError`, nothing created) rather than queued. e.g.
+     * `concurrency: { key: (input) => `tenant:${input.tenantId}`, limit: 8 }` caps what one tenant can
+     * have executing at once. The key is shared across workflows; `limit` may be a (async) function of
+     * the key for per-plan limits; `countStatuses` narrows what occupies a slot (default: every
+     * non-terminal status). Use `singleton` instead when excess runs should wait their turn.
+     */
+    concurrency?: ConcurrencyConfig;
     /**
      * Max wall-clock lifetime for a run of this workflow (e.g. `'2h'`, `'7 days'`, or ms). A run that
      * outlives it is moved to `cancelled` (`execution_timeout`) by the timer poller — a backstop for
@@ -363,7 +374,7 @@ declare function getOnEvents(meta: WorkflowMeta, target: object): string[];
 
 /**
  * Retention config for the {@link RetentionPoller}. One or more {@link RetentionPolicy policies}
- * (status sets must be disjoint — validated at boot), swept together on a shared interval.
+ * (status sets must be disjoint per scope — validated at boot), swept together on a shared interval.
  *
  * ```ts
  * retention: {
@@ -372,9 +383,14 @@ declare function getOnEvents(meta: WorkflowMeta, target: object): string[];
  *   policies: [
  *     { statuses: ['completed', 'cancelled'], maxAge: '14d', maxCount: 200 },
  *     { statuses: ['failed'], maxAge: '90d' }, // keep failures longer for debugging
+ *     // Scoped: chat turns age out after a day, whatever the defaults above say.
+ *     { statuses: ['completed', 'failed', 'cancelled'], maxAge: '1d', scope: { tags: ['chat'] } },
  *   ],
  * }
  * ```
+ *
+ * Policies are applied one after another, so a run matched by several scopes is pruned by the
+ * strictest of them.
  */
 interface DurableRetentionOptions {
     /** The retention rules, one per (disjoint) status group. */
@@ -513,12 +529,21 @@ interface DurableModuleOptions {
      * optional `cron-parser` peer dependency. Operator only.
      */
     schedules?: ScheduledWorkflow[];
+    /**
+     * Fire the PERSISTED schedules managed at runtime through `engine.schedules` (create/upsert/pause/
+     * resume/delete/list) on every timer-poll tick of a driving instance — one indexed "due by now"
+     * query per tick. Off by default, so a deployment that never uses them doesn't need the
+     * `durable_schedules` table. Safe with any number of driving instances: each window's run id is
+     * deterministic and advancing a schedule is a compare-and-set. Operator only.
+     */
+    persistedSchedules?: boolean;
     /**
      * Hard-prune terminal run history on an interval so `durable_workflow_runs` (and its child tables)
      * stays bounded — without it, completed/failed/cancelled runs accumulate forever and the timer
      * poller's per-tick status scans get linearly slower. Driving instances only. Omit to keep all
-     * history (the default). Requires a store adapter that implements `pruneTerminalRuns` (the
-     * MikroORM adapter does); other adapters no-op with a warning. See {@link DurableRetentionOptions}.
+     * history (the default). Requires a store adapter that implements `pruneTerminalRuns` (every
+     * first-party adapter does); a custom store without it no-ops with a warning. See
+     * {@link DurableRetentionOptions}.
      * Operator only.
      */
     retention?: DurableRetentionOptions;

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-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 { WorkflowCtx, SearchAttributes, WorkflowClass, StepError, WorkflowRef, SingletonConfig, ConcurrencyConfig, 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, DynamicWorkflowCtx, 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';
 import { DynamicModule, InjectionToken, OnModuleInit, OnApplicationBootstrap, OnApplicationShutdown, Provider } from '@nestjs/common';
@@ -112,6 +112,8 @@ interface WorkflowMeta {
     tags?: string[] | undefined;
     /** Per-key serialization (a durable mutex). See `WorkflowOptions`. */
     singleton?: SingletonConfig | undefined;
+    /** Start-time concurrency quota (rejecting). See `WorkflowOptions`. */
+    concurrency?: ConcurrencyConfig | undefined;
     /** Max wall-clock lifetime before a run is cancelled (e.g. `'2h'`). See `WorkflowOptions`. */
     executionTimeout?: string | number | undefined;
     /** class-validator DTO validated at start. See `WorkflowOptions`. */
@@ -156,6 +158,15 @@ interface WorkflowOptions {
      * 1) raises the concurrency.
      */
     singleton?: SingletonConfig;
+    /**
+     * A start-time concurrency QUOTA: at most `limit` runs sharing a key in flight, and a start over it
+     * is REJECTED (`ConcurrencyLimitError`, nothing created) rather than queued. e.g.
+     * `concurrency: { key: (input) => `tenant:${input.tenantId}`, limit: 8 }` caps what one tenant can
+     * have executing at once. The key is shared across workflows; `limit` may be a (async) function of
+     * the key for per-plan limits; `countStatuses` narrows what occupies a slot (default: every
+     * non-terminal status). Use `singleton` instead when excess runs should wait their turn.
+     */
+    concurrency?: ConcurrencyConfig;
     /**
      * Max wall-clock lifetime for a run of this workflow (e.g. `'2h'`, `'7 days'`, or ms). A run that
      * outlives it is moved to `cancelled` (`execution_timeout`) by the timer poller — a backstop for
@@ -363,7 +374,7 @@ declare function getOnEvents(meta: WorkflowMeta, target: object): string[];
 
 /**
  * Retention config for the {@link RetentionPoller}. One or more {@link RetentionPolicy policies}
- * (status sets must be disjoint — validated at boot), swept together on a shared interval.
+ * (status sets must be disjoint per scope — validated at boot), swept together on a shared interval.
  *
  * ```ts
  * retention: {
@@ -372,9 +383,14 @@ declare function getOnEvents(meta: WorkflowMeta, target: object): string[];
  *   policies: [
  *     { statuses: ['completed', 'cancelled'], maxAge: '14d', maxCount: 200 },
  *     { statuses: ['failed'], maxAge: '90d' }, // keep failures longer for debugging
+ *     // Scoped: chat turns age out after a day, whatever the defaults above say.
+ *     { statuses: ['completed', 'failed', 'cancelled'], maxAge: '1d', scope: { tags: ['chat'] } },
  *   ],
  * }
  * ```
+ *
+ * Policies are applied one after another, so a run matched by several scopes is pruned by the
+ * strictest of them.
  */
 interface DurableRetentionOptions {
     /** The retention rules, one per (disjoint) status group. */
@@ -513,12 +529,21 @@ interface DurableModuleOptions {
      * optional `cron-parser` peer dependency. Operator only.
      */
     schedules?: ScheduledWorkflow[];
+    /**
+     * Fire the PERSISTED schedules managed at runtime through `engine.schedules` (create/upsert/pause/
+     * resume/delete/list) on every timer-poll tick of a driving instance — one indexed "due by now"
+     * query per tick. Off by default, so a deployment that never uses them doesn't need the
+     * `durable_schedules` table. Safe with any number of driving instances: each window's run id is
+     * deterministic and advancing a schedule is a compare-and-set. Operator only.
+     */
+    persistedSchedules?: boolean;
     /**
      * Hard-prune terminal run history on an interval so `durable_workflow_runs` (and its child tables)
      * stays bounded — without it, completed/failed/cancelled runs accumulate forever and the timer
      * poller's per-tick status scans get linearly slower. Driving instances only. Omit to keep all
-     * history (the default). Requires a store adapter that implements `pruneTerminalRuns` (the
-     * MikroORM adapter does); other adapters no-op with a warning. See {@link DurableRetentionOptions}.
+     * history (the default). Requires a store adapter that implements `pruneTerminalRuns` (every
+     * first-party adapter does); a custom store without it no-ops with a warning. See
+     * {@link DurableRetentionOptions}.
      * Operator only.
      */
     retention?: DurableRetentionOptions;

package/dist/index.js

@@ -127,6 +127,7 @@ function Workflow(options) {
       deadLetterWorkflow: options.deadLetterWorkflow,
       tags: options.tags,
       singleton: options.singleton,
+      concurrency: options.concurrency,
       executionTimeout: options.executionTimeout,
       inputSchema: options.inputSchema,
       validateInput: options.validateInput,
@@ -1204,6 +1205,7 @@ var MAX_BATCHES_PER_POLICY = 100;
 function validateRetention(retention) {
   const seen = /* @__PURE__ */ new Set();
   for (const policy of retention.policies) {
+    const scopeKey = policy.scope ? stableKey(policy.scope) : "";
     if (policy.statuses.length === 0) {
       throw new Error("durable retention: each policy must list at least one status");
     }
@@ -1215,14 +1217,24 @@ function validateRetention(retention) {
       if (!TERMINAL_RUN_STATUSES.includes(status)) {
         throw new Error(`durable retention: status "${status}" is not terminal; only ${TERMINAL_RUN_STATUSES.join(", ")} can be pruned`);
       }
-      if (seen.has(status)) {
-        throw new Error(`durable retention: status "${status}" appears in more than one policy; status sets must be disjoint`);
+      const key = `${scopeKey}|${status}`;
+      if (seen.has(key)) {
+        throw new Error(`durable retention: status "${status}" appears in more than one policy with the same scope; status sets must be disjoint per scope`);
       }
-      seen.add(status);
+      seen.add(key);
     }
   }
 }
 __name(validateRetention, "validateRetention");
+function stableKey(value) {
+  if (Array.isArray(value)) return `[${value.map(stableKey).join(",")}]`;
+  if (value && typeof value === "object") {
+    const entries = Object.entries(value).filter(([, v]) => v !== void 0).sort(([a], [b]) => a.localeCompare(b));
+    return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${stableKey(v)}`).join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+__name(stableKey, "stableKey");
 var RetentionPoller = class {
   static {
     __name(this, "RetentionPoller");
@@ -1743,6 +1755,9 @@ var TimerPoller = class {
       if (schedules && schedules.length > 0) {
         await this.sweep("schedules", () => runSchedules(this.engine, schedules, Date.now()));
       }
+      if (this.options.persistedSchedules) {
+        await this.sweep("persistedSchedules", () => this.engine.schedules.tick());
+      }
     } finally {
       this.polling = false;
     }
@@ -1919,6 +1934,7 @@ var WorkflowRegistrar = class {
         origin,
         tags: meta.tags,
         singleton: meta.singleton,
+        concurrency: meta.concurrency,
         executionTimeout: meta.executionTimeout,
         requires: meta.requires,
         validateInput,