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

package/91.js

@@ -85,24 +85,15 @@ const DEFAULT_RANGE_LIMITS = {
 };
 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 createJoinTable = (joinTable, table1, table2, joinColumn, joinTypeOrOptions = "inner")=>{
+    const { joinType = "inner", columns, schema } = "string" == typeof joinTypeOrOptions ? {
+        joinType: joinTypeOrOptions
+    } : joinTypeOrOptions;
     const engineJoinTable = new JoinTable({
-        schema: combinedSchema,
+        schema: buildJoinSchema(joinTable, table1.schema, table2.schema, {
+            columns,
+            schema
+        }),
         baseTable: table1.engineTable,
         joinTable: table2.engineTable,
         leftColumn: joinColumn,
@@ -111,6 +102,49 @@ const createJoinTable = (joinTable, table1, table2, joinColumn, joinType = "inne
     });
     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)=>{
@@ -118,8 +152,8 @@ class TableContainer {
         this.addTable(table);
         return table;
     };
-    createJoinTable(joinTable, table1, table2, joinColumn, joinType = "inner") {
-        const newTable = createJoinTable(joinTable, this.getTable(table1), this.getTable(table2), joinColumn, joinType);
+    createJoinTable(joinTable, table1, table2, joinColumn, joinTypeOrOptions = "inner") {
+        const newTable = createJoinTable(joinTable, this.getTable(table1), this.getTable(table2), joinColumn, joinTypeOrOptions);
         this.addTable(newTable);
         return newTable;
     }

package/README.md

@@ -33,8 +33,9 @@ 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. The main entry needs no DOM, so it runs in plain Node or Bun. The
-React bindings (`createDataSourceProvider`, `createLocalVuuServer`,
+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.
 
@@ -151,6 +152,29 @@ changes. Pass `"leftOuter"` to keep every `table1` row. For a row with no match,
 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

package/index.js

@@ -147,12 +147,12 @@ class RowKeys {
         return key;
     }
 }
-const toRange = (range)=>"function" == typeof range.equals && void 0 !== range.withBuffer ? range : Range(range.from, range.to);
-const { KEY: KEY } = metadataKeys;
 const nextFrame = (callback)=>{
-    if ("function" == typeof globalThis.requestAnimationFrame) globalThis.requestAnimationFrame(callback);
+    if ("function" == typeof globalThis.requestAnimationFrame) globalThis.requestAnimationFrame(()=>callback());
     else globalThis.setTimeout(callback, 0);
 };
+const toRange = (range)=>"function" == typeof range.equals && void 0 !== range.withBuffer ? range : Range(range.from, range.to);
+const { KEY: KEY } = metadataKeys;
 const buildTableSchema = (columns, keyColumn)=>({
         columns: columns.map(toSchemaColumn),
         key: keyColumn ?? columns[0].name,
@@ -1228,7 +1228,7 @@ class VuuModule {
     handlePostSubscribeActivities = ({ clientViewportId, tableSchema })=>{
         const visualLinks = this.getVisualLinks(tableSchema.table.table);
         const { dataSource } = this.getSubscriptionByViewport(clientViewportId);
-        requestAnimationFrame(()=>{
+        nextFrame(()=>{
             dataSource.links = visualLinks;
         });
         if (this.visualLinks && dataSource.tableSchema) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heswell/vuu-data-engine-local",
-  "version": "4.0.0",
+  "version": "4.1.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/core/table/TableContainer.d.ts

@@ -9,13 +9,35 @@ import type { UpdateGenerator } from "../../rowUpdates";
  * whichever VuuModule returns it from `tables`.
  */
 export declare const createTable: (schema: TableSchema, data?: Array<Array<VuuRowDataItemType | bigint>>, dataMap?: ColumnMap, updateGenerator?: UpdateGenerator) => Table;
+export interface CreateJoinTableOptions {
+    /** Defaults to "inner". */
+    joinType?: JoinType;
+    /**
+     * Ordered column names of the join table, possibly a subset of the columns
+     * of the two source tables. Must include the key column of table1. Types
+     * are taken from the source tables. Defaults to every column of both
+     * tables, in alphabetical order.
+     */
+    columns?: readonly string[];
+    /**
+     * Declared schema of the join table, e.g. the schema a Vuu server would
+     * 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`.
+     */
+    schema?: TableSchema;
+}
 /**
  * Create a materialized join of two tables, backed by an engine JoinTable,
  * maintained incrementally as either source changes. `joinType` defaults to
  * "inner" (only rows with a match in table2). With "leftOuter" every table1
  * row is present and unmatched table2 columns are null, as in vuu-server.
+ *
+ * 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.
  */
-export declare const createJoinTable: (joinTable: VuuTable, table1: Table, table2: Table, joinColumn: string, joinType?: JoinType) => Table;
+export declare const createJoinTable: (joinTable: VuuTable, table1: Table, table2: Table, joinColumn: string, joinTypeOrOptions?: JoinType | CreateJoinTableOptions) => Table;
 /**
  * Tables, keyed by `{module, table}`. Each LocalEngine owns one, populated
  * from the tables of its registered modules. Tables created through
@@ -28,7 +50,7 @@ export declare class TableContainer {
      * 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, joinType?: JoinType): Table;
+    createJoinTable(joinTable: VuuTable, table1: VuuTable | string, table2: VuuTable | string, joinColumn: string, joinTypeOrOptions?: JoinType | CreateJoinTableOptions): Table;
     /**
      * Add a table, keyed by `as` if given, otherwise by its schema's
      * `{module, table}`.

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 { createJoinTable, createTable, TableContainer, } from "./core/table/TableContainer";
+export { type CreateJoinTableOptions, createJoinTable, createTable, TableContainer, } from "./core/table/TableContainer";
 export { tableContainer } from "./core/table/defaultTableContainer";
 export { registerDemoModules, type DemoModules } from "./demo-modules";
 export { BaseUpdateGenerator } from "./UpdateGenerator";

package/src/nextFrame.d.ts

@@ -0,0 +1 @@
+export declare const nextFrame: (callback: () => void) => void;