@lafken/state-machine 0.10.1

package/LICENCE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Aníbal Emilio Jorquera Cornejo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,383 @@
+# @lafken/state-machine
+
+Define AWS Step Functions state machines using TypeScript decorators. `@lafken/state-machine` lets you declare states, transitions, service integrations, and nested workflows directly within your classes — no raw JSON or ASL required.
+
+> [!NOTE]
+> This library exclusively supports **JSONata** for data transformation and querying. **JSONPath is not supported**.
+
+## Installation
+
+```bash
+npm install @lafken/state-machine
+```
+
+## Getting Started
+
+Register the `StateMachineResolver` in your application and define your first workflow:
+
+```typescript
+import { createApp, createModule } from '@lafken/main';
+import { StateMachineResolver } from '@lafken/state-machine/resolver';
+import { StateMachine, State, Event } from '@lafken/state-machine/main';
+
+// 1. Define the state machine
+@StateMachine({
+  startAt: 'processOrder',
+})
+class OrderWorkflow {
+  @State({ next: 'notifyCustomer' })
+  processOrder(@Event('{% $states.input %}') order: any) {
+    return { orderId: order.id, status: 'processed' };
+  }
+
+  @State({ end: true })
+  notifyCustomer(@Event('{% $states.input %}') data: any) {
+    console.log(`Order ${data.orderId} completed`);
+  }
+}
+
+// 2. Register it in a module
+const orderModule = createModule({
+  name: 'orders',
+  resources: [OrderWorkflow],
+});
+
+// 3. Add the resolver to your app
+createApp({
+  name: 'my-app',
+  resolvers: [new StateMachineResolver()],
+  modules: [orderModule],
+});
+```
+
+## Features
+
+### Defining a State Machine
+
+Use the `@StateMachine` decorator to mark a class as a state machine resource. The `startAt` property defines the entry point of the workflow and must reference either a method name or an inline state definition.
+
+```typescript
+import { StateMachine, State } from '@lafken/state-machine/main';
+
+@StateMachine({
+  startAt: 'validate',
+})
+export class PaymentWorkflow {
+  @State({ next: 'charge' })
+  validate(@Event('{% $states.input %}') input: any) {
+    return { amount: input.amount, valid: true };
+  }
+
+  @State({ end: true })
+  charge(@Event('{% $states.input %}') input: any) {
+    return { charged: input.amount };
+  }
+}
+```
+
+You can also start with a declarative state instead of a Lambda task:
+
+```typescript
+@StateMachine({
+  startAt: {
+    type: 'wait',
+    seconds: 5,
+    next: { type: 'succeed' },
+  },
+})
+export class DelayedWorkflow {}
+```
+
+### Lambda Tasks
+
+The `@State` decorator turns a method into a Lambda-backed task within the state machine. Step Functions will invoke the Lambda automatically during execution.
+
+Use `next` to chain to the following state, or `end: true` to mark it as a terminal state:
+
+```typescript
+@StateMachine({ startAt: 'enrich' })
+export class DataPipeline {
+  @State({ next: 'store' })
+  enrich(@Event('{% $states.input %}') record: any) {
+    return { ...record, enrichedAt: new Date().toISOString() };
+  }
+
+  @State({ end: true })
+  store(@Event('{% $states.input %}') record: any) {
+    console.log('Storing record:', record);
+  }
+}
+```
+
+#### Output Transformation
+
+Use the `output` option to transform a state's result before passing it to the next state. It accepts a JSONata expression or a plain object:
+
+```typescript
+@State({
+  next: 'process',
+  output: '{% $states.result.data %}',
+})
+fetchData() {
+  return { data: { items: [1, 2, 3] }, metadata: {} };
+}
+```
+
+#### State Assignment
+
+Use `assign` to add or update values in the state machine context. Assigned values persist across subsequent states:
+
+```typescript
+@State({
+  next: 'sendEmail',
+  assign: { attemptCount: '{% $states.input.attemptCount + 1 %}' },
+})
+retry(@Event('{% $states.input %}') input: any) {
+  return input;
+}
+```
+
+### AWS Service Integrations
+
+Instead of invoking a Lambda function, a state can directly call an AWS service API. Use the `integrationResource` property to specify the service ARN, and the `@IntegrationOptions` decorator to access resource references.
+
+This pattern eliminates the need for intermediate Lambda functions when you just need to call an AWS service (DynamoDB, SQS, SNS, etc.).
+
+```typescript
+import {
+  StateMachine,
+  State,
+  Event,
+  type IntegrationOptionsParams,
+} from '@lafken/state-machine/main';
+import { IntegrationOptions } from '@lafken/api/main';
+
+@StateMachine({
+  startAt: 'saveItem',
+  services: ['dynamodb'],
+})
+export class InventoryWorkflow {
+  @State({
+    integrationResource: 'arn:aws:states:::dynamodb:putItem',
+    next: 'confirm',
+  })
+  saveItem(@IntegrationOptions() { getResourceValue }: IntegrationOptionsParams) {
+    return {
+      TableName: getResourceValue('dynamo::inventory', 'id'),
+      Item: {
+        sku: { S: '{% $states.input.sku %}' },
+        quantity: { N: '{% $string($states.input.quantity) %}' },
+      },
+    };
+  }
+
+  @State({ end: true })
+  confirm(@Event('{% $states.input %}') e: any) {
+    console.log('Item saved successfully');
+  }
+}
+```
+
+A read example using `getItem`:
+
+```typescript
+@State({
+  integrationResource: 'arn:aws:states:::dynamodb:getItem',
+  next: 'processResult',
+  output: '{% $states.result.Item %}',
+})
+lookupUser(@IntegrationOptions() { getResourceValue }: IntegrationOptionsParams) {
+  return {
+    TableName: getResourceValue('dynamo::users', 'id'),
+    Key: {
+      email: { S: '{% $states.input.email %}' },
+    },
+  };
+}
+```
+
+### Nested State Machines
+
+Complex workflows often require sub-workflows for parallel execution or iteration over collections. Use `@NestedStateMachine` to define these embedded workflows.
+
+#### Map State
+
+A Map state iterates over a collection and executes a set of states for each item:
+
+```typescript
+import { StateMachine, NestedStateMachine, State, Event } from '@lafken/state-machine/main';
+
+@NestedStateMachine({
+  startAt: 'processItem',
+})
+class ItemProcessor {
+  @State({ end: true })
+  processItem(@Event('{% $states.input %}') item: any) {
+    return { id: item.id, processed: true };
+  }
+}
+
+@StateMachine({
+  startAt: {
+    type: 'map',
+    mode: 'inline',
+    items: '{% $states.input.items %}',
+    states: ItemProcessor,
+    end: true,
+  },
+})
+export class BatchWorkflow {}
+```
+
+#### Parallel State
+
+A Parallel state runs multiple branches concurrently. Each branch is a class decorated with `@NestedStateMachine`:
+
+```typescript
+@NestedStateMachine({ startAt: 'sendEmail' })
+class EmailBranch {
+  @State({ end: true })
+  sendEmail(@Event('{% $states.input %}') e: any) {
+    console.log('Sending email...');
+  }
+}
+
+@NestedStateMachine({ startAt: 'sendSms' })
+class SmsBranch {
+  @State({ end: true })
+  sendSms(@Event('{% $states.input %}') e: any) {
+    console.log('Sending SMS...');
+  }
+}
+
+@StateMachine({
+  startAt: {
+    type: 'parallel',
+    branches: [EmailBranch, SmsBranch],
+    end: true,
+  },
+})
+export class NotificationWorkflow {}
+```
+
+### Choice State
+
+Use the `choice` type in `startAt` or `next` to define conditional branching based on JSONata expressions:
+
+```typescript
+@StateMachine({
+  startAt: {
+    type: 'choice',
+    choices: [
+      {
+        condition: '{% $states.input.priority = "high" %}',
+        next: 'expedite',
+      },
+      {
+        condition: '{% $states.input.priority = "low" %}',
+        next: 'enqueue',
+      },
+    ],
+    default: { type: 'fail', error: 'UnknownPriority', cause: 'Priority not recognized' },
+  },
+})
+export class RoutingWorkflow {
+  @State({ end: true })
+  expedite(@Event('{% $states.input %}') e: any) {
+    return { routed: 'express' };
+  }
+
+  @State({ end: true })
+  enqueue(@Event('{% $states.input %}') e: any) {
+    return { routed: 'standard' };
+  }
+}
+```
+
+### Error Handling
+
+States support `retry` and `catch` configurations for resilient workflows:
+
+```typescript
+@State({
+  next: 'done',
+  retry: [
+    {
+      errorEquals: ['States.TaskFailed'],
+      intervalSeconds: 2,
+      maxAttempt: 3,
+      backoffRate: 2,
+    },
+  ],
+  catch: [
+    {
+      errorEquals: ['States.ALL'],
+      next: { type: 'fail', error: 'ProcessingError', cause: 'Task failed after retries' },
+    },
+  ],
+})
+riskyOperation(@Event('{% $states.input %}') input: any) {
+  // This operation will be retried up to 3 times on failure
+  return { result: 'done' };
+}
+```
+
+### State Events & Payloads
+
+Each `@State` method can receive input data through the `@Event` decorator. You can pass either a JSONata expression or a typed `@Payload` class.
+
+#### JSONata Expression
+
+Extract or transform the incoming event inline:
+
+```typescript
+@State({ end: true })
+handle(@Event('{% $states.input.user %}') user: { name: string; role: string }) {
+  console.log(`User: ${user.name}, Role: ${user.role}`);
+}
+```
+
+#### Typed Payload
+
+Define a structured payload class with `@Payload` and `@Param` decorators for clear, declarative input mapping:
+
+```typescript
+import { Payload, Param } from '@lafken/state-machine/main';
+
+@Payload()
+export class InvoiceInput {
+  @Param({ context: 'input', source: 'invoiceId' })
+  invoiceId: string;
+
+  @Param({ context: 'input', source: 'lineItems', type: [Number] })
+  lineItems: number[];
+
+  @Param({ context: 'execution', source: 'id' })
+  executionId: string;
+}
+
+@StateMachine({ startAt: 'generateInvoice' })
+export class InvoiceWorkflow {
+  @State({ next: 'send' })
+  generateInvoice(@Event(InvoiceInput) input: InvoiceInput) {
+    return { id: input.invoiceId, total: input.lineItems.reduce((a, b) => a + b, 0) };
+  }
+
+  @State({ end: true })
+  send(@Event('{% $states.input %}') invoice: any) {
+    console.log('Sending invoice:', invoice.id);
+  }
+}
+```
+
+Available `@Param` contexts:
+
+| Context          | Description                                 | Example sources                        |
+| ---------------- | ------------------------------------------- | -------------------------------------- |
+| `input`          | Values from the state input                 | Any field name (e.g. `'orderId'`)      |
+| `execution`      | Execution metadata                          | `'id'`, `'name'`, `'start_time'`       |
+| `state`          | Current state metadata                      | `'entered_time'`, `'name'`             |
+| `state_machine`  | State machine metadata                      | `'id'`, `'name'`                       |
+| `task`           | Task metadata                               | `'token'`                              |
+| `custom`         | A hardcoded value                           | Use `value` instead of `source`        |
+| `jsonata`        | A dynamic JSONata expression                | Use `value` with a JSONata string      |

