@dudousxd/nestjs-durable 0.33.0 → 0.34.1

package/dist/index.d.cts

@@ -1,10 +1,76 @@
-import { StepError, WorkflowRef, SingletonConfig, SearchAttributesSchema, StateStore, Transport, NamedTransport, ControlPlane, ScheduledWorkflow, RetentionPolicy, QueueConfig, AdmissionBackend, WorkflowClass, WorkflowInputOf, StartOptions, RunResult, RunGateway, WorkflowEngine, EntityHandler, DurableTopology, RunDetail, RunQuery, RunListItem, 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, 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';
 import { DynamicModule, InjectionToken, OnModuleInit, OnApplicationBootstrap, OnApplicationShutdown, Provider } from '@nestjs/common';
 import { DiscoveryService, MetadataScanner } from '@nestjs/core';
 
+/**
+ * The search-attributes shape a `@Workflow` class declares — extracted from its `run` method's
+ * `ctx: WorkflowCtx<A>` annotation, mirroring the `WorkflowInputOf`/`WorkflowOutputOf` structural-
+ * typing idiom in core's `workflow-ref.ts` (which extract `run`'s `input`/return type the same way).
+ * A class whose `run` leaves `ctx` untyped (or types it as the bare `WorkflowCtx`) resolves to the
+ * untyped `SearchAttributes` default — matching `WorkflowCtx` itself.
+ */
+type WorkflowAttributesOf<C> = C extends abstract new (...args: never[]) => {
+    run(ctx: WorkflowCtx<infer A>, input: never): unknown;
+} ? A : SearchAttributes;
+/**
+ * Read a run's search attributes **by workflow class**, with the schema resolved from that class's
+ * `@Workflow({ searchAttributes })` decorator metadata — the same single-source-of-truth idiom as
+ * triggering a workflow by class (`ctx.child(ShippingWorkflow, input)`, `engine.start(CheckoutWorkflow,
+ * input)`): the decorator is the one place the schema lives, and every reader references the
+ * WORKFLOW, never re-imports or re-declares the schema itself. The return type is inferred
+ * structurally from the class's `run(ctx: WorkflowCtx<A>, …)` annotation (see
+ * {@link WorkflowAttributesOf}), so a valid read is typed to `A` with no explicit type argument.
+ *
+ * Delegates to core's `readSearchAttributes(schema, run)` for the actual read, so the same lenient
+ * safe-parse semantics apply: a run whose stored `searchAttributes` predate the schema, or fail it,
+ * reads back as `{}` rather than throwing (see `readSearchAttributes`'s doc comment).
+ *
+ * @throws if `workflow` isn't a `@Workflow`-decorated class (no metadata at all — nothing to resolve
+ * the schema from).
+ * @throws if `workflow` is a `@Workflow` class that never declared a `searchAttributes` schema —
+ * reading attributes by class needs one to resolve against.
+ *
+ * @example
+ * ```ts
+ * import { z } from 'zod';
+ * import { Injectable } from '@nestjs/common';
+ * import {
+ *   attributesOf,
+ *   InferSearchAttributes,
+ *   Workflow,
+ *   WorkflowCtx,
+ *   WorkflowHandler,
+ * } from '@dudousxd/nestjs-durable';
+ *
+ * const orderAttrs = z.object({ tier: z.enum(['free', 'pro']), amount: z.number() });
+ * type OrderAttrs = InferSearchAttributes<typeof orderAttrs>;
+ *
+ * @Workflow({ name: 'checkout', searchAttributes: orderAttrs })
+ * class CheckoutWorkflow implements WorkflowHandler<{ orderId: string }, void, OrderAttrs> {
+ *   async run(ctx: WorkflowCtx<OrderAttrs>, input: { orderId: string }): Promise<void> {
+ *     await ctx.upsertSearchAttributes({ tier: 'pro', amount: 100 });
+ *   }
+ * }
+ *
+ * @Injectable()
+ * class CheckoutDashboardService {
+ *   constructor(private readonly store: StateStore) {}
+ *
+ *   async tierOf(runId: string) {
+ *     const run = await this.store.getRun(runId);
+ *     const attrs = attributesOf(CheckoutWorkflow, run ?? {}); // OrderAttrs
+ *     return attrs.tier;
+ *   }
+ * }
+ * ```
+ */
+declare function attributesOf<C extends WorkflowClass>(workflow: C, run: {
+    searchAttributes?: SearchAttributes | null | undefined;
+}): WorkflowAttributesOf<C>;
+
 /**
  * Local, structural mirror of `@dudousxd/nestjs-context`'s public accessor
  * (`packages/core/src/accessor.ts`).
@@ -612,6 +678,7 @@ declare class DurableStartClient {
     }, _opts?: StartOptions): Promise<void>;
     publishEvent(_name: string, _payload: unknown, _opts?: {
         id?: string;
+        buffer?: boolean;
     }): Promise<void>;
 }
 
@@ -1029,10 +1096,15 @@ declare class WorkflowService {
      * starts a fresh run of every workflow subscribed via `@Workflow({ onEvent })` / `@OnDurableEvent` (the
      * payload becomes its input). Pass `opts.id` to dedupe redeliveries. Returns how many runs it
      * touched (resumed + started).
+     *
+     * Reliable by default: a publish that touches NOBODY (no live waiter, no subscriber) buffers ONE
+     * copy so a LATER `waitForEvent(name, { match })` still consumes it instead of it being dropped —
+     * see {@link WorkflowEngine.publishEvent}'s full semantics doc. Pass `opts.buffer: false` to opt out.
      */
     publishEvent(name: string, payload: unknown, opts?: {
         id?: string;
+        buffer?: boolean;
     }): Promise<number>;
 }
 
