@revisium/schema-toolkit 0.20.2 → 0.21.1

package/README.md

@@ -17,8 +17,211 @@ Framework-agnostic TypeScript types, system schemas, runtime stores, and utiliti
 npm install @revisium/schema-toolkit
 ```
 
+## Quick Start
+
+### Schema helpers
+
+```typescript
+import { obj, str, num, bool, arr } from '@revisium/schema-toolkit';
+
+const schema = obj({
+  name: str(),
+  age: num(),
+  active: bool(),
+  tags: arr(str()),
+});
+```
+
+### RowModel
+
+```typescript
+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.getPatches();               // JSON Patch operations
+```
+
+### TableModel
+
+```typescript
+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:
+
+```typescript
+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](src/types/TYPED-API.md) 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:
+
+```typescript
+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](src/core/reactivity/README.md) 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:
+
+```typescript
+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:
+
+```typescript
+// 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](src/model/value-formula/README.md) for the runtime engine API and [schema-formula docs](src/model/schema-formula/README.md) for parsing, dependency tracking, and serialization.
+
+## Foreign Key Resolution
+
+Schemas with `foreignKey` fields (string fields referencing another table) can be resolved automatically via `ForeignKeyResolver`:
+
+```typescript
+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](src/model/foreign-key-resolver/README.md) 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) |
+
+### 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 |
@@ -57,6 +260,19 @@ npm install @revisium/schema-toolkit
 | `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 `getValue`, `setValue`, `getPlainValue` |
+| `TypedTableModel<S>` | TableModel with typed rows, `addRow`, `getRow` |
+
+See [Typed API documentation](src/types/TYPED-API.md) for the full reference.
+
 ## License
 
 MIT

package/dist/FormulaPathBuilder-BUJRR0Am.d.cts

@@ -0,0 +1,48 @@
+import { j as SchemaNode, P as Path, o as Formula } from './types-BIvIURgy.cjs';
+import { X as XFormula } from './schema.types-On_VGw2m.cjs';
+
+interface SchemaTree {
+    root(): SchemaNode;
+    nodeById(id: string): SchemaNode;
+    nodeAt(path: Path): SchemaNode;
+    pathOf(id: string): Path;
+    nodeIds(): IterableIterator<string>;
+    countNodes(): number;
+    clone(): SchemaTree;
+    trackReplacement(oldNodeId: string, newNodeId: string): void;
+    replacements(): IterableIterator<[string, string]>;
+    clearReplacements(): void;
+    addChildTo(parentId: string, node: SchemaNode): void;
+    insertChildAt(parentId: string, index: number, node: SchemaNode): void;
+    removeNodeAt(path: Path): boolean;
+    renameNode(nodeId: string, newName: string): void;
+    moveNode(nodeId: string, newParentId: string): void;
+    setNodeAt(path: Path, node: SchemaNode): void;
+    replaceRoot(newRoot: SchemaNode): void;
+}
+
+interface SerializeOptions {
+    readonly strict?: boolean;
+}
+declare class FormulaSerializer {
+    private readonly tree;
+    private readonly formulaNodeId;
+    private readonly formula;
+    private readonly pathBuilder;
+    constructor(tree: SchemaTree, formulaNodeId: string, formula: Formula);
+    static toXFormula(tree: SchemaTree, formulaNodeId: string, formula: Formula): XFormula;
+    static serializeExpression(tree: SchemaTree, formulaNodeId: string, formula: Formula, options?: SerializeOptions): string;
+    serialize(options?: SerializeOptions): string;
+    private buildPathReplacements;
+    private needsReplacement;
+    private normalizeArrayNotation;
+}
+
+declare class FormulaPathBuilder {
+    buildWithArrayNotation(fromPath: Path, toPath: Path): string;
+    private findCommonPrefixLength;
+    private buildPartsWithArrayNotation;
+    private formatPartsWithArrayNotation;
+}
+
+export { FormulaSerializer as F, type SchemaTree as S, FormulaPathBuilder as a };

package/dist/FormulaPathBuilder-QR0htn-e.d.ts

