GET STARTED / QUICK START

Your first workflow.

From an input to a result, in two nodes. This example doubles a number and shows the three building blocks in action.

01 Install the package

terminalShell

1npm install @newvexa/workify

Use the scoped name @newvexa/workify. The unscoped npm package workify belongs to a different publisher and is not this library.

ESM imports are shown below. CommonJS applications can use:

app.cjsJavaScript

1const { Engine, Workflow, ifNode, switchNode } = require("@newvexa/workify");

02 Build a reusable graph

Save this as workflow.ts. Every node has a unique ID, a name, a type, and an asynchronous execute handler. The first node receives input.initial; the next reads its ordered incoming deliveries.

workflow.tsTypeScript

1import { Engine, Workflow } from "@newvexa/workify";
2
3export function createWorkflowEngine() {
4  const workflow = new Workflow({ id: "demo", name: "Double a number" });
5
6  workflow.addNode({
7    id: "start",
8    name: "Receive input",
9    type: "trigger",
10    async execute(input) {
11      return { outputs: { main: input.initial } };
12    },
13  });
14
15  workflow.addNode({
16    id: "double",
17    name: "Double the value",
18    type: "action",
19    async execute(input, context) {
20      context.signal.throwIfAborted();
21      const value = input.incoming[0]?.value;
22      if (typeof value !== "number") throw new Error("Expected a number");
23      return { outputs: { main: value * 2 } };
24    },
25  });
26
27  workflow.addLink({
28    id: "start-double",
29    name: "Input to calculation",
30    source: { nodeId: "start", port: "main" },
31    target: { nodeId: "double", port: "main" },
32  });
33
34  return new Engine(workflow, { concurrency: 4, historyLimit: 500 });
35}

A link explicitly connects the source’s main output port to the target’s main input port. The factory returns an engine without starting a run on import.

03 Run your workflow

run.tsTypeScript

1import { createWorkflowEngine } from "./workflow.js";
2
3const engine = createWorkflowEngine();
4const result = await engine.run(21);
5
6console.log(result.status);                       // "succeeded"
7console.log(result.results.double?.outputs.main); // 42

For a standalone ESM project, install TypeScript and add "type": "module" to the application’s package.json. Then compile and run:

terminalShell

1npx tsc workflow.ts run.ts --target ES2022 --module NodeNext --moduleResolution NodeNext --outDir build
2node build/run.js

Prefer a zero-build demo?

An installed Node.js project can run the included JavaScript example directly:

terminalShell

1node ./node_modules/@newvexa/workify/examples/run-quick-start.mjs
2# Expected output: succeeded, then 42

The factory and entry point are included example files, not main package exports.

Observe the execution

observe.tsTypeScript

1const stopState = engine.subscribe(() => {
2  console.log(engine.getSnapshot().status);
3});
4
5const stopEvents = engine.onEvent((event) => {
6  if (event.type === "node.changed") {
7    console.log(event.nodeId, event.state.status);
8  }
9});
10
11try {
12  await engine.run(21);
13  const previous = engine.getHistory().at(-2);
14  console.log(previous?.snapshot.status);
15} finally {
16  stopState();
17  stopEvents();
18}

Both subscription methods return a cleanup function. Snapshots contain status and error metadata; read business output from result.results, not from snapshots.

What comes next?

Create one engine per independent view or request. Construction captures and validates the graph; subsequent builder changes do not alter that engine. Handle invalid initial inputs and overlapping runs with try/catch, and inspect result.status for execution failures.

Core concepts Try the live graph

Documentation for @newvexa/workify 0.1.3Read the full source guide