-export { CONTEXT_ACCESSOR, type ContextAccessor, type ContextStore, DEAD_LETTER_METADATA, DURABLE_STEP_METADATA, DURABLE_WORKER_RUNNERS, DeadLetter, DurableModule, type DurableModuleAsyncOptions, type DurableModuleOptions, type DurableRetentionOptions, DurableStartClient, DurableStep, type DurableStepInterceptor, type DurableStepMeta, ENTITY_METADATA, ENTITY_ON_METADATA, Entity, EntityService, IN_APP_RUN_REDIS_WORKER, IN_APP_WORKER_BINDING, IN_APP_WORKER_RUNNERS, IN_APP_WORKER_RUNTIME, type InAppWorkerBinding, InAppWorkerBootstrap, ON_EVENT_METADATA, On, OnDurableEvent, OnEvent, ProxyRunGateway, RUN_GATEWAY, RUN_REDIS_WORKER, type RunLookupStore, type RunRedisWorkerFn, RunRequestResponder, type RunRequestTransport, STEP_INTERCEPTOR_METADATA, Step, StepInterceptor, type StepOptions, StoreRunGateway, TenantEventRepublisher, ThinStepRegistrar, ThinWorkerBootstrap, ThinWorkflowRegistrar, type UserRef, WORKFLOW_METADATA, Workflow, type WorkflowMeta, type WorkflowOptions, WorkflowService, entityConfigFor, getDurableStepMeta, getEntityMeta, getOnEvents, getWorkflowMeta, inAppWorkerProviders, isDeadLetterHandler, isDrivingOperator, isOperatorRole, isStepInterceptor, thinWorkerProviders, unavailableRunGateway };
+export { CONTEXT_ACCESSOR, type ContextAccessor, type ContextStore, DEAD_LETTER_METADATA, DURABLE_STEP_METADATA, DURABLE_WORKER_RUNNERS, DeadLetter, DurableModule, type DurableModuleAsyncOptions, type DurableModuleOptions, type DurableRetentionOptions, DurableStartClient, DurableStep, type DurableStepInterceptor, type DurableStepMeta, ENTITY_METADATA, ENTITY_ON_METADATA, Entity, EntityService, IN_APP_RUN_REDIS_WORKER, IN_APP_WORKER_BINDING, IN_APP_WORKER_RUNNERS, IN_APP_WORKER_RUNTIME, type InAppWorkerBinding, InAppWorkerBootstrap, ON_EVENT_METADATA, On, OnDurableEvent, OnEvent, ProxyRunGateway, RUN_GATEWAY, RUN_REDIS_WORKER, type RunLookupStore, type RunRedisWorkerFn, RunRequestResponder, type RunRequestTransport, STEP_INTERCEPTOR_METADATA, Step, StepInterceptor, type StepOptions, StoreRunGateway, TenantEventRepublisher, ThinStepRegistrar, ThinWorkerBootstrap, ThinWorkflowRegistrar, type UserRef, WORKFLOW_METADATA, Workflow, type WorkflowAttributesOf, type WorkflowMeta, type WorkflowOptions, WorkflowService, attributesOf, entityConfigFor, getDurableStepMeta, getEntityMeta, getOnEvents, getWorkflowMeta, inAppWorkerProviders, isDeadLetterHandler, isDrivingOperator, isOperatorRole, isStepInterceptor, thinWorkerProviders, unavailableRunGateway };

