@heswell/vuu-data-engine-local 4.0.0-alpha.20 → 4.1.0

package/91.js

@@ -0,0 +1,282 @@
+import { JoinTable, Table } from "@heswell/vuu-table";
+import { EventEmitter } from "@vuu-ui/vuu-utils";
+class Table_Table extends EventEmitter {
+    engineTable;
+    #dataMap;
+    #indexOfKey;
+    #updateColumnName;
+    constructor(schemaOrEngineTable, data = [], dataMap, updateGenerator){
+        super();
+        this.engineTable = schemaOrEngineTable instanceof Table ? schemaOrEngineTable : new Table(schemaOrEngineTable);
+        this.#dataMap = dataMap ?? this.engineTable.columnMap;
+        this.#indexOfKey = this.engineTable.indexOfKeyField;
+        for (const row of data)this.engineTable.insert(row);
+        this.engineTable.addListener({
+            onInsert: (_rowIdx, row)=>this.emit("insert", row),
+            onUpdate: (_rowIdx, row)=>this.emit("update", row, this.#updateColumnName),
+            onDelete: (_rowIdx, row)=>this.emit("delete", String(row[this.#indexOfKey])),
+            onClear: ()=>void 0
+        });
+        updateGenerator?.setTable(this);
+        updateGenerator?.setRange({
+            from: 0,
+            to: 100
+        });
+    }
+    get data() {
+        return this.engineTable.rows;
+    }
+    get map() {
+        return this.#dataMap;
+    }
+    get schema() {
+        return this.engineTable.schema;
+    }
+    get name() {
+        return this.engineTable.name;
+    }
+    get rowCount() {
+        return this.engineTable.rowCount;
+    }
+    delete(key) {
+        if (!this.engineTable.delete(key)) throw Error(`[Table] delete key ${key} not found`);
+    }
+    insert(row, _emitEvent = true) {
+        const ts = Date.now();
+        const { vuuCreatedTimestamp, vuuUpdatedTimestamp } = this.#dataMap;
+        if (void 0 !== vuuUpdatedTimestamp) row[vuuUpdatedTimestamp] = ts;
+        if (void 0 !== vuuCreatedTimestamp) row[vuuCreatedTimestamp] = ts;
+        this.engineTable.insert(row);
+    }
+    findByKey(key) {
+        return this.engineTable.getRowAtKey(key, false);
+    }
+    update(key, columnName, value) {
+        const rowIdx = this.engineTable.rowIndexAtKey(key);
+        if (-1 !== rowIdx) {
+            const newRow = this.engineTable.rows[rowIdx].slice();
+            newRow[this.#dataMap[columnName]] = value;
+            this.#updateColumnName = columnName;
+            try {
+                this.engineTable.update(rowIdx, newRow);
+            } finally{
+                this.#updateColumnName = void 0;
+            }
+        }
+    }
+    updateRow(row) {
+        const rowIdx = this.engineTable.rowIndexAtKey(String(row[this.#indexOfKey]));
+        if (-1 !== rowIdx) this.engineTable.update(rowIdx, row);
+    }
+}
+function buildDataColumnMapFromSchema(schema) {
+    const map = {};
+    schema.columns.forEach((col, index)=>{
+        map[col.name] = index;
+    });
+    return map;
+}
+function buildDataColumnMap(schemas, tableName) {
+    return buildDataColumnMapFromSchema(schemas[tableName]);
+}
+const DEFAULT_RANGE_LIMITS = {
+    maxRangeEnd: 1000000,
+    maxRangeWidth: 1000
+};
+const tableKey = ({ module, table })=>`${module}:${table}`;
+const createTable = (schema, data = [], dataMap = buildDataColumnMapFromSchema(schema), updateGenerator)=>new Table_Table(schema, data, dataMap, updateGenerator);
+const createJoinTable = (joinTable, table1, table2, joinColumn, joinTypeOrOptions = "inner")=>{
+    const { joinType = "inner", columns, schema } = "string" == typeof joinTypeOrOptions ? {
+        joinType: joinTypeOrOptions
+    } : joinTypeOrOptions;
+    const engineJoinTable = new JoinTable({
+        schema: buildJoinSchema(joinTable, table1.schema, table2.schema, {
+            columns,
+            schema
+        }),
+        baseTable: table1.engineTable,
+        joinTable: table2.engineTable,
+        leftColumn: joinColumn,
+        rightColumn: joinColumn,
+        joinType
+    });
+    return new Table_Table(engineJoinTable);
+};
+const buildJoinSchema = (joinTable, schema1, schema2, { columns, schema })=>{
+    const name = `${joinTable.module}:${joinTable.table}`;
+    const fail = (message)=>{
+        throw Error(`[createJoinTable] ${name}: ${message}`);
+    };
+    if (columns && schema) fail("pass either columns or schema, not both");
+    if (schema) {
+        const { module, table } = schema.table;
+        if (module !== joinTable.module || table !== joinTable.table) fail(`schema is for table ${module}:${table}`);
+        if (schema.key !== schema1.key) fail(`schema key ${schema.key} must be the key of ${schema1.table.table} (${schema1.key})`);
+    }
+    const sourceColumns = new Set([
+        ...schema1.columns,
+        ...schema2.columns
+    ].map((col)=>col.name));
+    const columnNames = schema?.columns.map((col)=>col.name) ?? columns ?? Array.from(sourceColumns).sort();
+    const seen = new Set();
+    for (const columnName of columnNames){
+        if (!sourceColumns.has(columnName)) fail(`unknown column ${columnName}, not in ${schema1.table.table} or ${schema2.table.table}`);
+        if (seen.has(columnName)) fail(`duplicate column ${columnName}`);
+        seen.add(columnName);
+    }
+    if (!seen.has(schema1.key)) fail(`columns must include the key column ${schema1.key}`);
+    const joinColumns = columnNames.map((columnName)=>({
+            name: columnName,
+            serverDataType: getServerDataType(columnName, schema1, schema2)
+        }));
+    if (schema) {
+        schema.columns.forEach(({ name: columnName, serverDataType }, i)=>{
+            if (serverDataType !== joinColumns[i].serverDataType) fail(`column ${columnName} is declared ${serverDataType} but is ${joinColumns[i].serverDataType} in the source table`);
+        });
+        return {
+            ...schema,
+            rangeLimits: schema.rangeLimits ?? DEFAULT_RANGE_LIMITS
+        };
+    }
+    return {
+        key: schema1.key,
+        table: joinTable,
+        rangeLimits: DEFAULT_RANGE_LIMITS,
+        columns: joinColumns
+    };
+};
+class TableContainer {
+    #tables = new Map();
+    createTable = (schema, data = [], dataMap = buildDataColumnMapFromSchema(schema), updateGenerator)=>{
+        const table = createTable(schema, data, dataMap, updateGenerator);
+        this.addTable(table);
+        return table;
+    };
+    createJoinTable(joinTable, table1, table2, joinColumn, joinTypeOrOptions = "inner") {
+        const newTable = createJoinTable(joinTable, this.getTable(table1), this.getTable(table2), joinColumn, joinTypeOrOptions);
+        this.addTable(newTable);
+        return newTable;
+    }
+    addTable(table, as = table.schema.table) {
+        this.#tables.set(tableKey(as), table);
+    }
+    removeTable(table) {
+        return this.#tables.delete(tableKey(table));
+    }
+    hasTable(table) {
+        return this.#tables.has(tableKey(table));
+    }
+    getTable(table) {
+        if ("string" == typeof table) {
+            const matches = Array.from(this.#tables.keys()).filter((key)=>key.endsWith(`:${table}`));
+            if (1 === matches.length) return this.#tables.get(matches[0]);
+            if (matches.length > 1) throw Error(`[TableContainer] table name ${table} is ambiguous (${matches.join(", ")}), use {module, table}`);
+            throw Error(`[TableContainer] no table ${table}`);
+        }
+        const found = this.#tables.get(tableKey(table));
+        if (found) return found;
+        throw Error(`[TableContainer] no table ${tableKey(table)}`);
+    }
+    get tables() {
+        return Array.from(this.#tables.values());
+    }
+    clear() {
+        this.#tables.clear();
+    }
+}
+const getServerDataType = (columnName, { columns: cols1, table: t1 }, { columns: cols2, table: t2 })=>{
+    const col1 = cols1.find((col)=>col.name === columnName);
+    const col2 = cols2.find((col)=>col.name === columnName);
+    if (col1 && col2) if (col1.serverDataType === col2.serverDataType) return col1.serverDataType;
+    else throw Error(`both tables ${t1.table} and ${t2.table} implement column ${columnName}, but with types differ`);
+    if (col1) return col1.serverDataType;
+    if (col2) return col2.serverDataType;
+    throw Error("how is this possible");
+};
+class LocalEngine {
+    tableContainer = new TableContainer();
+    #modules = new Map();
+    #disposed = false;
+    constructor({ modules = [] } = {}){
+        for (const module of modules)this.register(module);
+    }
+    register(module) {
+        const existing = this.#modules.get(module.name);
+        if (existing === module) return module;
+        if (existing) this.unregister(existing.name);
+        this.#modules.set(module.name, module);
+        for (const [tableName, table] of Object.entries(module.getTables()))this.tableContainer.addTable(table, {
+            module: module.name,
+            table: tableName
+        });
+        module.attachEngine(this);
+        return module;
+    }
+    unregister(moduleName) {
+        const module = this.#modules.get(moduleName);
+        if (module) {
+            this.#modules.delete(moduleName);
+            for (const tableName of module.getTableList())this.tableContainer.removeTable({
+                module: moduleName,
+                table: tableName
+            });
+            module.detachEngine(this);
+            return true;
+        }
+        return false;
+    }
+    hasModule(moduleName) {
+        return this.#modules.has(moduleName);
+    }
+    getModule(moduleName) {
+        const module = this.#modules.get(moduleName);
+        if (module) return module;
+        throw Error(`[LocalEngine] module ${moduleName} not found`);
+    }
+    get modules() {
+        return Array.from(this.#modules.values());
+    }
+    get moduleNames() {
+        return Array.from(this.#modules.keys());
+    }
+    getTableList() {
+        return this.modules.flatMap((module)=>module.getTableList().map((table)=>({
+                    module: module.name,
+                    table
+                })));
+    }
+    getTableSchema({ module, table }) {
+        return this.getModule(module).getTableSchema(table);
+    }
+    createDataSource({ module, table }, viewport, config) {
+        return this.getModule(module).createDataSource(table, viewport, config);
+    }
+    get disposed() {
+        return this.#disposed;
+    }
+    dispose() {
+        for (const module of this.modules){
+            const owned = module.engine === this;
+            this.unregister(module.name);
+            if (owned) module.dispose();
+        }
+        this.tableContainer.clear();
+        this.#disposed = true;
+    }
+}
+const createLocalEngine = (options)=>new LocalEngine(options);
+let defaultEngine;
+const getDefaultEngine = ()=>{
+    if (void 0 === defaultEngine || defaultEngine.disposed) defaultEngine = new LocalEngine();
+    return defaultEngine;
+};
+const resetDefaultEngine = ()=>{
+    defaultEngine?.dispose();
+    defaultEngine = void 0;
+};
+const ensureVuuModule = (module)=>{
+    const engine = getDefaultEngine();
+    if (!engine.hasModule(module.name)) engine.register(module);
+    return module;
+};
+export { LocalEngine, TableContainer, Table_Table as Table, buildDataColumnMap, buildDataColumnMapFromSchema, createJoinTable, createLocalEngine, createTable, ensureVuuModule, getDefaultEngine, resetDefaultEngine };

package/README.md

@@ -9,17 +9,213 @@ The package runs alongside `@vuu-ui/vuu-data-test` and has the same public API.
 meant to replace the `VuuModule` / `TickingArrayDataSource` core in that package. The
 two packages don't depend on each other.
 
+## Peer dependencies
+
+All `@vuu-ui` packages are peers declared as `^4.0.0-alpha.20`, so the engine uses the host
+application's single copy of each (a second `@vuu-ui/vuu-utils` or `@vuu-ui/core` would mean
+a second set of React contexts). They are `@vuu-ui/vuu-utils` and `@vuu-ui/vuu-filter-parser`
+(runtime), `@vuu-ui/core` (React provider, `/react` entry only), and the type-only `vuu-data-types`,
+`vuu-filter-types`, `vuu-protocol-types` and `vuu-table-types`.
+
 ## Architecture
 
-| Component                              | Role                                                                                                                                                                                                                                  |
-| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `Table`                                | A façade over the engine `Table` that keeps the existing `Table` API. Inserts, updates and deletes go straight to the engine. Every change notifies subscribed viewports.                                                             |
-| `TableContainer`                       | A registry of tables, including join tables.                                                                                                                                                                                          |
+| Component                              | Role                                                                                                                                                                                                                                    |
+| -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Table`                                | A façade over the engine `Table` that keeps the existing `Table` API. Inserts, updates and deletes go straight to the engine. Every change notifies subscribed viewports.                                                               |
+| `LocalEngine`                          | An isolated in-browser Vuu server: the registered `VuuModule`s and a `TableContainer` of their tables. No React or DOM dependency.                                                                                                      |
+| `TableContainer`                       | A registry of tables, including join tables, keyed by `{module, table}`. Each engine has its own.                                                                                                                                       |
 | `EngineDataSource`                     | A `DataSource` implementation backed by an engine `Viewport`. It handles windowing, sort, filter, groupBy, selection (including select-all), freeze, base filter, link filter and permission filter. Row updates are batched per frame. |
-| `ModuleDataSource`                     | Extends `EngineDataSource` with the module features: RPC and menu services, edit sessions, and visual links. `TickingArrayDataSource` is a deprecated alias.                                                                          |
-| `VuuModule`                            | Creates `ModuleDataSource` instances. Row permissions are passed to the engine as a `permissionFilter` predicate.                                                                                                                     |
-| `RuntimeVisualLink`                    | When the parent's selection changes, sets the child's engine link filter.                                                                                                                                                             |
-| `UpdateGenerator` / `TickingGenerator` | Simulated ticking data that writes into the engine tables.                                                                                                                                                                            |
+| `ModuleDataSource`                     | Extends `EngineDataSource` with the module features: RPC and menu services, edit sessions, and visual links. `TickingArrayDataSource` is a deprecated alias.                                                                            |
+| `VuuModule`                            | Creates `ModuleDataSource` instances. Row permissions are passed to the engine as a `permissionFilter` predicate. Edit sessions can be customised per table with edit hooks.                                                            |
+| `RuntimeVisualLink`                    | When the parent's selection changes, sets the child's engine link filter.                                                                                                                                                               |
+| `UpdateGenerator` / `TickingGenerator` | Simulated ticking data that writes into the engine tables.                                                                                                                                                                              |
+
+## Usage
+
+Importing the package has no side effects: no modules, tables or timers are created
+until you ask for them. The main entry needs no DOM, so it runs in plain Node or Bun with
+no shims: it uses `requestAnimationFrame` when present and falls back to `setTimeout`
+otherwise. The React bindings (`createDataSourceProvider`, `createLocalVuuServer`,
+`LocalDataSourceProvider`) are in `@heswell/vuu-data-engine-local/react`, because
+`@vuu-ui/core` needs a DOM (`ResizeObserver`) at import time.
+
+```ts
+import {
+  createLocalEngine,
+  registerDemoModules,
+} from "@heswell/vuu-data-engine-local";
+import { createLocalVuuServer } from "@heswell/vuu-data-engine-local/react";
+
+// Your own modules, in an isolated engine
+const engine = createLocalEngine({ modules: [new OrdersModule()] });
+const dataSource = engine.createDataSource({
+  module: "ORDERS",
+  table: "parentOrders",
+});
+await dataSource.subscribe({ range: { from: 0, to: 100 } }, callback);
+engine.dispose(); // disposes its modules and stops their timers
+
+// A local Vuu server for a local-mode AuthenticationProvider (new engine per server)
+const server = createLocalVuuServer({
+  connectionId: "orders",
+  modules: [new OrdersModule()],
+});
+// server.DataSourceProvider, server.engine
+
+// The demo SIMUL, BASKET and TEST modules
+const { simulModule } = registerDemoModules(createLocalEngine());
+```
+
+### Engines
+
+| API                                                                   | Description                                                                                                                                                |
+| --------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `createLocalEngine({ modules? })`                                     | A new, isolated `LocalEngine`. Two engines, or two modules in one engine, can use the same table names.                                                    |
+| `engine.register(module)` / `unregister(name)`                        | Add or remove a module and its tables. A module is attached to the first engine it is registered with.                                                     |
+| `engine.getModule(name)`, `hasModule`, `modules`                      | Look up modules.                                                                                                                                           |
+| `engine.getTableList()`                                               | `VuuTable[]` (`{module, table}`) for every registered module.                                                                                              |
+| `engine.getTableSchema(vuuTable)`                                     | A table's schema.                                                                                                                                          |
+| `engine.createDataSource(vuuTable, vp?, cfg?)`                        | A `ModuleDataSource` for a table.                                                                                                                          |
+| `engine.tableContainer`                                               | The engine's `TableContainer`. Tables are keyed by `{module, table}`; a bare table name is accepted only if exactly one module has a table with that name. |
+| `engine.dispose()`                                                    | Unregisters every module and disposes those attached to this engine (stopping ticking data and timers).                                                    |
+| `createDataSourceProvider(engine)` (`/react`)                         | A React provider installing the legacy and core data contexts for the engine.                                                                              |
+| `createLocalVuuServer({ connectionId, modules, engine? })` (`/react`) | A `LocalVuuServer` (`{connectionId, DataSourceProvider, engine}`). Uses a new engine unless one is passed.                                                 |
+| `registerDemoModules(engine?)`                                        | Creates the SIMUL, BASKET and TEST demo modules and registers them with `engine` (default: the default engine).                                            |
+| `getDefaultEngine()` / `resetDefaultEngine()`                         | The shared engine behind the deprecated globals below.                                                                                                     |
+
+### Edit sessions: hooks and service overrides
+
+The built-in edit-session RPC services (`createSessionTable`, `editCell`, `addRow`, `deleteRow`,
+`undoRowChange`, `endEditSession`, …) can be overridden by `rpcName`, per module with
+`moduleServices` or per table with `services`. Precedence: table services, then module
+services, then the built-ins. Services registered for a source table also apply to its
+session tables.
+
+Most customisation needs only edit hooks, which mirror vuu-server's. Implement them per
+table with `editHooks` (these win), or for every table as protected methods of the module.
+
+| Hook                                              | Default                                                                                                                                                                      |
+| ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `canEditSource(column, ctx)`                      | `true`: editCell may write directly to a source table (outside a session).                                                                                                   |
+| `isEditableColumn(table, column, ctx)`            | Any column except the key and the system columns (`vuuCreatedTimestamp`, `vuuUpdatedTimestamp`, `vuuMsg`, `vuuAction`). The key of a row added in the session may be edited. |
+| `validateCellEdit(edit)`                          | Accept. Return an error message to refuse the edit.                                                                                                                          |
+| `getStaleColumns(sourceTable, sourceRow, change)` | `defaultGetStaleColumns`: for editCell, the edited columns that changed in the source since the row was copied into the session; for deleteRow, any column.                  |
+| `canSaveSession(prepared, ctx)`                   | `true`. Return `false` or a reason to refuse the save. May be async.                                                                                                         |
+| `applySessionSave(sessionTable, prepared, ctx)`   | `defaultApplySessionSave`: writes the changes to the source table atomically. May be async.                                                                                  |
+
+```ts
+class OrdersModule extends VuuModule<"parentOrders" | "childOrders"> {
+  protected editHooks = {
+    parentOrders: {
+      canSaveSession: ({ changes }) =>
+        changes.every(({ cellUpdates }) => Number(cellUpdates.qty) > 0) ||
+        "qty must be positive",
+      // amend orders through the order service instead of writing the table
+      applySessionSave: (_sessionTable, { changes }) =>
+        orderService.amend(changes),
+    },
+  };
+  // ...
+}
+```
+
+`deleteRow` and `deleteSelectedRows` behave as on vuu-server: they are only valid in an edit
+session, and mark the session row `vuuAction = "deleteRow"` whatever the `mode` (`"hard"`,
+vuu-ui's default, or `"soft"`). The row stays in the session until it is saved, when
+`applySessionSave` receives it as a `deleteRow` change, or `undoRowChange` restores it. A
+row added in the session is simply dropped. Outside a session `deleteRow` returns an error;
+`deleteSourceRow` (protected, not registered) keeps the old direct delete for subclasses
+such as SIMUL's `DELETE_ROW`.
+
+`endEditSession({ save: true })`:
+
+1. Rows already handled by `beforeSessionSave` (with a `vuuMsg`) are skipped.
+2. Changes are prepared. A row added with an existing key fails with `"duplicate key"`; a
+   source row that is missing or stale fails with exactly `"stale update"` (vuu-ui's
+   `VuuDataSource` matches this string and throws `StaleUpdateError`). Setting
+   `params.force` skips the stale check. The affected session rows get a `vuuMsg`
+   (`stale:<key>:<columns>`, `<action>:<key>:source row missing`,
+   `addRow:<key>:key already exists`).
+3. `canSaveSession`, then `applySessionSave`. A refusal or failure (`false`, an
+   `ERROR_RESULT`, or a thrown error) leaves the session open, so the user can retry or
+   cancel. Exported messages: `STALE_UPDATE`, `DUPLICATE_KEY`, `SAVE_NOT_PERMITTED`,
+   `SAVE_FAILED`.
+4. `afterSessionSave`, then the session rows are reset (deleted rows removed, `vuuAction`
+   and `vuuMsg` cleared, snapshots refreshed).
+
+### Join tables
+
+`createJoinTable(joinTable, table1, table2, joinColumn, joinType = "inner")` (and
+`tableContainer.createJoinTable`) creates a join that is kept up to date as either table
+changes. Pass `"leftOuter"` to keep every `table1` row. For a row with no match, the
+`table2` columns are `null` (not `0`), as on vuu-server, and vuu-ui renders them empty.
+Sort places nulls first when ascending; relational filters (`<`, `>=`, …) never match
+null; and aggregations skip nulls.
+
+By default the join table has every column of both tables, in alphabetical order. To
+control the columns, pass an options object as the fifth argument instead of a join type:
+
+```ts
+// an ordered list of column names, possibly a subset (must include table1's key)
+createJoinTable(joinTable, instruments, prices, "ric", {
+  joinType: "leftOuter",
+  columns: ["ric", "exchange", "bid", "ask"],
+});
+
+// or a declared TableSchema for the join table, e.g. the schema vuu-server returns
+createJoinTable(instrumentPricesSchema.table, instruments, prices, "ric", {
+  joinType: "leftOuter",
+  schema: instrumentPricesSchema,
+});
+```
+
+`columns` and `schema` are mutually exclusive, and `joinType` still defaults to `"inner"`.
+Column types come from the source tables; a column in both tables takes its value from
+`table1`. Unknown or duplicate columns, a missing key column, a declared `serverDataType`
+that differs from the source column, or a `schema` whose `table` or `key` does not match
+(`joinTable`, `table1`'s key) throw an error naming the join table and the problem.
+
+### Ranges
+
+`subscribe({ range })`, `dataSource.range = …` and `setRange` accept a vuu-utils `Range` or
+a plain `{from, to}`.
+
+### Deprecated globals and the `/legacy` entry
+
+`tableContainer`, `LocalDataSourceProvider` and `ensureVuuModule` use the default engine
+(`getDefaultEngine()`). `@heswell/vuu-data-engine-local/legacy` re-exports the main and
+`/react` entries and,
+on import, registers the demo modules with the default engine, exporting the instances
+`simulModule`, `basketModule`, `testModule`, `moduleAdminModule`, `userAdminModule` and
+`notificationsModule` as 2.x did. It is the only entry point with side effects
+(`"sideEffects": ["./src/legacy.ts"]`).
+
+## Migrating from 3.x
+
+These are breaking changes; the next release should be 4.0.0.
+
+| 3.x                                                                                                       | 4.x                                                                                                                |
+| --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `createDataSourceProvider`, `createLocalVuuServer`, `LocalDataSourceProvider` exported by the main entry. | Import them from `@heswell/vuu-data-engine-local/react` (or `/legacy`). The main entry no longer needs a DOM.      |
+| `deleteRow` with `mode: "hard"` removed the session row, so the save never saw the delete.                | The row is marked `vuuAction = "deleteRow"` in either mode and applied on save (or restored by `undoRowChange`).   |
+| `deleteRow` outside an edit session deleted the source row.                                               | Returns an error, as vuu-server does. Use an edit session, or expose the protected `deleteSourceRow` as a service. |
+
+## Migrating from 2.x
+
+These are breaking changes; the next release should be 3.0.0.
+
+| 2.x                                                                                                                                           | 3.x                                                                                                                                                                                            |
+| --------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Importing the package created and registered SIMUL, BASKET, TEST, MODULE_DISCOVERY, USER_ADMIN and NOTIFICATIONS, and exported the instances. | Nothing is created on import. Call `registerDemoModules()` or create the modules yourself, or import `/legacy`.                                                                                |
+| `new SomeModule()` registered itself in a global module container.                                                                            | Register modules with an engine: `createLocalEngine({ modules })`, `engine.register()`, or `createLocalVuuServer`.                                                                             |
+| `createLocalVuuServer` registered its modules globally, so `LocalDataSourceProvider` saw them.                                                | Each server has its own engine (`server.engine`). Pass `engine: getDefaultEngine()` to share the default engine.                                                                               |
+| `tableContainer` was global and keyed by bare table name.                                                                                     | Each engine has its own, keyed by `{module, table}`. The global `tableContainer` is a deprecated alias of the default engine's; a bare name throws if two modules have a table with that name. |
+| `ModuleContainer` / `moduleContainer`.                                                                                                        | Removed: use `LocalEngine`.                                                                                                                                                                    |
+| Module and table `services` were added alongside the built-in edit services.                                                                  | They override built-in services with the same `rpcName`.                                                                                                                                       |
+| editCell could change the key and system columns, and edit missing or deleted rows.                                                           | Refused by default (see `isEditableColumn`). Editing a missing row returns an error.                                                                                                           |
+| `endEditSession` saved without checking for concurrent source changes or duplicate keys.                                                      | Fails with `"stale update"` or `"duplicate key"` (unless `force`). After a successful save the session rows are reset.                                                                         |
+| Demo prices and notifications ticked from import.                                                                                             | They start when a data source is created, and stop on `engine.dispose()`.                                                                                                                      |
+| Reference data (`instrumentsTable`, `pricesTable`, `instrumentsData`, …) was created on import.                                               | Lazy getters and factories (`getInstrumentsData()`, `createPricesTable()`, …).                                                                                                                 |
 
 ## Differences from `@vuu-ui/vuu-data-test`
 
@@ -38,7 +234,8 @@ npm run showcase:engine   # equivalent to: VUU_DATA_ENGINE=local npm run showcas
 ```
 
 This aliases `@vuu-ui/vuu-data-test` to `@heswell/vuu-data-engine-local` in the showcase
-rsbuild config. The examples themselves don't change.
+rsbuild config. The examples themselves don't change. The examples use the eagerly created demo
+modules, so from 3.0 the alias should point to `@heswell/vuu-data-engine-local/legacy`.
 
 The showcase uses the published package. To publish it from vuu-websocket:
 
@@ -64,22 +261,22 @@ results for the sort, filter and groupBy scenarios.
 
 Mean time per operation, 100k rows, Node 24, Apple Silicon:
 
-| Scenario                                      | legacy   | engine  | speed-up |
-| --------------------------------------------- | -------- | ------- | -------- |
-| create + subscribe                            | 24.1 ms  | 8.7 ms  | 2.8x     |
-| sort numeric column                           | 62.1 ms  | 14.1 ms | 4.4x     |
-| sort two columns                              | 64.6 ms  | 17.1 ms | 3.8x     |
-| filter                                        | 5.7 ms   | 1.3 ms  | 4.3x     |
-| groupBy ccy, set/clear                        | 1.6 ms   | 1.2 ms  | 1.3x     |
-| groupBy ccy + exchange, set/clear             | 2.2 ms   | 2.0 ms  | 1.1x     |
-| scroll, 100 range changes                     | 0.82 ms  | 0.45 ms | 1.8x     |
-| 1000 ticks, random rows                       | 1543 ms  | 0.35 ms | ~4400x   |
-| 1000 ticks, rows in viewport                  | 0.63 ms  | 0.10 ms | 6.6x     |
-| 1000 ticks, sorted column                     | 3012 ms  | 1.9 ms  | ~1600x   |
-| 1000 ticks, filtered column                   | 1903 ms  | 0.55 ms | ~3400x   |
-| 1000 ticks, grouped                           | 1205 ms  | 0.39 ms | ~3100x   |
-| 500 deletes + 500 inserts                     | 1628 ms  | 0.60 ms | ~2700x   |
-| 500 deletes + 500 inserts, sorted             | 2564 ms  | 1.57 ms | ~1600x   |
+| Scenario                          | legacy  | engine  | speed-up |
+| --------------------------------- | ------- | ------- | -------- |
+| create + subscribe                | 24.1 ms | 8.7 ms  | 2.8x     |
+| sort numeric column               | 62.1 ms | 14.1 ms | 4.4x     |
+| sort two columns                  | 64.6 ms | 17.1 ms | 3.8x     |
+| filter                            | 5.7 ms  | 1.3 ms  | 4.3x     |
+| groupBy ccy, set/clear            | 1.6 ms  | 1.2 ms  | 1.3x     |
+| groupBy ccy + exchange, set/clear | 2.2 ms  | 2.0 ms  | 1.1x     |
+| scroll, 100 range changes         | 0.82 ms | 0.45 ms | 1.8x     |
+| 1000 ticks, random rows           | 1543 ms | 0.35 ms | ~4400x   |
+| 1000 ticks, rows in viewport      | 0.63 ms | 0.10 ms | 6.6x     |
+| 1000 ticks, sorted column         | 3012 ms | 1.9 ms  | ~1600x   |
+| 1000 ticks, filtered column       | 1903 ms | 0.55 ms | ~3400x   |
+| 1000 ticks, grouped               | 1205 ms | 0.39 ms | ~3100x   |
+| 500 deletes + 500 inserts         | 1628 ms | 0.60 ms | ~2700x   |
+| 500 deletes + 500 inserts, sorted | 2564 ms | 1.57 ms | ~1600x   |
 
 Notes: