@proteinjs/db 1.28.1 → 1.29.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proteinjs/db",
-  "version": "1.28.1",
+  "version": "1.29.1",
   "main": "./dist/generated/index.js",
   "types": "./dist/generated/index.d.ts",
   "exports": {
@@ -65,5 +65,6 @@
     "jest": "29.7.0",
     "ts-jest": "29.1.1",
     "typescript": "5.2.2"
-  }
+  },
+  "gitHead": "c945fb49ea7db32eb5bf51630eff23f5df06560c"
 }

package/src/Db.ts

@@ -29,6 +29,7 @@ import {
 import { isInstanceOf } from '@proteinjs/util';
 import { Reference } from './reference/Reference';
 import { ReferenceArray } from './reference/ReferenceArray';
+import { ReferenceCache } from './reference/ReferenceCache';
 import { ArrayMembershipUpdate, applyArrayMembershipOps } from './reference/ArrayMembershipOps';
 import { PreservedPath, overlayPreservedPaths } from './UpdatePreserving';
 
@@ -541,15 +542,25 @@ export class Db<R extends Record = Record> implements DbService<R> {
     return records;
   }
 
+  /**
+   * Batch-load the result set's references: one IN query per referenced table, grouped
+   * across rows and reference-array members, instead of a `get()` per reference (a 30-row
+   * window over references was 30 serialized point reads — each through its own default-
+   * driver Db). The batch queries ride THIS instance — driver, table resolution, ambient
+   * transaction, and authority — so a preload behaves like part of the query that carried
+   * it. References already loaded, or serveable from `ReferenceCache` (`Reference.get`
+   * consults it per read, deliberately never stamping `_object`), are left untouched.
+   */
   private async preloadReferences(records: any[], queryOptions?: QueryOptions<any>) {
     const { preloadReferences } = queryOptions || {};
     if (!preloadReferences?.enabled) {
       return;
     }
 
+    const pendingReferences: Reference<any>[] = [];
+    const pendingReferenceArrays: ReferenceArray<any>[] = [];
     for (const record of records) {
-      const fields = Object.entries(record);
-      for (const [fieldPropertyName, fieldValue] of fields) {
+      for (const [fieldPropertyName, fieldValue] of Object.entries(record)) {
         if (preloadReferences.excludeColumns?.includes(fieldPropertyName)) {
           continue;
         }
@@ -558,11 +569,62 @@ export class Db<R extends Record = Record> implements DbService<R> {
           continue;
         }
 
-        if (isInstanceOf(fieldValue, Reference) || isInstanceOf(fieldValue, ReferenceArray)) {
-          await (fieldValue as Reference<any> | ReferenceArray<any>).get();
+        if (isInstanceOf(fieldValue, Reference)) {
+          const reference = fieldValue as Reference<any>;
+          if (!reference._object && reference._id && !ReferenceCache.get().get(reference._table, reference._id)) {
+            pendingReferences.push(reference);
+          }
+        } else if (isInstanceOf(fieldValue, ReferenceArray)) {
+          const referenceArray = fieldValue as ReferenceArray<any>;
+          if (!referenceArray._objects) {
+            pendingReferenceArrays.push(referenceArray);
+          }
         }
       }
     }
+
+    const idsByTable = new Map<string, Set<string>>();
+    const addIds = (tableName: string, ids: string[]) => {
+      if (ids.length === 0) {
+        return;
+      }
+      let tableIds = idsByTable.get(tableName);
+      if (!tableIds) {
+        tableIds = new Set();
+        idsByTable.set(tableName, tableIds);
+      }
+      for (const id of ids) {
+        tableIds.add(id);
+      }
+    };
+    for (const reference of pendingReferences) {
+      addIds(reference._table, [reference._id as string]);
+    }
+    for (const referenceArray of pendingReferenceArrays) {
+      addIds(referenceArray._table, referenceArray._ids);
+    }
+
+    const rowsByTable = new Map<string, Map<string, any>>();
+    await Promise.all(
+      Array.from(idsByTable.entries()).map(async ([tableName, tableIds]) => {
+        const table = this.getTable(tableName);
+        const qb = new QueryBuilderFactory()
+          .getQueryBuilder(table)
+          .condition({ field: 'id', operator: 'IN', value: Array.from(tableIds) });
+        const rows = await this.query(table, qb);
+        rowsByTable.set(tableName, new Map(rows.map((row) => [row.id, row])));
+      })
+    );
+
+    for (const reference of pendingReferences) {
+      reference._object = rowsByTable.get(reference._table)?.get(reference._id as string);
+    }
+    for (const referenceArray of pendingReferenceArrays) {
+      const rowsById = rowsByTable.get(referenceArray._table);
+      referenceArray._objects = referenceArray._ids
+        .map((id) => rowsById?.get(id))
+        .filter((row): row is any => row !== undefined);
+    }
   }
 
   async getRowCount<T extends R>(table: Table<T>, query?: Query<T>): Promise<number> {

package/src/Table.ts

@@ -79,7 +79,12 @@ export abstract class Table<T extends Record> implements Loadable, CustomSeriali
   public __serializerId = TableSerializerId;
   abstract name: string;
   abstract columns: Columns<T>;
-  public indexes: { columns: (keyof T)[]; name?: string }[] = [];
+  /**
+   * `unique: true` creates a UNIQUE index (composite uniqueness lives here; single-column
+   * uniqueness can also use `ColumnOptions.unique`). Name unique indexes with a `_unique`
+   * suffix — schema metadata classifies unique indexes by that suffix.
+   */
+  public indexes: { columns: (keyof T)[]; name?: string; unique?: boolean }[] = [];
   /** When records are deleted, delete records having references pointing to deleted records */
   public cascadeDeleteReferences: () => { table: string; referenceColumn: string }[] = () => [];
   /**

package/src/schema/TableManager.ts

@@ -246,7 +246,7 @@ export class TableManager {
         const serializedColumns = JSON.stringify(columns);
         currentIndexMap[serializedColumns] = true;
         if (!existingIndexMap[serializedColumns]) {
-          indexesToCreate.push({ name: index.name, columns });
+          indexesToCreate.push({ name: index.name, columns, unique: index.unique });
         }
       }
     }

package/test/index.ts

@@ -4,6 +4,7 @@ export * from './reusable/ColumnTypesTests';
 export * from './reusable/DynamicReferenceColumnTests';
 export * from './reusable/TransactionTests';
 export * from './reusable/CascadeDeleteTests';
+export * from './reusable/PreloadReferencesTests';
 
 export * from './util/testUser';
 

package/test/reusable/PreloadReferencesTests.ts

@@ -0,0 +1,126 @@
+import { Db, DbDriver, QueryBuilderFactory, Reference, ReferenceArray, Table } from '@proteinjs/db';
+import { DbTestEnvironment } from '../util/DbTestEnvironment';
+import { dynamicReferenceTestTables } from '../util/tables/dynamicReferenceColumnTestTables';
+import { cascadeDeleteTestTables } from '../util/tables/cascadeDeleteTestTables';
+
+/**
+ * Preload behavior tests: `preloadReferences` must hydrate every reference in the result set
+ * with ONE query per referenced table — batching is the point of the option (a 30-row window
+ * preloaded per-row is 30 serialized point reads). The assertions count driver round trips,
+ * the outcome that keeps preload cheap, and then verify hydration is complete (no further
+ * round trips to read every referenced object).
+ */
+export const preloadReferencesTests = (driver: DbDriver, dropTable: (table: Table<any>) => Promise<void>) => {
+  return () => {
+    // Counting proxy: every runQuery through the driver increments `queryCount`. Db reads
+    // nothing else off the driver during query execution that matters here; everything not
+    // overridden delegates to the real driver via the prototype chain.
+    let queryCount = 0;
+    const countingDriver: DbDriver = Object.create(driver, {
+      runQuery: {
+        value: (...args: unknown[]) => {
+          queryCount++;
+          return (driver.runQuery as (...a: unknown[]) => Promise<unknown>).apply(driver, args);
+        },
+      },
+    });
+    const db = new Db(countingDriver);
+    const testEnv = new DbTestEnvironment(driver, dropTable);
+
+    beforeAll(async () => await testEnv.beforeAll(), 30000);
+    afterAll(async () => await testEnv.afterAll(), 30000);
+
+    test('preload hydrates dynamic references with one query per referenced table', async () => {
+      const engineerA = await db.insert(dynamicReferenceTestTables.Engineer, {
+        name: 'preload-batch engineer A',
+        yearsOfExperience: 3,
+      });
+      const engineerB = await db.insert(dynamicReferenceTestTables.Engineer, {
+        name: 'preload-batch engineer B',
+        yearsOfExperience: 7,
+      });
+      const designer = await db.insert(dynamicReferenceTestTables.Designer, {
+        name: 'preload-batch designer',
+        specialization: 'Motion',
+      });
+      const employees = [engineerA, engineerB, designer];
+      const employeeTables = [
+        dynamicReferenceTestTables.Engineer.name,
+        dynamicReferenceTestTables.Engineer.name,
+        dynamicReferenceTestTables.Designer.name,
+      ];
+      for (let i = 0; i < employees.length; i++) {
+        await db.insert(dynamicReferenceTestTables.ProjectAssignment, {
+          projectName: `preload-batch project ${i}`,
+          employeeRef: new Reference(employeeTables[i], employees[i].id),
+          startDate: '2026-01-01',
+        });
+      }
+
+      const qb = new QueryBuilderFactory()
+        .getQueryBuilder(dynamicReferenceTestTables.ProjectAssignment)
+        .condition({ field: 'projectName', operator: 'LIKE', value: 'preload-batch project %' });
+      queryCount = 0;
+      const assignments = await db.query(dynamicReferenceTestTables.ProjectAssignment, qb, {
+        preloadReferences: { enabled: true, includeColumns: ['employeeRef'] },
+      });
+      const queriesDuringPreload = queryCount;
+
+      expect(assignments.length).toBe(3);
+      // Hydration must be complete: every referenced object readable with ZERO further round trips.
+      queryCount = 0;
+      const names = (await Promise.all(assignments.map((assignment) => assignment.employeeRef!.get())))
+        .map((employee) => employee!.name)
+        .sort();
+      expect(names).toEqual(['preload-batch designer', 'preload-batch engineer A', 'preload-batch engineer B']);
+      expect(queryCount).toBe(0);
+      // One round trip for the assignments window, then one per referenced table
+      // (engineers, designers) — never one per row.
+      expect(queriesDuringPreload).toBe(3);
+    });
+
+    test('preload hydrates reference arrays with one query per referenced table', async () => {
+      const memberIds: string[][] = [];
+      for (let g = 0; g < 2; g++) {
+        const ids: string[] = [];
+        for (let m = 0; m < 2; m++) {
+          const member = await db.insert(cascadeDeleteTestTables.MemberArr, {
+            name: `preload-arr member ${g}.${m}`,
+          });
+          ids.push(member.id);
+        }
+        memberIds.push(ids);
+      }
+      for (let g = 0; g < 2; g++) {
+        await db.insert(cascadeDeleteTestTables.GroupArr, {
+          groupName: `preload-arr group ${g}`,
+          memberRefs: new ReferenceArray(cascadeDeleteTestTables.MemberArr.name, memberIds[g]),
+        });
+      }
+
+      const qb = new QueryBuilderFactory()
+        .getQueryBuilder(cascadeDeleteTestTables.GroupArr)
+        .condition({ field: 'groupName', operator: 'LIKE', value: 'preload-arr group %' })
+        .sort([{ field: 'groupName', desc: false }]);
+      queryCount = 0;
+      const groups = await db.query(cascadeDeleteTestTables.GroupArr, qb, {
+        preloadReferences: { enabled: true },
+      });
+      const queriesDuringPreload = queryCount;
+
+      expect(groups.length).toBe(2);
+      // Hydration must be complete AND ordered per each array's _ids, with zero further round trips.
+      queryCount = 0;
+      for (let g = 0; g < 2; g++) {
+        const members = await groups[g].memberRefs!.get();
+        expect(members.map((member) => member.name)).toEqual([
+          `preload-arr member ${g}.0`,
+          `preload-arr member ${g}.1`,
+        ]);
+      }
+      expect(queryCount).toBe(0);
+      // One round trip for the groups, one for ALL members across both arrays.
+      expect(queriesDuringPreload).toBe(2);
+    });
+  };
+};