@polymech/xblox

Block-based control flow for Polymech: if / else-if, for / while, switch / case / default, runScript, and break, with a nested JSON graph format, Zod validation, and a small Node CLI.

This package is a modern take on ideas from the legacy xblox AMD stack (ref-control-freak/ in this repo). It does not reimplement the full legacy Expression.js pipeline ([variables], {block} substitution, block-store UI); it focuses on execution and schema.

Install

From the monorepo, using npm in this package:

cd packages/xblox
npm install
npm run build

Package exports

Import	Use
`@polymech/xblox`	Types, enums, `ModelBase`, `RunScriptBlock`, engine entrypoints you re-export from app code. No `vm2`.
`@polymech/xblox/runtime`	`runScriptLegacyVm`, `evalExpression`, `runRunScriptBlock` — Node only, uses `vm2`. Do not import this path in browser bundles if you must avoid `vm2`.

CLI: `pm-xblox`

After npm run build, the pm-xblox binary runs validated graphs from disk.

npx pm-xblox run --source=./graph.json
npx pm-xblox run --source=./graph.json --output=./out.json
npx pm-xblox run --source=./graph.json --loglevel=info

Option	Default	Description
`--source`	(required)	Path to a blocks JSON file (`version: 1`).
`--output`	—	If set, writes `{ "result": … }` as JSON.
`--loglevel`	`info`	`debug` · `info` · `warn` · `error`

Blocks file format

Top-level shape (see src/schema/blocks-file.ts):

{
  "version": 1,
  "context": {},
  "root": { "kind": "…", … }
}

context — plain object merged into the execution this (expressions and scripts use this like the legacy apply(ctx, args) model).
root — a discriminated union on kind: if, runScript, for, while, switch, break, plus case / switchDefault inside switch.items.

Legacy note: older UIs often stored a flat array of blocks with id, parentId, declaredClass. This package currently executes the nested tree; you can add an adapter layer (flat → tree) for editors without changing the executor.

Expressions and scripts

Conditions and runScript.method bodies are evaluated via vm2 in @polymech/xblox/runtime, following the same new Function("{ … }").apply(ctx, args) idea as legacy Run Script blocks.
This is not a port of legacy Expression.js (no [var] substitution, {block} calls, or expression cache). For full parity with that layer, plan a separate module or bridge.

Security: vm2 is unmaintained; treat user scripts as trusted only in controlled environments, or replace the runtime with a stricter evaluator later.

Development

Script	Description
`npm run build`	`tsc` → `dist-in/`
`npm run dev`	`tsc --watch`
`npm run clean`	Remove `dist/` and `dist-in/`
`npm test`	Run Vitest once
`npm run test:watch`	Vitest watch mode
`npm run test:coverage`	Vitest with V8 coverage
`npm run test:ui`	Vitest browser UI
`npm run lint`	ESLint on `src/`
`npm run webpack`	After `build`, emits `dist/main_node.js` from `dist-in/main.js` (default package exports only; not `@polymech/xblox/runtime` / vm2).

Tests live under tests/; shared paths use tests/test-commons.ts. Fixtures are in tests/fixtures/.

Publishing to npm

package.json → files is an allowlist: only dist-in/, README.md, and LICENSE are packed. ref-control-freak/, tests/, src/, webpack/vitest configs, etc. are not published.
prepack runs npm run build, so dist-in/ exists when you npm publish or npm pack.
Dry-run the tarball: npm pack --dry-run (see “Files included” in the log) or npm pack and inspect the .tgz.
dist/ (webpack output) is intentionally not in files; consumers use dist-in/ from tsc.

License

MIT — see LICENSE.

4.0 KiB Raw Blame History