Native Nodes

Native nodes are Octonode's built-in palette — an n8n-style library of pre-written nodes covering math, logic, flow control, data transforms, text/string manipulation, date & time, and free-form code.

Unlike marketplace plugins (which are installed as self-contained folders), native nodes are materialized directly into your project: running octonode add math.add writes a real, fully-editable TypeScript source file into nodes/ and registers a deterministic CommonJS runtime artifact in .octonode. You edit nodes/add_1.ts; Octonode rebuilds and executes nodes/add_1.cjs, so source and runtime remain distinct in either module mode.

Adding a native node

Native nodes and plugins are different: built-ins live in packages/native/src/catalog/; installable plugins follow plugins.md. To register a new built-in:

1. Add one NativeNodeSpec to the matching catalog file. Declare its palette metadata, input/output JSON Schemas, and a TypeScript template using tsNodeFile from catalog/scaffold.ts.
2. For a new category file, import its exported spec array into catalog/index.ts and spread it into CATALOG. Existing category files are already registered there.
3. Use params only for values baked into generated source. A parameterized node is described after generation; a static node uses its catalog signature directly.
4. Add one runnable test covering materialization and the node's non-trivial behavior. If the node changes Studio rendering, add/update the component story and visual baseline.
5. Add the node to the catalog table below, then run yarn gen, yarn build, and the targeted test (plus the Storybook visual gate for Studio changes).

Generated node source must keep stdout reserved for the IPC envelope; log only to stderr.

Octonode integrations (3 nodes)

These native nodes use the active Octonode API, so the same node works with the local filesystem store and hosted Cloudflare workspace records. Set OCTONODE_API_URL when the API is not at http://127.0.0.1:8787/api.

The Catalog

Math (31 nodes)

The 13 binary operators take two operands a and b via incoming edges and emit one result. The generated code inlines the operator symbol — no function call, no indirection.

The 10 function nodes are unary (input a) or binary (a, b) and emit one numeric result:

The 8 advanced nodes work over a list (values) or take params:

Logic (6 nodes)

Boolean combinators and null/empty checks.

Generated TypeScript excerpt for math.add:

// nodes/add_1.ts (compiled to nodes/add_1.cjs)
const { defineNode, start } = require("@octonode/sdk");
const node = defineNode({
  id: "add-1",
  inputs:  { type: "object", properties: { a: { type: "number" }, b: { type: "number" } } },
  outputs: { type: "object", properties: { result: { type: "number" } } },
  async run({ inputs }) {
    const { a, b } = inputs;
    return { result: a + b };   // the + symbol, not a function call
  },
});
start(node);

Flow (11 nodes)

Console (1 node)

Data (24 nodes)

Text (13 nodes)

String manipulation nodes — most take text and emit result.

Date & Time (5 nodes)

Timestamps are epoch milliseconds — pure integer arithmetic with zero dependencies. parse follows an explicit UTC contract: an ISO 8601 string with no timezone offset is interpreted as UTC.

Code (2 nodes)

The body receives inputs and must return an outputs object:

octonode add code.custom --params '{"body":"return { doubled: inputs.n * 2 };"}'

For the full TypeScript Handbook/JavaScript runtime matrix and JSON boundary, see TypeScript and JavaScript coverage.

CLI

# Add a node with defaults
octonode add math.add

# Specify language and workflow
octonode add flow.if --lang typescript --workflow main

# Pass params (e.g. switch cases, or a code body)
octonode add flow.switch --params '{"cases":["high","med","low"]}'
octonode add code.custom --params '{"body":"return { out: inputs.value * 2 };"}'

# List the full catalog
octonode add --list

Instance IDs are auto-incremented: the first math.add becomes add-1, the second add-2, and so on. Collision detection is safe across concurrent adds.

defaults.language

Set a project-wide default language so --lang can be omitted:

# .octonode.yaml
defaults:
  language: typescript

API Endpoints

Branching Semantics

An edge from: { node, output: K } fires only when the node's outputs contain key K. A non-root node whose incoming edges all resolved inactive is skipped with reason no-active-branch; the skip propagates, but a fan-in node with at least one active incoming edge still runs.

This means flow.if (which emits either { true: ... } or { false: ... }) automatically prunes the untaken branch without any special-casing in the scheduler. The taken branch runs; the other is skipped with reason: "no-active-branch". Branch-skips do not count as failures and do not affect the run's status.

Studio

In edit mode the left palette shows all catalog entries grouped by category (Math / Flow / Data / Code). Drag a node onto the canvas or click Add to materialize it into the project and place it visually.

Existing workflows appear under Workflows as nodes in the node picker. Selecting one materializes flow.workflow-ref with its id, and the canvas renders a distinct workflow-call card so nested orchestration remains visible without opening generated code.

Math nodes display their operator symbol (e.g. +, ÷) as the node glyph on the canvas.

The live code panel opens when a native node is selected. It:

• Shows the generated source file in a read-only-by-default editor.
• Watches for external changes via the SSE /source/watch endpoint and refreshes automatically.
• Displays a conflict banner when a write is rejected due to a concurrent edit (stale baseMtime).