@lafken/state-machine 0.10.1

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

@@ -0,0 +1,77 @@
+import type { AllowedTypes, ArrayField, BooleanField, GetResourceProps, NumberField, ObjectField, StringField } from '@lafken/common';
+export type JsonAtaString = `{%${string}%}`;
+export type ExecutionSource = 'id' | `input.${string}` | 'name' | 'role_arn' | 'start_time' | 'redrive_count' | 'redrive_time';
+export type StateMachineSource = 'id' | 'name';
+export type StateSource = 'entered_time' | 'name' | 'retry_count';
+export type TaskSource = 'token';
+type ParamContextBase<C, T> = {
+    /**
+     * Identifies the context where the source is obtain
+     */
+    context: C;
+    /**
+     * Value or context parameter
+     */
+    source: T;
+    /**
+     * Field data type.
+     *
+     * Specifies the type of the field. By default, the type is inferred
+     * from the property that decorates the field. However, it can be
+     * explicitly set to a primitive type such as `String`, `Number`,
+     * `Boolean`, or to another payload type.
+     *
+     * This ensures correct parsing, validation, and serialization of the field's value.
+     */
+    type?: AllowedTypes;
+};
+export type InputParamContext = ParamContextBase<'input', string>;
+export type ExecutionParamContext = ParamContextBase<'execution', ExecutionSource>;
+export type StateParamContext = ParamContextBase<'state', StateSource>;
+export type StateMachineParamContext = ParamContextBase<'state_machine', StateMachineSource>;
+export type TaskParamContext = ParamContextBase<'task', TaskSource>;
+export type CustomParamContext = {
+    context: 'custom';
+    /**
+     * A simple value
+     */
+    value?: any;
+    /**
+     * You can extend this value with other
+     */
+    type?: String | Number | Boolean | Function;
+};
+export type JsonAtaParamContext = {
+    context: 'jsonata';
+    /**
+     * A simple value
+     */
+    value: JsonAtaString;
+};
+export type ParamContext = ExecutionParamContext | InputParamContext | StateParamContext | StateMachineParamContext | TaskParamContext | CustomParamContext | JsonAtaParamContext;
+export type ParamProps = {
+    /**
+     * Name of property
+     *
+     * @default class property name
+     */
+    name?: string;
+} & ParamContext;
+export type StateMachineParamBase = {
+    context: ParamContext['context'];
+    value: any;
+    source: any;
+    name: string;
+};
+export type StateMachineStringParam = StringField & StateMachineParamBase;
+export type StateMachineNumberParam = NumberField & StateMachineParamBase;
+export type StateMachineBooleanParam = BooleanField & StateMachineParamBase;
+export type StateMachineObjectParam = Omit<ObjectField, 'properties'> & StateMachineParamBase & {
+    properties: StateMachineParamMetadata[];
+};
+export type StateMachineArrayParam = Omit<ArrayField, 'items'> & StateMachineParamBase & {
+    items: StateMachineParamMetadata;
+};
+export type StateMachineParamMetadata = StateMachineStringParam | StateMachineNumberParam | StateMachineBooleanParam | StateMachineObjectParam | StateMachineArrayParam;
+export type IntegrationOptionsParams = GetResourceProps;
+export {};

package/lib/main/param/param.types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

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

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

package/lib/main/state-machine/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("./state-machine"), exports);
+__exportStar(require("./state-machine.types"), exports);

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

@@ -0,0 +1,113 @@
+import 'reflect-metadata';
+import { type DefaultMethod, type HandlerStateProps, type StateMachineBaseProps, type StateMachineResourceProps } from './state-machine.types';
+export declare const RESOURCE_TYPE: "STATE_MACHINE";
+/**
+ * Class decorator that registers a class as a **nested** state machine
+ * definition.
+ *
+ * A nested state machine defines a reusable sub-workflow that can be
+ * referenced inside a `parallel` branch or a `map` state of a
+ * parent `@StateMachine`. It is not deployed as a standalone resource
+ * but embedded within the parent definition.
+ *
+ * @typeParam T - The class being decorated.
+ * @param props - State machine definition including `startAt` and
+ *                optional `minify`.
+ *
+ * @example
+ * ```ts
+ * @NestedStateMachine({
+ *   startAt: {
+ *     type: 'wait',
+ *     seconds: 2,
+ *     next: { type: 'succeed' },
+ *   },
+ * })
+ * export class RetryBranch {}
+ *
+ * @StateMachine({
+ *   startAt: {
+ *     type: 'parallel',
+ *     branches: [RetryBranch],
+ *   },
+ * })
+ * export class OrderFlow {}
+ * ```
+ */
+export declare const NestedStateMachine: <T extends Function>(props: StateMachineBaseProps<keyof T["prototype"]>) => (constructor: T) => void;
+/**
+ * Class decorator that registers a class as an AWS Step Functions
+ * state machine resource.
+ *
+ * The decorated class defines a complete workflow. Use `@State` on
+ * its methods to declare task states backed by Lambda functions or
+ * AWS service integrations, and configure the execution flow through
+ * the `startAt` option.
+ *
+ * @typeParam T - The class being decorated.
+ * @param props - State machine configuration (startAt, executionType,
+ *                services, minify).
+ *
+ * @example
+ * ```ts
+ * @StateMachine({ startAt: 'validate' })
+ * export class OrderFlow {
+ *   @State({ next: 'process' })
+ *   validate(@Event(OrderInput) input: OrderInput) {}
+ *
+ *   @State({ end: true })
+ *   process(@Event(OrderInput) input: OrderInput) {}
+ * }
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Declarative flow without Lambda handlers
+ * @StateMachine({
+ *   startAt: {
+ *     type: 'wait',
+ *     seconds: 5,
+ *     next: { type: 'succeed' },
+ *   },
+ * })
+ * export class DelayedFlow {}
+ * ```
+ */
+export declare const StateMachine: <T extends Function>(props: StateMachineResourceProps<keyof T["prototype"]>) => (constructor: T) => void;
+/**
+ * Method decorator that registers a handler as a **Task** state inside
+ * a `@StateMachine`.
+ *
+ * The decorated method becomes a Lambda function (or an AWS service
+ * integration) that Step Functions invokes as part of the workflow.
+ * Use `next` to chain to the following state or `end: true` to mark
+ * it as a terminal state. Service integrations are configured via
+ * `integrationService`, `action`, and `mode`.
+ *
+ * @typeParam T - The class that owns the method.
+ * @typeParam K - The method key being decorated.
+ * @param props - Optional state configuration (next, end, assign,
+ *                integrationService, action, mode, lambda, etc.).
+ *
+ * @example
+ * ```ts
+ * @StateMachine({ startAt: 'step1' })
+ * export class MyFlow {
+ *   @State({ next: 'step2', assign: { count: 1 } })
+ *   step1(@Event(Input) input: Input) {}
+ *
+ *   @State({ end: true })
+ *   step2(@Event(Input) input: Input) {}
+ * }
+ * ```
+ *
+ * @example
+ * ```ts
+ * // AWS service integration (SQS)
+ * @State({ integrationService: 'sqs', action: 'sendMessage', mode: 'token' })
+ * send(@IntegrationOptions() { getResourceValue }: GetResourceProps) {
+ *   return { QueueUrl: getResourceValue('queue::orders', 'id') };
+ * }
+ * ```
+ */
+export declare const State: <T extends Record<K, DefaultMethod>, K extends keyof T>(props?: HandlerStateProps<T>) => (target: T, methodName: K, descriptor: PropertyDescriptor) => any;

package/lib/main/state-machine/state-machine.js

