Registry / serialization / machine

machine

JSON →
library0.0.1jsnpmunverified

The `machine` package is a JavaScript runner for functions that adhere to the Node-Machine specification, an open standard for atomic, context-free subroutines. It allows developers to define functions (called 'machines') with explicit inputs and exits, enabling robust static analysis, automatic documentation generation, UI inference, and advanced toolchain integration. This package, currently at version 15.2.3, provides the core `Machine.build()` method to transform machine definitions into callable JavaScript functions. While it sees continuous development with incremental releases and pre-releases, direct usage is often unnecessary, as higher-level `node-machine` modules (like `machine-as-action` or `machine-as-script`) frequently abstract its functionality. Its key differentiator is enforcing a strict function signature and behavior via the machine spec, which promotes maintainability and composability.

serializationworkflow
npm install machine
github ↗package ↗
INSTALL
IMPORT
SIG · MACHINE
M
machine
serializationjavascriptv0.0.1
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Machine
✓ const Machine = require('machine');
✗ import Machine from 'machine';
The `machine` package primarily targets CommonJS environments. While ES module syntax might work in some transpiled setups, `require` is the idiomatic and officially supported import method for this package, especially given its legacy Node.js engine support.
Machine.build
✓ const callable = Machine.build({ /* machine definition */ });
✗ const callable = new Machine({ /* machine definition */ });
Machine.build() (or simply calling Machine() directly) is the factory function for creating callable machine instances, not a constructor. Avoid `new`.
callable().exec
✓ const result = await callable(argins).exec();
✗ const result = await callable(argins);
While `await callable(argins)` works for the 'success' exit due to `parley`'s integration, explicitly calling `.exec()` on the Deferred instance can clarify intent, especially when chaining with other Deferred methods like `.log()` or `.switch()` for multiple exits.

This quickstart demonstrates defining a simple 'machine' with inputs and exits, building it into a callable function, and executing it using async/await syntax to handle both success and error paths, showcasing input defaults and basic error handling.

const Machine = require('machine'); // Define a simple machine to greet a user const greetMachine = Machine({ identity: 'greet-user', friendlyName: 'Greet User', description: 'Greets a user by their provided name.', inputs: { name: { type: 'string', required: true, description: 'The name of the user to greet.' }, greeting: { type: 'string', defaultsTo: 'Hello', description: 'The greeting to use (e.g., "Hi", "Bonjour").' } }, exits: { success: { outputFriendlyName: 'Greeting message', outputDescription: 'The personalized greeting.', outputExample: 'Hello Alice!' }, error: { outputFriendlyName: 'Error', outputDescription: 'An unexpected error occurred.' } }, fn: function(inputs, exits) { try { const message = `${inputs.greeting} ${inputs.name}!`; return exits.success(message); } catch (err) { return exits.error(err); } } }); async function runGreeting() { try { const formalGreeting = await greetMachine({ name: 'Dr. Smith', greeting: 'Good day' }); console.log(formalGreeting); // Expected: Good day Dr. Smith! const casualGreeting = await greetMachine({ name: 'Alice' }); console.log(casualGreeting); // Expected: Hello Alice! // Example of calling with missing required input (will hit 'error' exit) await greetMachine({}); // This will throw an error if not caught via .catch() } catch (err) { console.error('Machine execution failed:', err.raw.errors[0].message); // Accessing the raw error in v13+ } } runGreeting();
Debug
Known issues
breakingThe schema for validation errors has changed significantly since v13.x.x. The Error instance passed through the `error` exit now provides a reference to the machine instance instead of just the machine ID, altering the structure of the validation error object.
fix
Update error handling logic for validation errors to inspect the new error object structure. Specifically, look for a `raw.errors` property containing detailed validation failures instead of relying on a top-level `machine ID`.
affects: >=13.0.0
breakingIn v12.3.0, the preferred property name for defining an exit's output schema changed from `example` to `outputExample`. While `example` is currently backwards compatible, `outputExample` takes precedence if both are defined.
fix
Migrate `example` properties within exit definitions to `outputExample` to ensure future compatibility and adherence to the updated specification. `outputExample` explicitly clarifies the property's purpose.
affects: >=12.3.0
gotchaThe `machine` package is a low-level runner for the machine specification. Most applications and users typically do not need to use this module directly. Higher-level toolchain modules like `machine-as-action` or `machine-as-script` often provide a more convenient and integrated development experience.
fix
Before integrating `machine` directly, evaluate if a higher-level `node-machine` toolchain module better suits your project's needs, as they often wrap and simplify `machine`'s core functionality.
affects: >=0.12.x
gotchaPrior to version 13.0.0-17, asynchronous usage of machines, particularly via the `.exec()` method, suffered from suboptimal performance. A significant performance enhancement was introduced in this version.
fix
Upgrade to `machine` v13.0.0-17 or a newer version to benefit from improved performance when executing asynchronous machines.
affects: <13.0.0-17
Errors
Common errors & fixes
TypeError: callable is not a function
Attempting to invoke the `Machine` object itself directly as a function, rather than the 'callable' function returned by `Machine.build()` or `Machine()`.
fix
Ensure you first build a machine definition into a callable function: `const callable = Machine({ /* definition */ });` then invoke `callable(inputs);`.
Error: E_VALIDATION: Bad argument: The provided value `undefined` is not a valid string.
A machine's `required` input was not provided or was provided with an invalid type, and the error handling is expecting the pre-v13 validation error format.
fix
For versions `>=13.0.0`, the validation error object structure has changed. Access validation details through `err.raw.errors` (e.g., `err.raw.errors[0].message`) instead of previous top-level properties.
Upgrade
Version history
0.0.1latest on npm
Audit
Dependencies
parleyrequiredUsed internally for creating Deferred instances, enabling async/await, .then(), .catch(), and .exec() patterns on callable machine results.
Agent activity
15 hits · last 30 days
node
12
OpenAI (training)
1
Resources
githubhttps://github.com/node-machine/machine ↗
packagehttps://www.npmjs.com/package/machine ↗