@@ -0,0 +1,48 @@
+import { j as SchemaNode, P as Path, o as Formula } from './types-C_pTFtSY.js';
+import { X as XFormula } from './schema.types-On_VGw2m.js';
+
+interface SchemaTree {
+    root(): SchemaNode;
+    nodeById(id: string): SchemaNode;
+    nodeAt(path: Path): SchemaNode;
+    pathOf(id: string): Path;
+    nodeIds(): IterableIterator<string>;
+    countNodes(): number;
+    clone(): SchemaTree;
+    trackReplacement(oldNodeId: string, newNodeId: string): void;
+    replacements(): IterableIterator<[string, string]>;
+    clearReplacements(): void;
+    addChildTo(parentId: string, node: SchemaNode): void;
+    insertChildAt(parentId: string, index: number, node: SchemaNode): void;
+    removeNodeAt(path: Path): boolean;
+    renameNode(nodeId: string, newName: string): void;
+    moveNode(nodeId: string, newParentId: string): void;
+    setNodeAt(path: Path, node: SchemaNode): void;
+    replaceRoot(newRoot: SchemaNode): void;
+}
+
+interface SerializeOptions {
+    readonly strict?: boolean;
+}
+declare class FormulaSerializer {
+    private readonly tree;
+    private readonly formulaNodeId;
+    private readonly formula;
+    private readonly pathBuilder;
+    constructor(tree: SchemaTree, formulaNodeId: string, formula: Formula);
+    static toXFormula(tree: SchemaTree, formulaNodeId: string, formula: Formula): XFormula;
+    static serializeExpression(tree: SchemaTree, formulaNodeId: string, formula: Formula, options?: SerializeOptions): string;
+    serialize(options?: SerializeOptions): string;
+    private buildPathReplacements;
+    private needsReplacement;
+    private normalizeArrayNotation;
+}
+
+declare class FormulaPathBuilder {
+    buildWithArrayNotation(fromPath: Path, toPath: Path): string;
+    private findCommonPrefixLength;
+    private buildPartsWithArrayNotation;
+    private formatPartsWithArrayNotation;
+}
+
+export { FormulaSerializer as F, type SchemaTree as S, FormulaPathBuilder as a };

package/dist/{chunk-VGADCIBG.cjs → chunk-2PIMJSWJ.cjs}

@@ -1,6 +1,6 @@
 'use strict';
 
