AWS.StepFunctions reference

Activity

Source: src/AWS/StepFunctions/Activity.ts

An AWS Step Functions activity — a named endpoint that external workers poll for tasks (GetActivityTask) and complete with the SendTask* callback operations.

Activities support worker-hosted task processing outside Lambda. For most callback flows the .waitForTaskToken service-integration pattern on a StateMachine Task state is preferred.

Activity: Creating Activities

Basic Activity

import * as StepFunctions from "alchemy/AWS/StepFunctions";

const activity = yield* StepFunctions.Activity("ApprovalActivity");

Reference an Activity from a State Machine

const machine = yield* StepFunctions.StateMachine("ApprovalFlow", {
  definition: {
    StartAt: "WaitForWorker",
    States: {
      WaitForWorker: {
        Type: "Task",
        Resource: activity.activityArn,
        End: true,
      },
    },
  },
});

Activity: Completing Tasks at Runtime

// init
const sendTaskSuccess = yield* StepFunctions.SendTaskSuccess(activity);

// runtime
yield* sendTaskSuccess({
  taskToken: token,
  output: JSON.stringify({ approved: true }),
});

DescribeExecution

Source: src/AWS/StepFunctions/DescribeExecution.ts

Runtime binding for states:DescribeExecution.

Bind this operation to a StateMachine inside a function runtime to poll the status and output of that machine’s executions. IAM access is scoped to executions of the bound state machine.

DescribeExecution: Polling Executions

const describeExecution = yield* StepFunctions.DescribeExecution(machine);

const execution = yield* describeExecution({ executionArn });
// execution.status: "RUNNING" | "SUCCEEDED" | "FAILED" | ...

DescribeMapRun

Source: src/AWS/StepFunctions/DescribeMapRun.ts

Runtime binding for states:DescribeMapRun.

Returns a Distributed Map Run’s status, item counts, and configuration. IAM access is scoped to Map Runs of the bound StateMachine; obtain mapRunArns from ListMapRuns.

DescribeMapRun: Distributed Map Runs

const describeMapRun = yield* StepFunctions.DescribeMapRun(machine);

const mapRun = yield* describeMapRun({ mapRunArn });
// mapRun.status, mapRun.itemCounts.succeeded, ...

GetActivityTask

Source: src/AWS/StepFunctions/GetActivityTask.ts

Runtime binding for states:GetActivityTask — the activity worker’s long-poll. Bind this operation to an Activity inside a function runtime to receive scheduled activity tasks with the activity ARN injected automatically.

The call blocks for up to 60 seconds when no task is scheduled (an empty taskToken means the poll timed out) — size the host’s timeout accordingly. Complete the returned task with SendTaskSuccess / SendTaskFailure, keeping it alive with SendTaskHeartbeat.

GetActivityTask: Activity Workers

const getActivityTask = yield* StepFunctions.GetActivityTask(activity);
const sendTaskSuccess = yield* StepFunctions.SendTaskSuccess(activity);

const task = yield* getActivityTask({ workerName: "worker-1" });
if (task.taskToken) {
  yield* sendTaskSuccess({
    taskToken: task.taskToken,
    output: JSON.stringify({ handled: true }),
  });
}

GetExecutionHistory

Source: src/AWS/StepFunctions/GetExecutionHistory.ts

Runtime binding for states:GetExecutionHistory.

Bind this operation to a StateMachine inside a function runtime to page through an execution’s event history (state transitions, task results, failures). IAM access is scoped to executions of the bound state machine. Not supported by EXPRESS state machines.

GetExecutionHistory: Polling Executions

const getExecutionHistory =
  yield* StepFunctions.GetExecutionHistory(machine);

const { events } = yield* getExecutionHistory({
  executionArn,
  reverseOrder: true,
  maxResults: 10,
});
// events[0].type === "ExecutionFailed" carries the error details

ListExecutions

Source: src/AWS/StepFunctions/ListExecutions.ts

Runtime binding for states:ListExecutions.

Bind this operation to a StateMachine inside a function runtime to list that machine’s executions (optionally filtered by status) with the state machine ARN injected automatically. Not supported by EXPRESS state machines.

ListExecutions: Polling Executions

const listExecutions = yield* StepFunctions.ListExecutions(machine);

const { executions } = yield* listExecutions({ statusFilter: "RUNNING" });

ListMapRuns

Source: src/AWS/StepFunctions/ListMapRuns.ts

Runtime binding for states:ListMapRuns.

Lists the Distributed Map Runs started by an execution of the bound StateMachine — use the returned mapRunArns with DescribeMapRun / UpdateMapRun. IAM access is scoped to executions of the bound state machine.

ListMapRuns: Distributed Map Runs

const listMapRuns = yield* StepFunctions.ListMapRuns(machine);

const { mapRuns } = yield* listMapRuns({ executionArn });

RedriveExecution

Source: src/AWS/StepFunctions/RedriveExecution.ts

Runtime binding for states:RedriveExecution.

