@dudousxd/nestjs-durable-core 0.50.0 → 0.51.0

package/dist/index.d.cts

@@ -3308,7 +3308,7 @@ declare function attributeOperand(filter: AttributeFilter): string | number;
  * ```
  */
 declare function readSearchAttributes<S extends SearchAttributesSchema>(schema: S, run: {
-    searchAttributes?: SearchAttributes | undefined;
+    searchAttributes?: SearchAttributes | null | undefined;
 }): InferSearchAttributes<S>;
 
 /**
@@ -3369,6 +3369,60 @@ declare const STATE_STORE_CANONICAL: unique symbol;
 declare const TRANSPORT_CANONICAL: unique symbol;
 declare const DURABLE_OPTIONS_CANONICAL: unique symbol;
 
+/**
+ * The OPT-IN declaration-site contract for a `@Workflow` class: `implements WorkflowHandler<TInput,
+ * TOutput, A>` pins the class's `run(ctx, input)` signature against `TInput`/`TOutput`/`A` so a wrong
+ * signature — a renamed method, swapped/missing param, wrong return type — is a compile error AT THE
+ * CLASS instead of surfacing later as a runtime discovery failure (the `@Workflow` decorator finds no
+ * `run` it recognizes) or a silently-wrong type flowing out of `ctx.child(ThisWorkflow, …)` /
+ * `engine.start(ThisWorkflow, …)`. `A` also declares the run's {@link SearchAttributes} shape, so
+ * `ctx.upsertSearchAttributes` is narrowed to it inside the workflow body — see
+ * {@link SearchAttributesSchema} / {@link InferSearchAttributes} for pairing it with a `@Workflow({
+ * searchAttributes })` schema.
+ *
+ * This is a TYPES-ONLY contract: nothing reads `implements WorkflowHandler` at runtime, registration
+ * still goes through the `@Workflow` decorator + reflected metadata exactly as before, and a class
+ * that doesn't implement it works exactly as it always has.
+ *
+ * IMPORTANT caveat: TypeScript does **not** contextually infer a method's parameter types from an
+ * `implements` clause the way it does for e.g. an object literal assigned to a typed variable. The
+ * class still has to annotate `ctx`/`input` itself — `implements` only CHECKS that what you wrote is
+ * assignable to the interface; it doesn't write the annotations for you. Leaving `run`'s params
+ * unannotated still leaves them `any`/inferred-from-usage, `implements` or not.
+ *
+ * @example
+ * ```ts
+ * import { z } from 'zod';
+ * import { Workflow } from '@dudousxd/nestjs-durable';
+ * import type { InferSearchAttributes, WorkflowCtx, WorkflowHandler } from '@dudousxd/nestjs-durable';
+ *
+ * const orderAttrs = z.object({
+ *   tier: z.enum(['free', 'pro']),
+ *   amount: z.number(),
+ * });
+ * type OrderAttrs = InferSearchAttributes<typeof orderAttrs>;
+ *
+ * interface CheckoutInput {
+ *   orderId: string;
+ * }
+ * interface CheckoutOutput {
+ *   receiptId: string;
+ * }
+ *
+ * @Workflow({ name: 'checkout', searchAttributes: orderAttrs })
+ * class CheckoutWorkflow implements WorkflowHandler<CheckoutInput, CheckoutOutput, OrderAttrs> {
+ *   async run(ctx: WorkflowCtx<OrderAttrs>, input: CheckoutInput): Promise<CheckoutOutput> {
+ *     await ctx.upsertSearchAttributes({ tier: 'pro', amount: 100 });
+ *     const receiptId = await ctx.step('charge-card', { orderId: input.orderId });
+ *     return { receiptId };
+ *   }
+ * }
+ * ```
+ */
+interface WorkflowHandler<TInput = unknown, TOutput = unknown, A extends SearchAttributes = SearchAttributes> {
+    run(ctx: WorkflowCtx<A>, input: TInput): Promise<TOutput> | TOutput;
+}
+
 /**
  * A non-durable, in-process `StateStore` for tests and local development.
  * The shipped `@dudousxd/nestjs-durable-store` package re-exports an equivalent.
@@ -3458,4 +3512,4 @@ declare class InMemoryTransport implements Transport, ControlPlane {
     onControl(handler: (msg: ControlMessage) => void): void;
 }
 
-export { type AccumulatorHost, type Admission, type AdmissionBackend, type AdmissionItem, type AttributeFilter, type AttributeOp, type BackoffStrategy, type ChildCallOptions, CodecStateStore, ContinueAsNew, type ControlMessage, type ControlPlane, DURABLE_OPTIONS, DURABLE_OPTIONS_CANONICAL, DURABLE_STEP_CONFIG, DURABLE_STEP_NAME, type DurableTopology, type DurableWebhook, DurableWorkflow, type EngineEvent, type EngineEventType, type EngineListener, Entities, type EntityConfig, type EntityHandler, type EntityHost, EventAccumulators, type EventBatchConfig, FatalError, GatherError, type GroupHealth, type Heartbeat, type HistoryEvent, InMemoryAdmissionBackend, InMemoryStateStore, InMemoryTransport, type InferSearchAttributes, type MetricsCollector, type MetricsSnapshot, type NamedTransport, NonDeterminismError, type PayloadCodec, type QueueConfig, QueueController, RemoteStepError, RemoteStepTimeout, type RemoteTask, RemoteWorkflowExecutor, RemoteWorkflowTimeout, type RetentionPolicy, type RunAttributeRow, type RunDetail, type RunDispatcher, type RunGateway, type RunListItem, type RunQuery, type RunReply, type RunReplyResult, type RunRequest, type RunRequestKind, type RunResult, type RunSchedulesOptions, type RunStatus, type RunWaiting, STATE_STORE, STATE_STORE_CANONICAL, type ScheduledWorkflow, type SearchAttributes, type SearchAttributesSchema, SignalTimeoutError, type SignalWaiter, type SingletonConfig, SingletonQueueFullError, StandardSchemaV1, type StartOptions, type StartRunMessage, type StateStore, type StepCheckpoint, type StepConfig, type StepDef, type StepDispatchOpts, type StepError, type StepEvent, type StepHandler, type StepInterceptor, type StepInvocation, type StepKind, type StepLogger, type StepOptions, type StepRef, type StepResult, type StepUndo, type StoreTransaction, type SubProcessHandle, TERMINAL_RUN_STATUSES, TRANSPORT, TRANSPORT_CANONICAL, type TenantEvent, type Transport, type UndoOf, type UpdateResult, type UpdateValidator, WORKFLOW_NAME_KEY, type WireDates, type WorkerAdjust, type WorkerConcurrencyStatus, type WorkerHeartbeat, type WorkerStatus, type WorkflowClass, type WorkflowCommand, type WorkflowCtx, type WorkflowDecision, WorkflowEngine, type WorkflowEngineDeps, type WorkflowExecutor, type WorkflowInputOf, type WorkflowOutputOf, type WorkflowRef, type WorkflowRun, type WorkflowStartClient, type WorkflowStepEvent, WorkflowSuspended, type WorkflowTask, applyAttributeQuery, attributeColumnFor, attributeOperand, bindWorkflowClass, breakpointToken, classifyWaiterToken, collectMetrics, createStepLogger, currentWorkflowCtx, eventMatchOf, eventMatches, eventNameOf, eventPrefix, eventToken, indexWaitersByRun, matchesAttributes, normalizeAttributeRows, parseDuration, prevCronFireMs, readSearchAttributes, resolveRunWaiting, runInWorkflowCtx, runSchedules, runStepHandler, sanitizeQueueToken, scheduledRunId, sqlComparator, stepConfigOf, stepId, stepNameOf, tenantGroup, workflowName };
+export { type AccumulatorHost, type Admission, type AdmissionBackend, type AdmissionItem, type AttributeFilter, type AttributeOp, type BackoffStrategy, type ChildCallOptions, CodecStateStore, ContinueAsNew, type ControlMessage, type ControlPlane, DURABLE_OPTIONS, DURABLE_OPTIONS_CANONICAL, DURABLE_STEP_CONFIG, DURABLE_STEP_NAME, type DurableTopology, type DurableWebhook, DurableWorkflow, type EngineEvent, type EngineEventType, type EngineListener, Entities, type EntityConfig, type EntityHandler, type EntityHost, EventAccumulators, type EventBatchConfig, FatalError, GatherError, type GroupHealth, type Heartbeat, type HistoryEvent, InMemoryAdmissionBackend, InMemoryStateStore, InMemoryTransport, type InferSearchAttributes, type MetricsCollector, type MetricsSnapshot, type NamedTransport, NonDeterminismError, type PayloadCodec, type QueueConfig, QueueController, RemoteStepError, RemoteStepTimeout, type RemoteTask, RemoteWorkflowExecutor, RemoteWorkflowTimeout, type RetentionPolicy, type RunAttributeRow, type RunDetail, type RunDispatcher, type RunGateway, type RunListItem, type RunQuery, type RunReply, type RunReplyResult, type RunRequest, type RunRequestKind, type RunResult, type RunSchedulesOptions, type RunStatus, type RunWaiting, STATE_STORE, STATE_STORE_CANONICAL, type ScheduledWorkflow, type SearchAttributes, type SearchAttributesSchema, SignalTimeoutError, type SignalWaiter, type SingletonConfig, SingletonQueueFullError, StandardSchemaV1, type StartOptions, type StartRunMessage, type StateStore, type StepCheckpoint, type StepConfig, type StepDef, type StepDispatchOpts, type StepError, type StepEvent, type StepHandler, type StepInterceptor, type StepInvocation, type StepKind, type StepLogger, type StepOptions, type StepRef, type StepResult, type StepUndo, type StoreTransaction, type SubProcessHandle, TERMINAL_RUN_STATUSES, TRANSPORT, TRANSPORT_CANONICAL, type TenantEvent, type Transport, type UndoOf, type UpdateResult, type UpdateValidator, WORKFLOW_NAME_KEY, type WireDates, type WorkerAdjust, type WorkerConcurrencyStatus, type WorkerHeartbeat, type WorkerStatus, type WorkflowClass, type WorkflowCommand, type WorkflowCtx, type WorkflowDecision, WorkflowEngine, type WorkflowEngineDeps, type WorkflowExecutor, type WorkflowHandler, type WorkflowInputOf, type WorkflowOutputOf, type WorkflowRef, type WorkflowRun, type WorkflowStartClient, type WorkflowStepEvent, WorkflowSuspended, type WorkflowTask, applyAttributeQuery, attributeColumnFor, attributeOperand, bindWorkflowClass, breakpointToken, classifyWaiterToken, collectMetrics, createStepLogger, currentWorkflowCtx, eventMatchOf, eventMatches, eventNameOf, eventPrefix, eventToken, indexWaitersByRun, matchesAttributes, normalizeAttributeRows, parseDuration, prevCronFireMs, readSearchAttributes, resolveRunWaiting, runInWorkflowCtx, runSchedules, runStepHandler, sanitizeQueueToken, scheduledRunId, sqlComparator, stepConfigOf, stepId, stepNameOf, tenantGroup, workflowName };

package/dist/index.d.ts

@@ -3308,7 +3308,7 @@ declare function attributeOperand(filter: AttributeFilter): string | number;
  * ```
  */
 declare function readSearchAttributes<S extends SearchAttributesSchema>(schema: S, run: {
-    searchAttributes?: SearchAttributes | undefined;
+    searchAttributes?: SearchAttributes | null | undefined;
 }): InferSearchAttributes<S>;
 
 /**
@@ -3369,6 +3369,60 @@ declare const STATE_STORE_CANONICAL: unique symbol;
 declare const TRANSPORT_CANONICAL: unique symbol;
 declare const DURABLE_OPTIONS_CANONICAL: unique symbol;
 
+/**
+ * The OPT-IN declaration-site contract for a `@Workflow` class: `implements WorkflowHandler<TInput,
+ * TOutput, A>` pins the class's `run(ctx, input)` signature against `TInput`/`TOutput`/`A` so a wrong
+ * signature — a renamed method, swapped/missing param, wrong return type — is a compile error AT THE
+ * CLASS instead of surfacing later as a runtime discovery failure (the `@Workflow` decorator finds no
+ * `run` it recognizes) or a silently-wrong type flowing out of `ctx.child(ThisWorkflow, …)` /
+ * `engine.start(ThisWorkflow, …)`. `A` also declares the run's {@link SearchAttributes} shape, so
+ * `ctx.upsertSearchAttributes` is narrowed to it inside the workflow body — see
+ * {@link SearchAttributesSchema} / {@link InferSearchAttributes} for pairing it with a `@Workflow({
+ * searchAttributes })` schema.
+ *
+ * This is a TYPES-ONLY contract: nothing reads `implements WorkflowHandler` at runtime, registration
+ * still goes through the `@Workflow` decorator + reflected metadata exactly as before, and a class
+ * that doesn't implement it works exactly as it always has.
+ *
+ * IMPORTANT caveat: TypeScript does **not** contextually infer a method's parameter types from an
+ * `implements` clause the way it does for e.g. an object literal assigned to a typed variable. The
+ * class still has to annotate `ctx`/`input` itself — `implements` only CHECKS that what you wrote is
+ * assignable to the interface; it doesn't write the annotations for you. Leaving `run`'s params
+ * unannotated still leaves them `any`/inferred-from-usage, `implements` or not.
+ *
+ * @example
+ * ```ts
+ * import { z } from 'zod';
+ * import { Workflow } from '@dudousxd/nestjs-durable';
+ * import type { InferSearchAttributes, WorkflowCtx, WorkflowHandler } from '@dudousxd/nestjs-durable';
+ *
+ * const orderAttrs = z.object({
+ *   tier: z.enum(['free', 'pro']),
+ *   amount: z.number(),
+ * });
+ * type OrderAttrs = InferSearchAttributes<typeof orderAttrs>;
+ *
+ * interface CheckoutInput {
+ *   orderId: string;
+ * }
+ * interface CheckoutOutput {
+ *   receiptId: string;
+ * }
+ *
+ * @Workflow({ name: 'checkout', searchAttributes: orderAttrs })
+ * class CheckoutWorkflow implements WorkflowHandler<CheckoutInput, CheckoutOutput, OrderAttrs> {
+ *   async run(ctx: WorkflowCtx<OrderAttrs>, input: CheckoutInput): Promise<CheckoutOutput> {
+ *     await ctx.upsertSearchAttributes({ tier: 'pro', amount: 100 });
+ *     const receiptId = await ctx.step('charge-card', { orderId: input.orderId });
+ *     return { receiptId };
+ *   }
+ * }
+ * ```
+ */
+interface WorkflowHandler<TInput = unknown, TOutput = unknown, A extends SearchAttributes = SearchAttributes> {
+    run(ctx: WorkflowCtx<A>, input: TInput): Promise<TOutput> | TOutput;
+}
+
 /**
  * A non-durable, in-process `StateStore` for tests and local development.
  * The shipped `@dudousxd/nestjs-durable-store` package re-exports an equivalent.
@@ -3458,4 +3512,4 @@ declare class InMemoryTransport implements Transport, ControlPlane {
     onControl(handler: (msg: ControlMessage) => void): void;
 }
 
-export { type AccumulatorHost, type Admission, type AdmissionBackend, type AdmissionItem, type AttributeFilter, type AttributeOp, type BackoffStrategy, type ChildCallOptions, CodecStateStore, ContinueAsNew, type ControlMessage, type ControlPlane, DURABLE_OPTIONS, DURABLE_OPTIONS_CANONICAL, DURABLE_STEP_CONFIG, DURABLE_STEP_NAME, type DurableTopology, type DurableWebhook, DurableWorkflow, type EngineEvent, type EngineEventType, type EngineListener, Entities, type EntityConfig, type EntityHandler, type EntityHost, EventAccumulators, type EventBatchConfig, FatalError, GatherError, type GroupHealth, type Heartbeat, type HistoryEvent, InMemoryAdmissionBackend, InMemoryStateStore, InMemoryTransport, type InferSearchAttributes, type MetricsCollector, type MetricsSnapshot, type NamedTransport, NonDeterminismError, type PayloadCodec, type QueueConfig, QueueController, RemoteStepError, RemoteStepTimeout, type RemoteTask, RemoteWorkflowExecutor, RemoteWorkflowTimeout, type RetentionPolicy, type RunAttributeRow, type RunDetail, type RunDispatcher, type RunGateway, type RunListItem, type RunQuery, type RunReply, type RunReplyResult, type RunRequest, type RunRequestKind, type RunResult, type RunSchedulesOptions, type RunStatus, type RunWaiting, STATE_STORE, STATE_STORE_CANONICAL, type ScheduledWorkflow, type SearchAttributes, type SearchAttributesSchema, SignalTimeoutError, type SignalWaiter, type SingletonConfig, SingletonQueueFullError, StandardSchemaV1, type StartOptions, type StartRunMessage, type StateStore, type StepCheckpoint, type StepConfig, type StepDef, type StepDispatchOpts, type StepError, type StepEvent, type StepHandler, type StepInterceptor, type StepInvocation, type StepKind, type StepLogger, type StepOptions, type StepRef, type StepResult, type StepUndo, type StoreTransaction, type SubProcessHandle, TERMINAL_RUN_STATUSES, TRANSPORT, TRANSPORT_CANONICAL, type TenantEvent, type Transport, type UndoOf, type UpdateResult, type UpdateValidator, WORKFLOW_NAME_KEY, type WireDates, type WorkerAdjust, type WorkerConcurrencyStatus, type WorkerHeartbeat, type WorkerStatus, type WorkflowClass, type WorkflowCommand, type WorkflowCtx, type WorkflowDecision, WorkflowEngine, type WorkflowEngineDeps, type WorkflowExecutor, type WorkflowInputOf, type WorkflowOutputOf, type WorkflowRef, type WorkflowRun, type WorkflowStartClient, type WorkflowStepEvent, WorkflowSuspended, type WorkflowTask, applyAttributeQuery, attributeColumnFor, attributeOperand, bindWorkflowClass, breakpointToken, classifyWaiterToken, collectMetrics, createStepLogger, currentWorkflowCtx, eventMatchOf, eventMatches, eventNameOf, eventPrefix, eventToken, indexWaitersByRun, matchesAttributes, normalizeAttributeRows, parseDuration, prevCronFireMs, readSearchAttributes, resolveRunWaiting, runInWorkflowCtx, runSchedules, runStepHandler, sanitizeQueueToken, scheduledRunId, sqlComparator, stepConfigOf, stepId, stepNameOf, tenantGroup, workflowName };
+export { type AccumulatorHost, type Admission, type AdmissionBackend, type AdmissionItem, type AttributeFilter, type AttributeOp, type BackoffStrategy, type ChildCallOptions, CodecStateStore, ContinueAsNew, type ControlMessage, type ControlPlane, DURABLE_OPTIONS, DURABLE_OPTIONS_CANONICAL, DURABLE_STEP_CONFIG, DURABLE_STEP_NAME, type DurableTopology, type DurableWebhook, DurableWorkflow, type EngineEvent, type EngineEventType, type EngineListener, Entities, type EntityConfig, type EntityHandler, type EntityHost, EventAccumulators, type EventBatchConfig, FatalError, GatherError, type GroupHealth, type Heartbeat, type HistoryEvent, InMemoryAdmissionBackend, InMemoryStateStore, InMemoryTransport, type InferSearchAttributes, type MetricsCollector, type MetricsSnapshot, type NamedTransport, NonDeterminismError, type PayloadCodec, type QueueConfig, QueueController, RemoteStepError, RemoteStepTimeout, type RemoteTask, RemoteWorkflowExecutor, RemoteWorkflowTimeout, type RetentionPolicy, type RunAttributeRow, type RunDetail, type RunDispatcher, type RunGateway, type RunListItem, type RunQuery, type RunReply, type RunReplyResult, type RunRequest, type RunRequestKind, type RunResult, type RunSchedulesOptions, type RunStatus, type RunWaiting, STATE_STORE, STATE_STORE_CANONICAL, type ScheduledWorkflow, type SearchAttributes, type SearchAttributesSchema, SignalTimeoutError, type SignalWaiter, type SingletonConfig, SingletonQueueFullError, StandardSchemaV1, type StartOptions, type StartRunMessage, type StateStore, type StepCheckpoint, type StepConfig, type StepDef, type StepDispatchOpts, type StepError, type StepEvent, type StepHandler, type StepInterceptor, type StepInvocation, type StepKind, type StepLogger, type StepOptions, type StepRef, type StepResult, type StepUndo, type StoreTransaction, type SubProcessHandle, TERMINAL_RUN_STATUSES, TRANSPORT, TRANSPORT_CANONICAL, type TenantEvent, type Transport, type UndoOf, type UpdateResult, type UpdateValidator, WORKFLOW_NAME_KEY, type WireDates, type WorkerAdjust, type WorkerConcurrencyStatus, type WorkerHeartbeat, type WorkerStatus, type WorkflowClass, type WorkflowCommand, type WorkflowCtx, type WorkflowDecision, WorkflowEngine, type WorkflowEngineDeps, type WorkflowExecutor, type WorkflowHandler, type WorkflowInputOf, type WorkflowOutputOf, type WorkflowRef, type WorkflowRun, type WorkflowStartClient, type WorkflowStepEvent, WorkflowSuspended, type WorkflowTask, applyAttributeQuery, attributeColumnFor, attributeOperand, bindWorkflowClass, breakpointToken, classifyWaiterToken, collectMetrics, createStepLogger, currentWorkflowCtx, eventMatchOf, eventMatches, eventNameOf, eventPrefix, eventToken, indexWaitersByRun, matchesAttributes, normalizeAttributeRows, parseDuration, prevCronFireMs, readSearchAttributes, resolveRunWaiting, runInWorkflowCtx, runSchedules, runStepHandler, sanitizeQueueToken, scheduledRunId, sqlComparator, stepConfigOf, stepId, stepNameOf, tenantGroup, workflowName };