Machine as Action Controller

Common errors

• Error: E_DOUBLE_WRAP: This action has already been wrapped!

  cause Attempting to wrap a machine with `asAction` more than once, or passing an already-wrapped action to `asAction`.
  fix Ensure `asAction` is called only once for each machine. Store the result of `asAction` and reuse it, rather than calling `asAction` multiple times with the same input.

• Error: E_INVALID_MACHINE: The provided machine definition is invalid.

  cause The object passed to `asAction` does not conform to the expected machine specification (missing `fn`, malformed `inputs`/`exits`, etc.).
  fix Verify that the machine definition object has a `fn` property, and correctly structured `inputs` and `exits` objects as per the machine spec.

• ReferenceError: require is not defined in ES module scope

  cause Attempting to use `require('machine-as-action')` in an ECMAScript module (ESM) environment without proper transpilation or dynamic import.
  fix If working in a pure ESM project, you might need to use dynamic `import('machine-as-action')` or configure your build system (e.g., Webpack, Rollup) to handle CommonJS modules within an ESM context. This package is primarily CJS.

• TypeError: Cannot read properties of undefined (reading 'fn')

  cause The object passed to `asAction` is `undefined` or `null`, or does not have the expected `fn` property, indicating an invalid or missing machine definition.
  fix Double-check that the variable holding your machine definition is correctly imported or defined and is a valid object containing a `fn` function.

Warnings

• breaking As of v6.1.3, undocumented and experimental tolerance of 'loose functions' (functions not conforming to the machine spec) as machine definitions is no longer supported.
  Fix: Ensure all machine definitions adhere strictly to the 'machine' specification, providing `inputs`, `exits`, and a `fn` property.
• breaking Version 7.0.11 introduced significant changes to custom response types and error handling, potentially altering the default behavior or configuration for `responseType`, `statusCode`, and `viewTemplatePath` in machine exits. Existing custom response logic might require adjustments.
  Fix: Review the documentation for `responseType`, `statusCode`, and `viewTemplatePath` options within machine exits. Test existing custom response handling thoroughly after upgrading.
• gotcha When generating stub data and not in production mode, `machine-as-action` automatically attaches an `X-Stub` header to responses. This behavior was introduced in v6.1.0.
  Fix: Be aware of the `X-Stub` header for debugging. In production (`process.env.NODE_ENV==='production'`), a warning will be logged instead. If you want to suppress this header even in development, you may need to intercept or modify responses.
• gotcha For non-success exits that do not explicitly configure a `responseType` (e.g., 'view', 'redirect'), `machine-as-action` defaults to using a 500 status code.
  Fix: Always explicitly define the `responseType` and `statusCode` for non-success exits to ensure predictable HTTP responses, especially for error conditions that should return specific status codes (e.g., 400 Bad Request, 404 Not Found).

Install

• npm install machine-as-action npm
• yarn add machine-as-action yarn
• pnpm add machine-as-action pnpm

Imports

• asAction
  wrong:

  import asAction from 'machine-as-action';

  correct:

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

  This package is primarily CommonJS. Direct ESM import might require bundler configuration or dynamic import.

Quickstart

This quickstart demonstrates how to wrap an inline machine with `asAction` and simulate its execution using mock `req` and `res` objects. It covers basic JSON responses and advanced view rendering, illustrating how machine outputs are mapped to HTTP responses.

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

// Simulate Express/Sails req/res objects for demonstration
const mockReq = (query = {}, body = {}) => ({ query, body });
const mockRes = () => {
  let _status = 200;
  let _data = null;
  let _view = null;
  let _redirect = null;

  return {
    status: function(code) { _status = code; return this; },
    json: function(data) { _data = data; console.log(`[Response JSON] Status: ${_status}, Data: ${JSON.stringify(_data)}`); },
    send: function(data) { _data = data; console.log(`[Response Send] Status: ${_status}, Data: ${data}`); },
    view: function(template, locals) { _view = { template, locals }; console.log(`[Response View] Status: ${_status}, Template: ${_view.template}, Locals: ${JSON.stringify(_view.locals)}`); },
    redirect: function(url) { _redirect = url; console.log(`[Response Redirect] Status: ${_status}, URL: ${_redirect}`); },
    serverError: function(err) { _status = 500; _data = { error: err.message }; console.error(`[Server Error] Status: ${_status}, Data: ${JSON.stringify(_data)}`); }
  };
};

// 1. Define an inline machine
const greetMachine = {
  inputs: {
    name: { type: 'string', required: true, example: 'World' }
  },
  exits: {
    success: { outputExample: 'Hello World!' },
    error: { outputExample: 'Could not greet.' }
  },
  fn: function(inputs, exits) {
    if (inputs.name) {
      return exits.success(`Hello, ${inputs.name}!`);
    }
    return exits.error(new Error('Name input is missing.'));
  }
};

// 2. Wrap the machine as an action
const greetAction = asAction(greetMachine);

// 3. Simulate an HTTP request for greetAction
console.log('--- Simulating a simple custom action ---');
greetAction(mockReq({ name: 'Registry User' }), mockRes());

// 4. Define an action with a custom responseType (e.g., 'view')
const showProfilePageAction = asAction({
  inputs: {
    userId: { type: 'string', required: true, example: 'user-123' }
  },
  exits: {
    success: {
      responseType: 'view',
      viewTemplatePath: 'profile/show',
      outputExample: { username: 'Alice', id: 'user-123' }
    }
  },
  fn: function(inputs, exits) {
    // In a real app, this would fetch user data from a database
    const userData = { username: `User ${inputs.userId}`, id: inputs.userId };
    return exits.success(userData);
  }
});

// 5. Simulate an HTTP request for the view action
console.log('\n--- Simulating an action rendering a view ---');
showProfilePageAction(mockReq({ userId: '456' }), mockRes());