@rickosborne/skip

Tools for working with Step Functions and States Language. This is not super robust, and certainly would never work in any serious production capacity. It should, however, be sufficient for most basic use-cases and local testing.

Alternatives:

• asl-types - TypeScript types module that makes it easier to create AWS Step Functions JSON.
• asl-validator - A simple Amazon States Language validator based on JSON schemas.

Built on top of:

• @rickosborne/foundation for data structures and general helpers
• @rickosborne/guard for TypeScript guards
• @rickosborne/typical for helper TypeScript type definitions

Example

As a simple example, based on one from the spec, presume you have a Lambda function which adds two numbers. Its implementation might be:

export function add(numbers: { val1: number; val2: number }): number {
	return numbers.val1 + numbers.val2;
}

That function could accept an input of:

{
	"val1": 3,
	"val2": 4
}

Aside: Function arguments always arrive as a single value. Even if you provide an array, it will just be an array as the first value.

Your State Machine definition around that function might look like:

{
	"StartAt": "Add",
	"States": {
		"Add": {
			"End": true,
			"Resource": "arn:aws:lambda:us-east-1:123456789012:function:Add",
			"Type": "Task"
		}
	}
}

Presumably, you already have unit tests for the add function. But what if you want to test your State Machine definition?

Enter the runStateMachine function from this library:

// Import the State Machine runner.
import { runStateMachine } from "@rickosborne/skip";
// Import your implementation from its source.
import { add } from "../add.js";
// Import the State Machine definition as JSON.  Or read it from a file.  Or use a literal.
import addStateMachine from "../state-machines/add.json" with { type: "json" };

describe(add.name, () => {
	test("valid inputs", async () => {
		// The runner is always asynchronous.  There is no synchronous API.
		const result = await runStateMachine(addStateMachine, {
			input: {
				val1: 3,
				val2: 4,
			},
			// As the State Machine definition uses Resource ARNs, you need
			// to tell the runner how to resolve those ARNs to local functions.
			// You can do this as a simple Record, or you could provide a
			// resolver function.
			fnForResource: {
				[addStateMachine.States.Add.Resource]: add,
			}
		});
		// Assert the correct result was returned.
		expect(result, "result").eq(7);
	});
});

That runStateMachine function's configuration object has additional properties for things like:

