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

package/legacy.js

@@ -0,0 +1,8 @@
+import { getDefaultEngine, UserAdminModule, SimulatedNotificationsModule, registerDemoModules, ModuleAdminModule } from "./index.js";
+const engine = getDefaultEngine();
+const { simulModule: simulModule, basketModule: basketModule, testModule: testModule } = registerDemoModules(engine);
+const moduleAdminModule = engine.register(new ModuleAdminModule());
+const userAdminModule = engine.register(new UserAdminModule());
+const notificationsModule = engine.register(SimulatedNotificationsModule());
+export { AllowAllPermissionFilter, ArrayProxy, BaseUpdateGenerator, BasketModule, DUPLICATE_KEY, DefaultColumnGenerator, DefaultRowGenerator, DenyAllPermissionFilter, DismissNotificationRpcHandler, EngineDataSource, LocalDataSourceProvider, LocalEngine, MODULE_ADMIN_INITIAL_SNAPSHOT, MODULE_ADMIN_MODULE_NAME, MODULE_ADMIN_TABLE_SCHEMAS, ModuleAdminModule, ModuleDataSource, NotificationModule, NotificationsSchema, PermissionFilter, SAVE_FAILED, SAVE_NOT_PERMITTED, STALE_UPDATE, SimulModule, SimulatedNotificationsModule, SimulatedNotificationsProvider, Table, TableContainer, TestModule, TickingArrayDataSource, USER_ADMIN_INITIAL_SNAPSHOT, UserAdminModule, VUU_SYSTEM_COLUMNS, VuuModule, basketSchemas, buildDataColumnMap, buildDataColumnMapFromSchema, createDataSourceProvider, createJoinTable, createLocalEngine, createLocalVuuServer, createTable, defaultApplySessionSave, defaultCanEditSource, defaultGenerators, defaultGetStaleColumns, defaultIsEditableColumn, ensureVuuModule, formatMessage, getAllSchemas, getColumnAndRowGenerator, getCurrentUser, getDefaultEngine, getSchema, isBasketTable, isSimulTable, isSystemColumn, makeSuggestions, populateArray, projectModuleAdminSnapshot, projectUserAdminSnapshot, reconcileModuleAdminTables, reconcileUserAdminTables, registerDemoModules, resetDefaultEngine, schemas, setCurrentUser, simulSchemas, tableContainer, testSchemas, toColumn, toRange } from "./index.js";
+export { basketModule, moduleAdminModule, notificationsModule, simulModule, testModule, userAdminModule };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heswell/vuu-data-engine-local",
-  "version": "2.1.0",
+  "version": "3.0.0",
   "description": "In-browser Vuu server (VuuModule, tables, EngineDataSource) built on @heswell/vuu-table and @heswell/vuu-viewport",
   "main": "./index.js",
   "module": "./index.js",
@@ -9,6 +9,10 @@
     ".": {
       "types": "./src/index.d.ts",
       "import": "./index.js"
+    },
+    "./legacy": {
+      "types": "./src/legacy.d.ts",
+      "import": "./legacy.js"
     }
   },
   "type": "module",
@@ -33,5 +37,7 @@
     "@vuu-ui/vuu-utils": "^4.0.0-alpha.20",
     "react": "^19.2.3"
   },
-  "sideEffects": false
+  "sideEffects": [
+    "./legacy.js"
+  ]
 }

package/src/EngineDataSource.d.ts

@@ -1,9 +1,18 @@
 import { type DataEngine, type LinkFilter, type RowPredicate, type ViewportEngine } from "@heswell/vuu-viewport";
 import type { DataSourceBase, DataSourceConstructorProps, DataSourceEvents, DataSourceFilter, DataSourceRowWithBigint, DataSourceStatus, DataSourceSubscribeCallback, DataSourceSubscribeProps, TableSchema, WithBaseFilter, WithFullConfig } from "@vuu-ui/vuu-data-types";
 import type { Filter } from "@vuu-ui/vuu-filter-types";
