instructions v1.1.1

Instructions

Chain of instructions to process your input.

Installing

Using yarn:

yarn add instructions

Using npm:

npm install --save instructions

Start chain of Instructions

Start a chain of instructions using startWith function.

startWith will return an instance of Instruction.

Arguments

• value: any: Input to be processed with chain of instructions.

Returns

• (Instruction): Return a new Instruction wrapper instance.

Example

Create an inital instruction with startWith.

const { startWith } = require('instructions');

const initialInstructions = startWith({});

Chaining up instructions.

const { startWith } = require('instructions');

const instructions = startWith({})
  .then(doSomething)
  .ifElse(predicate, truthyHalder, falsyHandler)
  .then(doAnotherThing);

Instruction methods

Notes

• All Instruction methods except toPromise() will return an instance of Instruction allowing you to chain your instructions.
• All handlers should return a value which will be passed to as first argument of next handler in the chain of instructions.
• Handlers can be sync or async function.

.toPromise(formatter)

Returns result of instructions chain as Promise.

Arguments

• (Optional) formatter: (any): any: Handler to format the result before being returned as Promise.

Example

const result = startWith({ message: 'Hello World' }).toPromise();

console.log(result); // => Promise< pending >

result.then((value) => console.log(value.message)); // => 'Hello World'

.then(handler)

Like Promise.then(), handler receives value from previous handler as argument and returns a value which will be passed on to next Instruction in chain.

Arguments

• handler: (any): any: Function that receive result of previous Instruction and returns input for next Instruction.

Example

await startWith({})
  .then((value) => {
    value.message = 'Hello World';
    return value;
  })
  .toPromise(); // { message: 'Hello World' }

.ifElse(condition, truthyHandler, falsyHandler)

Instruction that will process either truthyHanlder or falsyHandler depending on result of condition predicate.

Arguments

• condition(any): boolean: Function which will receive result of previous Instruction as argument. Result which returned from this function will determine either truthyHandler or falsyHandler will be processed.
• trutyHandler(any): any: Standard Instruction handler which will be processed if condition predicate returns truthy value.
• falsyHandler(any): any: Standard Instruction handler which will be processed if condition predicate returns falsy value.

Example

await startWith({})
  .ifElse(
    () => true,
    () => ({ message: 'Predicate returns true!' }),
    () => ({ message: 'Predicate returns false!' }),
  ).toPromise(); // => { message: 'Predicate returns true!' }

.failOver(handler, failOverHandler)

Instruction which will process failOverHandler if handler throw an exception.

Arguments

• handler(any): any: Standard Instruction handler.
• failOverHandler(any, Error): any Standard Instruction handler which will be processed if handler throw an exception. Exception will be passed as second argument.

Example

await startWith({})
  .failOver(
    () => throw Error('Boom!'),
    (_, err) => ({ message: err.message + ' is catched' }),
  ).toPromise(); // => { message: 'Boom! is catched' }

.concurrent(handlers)

Instruction which receives an array of handlers then executes them concurrently. Result of all handlers will be merged then passed to next Instruction.

Arguments

• handlers: ((any): any)[]: An array of handlers which will be executed concurrently.

Example

await startWith({})
  .concurrent([
    () => ({ message1: 'Hi Mom!'}),
    () => ({ message2: 'Hi Dad!'}),
  ]).toPromise(); // => { message1: 'Hi Mom!', message2: 'Hi Dad!' }

.inCaseOf(condition, cases)

Instruction which will process handler of case that match with the result of condition predicate.

Arguments

• condition(any): any: Function that receive result of last Instruction as argument and which result will be evaluated to decide which case will be processed.
• cases: any, (any) => any: An array of tuple.
  • First element of tuple will be tested with result of condition predicate.
  • Second element is standard handler.
  • Note: a wildcard(*) case is required. This case will be processed if no other case is matched. The result of condition predicate will be passed as second argument of wildcard case handler.

Example

await startWith({})
  .inCaseOf(
    () => 5,
    [
      [1, () => ({ message: 'The result is 1' })],
      [2, () => ({ message: 'The result is 2' })],
      ['*', (_, predicateResult) => ({ message: 'The result is ' + predicateResult })],
    ]
  ).toPromise(); // => { message: 'The result is 5' }

Changelog

Please refer to CHANGELOG.md