• nowProvider — Inject a stable replacement for Date.now(). (Note that this will not be injected into your implementation functions. If you need such a thing, you'll need to partially apply your function with the replacement.)
• onHeartbeatSeconds — Simulate heartbeat failures and successes.
• onMaxInputBytesPerBatch — Micromanage input batches based on input size.
• onRetry — Observe and modify failure retries.
• onStateComplete — Observe state transitions and their current context values, like inputs and outputs.
• onWait — Simulate various wait conditions and asynchronous completion.

See the docs for RunStateMachineOptions for details.

See the examples.test.ts unit tests for more extensive examples.

How complete is it?

It's not a robust production-ready implementation, but it should be sufficient for most tasks.

• It uses the jsonata library, and wires up the $states bindings, so most/all JSONata expressions should work.
• It uses the jsonpath library, and resolves all the *Path properties, so most/all JSONPath expressions should work.
• All Data Test Expressions for JSONPath are implemented. (i.e. StringMatches, TimestampGreaterThan, etc.)
• All Intrinsic Functions are implemented. (i.e. States.Hash, States.JsonMerge, etc.)
• Parallel tasks are actually run in parallel via promises. (Not Web Workers, though, so you're still on a single thread.)
• Map tasks are batched and also run in parallel according to the MaxConcurrency configuration.
• Timeout values are checked. (To support faster unit tests, this implementation allows decimal timeouts, not just integers as the spec dictates. So 0.25 is a quarter-second timeout, for example.)

So ... what doesn't work?

• Any Heartbeat configuration does not actually use heartbeats. Instead, you can configure a callback to decide whether to simulate a heartbeat failure.
• By default, Wait won't actually wait. You can, however, provide an async function which will be await-ed, if you really do want to sleep some amount of time.
• Errors are dodgy. The spec isn't great at specifying where some/most of the States.* errors come into play. I've made my best guess, but your Retry and Choices may need to include a few extra Error names (mostly SyntaxError) which AWS's implementation will likely just ignore.
• Some Assign versus Output handling may be busted. Again, the spec is super unclear on exactly how these should interact. If you have a working-in-the-cloud example of how they interact, let me know!
• Try/Catch/Retry may not match AWS cloud execution. It's been tested to handle "reasonable" cases, but nowhere near exhaustively.

Or, put simple: it mostly works, but there are likely to be sharp edges here and there.

Usage

Install via your favorite package manager.

Each package supports CommonJS require, ESM import, and TypeScript usage.

You also have a choice: barrel imports or direct imports.

Barrel imports mean you're going to require/import everything from the same package-level namespace:

// CommonJS
const { isPlainObject, isListOf } = require("@rickosborne/guard");
// ESM / TypeScript
import { isPlainObject, isListOf } from "@rickosborne/guard";

Implications:

• Nice and simple.
• Your build system needs to do tree-shaking well ... or you'll end up adding the entire package even if you only import two functions.

The other option is to use direct imports:

// CommonJS
const { isPlainObject } = require("@rickosborne/guard/is-object");
const { isListOf } = require("@rickosborne/guard/is-list-of");
// ESM / TypeScript
import { isPlainObject } from "@rickosborne/guard/is-object.js";
import { isListOf } from "@rickosborne/guard/is-list-of.js";

Implications:

• You (probably) don't have to worry about tree-shaking as your build (likely) ends up with only the functions you need.

If you're using a modern build system, there aren't any strong reasons to prefer one way over the other. It's really just down to your personal preference.

A quick note about file extensions

Do you need to use file extensions? And if so, which extensions?

Honestly ... this is a dumpster fire question. It really comes down to your own setup and configuration.

Within each package itself:

• The CommonJS files all have .cjs extensions.
• The ESM files all have .mjs extensions.
• Node subpath exports have been set up to send .js imports to the .cjs (via require) or .mjs (via import) files, depending on your setup.

So, in theory, the only extension which won't work would be .ts because the source isn't included.

If you run into a problem with a particular configuration, file a GitHub issue with:

• Your tsconfig.json's module, moduleResolution, and target settings.
• Your package.json's type and imports settings.
• An example of another package which imports correctly for you.

License

This package is licensed as CC-BY-NC-SA-4.0 unless otherwise noted. That is, Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International.

---

API

Classes

JSONPathError

 class JSONPathError extends StatesError 

Thrown when there's a problem trying to resolve or assign using a JSONPath expression. This implementation is super-duper basic, so it's not going to support anything beyond dotted-path expressions.

QueryEvaluationError

 class QueryEvaluationError extends StatesError 

Error thrown when a JSONata expression evaluation or parsing fails.

StatesError

 class StatesError extends Error 

Generic error for "something went wrong while executing a State Machine". Its name will always be one of the reserved States.* errors.

Functions

arrayAssertion

arrayAssertion: (fieldName: string, stateName: StateIdentifier) => EvaluationAssertion<JSONArray>

Builder for an evaluation assertion for an array.

assertExactlyOne

 function assertExactlyOne<T extends object, K extends string>(name: string, value: T, ...keys: K[]): void;

Throw unless at most exactly one of the given keys is present in the given value. Used for "you can have A or B, but never both".

assertLanguage

 function assertLanguage<Q extends QueryLanguageIdentifier>(actual: QueryLanguageIdentifier, expected: Q, fieldName: string): asserts actual is Q;

Throw if the current actual language (in the context of the state) is not the expected language (based on the attempted operation).

assertNullUndef

 function assertNullUndef(value: unknown, errorProvider: (type: string) => Error): asserts value is (null | undefined);

Throw if the given value is not null or undefined.

assertNumber

 function assertNumber(value: unknown, errorProvider: (type: string) => Error): asserts value is number;

Throw if the given value is not a number.

assertString

 function assertString(value: unknown, errorProvider: (type: string) => Error): asserts value is string;

Throw if the given value is not a string.

assertValidStateName

 function assertValidStateName(name: string): asserts name is StateIdentifier;

Basic check to ensure the State identifier meets the spec restrictions.

assignJSONPath

assignJSONPath: (target: JSONSerializable, jsonPathExpression: string, value: JSONSerializable) => void

Given a target object, a JSONPath expression for navigating that object, and a value, try to traverse the object and assign the value at the given path. Will create "container" records and arrays to make the path work, if necessary. Does not support anything particularly tricky.

assignThenContinue

assignThenContinue: (context: {
    error?: Error | undefined;
    errorOutput: ErrorOutput | undefined;
    evalOutput?: boolean | undefined;
    evaluateOutput: (context: RunStateContext<State> & {
        catcher?: Catcher;
        output: JSONSerializable;
    }) => Promise<JSONSerializable>;
    input: JSONSerializable;
    nextStateName?: StateIdentifier | undefined;
    onNextState: (context: RunStateContext<State>) => Promise<JSONSerializable>;
    options: RunStateMachineOptions;
    output: JSONSerializable;
    retryCount: number;
    state: State;
    stateMachine: StateMachine;
    stateName: StateIdentifier;
    stateStack: State[];
}) => Promise<JSONSerializable>

After the main part of a State has been evaluated, handle any Catch or Retry as applicable, and then transition to the next state.

definitionFromSource

definitionFromSource: (sourcePath: string, fnName?: string | undefined) => StateMachine

errorOutputFromError

errorOutputFromError: (error: Error) => ErrorOutput

Format an ErrorOutput based on the information in an Error. Tries to find the root cause, if present.

evaluateChoice

evaluateChoice: (choice: ChoiceRule, context: {
    input: JSONSerializable;
    language: QueryLanguageIdentifier;
    options: RunStateMachineOptions;
    state: ChoiceState;
    stateName: StateIdentifier;
}) => Promise<boolean>

Evaluate whether a given Choice Rule matches the current State.

evaluateExpression

evaluateExpression: (expr: JSONSerializable, context: {
    catcher?: JSONataCatcher | JSONPathCatcher | undefined;
    contextObject?: JSONObject;
    errorOutput?: ErrorOutput | undefined;
    input: JSONSerializable;
    language: QueryLanguageIdentifier;
    options: RunStateMachineOptions;
    state: State;
    stateStack: State[];
}) => Promise<JSONSerializable>

Evaluate an expression, which may be a literal, JSONPath, or JSONata, in the context of the current State.

evaluateIntrinsicFunction

evaluateIntrinsicFunction: (expr: string | IntrinsicFunctionCall, input?: JSONSerializable, context?: JSONSerializable | undefined) => JSONSerializable

General entry point for an Intrinsic Function. Given an Intrinsic Function call expression, parse it, validate the given args against the params, and evaluate and return the result.

evaluateJSONata

evaluateJSONata: <T extends JSONSerializable>(text: JSONataString, context: {
    contextObject?: JSONObject;
    input: JSONSerializable;
    output?: JSONSerializable | undefined;
    errorOutput?: ErrorOutput | undefined;
    state: State;
}, assertion?: EvaluationAssertion<T>) => Promise<T>

Evaluate a JSONata expression in the context of a running State.

evaluateJSONPath

evaluateJSONPath: <T extends JSONSerializable>(expression: string, context: {
    contextOverride?: JSONObject | undefined;
    input: JSONSerializable;
    options: RunStateMachineOptions;
}, assertion?: {
    expected: string;
    fieldName: string;
    predicate: (value: JSONSerializable) => value is T;
    stateName: StateIdentifier;
}) => T

Evaluate a JSONPath expression in the context of the current State.

evaluateJSONPathChoice

evaluateJSONPathChoice: (choice: JSONPathChoiceRule, depth: number, context: {
    input: JSONSerializable;
    options: RunStateMachineOptions;
    state: ChoiceState;
    stateName: StateIdentifier;
}) => Promise<boolean>

Evaluate a Choice Rule in a JSONPath context.

evaluateOutput

evaluateOutput: (context: {
    catcher?: JSONataCatcher | JSONPathCatcher | undefined;
    errorOutput?: ErrorOutput | undefined;
    evaluateOutput: (context: RunStateContext<State> & {
        catcher?: Catcher;
        output: JSONSerializable;
    }) => Promise<JSONSerializable>;
    input: JSONSerializable;
    onNextState: (context: RunStateContext<State>) => Promise<JSONSerializable>;
    options: RunStateMachineOptions;
    output: JSONSerializable;
    retryCount: number;
    state: State;
    stateMachine: StateMachine;
    stateName: StateIdentifier;
    stateStack: State[];
}) => Promise<JSONSerializable>

For the various ways a State can modify its output, go through each.

expectJSONPath

 function expectJSONPath(value: JSONSerializable, name: string): JSONPathPath;

Assert that a value is a JSONPath expression, and return it.

expectState

expectState: (name: StateIdentifier, stateMachine: StateMachine) => State

Find the given State by its identifier in the given State Machine, throwing if it is not found.

getLanguage

getLanguage: (context: {
    options: RunStateMachineOptions;
    state: State;
    stateMachine: StateMachine;
}) => QueryLanguageIdentifier

Figure out what the current query language is based on the current State, its parent State Machine, or the provided Run options.

getMaxConcurrency

getMaxConcurrency: (context: {
    assertionBuilder: (fieldName: string, stateName: string) => EvaluationAssertion<number>;
    input: JSONSerializable;
    language: QueryLanguageIdentifier;
    options: RunStateMachineOptions;
    state: MapState;
    stateName: StateIdentifier;
}) => Promise<number>

Try to figure out the configured maximum concurrency for a Map State.

getTimeouts

getTimeouts: <T>(context: {
    assertionBuilder: (fieldName: string, stateName: string) => EvaluationAssertion<number>;
    input: JSONSerializable;
    language: QueryLanguageIdentifier;
    options: RunStateMachineOptions;
    state: TaskState;
    stateName: StateIdentifier;
}) => Promise<TimedWrapper<T> | undefined>

Try to figure out the timeout/heartbeat configuration for a State. Instead of returning a timeout, returns a wrapper which will throw/return based on that timeout or heartbeat.

getToleratedFailureCount

getToleratedFailureCount: (context: {
    assertionBuilder: (fieldName: string, stateName: StateIdentifier) => EvaluationAssertion<number>;
    input: JSONSerializable;
    itemCount: number;
    language: QueryLanguageIdentifier;
    options: RunStateMachineOptions;
    state: MapState;
    stateName: StateIdentifier;
}) => Promise<number>

Try to figure out the configured tolerated failure count of a Map State.

hasQueryLanguage

hasQueryLanguage: (value: unknown) => value is Required<CanQueryLanguage>

hasTimeouts

hasTimeouts: (value: unknown) => value is HasTimeoutsState

isAndExpression

isAndExpression: (value: unknown) => value is AndExpression

isArgumentsState

isArgumentsState: (value: unknown) => value is ArgumentsState

isAssignedState

isAssignedState: (state: unknown) => state is AssignedState

isCatchState

isCatchState: (state: unknown) => state is CatchState

isDataTestExpression

isDataTestExpression: (value: unknown) => value is DataTestExpression

isDataTestLiteralExpressionKey

isDataTestLiteralExpressionKey: (key: keyof DataTestExpressions) => key is keyof DataTestLiteralExpressions

isEndState

isEndState: <S extends State>(state: S) => state is S & EndState

isInputPathState

isInputPathState: (value: unknown) => value is InputPathState

isIntString

isIntString: (value: unknown) => value is `${number}`

Guard for whether the value is a stringified integer.

isIsoDate

isIsoDate: (value: unknown) => value is SimpleIsoDate

Guard for whether the value is an ISO8601-formatted date.

isIsoDateTime

isIsoDateTime: (value: unknown) => value is IsoDateTime

Guard for whether the value is an ISO8601-formatted date or datetime (timestamp).

isIsoTime

isIsoTime: (value: unknown) => value is SimpleIsoTime

Guard for whether the value is an ISO8601-formatted time.

isIsoTimeZone

isIsoTimeZone: (value: unknown) => value is SimpleIsoTimeZone

Guard for whether the value is an ISO8601-formatted timezone.

isJSONataChoiceRule

isJSONataChoiceRule: (value: unknown) => value is JSONataChoiceRule

isJSONataItemBatcher

isJSONataItemBatcher: (value: unknown) => value is JSONataItemBatcher

isJSONataItemReader

isJSONataItemReader: (value: unknown) => value is JSONataItemReader

isJSONataString

isJSONataString: (value: unknown) => value is JSONataString

isJSONPathInterpolated

isJSONPathInterpolated: (value: unknown) => value is JSONPathInterpolated

isJSONPathItemBatcher

isJSONPathItemBatcher: (value: unknown) => value is JSONPathItemBatcher

isJSONPathItemReader

isJSONPathItemReader: (value: unknown) => value is JSONPathItemReader

isJSONPathPath

isJSONPathPath: (value: unknown) => value is JSONPathPath

isJSONPathPayloadTemplate

isJSONPathPayloadTemplate: (value: unknown) => value is JSONPathPayloadTemplate

isNonTerminalState

isNonTerminalState: (value: unknown) => value is NonTerminalState

isNotExpression

isNotExpression: (value: unknown) => value is NotExpression

isOrExpression

isOrExpression: (value: unknown) => value is OrExpression

isOutputPathState

isOutputPathState: (value: unknown) => value is OutputPathState

isOutputState

isOutputState: (state: unknown) => state is OutputState

isParametersState

isParametersState: (value: unknown) => value is ParametersState

isResultPathState

isResultPathState: (value: unknown) => value is ResultPathState

isResultSelectorState

isResultSelectorState: (value: unknown) => value is ResultSelectorState

isRetryState

isRetryState: (value: unknown) => value is RetryState

isSucceedState

isSucceedState: <S extends State>(state: S) => state is S & SucceedState

parseIntrinsicFunctionExpression

parseIntrinsicFunctionExpression: (expr: string) => IntrinsicFunctionCall

Try to parse an Intrinsic Function call expression. This is a very basic pull parser. It's a little flaky, as the JSONPath expressions aren't quoted, and the jsonpath library's parse function can't handle trailing text like , or ). And, of course, both , and ) are perfectly valid at places inside a JSONPath expression, so we can't just look for the first one of those, either.

