Skip to content

API.md

Latest commit

 

History

History
991 lines (606 loc) · 36 KB

API.md

File metadata and controls

991 lines (606 loc) · 36 KB

API Reference

Constructs

StateMachine

Initializers 

import { StateMachine } from '@matthewbonig/state-machine'

new StateMachine(scope: Construct, id: string, props: StateMachineProps)
Name Type Description
scope constructs.Construct No description.
id string No description.
props StateMachineProps No description.
scopeRequired
  • Type: constructs.Construct
idRequired
  • Type: string
propsRequired

Methods

Name Description
toString Returns a string representation of this construct.
applyRemovalPolicy Apply the given removal policy to this resource.
addToRolePolicy Add the given statement to the role's policy.
grant Grant the given identity custom permissions.
grantExecution Grant the given identity permissions on all executions of the state machine.
grantRead Grant the given identity permissions to read results from state machine.
grantRedriveExecution Grant the given identity permission to redrive the execution of the state machine.
grantStartExecution Grant the given identity permissions to start an execution of this state machine.
grantStartSyncExecution Grant the given identity permissions to start a synchronous execution of this state machine.
grantTaskResponse Grant the given identity task response permissions on a state machine.
metric Return the given named metric for this State Machine's executions.
metricAborted Metric for the number of executions that were aborted.
metricFailed Metric for the number of executions that failed.
metricStarted Metric for the number of executions that were started.
metricSucceeded Metric for the number of executions that succeeded.
metricThrottled Metric for the number of executions that were throttled.
metricTime Metric for the interval, in milliseconds, between the time the execution starts and the time it closes.
metricTimedOut Metric for the number of executions that timed out.
toString 
public toString(): string

Returns a string representation of this construct.

applyRemovalPolicy 
public applyRemovalPolicy(policy: RemovalPolicy): void

Apply the given removal policy to this resource.

The Removal Policy controls what happens to this resource when it stops being managed by CloudFormation, either because you've removed it from the CDK application or because you've made a change that requires the resource to be replaced.

The resource can be deleted (RemovalPolicy.DESTROY), or left in your AWS account for data recovery and cleanup later (RemovalPolicy.RETAIN).

policyRequired
  • Type: aws-cdk-lib.RemovalPolicy
addToRolePolicy 
public addToRolePolicy(statement: PolicyStatement): void

Add the given statement to the role's policy.

statementRequired
  • Type: aws-cdk-lib.aws_iam.PolicyStatement
grant 
public grant(identity: IGrantable, actions: ...string[]): Grant

Grant the given identity custom permissions.

identityRequired
  • Type: aws-cdk-lib.aws_iam.IGrantable
actionsRequired
  • Type: ...string[]
grantExecution 
public grantExecution(identity: IGrantable, actions: ...string[]): Grant

Grant the given identity permissions on all executions of the state machine.

identityRequired
  • Type: aws-cdk-lib.aws_iam.IGrantable
actionsRequired
  • Type: ...string[]
grantRead 
public grantRead(identity: IGrantable): Grant

Grant the given identity permissions to read results from state machine.

identityRequired
  • Type: aws-cdk-lib.aws_iam.IGrantable
grantRedriveExecution 
public grantRedriveExecution(identity: IGrantable): Grant

Grant the given identity permission to redrive the execution of the state machine.

identityRequired
  • Type: aws-cdk-lib.aws_iam.IGrantable
grantStartExecution 
public grantStartExecution(identity: IGrantable): Grant

Grant the given identity permissions to start an execution of this state machine.

identityRequired
  • Type: aws-cdk-lib.aws_iam.IGrantable
grantStartSyncExecution 
public grantStartSyncExecution(identity: IGrantable): Grant

Grant the given identity permissions to start a synchronous execution of this state machine.

identityRequired
  • Type: aws-cdk-lib.aws_iam.IGrantable
grantTaskResponse 
public grantTaskResponse(identity: IGrantable): Grant

Grant the given identity task response permissions on a state machine.

identityRequired
  • Type: aws-cdk-lib.aws_iam.IGrantable
metric 
public metric(metricName: string, props?: MetricOptions): Metric