@@ -0,0 +1,133 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.State = exports.StateMachine = exports.NestedStateMachine = exports.RESOURCE_TYPE = void 0;
+require("reflect-metadata");
+const common_1 = require("@lafken/common");
+const state_machine_types_1 = require("./state-machine.types");
+exports.RESOURCE_TYPE = 'STATE_MACHINE';
+/**
+ * Class decorator that registers a class as a **nested** state machine
+ * definition.
+ *
+ * A nested state machine defines a reusable sub-workflow that can be
+ * referenced inside a `parallel` branch or a `map` state of a
+ * parent `@StateMachine`. It is not deployed as a standalone resource
+ * but embedded within the parent definition.
+ *
+ * @typeParam T - The class being decorated.
+ * @param props - State machine definition including `startAt` and
+ *                optional `minify`.
+ *
+ * @example
+ * ```ts
+ * @NestedStateMachine({
+ *   startAt: {
+ *     type: 'wait',
+ *     seconds: 2,
+ *     next: { type: 'succeed' },
+ *   },
+ * })
+ * export class RetryBranch {}
+ *
+ * @StateMachine({
+ *   startAt: {
+ *     type: 'parallel',
+ *     branches: [RetryBranch],
+ *   },
+ * })
+ * export class OrderFlow {}
+ * ```
+ */
+const NestedStateMachine = (props) => (constructor) => (0, common_1.createResourceDecorator)({
+    type: state_machine_types_1.StateMachineReflectKeys.nested,
+    callerFileIndex: 6,
+})(props)(constructor);
+exports.NestedStateMachine = NestedStateMachine;
+/**
+ * Class decorator that registers a class as an AWS Step Functions
+ * state machine resource.
+ *
+ * The decorated class defines a complete workflow. Use `@State` on
+ * its methods to declare task states backed by Lambda functions or
+ * AWS service integrations, and configure the execution flow through
+ * the `startAt` option.
+ *
+ * @typeParam T - The class being decorated.
+ * @param props - State machine configuration (startAt, executionType,
+ *                services, minify).
+ *
+ * @example
+ * ```ts
+ * @StateMachine({ startAt: 'validate' })
+ * export class OrderFlow {
+ *   @State({ next: 'process' })
+ *   validate(@Event(OrderInput) input: OrderInput) {}
+ *
+ *   @State({ end: true })
+ *   process(@Event(OrderInput) input: OrderInput) {}
+ * }
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Declarative flow without Lambda handlers
+ * @StateMachine({
+ *   startAt: {
+ *     type: 'wait',
+ *     seconds: 5,
+ *     next: { type: 'succeed' },
+ *   },
+ * })
+ * export class DelayedFlow {}
+ * ```
+ */
+const StateMachine = (props) => (constructor) => (0, common_1.createResourceDecorator)({
+    type: exports.RESOURCE_TYPE,
+    callerFileIndex: 6,
+})(props)(constructor);
+exports.StateMachine = StateMachine;
+/**
+ * Method decorator that registers a handler as a **Task** state inside
+ * a `@StateMachine`.
+ *
+ * The decorated method becomes a Lambda function (or an AWS service
+ * integration) that Step Functions invokes as part of the workflow.
+ * Use `next` to chain to the following state or `end: true` to mark
+ * it as a terminal state. Service integrations are configured via
+ * `integrationService`, `action`, and `mode`.
+ *
+ * @typeParam T - The class that owns the method.
+ * @typeParam K - The method key being decorated.
+ * @param props - Optional state configuration (next, end, assign,
+ *                integrationService, action, mode, lambda, etc.).
+ *
+ * @example
+ * ```ts
+ * @StateMachine({ startAt: 'step1' })
+ * export class MyFlow {
+ *   @State({ next: 'step2', assign: { count: 1 } })
+ *   step1(@Event(Input) input: Input) {}
+ *
+ *   @State({ end: true })
+ *   step2(@Event(Input) input: Input) {}
+ * }
+ * ```
+ *
+ * @example
+ * ```ts
+ * // AWS service integration (SQS)
+ * @State({ integrationService: 'sqs', action: 'sendMessage', mode: 'token' })
+ * send(@IntegrationOptions() { getResourceValue }: GetResourceProps) {
+ *   return { QueueUrl: getResourceValue('queue::orders', 'id') };
+ * }
+ * ```
+ */
+const State = (props) => (target, methodName, descriptor) => {
+    return (0, common_1.createLambdaDecorator)({
+        getLambdaMetadata: (props) => ({
+            ...props,
+            name: methodName,
+        }),
+    })(props)(target, methodName, descriptor);
+};
+exports.State = State;