Machine Spec ( X )

This is an example machine definition, a JavaScript file that should be included in your machinepack's machines/ folder.

module.exports = {
  friendlyName: 'Do something',
  description: 'Do something with the provided inputs that results in one of the exit scenarios.',
  extendedDescription: 'This optional extended description can be used to communicate caveats, technical notes, or any other sort of additional information which might be helpful for users of this machine.',
  moreInfoUrl: 'https://stripe.com/docs/api#list_cards',
  sideEffects: 'cacheable',
  sync: true,

  inputs: {
    brand: {
      friendlyName: 'Some input',
      description: 'The brand of gummy worms.',
      extendedDescription: 'The provided value will be matched against all known gummy worm brands.  The match is case-insensitive, and tolerant of typos within Levenstein edit distance <= 2 (if ambiguous, prefers whichever brand comes first alphabetically).',
      moreInfoUrl: 'http://gummy-worms.org/common-brands?countries=all',
      required: true,
      example: 'haribo',
      whereToGet: {
        url: 'http://gummy-worms.org/how-to-check-your-brand',
        description: 'Look at the giant branding on the front of the package.  Copy and paste with your brain.',
        extendedDescription: 'If you don\'t have a package of gummy worms handy, this probably isn\'t the machine for you.  Check out the `order()` machine in this pack.'
      }
    }
  },

  exits: {
    success: {
      outputFriendlyName: 'Protein (g)',
      outputDescription: 'The grams of gelatin-based protein in a 1kg serving.',
    },
    unrecognizedFlavors: {
      description: 'Could not recognize one or more of the provided `flavorStrings`.',
      extendedDescription: 'Some **markdown**.',
      moreInfoUrl: 'http://gummyworms.com/flavors',
    }
  },

  fn: function(inputs, exits) {
    // ...
    // your code here
    var result = 'foo';
    // ...
    // ...and when you're done:
    return exits.success(result);
  };
}

This is an interactive guide to the machine specification. You can mouseover any part of the spec for more info, or click for a linkable description.

identity

The unique name of your machine and should be down in lowercase. This property is required and your machine will not build without it.

friendlyName

A display name for the machine.

  • Sentence-case (like a normal sentence)
  • No ending punctuation.
  • Less than 50 characters

description

Clear, 1 sentence description in the imperative mood (e.g. "delete all..." not "deletes all..."). Should be less than 80 characters.

extendedDescription

Provides supplemental info on top of description. Full markdown syntax with complete sentences (including punctuation). Should be less than 2000 characters.

moreInfoUrl

