@lafken/state-machine 0.14.1 → 0.14.3

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

@@ -1,6 +1,8 @@
 import { type ClassResource } from '@lafken/common';
 import type { JsonAtaString, ParamProps } from './param.types';
+/** Reflect-metadata key prefix for state machine field metadata. */
 export declare const stateMachineFieldKey: string;
+/** Reflect-metadata key prefix for state machine payload metadata. */
 export declare const stateMachinePayloadKey: string;
 /**
  * Parameter decorator that binds the incoming Step Functions state

package/lib/main/param/param.js

@@ -3,7 +3,9 @@ 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");
+/** Reflect-metadata key prefix for state machine field metadata. */
 exports.stateMachineFieldKey = (0, common_1.createFieldName)(state_machine_1.RESOURCE_TYPE, common_1.FieldProperties.field);
+/** Reflect-metadata key prefix for state machine payload metadata. */
 exports.stateMachinePayloadKey = (0, common_1.createFieldName)(state_machine_1.RESOURCE_TYPE, common_1.FieldProperties.payload);
 /**
  * Parameter decorator that binds the incoming Step Functions state

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

@@ -116,6 +116,10 @@ export type StateMachineParamContext = ParamContextBase<'state_machine', StateMa
  * { context: 'task', source: 'token' }
  */
 export type TaskParamContext = ParamContextBase<'task', TaskSource>;
+/**
+ * Parameter context for supplying an arbitrary static or computed value
+ * that does not originate from execution, state, or task runtime data.
+ */
 /**
  * Parameter context for supplying an arbitrary static or computed value
  * that does not originate from execution, state, or task runtime data.
@@ -123,11 +127,14 @@ export type TaskParamContext = ParamContextBase<'task', TaskSource>;
 export type CustomParamContext = {
     context: 'custom';
     /**
-     * A simple value
+     * Static value to inject as the parameter.
+     * Can be a string, number, boolean, or any other JSON-serializable value.
      */
     value?: any;
     /**
-     * You can extend this value with other
+     * Optional type constructor used to cast or transform the value at runtime.
+     * When provided, the raw value is converted to the specified type
+     * (e.g. `String`, `Number`, `Boolean`, or a custom transformer function).
      */
     type?: String | Number | Boolean | Function;
 };

package/lib/main/state-machine/state-machine.types.d.ts

@@ -3,13 +3,52 @@ import type { JsonAtaString } from '../param';
 export declare enum StateMachineReflectKeys {
     nested = "state_machine:nested"
 }
+/** Generic method signature for any Lambda handler. */
 export type DefaultMethod = (...args: any) => any;
+/**
+ * Step Functions execution type.
+ *
+ * - `'STANDARD'` — Long-running workflows with exactly-once processing.
+ * - `'EXPRESS'` — High-throughput, short-duration workflows with at-least-once processing.
+ */
 export type ProcessorExecutionType = 'STANDARD' | 'EXPRESS';
+/**
+ * Map state execution mode.
+ *
+ * - `'INLINE'` — All iterations run within the same state machine execution.
+ * - `'DISTRIBUTED'` — Each iteration can be a separate execution for higher scalability.
+ */
 export type ProcessorMode = 'INLINE' | 'DISTRIBUTED';
+/**
+ * CSV delimiter character for distributed map item readers.
+ */
 export type CsvDelimiter = 'COMMA' | 'PIPE' | 'SEMICOLON' | 'SPACE' | 'TAB';
+/**
+ * Header location in CSV files for distributed map item readers.
+ *
+ * - `'FIRST_ROW'` — Headers are in the first row of the CSV.
+ * - `'GIVEN'` — Headers are provided explicitly via `titles`.
+ */
 export type HeaderLocation = 'FIRST_ROW' | 'GIVEN';
+/**
+ * Output format for distributed map result writers.
+ */
 export type ResultOutputType = 'JSON' | 'JSONL';
+/**
+ * Transformation applied to distributed map results before writing.
+ *
+ * - `'NONE'` — No transformation.
+ * - `'COMPACT'` — Compact the JSON output.
+ * - `'FLATTEN'` — Flatten nested objects.
+ */
 export type ResultTransformation = 'NONE' | 'COMPACT' | 'FLATTEN';