Return the given named metric for this State Machine's executions.

metricNameRequired
  • Type: string
propsOptional
  • Type: aws-cdk-lib.aws_cloudwatch.MetricOptions
metricAborted 
public metricAborted(props?: MetricOptions): Metric

Metric for the number of executions that were aborted.

propsOptional
  • Type: aws-cdk-lib.aws_cloudwatch.MetricOptions
metricFailed 
public metricFailed(props?: MetricOptions): Metric

Metric for the number of executions that failed.

propsOptional
  • Type: aws-cdk-lib.aws_cloudwatch.MetricOptions
metricStarted 
public metricStarted(props?: MetricOptions): Metric

Metric for the number of executions that were started.

propsOptional
  • Type: aws-cdk-lib.aws_cloudwatch.MetricOptions
metricSucceeded 
public metricSucceeded(props?: MetricOptions): Metric

Metric for the number of executions that succeeded.

propsOptional
  • Type: aws-cdk-lib.aws_cloudwatch.MetricOptions
metricThrottled 
public metricThrottled(props?: MetricOptions): Metric

Metric for the number of executions that were throttled.

propsOptional
  • Type: aws-cdk-lib.aws_cloudwatch.MetricOptions
metricTime 
public metricTime(props?: MetricOptions): Metric

Metric for the interval, in milliseconds, between the time the execution starts and the time it closes.

propsOptional
  • Type: aws-cdk-lib.aws_cloudwatch.MetricOptions
metricTimedOut 
public metricTimedOut(props?: MetricOptions): Metric

Metric for the number of executions that timed out.

propsOptional
  • Type: aws-cdk-lib.aws_cloudwatch.MetricOptions

Static Functions

Name Description
isConstruct Checks if x is a construct.
isOwnedResource Returns true if the construct was created by CDK, and false otherwise.
isResource Check whether the given construct is a Resource.
fromStateMachineArn Import a state machine.
fromStateMachineName Import a state machine via resource name.
isConstruct 
import { StateMachine } from '@matthewbonig/state-machine'

StateMachine.isConstruct(x: any)

Checks if x is a construct.

Use this method instead of instanceof to properly detect Construct instances, even when the construct library is symlinked.

Explanation: in JavaScript, multiple copies of the constructs library on disk are seen as independent, completely different libraries. As a consequence, the class Construct in each copy of the constructs library is seen as a different class, and an instance of one class will not test as instanceof the other class. npm install will not create installations like this, but users may manually symlink construct libraries together or use a monorepo tool: in those cases, multiple copies of the constructs library can be accidentally installed, and instanceof will behave unpredictably. It is safest to avoid using instanceof, and using this type-testing method instead.

xRequired
  • Type: any

Any object.

isOwnedResource 
import { StateMachine } from '@matthewbonig/state-machine'

StateMachine.isOwnedResource(construct: IConstruct)

Returns true if the construct was created by CDK, and false otherwise.

constructRequired
  • Type: constructs.IConstruct
isResource 
import { StateMachine } from '@matthewbonig/state-machine'

StateMachine.isResource(construct: IConstruct)

Check whether the given construct is a Resource.

constructRequired
  • Type: constructs.IConstruct
fromStateMachineArn 
import { StateMachine } from '@matthewbonig/state-machine'

StateMachine.fromStateMachineArn(scope: Construct, id: string, stateMachineArn: string)

Import a state machine.

scopeRequired
  • Type: constructs.Construct
idRequired
  • Type: string
stateMachineArnRequired
  • Type: string
fromStateMachineName 
import { StateMachine } from '@matthewbonig/state-machine'

StateMachine.fromStateMachineName(scope: Construct, id: string, stateMachineName: string)

Import a state machine via resource name.

scopeRequired
  • Type: constructs.Construct
idRequired
  • Type: string
stateMachineNameRequired
  • Type: string

Properties