This optional URL points to somewhere (other than http://node-machine.org) where additional information about the underlying functionality in this machine can be found.

Particularly helpful for machines that communicate with 3rd-party APIs like Twitter or Stripe. Be sure and use a fully qualified URL like http://foo.com/bar/baz.

sideEffects

Optional. Either omit, or set as 'cacheable' or 'idempotent'.

If set to 'cacheable', .cache() can be used with this machine. Should only be set to 'cacheable' if this machine has no "side effects". For instance, fetching a list of tweets which contain a particular hashtag is cacheable, whereas posting a tweet is not.

sync

Optional. Either omit, or set as true.

habitat

Optional. Either omit, or set as 'request' or 'sails'.

inputs

The specification for the input values that the machine fn expects.

input key

An input key is a camel-cased alphanumeric string that must start with a lower-cased letter. No special characters allowed INCLUDING underscores (_) or dollar signs ($).

Examples of input keys which are NOT OK:

  • 4myhOmies
  • _id
  • $
  • $contains

friendlyName

A display name for the input.

  • Sentence-case (like a normal sentence)
  • No ending punctuation.
  • Less than 50 characters

input extendedDescription

Provides supplemental info on top of the input's description. Full markdown syntax with complete sentences (including punctuation). Should be less than 2000 characters.

input example

Used to determine the expected data type of the input. All runtime values which are functions, undefined, null, regex will be ignored. For inputs that expect objects, `example` determines the minimum required schema. Required.

input description

A short description describing the input use.

input more info URL

This optional URL points to somewhere (other than http://node-machine.org) where additional information about this input can be found.

Particularly helpful for machines that communicate with 3rd-party APIs like Twitter or Stripe. Be sure and use a fully qualified URL like http://foo.com/bar/baz.

where to get

An optional documentation object that provides additional information about how to locate a suitable value for this input.

This is not a fit for every input, but it is particularly useful for authentication tokens, API keys, and the like.

where to get (url)

This optional URL should be provided if the value for this input must be found on a web page, e.g. authentication tokens, API keys, etc.

where to get (description)

Clear, 1 sentence description in the imperative mood (e.g. "Copy the...") which describes how to find the suitable value for this input.

Should be less than 80 characters.

This is not a fit for every input, but it is particularly useful for authentication tokens, API keys, and the like.

where to get (extended description)

Provides supplemental info beyond the instructions in whereToGet.description. You may use full markdown syntax with complete sentences (including punctuation).

Should be less than 2000 characters.

This is not a fit for every input, but it is particularly useful for authentication tokens, API keys, and the like.

input required

By default, every input is optional (required: false). If no runtime value is provided for an input, the machine fn will receive undefined (e.g. inputs.apiKey === undefined).

exits

The specification of all possible exit callbacks that this machine's fn implementation can trigger. Each exit represents a possible outcome from executing the machine.

exit key

The name of this exit; i.e. the key within the object passed to .exec() where you attach your callback function when using a machine. It is also the name of the property on the exits object that you use to trigger this exit when implementing a machine.

error exit

error is a special, required exit. It is always available, and will always return an Error instance.

When using a machine, be sure to always handle the error exit, just in case (much like you would always handle the err argument to a Node.js callback.)

While a machine may or may not explicitly call this exit in its implementation (i.e. fn), the error exit is called automatically in a few different scenarios:

  • When something unexpected happens: like if a machine throws an uncaught error, or has an invalid definition.
  • As a result of incomplete usage; e.g. providing an invalid value for an input or omitting a required input altogether
  • If the machine triggered an exit you weren't expecting (i.e. that you didn't set up a callback for.)

friendlyName

A display name for the exit.

  • Sentence-case (like a normal sentence)
  • No ending punctuation.
  • Less than 50 characters

input more info URL

This optional URL points to somewhere (other than http://node-machine.org) where additional information about this exit can be found.

Particularly helpful for machines that communicate with 3rd-party APIs like Twitter or Stripe. Be sure and use a fully qualified URL like http://foo.com/bar/baz.

outputExample

An example of the output, if relevant. Technically, this is an RTTC exemplar schema. Omit this property (as well as like, itemOf, and getExample) to indicate no output.

Keys in dictionary examples are all required; if a key doesn't exist in an output variable, node machine will coerce it to the falsey of the correct type.

exit description

A short description describing when the exit would be called.

extendedDescription

Provides supplemental info on top of the exit's description. Full markdown syntax with complete sentences (including punctuation). Should be less than 2000 characters.

outputFriendlyName

A display name for this exit's output.

  • Sentence-case (like a normal sentence)
  • No ending punctuation.
  • Less than 50 characters

like

The code name of an input to base this data type guarantee off of. The referenced input must exist. The effective data type guarantee will be exactly the same as the input's exemplar (example). That is, if the referenced input has example: [ { age: 49 } ], then the effective RTTC exemplar schema will be [ { age: 49 } ]. If runtime data is received for the referenced input, it will be exemplified (using rttc.coerceExemplar()) and used instead. (This is useful for building custom iterator machines, or machines that parse data with a dynamic schema.)

(ADVANCED, USE WITH CARE.)

itemOf

The code name of an input to base this data type guarantee off of. The referenced input must exist, and its example MUST be an array. The effective data type guarantee will be based off of the *pattern* of the input's exemplar (example). That is, if the referenced input has example: [ { name: 'foo' } ], then the effective RTTC exemplar schema for this exit will be {name: 'foo'}. If runtime data is received for the referenced input, it will be exemplified (using rttc.coerceExemplar()) and used instead. (This is useful for building custom iterator machines, or machines that parse data with a dynamic schema.)

(ADVANCED, USE WITH CARE.)

like

A function which receives runtime input values as its first argument and is expected to return an RTTC exemplar schema describing the data type under these particular conditions. May not return undefined or throw. Returning null to indicate that the exit is void (has no output) is experimental in the current version of the specification.

(VERY ADVANCED, USE WITH CARE!)

outputDescription

A short noun phrase describing the output from this exit.

exit variable name

The name of the variable to use in example code in the generated documentation. Must be a valid ECMAScript 5.1 variable name.

exit void

If void is set to true, example may be omitted. If provided, it will not be passed to the exit callback. (defaults to false)

fn

The JavaScript function which embodies the behavior of the machine. It will be run when this machine is executed. The inputs argument is an object of the runtime values that were passed in to the machine. The exits argument is a switchback (or object of functions) where each key corresponds to an exit callback.