@revisium/schema-toolkit

Framework-agnostic TypeScript types, system schemas, runtime stores, and utilities for working with JSON Schema in Revisium projects.

Installation

npm install @revisium/schema-toolkit

Quick Start

Schema helpers

import { obj, str, num, bool, arr } from '@revisium/schema-toolkit';

const schema = obj({
  name: str(),
  age: num(),
  active: bool(),
  tags: arr(str()),
});

RowModel

import { obj, str, num, createRowModel } from '@revisium/schema-toolkit';

const schema = obj({ name: str(), price: num() });

const row = createRowModel({
  rowId: 'row-1',
  schema,
  data: { name: 'Widget', price: 9.99 },
});

row.getValue('name');           // string (typed!)
row.setValue('price', 19.99);   // OK
row.setValue('price', 'wrong'); // TS Error!
row.getPlainValue();            // { name: string, price: number }
row.patches;                    // JSON Patch operations
row.root;                       // typed root node (InferNode<S>)
row.reset({ name: 'New', price: 0 }); // reset to new data, commit
row.reset();                    // reset to schema defaults

Array Search

Arrays expose find and findIndex for searching elements by node properties:

import { obj, str, arr, createRowModel } from '@revisium/schema-toolkit';

const schema = obj({
  sorts: arr(obj({ field: str(), direction: str() })),
});

const row = createRowModel({
  rowId: 'row-1',
  schema,
  data: { sorts: [
    { field: 'name', direction: 'asc' },
    { field: 'age', direction: 'desc' },
  ]},
});

const sortsNode = row.get('sorts');
// find returns the typed node
const ageSort = sortsNode.find(
  (node) => node.child('field').getPlainValue() === 'age',
);
// findIndex returns the index
const idx = sortsNode.findIndex(
  (node) => node.child('field').getPlainValue() === 'age',
); // 1

TableModel

import { obj, str, num, bool, createTableModel } from '@revisium/schema-toolkit';

const schema = obj({ title: str(), price: num(), inStock: bool() });

const table = createTableModel({
  tableId: 'products',
  schema,
  rows: [
    { rowId: 'p1', data: { title: 'Laptop', price: 999, inStock: true } },
  ],
});

const row = table.getRow('p1');
row?.getValue('title');         // string (typed!)
row?.getPlainValue();           // { title: string, price: number, inStock: boolean }

const newRow = table.addRow('p2', { title: 'Mouse', price: 29, inStock: true });
newRow.setValue('price', 39);   // OK
newRow.setValue('price', 'x');  // TS Error!

Typed API without helpers

When the schema is typed (via helpers or as const), createRowModel / createTableModel return typed models automatically. With plain JsonSchema they return the untyped API as before:

import { createRowModel } from '@revisium/schema-toolkit';
import type { JsonObjectSchema } from '@revisium/schema-toolkit';

// Untyped — returns plain RowModel with unknown types
const schema: JsonObjectSchema = getSchemaFromApi();
const row = createRowModel({ rowId: 'row-1', schema, data });
row.getValue('name'); // unknown

See Typed API documentation for all approaches: as const, explicit type declarations, SchemaFromValue<T>, and more.

Reactivity (MobX)

By default all models use a noop reactivity provider, which works for backend and plain scripts. To enable MobX reactivity (e.g. in a React app), configure the provider once at startup:

import * as mobx from 'mobx';
import { setReactivityProvider, createMobxProvider } from '@revisium/schema-toolkit/core';

setReactivityProvider(createMobxProvider(mobx));

After this call every model created via createRowModel, createTableModel, or createDataModel becomes fully observable.

See Reactivity Module docs for the full API, noop behaviour table, and test-setup examples.

Formulas (Computed Fields)

Fields with x-formula are automatically computed from other fields. Use readOnly: true and the formula option in helpers:

import { obj, num, numFormula, createRowModel } from '@revisium/schema-toolkit';

const schema = obj({
  price: num(),
  quantity: num(),
  subtotal: numFormula('price * quantity'),
  tax: numFormula('subtotal * 0.1'),
  total: numFormula('subtotal + tax'),
});

const row = createRowModel({
  rowId: 'order-1',
  schema,
  data: { price: 100, quantity: 5, subtotal: 0, tax: 0, total: 0 },
});

row.getPlainValue();
// { price: 100, quantity: 5, subtotal: 500, tax: 50, total: 550 }

Formulas are evaluated in dependency order. With the MobX reactivity provider configured, changing a dependency triggers automatic re-evaluation of all affected formulas.

Expression Syntax

| Syntax | Example | |--------|---------| | Field reference | price, item.quantity | | Arithmetic | price * quantity, a + b - c | | Comparison & logic | a > b && c < d, x ? y : z | | Absolute path | /rootField | | Relative path | ../siblingField | | Array access | items[0].price, items[*].price | | Array context | #index, #length, @prev, @next | | Functions | sum(items[*].price), avg(values), count(array) |

Schema-Level Integration

