nestjs-serverless-workflow 0.1.0 → 0.1.3

package/README.md

@@ -154,7 +154,7 @@ The library is organized into tree-shakable subpath exports:
 ```
 nestjs-serverless-workflow/
 ├── core          # Core workflow engine (decorators, services, types, IWorkflowEvent)
-├── adapter       # Durable Lambda adapter for checkpoint/replay execution
+├── adapter       # BaseWorkflowAdapter + Durable Lambda adapter for checkpoint/replay execution
 └── exception     # Custom exception types
 ```
 
@@ -164,8 +164,8 @@ nestjs-serverless-workflow/
 // Core workflow engine
 import { WorkflowModule, IWorkflowEvent } from 'nestjs-serverless-workflow/core';
 
-// Durable Lambda adapter
-import { DurableLambdaEventHandler } from 'nestjs-serverless-workflow/adapter';
+// Adapter — base class + built-in durable Lambda adapter
+import { BaseWorkflowAdapter, DurableLambdaEventHandler } from 'nestjs-serverless-workflow/adapter';
 
 // Exceptions
 import { UnretriableException } from 'nestjs-serverless-workflow/exception';
@@ -180,9 +180,9 @@ The `transit()` method on the orchestrator returns a `TransitResult`, which adap
 ```typescript
 type TransitResult =
   | { status: 'final'; state: string | number }
-  | { status: 'idle'; state: string | number }
+  | { status: 'idle'; state: string | number; timeout?: Duration }
   | { status: 'continued'; nextEvent: IWorkflowEvent }
-  | { status: 'no_transition'; state: string | number };
+  | { status: 'no_transition'; state: string | number; timeout?: Duration };
 ```
 
 - **`final`** -- the workflow has reached a terminal state.
@@ -190,6 +190,44 @@ type TransitResult =
 - **`continued`** -- the workflow auto-transitioned and provides the next event to process.
 - **`no_transition`** -- no matching transition was found from the current state.
 