package/lib/index.d.ts

@@ -0,0 +1,2 @@
+export * from './main';
+export * from './resolver';

package/lib/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./main"), exports);
+__exportStar(require("./resolver"), exports);

package/lib/main/index.d.ts

@@ -0,0 +1,2 @@
+export * from './param';
+export * from './state-machine';

package/lib/main/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./param"), exports);
+__exportStar(require("./state-machine"), exports);

package/lib/main/param/index.d.ts

@@ -0,0 +1,2 @@
+export * from './param';
+export * from './param.types';

package/lib/main/param/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./param"), exports);
+__exportStar(require("./param.types"), exports);

package/lib/main/param/param.d.ts

@@ -0,0 +1,105 @@
+import { type ClassResource } from '@lafken/common';
+import type { JsonAtaString, ParamProps } from './param.types';
+export declare const stateMachineFieldKey: string;
+export declare const stateMachinePayloadKey: string;
+/**
+ * Parameter decorator that binds the incoming Step Functions state
+ * input to a handler method argument.
+ *
+ * The event data can come from either:
+ * - A class decorated with `@Payload`, which maps the incoming data
+ *   to a typed class structure.
+ * - A JSONata expression string (`{%...%}`), allowing dynamic
+ *   extraction or transformation of the event data.
+ *
+ * @typeParam E - A `@Payload` class or a JSONata string.
+ * @param FieldClass - The payload class or JSONata expression that
+ *                     describes how to extract the event data.
+ *
+ * @example
+ * ```ts
+ * @StateMachine()
+ * export class OrderFlow {
+ *   @Task()
+ *   validate(@Event(OrderInput) input: OrderInput) { }
+ *
+ *   @Task()
+ *   transform(@Event('{%$states.input.orderId%}') id: string) { }
+ * }
+ * ```
+ */
+export declare const Event: <E extends ClassResource | JsonAtaString>(FieldClass: E) => (target: any, methodName: string, _number: number) => void;
+/**
+ * Class decorator that declares a class as a Step Functions state
+ * input/output payload.
+ *
+ * The decorated class defines the shape of the data passed between
+ * states. Use `@Param` on its properties to describe where each value
+ * is extracted from (execution context, state input, custom value, etc.).
+ *
+ * @param props - Optional payload configuration (e.g. a custom `name`).
+ *
+ * @example
+ * ```ts
+ * @Payload()
+ * export class OrderInput {
+ *   @Param({ context: 'input', source: 'orderId' })
+ *   orderId: string;
+ *
+ *   @Param({ context: 'execution', source: 'id' })
+ *   executionId: string;
+ * }
+ * ```
+ */
+export declare const Payload: (props?: import("@lafken/common").PayloadProps | undefined) => (target: Function) => void;
+/**
+ * Parameter decorator that injects the integration options
+ *
+ * Use it to receive a `GetResourceProps` object (or custom integration
+ * parameters) that provides access to `getResourceValue`, allowing you
+ * to reference other infrastructure resources (queues, buckets, tables,
+ * etc.) when building the integration payload returned by the handler.
+ *
+ * @example
+ * ```ts
+ * @StateMachine({ startAt: 'send' })
+ * export class OrderFlow {
+ *   @State({ integrationService: 'sqs', action: 'sendMessage', mode: 'token' })
+ *   send(@IntegrationOptions() { getResourceValue }: GetResourceProps) {
+ *     return {
+ *       QueueUrl: getResourceValue('queue::orders', 'id'),
+ *       MessageBody: { message: 'new order' },
+ *     };
+ *   }
+ * }
+ * ```
+ */
+export declare const IntegrationOptions: () => (target: any, methodName: string, _number: number) => void;
+/**
+ * Property decorator that maps a class field to a value extracted from
+ * the Step Functions execution context.
+ *
+ * Use it inside a `@Payload` class to specify which context or source
+ * provides the value for the field. Supported contexts include:
+ * `input`, `execution`, `state`, `state_machine`, `task`, `custom`,
+ * and `jsonata`.
+ *
+ * @param props - Extraction configuration (context, source/value, optional
+ *                name and type overrides).
+ *
+ * @example
+ * ```ts
+ * @Payload()
+ * export class TaskInput {
+ *   @Param({ context: 'input', source: 'userId' })
+ *   userId: string;
+ *
+ *   @Param({ context: 'execution', source: 'start_time' })
+ *   startedAt: string;
+ *
+ *   @Param({ context: 'custom', value: 'pending' })
+ *   status: string;
+ * }
+ * ```
+ */
+export declare const Param: (props?: ParamProps | undefined) => (target: any, destinationName: string) => void;