-import type { LinkDescriptorWithLabel, SelectRequest, VuuAggregation, VuuGroupBy, VuuMenu, VuuRowDataItemType, VuuRpcMenuRequest, VuuRpcMenuResponse, VuuRpcServiceRequest, RpcResultError, RpcResultSuccess, VuuSort } from "@vuu-ui/vuu-protocol-types";
+import type { LinkDescriptorWithLabel, SelectRequest, VuuAggregation, VuuGroupBy, VuuMenu, VuuRange, VuuRowDataItemType, VuuRpcMenuRequest, VuuRpcMenuResponse, VuuRpcServiceRequest, RpcResultError, RpcResultSuccess, VuuSort } from "@vuu-ui/vuu-protocol-types";
 import type { ColumnDescriptor } from "@vuu-ui/vuu-table-types";
 import { type ColumnMap, EventEmitter, Range } from "@vuu-ui/vuu-utils";
+/**
+ * Accept either a vuu-utils `Range` or a plain `{from, to}` (VuuRange),
+ * which is converted to a `Range`.
+ */
+/** `range` may be a plain `{from, to}`. */
+export type EngineDataSourceSubscribeProps = Omit<DataSourceSubscribeProps, "range"> & {
+    range?: Range | VuuRange;
+};
+export declare const toRange: (range: VuuRange | Range) => Range;
 import { Table } from "./Table";
 export interface EngineDataSourceConstructorProps extends Omit<DataSourceConstructorProps, "bufferSize" | "table"> {
     /**
@@ -38,7 +47,7 @@ export declare class EngineDataSource extends EventEmitter<DataSourceEvents> imp
     sendSizeUpdateToClient(): void;
     /** Send every row in the current range, irrespective of what was sent before */
     sendRowsToClient(): void;
-    subscribe({ viewport, columns, aggregations, baseFilterSpec, range, sort, groupBy, filterSpec, }: DataSourceSubscribeProps, callback: DataSourceSubscribeCallback): Promise<void>;
+    subscribe({ viewport, columns, aggregations, baseFilterSpec, range, sort, groupBy, filterSpec, }: EngineDataSourceSubscribeProps, callback: DataSourceSubscribeCallback): Promise<void>;
     unsubscribe(): void;
     suspend(): void;
     resume(callback?: DataSourceSubscribeCallback): void;
@@ -46,10 +55,11 @@ export declare class EngineDataSource extends EventEmitter<DataSourceEvents> imp
     enable(): void;
     get status(): DataSourceStatus;
     get range(): Range;
+    /** A plain `{from, to}` is also accepted at runtime. */
     set range(range: Range);
     get maxRangeEnd(): number;
     get pageSize(): number;
-    protected setRange(range: Range, forceFullRefresh?: boolean): void;
+    protected setRange(vuuRange: Range | VuuRange, forceFullRefresh?: boolean): void;
     get config(): WithBaseFilter<WithFullConfig>;
     set config(config: WithBaseFilter<WithFullConfig>);
     get aggregations(): VuuAggregation[];

package/src/ModuleDataSource.d.ts

@@ -1,7 +1,7 @@
-import type { DataSourceBase, DataSource, DataSourceRowWithBigint, DataSourceSubscribeCallback, DataSourceSubscribeProps, DataSourceVisualLinkCreatedMessage, DeleteRowMode, CopyOption, EditSessionMode, SessionDataSourceOverrides, SessionType } from "@vuu-ui/vuu-data-types";
+import type { DataSourceBase, DataSource, DataSourceRowWithBigint, DataSourceSubscribeCallback, DataSourceVisualLinkCreatedMessage, DeleteRowMode, CopyOption, EditSessionMode, SessionDataSourceOverrides, SessionType } from "@vuu-ui/vuu-data-types";
 import type { LinkDescriptorWithLabel, RpcResult, RpcResultError, RpcResultSuccess, VuuCreateVisualLink, VuuRemoveVisualLink, VuuRowDataItemType, VuuRpcMenuRequest, VuuRpcMenuResponse, VuuRpcServiceRequest } from "@vuu-ui/vuu-protocol-types";
 import type { IVuuModule, RpcMenuService, RpcService } from "./core/module/VuuModule";
-import { EngineDataSource, type EngineDataSourceConstructorProps } from "./EngineDataSource";
+import { EngineDataSource, type EngineDataSourceConstructorProps, type EngineDataSourceSubscribeProps } from "./EngineDataSource";
 export type VisualLinkHandler = (message: VuuCreateVisualLink | VuuRemoveVisualLink) => Promise<DataSourceVisualLinkCreatedMessage | undefined>;
 export interface ModuleDataSourceConstructorProps extends EngineDataSourceConstructorProps {
     getVisualLinks?: (tableName: string) => LinkDescriptorWithLabel[] | undefined;
@@ -18,7 +18,7 @@ export interface ModuleDataSourceConstructorProps extends EngineDataSourceConstr
 export declare class ModuleDataSource extends EngineDataSource {
     #private;
     constructor({ getVisualLinks, rpcServices, rpcMenuServices, session, visualLink, visualLinkService, vuuModule, ...engineDataSourceProps }: ModuleDataSourceConstructorProps);
-    subscribe(subscribeProps: DataSourceSubscribeProps, callback: DataSourceSubscribeCallback): Promise<void>;
+    subscribe(subscribeProps: EngineDataSourceSubscribeProps, callback: DataSourceSubscribeCallback): Promise<void>;
     set links(links: LinkDescriptorWithLabel[] | undefined);
     get links(): LinkDescriptorWithLabel[] | undefined;
     isSessionDataSourceOf(dataSource: DataSource): boolean;

package/src/UpdateGenerator.d.ts

@@ -7,10 +7,22 @@ export declare class BaseUpdateGenerator implements UpdateGenerator {
     private updating;
     private timer;
     private tickingColumns;
+    private enabled;
+    /**
+     * @param autoStart default true, start ticking as soon as a table and
+     * range are set. With false, ticking starts only when `start` is called.
+     */
     constructor(tickingColumns: {
         [key: string]: number;
+    }, { autoStart }?: {
+        autoStart?: boolean;
     });
     setRange(range: VuuRange): void;
+    get isUpdating(): boolean;
+    /** Start (or resume) ticking. */
+    start(): void;
+    /** Stop ticking, clearing any pending timer. */
+    stop(): void;
     setTable(table: Table): void;
     private startUpdating;
     private stopUpdating;

package/src/basket/BasketModule.d.ts

@@ -2,6 +2,15 @@ import type { VuuMenu } from "@vuu-ui/vuu-protocol-types";
 import { type RpcMenuService, type ServiceHandler, VuuModule } from "../core/module/VuuModule";
 import { type BasketsTableName } from "./basket-schemas";
 import type { Table } from "../Table";
+import { type PricesTable } from "../simul/reference-data/prices";
+export type BasketModuleOptions = {
+    /**
+     * The prices table joined with basket constituents, typically the SIMUL
+     * module's prices (`simulModule.prices`). If not provided, the module
+     * creates its own prices table.
+     */
+    prices?: PricesTable;
+};
 export declare const createBasketTradingRow: (basketId: string, basketName: string, side?: string, status?: string) => (string | number)[];
 /**
  * This is an example of how we might extend the built-in VuuModule to
@@ -10,7 +19,9 @@ export declare const createBasketTradingRow: (basketId: string, basketName: stri
  */
 export declare class BasketModule extends VuuModule<BasketsTableName> {
     #private;
-    constructor();
+    constructor({ prices }?: BasketModuleOptions);
+    protected beforeCreateDataSource(): void;
+    dispose(): void;
     get menus(): Record<BasketsTableName, VuuMenu | undefined>;
     get schemas(): Readonly<Record<BasketsTableName, Readonly<import("@vuu-ui/vuu-data-types").TableSchema>>>;
     get services(): {
@@ -52,4 +63,3 @@ export declare class BasketModule extends VuuModule<BasketsTableName> {
     private takeOffMarket;
     private addConstituent;
 }
-export declare const basketModule: BasketModule;

package/src/basket/index.d.ts

@@ -1,2 +1,2 @@
 export { type BasketsTableName, schemas as basketSchemas, isBasketTable, } from "./basket-schemas";
-export { basketModule } from "./BasketModule";
+export { BasketModule, type BasketModuleOptions } from "./BasketModule";

package/src/core/engine/LocalEngine.d.ts

@@ -0,0 +1,62 @@
+import type { DataSourceConfig, SessionDataSourceOverrides, TableSchema } from "@vuu-ui/vuu-data-types";
+import type { VuuTable } from "@vuu-ui/vuu-protocol-types";
+import type { VuuModule } from "../module/VuuModule";
+import { TableContainer } from "../table/TableContainer";
+export type AnyVuuModule = VuuModule<any>;
+export interface LocalEngineOptions {
+    /** Modules to register on creation. */
+    modules?: AnyVuuModule[];
+}
+/**
+ * An in-browser Vuu server: a set of VuuModules and the tables they publish,
+ * keyed by `{module, table}`. Engines are fully isolated from each other, so
+ * two engines (or two modules in one engine) can use the same table names.
+ *
+ * The engine has no React or DOM dependency. Use `createDataSourceProvider`
+ * or `createLocalVuuServer` to expose it to a React app.
+ */
+export declare class LocalEngine {
+    #private;
+    readonly tableContainer: TableContainer;
+    constructor({ modules }?: LocalEngineOptions);
+    /**
+     * Register a module. A module already registered under the same name is
+     * replaced (and unregistered). Its tables are added to `tableContainer`,
+     * keyed by `{module: module.name, table}`.
+     */
+    register<M extends AnyVuuModule>(module: M): M;
+    /** Remove a module and its tables. The module is not disposed. */
+    unregister(moduleName: string): boolean;
+    hasModule(moduleName: string): boolean;
+    getModule<M extends AnyVuuModule = AnyVuuModule>(moduleName: string): M;
+    get modules(): AnyVuuModule[];
+    get moduleNames(): string[];
+    /** Every table published by the registered modules. */
+    getTableList(): VuuTable[];
+    getTableSchema({ module, table }: VuuTable): TableSchema | undefined;
+    createDataSource({ module, table }: VuuTable, viewport?: string, config?: DataSourceConfig & {
+        session?: SessionDataSourceOverrides;
+    }): import("@vuu-ui/vuu-data-types").DataSourceBase<import("@vuu-ui/vuu-data-types").DataSourceRowWithBigint>;
+    get disposed(): boolean;
+    /**
+     * Unregister every module and dispose those owned by this engine (that is,
+     * first registered here), stopping any timers they started.
+     */
+    dispose(): void;
+}
+/** Create an isolated local engine, optionally registering modules. */
+export declare const createLocalEngine: (options?: LocalEngineOptions) => LocalEngine;
+/**
+ * The shared engine behind the deprecated globals (`tableContainer`,
+ * `LocalDataSourceProvider`, `ensureVuuModule`) and the `/legacy` entry.
+ * Created on first use.
+ */
+export declare const getDefaultEngine: () => LocalEngine;
+/** Dispose the default engine; the next `getDefaultEngine()` creates a new one. */
+export declare const resetDefaultEngine: () => void;
+/**
+ * Register a module with the default engine, unless a module with that name
+ * is already registered there.
+ * @deprecated create an engine with `createLocalEngine({ modules })`.
+ */
+export declare const ensureVuuModule: <T extends AnyVuuModule>(module: T) => T;

package/src/core/filter/PermissionFilter.d.ts

@@ -1,7 +1,7 @@
 import type { VuuRowDataItemType } from "@vuu-ui/vuu-protocol-types";
 import type { VuuModuleUser } from "../user/CurrentUser";
 import type { ColumnMap } from "@vuu-ui/vuu-utils";
-import type tableContainer from "../table/TableContainer";
+import type { TableContainer } from "../table/TableContainer";
 export type TableRow = Array<bigint | VuuRowDataItemType>;
 export type RowPredicate = (row: TableRow) => boolean;
 /**
@@ -29,7 +29,7 @@ export interface PermissionViewport {
     id: string;
     user: VuuModuleUser;
 }
-export type TableContainer = typeof tableContainer;
+export type { TableContainer };
 /**
  * Creates the PermissionFilter for a viewport. Configured per table on a VuuModule.
  */

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

@@ -1,9 +1,12 @@
 import type { DataSourceBase, DataSourceConfig, DataSourceRowWithBigint, DataSourceSubscribedMessage, DataSourceVisualLinkCreatedMessage, EditSessionMode, CopyOption, SessionDataSourceOverrides, SessionType, TableSchema } from "@vuu-ui/vuu-data-types";
 import type { VuuMenu, VuuLink, LinkDescriptorWithLabel, VuuRpcMenuResponse, VuuCreateVisualLink, VuuRemoveVisualLink, VuuRpcServiceRequest, RpcResultSuccess, RpcResultError, VuuRpcMenuRequest } from "@vuu-ui/vuu-protocol-types";
-import { Table } from "../../Table";
+import { Table, type TableRow } from "../../Table";
 import { ModuleDataSource } from "../../ModuleDataSource";
 import { type PermissionFunction } from "../filter/PermissionFilter";
 import { type VuuModuleUser } from "../user/CurrentUser";
+import { TableContainer } from "../table/TableContainer";
+import type { LocalEngine } from "../engine/LocalEngine";
+import { type CanSaveSessionResult, type CellEdit, type EditContext, type EditHooks, type PreparedSessionSave, type SessionRowChange, type SessionSaveResult } from "./edit-hooks";
 export interface IVuuModule<T extends string = string> {
     createDataSource: (tableName: T, viewport?: string, config?: DataSourceConfig & {
         session?: SessionDataSourceOverrides;
@@ -39,16 +42,67 @@ type Subscription = {
 };
 export declare abstract class VuuModule<T extends string = string> implements IVuuModule<T> {
     #private;
+    /**
+     * Modules are not registered anywhere on construction. Register them with
+     * a LocalEngine (`createLocalEngine({ modules })`).
+     */
     constructor(name: string, { sessionTableMessageColumn }?: VuuModuleOptions);
+    /** The engine this module was first registered with, if any. */
+    get engine(): LocalEngine | undefined;
+    /** @internal called by LocalEngine.register */
+    attachEngine(engine: LocalEngine): void;
+    /** @internal called by LocalEngine.unregister */
+    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().
+     */
+    dispose(): void;
     protected abstract menus?: Record<T, VuuMenu | undefined> | undefined;
     protected abstract schemas: Record<T, Readonly<TableSchema>>;
     protected abstract tables: Record<T, Table>;
     protected abstract menuServices?: Record<T, RpcMenuService[] | undefined> | undefined;
+    /**
+     * Per table services. A service with the same rpcName as a built-in
+     * service (e.g. endEditSession, editCell) replaces it for that table,
+     * including for edit sessions created from the table.
+     */
     protected abstract services?: Record<T, RpcService[] | undefined> | undefined;
+    /**
+     * Services available on every table of this module. Like table services,
+     * these replace built-in services with the same rpcName. Table services
+     * take precedence.
+     */
+    protected moduleServices?: RpcService[];
+    /**
+     * Per table edit hooks. These take precedence over the module-wide
+     * protected hook methods (isEditableColumn, validateCellEdit,
+     * getStaleColumns, canSaveSession, applySessionSave, canEditSource).
+     */
+    protected editHooks?: Partial<Record<T, EditHooks>>;
     protected abstract visualLinks?: Record<T, VuuLink[] | undefined>;
     protected get includeDefaultServices(): boolean;
+    /**
+     * Called on save, before changes are prepared. Rows given a message
+     * (vuuMsg) here are treated as handled and excluded from the save.
+     * @deprecated implement applySessionSave (per table via editHooks).
+     */
     protected beforeSessionSave(_sourceTable: Table, _sessionTable: Table): Promise<void>;
+    /** Called after a successful save, before the session is reset. */
     protected afterSessionSave(_sourceTable: Table, _sessionTable: Table): Promise<void>;
+    /** See {@link EditHooks.canEditSource}. Default true. */
+    protected canEditSource(_column: string, _ctx: EditContext): boolean;
+    /** See {@link EditHooks.isEditableColumn}. */
+    protected isEditableColumn(table: Table, column: string, _ctx: EditContext): boolean;
+    /** See {@link EditHooks.validateCellEdit}. */
+    protected validateCellEdit(_edit: CellEdit): string | undefined | void;
+    /** See {@link EditHooks.getStaleColumns}. */
+    protected getStaleColumns(sourceTable: Table, sourceRow: TableRow, change: SessionRowChange): string[];
+    /** See {@link EditHooks.canSaveSession}. Default true. */
+    protected canSaveSession(_prepared: PreparedSessionSave, _ctx: EditContext): CanSaveSessionResult | Promise<CanSaveSessionResult>;
+    /** See {@link EditHooks.applySessionSave}. */
+    protected applySessionSave(sessionTable: Table, prepared: PreparedSessionSave, _ctx: EditContext): SessionSaveResult | Promise<SessionSaveResult>;
     /**
      * Optional, per table. Restricts the rows visible to each viewport, based on
      * the viewport (and the user who owns it).
@@ -61,6 +115,14 @@ export declare abstract class VuuModule<T extends string = string> implements IV
     protected beforeCreateDataSource?(tableName: T): void;
     getTableSchema(tableName: string): Record<T, Readonly<TableSchema>>[T];
     getTableList(): string[];
+    /** The tables published by this module, keyed by table name. */
+    getTables(): Record<T, Table>;
+    getTable(tableName: T): Table;
+    /**
+     * Tables visible to permission functions: the engine's tables, or this
+     * module's own tables if it is not registered with an engine.
+     */
+    protected get tableContainer(): TableContainer;
     protected handlePostSubscribeActivities: ({ clientViewportId, tableSchema, }: DataSourceSubscribedMessage) => void;
     protected unregisterViewport: (viewportId: string) => void;
     get name(): string;
@@ -73,6 +135,11 @@ export declare abstract class VuuModule<T extends string = string> implements IV
         session?: SessionDataSourceOverrides;
     }) => DataSourceBase<DataSourceRowWithBigint>;
     private createPermissionPredicate;
+    /**
+     * The RPC services for a table: built-in services, overridden by
+     * moduleServices, overridden by table services (matched by rpcName).
+     * For a session table, the services of its source table.
+     */
     getServices(tableName: T): RpcService[];
     getMenuServices(tableName: T): RpcMenuService[];
     protected get sessionTableMap(): SessionTableMap;

package/src/core/module/edit-hooks.d.ts

@@ -0,0 +1,135 @@
+import type { RpcResult, VuuColumnDataType, VuuRowDataItemType } from "@vuu-ui/vuu-protocol-types";
+import type { Table, TableRow } from "../../Table";
+import type { VuuModuleUser } from "../user/CurrentUser";
+/**
+ * Engine-maintained columns. Not editable through editCell by default.
+ */
+export declare const VUU_SYSTEM_COLUMNS: ReadonlySet<string>;
+export declare const isSystemColumn: (column: string) => boolean;
+/**
+ * endEditSession error when a source row changed after it was copied into
+ * the session. vuu-ui's VuuDataSource matches this string exactly (and
+ * throws StaleUpdateError), do not change it.
+ */
+export declare const STALE_UPDATE = "stale update";
+export declare const DUPLICATE_KEY = "duplicate key";
+export declare const SAVE_NOT_PERMITTED = "endEditSession: save not permitted";
+export declare const SAVE_FAILED = "endEditSession: save failed";
+/**
+ * Passed to every edit hook.
+ */
+export interface EditContext {
+    moduleName: string;
+    /** The source table name (never the session table name). */
+    tableName: string;
+    /** The viewport that made the request. */
+    viewportId: string;
+    /** The user that owns the viewport. */
+    user: VuuModuleUser;
+    /** The session table, when the request targets an edit session. */
+    sessionTable?: Table;
+    sessionTableName?: string;
+}
+export type SessionTableAction = "addRow" | "editCell" | "deleteRow";
+export type SessionRowChange = {
+    action: SessionTableAction;
+    /**
+     * Changed source columns and their new values. For addRow, every source
+     * column. Empty for deleteRow.
+     */
+    cellUpdates: Record<string, VuuRowDataItemType>;
+    key: string;
+    /** The session row, projected onto the source table's columns. */
+    row: TableRow;
+    /** The session row, as stored in the session table. */
+    sessionRow: TableRow;
+    /**
+     * Copy of the source row taken when it was copied into the session (or
+     * when a change was undone). Used to detect concurrent source changes.
+     */
+    sourceSnapshot?: TableRow;
+};
+export type PreparedSessionChange = SessionRowChange & {
+    /** The current source row (absent for addRow). */
+    sourceRow?: TableRow;
+};
+export type PreparedSessionSave = {
+    sourceTable: Table;
+    sessionTable: Table;
+    changes: PreparedSessionChange[];
+};
+/** true permits the save, false or a string (the reason) refuses it. */
+export type CanSaveSessionResult = boolean | string;
+/**
+ * undefined, true or a SUCCESS_RESULT mean the save succeeded. false or an
+ * ERROR_RESULT (as does a thrown error) mean it failed; the session is left
+ * open so the user can retry or cancel.
+ */
+export type SessionSaveResult = void | boolean | RpcResult;
+/** A cell edit, passed to `validateCellEdit`. */
+export type CellEdit = {
+    column: string;
+    ctx: EditContext;
+    dataType: VuuColumnDataType | undefined;
+    key: string;
+    /** the row after the edit */
+    newRow: TableRow;
+    /** the row before the edit */
+    row: TableRow;
+    /** the table being edited, the session table unless editing the source directly */
+    table: Table;
+    value: VuuRowDataItemType;
+};
+/**
+ * Edit and session-save hooks. Implement them as protected methods of a
+ * VuuModule (applying to every table), or per table via
+ * `VuuModule.editHooks`, which take precedence.
+ */
+export interface EditHooks {
+    /**
+     * Opt in to editCell on a viewport that is NOT using a session table, i.e.
+     * edits written directly to the source table. Default true (unlike
+     * vuu-server) for backward compatibility.
+     */
+    canEditSource?: (column: string, ctx: EditContext) => boolean;
+    /**
+     * Whether a column may be edited through editCell. Default: any column
+     * except the key and the system columns.
+     */
+    isEditableColumn?: (table: Table, column: string, ctx: EditContext) => boolean;
+    /** Return an error message to refuse a cell edit. */
+    validateCellEdit?: (edit: CellEdit) => string | undefined | void;
+    /**
+     * Names of the source columns that changed since the row was copied into
+     * the session. A non-empty result makes the save fail with "stale update".
+     */
+    getStaleColumns?: (sourceTable: Table, sourceRow: TableRow, change: SessionRowChange) => string[];
+    /**
+     * Authorise a save, after changes are prepared (and found not stale),
+     * before applySessionSave. Return false or a reason to refuse.
+     */
+    canSaveSession?: (prepared: PreparedSessionSave, ctx: EditContext) => CanSaveSessionResult | Promise<CanSaveSessionResult>;
+    /**
+     * Apply prepared changes. Default {@link defaultApplySessionSave}, an
+     * atomic write to the source table. Override to route changes elsewhere
+     * (e.g. to an order service); call `defaultApplySessionSave` for any
+     * changes that should still be written to the source table.
+     */
+    applySessionSave?: (sessionTable: Table, prepared: PreparedSessionSave, ctx: EditContext) => SessionSaveResult | Promise<SessionSaveResult>;
+}
+export declare const defaultCanEditSource: () => boolean;
+export declare const defaultIsEditableColumn: (table: Table, column: string) => boolean;
+/**
+ * Compares the current source row with the snapshot taken when the row was
+ * copied into the session. For editCell, only the columns edited in the
+ * session are compared (other columns, e.g. ticking prices, are not written
+ * by the save so cannot conflict). For deleteRow, every column is compared.
+ * Without a snapshot (e.g. a row added to an empty session), nothing is
+ * reported as stale.
+ */
+export declare const defaultGetStaleColumns: (sourceTable: Table, sourceRow: TableRow, { action, cellUpdates, sourceSnapshot }: SessionRowChange) => string[];
+/**
+ * Writes prepared changes to the source table. Atomic: if any change
+ * throws, changes already applied are rolled back and the error rethrown.
+ */
+export declare const defaultApplySessionSave: (_sessionTable: Table, { sourceTable, changes, }: Pick<PreparedSessionSave, "sourceTable" | "changes">) => SessionSaveResult;

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

@@ -3,19 +3,43 @@ 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";
-declare class TableContainer {
+/**
+ * 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;
+/**
+ * Create a materialized (inner) join of two tables, backed by an engine
+ * JoinTable, maintained incrementally as either source changes.
+ */
+export declare const createJoinTable: (joinTable: VuuTable, table1: Table, table2: Table, joinColumn: string) => Table;
+/**
+ * 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.
+ */
+export declare class TableContainer {
     #private;
-    private constructor();
-    static get instance(): TableContainer;
     createTable: (schema: TableSchema, data?: Array<Array<VuuRowDataItemType | bigint>>, dataMap?: ColumnMap, updateGenerator?: UpdateGenerator) => Table;
     /**
-     * Create a materialized (inner) join of two existing tables, backed by an
-     * engine JoinTable, maintained incrementally as either source changes.
-     * Both source tables must already have been created.
+     * 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, { table: t1 }: VuuTable, { table: t2 }: VuuTable, joinColumn: string): Table;
-    addTable(table: Table): void;
-    getTable<T = Table>(tableName: string): NonNullable<T>;
+    createJoinTable(joinTable: VuuTable, table1: VuuTable | string, table2: VuuTable | string, joinColumn: string): Table;
+    /**
+     * Add a table, keyed by `as` if given, otherwise by its schema's
+     * `{module, table}`.
+     */
+    addTable(table: Table, as?: VuuTable): void;
+    removeTable(table: VuuTable): boolean;
+    hasTable(table: VuuTable): boolean;
+    /**
+     * Resolve a table by `{module, table}`. A bare table name is accepted for
+     * backward compatibility, but only resolves if exactly one module has a
+     * table with that name.
+     */
+    getTable(table: VuuTable | string): Table;
+    getTable<T>(table: VuuTable | string): T;
+    get tables(): Table[];
+    clear(): void;
 }
-declare const _default: TableContainer;
-export default _default;

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

@@ -0,0 +1,6 @@
+import type { TableContainer } from "./TableContainer";
+/**
+ * @deprecated The default engine's table container, resolved lazily on each
+ * access. Use `engine.tableContainer` of an engine you create.
+ */
+export declare const tableContainer: TableContainer;

package/src/data-utils.d.ts

@@ -5,3 +5,10 @@ export declare const nextRandomDouble: PriceGenerator;
 export declare const initBidAsk: (priceMaxDelta: number, nextRandomDouble: PriceGenerator) => number[];
 export declare const generateNextBidAsk: (bid: number, ask: number, spreadMultipler: number, priceMaxDelta: number, nextRandomDouble: PriceGenerator) => number[];
 export declare const withNanoMs: (ts: number, nanos?: number) => bigint;
+/**
+ * Copy rows, so tables created from shared reference data do not share
+ * (and mutate) the same row arrays.
+ */
+export declare const cloneRows: <R extends unknown[]>(rows: readonly R[]) => R[];
+/** Memoise a zero-arg factory. */
+export declare const lazy: <V>(factory: () => V) => () => V;

package/src/demo-modules.d.ts

@@ -0,0 +1,18 @@
+import { BasketModule } from "./basket/BasketModule";
+import { type LocalEngine } from "./core/engine/LocalEngine";
+import { SimulModule } from "./simul/SimulModule";
+import { TestModule } from "./test/TestModule";
+export type DemoModules = {
+    simulModule: SimulModule;
+    basketModule: BasketModule;
+    testModule: TestModule;
+};
+/**
+ * Create new SIMUL, BASKET and TEST demo modules and register them with an
+ * engine (by default, the default engine used by LocalDataSourceProvider).
+ * BASKET shares SIMUL's prices table. Prices tick only once a dataSource is
+ * created; `engine.dispose()` stops all timers.
+ *
+ * Nothing is created or registered until this is called.
+ */
+export declare const registerDemoModules: (engine?: LocalEngine) => DemoModules;

package/src/index.d.ts

@@ -1,10 +1,15 @@
 export * from "./ArrayProxy";
 export * from "./core/filter/PermissionFilter";
 export * from "./core/module/VuuModule";
-export { ensureVuuModule } from "./core/module/ModuleContainer";
+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 { default as tableContainer } from "./core/table/TableContainer";
+export { createJoinTable, createTable, TableContainer, } from "./core/table/TableContainer";
+export { tableContainer } from "./core/table/defaultTableContainer";
+export { registerDemoModules, type DemoModules } from "./demo-modules";
+export { BaseUpdateGenerator } from "./UpdateGenerator";
 export * from "./local-datasource-provider/LocalDatasourceProvider";
+export { createDataSourceProvider } from "./local-datasource-provider/createDataSourceProvider";
 export * from "./makeSuggestions";
 export * from "./notifications";
 export * from "./schemas";

package/src/legacy.d.ts

@@ -0,0 +1,11 @@
+import { ModuleAdminModule } from "./module-admin/ModuleAdminModule";
+import { UserAdminModule } from "./user-admin/UserAdminModule";
+export * from "./index";
+/** @deprecated */
+export declare const simulModule: import("./simul").SimulModule, basketModule: import("./basket").BasketModule, testModule: import("./test").TestModule;
+/** @deprecated */
+export declare const moduleAdminModule: ModuleAdminModule;
+/** @deprecated */
+export declare const userAdminModule: UserAdminModule;
+/** @deprecated */
+export declare const notificationsModule: import("./notifications").NotificationModule;