positiveIntAssertion

positiveIntAssertion: (fieldName: string, stateName: StateIdentifier) => EvaluationAssertion<number>

Builder for an evaluation assertion for a positive integer.

processArgs

processArgs: (context: {
    input: JSONSerializable;
    options: RunStateMachineOptions;
    state: State;
    stateMachine: StateMachine;
    stateStack: State[];
}, targetOverride?: ResultWriter) => Promise<JSONSerializable>

Try to find the Arguments, InputPath, and Parameters for the target, and evaluate them as necessary to modify the input for the current State.

resourceHandlerResolver

resourceHandlerResolver: (options: RunStateMachineOptions) => ResourceHandlerResolver

Given some State Machine options, generate a function which can resolve Resource URIs to Lambda-like function implementations.

runAssign

runAssign: (output: JSONSerializable, assigned: AssignedState, context: {
    input: JSONSerializable;
    options: RunStateMachineOptions;
    state: State;
    stateMachine: StateMachine;
    stateStack: State[];
}) => Promise<JSONSerializable>

If the current State can use Assign, evaluate that to modify the given output.

runChoice

runChoice: (context: RunStateContext<ChoiceState>) => Promise<JSONSerializable>

Run the given Choice State.

runFail

runFail: (context: RunStateContext<FailState>) => Promise<JSONSerializable>