Restarts a failed, aborted, or timed-out STANDARD execution from its failure point, reusing the same input and execution ARN. IAM access is scoped to executions of the bound StateMachine. Executions that are still running (or succeeded) fail with the typed ExecutionNotRedrivable error.

RedriveExecution: Redriving Executions

const redriveExecution = yield* StepFunctions.RedriveExecution(machine);

yield* redriveExecution({ executionArn }).pipe(
  Effect.catchTag("ExecutionNotRedrivable", () => Effect.void),
);

SendTaskFailure

Source: src/AWS/StepFunctions/SendTaskFailure.ts

Runtime binding for states:SendTaskFailure.

Fails a callback-pattern task (.waitForTaskToken) or an Activity task. Bind without arguments for task tokens issued by service-integration Task states, or pass an Activity to scope access.

SendTaskFailure: Callback Pattern

const sendTaskFailure = yield* StepFunctions.SendTaskFailure();

yield* sendTaskFailure({
  taskToken: token,
  error: "ApprovalRejected",
  cause: "the reviewer rejected the request",
});

SendTaskHeartbeat

Source: src/AWS/StepFunctions/SendTaskHeartbeat.ts

Runtime binding for states:SendTaskHeartbeat.

Reports liveness for a long-running callback-pattern task (.waitForTaskToken) or Activity task so its HeartbeatSeconds timeout does not fire. Bind without arguments for task tokens issued by service-integration Task states, or pass an Activity to scope access.

SendTaskHeartbeat: Callback Pattern

const sendTaskHeartbeat = yield* StepFunctions.SendTaskHeartbeat();

yield* sendTaskHeartbeat({ taskToken: token });

SendTaskSuccess

Source: src/AWS/StepFunctions/SendTaskSuccess.ts

Runtime binding for states:SendTaskSuccess.

Completes a callback-pattern task (.waitForTaskToken) or an Activity task successfully. Bind without arguments for task tokens issued by service-integration Task states (IAM cannot scope those), or pass an Activity to scope access to its tasks.

SendTaskSuccess: Callback Pattern

const sendTaskSuccess = yield* StepFunctions.SendTaskSuccess();

yield* sendTaskSuccess({
  taskToken: token,
  output: JSON.stringify({ approved: true }),
});

StartExecution

Source: src/AWS/StepFunctions/StartExecution.ts

Runtime binding for states:StartExecution.

Bind this operation to a StateMachine inside a function runtime to get a callable that starts asynchronous executions with the state machine ARN injected automatically.

StartExecution: Starting Executions

Start a workflow execution

const startExecution = yield* StepFunctions.StartExecution(machine);

const execution = yield* startExecution({
  input: JSON.stringify({ orderId: "123" }),
});
// execution.executionArn identifies the running workflow

Idempotent start via execution name

const execution = yield* startExecution({
  name: `order-${orderId}`,
  input: JSON.stringify({ orderId }),
});

StartSyncExecution

Source: src/AWS/StepFunctions/StartSyncExecution.ts

Runtime binding for states:StartSyncExecution.

Bind this operation to an EXPRESS StateMachine inside a function runtime to run the workflow synchronously — the call returns once the execution finishes, with its status and output. Not available for STANDARD workflows.

StartSyncExecution: Synchronous Execution

const startSyncExecution = yield* StepFunctions.StartSyncExecution(machine);

const result = yield* startSyncExecution({
  input: JSON.stringify({ value: 21 }),
});
if (result.status === "SUCCEEDED") {
  const output = JSON.parse(String(result.output));
}

StateMachine

Source: src/AWS/StepFunctions/StateMachine.ts

An AWS Step Functions state machine (workflow).

StateMachine owns the lifecycle of a STANDARD or EXPRESS workflow. The Amazon States Language definition may be provided as a plain object — Output values (like Lambda function ARNs) inside it are resolved before serialization — and an execution role is created automatically unless an explicit roleArn is given. Lambda functions referenced in the definition are granted lambda:InvokeFunction on the auto-created role.

StateMachine: Creating State Machines

Standard Workflow with a Pass State

import * as StepFunctions from "alchemy/AWS/StepFunctions";

const machine = yield* StepFunctions.StateMachine("OrderWorkflow", {
  definition: {
    StartAt: "Done",
    States: {
      Done: { Type: "Pass", End: true },
    },
  },
});

Express Workflow

const machine = yield* StepFunctions.StateMachine("FastWorkflow", {
  type: "EXPRESS",
  definition: {
    StartAt: "Echo",
    States: {
      Echo: { Type: "Pass", End: true },
    },
  },
});

StateMachine: Orchestrating Lambda Functions

Reference a function ARN in a Task state — lambda:InvokeFunction is granted on the auto-created execution role automatically.

const machine = yield* StepFunctions.StateMachine("Pipeline", {
  definition: {
    StartAt: "Process",
    States: {
      Process: {
        Type: "Task",
        Resource: fn.functionArn,
        End: true,
      },
    },
  },
});

