@heswell/vuu-data-engine-local 4.1.0 → 4.2.0

package/91.js

@@ -1,9 +1,15 @@
 import { JoinTable, Table } from "@heswell/vuu-table";
 import { EventEmitter } from "@vuu-ui/vuu-utils";
+const defaultRangeLimits = new WeakMap();
+const setDefaultRangeLimits = (table, rangeLimits)=>{
+    defaultRangeLimits.set(table, rangeLimits);
+};
 class Table_Table extends EventEmitter {
     engineTable;
     #dataMap;
+    #destroyed = false;
     #indexOfKey;
+    #listener;
     #updateColumnName;
     constructor(schemaOrEngineTable, data = [], dataMap, updateGenerator){
         super();
@@ -11,12 +17,13 @@ class Table_Table extends EventEmitter {
         this.#dataMap = dataMap ?? this.engineTable.columnMap;
         this.#indexOfKey = this.engineTable.indexOfKeyField;
         for (const row of data)this.engineTable.insert(row);
-        this.engineTable.addListener({
+        this.#listener = {
             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
-        });
+        };
+        this.engineTable.addListener(this.#listener);
         updateGenerator?.setTable(this);
         updateGenerator?.setRange({
             from: 0,
@@ -32,6 +39,18 @@ class Table_Table extends EventEmitter {
     get schema() {
         return this.engineTable.schema;
     }
+    get rangeLimits() {
+        return this.schema.rangeLimits ?? defaultRangeLimits.get(this);
+    }
+    get destroyed() {
+        return this.#destroyed;
+    }
+    destroy() {
+        if (this.#destroyed) return;
+        this.#destroyed = true;
+        this.engineTable.removeListener(this.#listener);
+        if (this.engineTable instanceof JoinTable) this.engineTable.destroy();
+    }
     get name() {
         return this.engineTable.name;
     }
@@ -100,7 +119,9 @@ const createJoinTable = (joinTable, table1, table2, joinColumn, joinTypeOrOption
         rightColumn: joinColumn,
         joinType
     });
-    return new Table_Table(engineJoinTable);
+    const table = new Table_Table(engineJoinTable);
+    setDefaultRangeLimits(table, DEFAULT_RANGE_LIMITS);
+    return table;
 };
 const buildJoinSchema = (joinTable, schema1, schema2, { columns, schema })=>{
     const name = `${joinTable.module}:${joinTable.table}`;
@@ -133,10 +154,7 @@ const buildJoinSchema = (joinTable, schema1, schema2, { columns, 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 schema;
     }
     return {
         key: schema1.key,
@@ -147,21 +165,27 @@ const buildJoinSchema = (joinTable, schema1, schema2, { columns, schema })=>{
 };
 class TableContainer {
     #tables = new Map();
+    #created = new Set();
     createTable = (schema, data = [], dataMap = buildDataColumnMapFromSchema(schema), updateGenerator)=>{
         const table = createTable(schema, data, dataMap, updateGenerator);
         this.addTable(table);
+        this.#created.add(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);
+        this.#created.add(newTable);
         return newTable;
     }
     addTable(table, as = table.schema.table) {
         this.#tables.set(tableKey(as), table);
     }
     removeTable(table) {
-        return this.#tables.delete(tableKey(table));
+        const key = tableKey(table);
+        const found = this.#tables.get(key);
+        if (found) this.#created.delete(found);
+        return this.#tables.delete(key);
     }
     hasTable(table) {
         return this.#tables.has(tableKey(table));
@@ -181,6 +205,8 @@ class TableContainer {
         return Array.from(this.#tables.values());
     }
     clear() {
+        for (const table of this.#created)table.destroy();
+        this.#created.clear();
         this.#tables.clear();
     }
 }

package/README.md

@@ -175,6 +175,26 @@ Column types come from the source tables; a column in both tables takes its valu
 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.
 
+With `schema`, the join's `Table.schema` is exactly the declared schema (no keys added), so
+it matches `getTableSchema` / TABLE_META_RESP and can be published as a module's
+`schemas`. If the declared schema has no `rangeLimits`, the engine default
+(`maxRangeEnd: 1_000_000`, `maxRangeWidth: 1_000`) still applies, exposed as
+`table.rangeLimits` rather than added to the schema. Joins created without `schema`
+(default or `columns`) generate a schema that includes those default `rangeLimits`.
+
+`createJoinTable` returns a `JoinTableHandle` (`Table<JoinTable>`), whose `engineTable` is
+typed as the `@heswell/vuu-table` `JoinTable`. Call `table.destroy()` to detach a join from
+its source tables, after which source changes no longer propagate to it. `destroy()` is
+available on every `Table` and is safe to call more than once. You rarely need to call it
+yourself:
+
+- `module.dispose()` (called by `engine.dispose()` for modules the engine owns) destroys the
+  join tables the module publishes.
+- `tableContainer.clear()` (also called by `engine.dispose()`) destroys tables created by
+  that container's `createTable` / `createJoinTable`.
+- `engine.unregister()` and `tableContainer.removeTable()` do not destroy tables, as they
+  may still be in use.
+
 ### Ranges
 
 `subscribe({ range })`, `dataSource.range = …` and `setRange` accept a vuu-utils `Range` or

package/index.js

@@ -1,3 +1,4 @@
+import { JoinTable } from "@heswell/vuu-table";
 import { Clock, EventEmitter, NULL_RANGE, Range, StaleUpdateError, assertExpectedSessionTable, filterAsQuery, isAddRowRpcRequest, isBeginEditSessionRpcRequest, isConfigChanged, isCreateSessionTableRpcRequest, isDeleteSelectedRowsRpcRequest, isEditCellRpcRequest, isEndEditSessionRpcRequest, isRpcSuccess, isTypeaheadRequest, isUndoRowChangeRpcRequest, metadataKeys, sessionDataSourceConfig, toSchemaColumn, uuid, vanillaConfig, withConfigDefaults } from "@vuu-ui/vuu-utils";
 import { inMemoryDataEngine } from "@heswell/vuu-viewport";
 import { parseFilter } from "@vuu-ui/vuu-filter-parser";
@@ -362,7 +363,8 @@ class EngineDataSource extends EventEmitter {
         this.clientCallback = callback;
         this.viewport = viewport;
         this.#status = "subscribed";
-        if (this.tableSchema.rangeLimits) this.#maxRangeEnd = this.tableSchema.rangeLimits.maxRangeEnd;
+        const rangeLimits = this.#table.rangeLimits;
+        if (rangeLimits) this.#maxRangeEnd = rangeLimits.maxRangeEnd;
         let config = this._config;
         const hasConfigProps = aggregations || columns || filterSpec || groupBy || sort;
         if (hasConfigProps) config = {
@@ -1160,6 +1162,7 @@ class VuuModule {
         if (this.#engine === engine) this.#engine = void 0;
     }
     dispose() {
+        for (const table of Object.values(this.tables))if (table.engineTable instanceof JoinTable) table.destroy();
         this.#sessionTableMap = {};
         this.#sessionSourceTableMap = {};
         this.#sessionSnapshots.clear();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heswell/vuu-data-engine-local",
-  "version": "4.1.0",
+  "version": "4.2.0",
   "description": "In-browser Vuu server (VuuModule, tables, EngineDataSource) built on @heswell/vuu-table and @heswell/vuu-viewport",
   "main": "./index.js",
   "module": "./index.js",

package/src/EngineDataSource.d.ts

@@ -95,7 +95,7 @@ export declare class EngineDataSource extends EventEmitter<DataSourceEvents> imp
     get size(): number;
     get table(): import("@vuu-ui/vuu-data-types").TableSchemaTable;
     /** The table backing this dataSource */
-    get dataTable(): Table;
+    get dataTable(): Table<import("@heswell/vuu-table").Table>;
     get columnMap(): ColumnMap;
     /**
      * Flat (ungrouped) rows can be resolved at any index. Grouped rows are

package/src/Table.d.ts

@@ -4,6 +4,12 @@ import type { VuuRowDataItemType } from "@vuu-ui/vuu-protocol-types";
 import { type ColumnMap, EventEmitter } from "@vuu-ui/vuu-utils";
 import type { UpdateGenerator } from "./rowUpdates";
 export type TableRow = Array<VuuRowDataItemType | bigint>;
+export type RangeLimits = NonNullable<TableSchema["rangeLimits"]>;
+/**
+ * @internal Range limits applied when the table's schema declares none,
+ * without adding them to the (exposed) schema.
+ */
+export declare const setDefaultRangeLimits: (table: Table<EngineTable>, rangeLimits: RangeLimits) => void;
 export type TableEvents = {
     delete: (key: string) => void;
     insert: (row: TableRow) => void;
@@ -17,14 +23,30 @@ export type TableEvents = {
  *
  * Events are emitted from engine table listeners, so changes applied
  * directly to the engine table (e.g. by a JoinTable) are also observed.
+ *
+ * `E` is the type of the engine table, `JoinTable` for tables created by
+ * `createJoinTable` (see `JoinTableHandle`).
  */
-export declare class Table extends EventEmitter<TableEvents> {
+export declare class Table<E extends EngineTable = EngineTable> extends EventEmitter<TableEvents> {
     #private;
-    readonly engineTable: EngineTable;
-    constructor(schemaOrEngineTable: TableSchema | EngineTable, data?: TableRow[], dataMap?: ColumnMap, updateGenerator?: UpdateGenerator);
+    readonly engineTable: E;
+    constructor(schemaOrEngineTable: TableSchema | E, data?: TableRow[], dataMap?: ColumnMap, updateGenerator?: UpdateGenerator);
     get data(): TableRow[];
     get map(): ColumnMap;
     get schema(): TableSchema;
+    /**
+     * The range limits in effect: those of the schema if it declares any,
+     * otherwise any engine default (applied to join tables), else undefined
+     * (unlimited). Never added to `schema`.
+     */
+    get rangeLimits(): RangeLimits | undefined;
+    get destroyed(): boolean;
+    /**
+     * Release the table. For a join table this detaches the join from its
+     * source tables, so source changes no longer propagate. This table stops
+     * emitting events. Safe to call on any table, and more than once.
+     */
+    destroy(): void;
     get name(): string;
     get rowCount(): number;
     delete(key: string): void;

package/src/basket/BasketModule.d.ts

@@ -43,7 +43,7 @@ export declare class BasketModule extends VuuModule<BasketsTableName> {
         priceStrategyType: undefined;
     };
     get menuServices(): Record<BasketsTableName, RpcMenuService[] | undefined> | undefined;
-    get tables(): Record<BasketsTableName, Table>;
+    get tables(): Record<BasketsTableName, Table<import("@heswell/vuu-table").Table>>;
     get visualLinks(): {
         basketConstituent: {
             fromColumn: string;

package/src/core/module/VuuModule.d.ts

@@ -55,8 +55,9 @@ export declare abstract class VuuModule<T extends string = string> implements IV
     detachEngine(engine: LocalEngine): void;
     /**
      * Release resources (timers, providers). Called by `LocalEngine.dispose`
-     * for modules it owns. Subclasses that start timers should override,
-     * calling super.dispose().
+     * for modules it owns. Join tables published by the module are destroyed,
+     * detaching them from their source tables. Subclasses that start timers
+     * should override, calling super.dispose().
      */
     dispose(): void;
     protected abstract menus?: Record<T, VuuMenu | undefined> | undefined;
@@ -174,9 +175,9 @@ export declare abstract class VuuModule<T extends string = string> implements IV
     private addRow;
     private endEditSession;
     private applyBulkEdits;
-    protected createSessionTable(sourceTable: Table, sessionTableName: string, editSessionMode: EditSessionMode | CopyOption, dataSource: ModuleDataSource, sessionType?: SessionType): Table;
-    protected createSessionTableWithAllRows({ data, schema }: Table, _sessionTableName: string): Table;
-    protected createEmptySessionTable({ schema }: Table, sessionTableName: string, sessionType?: SessionType): Table;
-    protected createSessionTableFromSelectedRows({ data, map, schema }: Table, sessionTableName: string, dataSource: ModuleDataSource): Table;
+    protected createSessionTable(sourceTable: Table, sessionTableName: string, editSessionMode: EditSessionMode | CopyOption, dataSource: ModuleDataSource, sessionType?: SessionType): Table<import("@heswell/vuu-table").Table>;
+    protected createSessionTableWithAllRows({ data, schema }: Table, _sessionTableName: string): Table<import("@heswell/vuu-table").Table>;
+    protected createEmptySessionTable({ schema }: Table, sessionTableName: string, sessionType?: SessionType): Table<import("@heswell/vuu-table").Table>;
+    protected createSessionTableFromSelectedRows({ data, map, schema }: Table, sessionTableName: string, dataSource: ModuleDataSource): Table<import("@heswell/vuu-table").Table>;
 }
 export {};

package/src/core/table/TableContainer.d.ts

@@ -1,14 +1,19 @@
-import { type JoinType } from "@heswell/vuu-table";
+import { JoinTable, type JoinType } from "@heswell/vuu-table";
 import type { TableSchema } from "@vuu-ui/vuu-data-types";
 import { Table } from "../../Table";
 import type { VuuRowDataItemType, VuuTable } from "@vuu-ui/vuu-protocol-types";
 import type { ColumnMap } from "@vuu-ui/vuu-utils";
 import type { UpdateGenerator } from "../../rowUpdates";
+/**
+ * A Table backed by an engine `JoinTable`, as returned by `createJoinTable`.
+ * `destroy()` detaches the join from its source tables.
+ */
+export type JoinTableHandle = Table<JoinTable>;
 /**
  * Create a table. The table is not registered anywhere; it belongs to
  * whichever VuuModule returns it from `tables`.
  */
-export declare const createTable: (schema: TableSchema, data?: Array<Array<VuuRowDataItemType | bigint>>, dataMap?: ColumnMap, updateGenerator?: UpdateGenerator) => Table;
+export declare const createTable: (schema: TableSchema, data?: Array<Array<VuuRowDataItemType | bigint>>, dataMap?: ColumnMap, updateGenerator?: UpdateGenerator) => Table<import("@heswell/vuu-table").Table>;
 export interface CreateJoinTableOptions {
     /** Defaults to "inner". */
     joinType?: JoinType;
@@ -24,6 +29,9 @@ export interface CreateJoinTableOptions {
      * return in TABLE_META_RESP. Its column order is preserved; every column
      * must exist in one of the source tables, with the same serverDataType, and
      * its key must be the key of table1. Cannot be combined with `columns`.
+     * The join's `schema` is exactly this schema; if it declares no
+     * `rangeLimits`, the engine default limits are applied without being added
+     * to the schema.
      */
     schema?: TableSchema;
 }
@@ -36,26 +44,34 @@ export interface CreateJoinTableOptions {
  * The fifth argument is either a JoinType or a CreateJoinTableOptions, which
  * can also control the columns (and their order) of the join table. Where a
  * column exists in both tables, the value comes from table1.
+ *
+ * Call `destroy()` on the returned table to detach it from its source tables.
+ * Tables published by a module are destroyed when the module is disposed.
  */
-export declare const createJoinTable: (joinTable: VuuTable, table1: Table, table2: Table, joinColumn: string, joinTypeOrOptions?: JoinType | CreateJoinTableOptions) => Table;
+export declare const createJoinTable: (joinTable: VuuTable, table1: Table, table2: Table, joinColumn: string, joinTypeOrOptions?: JoinType | CreateJoinTableOptions) => JoinTableHandle;
 /**
  * Tables, keyed by `{module, table}`. Each LocalEngine owns one, populated
  * from the tables of its registered modules. Tables created through
- * `createTable` / `createJoinTable` are added to this container.
+ * `createTable` / `createJoinTable` are added to this container, and are
+ * destroyed by `clear()`.
  */
 export declare class TableContainer {
     #private;
-    createTable: (schema: TableSchema, data?: Array<Array<VuuRowDataItemType | bigint>>, dataMap?: ColumnMap, updateGenerator?: UpdateGenerator) => Table;
+    createTable: (schema: TableSchema, data?: Array<Array<VuuRowDataItemType | bigint>>, dataMap?: ColumnMap, updateGenerator?: UpdateGenerator) => Table<import("@heswell/vuu-table").Table>;
     /**
      * Create a join of two tables already in this container. Pass full
      * `{module, table}` references; a bare name is accepted only if unique.
      */
-    createJoinTable(joinTable: VuuTable, table1: VuuTable | string, table2: VuuTable | string, joinColumn: string, joinTypeOrOptions?: JoinType | CreateJoinTableOptions): Table;
+    createJoinTable(joinTable: VuuTable, table1: VuuTable | string, table2: VuuTable | string, joinColumn: string, joinTypeOrOptions?: JoinType | CreateJoinTableOptions): JoinTableHandle;
     /**
      * Add a table, keyed by `as` if given, otherwise by its schema's
      * `{module, table}`.
      */
     addTable(table: Table, as?: VuuTable): void;
+    /**
+     * Remove a table from the container. The table is not destroyed, it may
+     * still be in use elsewhere; call its `destroy()` if not.
+     */
     removeTable(table: VuuTable): boolean;
     hasTable(table: VuuTable): boolean;
     /**
@@ -66,5 +82,10 @@ export declare class TableContainer {
     getTable(table: VuuTable | string): Table;
     getTable<T>(table: VuuTable | string): T;
     get tables(): Table[];
+    /**
+     * Remove every table, destroying those created by this container's
+     * `createTable` / `createJoinTable` (detaching join tables from their
+     * sources). Tables added with `addTable` are not destroyed.
+     */
     clear(): void;
 }

package/src/index.d.ts

@@ -4,7 +4,7 @@ export * from "./core/module/VuuModule";
 export * from "./core/module/edit-hooks";
 export { type AnyVuuModule, createLocalEngine, ensureVuuModule, getDefaultEngine, LocalEngine, type LocalEngineOptions, resetDefaultEngine, } from "./core/engine/LocalEngine";
 export * from "./core/user/CurrentUser";
-export { type CreateJoinTableOptions, createJoinTable, createTable, TableContainer, } from "./core/table/TableContainer";
+export { type CreateJoinTableOptions, createJoinTable, createTable, type JoinTableHandle, TableContainer, } from "./core/table/TableContainer";
 export { tableContainer } from "./core/table/defaultTableContainer";
 export { registerDemoModules, type DemoModules } from "./demo-modules";
 export { BaseUpdateGenerator } from "./UpdateGenerator";
@@ -15,7 +15,7 @@ export * from "./simul";
 export * from "./basket";
 export * from "./module-admin";
 export * from "./user-admin";
-export { buildDataColumnMap, buildDataColumnMapFromSchema, Table, type TableEvents, } from "./Table";
+export { buildDataColumnMap, buildDataColumnMapFromSchema, type RangeLimits, Table, type TableEvents, } from "./Table";
 export * from "./test";
 export * from "./EngineDataSource";
 export * from "./ModuleDataSource";

package/src/notifications/NotificationModule.d.ts

@@ -35,6 +35,6 @@ export declare class NotificationModule extends VuuModule<NotificationsTableName
     get menuServices(): undefined;
     get schemas(): Record<"notifications", TableSchema>;
     get services(): Record<"notifications", RpcService[]>;
-    get tables(): Record<"notifications", Table>;
+    get tables(): Record<"notifications", Table<import("@heswell/vuu-table").Table>>;
     get visualLinks(): undefined;
 }

package/src/session-table-utils.d.ts

@@ -2,5 +2,5 @@ import type { VuuRowDataItemType } from "@vuu-ui/vuu-protocol-types";
 import { Table } from "./Table";
 import type { TableSchema } from "@vuu-ui/vuu-data-types";
 export declare const sessionTableRow: (row: Array<bigint | VuuRowDataItemType>, schema: TableSchema) => (bigint | VuuRowDataItemType)[];
-export declare const createSessionTableFromSelectedRows: (table: Table, selectedRowIds: string[]) => Table;
+export declare const createSessionTableFromSelectedRows: (table: Table, selectedRowIds: string[]) => Table<import("@heswell/vuu-table").Table>;
 export declare const sessionTableSchema: (schema: TableSchema) => TableSchema;

package/src/simul/SimulModule.d.ts

@@ -24,7 +24,7 @@ export declare class SimulModule extends VuuModule<SimulTableName> {
     get editServices(): undefined;
     get menuServices(): Record<SimulTableName, RpcMenuService[] | undefined> | undefined;
     get services(): Record<SimulTableName, RpcService[] | undefined> | undefined;
-    get tables(): Record<SimulTableName, Table>;
+    get tables(): Record<SimulTableName, Table<import("@heswell/vuu-table").Table>>;
     get visualLinks(): Record<SimulTableName, VuuLink[] | undefined>;
     cancelOrder: MenuServiceHandler;
     startOrders: ServiceHandler;

package/src/simul/reference-data/instruments-extended.d.ts

@@ -1 +1 @@
-export declare const createInstrumentsExtendedTable: () => import("../..").Table;
+export declare const createInstrumentsExtendedTable: () => import("../..").Table<import("@heswell/vuu-table").Table>;

package/src/simul/reference-data/instruments.d.ts

@@ -31,4 +31,4 @@ export declare const InstrumentColumnMap: {
 };
 export declare const getInstrumentsData: () => InstrumentsDataRow[];
 export declare const getRic: (defaultRic: string) => string;
-export declare const createInstrumentsTable: () => import("../..").Table;
+export declare const createInstrumentsTable: () => import("../..").Table<import("@heswell/vuu-table").Table>;

package/src/simul/reference-data/orders.d.ts

@@ -32,4 +32,4 @@ export declare const OrderColumnMap: {
     readonly trader: 8;
 };
 export declare const getOrdersData: () => OrdersDataRow[];
-export declare const createOrdersTable: () => import("../..").Table;
+export declare const createOrdersTable: () => import("../..").Table<import("@heswell/vuu-table").Table>;

package/src/test/TestModule.d.ts

@@ -10,6 +10,6 @@ export declare class TestModule extends VuuModule<TestTableName> {
     get services(): undefined;
     get menuServices(): Record<TestTableName, RpcMenuService[] | undefined> | undefined;
     get schemas(): Record<TestTableName, TableSchema>;
-    get tables(): Record<TestTableName, Table>;
+    get tables(): Record<TestTableName, Table<import("@heswell/vuu-table").Table>>;
     get visualLinks(): undefined;
 }

package/src/user-admin/UserAdminModule.d.ts

@@ -23,7 +23,7 @@ export declare class UserAdminModule extends VuuModule<UserAdminTableName> {
     get menuServices(): undefined;
     get services(): Record<UserAdminTableName, RpcService[]>;
     reconcile(): Promise<void>;
-    protected createSessionTable(sourceTable: Table, sessionTableName: string, editSessionMode: import("@vuu-ui/vuu-data-types").EditSessionMode | import("@vuu-ui/vuu-data-types").CopyOption, dataSource: import("../ModuleDataSource").ModuleDataSource, sessionType?: import("@vuu-ui/vuu-data-types").SessionType): Table;
+    protected createSessionTable(sourceTable: Table, sessionTableName: string, editSessionMode: import("@vuu-ui/vuu-data-types").EditSessionMode | import("@vuu-ui/vuu-data-types").CopyOption, dataSource: import("../ModuleDataSource").ModuleDataSource, sessionType?: import("@vuu-ui/vuu-data-types").SessionType): Table<import("@heswell/vuu-table").Table>;
     protected beforeSessionSave(sourceTable: Table, sessionTable: Table): Promise<void>;
     protected afterSessionSave(sourceTable: Table, sessionTable: Table): Promise<void>;
     private saveGroupsFromSession;