@wmfs/statebox

Orchestrate Node functions using Amazon States Language

Useful links

• AWS Step Functions - overview of Amazon States Language, use cases, etc
• statelint - a validator for Amazon States Language JSON files
• https://docs.aws.amazon.com/step-functions/latest/dg/concepts-amazon-states-language.html
• https://docs.aws.amazon.com/step-functions/latest/apireference/API_SendTaskSuccess.html

Install

$ npm install @wmfs/statebox --save

Usage

const Statebox = require('@wmfs/statebox')
const statebox = new Statebox({})

const main = async

function() {

  // STEP 1:
  // Create some 'module' resources (i.e. Javascript
  // classes with 'run' and optional 'init' methods)
  // that state machines can then refer to...
  // -------------------------------------------------
  await statebox.ready
  statebox.createModuleResources({
    // Simple module to add two numbers together
    add: class Add {
      run(event, context) {
        context.sendTaskSuccess(event.number1 + event.number2)
      }
    },
    // Simple module to subtract one number from another
    subtract: class Subtract {
      // Init methods are optional, but all allow
      // resource-instances to be configured...
      init(resourceConfig, env, callback) {
        callback(null)
      }
      run(event, context) {
        context.sendTaskSuccess(event.number1 - event.number2)
      }
    }
  })

  // STEP 2:
  // Next create a new 'calculator' state
  // machine using Amazon States Language...
  // ---------------------------------------
  await statebox.createStateMachines({
      'calculator': {
        Comment: 'A simple calculator',
        StartAt: 'OperatorChoice',
        States: {
          OperatorChoice: {
            Type: 'Choice',
            Choices: [{
              Variable: '$.operator',
              StringEquals: '+',
              Next: 'Add'
            }, {
              Variable: '$.operator',
              StringEquals: '-',
              Next: 'Subtract'
            }]
          },
          Add: {
            Type: 'Task',
            InputPath: '$.numbers',
            Resource: 'module:add', // See createModuleResources()
            ResultPath: '$.result',
            End: true
          },
          Subtract: {
            Type: 'Task',
            InputPath: '$.numbers',
            Resource: 'module:subtract',
            ResultPath: '$.result',
            End: true
          }
        }
      }
    }, {}, // 'env': An environment/context/sandbox
  )

  // STEP 3:
  // Start a new execution on a state machine
  // ----------------------------------------
  const executionDescription = await statebox.startExecution({
      numbers: {
        number1: 3,
        number2: 2
      },
      operator: '-'
    }, // input
    'calculator', // state machine name
    {} // options
  )

  // STEP 4:
  // Look at the results...
  // ----------------------
  console.log(executionDescription)
  //  Result object
  //  -------------
  // {
  //   executionName: '...',
  //   ctx: {
  //     numbers': {
  //       number1: 3,
  //       number2: 2
  //     },
  //     operator: '-',
  //     result: 1 <--- The important bit :-)
  //   },
  //   currentStateName:'Subtract',
  //   currentResource:'module:subtract',
  //   stateMachineName:'calculator',
  //   startDate: '2018-09-03T21:58:04.287Z'
  // }
}

if (require.main === module) {
  main();
}

Testing

$ npm test

License

MIT

Changelog

1.74.0 (2020-11-09)

✨ Features

• instrinsic-functions: States.Array (d724019)
• instrinsics: Start of States.Format function (cb48f07)
• instrinsics: States.JsonToString (d84ddef)
• instrinsics: States.StringToJson (ecb74fe)
• instrinsics: States.StringToJson done (f0fb332)
• intrinsics: States.Format error conditions (7c735d5)
• Argument parsing (51d8710)
• More rigourous call checking (76fcec2)
• Start on function argument parsing (6af3243)

🐛 Bug Fixes

• input-path-handler: Parse out and start to evaluate intrinsic functions (f38f920)
• input-path-handler: Starting to extend tokeniser to handle instrinsics (cec942b)
• input-path-handler: tokenise functions with a single parameter (99ccfbe)
• input-path-handler: tokenise functions with multiple parameters (b372981)
• instrinsics: corrected string regex (6e8eddb)
• instrinsics: Extend parameter parsing to evaluate path expressions (7be262f)
• instrinsics: Tweak instrinsic function rule, so they can appear in the parameter list (502c150)
• intrinsics: Escape sequences in States.Format (65335c4)
• intrinsics: JsonToString parameter validation (e25c123)
• intrinsics: Tokenise strings with escape sequences correctly (3fca040)
• Format null values (5916eb3)
• More work on argument parsing (643ca39)
• Multiple substitutions, substitution at start and at end (d059584)
• Parse multiple arguments separated by , (2c892d4)
• Strip extraneous whitespace while tokenising arguments (c75d406)
• State.Format: more wrong number of arguments tests (f1419a2)
• States.Format: validate number of arguments (bc9e68f)
• Simple value substitution (2d06029)

🛠 Builds

• deps-dev: bump codecov from 3.8.0 to 3.8.1 (2560e3a)
• deps-dev: bump mocha from 8.2.0 to 8.2.1 (2ac8e6e)
• deps-dev: bump semantic-release from 17.2.1 to 17.2.2 (cbcc88f)
• deps-dev: bump standard from 15.0.1 to 16.0.0 (d7bb9d5)
• deps-dev: bump standard from 16.0.0 to 16.0.1 (ad043ba)

📦 Code Refactoring

• Changed intrinsic-function fixture name (1930afb)
• input-path-handler: Use tokenizr when evaluating Path expressions (f7d227f)
• input-path-selector: Renamed ctx to input - matches spec text better (fc3e681)
• instrinsics: Convert strings to values after tokenisation, instead of during (16bc45f)
• instrinsics: jiggled test descriptions a little (2fe5cdf)
• intrinsics: States.Format error handling (c4d893a)
• intrinsics: StringToJson parameter validation (b14391e)
• Hook States.Format implementation into input path handler (944018b)
• Move instrinics subdirectory under state-types (92207a6)

🚨 Tests

• failing: Nested instrinsic tokenising tests (9103b64)
• failing: Nested intrinsic function calls (9eb38f4)
• intrinsics: Extra JsonToString state machine tests (00a9f48)
• intrinsics: More State.Format tests (41b1ca5)
• intrinsics: States.Array state machine tests (c374b5b)
• intrinsics: States.JsonToString state machine tests (cbad475)
• Combine instrinsics tests into a single test file (a6106ae)

💎 Styles

• Lint fix (63b4ae4)