StateMachine: Service Integrations

const machine = yield* StepFunctions.StateMachine("Callback", {
  definition: {
    StartAt: "WaitForApproval",
    States: {
      WaitForApproval: {
        Type: "Task",
        Resource: "arn:aws:states:::sqs:sendMessage.waitForTaskToken",
        Parameters: {
          QueueUrl: queue.queueUrl,
          MessageBody: { "token.$": "$$.Task.Token" },
        },
        End: true,
      },
    },
  },
  policyStatements: [
    {
      Effect: "Allow",
      Action: ["sqs:SendMessage"],
      Resource: [queue.queueArn],
    },
  ],
});

StateMachine: Starting Executions at Runtime

Bind execution operations in the init phase and use them in runtime handlers.

Start a workflow from a handler

// init
const startExecution = yield* StepFunctions.StartExecution(machine);

return {
  fetch: Effect.gen(function* () {
    // runtime
    const execution = yield* startExecution({
      input: JSON.stringify({ orderId: "123" }),
    });
    return HttpServerResponse.json({ executionArn: execution.executionArn });
  }),
};

Run an EXPRESS workflow synchronously

// init
const startSyncExecution = yield* StepFunctions.StartSyncExecution(machine);

// runtime
const result = yield* startSyncExecution({
  input: JSON.stringify({ value: 21 }),
});
// result.status === "SUCCEEDED", result.output is the workflow output

StateMachine: Typed Programs

Author the workflow as a typed Sfn program (mirroring Effect’s names — Sfn.gen, Sfn.invoke, Sfn.when, Sfn.forEach, Sfn.catchTag, …) and compile it with StateMachine.fromProgram. The compiler emits a plain ASL definition plus the IAM policy statements its task states need; the raw definition path above stays fully usable underneath.

import { Sfn, StateMachine } from "alchemy/AWS/StepFunctions";

const machine = yield* StateMachine.fromProgram("OrderWorkflow", {
  type: "EXPRESS",
  program: Sfn.gen(function* (input: Sfn.Expr<{ value: number }>) {
    const result = yield* Sfn.invoke<{ doubled: number }>(doubler, {
      value: input.value,
    });
    const size = yield* Sfn.when(
      Sfn.gt(result.doubled, 10),
      Sfn.succeed("big"),
      Sfn.succeed("small"),
    );
    return { doubled: result.doubled, size };
  }),
});

StopExecution

Source: src/AWS/StepFunctions/StopExecution.ts

Runtime binding for states:StopExecution.

Bind this operation to a StateMachine inside a function runtime to cancel that machine’s running executions. Not supported by EXPRESS workflows.

StopExecution: Stopping Executions

const stopExecution = yield* StepFunctions.StopExecution(machine);

yield* stopExecution({
  executionArn,
  error: "OrderCancelled",
  cause: "user requested cancellation",
});

TestState

Source: src/AWS/StepFunctions/TestState.ts

Runtime binding for states:TestState — execute a single ASL state (Task, Pass, Wait, Choice, Succeed, Fail) without creating a state machine, optionally with mocked service integrations.

Service-scoped (no resource argument). States that call other services (e.g. lambda:invoke) need a roleArn the caller can iam:PassRole — intrinsic states (Pass/Choice/Succeed/Fail) run without one.

TestState: Testing States

const testState = yield* StepFunctions.TestState();

const result = yield* testState({
  definition: JSON.stringify({
    Type: "Pass",
    QueryLanguage: "JSONata",
    Output: "{% $states.input.value * 2 %}",
    End: true,
  }),
  input: JSON.stringify({ value: 21 }),
});
// result.status === "SUCCEEDED", result.output === "42"

UpdateMapRun

Source: src/AWS/StepFunctions/UpdateMapRun.ts

Runtime binding for states:UpdateMapRun.

Adjusts a running Distributed Map Run’s maxConcurrency and tolerated failure thresholds in place. IAM access is scoped to Map Runs of the bound StateMachine.

UpdateMapRun: Distributed Map Runs

const updateMapRun = yield* StepFunctions.UpdateMapRun(machine);

yield* updateMapRun({ mapRunArn, maxConcurrency: 10 });

ValidateStateMachineDefinition

Source: src/AWS/StepFunctions/ValidateStateMachineDefinition.ts

Runtime binding for states:ValidateStateMachineDefinition — AWS’s static ASL validator (the Tier-4 check op for the Step Functions DSL).

Service-scoped (no resource argument): validates any definition string without creating or updating a state machine. StateMachine’s reconcile runs this same check as a pre-flight; bind it in a function runtime to validate definitions on demand (e.g. compiled Sfn programs before a deployment pipeline applies them).

ValidateStateMachineDefinition: Validating Definitions

const validate = yield* StepFunctions.ValidateStateMachineDefinition();

const report = yield* validate({
  definition: JSON.stringify(definition),
  type: "EXPRESS",
  severity: "ERROR",
});
// report.result === "OK" | "FAIL"; report.diagnostics lists findings