joist-core 2.3.0-next.31 → 2.3.0-next.32

package/build/EntityManager.d.ts

@@ -29,6 +29,7 @@ import { PreloadPlugin } from "./plugins/PreloadPlugin";
 import { ReactionsManager } from "./ReactionsManager";
 import { Collection } from "./relations/Collection";
 import { lazyColumnLoadOperation } from "./relations/LazyField";
+import { RowData } from "./RowData";
 import { OptsOf, OrderOf } from "./typeMap";
 import { MaybePromise } from "./utils";
 /**
@@ -167,8 +168,16 @@ export declare class EntityManager<C = unknown, Entity extends EntityW = EntityW
     }): Promise<Loaded<T, H>[]>;
     /** Runs the post-parse find pipeline: plugins mutate the logical AST, then Joist optimizes/prunes before SQL. */
     private executeFind;
+    /** Like {@link executeFind}, but returns a {@link RowData}; see {@link executePreparedFindRowData}. */
+    private executeFindRowData;
     /** Executes a query that has already had find hooks and optimizations applied. */
     private executePreparedFind;
+    /**
+     * Like {@link executePreparedFind}, but returns a {@link RowData}: lazy wire rows when the
+     * driver has `lazyRows` enabled, else classic POJO rows wrapped in a `PojoRowData` — so
+     * loaders can hydrate from one shape without caring which the driver provides.
+     */
+    private executePreparedFindRowData;
     /**
      * Runs pre-SQL find hooks and optimizations against a parsed query.
      *
@@ -547,6 +556,28 @@ export declare class EntityManager<C = unknown, Entity extends EntityW = EntityW
     hydrate<T extends EntityW>(type: MaybeAbstractEntityConstructor<T>, rows: readonly any[], options?: {
         overwriteExisting?: boolean;
     }): T[];
+    /**
+     * Hydrates a query's `RowData`, running any sidecar reads, and always `finalize`s the result.
+     *
+     * This is the internal API for Joist's find/load loaders: `sidecars` is where reads of
+     * non-entity columns (preload aggregates, `_tags`, found-id checks) belong — they must run
+     * before `finalize`, because compaction drops unretained rows — and the `try/finally`
+     * guarantees a failed hydration or sidecar read still releases the result's unretained
+     * buffers instead of pinning them.
+     */
+    private hydrateAndFinalize;
+    /**
+     * Like {@link hydrate}, but reads rows from a {@link RowData}, i.e. a driver-produced
+     * lazy query result, instead of an array of POJO rows.
+     *
+     * This is an internal API used by Joist's own find loaders (usually via
+     * {@link hydrateAndFinalize}); rows whose entities are kept (newly created or
+     * overwrite-refreshed) are `retain`-ed on the `RowData` so the caller can later `finalize`
+     * (trim/compact) the result.
+     */
+    hydrateFromRowData<T extends EntityW>(type: MaybeAbstractEntityConstructor<T>, rowData: RowData, options?: {
+        overwriteExisting?: boolean;
+    }): T[];
     /**
      * Mark an entity as needing to be flushed regardless of its state.
      *

package/build/EntityManager.js

@@ -54,6 +54,7 @@ const AsyncProperty_1 = require("./relations/AsyncProperty");
 const hasAsyncMethod_1 = require("./relations/hasAsyncMethod");
 const LazyField_1 = require("./relations/LazyField");
 const RecursiveCollection_1 = require("./relations/RecursiveCollection");
+const RowData_1 = require("./RowData");
 const scopes_1 = require("./scopes");
 const Todo_1 = require("./Todo");
 const trusted_1 = require("./trusted");
@@ -296,6 +297,11 @@ class EntityManager {
         const { checkLimit, findSettings } = this.prepareFind(meta, operation, parsed, settings);
         return this.executePreparedFind(meta, operation, parsed, findSettings, checkLimit);
     }
+    /** Like {@link executeFind}, but returns a {@link RowData}; see {@link executePreparedFindRowData}. */
+    async executeFindRowData(meta, operation, parsed, settings) {
+        const { checkLimit, findSettings } = this.prepareFind(meta, operation, parsed, settings);
+        return this.executePreparedFindRowData(meta, operation, parsed, findSettings, checkLimit);
+    }
     /** Executes a query that has already had find hooks and optimizations applied. */
     async executePreparedFind(meta, operation, parsed, findSettings, checkLimit) {
         const { pluginManager } = getEmInternalApi(this);
@@ -305,9 +311,33 @@ class EntityManager {
         if (shouldCheck && rows.length >= this.entityLimit) {
             throw new Error(`Query returned more than ${this.entityLimit} entityLimit rows`);
         }
-        pluginManager.afterFind(meta, operation, rows);
+        if (pluginManager.hasHook("afterFind")) {
+            pluginManager.afterFind(meta, operation, new RowData_1.PojoRowData(rows));
+        }
         return rows;
     }
+    /**
+     * Like {@link executePreparedFind}, but returns a {@link RowData}: lazy wire rows when the
+     * driver has `lazyRows` enabled, else classic POJO rows wrapped in a `PojoRowData` — so
+     * loaders can hydrate from one shape without caring which the driver provides.
+     */
+    async executePreparedFindRowData(meta, operation, parsed, findSettings, checkLimit) {
+        const { executeFindRowData } = this.driver;
+        if (executeFindRowData === undefined) {
+            return new RowData_1.PojoRowData(await this.executePreparedFind(meta, operation, parsed, findSettings, checkLimit));
+        }
+        const { pluginManager } = getEmInternalApi(this);
+        const rowData = await executeFindRowData.call(this.driver, this, parsed, findSettings);
+        // Check by default unless explicitly disabled or the caller removed the LIMIT via `limit: undefined`
+        const shouldCheck = checkLimit ?? !("limit" in findSettings && findSettings.limit === undefined);
+        if (shouldCheck && rowData.rowCount >= this.entityLimit) {
+            throw new Error(`Query returned more than ${this.entityLimit} entityLimit rows`);
+        }
+        // The hook receives the lazy RowData view directly, so observe-only hooks (i.e. metrics
+        // reading `rowCount`) never materialize cells; hooks call `toRows()` if they want POJOs
+        pluginManager.afterFind(meta, operation, rowData);
+        return rowData;
+    }
     /**
      * Runs pre-SQL find hooks and optimizations against a parsed query.
      *
@@ -1415,22 +1445,55 @@ class EntityManager {
      * the WIP entity state.
      */
     hydrate(type, rows, options) {
+        return this.hydrateFromRowData(type, new RowData_1.PojoRowData(rows), options);
+    }
+    /**
+     * Hydrates a query's `RowData`, running any sidecar reads, and always `finalize`s the result.
+     *
+     * This is the internal API for Joist's find/load loaders: `sidecars` is where reads of
+     * non-entity columns (preload aggregates, `_tags`, found-id checks) belong — they must run
+     * before `finalize`, because compaction drops unretained rows — and the `try/finally`
+     * guarantees a failed hydration or sidecar read still releases the result's unretained
+     * buffers instead of pinning them.
+     */
+    hydrateAndFinalize(type, rowData, opts) {
+        try {
+            const entities = this.hydrateFromRowData(type, rowData, opts);
+            opts?.sidecars?.(entities);
+            return entities;
+        }
+        finally {
+            rowData.finalize?.();
+        }
+    }
+    /**
+     * Like {@link hydrate}, but reads rows from a {@link RowData}, i.e. a driver-produced
+     * lazy query result, instead of an array of POJO rows.
+     *
+     * This is an internal API used by Joist's own find loaders (usually via
+     * {@link hydrateAndFinalize}); rows whose entities are kept (newly created or
+     * overwrite-refreshed) are `retain`-ed on the `RowData` so the caller can later `finalize`
+     * (trim/compact) the result.
+     */
+    hydrateFromRowData(type, rowData, options) {
         const maybeBaseMeta = (0, index_1.getMetadata)(type);
         const overwriteExisting = options?.overwriteExisting === true;
-        let i = 0;
-        const entities = new Array(rows.length);
-        for (const row of rows) {
-            const id = row["id"];
+        const count = rowData.rowCount;
+        const entities = new Array(count);
+        for (let i = 0; i < count; i++) {
+            const id = rowData.get(i, "id");
             const taggedId = id === undefined || id === null ? (0, utils_1.fail)("No id column was available") : (0, index_1.keyToTaggedId)(maybeBaseMeta, id);
             // See if this is already in our UoW
             let entity = this.findExistingInstance(taggedId);
             if (!entity) {
                 // Look for __class from the driver telling us which subtype to instantiate
-                const meta = findConcreteMeta(maybeBaseMeta, row);
+                const meta = findConcreteMeta(maybeBaseMeta, rowData, i);
                 // Pass id as a hint that we're in hydrate mode
                 entity = (0, newEntity_1.newEntity)(this, (0, index_1.asConcreteCstr)(meta.cstr), false);
                 const instanceData = (0, BaseEntity_1.getInstanceData)(entity);
-                instanceData.row = row;
+                instanceData.rowData = rowData;
+                instanceData.rowIndex = i;
+                rowData.retain?.(i);
                 // Seed the id to share the identity-map key string and skip the id serde on first read
                 instanceData.data["id"] = taggedId;
                 this.#doRegister(entity, taggedId, meta, true);
@@ -1440,7 +1503,9 @@ class EntityManager {
                 // `EntityManager.refresh` is telling us to explicitly load the latest data.
                 // First swap out the old row with the new row
                 const instanceData = (0, BaseEntity_1.getInstanceData)(entity);
-                instanceData.row = row;
+                instanceData.rowData = rowData;
+                instanceData.rowIndex = i;
+                rowData.retain?.(i);
                 // And then only refresh the data keys that have already been serde-d from rows
                 // (this keeps us from deserializing data out of rows that we don't need).
                 const { data } = instanceData;
@@ -1457,7 +1522,7 @@ class EntityManager {
                             if (fieldName === "id")
                                 continue;
                             const serde = allFields[fieldName].serde ?? (0, utils_1.fail)(`Missing serde for ${fieldName}`);
-                            serde.setOnEntity(data, row);
+                            serde.setOnEntityFromRowData(data, rowData, i);
                         }
                     }
                     else {
@@ -1465,7 +1530,7 @@ class EntityManager {
                             if (fieldName === "id")
                                 continue;
                             const serde = allFields[fieldName].serde ?? (0, utils_1.fail)(`Missing serde for ${fieldName}`);
-                            serde.setOnEntity(data, row);
+                            serde.setOnEntityFromRowData(data, rowData, i);
                             // Make the field look not-dirty
                             if (changedFields.includes(fieldName)) {
                                 instanceData.markFieldClean(fieldName);
@@ -1474,7 +1539,7 @@ class EntityManager {
                     }
                 }
             }
-            entities[i++] = entity;
+            entities[i] = entity;
         }
         return entities;
     }
@@ -2357,22 +2422,28 @@ function getNow() {
     return now;
 }
 /** Given a `row` from the db, resolves the CTI/STI subtype, if applicable. */
-function findConcreteMeta(maybeBaseMeta, row) {
-    // Common case of no CTI or STI inheritance
-    if (!row.__class && maybeBaseMeta.inheritanceType !== "sti") {
+function findConcreteMeta(maybeBaseMeta, rowData, rowIndex) {
+    // Common case of no CTI or STI inheritance; only probe __class for CTI metas so that
+    // lazy/columnar stores don't pay a missing-column lookup per row for regular entities
+    if (maybeBaseMeta.inheritanceType === undefined) {
+        return maybeBaseMeta;
+    }
+    const __class = rowData.get(rowIndex, "__class");
+    if (!__class && maybeBaseMeta.inheritanceType !== "sti") {
         return maybeBaseMeta;
     }
-    if (row.__class) {
-        if (row.__class === "_" && maybeBaseMeta.ctiAbstract) {
-            throw new Error(`${maybeBaseMeta.type} ${(0, index_1.tagId)(maybeBaseMeta, row.id)} must be instantiated via a subtype`);
+    if (__class) {
+        if (__class === "_" && maybeBaseMeta.ctiAbstract) {
+            const id = rowData.get(rowIndex, "id");
+            throw new Error(`${maybeBaseMeta.type} ${(0, index_1.tagId)(maybeBaseMeta, id)} must be instantiated via a subtype`);
         }
         // Look for the CTI __class from the driver telling us which subtype to instantiate
-        return maybeBaseMeta.subTypesByType.get(row.__class) ?? maybeBaseMeta;
+        return maybeBaseMeta.subTypesByType.get(__class) ?? maybeBaseMeta;
     }
     else if (maybeBaseMeta.inheritanceType === "sti") {
         // Look for the STI discriminator value
         const baseMeta = (0, index_1.getBaseMeta)(maybeBaseMeta);
-        const value = row[baseMeta.stiDiscriminatorColumnName];
+        const value = rowData.get(rowIndex, baseMeta.stiDiscriminatorColumnName);
         return baseMeta.subTypesByStiValue.get(value) ?? baseMeta;
     }
     else {
@@ -2461,7 +2532,7 @@ const fieldMap = {};
 // Generates what a row from the db would look like for a given entity
 function createRowFromEntityData(e, opts = {}) {
     const { preferOriginalData = true } = opts;
-    const { row: oldRow, data, originalData } = e.__data;
+    const { rowData, rowIndex, data, originalData } = e.__data;
     const __class = e.constructor.name;
     const { metadata: meta } = e.__data;
     if (!fieldMap[__class]) {
@@ -2486,8 +2557,8 @@ function createRowFromEntityData(e, opts = {}) {
                 // reflect what would come from the db if we queried it right now, so use originalData when present
                 column.rowValue(preferOriginalData && field.fieldName in originalData ? originalData : data)
             : // `data` is lazy and isn't set until it's accessed, so if the field isn't present there, then we should
-                // be safe to pull the raw data out of `row`
-                oldRow[column.columnName];
+                // be safe to pull the raw data out of the as-loaded RowData
+                rowData.get(rowIndex, column.columnName);
         row[column.columnName] = value ?? null;
     }
     return row;