-// src/mocks/schema.mocks.ts
+// src/lib/schema-helpers.ts
 var getReplacePatch = ({
   path,
   value
@@ -38,7 +38,7 @@ var buildFormula = (expression) => ({
 var getStringSchema = (params = {}) => {
   const { formula, ...rest } = params;
   return {
-    type: "string" /* String */,
+    type: "string",
     ...rest,
     default: rest.default ?? "",
     ...formula && { "x-formula": buildFormula(formula) }
@@ -47,7 +47,7 @@ var getStringSchema = (params = {}) => {
 var getNumberSchema = (params = {}) => {
   const { formula, ...rest } = params;
   return {
-    type: "number" /* Number */,
+    type: "number",
     ...rest,
     default: rest.default ?? 0,
     ...formula && { "x-formula": buildFormula(formula) }
@@ -56,21 +56,21 @@ var getNumberSchema = (params = {}) => {
 var getBooleanSchema = (params = {}) => {
   const { formula, ...rest } = params;
   return {
-    type: "boolean" /* Boolean */,
+    type: "boolean",
     ...rest,
     default: rest.default ?? false,
     ...formula && { "x-formula": buildFormula(formula) }
   };
 };
 var getObjectSchema = (properties, options = {}) => ({
-  type: "object" /* Object */,
+  type: "object",
   additionalProperties: false,
   required: Object.keys(properties).sort((a, b) => a.localeCompare(b)),
   properties,
   ...options
 });
 var getArraySchema = (items, options = {}) => ({
-  type: "array" /* Array */,
+  type: "array",
   items,
   ...options
 });
@@ -81,12 +81,16 @@ var getRefSchema = ($ref, options = {}) => ({
 var str = (params = {}) => getStringSchema(params);
 var num = (params = {}) => getNumberSchema(params);
 var bool = (params = {}) => getBooleanSchema(params);
+var strFormula = (formula, params = {}) => getStringSchema({ ...params, formula, readOnly: true });
+var numFormula = (formula, params = {}) => getNumberSchema({ ...params, formula, readOnly: true });
+var boolFormula = (formula, params = {}) => getBooleanSchema({ ...params, formula, readOnly: true });
 var obj = (properties, options) => getObjectSchema(properties, options);
 var arr = (items, options) => getArraySchema(items, options);
 var ref = ($ref, options) => getRefSchema($ref, options);
 
 exports.arr = arr;
 exports.bool = bool;
+exports.boolFormula = boolFormula;
 exports.getAddPatch = getAddPatch;
 exports.getArraySchema = getArraySchema;
 exports.getBooleanSchema = getBooleanSchema;
@@ -98,8 +102,8 @@ exports.getRemovePatch = getRemovePatch;
 exports.getReplacePatch = getReplacePatch;
 exports.getStringSchema = getStringSchema;
 exports.num = num;
+exports.numFormula = numFormula;
 exports.obj = obj;
 exports.ref = ref;
 exports.str = str;
-//# sourceMappingURL=chunk-VGADCIBG.cjs.map
-//# sourceMappingURL=chunk-VGADCIBG.cjs.map
+exports.strFormula = strFormula;

package/dist/chunk-3MJP73IJ.js

@@ -0,0 +1 @@
+

package/dist/{chunk-LLHQWDAR.js → chunk-4U2RZHMX.js}

@@ -1,6 +1,6 @@
 // src/plugins/row-id.schema.ts
 var rowIdSchema = {
-  type: "string" /* String */,
+  type: "string",
   default: "",
   readOnly: true
 };
@@ -11,7 +11,7 @@ var ajvRowIdSchema = {
 
 // src/plugins/row-version-id.schema.ts
 var rowVersionIdSchema = {
-  type: "string" /* String */,
+  type: "string",
   default: "",
   readOnly: true
 };
@@ -22,7 +22,7 @@ var ajvRowVersionIdSchema = {
 
 // src/plugins/row-created-id.schema.ts
 var rowCreatedIdSchema = {
-  type: "string" /* String */,
+  type: "string",
   default: "",
   readOnly: true
 };
@@ -33,7 +33,7 @@ var ajvRowCreatedIdSchema = {
 
 // src/plugins/row-created-at.schema.ts
 var rowCreatedAtSchema = {
-  type: "string" /* String */,
+  type: "string",
   default: "",
   readOnly: true
 };
@@ -44,7 +44,7 @@ var ajvRowCreatedAtSchema = {
 
 // src/plugins/row-published-at.schema.ts
 var rowPublishedAtSchema = {
-  type: "string" /* String */,
+  type: "string",
   default: ""
 };
 var ajvRowPublishedAtSchema = {
@@ -54,7 +54,7 @@ var ajvRowPublishedAtSchema = {
 
 // src/plugins/row-updated-at.schema.ts
 var rowUpdatedAtSchema = {
-  type: "string" /* String */,
+  type: "string",
   default: "",
   readOnly: true
 };
@@ -65,7 +65,7 @@ var ajvRowUpdatedAtSchema = {
 
 // src/plugins/row-hash.schema.ts
 var rowHashSchema = {
-  type: "string" /* String */,
+  type: "string",
   default: "",
   readOnly: true
 };
@@ -76,7 +76,7 @@ var ajvRowHashSchema = {
 
 // src/plugins/row-schema-hash.schema.ts
 var rowSchemaHashSchema = {
-  type: "string" /* String */,
+  type: "string",
   default: "",
   readOnly: true
 };
@@ -87,39 +87,39 @@ var ajvRowSchemaHashSchema = {
 
 // src/plugins/file-schema.ts
 var fileSchema = {
-  type: "object" /* Object */,
+  type: "object",
   properties: {
-    status: { type: "string" /* String */, default: "", readOnly: true },
-    fileId: { type: "string" /* String */, default: "", readOnly: true },
-    url: { type: "string" /* String */, default: "", readOnly: true },
-    fileName: { type: "string" /* String */, default: "" },
+    status: { type: "string", default: "", readOnly: true },
+    fileId: { type: "string", default: "", readOnly: true },
+    url: { type: "string", default: "", readOnly: true },
+    fileName: { type: "string", default: "" },
     hash: {
-      type: "string" /* String */,
+      type: "string",
       default: "",
       readOnly: true
     },
     extension: {
-      type: "string" /* String */,
+      type: "string",
       default: "",
       readOnly: true
     },
     mimeType: {
-      type: "string" /* String */,
+      type: "string",
       default: "",
       readOnly: true
     },
     size: {
-      type: "number" /* Number */,
+      type: "number",
       default: 0,
       readOnly: true
     },
     width: {
-      type: "number" /* Number */,
+      type: "number",
       default: 0,
       readOnly: true
     },
     height: {
-      type: "number" /* Number */,
+      type: "number",
       default: 0,
       readOnly: true
     }
@@ -144,5 +144,3 @@ var ajvFileSchema = {
 };
 
 export { ajvFileSchema, ajvRowCreatedAtSchema, ajvRowCreatedIdSchema, ajvRowHashSchema, ajvRowIdSchema, ajvRowPublishedAtSchema, ajvRowSchemaHashSchema, ajvRowUpdatedAtSchema, ajvRowVersionIdSchema, fileSchema, rowCreatedAtSchema, rowCreatedIdSchema, rowHashSchema, rowIdSchema, rowPublishedAtSchema, rowSchemaHashSchema, rowUpdatedAtSchema, rowVersionIdSchema };
-//# sourceMappingURL=chunk-LLHQWDAR.js.map
-//# sourceMappingURL=chunk-LLHQWDAR.js.map

package/dist/{chunk-Q2UOTIMG.js → chunk-5DUMJHCA.js}

@@ -13,5 +13,3 @@ var SystemSchemaIds = /* @__PURE__ */ ((SystemSchemaIds2) => {
 })(SystemSchemaIds || {});
 
 export { SystemSchemaIds };
-//# sourceMappingURL=chunk-Q2UOTIMG.js.map
-//# sourceMappingURL=chunk-Q2UOTIMG.js.map