Run the given Fail State.

runMap

runMap: (context: RunStateContext<MapState>) => Promise<JSONSerializable>

Run the given Map State.

runParallel

runParallel: (context: RunStateContext<ParallelState>) => Promise<JSONSerializable>

Run the given Parallel State.

runPass

runPass: (context: RunStateContext<PassState>) => Promise<JSONSerializable>

Run the given Pass State.

runState

runState: <S extends State>(context: RunStateContext<S>) => Promise<JSONSerializable>

Run the given State.

runStateMachine

runStateMachine: (stateMachine: StateMachine, options?: RunStateMachineOptions) => Promise<JSONSerializable>

runSucceed

runSucceed: (context: RunStateContext<SucceedState>) => Promise<JSONSerializable>

Run the given Succeed State.

runTask

runTask: (context: RunStateContext<TaskState>) => Promise<JSONSerializable>

Run the given Task state.

runWait

runWait: (context: RunStateContext<WaitState>) => Promise<JSONSerializable>

Run the given Wait State.

shouldRetry

shouldRetry: (context: {
    errorOutput: ErrorOutput;
    options: RunStateMachineOptions;
    retryCount: number;
    state: State;
    stateName: StateIdentifier;
}) => Promise<boolean>

Figure out whether a failed State should attempt a retry, based on its configuration and the current retry count.

statesArray

statesArray: (...values: JSONSerializable[]) => JSONArray

statesArrayContains

statesArrayContains: (haystack: JSONArray, needle: JSONSerializable) => boolean

statesArrayGetItem

statesArrayGetItem: (array: JSONArray, index: number) => JSONSerializable

statesArrayLength

statesArrayLength: (array: JSONArray) => number

statesArrayPartition

statesArrayPartition: (array: JSONArray, size: number) => JSONArray

statesArrayRange

statesArrayRange: (first: number, last: number, step: number) => number[]

statesArrayUnique

statesArrayUnique: (array: JSONArray) => JSONArray

statesBase64Decode

statesBase64Decode: (encoded: string) => string

statesBase64Encode

statesBase64Encode: (text: string) => string

statesFormat

statesFormat: (text: string, ...values: JSONSerializable[]) => string

statesHash

statesHash: (data: JSONSerializable, algorithm: string) => string

statesJsonMerge

statesJsonMerge: (left: JSONObject, right: JSONObject, deep: boolean) => JSONObject

statesJsonToString

statesJsonToString: (value: JSONSerializable) => string

statesMathAdd

statesMathAdd: (a: number, b: number) => number

statesMathRandom

statesMathRandom: (start: number, end: number, seed?: number) => number

statesStringSplit

statesStringSplit: (text: string, delimiter: string) => string[]

statesStringToJson

statesStringToJson: (text: string) => JSONSerializable

statesUUID

statesUUID: () => string

stringAssertion

stringAssertion: (fieldName: string, stateName: StateIdentifier) => EvaluationAssertion<string>

Builder for an evaluation assertion for a string.

toDataTestLiteralExpressionKey

toDataTestLiteralExpressionKey: (key: Exclude<keyof DataTestExpressions, keyof DataTestLiteralExpressions>) => keyof DataTestLiteralExpressions

tryHandleCatch

tryHandleCatch: (context: {
    input: JSONSerializable;
    error?: Error | undefined;
    errorOutput: ErrorOutput;
    evaluateOutput: (context: RunStateContext<State> & {
        catcher?: Catcher;
        output: JSONSerializable;
    }) => Promise<JSONSerializable>;
    options: RunStateMachineOptions;
    onNextState: (context: RunStateContext<State>) => Promise<JSONSerializable>;
    retryCount: number;
    state: State;
    stateMachine: StateMachine;
    stateName: StateIdentifier;
    stateStack: State[];
}) => Promise<JSONSerializable>

If the current State has a Catch expression, try to evaluate it to see what to do next.

Interfaces

AndExpression

export interface AndExpression 

ArgumentsState

export interface ArgumentsState 

AssignedState

export interface AssignedState 

CanArguments

export interface CanArguments extends Partial<ArgumentsState> 

Included in: Task, Parallel.

CanAssign

export interface CanAssign extends Partial<AssignedState> 

Included in: Choice Rule, Catcher, Map, Parallel.

CanCatchOf

export interface CanCatchOf<Q extends QueryLanguageIdentifier> extends Partial<CatchStateOf<Q>> 

Included in: Task, Parallel, Map

CanComment

export interface CanComment extends Partial<CommentState> 

CanEnd

export interface CanEnd 

Excluded from: Choice State, Succeed State, Fail State.

CanInputOutputPath

export interface CanInputOutputPath extends Partial<InputPathState>, Partial<OutputPathState> 

Excluded from: Succeed, Fail

CanOutput

export interface CanOutput extends Partial<OutputState> 

Excluded from: Fail.

CanParameters

export interface CanParameters extends Partial<ParametersState> 

Included in: Task, Parallel, Map, Pass

CanQueryLanguage

export interface CanQueryLanguage 

CanResultPath