+/**
+ * Integration invocation mode for Step Functions service integrations.
+ *
+ * - `'sync'` — Wait for the service to complete before proceeding.
+ * - `'async'` — Fire-and-forget; the state machine continues immediately.
+ * - `'token'` — Use a task token for callback-based integrations.
+ */
 export type IntegrationMode = 'sync' | 'async' | 'token';
 type ObjectOrJsonAta = Record<string, any> | JsonAtaString;
 export interface StateName {
@@ -456,6 +495,7 @@ interface ParallelState<T> extends CatchAndRetry<T>, StateName {
     next?: StateTypes<T>;
 }
 interface FailState extends StateName {
+    /** State type: Fail. Terminates execution with an error. */
     type: 'fail';
     /**
      * Description about error cause, you can use an jsonata expression
@@ -486,6 +526,7 @@ interface FailState extends StateName {
     error?: string;
 }
 interface SucceedState extends StateName {
+    /** State type: Succeed. Terminates execution successfully. */
     type: 'succeed';
     /**
      * State output transformation.
@@ -510,6 +551,7 @@ interface SucceedState extends StateName {
     output?: ObjectOrJsonAta;
 }
 interface PassState<T> extends StateName {
+    /** State type: Pass. Passes its input to its output or injects fixed data. */
     type: 'pass';
     /**
      * Next state to execute.
@@ -729,28 +771,55 @@ interface MapInline<T> extends MapStateBase<T> {
      */
     mode: 'inline';
 }
+/**
+ * Base configuration for a distributed map item reader.
+ */
 interface MapReaderItemBase {
+    /** S3 bucket containing the input data file. */
     bucket: BucketNames;
+    /** S3 object key of the input data file. */
     key: string;
+    /** Maximum number of items to read from the file. */
     maxItems?: number;
 }
+/**
+ * Item reader for JSON, JSONL, or manifest files.
+ */
 interface MapReaderJSONItem extends MapReaderItemBase {
+    /** Input file format. */
     source: 'json' | 'jsonl' | 'manifest';
+    /** JSON pointer expression to locate the array of items within the file. */
     itemsPointer?: string;
 }
+/**
+ * Item reader for CSV files.
+ */
 interface MapReaderCSVItem extends MapReaderItemBase {
+    /** Must be `'csv'` to indicate CSV input. */
     source: 'csv';
+    /** Header configuration for the CSV file. */
     headers: {
+        /** Where the header row is located. */
         location: HeaderLocation;
+        /** Explicit column titles (used when `location` is `'GIVEN'`). */
         titles?: string[];
     };
+    /** Delimiter character between CSV fields. */
     delimiter?: CsvDelimiter;
 }
+/**
+ * Configuration for writing distributed map results to S3.
+ */
 interface MapWriteResult {
+    /** S3 bucket where results are written. */
     bucket: BucketNames;
+    /** S3 key prefix for the result files. */
     prefix: string;
+    /** Output format and transformation settings. */
     config?: {
+        /** Output file format. */
         outputType: 'JSON' | 'JSONL';
+        /** Transformation applied to the output. */
         transformation?: 'NONE' | 'COMPACT' | 'FLATTEN';
     };
 }
@@ -823,12 +892,21 @@ export interface MapDistributed<T> extends MapStateBase<T> {
 }
 type MapState<T> = MapInline<T> | MapDistributed<T>;
 export type ErrorType = 'States.ALL' | 'States.HeartbeatTimeout' | 'States.Timeout' | 'States.TaskFailed' | 'States.Permissions' | 'States.ResultPathMatchFailure' | 'States.ParameterPathFailure' | 'States.QueryEvaluationError' | 'States.BranchFailed' | 'States.NoChoiceMatched' | 'States.IntrinsicFailure' | 'States.ExceedToleratedFailureThreshold' | 'States.ItemReaderFailed' | 'States.ResultWriterFailed' | (string & {});
+/**
+ * Retry configuration for a state in case of failure.
+ */
 interface StateRetry {
+    /** Error types that trigger this retry configuration. */
     errorEquals: ErrorType[];
+    /** Seconds to wait before the first retry attempt. */
     intervalSeconds?: number;
+    /** Maximum number of retry attempts. */
     maxAttempt?: number;
+    /** Multiplier applied to `intervalSeconds` after each retry. */
     backoffRate?: number;
+    /** Maximum delay in seconds between retries (caps exponential backoff). */
     maxDelaySeconds?: number;
+    /** Random jitter strategy: `'FULL'` adds up to 100% jitter, `'NONE'` disables it. */
     jitterStrategy?: 'FULL' | 'NONE';
 }
 interface StateCatch<T> {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lafken/state-machine",
-  "version": "0.14.1",
+  "version": "0.14.3",
   "private": false,
   "description": "Build Step Functions workflows with TypeScript decorators - declarative orchestration with Lafken",
   "keywords": [
@@ -50,7 +50,7 @@
   ],
   "dependencies": {
     "reflect-metadata": "^0.2.2",
-    "@lafken/resolver": "0.14.1"
+    "@lafken/resolver": "0.14.3"
   },
   "devDependencies": {
     "@cdktn/provider-aws": "^25.0.0",
@@ -63,13 +63,13 @@
     "typescript": "7.0.2",
     "unplugin-swc": "^1.5.10",
     "vitest": "^4.1.10",
-    "@lafken/common": "0.14.1"
+    "@lafken/common": "0.14.3"
   },
   "peerDependencies": {
     "@cdktn/provider-aws": ">=23.0.0",
     "cdktn": ">=0.22.0",
     "constructs": ">=10.7.0",
-    "@lafken/common": "0.14.1"
+    "@lafken/common": "0.14.3"
   },
   "engines": {
     "node": ">=20.19"