Name Type Description
node constructs.Node The tree node.
env aws-cdk-lib.ResourceEnvironment The environment this resource belongs to.
stack aws-cdk-lib.Stack The stack in which this resource is defined.
grantPrincipal aws-cdk-lib.aws_iam.IPrincipal The principal this state machine is running as.
role aws-cdk-lib.aws_iam.IRole Execution role of this state machine.
stateMachineArn string The ARN of the state machine.
stateMachineName string The name of the state machine.
stateMachineRevisionId string Identifier for the state machine revision, which is an immutable, read-only snapshot of a state machine’s definition and configuration.
stateMachineType aws-cdk-lib.aws_stepfunctions.StateMachineType Type of the state machine.
nodeRequired 
public readonly node: Node;
  • Type: constructs.Node

The tree node.

envRequired 
public readonly env: ResourceEnvironment;
  • Type: aws-cdk-lib.ResourceEnvironment

The environment this resource belongs to.

For resources that are created and managed by the CDK (generally, those created by creating new class instances like Role, Bucket, etc.), this is always the same as the environment of the stack they belong to; however, for imported resources (those obtained from static methods like fromRoleArn, fromBucketName, etc.), that might be different than the stack they were imported into.

stackRequired 
public readonly stack: Stack;
  • Type: aws-cdk-lib.Stack

The stack in which this resource is defined.

grantPrincipalRequired 
public readonly grantPrincipal: IPrincipal;
  • Type: aws-cdk-lib.aws_iam.IPrincipal

The principal this state machine is running as.

roleRequired 
public readonly role: IRole;
  • Type: aws-cdk-lib.aws_iam.IRole

Execution role of this state machine.

stateMachineArnRequired 
public readonly stateMachineArn: string;
  • Type: string

The ARN of the state machine.

stateMachineNameRequired 
public readonly stateMachineName: string;
  • Type: string

The name of the state machine.

stateMachineRevisionIdRequired 
public readonly stateMachineRevisionId: string;
  • Type: string

Identifier for the state machine revision, which is an immutable, read-only snapshot of a state machine’s definition and configuration.

stateMachineTypeRequired 
public readonly stateMachineType: StateMachineType;
  • Type: aws-cdk-lib.aws_stepfunctions.StateMachineType

Type of the state machine.

Constants

Name Type Description
PROPERTY_INJECTION_ID string Uniquely identifies this class.
PROPERTY_INJECTION_IDRequired 
public readonly PROPERTY_INJECTION_ID: string;
  • Type: string

Uniquely identifies this class.

StepFunctionsAutoDiscover

A projen component for discovering AWS Step Function state machine workflow ASL files and generating a strongly typed interface and construct to use it.

Simply add a new instance and hand it your AwsCdkTypeScriptApp projen class:

const project = new AwsCdkTypeScriptApp({ ... });
new StepFunctionsAutoDiscover(project);

And any *.workflow.json file will cause the generation of a new strongly-typed StateMachine-derived class you can use. Note that these constructs are NOT jsii-compatible. If you need that, please open an issue

Initializers 

import { StepFunctionsAutoDiscover } from '@matthewbonig/state-machine'

new StepFunctionsAutoDiscover(project: AwsCdkTypeScriptApp, _options?: StepFunctionsAutoDiscoverOptions)
Name Type Description
project projen.awscdk.AwsCdkTypeScriptApp No description.
_options StepFunctionsAutoDiscoverOptions No description.
projectRequired
  • Type: projen.awscdk.AwsCdkTypeScriptApp
_optionsOptional

Methods

Name Description
toString Returns a string representation of this construct.
postSynthesize Called after synthesis.
preSynthesize Called before synthesis.
synthesize Synthesizes files to the project output directory.
toString 
public toString(): string

Returns a string representation of this construct.

postSynthesize 
public postSynthesize(): void

Called after synthesis.

Order is not guaranteed.

preSynthesize 
public preSynthesize(): void

Called before synthesis.

synthesize 
public synthesize(): void

Synthesizes files to the project output directory.

Static Functions

Name Description
isConstruct Checks if x is a construct.
isComponent Test whether the given construct is a component.
isConstruct 
import { StepFunctionsAutoDiscover } from '@matthewbonig/state-machine'

StepFunctionsAutoDiscover.isConstruct(x: any)

Checks if x is a construct.

Use this method instead of instanceof to properly detect Construct instances, even when the construct library is symlinked.