export interface CanResultPath extends Partial<ResultPathState> 

Included in: Task, Parallel, Map, Pass

CanResultSelector

export interface CanResultSelector extends Partial<ResultSelectorState> 

Included in: Task, Parallel, Map

CanRetry

export interface CanRetry extends Partial<RetryState> 

Included in: Task, Parallel, Map

Catcher

export interface Catcher extends CanAssign, NonTerminalState 

CatcherOf

export interface CatcherOf 

CatchState

export interface CatchState 

CatchStateOf

export interface CatchStateOf<Q extends QueryLanguageIdentifier> 

ChoiceStateCommon

export interface ChoiceStateCommon extends CanAssign 

CommentState

export interface CommentState 

DataTestExpressions

export interface DataTestExpressions extends DataTestLiteralExpressions 

DataTestLiteralExpressions

export interface DataTestLiteralExpressions 

EndState

export interface EndState 

ErrorOutput

export interface ErrorOutput 

EvaluationAssertion

export interface EvaluationAssertion<T extends JSONSerializable> 

A value type guard/assertion which should happen after evaluating a JSONata or JSONPath expression.

FailStateCommon

export interface FailStateCommon 

HasTimeoutsState

export interface HasTimeoutsState 

InputPathState

export interface InputPathState 

IntrinsicFunctionCall

export interface IntrinsicFunctionCall 

ItemProcessor

export interface ItemProcessor 

ItemReader

export interface ItemReader 

JSONataCatcher

export interface JSONataCatcher extends Catcher, CanOutput 

JSONataChoiceRule

export interface JSONataChoiceRule extends CanAssign, CanOutput, NonTerminalState 

JSONataChoiceState

export interface JSONataChoiceState extends StateOf<ChoiceType, QueryLanguageJSONata>, ChoiceStateCommon, CanOutput, CanComment 

JSONataFailState

export interface JSONataFailState extends StateOf<FailType, QueryLanguageJSONata>, JSONataFailStateCommon, CanOutput, CanComment 

JSONataFailStateCommon

export interface JSONataFailStateCommon extends FailStateCommon 

JSONataItemBatcher

export interface JSONataItemBatcher 

JSONataItemProcessor

export interface JSONataItemProcessor extends ItemProcessor 

JSONataItemReader

export interface JSONataItemReader extends ItemReader 

JSONataMapStateCommon

export interface JSONataMapStateCommon extends MapStateCommon, CanCatchOf<QueryLanguageJSONata> 

JSONataMapStateWithoutEndOrNext

export interface JSONataMapStateWithoutEndOrNext extends StateOf<MapType, QueryLanguageJSONata>, JSONataMapStateCommon, CanOutput, CanArguments 

JSONataParallelStateWithoutEndOrNext

export interface JSONataParallelStateWithoutEndOrNext extends StateOf<ParallelType, QueryLanguageJSONata>, ParallelStateCommon, CanOutput, CanArguments, CanCatchOf<QueryLanguageJSONata> 

JSONataPassStateWithoutEndOrNext

export interface JSONataPassStateWithoutEndOrNext extends StateOf<PassType, QueryLanguageJSONata>, PassStateCommon, CanOutput 

JSONataResultWriter

export interface JSONataResultWriter extends ResultWriter 

JSONataSucceedState

export interface JSONataSucceedState extends StateOf<SucceedType, QueryLanguageJSONata>, SucceedStateCommon, CanOutput, CanComment 

JSONataTaskStateWithoutEndOrNext

export interface JSONataTaskStateWithoutEndOrNext extends StateOf<TaskType, QueryLanguageJSONata>, TaskStateCommon, CanOutput, CanArguments, CanCatchOf<QueryLanguageJSONata> 

JSONataTaskTimeout

export interface JSONataTaskTimeout 

JSONataWaitStateWithoutEndOrNext

export interface JSONataWaitStateWithoutEndOrNext extends StateOf<WaitType, QueryLanguageJSONata>, WaitStateCommon, CanOutput 

JSONataWaitTimes

export interface JSONataWaitTimes 

JSONPathCatcher

export interface JSONPathCatcher extends Catcher, CanResultPath 

JSONPathChoiceState

export interface JSONPathChoiceState extends StateOf<ChoiceType, QueryLanguageJSONPath>, ChoiceStateCommon, CanInputOutputPath, CanComment 

JSONPathErrorOptions

export interface JSONPathErrorOptions extends ErrorOptions 

JSONPathFailStateCauses

export interface JSONPathFailStateCauses 

JSONPathFailStateErrors

export interface JSONPathFailStateErrors 

JSONPathItemReader

export interface JSONPathItemReader extends ItemReader 

JSONPathMapStateCommon

export interface JSONPathMapStateCommon extends MapStateCommon, CanCatchOf<QueryLanguageJSONPath> 

JSONPathMapStateWithoutEndOrNext

export interface JSONPathMapStateWithoutEndOrNext extends StateOf<MapType, QueryLanguageJSONPath>, JSONPathMapStateCommon, CanInputOutputPath, CanResultPath, CanParameters, CanResultSelector 

JSONPathParallelStateWithoutEndOrNext

export interface JSONPathParallelStateWithoutEndOrNext extends StateOf<ParallelType, QueryLanguageJSONPath>, ParallelStateCommon, CanInputOutputPath, CanResultPath, CanParameters, CanResultSelector, CanCatchOf<QueryLanguageJSONPath> 

JSONPathPassStateWithoutEndOrNext

export interface JSONPathPassStateWithoutEndOrNext extends StateOf<PassType, QueryLanguageJSONPath>, PassStateCommon, CanInputOutputPath, CanResultPath, CanParameters 

JSONPathResultWriter

export interface JSONPathResultWriter extends ResultWriter 

JSONPathSucceedState

export interface JSONPathSucceedState extends StateOf<SucceedType, QueryLanguageJSONPath>, SucceedStateCommon, CanInputOutputPath, CanComment 

JSONPathTaskHeartbeatNumber

export interface JSONPathTaskHeartbeatNumber 

JSONPathTaskHeartbeatPath

export interface JSONPathTaskHeartbeatPath 

JSONPathTaskStateWithoutEndOrNext

