import type { Input } from "alchemy/Input";
import * as Output from "alchemy/Output";
import { toSeconds as toWholeSeconds } from "alchemy/Util/Duration";
/**
* The Step Functions program compiler: `SfnEffect` AST → a plain JSONata-mode
* ASL `definition` object (with embedded `Output`s the engine resolves) plus
* the IAM `policyStatements` its Task states require.
*
* The output is deliberately deterministic — state names and variable names
* are per-compile ordinals, no timestamps — so `StateMachine`'s
* `normalizeDefinition` drift comparison stays quiet across deploys of an
* unchanged program.
*/
import * as Data from "effect/Data";
import type * as Duration from "effect/Duration";
import type { PolicyStatement } from "../../IAM/Policy.ts";
import {
inputExpr,
isExpr,
nodeOf,
renderExprString,
renderNode,
variableExpr,
} from "./Jsonata.ts";
import type { AslNode, RetryOptions } from "./Node.ts";
import { isSfnEffect, type SfnEffect } from "./Program.ts";
/**
* A program failed to compile to ASL — e.g. yielding a non-`Sfn` value
* inside `Sfn.gen`, or unreachable steps after an unconditional `Sfn.fail`.
*/
export class SfnCompileError extends Data.TaggedError("SfnCompileError")<{
readonly message: string;
}> {}
/** The result of {@link compileProgram}. */
export interface CompiledProgram {
/**
* The ASL definition (JSONata query language). A plain object with
* embedded `Output`s — exactly what `StateMachineProps.definition`
* accepts.
*/
readonly definition: Record<string, unknown>;
/**
* IAM policy statements collected from `Sfn.invoke` / `Sfn.integrate`
* task states, for the state machine's execution role.
*/
readonly policyStatements: Input<PolicyStatement>[];
}
interface Ctx {
readonly nameCounters: Record<string, number>;
varCounter: number;
readonly policyStatements: Input<PolicyStatement>[];
readonly invokedFunctions: Set<string>;
}
type State = Record<string, any>;
/**
* A partially-built subgraph: its entry state, its states, and the names of
* states whose `Next`/`End` is still open (patched when the fragment is
* chained to a successor or sealed).
*/
interface Fragment {
readonly startAt: string;
readonly states: Record<string, State>;
readonly terminals: readonly string[];
}
const allocName = (ctx: Ctx, prefix: string): string => {
const n = ctx.nameCounters[prefix] ?? 0;
ctx.nameCounters[prefix] = n + 1;
return `${prefix}${n}`;
};
const allocVar = (ctx: Ctx): string => `v${ctx.varCounter++}`;
/** Chain `next` after `self`, patching `self`'s open terminals. */
const chain = (self: Fragment, next: Fragment): Fragment => {
const states = { ...self.states, ...next.states };
for (const terminal of self.terminals) {
states[terminal] = { ...states[terminal], Next: next.startAt };
}
return { startAt: self.startAt, states, terminals: next.terminals };
};
/** Seal a fragment into a `{ StartAt, States }` machine (`End: true`). */
const seal = (fragment: Fragment): { StartAt: string; States: Record<string, State> } => {
const states = { ...fragment.states };
for (const terminal of fragment.terminals) {
states[terminal] = { ...states[terminal], End: true };
}
return { StartAt: fragment.startAt, States: states };
};
/**
* Render a payload/assign value: `Expr` references become `{% ... %}`
* JSONata strings, embedded `Output`s pass through untouched (the engine
* resolves them before serialization), containers recurse, `undefined`
* becomes `null`.
*/
const renderValue = (value: unknown): unknown => {
if (value === undefined) return null;
if (isExpr(value)) return renderExprString(value);
if (Output.isOutput(value)) return value;
if (Array.isArray(value)) return value.map(renderValue);
if (typeof value === "object" && value !== null) {
return Object.fromEntries(
Object.entries(value).map(([key, entry]) => [key, renderValue(entry)]),
);
}
return value;
};
/**
* Convert a `Duration.Input` to ASL whole seconds (normalizing any
* persisted-state `Duration` JSON via the central util). ASL second fields
* (`TimeoutSeconds`, `IntervalSeconds`, `Seconds`) must be positive
* integers, so sub-second durations round up to 1.
*/
export const aslSeconds = (input: Duration.Input): number => Math.max(1, toWholeSeconds(input)!);
const retryPolicy = (options: RetryOptions): Record<string, unknown> => ({
ErrorEquals:
options.while === undefined
? ["States.ALL"]
: typeof options.while === "string"
? [options.while]
: [...options.while],
IntervalSeconds: aslSeconds(options.initial ?? "1 second"),
BackoffRate: options.backoff ?? 2,
MaxAttempts: options.maxAttempts ?? 3,
...(options.maxDelay !== undefined ? { MaxDelaySeconds: aslSeconds(options.maxDelay) } : {}),
...(options.jitter ? { JitterStrategy: "FULL" } : {}),
});
/**
* Does this node compile to exactly one catchable/retryable state
* (`Task`/`Parallel`/`Map`)? When true, `retry`/`catch` attach their
* `Retry`/`Catch` directly instead of wrapping in a single-branch
* `Parallel`.
*/
const isSingleCatchableState = (node: AslNode): boolean =>
node.kind === "invoke" ||
node.kind === "integrate" ||
node.kind === "all" ||
node.kind === "forEach" ||
(node.kind === "retry" && isSingleCatchableState(node.inner.node));
export const compileNode = (ctx: Ctx, node: AslNode, v: string): Fragment => {
switch (node.kind) {
case "invoke": {
const name = allocName(ctx, "Invoke");
if (!ctx.invokedFunctions.has(node.fn.LogicalId)) {
ctx.invokedFunctions.add(node.fn.LogicalId);
ctx.policyStatements.push({
Effect: "Allow",
Action: ["lambda:InvokeFunction"],
Resource: [
node.fn.functionArn,
// cover qualified invocations (versions/aliases)
Output.interpolate`${node.fn.functionArn}:*`,
],
} as Input<PolicyStatement>);
}
return {
startAt: name,
states: {
[name]: {
Type: "Task",
Resource: "arn:aws:states:::lambda:invoke",
Arguments: {
FunctionName: node.fn.functionArn,
Payload: renderValue(node.payload),
},
Assign: { [v]: "{% $states.result.Payload %}" },
},
},
terminals: [name],
};
}
case "integrate": {
const name = allocName(ctx, "Task");
ctx.policyStatements.push(
...((node.options.policyStatements ?? []) as Input<PolicyStatement>[]),
);
return {
startAt: name,
states: {
[name]: {
Type: "Task",
Resource: node.waitForTaskToken
? `${node.options.resource}.waitForTaskToken`
: node.options.resource,
...(node.options.arguments !== undefined
? { Arguments: renderValue(node.options.arguments) }
: {}),
...(node.options.timeout !== undefined
? { TimeoutSeconds: aslSeconds(node.options.timeout) }
: {}),
Assign: { [v]: "{% $states.result %}" },
},
},
terminals: [name],
};
}
case "all": {
const name = allocName(ctx, "Parallel");
return {
startAt: name,
states: {
[name]: {
Type: "Parallel",
Branches: node.branches.map((branch) => compileBranch(ctx, branch)),
Assign: { [v]: "{% $states.result %}" },
},
},
terminals: [name],
};
}
case "forEach": {
const name = allocName(ctx, "Map");
// the item arrives as the ItemProcessor's state input — bind it to a
// variable in a prologue Pass so the body can reference it anywhere
// ($states.context.Map.Item.Value only exists inside ItemSelector)
const itemVar = allocVar(ctx);
const body = node.body(variableExpr(itemVar));
if (!isSfnEffect(body)) {
throw new SfnCompileError({
message: "Sfn.forEach body must return an Sfn effect",
});
}
const itemName = allocName(ctx, "Item");
const intro: Fragment = {
startAt: itemName,
states: {
[itemName]: {
Type: "Pass",
Assign: { [itemVar]: "{% $states.input %}" },
},
},
terminals: [itemName],
};
return {
startAt: name,
states: {
[name]: {
Type: "Map",
Items: renderExprString(node.items),
...(node.options.concurrency !== undefined
? { MaxConcurrency: node.options.concurrency }
: {}),
ItemProcessor: {
ProcessorConfig: { Mode: "INLINE" },
...compileBranch(ctx, body, intro),
},
Assign: { [v]: "{% $states.result %}" },
},
},
terminals: [name],
};
}
case "sleep": {
const name = allocName(ctx, "Wait");
return {
startAt: name,
states: {
[name]: {
Type: "Wait",
Seconds: node.seconds,
Assign: { [v]: null },
},
},
terminals: [name],
};
}
case "when": {
const name = allocName(ctx, "Choice");
const onTrue = compileNode(ctx, node.onTrue.node, v);
const onFalse = compileNode(ctx, node.onFalse?.node ?? { kind: "succeed", value: null }, v);
return {
startAt: name,
states: {
[name]: {
Type: "Choice",
Choices: [
{
Condition: renderExprString(node.condition),
Next: onTrue.startAt,
},
],
Default: onFalse.startAt,
},
...onTrue.states,
...onFalse.states,
},
terminals: [...onTrue.terminals, ...onFalse.terminals],
};
}
case "match": {
const name = allocName(ctx, "Choice");
const states: Record<string, State> = {};
const terminals: string[] = [];
const rules: Record<string, unknown>[] = [];
const value = renderNode(nodeOf(node.value));
for (const [caseValue, program] of Object.entries(node.cases)) {
const fragment = compileNode(ctx, program.node, v);
Object.assign(states, fragment.states);
terminals.push(...fragment.terminals);
rules.push({
// string-coerced comparison so numeric/boolean case keys behave
Condition: `{% ($string(${value}) = ${JSON.stringify(caseValue)}) %}`,
Next: fragment.startAt,
});
}
let defaultTarget: string | undefined;
if (node.otherwise !== undefined) {
const fragment = compileNode(ctx, node.otherwise.node, v);
Object.assign(states, fragment.states);
terminals.push(...fragment.terminals);
defaultTarget = fragment.startAt;
}
return {
startAt: name,
states: {
[name]: {
Type: "Choice",
Choices: rules,
...(defaultTarget !== undefined ? { Default: defaultTarget } : {}),
},
...states,
},
terminals,
};
}
case "succeed": {
const name = allocName(ctx, "Pass");
return {
startAt: name,
states: {
[name]: { Type: "Pass", Assign: { [v]: renderValue(node.value) } },
},
terminals: [name],
};
}
case "fail": {
const name = allocName(ctx, "Fail");
return {
startAt: name,
states: {
[name]: { Type: "Fail", Error: node.error, Cause: node.cause },
},
terminals: [],
};
}
case "retry": {
if (isSingleCatchableState(node.inner.node)) {
const fragment = compileNode(ctx, node.inner.node, v);
const state = fragment.states[fragment.startAt];
state.Retry = [...(state.Retry ?? []), retryPolicy(node.options)];
return fragment;
}
// multi-state program: wrap in a single-branch Parallel so the whole
// program re-runs on retry (Effect.retry semantics)
const name = allocName(ctx, "Try");
return {
startAt: name,
states: {
[name]: {
Type: "Parallel",
Branches: [compileBranch(ctx, node.inner)],
Retry: [retryPolicy(node.options)],
Assign: { [v]: "{% $states.result[0] %}" },
},
},
terminals: [name],
};
}
case "catch": {
const errorVar = allocVar(ctx);
let guarded: Fragment;
if (isSingleCatchableState(node.inner.node)) {
guarded = compileNode(ctx, node.inner.node, v);
} else {
const name = allocName(ctx, "Try");
guarded = {
startAt: name,
states: {
[name]: {
Type: "Parallel",
Branches: [compileBranch(ctx, node.inner)],
Assign: { [v]: "{% $states.result[0] %}" },
},
},
terminals: [name],
};
}
const handlerProgram = node.handler(variableExpr(errorVar));
if (!isSfnEffect(handlerProgram)) {
throw new SfnCompileError({
message: "Sfn.catchTag/catchAll handler must return an Sfn effect",
});
}
const handler = compileNode(ctx, handlerProgram.node, v);
const target = guarded.states[guarded.startAt];
target.Catch = [
...(target.Catch ?? []),
{
ErrorEquals: [...node.tags],
Assign: { [errorVar]: "{% $states.errorOutput %}" },
Next: handler.startAt,
},
];
return {
startAt: guarded.startAt,
states: { ...guarded.states, ...handler.states },
terminals: [...guarded.terminals, ...handler.terminals],
};
}
case "gen": {
const iterator = node.body(inputExpr());
const fragments: Fragment[] = [];
let step = iterator.next();
while (!step.done) {
const program: unknown = step.value;
if (!isSfnEffect(program)) {
throw new SfnCompileError({
message:
"Sfn.gen may only yield Sfn effects (Sfn.invoke, Sfn.when, ...) — real Effects cannot compile to ASL",
});
}
const stepVar = allocVar(ctx);
fragments.push(compileNode(ctx, program.node, stepVar));
step = iterator.next(variableExpr(stepVar));
}
const diverged =
fragments.length > 0 && fragments[fragments.length - 1].terminals.length === 0;
if (!diverged) {
// final Pass assigning the generator's return value
const name = allocName(ctx, "Pass");
fragments.push({
startAt: name,
states: {
[name]: { Type: "Pass", Assign: { [v]: renderValue(step.value) } },
},
terminals: [name],
});
}
return fragments.reduce((chained, fragment) => {
if (chained.terminals.length === 0) {
throw new SfnCompileError({
message:
"unreachable steps after an unconditional Sfn.fail — move the failure into a branch or make it the final step",
});
}
return chain(chained, fragment);
});
}
}
};
/**
* Compile a program into a sealed `{ StartAt, States }` branch machine
* (Parallel branch / Map ItemProcessor). The branch's own result variable is
* exposed as the branch output via a terminal Pass state.
*/
const compileBranch = (
ctx: Ctx,
program: SfnEffect<any, any>,
intro?: Fragment,
): { StartAt: string; States: Record<string, State> } => {
const branchVar = allocVar(ctx);
let fragment = compileNode(ctx, program.node, branchVar);
if (intro !== undefined) fragment = chain(intro, fragment);
if (fragment.terminals.length === 0) {
// the branch always fails — no output state needed
return seal(fragment);
}
const name = allocName(ctx, "Result");
return seal(
chain(fragment, {
startAt: name,
states: { [name]: { Type: "Pass", Output: `{% ${branchVar} %}` } },
terminals: [name],
}),
);
};
/**
* Compile a typed Step Functions program to a plain ASL definition object
* (JSONata query language, embedded `Output`s intact) plus the IAM policy
* statements its task states require. Pure and deterministic; throws
* {@link SfnCompileError} on structurally invalid programs.
*
* This is sugar over the raw path: feed the result straight into the
* existing `StateMachine` resource (`StateMachine.fromProgram` does exactly
* that), or inspect/extend the definition first — the raw
* `definition: Record<string, unknown>` escape hatch stays first-class.
*/
export const compileProgram = (program: SfnEffect<any, any>): CompiledProgram => {
const ctx: Ctx = {
nameCounters: {},
varCounter: 0,
policyStatements: [],
invokedFunctions: new Set(),
};
const v = allocVar(ctx);
const fragment = compileNode(ctx, program.node, v);
const full =
fragment.terminals.length === 0
? fragment
: chain(fragment, {
startAt: "Return",
states: { Return: { Type: "Pass", Output: `{% ${v} %}` } },
terminals: ["Return"],
});
const machine = seal(full);
return {
definition: {
QueryLanguage: "JSONata",
StartAt: machine.StartAt,
States: machine.States,
},
policyStatements: ctx.policyStatements,
};
};