package/dist/index.d.ts

@@ -1,10 +1,76 @@
-import { StepError, WorkflowRef, SingletonConfig, SearchAttributesSchema, StateStore, Transport, NamedTransport, ControlPlane, ScheduledWorkflow, RetentionPolicy, QueueConfig, AdmissionBackend, WorkflowClass, WorkflowInputOf, StartOptions, RunResult, RunGateway, WorkflowEngine, EntityHandler, DurableTopology, RunDetail, RunQuery, RunListItem, 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, 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';
 import { DynamicModule, InjectionToken, OnModuleInit, OnApplicationBootstrap, OnApplicationShutdown, Provider } from '@nestjs/common';
 import { DiscoveryService, MetadataScanner } from '@nestjs/core';
 
+/**
+ * The search-attributes shape a `@Workflow` class declares — extracted from its `run` method's
+ * `ctx: WorkflowCtx<A>` annotation, mirroring the `WorkflowInputOf`/`WorkflowOutputOf` structural-
+ * typing idiom in core's `workflow-ref.ts` (which extract `run`'s `input`/return type the same way).
+ * A class whose `run` leaves `ctx` untyped (or types it as the bare `WorkflowCtx`) resolves to the
+ * untyped `SearchAttributes` default — matching `WorkflowCtx` itself.
+ */
+type WorkflowAttributesOf<C> = C extends abstract new (...args: never[]) => {
+    run(ctx: WorkflowCtx<infer A>, input: never): unknown;
+} ? A : SearchAttributes;
+/**
+ * Read a run's search attributes **by workflow class**, with the schema resolved from that class's
+ * `@Workflow({ searchAttributes })` decorator metadata — the same single-source-of-truth idiom as
+ * triggering a workflow by class (`ctx.child(ShippingWorkflow, input)`, `engine.start(CheckoutWorkflow,
+ * input)`): the decorator is the one place the schema lives, and every reader references the
+ * WORKFLOW, never re-imports or re-declares the schema itself. The return type is inferred
+ * structurally from the class's `run(ctx: WorkflowCtx<A>, …)` annotation (see
+ * {@link WorkflowAttributesOf}), so a valid read is typed to `A` with no explicit type argument.
+ *
+ * Delegates to core's `readSearchAttributes(schema, run)` for the actual read, so the same lenient
+ * safe-parse semantics apply: a run whose stored `searchAttributes` predate the schema, or fail it,
+ * reads back as `{}` rather than throwing (see `readSearchAttributes`'s doc comment).
+ *
+ * @throws if `workflow` isn't a `@Workflow`-decorated class (no metadata at all — nothing to resolve
+ * the schema from).
+ * @throws if `workflow` is a `@Workflow` class that never declared a `searchAttributes` schema —
+ * reading attributes by class needs one to resolve against.
+ *
+ * @example
+ * ```ts
+ * import { z } from 'zod';
+ * import { Injectable } from '@nestjs/common';
+ * import {
+ *   attributesOf,
+ *   InferSearchAttributes,
+ *   Workflow,
+ *   WorkflowCtx,
+ *   WorkflowHandler,
+ * } from '@dudousxd/nestjs-durable';
+ *
+ * const orderAttrs = z.object({ tier: z.enum(['free', 'pro']), amount: z.number() });
+ * type OrderAttrs = InferSearchAttributes<typeof orderAttrs>;
+ *
+ * @Workflow({ name: 'checkout', searchAttributes: orderAttrs })
+ * class CheckoutWorkflow implements WorkflowHandler<{ orderId: string }, void, OrderAttrs> {
+ *   async run(ctx: WorkflowCtx<OrderAttrs>, input: { orderId: string }): Promise<void> {
+ *     await ctx.upsertSearchAttributes({ tier: 'pro', amount: 100 });
+ *   }
+ * }
+ *
+ * @Injectable()
+ * class CheckoutDashboardService {
+ *   constructor(private readonly store: StateStore) {}
+ *
+ *   async tierOf(runId: string) {
+ *     const run = await this.store.getRun(runId);
+ *     const attrs = attributesOf(CheckoutWorkflow, run ?? {}); // OrderAttrs
+ *     return attrs.tier;
+ *   }
+ * }
+ * ```
+ */
+declare function attributesOf<C extends WorkflowClass>(workflow: C, run: {
+    searchAttributes?: SearchAttributes | null | undefined;
+}): WorkflowAttributesOf<C>;
+
 /**
  * Local, structural mirror of `@dudousxd/nestjs-context`'s public accessor
  * (`packages/core/src/accessor.ts`).
@@ -612,6 +678,7 @@ declare class DurableStartClient {
     }, _opts?: StartOptions): Promise<void>;
     publishEvent(_name: string, _payload: unknown, _opts?: {
         id?: string;
+        buffer?: boolean;
     }): Promise<void>;
 }
 
@@ -1029,10 +1096,15 @@ declare class WorkflowService {
      * starts a fresh run of every workflow subscribed via `@Workflow({ onEvent })` / `@OnDurableEvent` (the
      * payload becomes its input). Pass `opts.id` to dedupe redeliveries. Returns how many runs it
      * touched (resumed + started).
+     *
+     * Reliable by default: a publish that touches NOBODY (no live waiter, no subscriber) buffers ONE
+     * copy so a LATER `waitForEvent(name, { match })` still consumes it instead of it being dropped —
+     * see {@link WorkflowEngine.publishEvent}'s full semantics doc. Pass `opts.buffer: false` to opt out.
      */
     publishEvent(name: string, payload: unknown, opts?: {
         id?: string;
+        buffer?: boolean;
     }): Promise<number>;
 }
 