When fields are renamed or moved, formula expressions are automatically updated in the generated patches:

// rename price → cost
// formula 'price * quantity' → 'cost * quantity' (auto-updated)

Warnings

The evaluator tracks problematic results (nan, infinity, runtime-error) on the node's formulaWarning property.

See value-formula docs for the runtime engine API and schema-formula docs for parsing, dependency tracking, and serialization.

Foreign Key Resolution

Schemas with foreignKey fields (string fields referencing another table) can be resolved automatically via ForeignKeyResolver:

import { createForeignKeyResolver, createTableModel, obj, str } from '@revisium/schema-toolkit';

const resolver = createForeignKeyResolver({
  loader: {
    loadSchema: async (tableId) => api.getTableSchema(tableId),
    loadRow: async (tableId, rowId) => api.getRow(tableId, rowId),
  },
  prefetch: true,
});

const table = createTableModel({
  tableId: 'products',
  schema: obj({ name: str(), categoryId: str({ foreignKey: 'categories' }) }),
  rows: [{ rowId: 'p1', data: { name: 'Laptop', categoryId: 'cat-1' } }],
  fkResolver: resolver,
});

// Referenced data is prefetched in the background and available from cache
const category = await resolver.getRowData('categories', 'cat-1');

The same fkResolver option is accepted by createRowModel. When using createDataModel, pass the resolver once and all tables will share it.

See ForeignKeyResolver docs for cache-only mode, prefetch control, loading state, and error handling.

API

Schema Helpers

| Function | Description | |----------|-------------| | str() | Create string schema | | num() | Create number schema | | bool() | Create boolean schema | | strFormula(expr) | Create computed string field (readOnly: true + x-formula) | | numFormula(expr) | Create computed number field (readOnly: true + x-formula) | | boolFormula(expr) | Create computed boolean field (readOnly: true + x-formula) | | obj(properties) | Create object schema (generic — preserves property types) | | arr(items) | Create array schema (generic — preserves items type) | | ref(tableName) | Create $ref schema |

Table & Row

| Function | Description | |----------|-------------| | createRowModel(options) | Create a row model (typed overload when schema is typed) | | createTableModel(options) | Create a table model (typed overload when schema is typed) |

RowModel

| Property / Method | Description | |-------------------|-------------| | root | Typed root node (InferNode<S> for typed, ValueNode for untyped) | | get(path) | Get node at path | | getValue(path) | Get plain value at path | | setValue(path, value) | Set value at path | | getPlainValue() | Get full plain value | | patches | JSON Patch operations (JsonValuePatch[]) for current changes | | reset(data?) | Reset to given data (or schema defaults) and commit | | commit() | Commit current state as base | | revert() | Revert to last committed state |

ArrayValueNode

| Method | Description | |--------|-------------| | at(index) | Get element at index (supports negative) | | find(predicate) | Find first element matching predicate, or undefined | | findIndex(predicate) | Find index of first matching element, or -1 | | push(node) | Append element | | pushValue(value?) | Create and append element from value | | removeAt(index) | Remove element at index | | move(from, to) | Move element between positions | | clear() | Remove all elements |

Value Tree

| Function | Description | |----------|-------------| | createTypedTree(schema, data) | Create a typed value tree with path-based access | | typedNode(node) | Cast an untyped ValueNode to a typed node |

Schema

| Function | Description | |----------|-------------| | createJsonSchemaStore | Create runtime schema store | | getJsonSchemaStoreByPath | Navigate schema by path | | applyPatches | Apply JSON Patch operations to schema | | resolveRefs | Resolve $ref to inline schemas | | validateJsonFieldName | Validate field name format | | getInvalidFieldNamesInSchema | Find invalid field names in schema |

Value

| Function | Description | |----------|-------------| | createJsonValueStore | Create runtime value store | | getJsonValueByPath | Navigate value by path | | computeValueDiff | Compute field-level diff between two values | | traverseValue | Traverse value tree |

Foreign Keys

| Function | Description | |----------|-------------| | getForeignKeysFromSchema | Extract foreign keys from schema | | getForeignKeysFromValue | Extract foreign key values from data | | getForeignKeyPatchesFromSchema | Get patches for foreign key changes | | replaceForeignKeyValue | Replace foreign key references |

Path Utils

| Function | Description | |----------|-------------| | parsePath | Parse dot-notation path to segments | | getParentForPath | Get parent path | | getPathByStore | Get path from store | | deepEqual | Deep equality comparison |

Type Utilities

| Type | Description | |------|-------------| | InferValue<S> | Schema → plain TypeScript value type | | InferNode<S> | Schema → typed ValueNode interface | | SchemaFromValue<T> | Plain TS type → virtual schema shape | | SchemaPaths<S> | Union of all valid dot-separated paths | | TypedRowModel<S> | RowModel with typed root, getValue, setValue, getPlainValue, reset | | TypedTableModel<S> | TableModel with typed rows, addRow, getRow |

See Typed API documentation for the full reference.

License

MIT