Run a machine by sending an HTTP or WebSocket request to your Sails.js app. ("actions2")
Latest commit 86de0e6 Aug 24, 2018
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
lib Implement PassThrough stream to insulate output Aug 24, 2018
test Update expected output in test. Oct 25, 2017
.editorconfig update boilerplate Jul 13, 2017
.eslintrc update boilerplate Jul 13, 2017
.gitignore Remove package-lock Oct 9, 2017
.jshintrc update boilerplate Jul 13, 2017
.npmignore update boilerplate Jul 13, 2017
.travis.yml update boilerplate Jul 13, 2017
README.md Update README.md Jan 3, 2017
appveyor.yml Add Node 8 May 31, 2017
package.json 10.3.0-0 Aug 24, 2018

README.md

machine-as-action

Build a modified version of a machine that proxies its inputs from request parameters, and proxies its exits through the response.

$ npm install machine-as-action --save

Usage

var asAction = require('machine-as-action');
var OpenWeather = require('machinepack-openweather');

// WeatherController.js
module.exports = {

  traditionalReqRes: function (req, res) { /* ... */ },

  getLatest: asAction(OpenWeather.getCurrentConditions),

  doSomethingCustom: asAction({
    exits: {
      success: {
        outputExample: 'Some dynamic message like this.'
      }
    },
    fn: function (inputs, exits) {
      return exits.success('Hello world!');
    }
  }),

  // etc...

}

Now you can run your machine using a HTTP or Socket.io request:

// For example, using jQuery and an out-of-the-box Sails.js route/blueprint configuration:
$.get('/weather/getLatest', {
  city: 'San Francisco'
}, function (weatherData){
  console.log(weatherData);
});

Note that the machine definition you provide here doesn't have to come from an already-published machinepack-- it can be required locally from your project, or declared inline.

Customizing the response

So sending down data is great, but sometimes you need to render view templates, redirect to dynamic URLs, use a special status code, stream down a file, etc. No problem. You can customize the response from each exit using a number of additional, machine-as-action specific options.

var asAction = require('machine-as-action');

// WeatherController.js
module.exports = {

  showHomepage: asAction({
    

    exits: {

      success:{
        responseType: 'view',
        viewTemplatePath: 'homepage'
        // The view will be provided with a "local" called `stuff`,
      }

    },


    fn: function(inputs,exits){
      return exits.success({ stuff: 'things' });
    }
    

  })
};

For each of your exits, you can optionally specify a responseType, status, and/or view.

responseType is one of the following:

  • "" (the standard response: Determine an appropriate response based on context: this might send plain text, download a file, transmit data as JSON, or send no response body at all.)
  • "view" (render and respond with a view; exit output will be provided as view locals)
  • "redirect" (redirect to the URL returned as the exit output)

statusCode is the status code to respond with. (This works just like status codes in Sails/Node).

viewTemplatePath is the relative path (from the views/ directory) of the view to render. It is only relevant if responseType is set to "view". (This works just like views in Sails/Express).

If any of the above are not set explicitly, they will fall back to reasonable defaults (based on available information).

For example, if a non-success exit is set up to serve a view, then it will use the 200 response code. But if a non-success exit has no explicit response type configured (meaning it will respond with plain text, JSON-encoded data, or with no data and just a status code), then machine-as-action will default to using the 500 status code. Similarly, in the same same scenario, but with responseType: 'redirect', the status code will default to 302. The success exit always has a default status code of 200, unless it is also responseType: 'redirect' (in which case it defaults to 302.)

File uploads

You can use the special files option to map a file parameter containing an incoming Skipper upstream to a machine input:

var asAction = require('machine-as-action');

// WeatherController.js
module.exports = {


  uploadPhoto: asAction({
    

    files: ['photo']
    

    inputs: {

      photo: {
        example: '===',
        required: true
      }

    },


    fn: function (inputs, exits){
      inputs.photo.upload(function (err, uploadedFiles){
        if (err) return exits.error(err);
        exits.success();
      });
    }


  })


};

Available Options

Aside from the normal properties that go into a Node Machine definition, the following additional options are supported:

Option Type Description
files ((array?)) An array of input code names identifying inputs which expect to receive file uploads instead of text parameters. These file inputs must have example: '===', but they needn't necessarily be required.
urlWildcardSuffix ((string?)) If this action is handling a route with a wildcard suffix (e.g. /foo/bar/*), then specify this option as the code name of the machine input which should receive the string at runtime (i.e. the actual value of the "*" in the request URL).
disableDevelopmentHeaders ((boolean?)) If set, then do not automatically set headers w/ exit info during development.
disableXExitHeader ((boolean?)) If set, then do not automatically send the X-Exit response header for any exit, regardless of whether this is a prod or dev environment.
simulateLatency ((number?)) If set, then simulate a latency of the specified number of milliseconds (e.g. 500)
logDebugOutputFn ((function?)) An optional override function to call when any output other than undefined is received from a void exit (i.e. an exit w/ no outputExample). By default, machine-as-action uses sails.log.warn() if available, or console.warn() otherwise.
NOTE

Extended example

This is a more detailed example, based on the simple intro example at the top of this README.

var asAction = require('machine-as-action');
var OpenWeather = require('machinepack-openweather');

// WeatherController.js
module.exports = {

  traditionalReqRes: function (req, res) { /* ... */ },

  getLatest: asAction(OpenWeather.getCurrentConditions),

  doSomethingCustom: asAction({
    description: 'Send a plaintext response.',
    exits: {
      success: {
        outputExample: 'Some dynamic message like this.'
      }
    },
    fn: function (inputs, exits) {
      return exits.success('Hello world!');
    }
  }),

  getForecastData: asAction({
    description: 'Fetch data for the forecast with the specified id.',
    inputs: {
      id: { required: true, example: 325 }
    },
    exits: {
      success: {
        outputExample: {
          weatherPerson: 'Joaquin',
          days: [
            { tempCelsius: 21, windSpeedMph: 392 }
          ]
        }
      },
      notFound: {
        description: 'Could not find forecast with that id.',
        statusCode: 404
      }
    },
    fn: function (inputs, exits) {
      Forecast.find({ id: inputs.id }).exec(function (err, forecastRecord) {
        if (err) { return exits.error(err); }
        if (!forecastRecord) { return exits.notFound(); }
        return exits.success(forecastRecord);
      });
    }
  }),

  show7DayForecast: asAction({
    description: 'Show the current 7 day forecast page.',
    exits: {
      success: {
        responseType: 'view',
        viewTemplatePath: 'pages/weather/7-day-forecast'
      }
    },
    fn: function (inputs, exits) {
      return exits.success('http://sailsjs.org');
    }
  }),

  redirectToExternalForecastMaybe: asAction({
    description: 'Redirect the requesting user agent to http://weather.com, or to http://omfgdogs.com.',
    exits: {
      success: { responseType: 'redirect' }
    },
    fn: function (inputs, exits) {
      if (Math.random() > 0.5) {
        return exits.success('http://weather.com');
      }
      else {
        return exits.success('http://omfgdogs.com');
      }
    }
  })

};

Bugs   NPM version

To report a bug, click here.

Contributing   Build Status

Please observe the guidelines and conventions laid out in the Sails project contribution guide when opening issues or submitting pull requests.

NPM

License

MIT © 2015-2016 Mike McNeil

Incorporated as a core part of the Sails framework in 2016.

The Sails framework is free and open-source under the MIT License.