-export { CONTEXT_ACCESSOR, type ContextAccessor, type ContextStore, DEAD_LETTER_METADATA, DURABLE_STEP_METADATA, DURABLE_WORKER_RUNNERS, DeadLetter, DurableModule, type DurableModuleAsyncOptions, type DurableModuleOptions, type DurableRetentionOptions, DurableStartClient, DurableStep, type DurableStepInterceptor, type DurableStepMeta, ENTITY_METADATA, ENTITY_ON_METADATA, Entity, EntityService, IN_APP_RUN_REDIS_WORKER, IN_APP_WORKER_BINDING, IN_APP_WORKER_RUNNERS, IN_APP_WORKER_RUNTIME, type InAppWorkerBinding, InAppWorkerBootstrap, ON_EVENT_METADATA, On, OnDurableEvent, OnEvent, ProxyRunGateway, RUN_GATEWAY, RUN_REDIS_WORKER, type RunLookupStore, type RunRedisWorkerFn, RunRequestResponder, type RunRequestTransport, STEP_INTERCEPTOR_METADATA, Step, StepInterceptor, type StepOptions, StoreRunGateway, TenantEventRepublisher, ThinStepRegistrar, ThinWorkerBootstrap, ThinWorkflowRegistrar, type UserRef, WORKFLOW_METADATA, Workflow, type WorkflowMeta, type WorkflowOptions, WorkflowService, entityConfigFor, getDurableStepMeta, getEntityMeta, getOnEvents, getWorkflowMeta, inAppWorkerProviders, isDeadLetterHandler, isDrivingOperator, isOperatorRole, isStepInterceptor, thinWorkerProviders, unavailableRunGateway };
+export { CONTEXT_ACCESSOR, type ContextAccessor, type ContextStore, DEAD_LETTER_METADATA, DURABLE_STEP_METADATA, DURABLE_WORKER_RUNNERS, DeadLetter, DurableModule, type DurableModuleAsyncOptions, type DurableModuleOptions, type DurableRetentionOptions, DurableStartClient, DurableStep, type DurableStepInterceptor, type DurableStepMeta, ENTITY_METADATA, ENTITY_ON_METADATA, Entity, EntityService, IN_APP_RUN_REDIS_WORKER, IN_APP_WORKER_BINDING, IN_APP_WORKER_RUNNERS, IN_APP_WORKER_RUNTIME, type InAppWorkerBinding, InAppWorkerBootstrap, ON_EVENT_METADATA, On, OnDurableEvent, OnEvent, ProxyRunGateway, RUN_GATEWAY, RUN_REDIS_WORKER, type RunLookupStore, type RunRedisWorkerFn, RunRequestResponder, type RunRequestTransport, STEP_INTERCEPTOR_METADATA, Step, StepInterceptor, type StepOptions, StoreRunGateway, TenantEventRepublisher, ThinStepRegistrar, ThinWorkerBootstrap, ThinWorkflowRegistrar, type UserRef, WORKFLOW_METADATA, Workflow, type WorkflowAttributesOf, type WorkflowMeta, type WorkflowOptions, WorkflowService, attributesOf, entityConfigFor, getDurableStepMeta, getEntityMeta, getOnEvents, getWorkflowMeta, inAppWorkerProviders, isDeadLetterHandler, isDrivingOperator, isOperatorRole, isStepInterceptor, thinWorkerProviders, unavailableRunGateway };