Explanation: in JavaScript, multiple copies of the constructs library on disk are seen as independent, completely different libraries. As a consequence, the class Construct in each copy of the constructs library is seen as a different class, and an instance of one class will not test as instanceof the other class. npm install will not create installations like this, but users may manually symlink construct libraries together or use a monorepo tool: in those cases, multiple copies of the constructs library can be accidentally installed, and instanceof will behave unpredictably. It is safest to avoid using instanceof, and using this type-testing method instead.

xRequired
  • Type: any

Any object.

isComponent 
import { StepFunctionsAutoDiscover } from '@matthewbonig/state-machine'

StepFunctionsAutoDiscover.isComponent(x: any)

Test whether the given construct is a component.

xRequired
  • Type: any

Properties

Name Type Description
node constructs.Node The tree node.
project projen.Project No description.
entrypoints string[] Auto-discovered entry points with paths relative to the project directory.
nodeRequired 
public readonly node: Node;
  • Type: constructs.Node

The tree node.

projectRequired 
public readonly project: Project;
  • Type: projen.Project
entrypointsRequired 
public readonly entrypoints: string[];
  • Type: string[]

Auto-discovered entry points with paths relative to the project directory.

Structs

StateMachineProps

Initializer 

import { StateMachineProps } from '@matthewbonig/state-machine'

const stateMachineProps: StateMachineProps = { ... }

Properties

Name Type Description
definition any An object that can be serialized into an ASL.
aslYaml boolean Should the ASL definition be written as YAML.
logs aws-cdk-lib.aws_stepfunctions.LogOptions Defines what execution history events are logged and where they are logged.
overrides any An object that matches the schema/shape of the ASL .States map with overridden values.
role aws-cdk-lib.aws_iam.IRole The execution role for the state machine service.
stateMachineName string A name for the state machine.
stateMachineType aws-cdk-lib.aws_stepfunctions.StateMachineType Type of the state machine.
timeout aws-cdk-lib.Duration Maximum run time for this state machine.
tracingEnabled boolean Specifies whether Amazon X-Ray tracing is enabled for this state machine.
definitionRequired 
public readonly definition: any;
  • Type: any

An object that can be serialized into an ASL.

aslYamlOptional 
public readonly aslYaml: boolean;
  • Type: boolean
  • Default: false

Should the ASL definition be written as YAML.

logsOptional 
public readonly logs: LogOptions;
  • Type: aws-cdk-lib.aws_stepfunctions.LogOptions
  • Default: No logging

Defines what execution history events are logged and where they are logged.

overridesOptional 
public readonly overrides: any;
  • Type: any

An object that matches the schema/shape of the ASL .States map with overridden values.

Example

{'My First State': { Parameters: { FunctionName: 'aLambdaFunctionArn' } } }
roleOptional 
public readonly role: IRole;
  • Type: aws-cdk-lib.aws_iam.IRole
  • Default: A role is automatically created

The execution role for the state machine service.

stateMachineNameOptional 
public readonly stateMachineName: string;
  • Type: string
  • Default: A name is automatically generated

A name for the state machine.

stateMachineTypeOptional 
public readonly stateMachineType: StateMachineType;
  • Type: aws-cdk-lib.aws_stepfunctions.StateMachineType
  • Default: StateMachineType.STANDARD

Type of the state machine.

timeoutOptional 
public readonly timeout: Duration;
  • Type: aws-cdk-lib.Duration
  • Default: No timeout

Maximum run time for this state machine.

tracingEnabledOptional 
public readonly tracingEnabled: boolean;
  • Type: boolean
  • Default: false

Specifies whether Amazon X-Ray tracing is enabled for this state machine.

StepFunctionsAutoDiscoverOptions

Initializer 

import { StepFunctionsAutoDiscoverOptions } from '@matthewbonig/state-machine'

const stepFunctionsAutoDiscoverOptions: StepFunctionsAutoDiscoverOptions = { ... }

Properties

Name Type Description
extension string An optional extension to use for discovering state machine files.
extensionOptional 
public readonly extension: string;
  • Type: string
  • Default: '.workflow.json' (JSON_STEPFUNCTION_EXT)

An optional extension to use for discovering state machine files.