export interface JSONPathTaskStateWithoutEndOrNext extends StateOf<TaskType, QueryLanguageJSONPath>, TaskStateCommon, CanInputOutputPath, CanResultPath, CanParameters, CanCatchOf<QueryLanguageJSONPath> 

JSONPathTaskTimeoutNumber

export interface JSONPathTaskTimeoutNumber 

JSONPathTaskTimeoutPath

export interface JSONPathTaskTimeoutPath 

JSONPathWaitFields

export interface JSONPathWaitFields 

JSONPathWaitStateWithoutEndOrNext

export interface JSONPathWaitStateWithoutEndOrNext extends StateOf<WaitType, QueryLanguageJSONPath>, WaitStateCommon, CanInputOutputPath 

MapStateCommon

export interface MapStateCommon extends CanRetry, CanAssign 

NonTerminalState

export interface NonTerminalState 

NonTerminalStateOf

export interface NonTerminalStateOf<S extends StateIdentifier> 

NotExpression

export interface NotExpression 

OrExpression

export interface OrExpression 

OutputPathState

export interface OutputPathState 

OutputState

export interface OutputState 

ParallelBranch

export interface ParallelBranch 

ParallelBranchOf

export interface ParallelBranchOf<S extends StateIdentifier> 

ParallelStateCommon

export interface ParallelStateCommon extends CanRetry, CanAssign 

ParametersState

export interface ParametersState 

PassStateCommon

export interface PassStateCommon extends CanAssign 

QueryEvaluationErrorOptions

export interface QueryEvaluationErrorOptions extends ErrorOptions 

QueryLanguageJSONataState

export interface QueryLanguageJSONataState 

QueryLanguageJSONPathState

export interface QueryLanguageJSONPathState 

ResultPathState

export interface ResultPathState 

ResultSelectorState

export interface ResultSelectorState 

ResultWriter

export interface ResultWriter 

Retrier

export interface Retrier 

RetryState

export interface RetryState 

RunStateContext

export interface RunStateContext<StateT extends State> 

Shared context needed for running any State.

RunStateMachineOptions

export interface RunStateMachineOptions 

Initial options for running a State Machine.

StateForType

export interface StateForType 

StateMachine

export interface StateMachine extends CanComment 

StateMachineOf

export interface StateMachineOf<S extends StateIdentifier, Q extends QueryLanguageIdentifier = QueryLanguageJSONPath> extends StateMachine 

StateOf

export interface StateOf<T extends StateType, Q extends QueryLanguageIdentifier> 

SucceedStateCommon

export interface SucceedStateCommon 

TaskStateCommon

export interface TaskStateCommon extends CanRetry, CanAssign 

WaitSeconds

export interface WaitSeconds 

WaitStateCommon

export interface WaitStateCommon extends CanAssign, NonTerminalState 

WaitTimestamp

export interface WaitTimestamp 

TypeAliases

ARN

type ARN = `arn:aws:${string}`;

ChoiceRule

type ChoiceRule = JSONataChoiceRule | (JSONPathChoiceRule & NonTerminalState);

ChoiceState

type ChoiceState = JSONataChoiceState | JSONPathChoiceState;

ChoiceType

type ChoiceType = typeof TYPE_CHOICE;

DataTestExpression

type DataTestExpression = ExactlyOneOf<DataTestExpressions> & {
    Variable: JSONPathPath;
};

EndOrNext

type EndOrNext = EndState | NonTerminalState;

EndOrNextOf

type EndOrNextOf<S extends StateIdentifier> = EndState | NonTerminalStateOf<S>;

ErrorName

type ErrorName = string;

FailState

type FailState = JSONataFailState | JSONPathFailState;

FailType

type FailType = typeof TYPE_FAIL;

IntrinsicFunctionArg

type IntrinsicFunctionArg = IntrinsicFunctionLiteralArg | IntrinsicFunctionPathArg | IntrinsicFunctionCall;

IntrinsicFunctionExpression

type IntrinsicFunctionExpression = `${IntrinsicFunctionName}(${string})`;

IntrinsicFunctionName

type IntrinsicFunctionName = typeof STATES_ARRAY | typeof STATES_ARRAY_CONTAINS | typeof STATES_ARRAY_GET_ITEM | typeof STATES_ARRAY_LENGTH | typeof STATES_ARRAY_PARTITION | typeof STATES_ARRAY_RANGE | typeof STATES_ARRAY_UNIQUE | typeof STATES_BASE64_DECODE | typeof STATES_BASE64_ENCODE | typeof STATES_FORMAT | typeof STATES_HASH | typeof STATES_JSON_MERGE | typeof STATES_JSON_TO_STRING | typeof STATES_MATH_ADD | typeof STATES_MATH_RANDOM | typeof STATES_STRING_SPLIT | typeof STATES_STRING_TO_JSON | typeof STATES_UUID;

IsoDateTime

type IsoDateTime = `${SimpleIsoDate}T${SimpleIsoTime}${SimpleIsoTimeZone}`;

JSONataMapState

type JSONataMapState = JSONataMapStateWithoutEndOrNext & EndOrNext & CanComment;

JSONataMapStateOf

type JSONataMapStateOf<S extends StateIdentifier> = JSONataMapStateWithoutEndOrNext & EndOrNextOf<S>;

JSONataParallelState

type JSONataParallelState = JSONataParallelStateWithoutEndOrNext & EndOrNext & CanComment;

JSONataParallelStateOf

type JSONataParallelStateOf<S extends StateIdentifier> = JSONataParallelStateWithoutEndOrNext & EndOrNextOf<S>;

JSONataPassState

type JSONataPassState = JSONataPassStateWithoutEndOrNext & EndOrNext & CanComment;

JSONataPassStateOf

type JSONataPassStateOf<S extends StateIdentifier> = JSONataPassStateWithoutEndOrNext & EndOrNextOf<S>;

JSONataString

type JSONataString = `{%${string}%}`;

JSONataTaskState

type JSONataTaskState = JSONataTaskStateWithoutEndOrNext & JSONataTaskTimeout & EndOrNext & CanComment;

JSONataTaskStateOf

type JSONataTaskStateOf<S extends StateIdentifier> = JSONataTaskStateWithoutEndOrNext & JSONataTaskTimeout & EndOrNextOf<S>;

JSONataWaitState