package/dist/index.js

@@ -7,6 +7,9 @@ var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require
   throw Error('Dynamic require of "' + x + '" is not supported');
 });
 
+// src/attributes-of.ts
+import { readSearchAttributes } from "@dudousxd/nestjs-durable-core";
+
 // src/decorators.ts
 import { DURABLE_STEP_CONFIG, DURABLE_STEP_NAME, WORKFLOW_NAME_KEY } from "@dudousxd/nestjs-durable-core";
 import "reflect-metadata";
@@ -114,6 +117,19 @@ function getOnEvents(meta, target) {
 }
 __name(getOnEvents, "getOnEvents");
 
+// src/attributes-of.ts
+function attributesOf(workflow, run) {
+  const meta = getWorkflowMeta(workflow);
+  if (!meta) {
+    throw new Error(`attributesOf: ${workflow.name} is not a @Workflow class \u2014 is it decorated with @Workflow({ name, searchAttributes })?`);
+  }
+  if (!meta.searchAttributes) {
+    throw new Error(`attributesOf: workflow '${meta.name}' declares no searchAttributes schema \u2014 reading attributes by class requires the workflow to declare its schema: @Workflow({ name: '${meta.name}', searchAttributes: mySchema }).`);
+  }
+  return readSearchAttributes(meta.searchAttributes, run);
+}
+__name(attributesOf, "attributesOf");
+
 // src/durable-start-client.ts
 import { startRun } from "@dudousxd/durable-worker";
 import { workflowName } from "@dudousxd/nestjs-durable-core";
@@ -1678,6 +1694,10 @@ var WorkflowService = class {
   * starts a fresh run of every workflow subscribed via `@Workflow({ onEvent })` / `@OnDurableEvent` (the
   * payload becomes its input). Pass `opts.id` to dedupe redeliveries. Returns how many runs it
   * touched (resumed + started).
+  *
+  * Reliable by default: a publish that touches NOBODY (no live waiter, no subscriber) buffers ONE
+  * copy so a LATER `waitForEvent(name, { match })` still consumes it instead of it being dropped —
+  * see {@link WorkflowEngine.publishEvent}'s full semantics doc. Pass `opts.buffer: false` to opt out.
   */
   publishEvent(name, payload, opts) {
     return this.engine.publishEvent(name, payload, opts);
@@ -2054,7 +2074,7 @@ DurableModule = _ts_decorate12([
 ], DurableModule);
 
 // src/index.ts
-import { readSearchAttributes, WorkflowEngine as WorkflowEngine7 } from "@dudousxd/nestjs-durable-core";
+import { readSearchAttributes as readSearchAttributes2, WorkflowEngine as WorkflowEngine7 } from "@dudousxd/nestjs-durable-core";
 export {
   CONTEXT_ACCESSOR,
   DEAD_LETTER_METADATA,
@@ -2093,6 +2113,7 @@ export {
   Workflow,
   WorkflowEngine7 as WorkflowEngine,
   WorkflowService,
+  attributesOf,
   entityConfigFor,
   getDurableStepMeta,
   getEntityMeta,
@@ -2103,7 +2124,7 @@ export {
   isDrivingOperator,
   isOperatorRole,
   isStepInterceptor,
-  readSearchAttributes,
+  readSearchAttributes2 as readSearchAttributes,
   thinWorkerProviders,
   unavailableRunGateway
 };