Tiny ASL Machine

A lightweight TypeScript interpreter for AWS Step Functions' Amazon States Language (ASL), built for local testing.

Best for: testing workflow logic locally with mocked Task resources Not for: production workflow execution, durable state, or full AWS emulation

Install

npm install tiny-asl-machine
pnpm add tiny-asl-machine
yarn add tiny-asl-machine

Quick start

import { run, type StateDefinition } from 'tiny-asl-machine';

const definition: StateDefinition = {
  StartAt: 'MyTask',
  States: {
    MyTask: {
      Type: 'Task',
      Resource: 'arn:aws:lambda:us-east-1:123456789012:function:MyFunction',
      End: true,
    },
  },
};

const result = await run(
  {
    definition,
    resourceContext: {
      invoke: async (resource, input) => {
        if (resource === 'arn:aws:lambda:us-east-1:123456789012:function:MyFunction') {
          return { processed: true, ...input };
        }

        throw new Error(`Unexpected resource: ${resource}`);
      },
    },
  },
  { data: 'test' }
);

What it is good at

Use Tiny ASL Machine when you want to:

• keep your ASL definition close to production
• mock Task resources in-process
• test branching, dataflow, retries, catches, waits, Map, and Parallel locally
• move quickly locally, then confirm parity-sensitive behavior on AWS

What it is not

Do not use it as:

• a production Step Functions replacement
• a durable execution engine
• a persistence layer
• a full AWS service-integration emulator

Support at a glance

| Area | Status | Notes | | ----------------------------------------- | ------------ | ----------------------------------------------------------------------- | | Core states | Strong | Task, Pass, Choice, Wait, Parallel, Map, Succeed, Fail | | Dataflow | Strong | InputPath, OutputPath, ResultPath, Parameters, ResultSelector | | Error handling | Strong | Catch and Retry for normal orchestration flows | | Intrinsics | Strong | broad JSONPath intrinsic coverage | | JSONata | Strong | one of the strongest areas of the project | | Advanced distributed Map / ItemReader | Partial | common local cases work; advanced service-coupled shapes still need AWS | | Callback / task-token fidelity | Partial | some support exists, but not full service fidelity | | Durable execution | Out of scope | use AWS Step Functions for that |

For deeper status, use ASL_COMPATIBILITY.md.

Same JSON for tests and production

The library matches Task resources by the exact Resource string in the ASL definition.

That means local tests can usually use the same definition you deploy, whether your file contains:

• deployment placeholders like {chargeCustomerArn}
• internal resource names
• full AWS ARNs

When to use AWS-backed checks

Use local tests for fast feedback. Use AWS-backed conformance when:

• behavior is parity-sensitive
• validation rules matter
• you are relying on less common ASL features
• you need a final answer on real Step Functions behavior

Main docs

• Examples
• FAQ
• ASL compatibility guide
• Contributing
• Engineering playbook
• Skill: write local state machine tests

Useful repository references

• tests/sampleETLOrchestration.spec.ts — realistic example
• tests/conformance/cases/ — compatibility coverage by feature/group
• tests/conformance.spec.ts — unified local/AWS conformance runner

Bottom line

Tiny ASL Machine gives you a high-confidence local testing workflow for a large part of real Step Functions logic.

For production semantics and hard edge cases, AWS remains the authority.

License

MIT - See LICENSE