+## Custom Adapters
+
+Extend `BaseWorkflowAdapter` to plug the orchestrator into any runtime. The base class owns the orchestration loop and dispatches each `TransitResult` variant to a handler method you override:
+
+```typescript
+import { BaseWorkflowAdapter } from 'nestjs-serverless-workflow/adapter';
+import { OrchestratorService } from 'nestjs-serverless-workflow/core';
+import type { IWorkflowEvent, TransitResult } from 'nestjs-serverless-workflow/core';
+
+class MyAdapter extends BaseWorkflowAdapter<MyContext, MyResult> {
+  constructor(orchestrator: OrchestratorService) {
+    super(orchestrator);
+  }
+
+  protected async executeTransit(event: IWorkflowEvent): Promise<TransitResult> {
+    return this.orchestrator.transit(event);
+  }
+
+  protected onFinal(result: Extract<TransitResult, { status: 'final' }>): MyResult {
+    return { status: 'completed', state: result.state };
+  }
+
+  protected async onIdle(result: Extract<TransitResult, { status: 'idle' }>): Promise<IWorkflowEvent> {
+    // Wait for callback, poll a queue, etc.
+  }
+
+  protected async onContinued(result: Extract<TransitResult, { status: 'continued' }>): Promise<IWorkflowEvent> {
+    return result.nextEvent;
+  }
+
+  protected async onNoTransition(result: Extract<TransitResult, { status: 'no_transition' }>): Promise<IWorkflowEvent> {
+    // Wait for an explicit external event
+  }
+}
+```
+
+The built-in `DurableLambdaEventHandler` extends this base with AWS checkpointing and `waitForCallback()` support. See the [Custom Adapter recipe](https://tung-dnt.github.io/nestjs-serverless-workflow/docs/recipes/custom-adapter) for full examples.
+
 ## Examples
 
 Check out the [examples directory](https://github.com/tung-dnt/nestjs-serverless-workflow/tree/main/examples) for complete working examples:

package/dist/adapter/base-workflow.adapter.d.ts

@@ -0,0 +1,38 @@
+import { OrchestratorService, type IWorkflowEvent, type TransitResult } from '../core/index.js';
+/**
+ * Abstract base for workflow adapters.
+ *
+ * Owns the orchestration loop — call `transit()`, dispatch by status, repeat.
+ * Concrete adapters override the handler methods to plug in infrastructure
+ * (checkpointing, callbacks, queues, HTTP responses, etc.).
+ *
+ * @typeParam TContext  - Adapter-specific execution context (e.g. IDurableContext)
+ * @typeParam TResult   - The value returned when the workflow completes
+ */
+export declare abstract class BaseWorkflowAdapter<TContext, TResult> {
+    protected readonly orchestrator: OrchestratorService;
+    constructor(orchestrator: OrchestratorService);
+    /**
+     * Run the workflow loop until a final state is reached.
+     */
+    protected runWorkflowLoop(initialEvent: IWorkflowEvent, ctx: TContext): Promise<TResult>;
+    /** Execute a single transit step (may include retry, checkpointing, etc.) */
+    protected abstract executeTransit(event: IWorkflowEvent, iteration: number, ctx: TContext): Promise<TransitResult>;
+    /** Workflow reached a terminal state — return the final result. */
+    protected abstract onFinal(result: Extract<TransitResult, {
+        status: 'final';
+    }>, event: IWorkflowEvent, ctx: TContext): TResult;
+    /** Entity is idle — wait for an external callback and return the next event. */
+    protected abstract onIdle(result: Extract<TransitResult, {
+        status: 'idle';
+    }>, event: IWorkflowEvent, iteration: number, ctx: TContext): Promise<IWorkflowEvent>;
+    /** Auto-transition found — checkpoint if needed and return the next event. */
+    protected abstract onContinued(result: Extract<TransitResult, {
+        status: 'continued';
+    }>, iteration: number, ctx: TContext): Promise<IWorkflowEvent>;
+    /** No unambiguous transition — wait for an explicit external event. */
+    protected abstract onNoTransition(result: Extract<TransitResult, {
+        status: 'no_transition';
+    }>, event: IWorkflowEvent, iteration: number, ctx: TContext): Promise<IWorkflowEvent>;
+}
+//# sourceMappingURL=base-workflow.adapter.d.ts.map

package/dist/adapter/base-workflow.adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-workflow.adapter.d.ts","sourceRoot":"","sources":["../../packages/adapter/base-workflow.adapter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,KAAK,cAAc,EAAE,KAAK,aAAa,EAAE,MAAM,QAAQ,CAAC;AAEtF;;;;;;;;;GASG;AACH,8BAAsB,mBAAmB,CAAC,QAAQ,EAAE,OAAO;IAC7C,SAAS,CAAC,QAAQ,CAAC,YAAY,EAAE,mBAAmB;IAAhE,YAA+B,YAAY,EAAE,mBAAmB,EAAI;IAEpE;;OAEG;IACH,UAAgB,eAAe,CAAC,YAAY,EAAE,cAAc,EAAE,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC,CA0B7F;IAID,6EAA6E;IAC7E,SAAS,CAAC,QAAQ,CAAC,cAAc,CAAC,KAAK,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IAEnH,qEAAmE;IACnE,SAAS,CAAC,QAAQ,CAAC,OAAO,CACxB,MAAM,EAAE,OAAO,CAAC,aAAa,EAAE;QAAE,MAAM,EAAE,OAAO,CAAA;KAAE,CAAC,EACnD,KAAK,EAAE,cAAc,EACrB,GAAG,EAAE,QAAQ,GACZ,OAAO,CAAC;IAEX,kFAAgF;IAChF,SAAS,CAAC,QAAQ,CAAC,MAAM,CACvB,MAAM,EAAE,OAAO,CAAC,aAAa,EAAE;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,EAClD,KAAK,EAAE,cAAc,EACrB,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,QAAQ,GACZ,OAAO,CAAC,cAAc,CAAC,CAAC;IAE3B,gFAA8E;IAC9E,SAAS,CAAC,QAAQ,CAAC,WAAW,CAC5B,MAAM,EAAE,OAAO,CAAC,aAAa,EAAE;QAAE,MAAM,EAAE,WAAW,CAAA;KAAE,CAAC,EACvD,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,QAAQ,GACZ,OAAO,CAAC,cAAc,CAAC,CAAC;IAE3B,yEAAuE;IACvE,SAAS,CAAC,QAAQ,CAAC,cAAc,CAC/B,MAAM,EAAE,OAAO,CAAC,aAAa,EAAE;QAAE,MAAM,EAAE,eAAe,CAAA;KAAE,CAAC,EAC3D,KAAK,EAAE,cAAc,EACrB,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,QAAQ,GACZ,OAAO,CAAC,cAAc,CAAC,CAAC;CAC5B"}

package/dist/adapter/base-workflow.adapter.js

@@ -0,0 +1,42 @@
+import { OrchestratorService } from '../core/index.js';
+/**
+ * Abstract base for workflow adapters.
+ *
+ * Owns the orchestration loop — call `transit()`, dispatch by status, repeat.
+ * Concrete adapters override the handler methods to plug in infrastructure
+ * (checkpointing, callbacks, queues, HTTP responses, etc.).
+ *
+ * @typeParam TContext  - Adapter-specific execution context (e.g. IDurableContext)
+ * @typeParam TResult   - The value returned when the workflow completes
+ */
+export class BaseWorkflowAdapter {
+    orchestrator;
+    constructor(orchestrator) {
+        this.orchestrator = orchestrator;
+    }
+    /**
+     * Run the workflow loop until a final state is reached.
+     */
+    async runWorkflowLoop(initialEvent, ctx) {
+        let currentEvent = initialEvent;
+        let iteration = 0;
+        while (true) {
+            const result = await this.executeTransit(currentEvent, iteration, ctx);
+            switch (result.status) {
+                case 'final':
+                    return this.onFinal(result, currentEvent, ctx);
+                case 'idle':
+                    currentEvent = await this.onIdle(result, currentEvent, iteration, ctx);
+                    break;
+                case 'continued':
+                    currentEvent = await this.onContinued(result, iteration, ctx);
+                    break;
+                case 'no_transition':
+                    currentEvent = await this.onNoTransition(result, currentEvent, iteration, ctx);
+                    break;
+            }
+            iteration++;
+        }
+    }
+}
+//# sourceMappingURL=base-workflow.adapter.js.map

package/dist/adapter/base-workflow.adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-workflow.adapter.js","sourceRoot":"","sources":["../../packages/adapter/base-workflow.adapter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAA2C,MAAM,QAAQ,CAAC;AAEtF;;;;;;;;;GASG;AACH,MAAM,OAAgB,mBAAmB;IACR,YAAY;IAA3C,YAA+B,YAAiC,EAAE;4BAAnC,YAAY;IAAwB,CAAC;IAEpE;;OAEG;IACO,KAAK,CAAC,eAAe,CAAC,YAA4B,EAAE,GAAa,EAAoB;QAC7F,IAAI,YAAY,GAAG,YAAY,CAAC;QAChC,IAAI,SAAS,GAAG,CAAC,CAAC;QAElB,OAAO,IAAI,EAAE,CAAC;YACZ,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,cAAc,CAAC,YAAY,EAAE,SAAS,EAAE,GAAG,CAAC,CAAC;YAEvE,QAAQ,MAAM,CAAC,MAAM,EAAE,CAAC;gBACtB,KAAK,OAAO;oBACV,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,YAAY,EAAE,GAAG,CAAC,CAAC;gBAEjD,KAAK,MAAM;oBACT,YAAY,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,YAAY,EAAE,SAAS,EAAE,GAAG,CAAC,CAAC;oBACvE,MAAM;gBAER,KAAK,WAAW;oBACd,YAAY,GAAG,MAAM,IAAI,CAAC,WAAW,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,CAAC,CAAC;oBAC9D,MAAM;gBAER,KAAK,eAAe;oBAClB,YAAY,GAAG,MAAM,IAAI,CAAC,cAAc,CAAC,MAAM,EAAE,YAAY,EAAE,SAAS,EAAE,GAAG,CAAC,CAAC;oBAC/E,MAAM;YACV,CAAC;YAED,SAAS,EAAE,CAAC;QACd,CAAC;IAAA,CACF;CAoCF"}

package/dist/adapter/durable-lambda.adapter.d.ts

@@ -47,9 +47,5 @@ export type WithDurableExecution = <TEvent, TResult>(handler: (event: TEvent, ct
  * @param app - NestJS application context
  * @param withDurableExecution - The `withDurableExecution` function from `@aws/durable-execution-sdk-js`
  */
-export declare const DurableLambdaEventHandler: (app: INestApplicationContext, withDurableExecution: WithDurableExecution) => (event: DurableWorkflowEvent, ctx: any) => Promise<{
-    urn: string | number;
-    status: string;
-    state: string | number;
-}>;
+export declare const DurableLambdaEventHandler: (app: INestApplicationContext, withDurableExecution: WithDurableExecution) => (event: DurableWorkflowEvent, ctx: any) => Promise<DurableWorkflowResult>;
 //# sourceMappingURL=durable-lambda.adapter.d.ts.map

package/dist/adapter/durable-lambda.adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"durable-lambda.adapter.d.ts","sourceRoot":"","sources":["../../packages/adapter/durable-lambda.adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC;AAI9D,MAAM,WAAW,oBAAoB;IACnC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,GAAG,CAAC;CACf;AAED,MAAM,WAAW,qBAAqB;IACpC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;CACxB;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACxD,eAAe,CAAC,CAAC,EACf,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,EACjD,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE;YAAE,KAAK,CAAC,EAAE,MAAM,CAAC;YAAC,OAAO,CAAC,EAAE,MAAM,CAAC;YAAC,OAAO,CAAC,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,GAC7E,OAAO,CAAC,CAAC,CAAC,CAAC;IACd,IAAI,CAAC,QAAQ,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtF,MAAM,EAAE;QAAE,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG,GAAG,IAAI,CAAA;KAAE,CAAC;CACjD;AAED;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,MAAM,EAAE,OAAO,EACjD,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,eAAe,KAAK,OAAO,CAAC,OAAO,CAAC,KAC/D,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;AAmBnD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,yBAAyB;;;;EAyErC,CAAC"}
+{"version":3,"file":"durable-lambda.adapter.d.ts","sourceRoot":"","sources":["../../packages/adapter/durable-lambda.adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC;AAK9D,MAAM,WAAW,oBAAoB;IACnC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,GAAG,CAAC;CACf;AAED,MAAM,WAAW,qBAAqB;IACpC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;CACxB;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACxD,eAAe,CAAC,CAAC,EACf,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,EACjD,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE;YAAE,KAAK,CAAC,EAAE,MAAM,CAAC;YAAC,OAAO,CAAC,EAAE,MAAM,CAAC;YAAC,OAAO,CAAC,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,GAC7E,OAAO,CAAC,CAAC,CAAC,CAAC;IACd,IAAI,CAAC,QAAQ,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtF,MAAM,EAAE;QAAE,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG,GAAG,IAAI,CAAA;KAAE,CAAC;CACjD;AAED;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,MAAM,EAAE,OAAO,EACjD,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,eAAe,KAAK,OAAO,CAAC,OAAO,CAAC,KAC/D,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;AA6InD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,yBAAyB,yJAOrC,CAAC"}

package/dist/adapter/durable-lambda.adapter.js

@@ -1,5 +1,6 @@
 import { OrchestratorService, RetryBackoff } from '../core/index.js';
 import { UnretriableException } from '../exception/unretriable.exception.js';
+import { BaseWorkflowAdapter } from './base-workflow.adapter.js';
 const DEFAULT_CALLBACK_TIMEOUT = { hours: 24 };
 /**
  * Parse a callback result from the SDK.
@@ -16,6 +17,84 @@ function parseCallbackResult(raw) {
     }
     return raw;
 }
+/**
+ * Concrete adapter that wraps the workflow orchestrator in an AWS durable execution.
+ *
+ * Each workflow instance runs as a single durable execution spanning multiple Lambda invocations.
+ * Steps are checkpointed at event boundaries — on replay, completed steps return stored results.
+ */
+class DurableLambdaWorkflowAdapter extends BaseWorkflowAdapter {
+    urn;
+    constructor(orchestrator) {
+        super(orchestrator);
+    }
+    async run(event, ctx) {
+        this.urn = event.urn;
+        const initialEvent = {
+            event: event.initialEvent,
+            urn: event.urn,
+            payload: event.payload,
+            attempt: 0,
+        };
+        return this.runWorkflowLoop(initialEvent, ctx);
+    }
+    async executeTransit(currentEvent, iteration, ctx) {
+        const retryConfig = this.orchestrator.getRetryConfig(currentEvent.event);
+        const maxAttempts = retryConfig?.maxAttempts ?? 1;
+        let lastError;
+        for (let attempt = 0; attempt < maxAttempts; attempt++) {
+            try {
+                return await ctx.step(`transit:${currentEvent.event}:${iteration}:${attempt}`, () => this.orchestrator.transit(currentEvent));
+            }
+            catch (e) {
+                if (e instanceof UnretriableException)
+                    throw e;
+                lastError = e;
+                if (attempt < maxAttempts - 1) {
+                    const delay = RetryBackoff.calculateDelay(attempt, retryConfig);
+                    ctx.logger.info(`Handler ${currentEvent.event} failed (attempt ${attempt + 1}/${maxAttempts}), retrying in ${delay}ms`);
+                    await ctx.wait({ seconds: Math.ceil(delay / 1000) });
+                }
+            }
+        }
+        throw lastError;
+    }
+    // TODO: review adapter hooks' logic
+    onFinal(result, _event, _ctx) {
+        return { urn: this.urn, status: 'completed', state: result.state };
+    }
+    async onIdle(result, _event, iteration, ctx) {
+        const timeout = result.timeout ?? DEFAULT_CALLBACK_TIMEOUT;
+        const raw = await ctx.waitForCallback(`idle:${result.state}:${iteration}`, async (callbackId) => {
+            ctx.logger.info(`Waiting for callback at idle state ${result.state}`, { callbackId });
+        }, { timeout });
+        const callbackPayload = parseCallbackResult(raw);
+        return {
+            event: callbackPayload.event,
+            urn: this.urn,
+            payload: callbackPayload.payload,
+            attempt: 0,
+        };
+    }
+    async onContinued(result, iteration, ctx) {
+        // Checkpoint the progression — on replay, returns stored result
+        await ctx.step(`${result.nextEvent.event}:${iteration}`, async () => result.nextEvent);
+        return result.nextEvent;
+    }
+    async onNoTransition(result, _event, iteration, ctx) {
+        const timeout = result.timeout ?? DEFAULT_CALLBACK_TIMEOUT;
+        const raw = await ctx.waitForCallback(`awaiting:${result.state}:${iteration}`, async (callbackId) => {
+            ctx.logger.info(`No auto-transition from ${result.state}, waiting for explicit event`, { callbackId });
+        }, { timeout });
+        const noTransitionPayload = parseCallbackResult(raw);
+        return {
+            event: noTransitionPayload.event,
+            urn: this.urn,
+            payload: noTransitionPayload.payload,
+            attempt: 0,
+        };
+    }
+}
 /**
  * Creates a Lambda handler that wraps the workflow orchestrator in a durable execution.
  *
@@ -30,84 +109,9 @@ function parseCallbackResult(raw) {
  */
 export const DurableLambdaEventHandler = (app, withDurableExecution) => {
     const orchestrator = app.get(OrchestratorService);
+    const adapter = new DurableLambdaWorkflowAdapter(orchestrator);
     return withDurableExecution(async (event, ctx) => {
-        let currentEvent = {
-            event: event.initialEvent,
-            urn: event.urn,
-            payload: event.payload,
-            attempt: 0,
-        };
-        let iteration = 0;
-        while (true) {
-            const result = await transitWithRetry(orchestrator, currentEvent, iteration, ctx);
-            switch (result.status) {
-                case 'final':
-                    return { urn: event.urn, status: 'completed', state: result.state };
-                case 'idle': {
-                    const timeout = result.timeout ?? DEFAULT_CALLBACK_TIMEOUT;
-                    const raw = await ctx.waitForCallback(`idle:${result.state}:${iteration}`, async (callbackId) => {
-                        // External systems use this callbackId to resume the workflow
-                        // via SendDurableExecutionCallbackSuccess Lambda API
-                        ctx.logger.info(`Waiting for callback at idle state ${result.state}`, { callbackId });
-                    }, { timeout });
-                    const callbackPayload = parseCallbackResult(raw);
-                    currentEvent = {
-                        event: callbackPayload.event,
-                        urn: event.urn,
-                        payload: callbackPayload.payload,
-                        attempt: 0,
-                    };
-                    break;
-                }
-                case 'continued': {
-                    // Checkpoint the progression — on replay, returns stored result
-                    await ctx.step(`${result.nextEvent.event}:${iteration}`, async () => result.nextEvent);
-                    currentEvent = result.nextEvent;
-                    break;
-                }
-                case 'no_transition': {
-                    const timeout = result.timeout ?? DEFAULT_CALLBACK_TIMEOUT;
-                    // No unambiguous auto-transition — wait for explicit event via callback
-                    const raw = await ctx.waitForCallback(`awaiting:${result.state}:${iteration}`, async (callbackId) => {
-                        ctx.logger.info(`No auto-transition from ${result.state}, waiting for explicit event`, { callbackId });
-                    }, { timeout });
-                    const noTransitionPayload = parseCallbackResult(raw);
-                    currentEvent = {
-                        event: noTransitionPayload.event,
-                        urn: event.urn,
-                        payload: noTransitionPayload.payload,
-                        attempt: 0,
-                    };
-                    break;
-                }
-            }
-            iteration++;
-        }
+        return adapter.run(event, ctx);
     });
 };
-/**
- * Wraps `orchestrator.transit()` with retry logic when the handler has `@WithRetry()` config.
- * Each attempt is checkpointed via `ctx.step()` so replays skip completed attempts.
- */
-async function transitWithRetry(orchestrator, currentEvent, iteration, ctx) {
-    const retryConfig = orchestrator.getRetryConfig(currentEvent.event);
-    const maxAttempts = retryConfig?.maxAttempts ?? 1;
-    let lastError;
-    for (let attempt = 0; attempt < maxAttempts; attempt++) {
-        try {
-            return await ctx.step(`transit:${currentEvent.event}:${iteration}:${attempt}`, () => orchestrator.transit(currentEvent));
-        }
-        catch (e) {
-            if (e instanceof UnretriableException)
-                throw e;
-            lastError = e;
-            if (attempt < maxAttempts - 1) {
-                const delay = RetryBackoff.calculateDelay(attempt, retryConfig);
-                ctx.logger.info(`Handler ${currentEvent.event} failed (attempt ${attempt + 1}/${maxAttempts}), retrying in ${delay}ms`);
-                await ctx.wait({ seconds: Math.ceil(delay / 1000) });
-            }
-        }
-    }
-    throw lastError;
-}
 //# sourceMappingURL=durable-lambda.adapter.js.map

package/dist/adapter/durable-lambda.adapter.js.map

@@ -1 +1 @@
-{"version":3,"file":"durable-lambda.adapter.js","sourceRoot":"","sources":["../../packages/adapter/durable-lambda.adapter.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"durable-lambda.adapter.js","sourceRoot":"","sources":["../../packages/adapter/durable-lambda.adapter.ts"],"names":[],"mappings":"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"}

package/dist/adapter/index.d.ts

@@ -1,2 +1,3 @@
+export * from './base-workflow.adapter.js';
 export * from './durable-lambda.adapter.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/adapter/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../packages/adapter/index.ts"],"names":[],"mappings":"AAAA,cAAc,0BAA0B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../packages/adapter/index.ts"],"names":[],"mappings":"AAAA,cAAc,yBAAyB,CAAC;AACxC,cAAc,0BAA0B,CAAC"}

package/dist/adapter/index.js

@@ -1,2 +1,3 @@
+export * from './base-workflow.adapter.js';
 export * from './durable-lambda.adapter.js';
 //# sourceMappingURL=index.js.map

package/dist/adapter/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../packages/adapter/index.ts"],"names":[],"mappings":"AAAA,cAAc,0BAA0B,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../packages/adapter/index.ts"],"names":[],"mappings":"AAAA,cAAc,yBAAyB,CAAC;AACxC,cAAc,0BAA0B,CAAC"}

package/dist/core/decorators/default.decorator.d.ts

@@ -1,3 +1,20 @@
+/** @internal Metadata key for the default (fallback) handler. */
 export declare const WORKFLOW_DEFAULT_EVENT = "workflow.default";
+/**
+ * Method decorator that marks a handler as the fallback for unmatched events.
+ *
+ * When the orchestrator cannot find a valid transition for an incoming event,
+ * it invokes the method decorated with `@OnDefault` before throwing.
+ * Only one default handler per workflow class is allowed — subsequent
+ * decorations are silently ignored.
+ *
+ * @example
+ * ```typescript
+ * @OnDefault
+ * async fallback(entity: Order, event: string, payload?: any) {
+ *   logger.warn(`Unhandled event ${event} for order ${entity.id}`);
+ * }
+ * ```
+ */
 export declare const OnDefault: (target: any, _propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
 //# sourceMappingURL=default.decorator.d.ts.map

package/dist/core/decorators/default.decorator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"default.decorator.d.ts","sourceRoot":"","sources":["../../../packages/core/decorators/default.decorator.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,sBAAsB,qBAAqB,CAAC;AAEzD,eAAO,MAAM,SAAS,2FAMrB,CAAC"}
+{"version":3,"file":"default.decorator.d.ts","sourceRoot":"","sources":["../../../packages/core/decorators/default.decorator.ts"],"names":[],"mappings":"AAAA,iEAAiE;AACjE,eAAO,MAAM,sBAAsB,qBAAqB,CAAC;AAEzD;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,SAAS,2FAMrB,CAAC"}

package/dist/core/decorators/default.decorator.js

@@ -1,4 +1,21 @@
+/** @internal Metadata key for the default (fallback) handler. */
 export const WORKFLOW_DEFAULT_EVENT = 'workflow.default';
+/**
+ * Method decorator that marks a handler as the fallback for unmatched events.
+ *
+ * When the orchestrator cannot find a valid transition for an incoming event,
+ * it invokes the method decorated with `@OnDefault` before throwing.
+ * Only one default handler per workflow class is allowed — subsequent
+ * decorations are silently ignored.
+ *
+ * @example
+ * ```typescript
+ * @OnDefault
+ * async fallback(entity: Order, event: string, payload?: any) {
+ *   logger.warn(`Unhandled event ${event} for order ${entity.id}`);
+ * }
+ * ```
+ */
 export const OnDefault = (target, _propertyKey, descriptor) => {
     const existingFallback = Reflect.getMetadata(WORKFLOW_DEFAULT_EVENT, target.constructor);
     if (!existingFallback) {

package/dist/core/decorators/default.decorator.js.map

@@ -1 +1 @@
-{"version":3,"file":"default.decorator.js","sourceRoot":"","sources":["../../../packages/core/decorators/default.decorator.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,sBAAsB,GAAG,kBAAkB,CAAC;AAEzD,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,MAAW,EAAE,YAAoB,EAAE,UAA8B,EAAE,EAAE,CAAC;IAC9F,MAAM,gBAAgB,GAAG,OAAO,CAAC,WAAW,CAAC,sBAAsB,EAAE,MAAM,CAAC,WAAW,CAAC,CAAC;IACzF,IAAI,CAAC,gBAAgB,EAAE,CAAC;QACtB,OAAO,CAAC,cAAc,CAAC,sBAAsB,EAAE,UAAU,CAAC,KAAK,EAAE,MAAM,CAAC,WAAW,CAAC,CAAC;IACvF,CAAC;IACD,OAAO,UAAU,CAAC;AAAA,CACnB,CAAC"}
+{"version":3,"file":"default.decorator.js","sourceRoot":"","sources":["../../../packages/core/decorators/default.decorator.ts"],"names":[],"mappings":"AAAA,iEAAiE;AACjE,MAAM,CAAC,MAAM,sBAAsB,GAAG,kBAAkB,CAAC;AAEzD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,MAAW,EAAE,YAAoB,EAAE,UAA8B,EAAE,EAAE,CAAC;IAC9F,MAAM,gBAAgB,GAAG,OAAO,CAAC,WAAW,CAAC,sBAAsB,EAAE,MAAM,CAAC,WAAW,CAAC,CAAC;IACzF,IAAI,CAAC,gBAAgB,EAAE,CAAC;QACtB,OAAO,CAAC,cAAc,CAAC,sBAAsB,EAAE,UAAU,CAAC,KAAK,EAAE,MAAM,CAAC,WAAW,CAAC,CAAC;IACvF,CAAC;IACD,OAAO,UAAU,CAAC;AAAA,CACnB,CAAC"}

package/dist/core/decorators/event.decorator.d.ts

@@ -1,3 +1,21 @@
+/** @internal Metadata key for the list of event handlers on a workflow class. */
 export declare const WORKFLOW_HANDLER_KEY = "workflow:metadata";
+/**
+ * Method decorator that registers a handler for a specific workflow event.
+ *
+ * The event name must match a transition's `event` field in the workflow
+ * definition. The orchestrator discovers these handlers at module init
+ * and routes incoming {@link IWorkflowEvent}s to the correct method.
+ *
+ * @param event - The event name this method handles (e.g. `'order.submit'`).
+ *
+ * @example
+ * ```typescript
+ * @OnEvent('order.submit')
+ * async onSubmit(@Entity() order: Order, @Payload() data: SubmitDto) {
+ *   // transition logic
+ * }
+ * ```
+ */
 export declare const OnEvent: (event: string) => (target: any, propertyKey: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
 //# sourceMappingURL=event.decorator.d.ts.map

package/dist/core/decorators/event.decorator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"event.decorator.d.ts","sourceRoot":"","sources":["../../../packages/core/decorators/event.decorator.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,oBAAoB,sBAAsB,CAAC;AAExD,eAAO,MAAM,OAAO,6GAWnB,CAAC"}
+{"version":3,"file":"event.decorator.d.ts","sourceRoot":"","sources":["../../../packages/core/decorators/event.decorator.ts"],"names":[],"mappings":"AAEA,iFAAiF;AACjF,eAAO,MAAM,oBAAoB,sBAAsB,CAAC;AAExD;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,OAAO,6GAWnB,CAAC"}

package/dist/core/decorators/event.decorator.js

@@ -1,4 +1,22 @@
+/** @internal Metadata key for the list of event handlers on a workflow class. */
 export const WORKFLOW_HANDLER_KEY = 'workflow:metadata';
+/**
+ * Method decorator that registers a handler for a specific workflow event.
+ *
+ * The event name must match a transition's `event` field in the workflow
+ * definition. The orchestrator discovers these handlers at module init
+ * and routes incoming {@link IWorkflowEvent}s to the correct method.
+ *
+ * @param event - The event name this method handles (e.g. `'order.submit'`).
+ *
+ * @example
+ * ```typescript
+ * @OnEvent('order.submit')
+ * async onSubmit(@Entity() order: Order, @Payload() data: SubmitDto) {
+ *   // transition logic
+ * }
+ * ```
+ */
 export const OnEvent = (event) => (target, propertyKey, descriptor) => {
     let workflowHandlers = Reflect.getMetadata(WORKFLOW_HANDLER_KEY, target.constructor);
     if (!workflowHandlers) {

package/dist/core/decorators/event.decorator.js.map

@@ -1 +1 @@
-{"version":3,"file":"event.decorator.js","sourceRoot":"","sources":["../../../packages/core/decorators/event.decorator.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,oBAAoB,GAAG,mBAAmB,CAAC;AAExD,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,KAAa,EAAE,EAAE,CAAC,CAAC,MAAW,EAAE,WAAmB,EAAE,UAA8B,EAAE,EAAE,CAAC;IAC9G,IAAI,gBAAgB,GAAuB,OAAO,CAAC,WAAW,CAAC,oBAAoB,EAAE,MAAM,CAAC,WAAW,CAAC,CAAC;IAEzG,IAAI,CAAC,gBAAgB,EAAE,CAAC;QACtB,gBAAgB,GAAG,EAAE,CAAC;QACtB,OAAO,CAAC,cAAc,CAAC,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,CAAC,WAAW,CAAC,CAAC;IACrF,CAAC;IAED,gBAAgB,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,UAAU,CAAC,KAAK,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC,CAAC;IAE/E,OAAO,UAAU,CAAC;AAAA,CACnB,CAAC"}
+{"version":3,"file":"event.decorator.js","sourceRoot":"","sources":["../../../packages/core/decorators/event.decorator.ts"],"names":[],"mappings":"AAEA,iFAAiF;AACjF,MAAM,CAAC,MAAM,oBAAoB,GAAG,mBAAmB,CAAC;AAExD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,KAAa,EAAE,EAAE,CAAC,CAAC,MAAW,EAAE,WAAmB,EAAE,UAA8B,EAAE,EAAE,CAAC;IAC9G,IAAI,gBAAgB,GAAuB,OAAO,CAAC,WAAW,CAAC,oBAAoB,EAAE,MAAM,CAAC,WAAW,CAAC,CAAC;IAEzG,IAAI,CAAC,gBAAgB,EAAE,CAAC;QACtB,gBAAgB,GAAG,EAAE,CAAC;QACtB,OAAO,CAAC,cAAc,CAAC,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,CAAC,WAAW,CAAC,CAAC;IACrF,CAAC;IAED,gBAAgB,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,UAAU,CAAC,KAAK,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC,CAAC;IAE/E,OAAO,UAAU,CAAC;AAAA,CACnB,CAAC"}

package/dist/core/decorators/params.decorator.d.ts

@@ -1,3 +1,30 @@
+/**
+ * Parameter decorator that injects the current workflow entity into a handler method.
+ *
+ * The entity is loaded via the {@link IWorkflowEntity.load} method of the
+ * entity service registered in the workflow definition.
+ *
+ * @example
+ * ```typescript
+ * @OnEvent('order.submit')
+ * async onSubmit(@Entity() order: Order) { ... }
+ * ```
+ */
 export declare function Entity(): ParameterDecorator;
+/**
+ * Parameter decorator that injects the event payload into a handler method.
+ *
+ * The payload comes from the `payload` field of the incoming
+ * {@link IWorkflowEvent}, or from the return value of the previous handler
+ * when auto-transitioning (`continued` status).
+ *
+ * @param dto - Optional DTO class for validation (reserved for future use).
+ *
+ * @example
+ * ```typescript
+ * @OnEvent('order.submit')
+ * async onSubmit(@Entity() order: Order, @Payload() data: SubmitDto) { ... }
+ * ```
+ */
 export declare function Payload<P>(dto?: P): ParameterDecorator;
 //# sourceMappingURL=params.decorator.d.ts.map

package/dist/core/decorators/params.decorator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"params.decorator.d.ts","sourceRoot":"","sources":["../../../packages/core/decorators/params.decorator.ts"],"names":[],"mappings":"AAAA,wBAAgB,MAAM,IAAI,kBAAkB,CAQ3C;AAED,wBAAgB,OAAO,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,GAAG,kBAAkB,CAQtD"}
+{"version":3,"file":"params.decorator.d.ts","sourceRoot":"","sources":["../../../packages/core/decorators/params.decorator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,wBAAgB,MAAM,IAAI,kBAAkB,CAQ3C;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,GAAG,kBAAkB,CAQtD"}

package/dist/core/decorators/params.decorator.js

@@ -1,3 +1,15 @@
+/**
+ * Parameter decorator that injects the current workflow entity into a handler method.
+ *
+ * The entity is loaded via the {@link IWorkflowEntity.load} method of the
+ * entity service registered in the workflow definition.
+ *
+ * @example
+ * ```typescript
+ * @OnEvent('order.submit')
+ * async onSubmit(@Entity() order: Order) { ... }
+ * ```
+ */
 export function Entity() {
     return (target, propertyKey, parameterIndex) => {
         if (!propertyKey || parameterIndex === undefined)
@@ -7,6 +19,21 @@ export function Entity() {
         Reflect.defineMetadata('workflow:params', existing, target, propertyKey);
     };
 }
+/**
+ * Parameter decorator that injects the event payload into a handler method.
+ *
+ * The payload comes from the `payload` field of the incoming
+ * {@link IWorkflowEvent}, or from the return value of the previous handler
+ * when auto-transitioning (`continued` status).
+ *
+ * @param dto - Optional DTO class for validation (reserved for future use).
+ *
+ * @example
+ * ```typescript
+ * @OnEvent('order.submit')
+ * async onSubmit(@Entity() order: Order, @Payload() data: SubmitDto) { ... }
+ * ```
+ */
 export function Payload(dto) {
     return (target, propertyKey, parameterIndex) => {
         if (!propertyKey || parameterIndex === undefined)

package/dist/core/decorators/params.decorator.js.map

@@ -1 +1 @@
-{"version":3,"file":"params.decorator.js","sourceRoot":"","sources":["../../../packages/core/decorators/params.decorator.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,MAAM,GAAuB;IAC3C,OAAO,CAAC,MAAc,EAAE,WAA6B,EAAE,cAAuB,EAAE,EAAE,CAAC;QACjF,IAAI,CAAC,WAAW,IAAI,cAAc,KAAK,SAAS;YAC9C,MAAM,IAAI,KAAK,CAAC,wDAAwD,CAAC,CAAC;QAC5E,MAAM,QAAQ,GAAe,OAAO,CAAC,cAAc,CAAC,iBAAiB,EAAE,MAAM,EAAE,WAAW,CAAC,IAAI,EAAE,CAAC;QAClG,QAAQ,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,cAAc,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAC;QACzD,OAAO,CAAC,cAAc,CAAC,iBAAiB,EAAE,QAAQ,EAAE,MAAM,EAAE,WAAW,CAAC,CAAC;IAAA,CAC1E,CAAC;AAAA,CACH;AAED,MAAM,UAAU,OAAO,CAAI,GAAO,EAAsB;IACtD,OAAO,CAAC,MAAc,EAAE,WAA6B,EAAE,cAAuB,EAAE,EAAE,CAAC;QACjF,IAAI,CAAC,WAAW,IAAI,cAAc,KAAK,SAAS;YAC9C,MAAM,IAAI,KAAK,CAAC,yDAAyD,CAAC,CAAC;QAC7E,MAAM,QAAQ,GAAe,OAAO,CAAC,cAAc,CAAC,iBAAiB,EAAE,MAAM,EAAE,WAAW,CAAC,IAAI,EAAE,CAAC;QAClG,QAAQ,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,cAAc,EAAE,IAAI,EAAE,SAAS,EAAE,GAAG,EAAE,CAAC,CAAC;QAC/D,OAAO,CAAC,cAAc,CAAC,iBAAiB,EAAE,QAAQ,EAAE,MAAM,EAAE,WAAW,CAAC,CAAC;IAAA,CAC1E,CAAC;AAAA,CACH"}
+{"version":3,"file":"params.decorator.js","sourceRoot":"","sources":["../../../packages/core/decorators/params.decorator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,MAAM,GAAuB;IAC3C,OAAO,CAAC,MAAc,EAAE,WAA6B,EAAE,cAAuB,EAAE,EAAE,CAAC;QACjF,IAAI,CAAC,WAAW,IAAI,cAAc,KAAK,SAAS;YAC9C,MAAM,IAAI,KAAK,CAAC,wDAAwD,CAAC,CAAC;QAC5E,MAAM,QAAQ,GAAe,OAAO,CAAC,cAAc,CAAC,iBAAiB,EAAE,MAAM,EAAE,WAAW,CAAC,IAAI,EAAE,CAAC;QAClG,QAAQ,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,cAAc,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,CAAC;QACzD,OAAO,CAAC,cAAc,CAAC,iBAAiB,EAAE,QAAQ,EAAE,MAAM,EAAE,WAAW,CAAC,CAAC;IAAA,CAC1E,CAAC;AAAA,CACH;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,OAAO,CAAI,GAAO,EAAsB;IACtD,OAAO,CAAC,MAAc,EAAE,WAA6B,EAAE,cAAuB,EAAE,EAAE,CAAC;QACjF,IAAI,CAAC,WAAW,IAAI,cAAc,KAAK,SAAS;YAC9C,MAAM,IAAI,KAAK,CAAC,yDAAyD,CAAC,CAAC;QAC7E,MAAM,QAAQ,GAAe,OAAO,CAAC,cAAc,CAAC,iBAAiB,EAAE,MAAM,EAAE,WAAW,CAAC,IAAI,EAAE,CAAC;QAClG,QAAQ,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,cAAc,EAAE,IAAI,EAAE,SAAS,EAAE,GAAG,EAAE,CAAC,CAAC;QAC/D,OAAO,CAAC,cAAc,CAAC,iBAAiB,EAAE,QAAQ,EAAE,MAAM,EAAE,WAAW,CAAC,CAAC;IAAA,CAC1E,CAAC;AAAA,CACH"}