package/lib/main/param/param.js

@@ -0,0 +1,115 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Param = exports.IntegrationOptions = exports.Payload = exports.Event = exports.stateMachinePayloadKey = exports.stateMachineFieldKey = void 0;
+const common_1 = require("@lafken/common");
+const state_machine_1 = require("../state-machine");
+exports.stateMachineFieldKey = (0, common_1.createFieldName)(state_machine_1.RESOURCE_TYPE, common_1.FieldProperties.field);
+exports.stateMachinePayloadKey = (0, common_1.createFieldName)(state_machine_1.RESOURCE_TYPE, common_1.FieldProperties.payload);
+/**
+ * Parameter decorator that binds the incoming Step Functions state
+ * input to a handler method argument.
+ *
+ * The event data can come from either:
+ * - A class decorated with `@Payload`, which maps the incoming data
+ *   to a typed class structure.
+ * - A JSONata expression string (`{%...%}`), allowing dynamic
+ *   extraction or transformation of the event data.
+ *
+ * @typeParam E - A `@Payload` class or a JSONata string.
+ * @param FieldClass - The payload class or JSONata expression that
+ *                     describes how to extract the event data.
+ *
+ * @example
+ * ```ts
+ * @StateMachine()
+ * export class OrderFlow {
+ *   @Task()
+ *   validate(@Event(OrderInput) input: OrderInput) { }
+ *
+ *   @Task()
+ *   transform(@Event('{%$states.input.orderId%}') id: string) { }
+ * }
+ * ```
+ */
+const Event = (FieldClass) => (0, common_1.createEventDecorator)({ prefix: state_machine_1.RESOURCE_TYPE })(FieldClass);
+exports.Event = Event;
+/**
+ * Class decorator that declares a class as a Step Functions state
+ * input/output payload.
+ *
+ * The decorated class defines the shape of the data passed between
+ * states. Use `@Param` on its properties to describe where each value
+ * is extracted from (execution context, state input, custom value, etc.).
+ *
+ * @param props - Optional payload configuration (e.g. a custom `name`).
+ *
+ * @example
+ * ```ts
+ * @Payload()
+ * export class OrderInput {
+ *   @Param({ context: 'input', source: 'orderId' })
+ *   orderId: string;
+ *
+ *   @Param({ context: 'execution', source: 'id' })
+ *   executionId: string;
+ * }
+ * ```
+ */
+exports.Payload = (0, common_1.createPayloadDecorator)({
+    prefix: state_machine_1.RESOURCE_TYPE,
+    createUniqueId: false,
+});
+/**
+ * Parameter decorator that injects the integration options
+ *
+ * Use it to receive a `GetResourceProps` object (or custom integration
+ * parameters) that provides access to `getResourceValue`, allowing you
+ * to reference other infrastructure resources (queues, buckets, tables,
+ * etc.) when building the integration payload returned by the handler.
+ *
+ * @example
+ * ```ts
+ * @StateMachine({ startAt: 'send' })
+ * export class OrderFlow {
+ *   @State({ integrationService: 'sqs', action: 'sendMessage', mode: 'token' })
+ *   send(@IntegrationOptions() { getResourceValue }: GetResourceProps) {
+ *     return {
+ *       QueueUrl: getResourceValue('queue::orders', 'id'),
+ *       MessageBody: { message: 'new order' },
+ *     };
+ *   }
+ * }
+ * ```
+ */
+exports.IntegrationOptions = common_1.Context;
+/**
+ * Property decorator that maps a class field to a value extracted from
+ * the Step Functions execution context.
+ *
+ * Use it inside a `@Payload` class to specify which context or source
+ * provides the value for the field. Supported contexts include:
+ * `input`, `execution`, `state`, `state_machine`, `task`, `custom`,
+ * and `jsonata`.
+ *
+ * @param props - Extraction configuration (context, source/value, optional
+ *                name and type overrides).
+ *
+ * @example
+ * ```ts
+ * @Payload()
+ * export class TaskInput {
+ *   @Param({ context: 'input', source: 'userId' })
+ *   userId: string;
+ *
+ *   @Param({ context: 'execution', source: 'start_time' })
+ *   startedAt: string;
+ *
+ *   @Param({ context: 'custom', value: 'pending' })
+ *   status: string;
+ * }
+ * ```
+ */
+exports.Param = (0, common_1.createFieldDecorator)({
+    prefix: state_machine_1.RESOURCE_TYPE,
+    getMetadata: (props) => props,
+});