@heswell/vuu-data-engine-local 3.0.0 → 4.0.0

package/91.js

@@ -0,0 +1,248 @@
+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, joinType = "inner")=>{
+    const { schema: schema1 } = table1;
+    const { schema: schema2 } = table2;
+    const combinedColumns = new Set([
+        ...schema1.columns,
+        ...schema2.columns
+    ].map((col)=>col.name).sort());
+    const combinedSchema = {
+        key: schema1.key,
+        table: joinTable,
+        rangeLimits: DEFAULT_RANGE_LIMITS,
+        columns: Array.from(combinedColumns).map((columnName)=>({
+                name: columnName,
+                serverDataType: getServerDataType(columnName, schema1, schema2)
+            }))
+    };
+    const engineJoinTable = new JoinTable({
+        schema: combinedSchema,
+        baseTable: table1.engineTable,
+        joinTable: table2.engineTable,
+        leftColumn: joinColumn,
+        rightColumn: joinColumn,
+        joinType
+    });
+    return new Table_Table(engineJoinTable);
+};
+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, joinType = "inner") {
+        const newTable = createJoinTable(joinTable, this.getTable(table1), this.getTable(table2), joinColumn, joinType);
+        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

@@ -14,7 +14,7 @@ two packages don't depend on each other.
 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), and the type-only `vuu-data-types`,
+(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
@@ -33,14 +33,17 @@ a second set of React contexts). They are `@vuu-ui/vuu-utils` and `@vuu-ui/vuu-f
 ## Usage
 
 Importing the package has no side effects: no modules, tables or timers are created
-until you ask for them.
+until you ask for them. The main entry needs no DOM, so it runs in plain Node or Bun. 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,
-  createLocalVuuServer,
   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()] });
@@ -64,20 +67,20 @@ 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)`                         | A React provider installing the legacy and core data contexts for the engine.                                                                              |
-| `createLocalVuuServer({ connectionId, modules, engine? })` | 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.                                                                                                     |
+| 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
 
@@ -115,6 +118,14 @@ class OrdersModule extends VuuModule<"parentOrders" | "childOrders"> {
 }
 ```
 
+`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.
@@ -131,6 +142,15 @@ class OrdersModule extends VuuModule<"parentOrders" | "childOrders"> {
 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.
+
 ### Ranges
 
 `subscribe({ range })`, `dataSource.range = …` and `setRange` accept a vuu-utils `Range` or
@@ -139,12 +159,23 @@ 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 entry and,
+(`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.