type JSONataWaitState = JSONataWaitStateWithoutEndOrNext & JSONataWaitTime & EndOrNext & CanComment;

JSONataWaitStateOf

type JSONataWaitStateOf<S extends StateIdentifier> = JSONataWaitStateWithoutEndOrNext & JSONataWaitTime & EndOrNextOf<S>;

JSONataWaitTime

type JSONataWaitTime = ExactlyOneOf<JSONataWaitTimes>;

JSONPathChoiceRule

type JSONPathChoiceRule = AndExpression | OrExpression | NotExpression | DataTestExpression;

JSONPathFailState

type JSONPathFailState = StateOf<FailType, QueryLanguageJSONPath> & JSONPathFailStateCommon & CanInputOutputPath & CanComment;

JSONPathFailStateCommon

type JSONPathFailStateCommon = {
    Next?: never;
} & Partial<ExactlyOneOf<JSONPathFailStateCauses>> & Partial<ExactlyOneOf<JSONPathFailStateErrors>>;

JSONPathInterpolated

type JSONPathInterpolated = `${string}.$`;

JSONPathItemBatcher

type JSONPathItemBatcher = {
    BatchInput?: JSONPathPayloadTemplate;
} & Partial<ExactlyOneOf<{
    MaxItemsPerBatch: number;
    MaxItemsPerBatchPath: JSONPathPath;
}>> & Partial<ExactlyOneOf<{
    MaxInputBytesPerBatch: number;
    MaxInputBytesPerBatchPath: JSONPathPath;
}>>;

JSONPathItemProcessor

type JSONPathItemProcessor = ItemProcessor & Partial<ExactlyOneOf<{
    ToleratedFailureCount: number;
    ToleratedFailureCountPath: JSONPathPath;
}>> & Partial<ExactlyOneOf<{
    ToleratedFailurePercentage: number;
    ToleratedFailurePercentagePath: JSONPathPath;
}>>;

JSONPathMapMaxConcurrency

type JSONPathMapMaxConcurrency = Partial<ExactlyOneOf<{
    MaxConcurrency: number;
    MaxConcurrencyPath: JSONPathPath;
}>>;

JSONPathMapState

type JSONPathMapState = JSONPathMapStateWithoutEndOrNext & JSONPathMapMaxConcurrency & EndOrNext & CanComment;

JSONPathMapStateOf

type JSONPathMapStateOf<S extends StateIdentifier> = JSONPathMapStateWithoutEndOrNext & JSONPathMapMaxConcurrency & EndOrNextOf<S>;

JSONPathParallelState

type JSONPathParallelState = JSONPathParallelStateWithoutEndOrNext & EndOrNext & CanComment;

JSONPathParallelStateOf

type JSONPathParallelStateOf<S extends StateIdentifier> = JSONPathParallelStateWithoutEndOrNext & EndOrNextOf<S>;

JSONPathPassState

type JSONPathPassState = JSONPathPassStateWithoutEndOrNext & EndOrNext & CanComment;

JSONPathPassStateOf

type JSONPathPassStateOf<S extends StateIdentifier> = JSONPathPassStateWithoutEndOrNext & EndOrNextOf<S>;

JSONPathPath

type JSONPathPath = `$${string}`;

JSONPathTaskState

type JSONPathTaskState = JSONPathTaskStateWithoutEndOrNext & JSONPathTaskTimeout & EndOrNext & CanComment;

JSONPathTaskStateOf

type JSONPathTaskStateOf<S extends StateIdentifier> = JSONPathTaskStateWithoutEndOrNext & JSONPathTaskTimeout & EndOrNextOf<S>;

JSONPathTaskTimeout

type JSONPathTaskTimeout = (JSONPathTaskTimeoutNumber | JSONPathTaskHeartbeatNumber) & (JSONPathTaskTimeoutPath | JSONPathTaskHeartbeatPath);

JSONPathWaitState

type JSONPathWaitState = JSONPathWaitStateWithoutEndOrNext & JSONPathWaitTime & EndOrNext & CanComment;

JSONPathWaitStateOf

type JSONPathWaitStateOf<S extends StateIdentifier> = JSONPathWaitStateWithoutEndOrNext & JSONPathWaitTime & EndOrNextOf<S>;

JSONPathWaitTime

type JSONPathWaitTime = ExactlyOneOf<JSONPathWaitFields>;

MapState

type MapState = JSONataMapState | JSONPathMapState;

MapStateOf

type MapStateOf<S extends StateIdentifier> = JSONataMapStateOf<S> | JSONPathMapStateOf<S>;

MapType

type MapType = typeof TYPE_MAP;

ParallelState

type ParallelState = JSONataParallelState | JSONPathParallelState;

ParallelStateOf

type ParallelStateOf<S extends StateIdentifier> = JSONataParallelStateOf<S> | JSONPathParallelStateOf<S>;

ParallelType

type ParallelType = typeof TYPE_PARALLEL;

PassState

type PassState = JSONataPassState | JSONPathPassState;

PassStateOf

type PassStateOf<S extends StateIdentifier> = JSONataPassStateOf<S> | JSONPathPassStateOf<S>;

PassType

type PassType = typeof TYPE_PASS;

QueryLanguageIdentifier

type QueryLanguageIdentifier = QueryLanguageJSONata | QueryLanguageJSONPath;

QueryLanguageJSONata

type QueryLanguageJSONata = typeof JSONATA;

QueryLanguageJSONPath

type QueryLanguageJSONPath = typeof JSONPATH;

ResourceHandlerResolver

type ResourceHandlerResolver = (resourceUri: ResourceURI) => StepFunctionLambdaLike;

Resolve a resource URI to a local runnable function.

ResourceURI

type ResourceURI = string;

SimpleIsoDate

type SimpleIsoDate = `${number}${number}${number}${number}-${number}${number}-${number}${number}`;

SimpleIsoTime

type SimpleIsoTime = `${number}${number}:${number}${number}:${number}${number}${"" | `.${number}`}`;

SimpleIsoTimeZone

type SimpleIsoTimeZone = "Z" | `${"+" | "-"}${number}${number}:${number}${number}`;

State

type State = ChoiceState | FailState | MapState | ParallelState | PassState | SucceedState | TaskState | WaitState;

StateIdentifier

type StateIdentifier = string;

StatesAll

type StatesAll = typeof STATES_ALL;

StatesHashAlgorithm

type StatesHashAlgorithm = ItemType<typeof STATES_HASH_ALGORITHMS>;

StateType

type StateType = TaskType | SucceedType | FailType | ParallelType | MapType | ChoiceType | PassType | WaitType;

StepFunctionLambdaLike

type StepFunctionLambdaLike = (...args: any) => (JSONSerializable | undefined | Promise<JSONSerializable | undefined> | void);

A (local) function which accepts only JSON-serializable params and returns only JSON-serializable results, if any, or a promise for the same.

SucceedState

type SucceedState = JSONataSucceedState | JSONPathSucceedState;

SucceedType

type SucceedType = typeof TYPE_SUCCEED;

TaskState

type TaskState = JSONataTaskState | JSONPathTaskState;

TaskStateOf

type TaskStateOf<S extends StateIdentifier> = JSONataTaskStateOf<S> | JSONPathTaskStateOf<S>;

TaskType

type TaskType = typeof TYPE_TASK;

TerminalState

type TerminalState = EndState | SucceedState | FailState;

VariableName

type VariableName = string;

WaitState

type WaitState = JSONataWaitState | JSONPathWaitState;

WaitStateOf

type WaitStateOf<S extends StateIdentifier> = JSONataWaitStateOf<S> | JSONPathWaitStateOf<S>;

WaitTime

type WaitTime = WaitSeconds | WaitTimestamp;

WaitType

type WaitType = typeof TYPE_WAIT;

Variables

JSONATA

JSONATA = "JSONata"

JSONPATH

JSONPATH = "JSONPath"

STATES_ALL

STATES_ALL = "States.ALL"

STATES_ARRAY

STATES_ARRAY = "States.Array"

STATES_ARRAY_CONTAINS

STATES_ARRAY_CONTAINS = "States.ArrayContains"

STATES_ARRAY_GET_ITEM

STATES_ARRAY_GET_ITEM = "States.ArrayGetItem"

STATES_ARRAY_LENGTH

STATES_ARRAY_LENGTH = "States.ArrayLength"

STATES_ARRAY_PARTITION

STATES_ARRAY_PARTITION = "States.ArrayPartition"

STATES_ARRAY_RANGE

STATES_ARRAY_RANGE = "States.ArrayRange"

STATES_ARRAY_UNIQUE

STATES_ARRAY_UNIQUE = "States.ArrayUnique"

STATES_BASE64_DECODE

STATES_BASE64_DECODE = "States.Base64Decode"

STATES_BASE64_ENCODE

STATES_BASE64_ENCODE = "States.Base64Encode"

STATES_BRANCH_FAILED

STATES_BRANCH_FAILED = "States.BranchFailed"

STATES_EXCEED_TOLERATED_FAILURE_THRESHOLD

STATES_EXCEED_TOLERATED_FAILURE_THRESHOLD = "States.ExceedToleratedFailureThreshold"

STATES_FORMAT

STATES_FORMAT = "States.Format"

STATES_HASH

STATES_HASH = "States.Hash"

STATES_HASH_ALGORITHMS

STATES_HASH_ALGORITHMS: readonly ["MD5", "SHA-1", "SHA-256", "SHA-384", "SHA-512"]

STATES_HASH_MD5

STATES_HASH_MD5 = "MD5"

STATES_HASH_SHA1

STATES_HASH_SHA1 = "SHA-1"

STATES_HASH_SHA256

STATES_HASH_SHA256 = "SHA-256"

STATES_HASH_SHA384

STATES_HASH_SHA384 = "SHA-384"

STATES_HASH_SHA512

STATES_HASH_SHA512 = "SHA-512"

STATES_HEARTBEAT_TIMEOUT

STATES_HEARTBEAT_TIMEOUT = "States.HeartbeatTimeout"

STATES_INTRINSIC_FAILURE

STATES_INTRINSIC_FAILURE = "States.IntrinsicFailure"

STATES_ITEM_READER_FAILED

STATES_ITEM_READER_FAILED = "States.ItemReaderFailed"

STATES_JSON_MERGE

STATES_JSON_MERGE = "States.JsonMerge"

STATES_JSON_TO_STRING

STATES_JSON_TO_STRING = "States.JsonToString"

STATES_MATH_ADD

STATES_MATH_ADD = "States.MathAdd"

STATES_MATH_RANDOM

STATES_MATH_RANDOM = "States.MathRandom"

STATES_NO_CHOICE_MATCHED

STATES_NO_CHOICE_MATCHED = "States.NoChoiceMatched"

STATES_PARAMETER_PATH_FAILURE

STATES_PARAMETER_PATH_FAILURE = "States.ParameterPathFailure"

STATES_PERMISSIONS

STATES_PERMISSIONS = "States.Permissions"

STATES_QUERY_EVALUATION_ERROR

STATES_QUERY_EVALUATION_ERROR = "States.QueryEvaluationError"

STATES_RESULT_PATH_MATCH_FAILURE

STATES_RESULT_PATH_MATCH_FAILURE = "States.ResultPathMatchFailure"

STATES_RESULT_WRITER_FAILED

STATES_RESULT_WRITER_FAILED = "States.ResultWriterFailed"

STATES_STRING_SPLIT

STATES_STRING_SPLIT = "States.StringSplit"

STATES_STRING_TO_JSON

STATES_STRING_TO_JSON = "States.StringToJson"

STATES_TASK_FAILED

STATES_TASK_FAILED = "States.TaskFailed"

STATES_TIMEOUT

STATES_TIMEOUT = "States.Timeout"

STATES_UUID

STATES_UUID = "States.UUID"

TYPE_CHOICE

TYPE_CHOICE = "Choice"

TYPE_FAIL

TYPE_FAIL = "Fail"

TYPE_MAP

TYPE_MAP = "Map"

TYPE_PARALLEL

TYPE_PARALLEL = "Parallel"

TYPE_PASS

TYPE_PASS = "Pass"

TYPE_SUCCEED

TYPE_SUCCEED = "Succeed"

TYPE_TASK

TYPE_TASK = "Task"

TYPE_WAIT

TYPE_WAIT = "Wait"

VERSION_1

VERSION_1 = "1.0"