@leumas/grids

The 3D programming grid/graph runtime. A grid is a set of layers of cells; a cell is an action (code, endpoint, conditional, variable) — reusable across the whole system. Cells reference each other by $Layer.Cell; the engine resolves those refs, memoizes results, detects cycles, and recommends the next cell to run.

Absorbs (DRY-consolidated from): Servers/z.Programming3 (v4, four core cell types). Ported the core runtime only — dropped the bundled express server, pino logging, Postgres/pglite/File stores, node-cron trigger engine, media/plugin-upload/plugin-generator/adapter-scan machinery, and the bundled React frontend.

Usage (in leumas-api)

import { createGridsRouter, createCollectionStore } from '@leumas/grids';
import { requirePassNode } from '@leumas/auth';

// Persist grids in the dynamic `grids` collection over leumas.db (same connector everything uses).
const store = createCollectionStore(connector.get(), 'grids');
app.use('/api/grids', createGridsRouter({ store, gate: requirePassNode() })); // gate = price/meter

With no store, an in-memory store is used (dev / tests).

API (mounted at /api/grids)

• GET / · POST / · GET /:id · PUT /:id · DELETE /:id — grid CRUD
• GET /cell-types — the built-in cell catalogue (a cell = an action)
• POST /:id/execute { entryCell:"Layer.Ref" } — run a cell (+ its deps), returns value,

results, debug, and suggestions (what to run next)

• POST /:id/execute-many { executeCells?, executeLayers? } — run many
• POST /:id/suggest { executed? } — recommend next cells from an executed set

Grid shape

{
  "id": "demo",
  "name": "Demo",
  "layers": [
    { "name": "default", "cells": {
      "A2": { "type": "variable", "specialConfig": { "value": 5 } },
      "A3": { "type": "variable", "specialConfig": { "value": 10 } },
      "A1": { "type": "code", "code": "$default.A2 + $default.A3" }
    } },
    { "name": "Layer 2", "cells": {
      "B1": { "type": "code", "code": "$default.A1 * 2" }
    } }
  ]
}

Core cell types

• code — custom JavaScript (runs in a node:vm sandbox — no process/require reach), $ref-aware
• endpoint — HTTP request builder (baseUrl/url/method/headers/query/body), all fields $ref-aware
• conditional — evaluate a JS boolean and pick trueResult / falseResult
• variable — a static value (numeric-looking strings coerce losslessly to numbers)

Extend at the call site: createGridsRouter({ adapters: { ...coreCellAdapters, myType } }), where an adapter is { meta, run(cell, ctx) } and ctx provides replaceRefsInText, executeCell, layerName, fullCellId, debug.