linkgress-orm 0.4.64 → 0.4.66

package/dist/query/query-builder.js

@@ -15,6 +15,7 @@ const cte_builder_1 = require("./cte-builder");
 const collection_strategy_factory_1 = require("./collection-strategy.factory");
 const union_builder_1 = require("./union-builder");
 const future_query_1 = require("./future-query");
+const mock_row_cache_1 = require("./mock-row-cache");
 const join_utils_1 = require("./join-utils");
 /**
  * Field type categories for optimized result transformation
@@ -57,6 +58,27 @@ function getRelationEntriesForSchema(schema) {
     // Fallback: build the array (for schemas that weren't built with the new TableBuilder)
     return Object.entries(schema.relations);
 }
+/**
+ * Mock-row descriptor cache for {@link ReferenceQueryBuilder.createMockTargetRow}.
+ *
+ * Building a reference mock row costs O(columns + relations) `Object.defineProperty`
+ * calls plus fresh closures per row — and deep selectors (cart → items → product →
+ * price → …) rebuild that graph from scratch on EVERY query build. All of it is
+ * deterministic in (target schema, relation alias, navigation path), so the property
+ * descriptors are built once per signature and reused: each new mock row is a bare
+ * object + one `Object.defineProperties` call with the shared descriptor map.
+ *
+ * Per-instance state (the lazy FieldRef cache and the memoized navigation rows)
+ * lives in symbol-keyed slots read by the shared getters through `this`, so sharing
+ * descriptors across rows is safe. The navigation-path arrays captured at build
+ * time are shared by content — nothing downstream mutates them (they are always
+ * spread-copied when extended).
+ */
+const MOCK_ROW_FIELD_REFS = Symbol('linkgressMockFieldRefs');
+const MOCK_ROW_NAV_CACHE = Symbol('linkgressMockNavCache');
+const navigationPathSignature = (path) => path
+    .map(step => `${step.alias}:${step.targetTable}:${(step.foreignKeys ?? []).join('+')}:${(step.matches ?? []).join('+')}:${step.isMandatory ? 1 : 0}:${step.sourceAlias ?? ''}`)
+    .join('>');
 /**
  * Performance utility: Get target schema for a relation, using cached version if available
  */
@@ -734,6 +756,39 @@ class SelectQueryBuilder {
         this.offsetValue = count;
         return this;
     }
+    /**
+     * Append a row-level lock clause to the final SELECT — `FOR UPDATE` (with the
+     * optional `SKIP LOCKED` / `NOWAIT` modifiers). The lock is taken on the rows
+     * the statement reads, making a following check+write in the SAME transaction
+     * (or a later CTE leg of a fused statement) atomic against every other
+     * `forUpdate` reader of those rows — the DB-side replacement for app-level
+     * distributed locks around read-then-write sequences (TOCTOU).
+     *
+     * Always pair with `.orderBy(...)` for a deterministic lock ORDER (lock
+     * multi-row sets in a stable order — e.g. ascending id — to avoid deadlocks).
+     *
+     * Execution paths: toList()/firstOrDefault() emit the clause; UNION builds and
+     * nested-collection CTE legs intentionally drop it (a lock on a lateral join
+     * leg is meaningless). A query used as a Subquery/CTE leg through
+     * `asSubquery()` carries it verbatim — that is the fused-conditional-INSERT
+     * pattern's lock leg.
+     *
+     * @example
+     * .orderBy(g => g.id)
+     * .forUpdate()
+     * .toList()
+     */
+    forUpdate(options) {
+        if (options?.skipLocked && options?.noWait) {
+            throw new Error('forUpdate: skipLocked and noWait are mutually exclusive');
+        }
+        this.lockClause = options?.skipLocked
+            ? 'FOR UPDATE SKIP LOCKED'
+            : options?.noWait
+                ? 'FOR UPDATE NOWAIT'
+                : 'FOR UPDATE';
+        return this;
+    }
     orderBy(selector) {
         const mockRow = this._createMockRow();
         const selectedMock = this.selector(mockRow);
@@ -3139,11 +3194,11 @@ class SelectQueryBuilder {
             joinClauses.push(collection.joinClause);
         }
         // Build the final CTE query
-        const sql = `WITH "__mutation__" AS (
-  ${mutationWithReturning}
-)
-SELECT ${selectParts.join(', ')}
-FROM "__mutation__"
+        const sql = `WITH "__mutation__" AS (
+  ${mutationWithReturning}
+)
+SELECT ${selectParts.join(', ')}
+FROM "__mutation__"
 ${joinClauses.join('\n')}`;
         return { sql, params: allParams, nestedPaths };
     }
@@ -4321,7 +4376,12 @@ ${joinClauses.join('\n')}`;
         }
         // Add DISTINCT if needed
         const distinctClause = this.isDistinct ? 'DISTINCT ' : '';
-        finalQuery += `SELECT ${distinctClause}${selectParts.join(', ')}\n${fromClause}\n${whereClause}\n${orderByClause}\n${limitClause}`.trim();
+        // Row-level lock clause (forUpdate) — emitted only on the TOP-LEVEL statement:
+        // nested-collection CTE legs run as lateral joins where a lock is meaningless
+        // (and would be a syntax error inside some leg shapes), so the flag is read
+        // ONLY here at the final assembly point.
+        const lockClause = this.lockClause ? `\n${this.lockClause}` : '';
+        finalQuery += `SELECT ${distinctClause}${selectParts.join(', ')}\n${fromClause}\n${whereClause}\n${orderByClause}\n${limitClause}${lockClause}`.trim();
         return {
             sql: finalQuery,
             params: context.allParams,
@@ -5538,120 +5598,162 @@ class ReferenceQueryBuilder {
      */
     createMockTargetRow() {
         if (this.targetTableSchema) {
-            const mock = {};
-            // Add columns - use pre-computed column name map if available
-            const columnNameMap = getColumnNameMapForSchema(this.targetTableSchema);
-            // Performance: Lazy-cache FieldRef objects
-            const fieldRefCache = {};
-            const tableAlias = this.relationName;
-            // Build a mapper lookup for columns (only when needed)
-            const columnMappers = {};
-            const columnSqlTypes = {};
-            for (const [colName, colBuilder] of Object.entries(this.targetTableSchema.columns)) {
-                const config = colBuilder.build();
-                if (config.mapper) {
-                    columnMappers[colName] = config.mapper;
-                }
-                if (config.type) {
-                    columnSqlTypes[colName] = config.type;
-                }
-            }
-            const sourceTable = this.targetTable; // Actual table name for schema lookup
-            // Collect all navigation aliases from the path leading to this reference
-            // This is needed for WHERE conditions that use multi-level navigation (e.g., task.level.name)
-            const navigationAliases = this.navigationPath.map(nav => nav.alias);
-            for (const [colName, dbColumnName] of columnNameMap) {
-                const mapper = columnMappers[colName];
-                Object.defineProperty(mock, colName, {
-                    get() {
-                        let cached = fieldRefCache[colName];
-                        if (!cached) {
-                            cached = fieldRefCache[colName] = {
-                                __fieldName: colName,
-                                __dbColumnName: dbColumnName,
-                                __tableAlias: tableAlias, // Alias for SQL generation
-                                __sourceTable: sourceTable, // Actual table name for mapper lookup
-                                __mapper: mapper, // Include mapper for toDriver transformation in conditions
-                                __sqlType: columnSqlTypes[colName], // Column SQL type — lets flag* emit width-exact mask casts
-                                __navigationAliases: navigationAliases, // All intermediate navigation aliases for JOIN resolution
-                            };
-                        }
-                        return cached;
-                    },
-                    enumerable: true,
-                    configurable: true,
-                });
+            // Descriptor-level cache — see MockRowCache's doc. Everything the descriptors close
+            // over is fully determined by (target schema object identity, relationName,
+            // sourceAlias, navigation-path content), so rows with the same signature can share
+            // one prebuilt PropertyDescriptorMap. The cross-row cache is OPT-IN via the static
+            // switch (MockRowCache.setEnabled — the host app flips it from its own config):
+            // with it off, each row gets a FRESH descriptor set (the pre-0.4.66 memory profile
+            // — nothing retained beyond the row's lifetime), while the per-row FieldRef and
+            // navigation slots below stay enabled either way (they are row-scoped).
+            const descriptors = mock_row_cache_1.MockRowCache.getOrBuild(`${this.targetTable}|${this.relationName}|${this.sourceAlias ?? ''}|${navigationPathSignature(this.navigationPath)}`, () => this.buildMockRowDescriptors());
+            const mock = {
+                [MOCK_ROW_FIELD_REFS]: {},
+                [MOCK_ROW_NAV_CACHE]: {},
+            };
+            Object.defineProperties(mock, descriptors);
+            return mock;
+        }
+        else {
+            // Fallback: use the shared nested proxy that supports deep property access
+            return createNestedFieldRefProxy(this.relationName);
+        }
+    }
+    /**
+     * Builds the shared property-descriptor map for {@link createMockTargetRow}'s cached path.
+     * The getters read per-row state through `this`-bound symbol slots, so one descriptor
+     * map serves every row of the same signature.
+     */
+    buildMockRowDescriptors() {
+        // Add columns - use pre-computed column name map if available
+        const columnNameMap = getColumnNameMapForSchema(this.targetTableSchema);
+        const tableAlias = this.relationName;
+        // Build a mapper lookup for columns (only when needed)
+        const columnMappers = {};
+        const columnSqlTypes = {};
+        for (const [colName, colBuilder] of Object.entries(this.targetTableSchema.columns)) {
+            const config = colBuilder.build();
+            if (config.mapper) {
+                columnMappers[colName] = config.mapper;
             }
-            // Build extended navigation path for nested collections
-            // Only build navigation path if we have a sourceAlias (meaning we're inside a collection's selector)
-            // If sourceAlias is empty, we're in the main query and references are joined in the FROM clause
-            let extendedNavPath = [];
-            if (this.sourceAlias) {
-                // Build the current navigation step to include in path for nested collections
-                // This represents the join from sourceAlias to this.relationName (this.targetTable)
-                const currentNavStep = {
-                    alias: this.relationName,
-                    targetTable: this.targetTable,
-                    foreignKeys: this.foreignKeys,
-                    matches: this.matches.length > 0 ? this.matches : ['id'], // Default to 'id' if not specified
-                    isMandatory: this.isMandatory,
-                    sourceAlias: this.sourceAlias,
-                };
-                extendedNavPath = [...this.navigationPath, currentNavStep];
+            if (config.type) {
+                columnSqlTypes[colName] = config.type;
             }
-            // Add navigation properties (both collections and references)
-            if (this.targetTableSchema.relations) {
-                for (const [relName, relConfig] of Object.entries(this.targetTableSchema.relations)) {
-                    // Try to get target schema from registry (preferred, has full relations) or targetTableBuilder
-                    let nestedTargetSchema;
-                    if (this.schemaRegistry) {
-                        nestedTargetSchema = this.schemaRegistry.get(relConfig.targetTable);
-                    }
-                    if (!nestedTargetSchema && relConfig.targetTableBuilder) {
-                        nestedTargetSchema = relConfig.targetTableBuilder.build();
+        }
+        const sourceTable = this.targetTable; // Actual table name for schema lookup
+        // Collect all navigation aliases from the path leading to this reference
+        // This is needed for WHERE conditions that use multi-level navigation (e.g., task.level.name)
+        const navigationAliases = this.navigationPath.map(nav => nav.alias);
+        const descriptors = {};
+        for (const [colName, dbColumnName] of columnNameMap) {
+            const mapper = columnMappers[colName];
+            descriptors[colName] = {
+                get() {
+                    const slots = this;
+                    const fieldRefCache = slots[MOCK_ROW_FIELD_REFS] ?? (slots[MOCK_ROW_FIELD_REFS] = {});
+                    let cached = fieldRefCache[colName];
+                    if (!cached) {
+                        cached = fieldRefCache[colName] = {
+                            __fieldName: colName,
+                            __dbColumnName: dbColumnName,
+                            __tableAlias: tableAlias, // Alias for SQL generation
+                            __sourceTable: sourceTable, // Actual table name for mapper lookup
+                            __mapper: mapper, // Include mapper for toDriver transformation in conditions
+                            __sqlType: columnSqlTypes[colName], // Column SQL type — lets flag* emit width-exact mask casts
+                            __navigationAliases: navigationAliases, // All intermediate navigation aliases for JOIN resolution
+                        };
                     }
-                    if (relConfig.type === 'many') {
-                        // Collection navigation
-                        // Non-enumerable to prevent Object.entries triggering getters (avoids stack overflow)
-                        Object.defineProperty(mock, relName, {
-                            get: () => {
+                    return cached;
+                },
+                enumerable: true,
+                configurable: true,
+            };
+        }
+        // Build extended navigation path for nested collections
+        // Only build navigation path if we have a sourceAlias (meaning we're inside a collection's selector)
+        // If sourceAlias is empty, we're in the main query and references are joined in the FROM clause
+        let extendedNavPath = [];
+        if (this.sourceAlias) {
+            // Build the current navigation step to include in path for nested collections
+            // This represents the join from sourceAlias to this.relationName (this.targetTable)
+            const currentNavStep = {
+                alias: this.relationName,
+                targetTable: this.targetTable,
+                foreignKeys: this.foreignKeys,
+                matches: this.matches.length > 0 ? this.matches : ['id'], // Default to 'id' if not specified
+                isMandatory: this.isMandatory,
+                sourceAlias: this.sourceAlias,
+            };
+            extendedNavPath = [...this.navigationPath, currentNavStep];
+        }
+        // Values captured at descriptor-build time — identical for every row of this
+        // signature (the registry is the process-wide schema registry; `sourceAlias`
+        // determines whether nested references track their join path).
+        const schemaRegistry = this.schemaRegistry;
+        const parentSourceAlias = this.sourceAlias;
+        // Add navigation properties (both collections and references)
+        if (this.targetTableSchema.relations) {
+            for (const [relName, relConfig] of Object.entries(this.targetTableSchema.relations)) {
+                // Try to get target schema from registry (preferred, has full relations) or targetTableBuilder
+                let nestedTargetSchema;
+                if (this.schemaRegistry) {
+                    nestedTargetSchema = this.schemaRegistry.get(relConfig.targetTable);
+                }
+                if (!nestedTargetSchema && relConfig.targetTableBuilder) {
+                    nestedTargetSchema = relConfig.targetTableBuilder.build();
+                }
+                if (relConfig.type === 'many') {
+                    // Collection navigation
+                    // Non-enumerable to prevent Object.entries triggering getters (avoids stack overflow)
+                    descriptors[relName] = {
+                        get() {
+                            const slots = this;
+                            const navCache = slots[MOCK_ROW_NAV_CACHE] ?? (slots[MOCK_ROW_NAV_CACHE] = {});
+                            // Memoize per row: selectors revisit the same navigation repeatedly
+                            // (aggregates, predicates), and each fresh visit used to rebuild the
+                            // whole sub-graph.
+                            let cached = navCache[relName];
+                            if (cached === undefined) {
                                 const fk = relConfig.foreignKey || relConfig.foreignKeys?.[0] || '';
-                                return new CollectionQueryBuilder(relName, relConfig.targetTable, fk, this.relationName, // Use alias (relationName) for correlation in lateral joins
+                                cached = navCache[relName] = new CollectionQueryBuilder(relName, relConfig.targetTable, fk, tableAlias, // Use alias (relationName) for correlation in lateral joins
                                 nestedTargetSchema, // Pass the target schema directly
-                                this.schemaRegistry, // Pass schema registry for nested resolution
+                                schemaRegistry, // Pass schema registry for nested resolution
                                 extendedNavPath, // Pass navigation path for intermediate joins (empty if main query)
                                 relConfig.foreignKeys, // Propagate composite FK / literal predicates
                                 relConfig.matches);
-                            },
-                            enumerable: false,
-                            configurable: true,
-                        });
-                    }
-                    else {
-                        // Reference navigation
-                        // Non-enumerable to prevent Object.entries triggering getters (avoids stack overflow
-                        // with circular relations like User->Posts->User)
-                        Object.defineProperty(mock, relName, {
-                            get: () => {
+                            }
+                            return cached;
+                        },
+                        enumerable: false,
+                        configurable: true,
+                    };
+                }
+                else {
+                    // Reference navigation
+                    // Non-enumerable to prevent Object.entries triggering getters (avoids stack overflow
+                    // with circular relations like User->Posts->User)
+                    descriptors[relName] = {
+                        get() {
+                            const slots = this;
+                            const navCache = slots[MOCK_ROW_NAV_CACHE] ?? (slots[MOCK_ROW_NAV_CACHE] = {});
+                            let cached = navCache[relName];
+                            if (cached === undefined) {
                                 const refBuilder = new ReferenceQueryBuilder(relName, relConfig.targetTable, relConfig.foreignKeys || [relConfig.foreignKey || ''], relConfig.matches || [], relConfig.isMandatory ?? false, nestedTargetSchema, // Pass the target schema directly
-                                this.schemaRegistry, // Pass schema registry for nested resolution
+                                schemaRegistry, // Pass schema registry for nested resolution
                                 extendedNavPath, // Pass navigation path for nested collections
-                                this.sourceAlias ? this.relationName : '' // Only set source if tracking path
+                                parentSourceAlias ? tableAlias : '' // Only set source if tracking path
                                 );
-                                return refBuilder.createMockTargetRow();
-                            },
-                            enumerable: false,
-                            configurable: true,
-                        });
-                    }
+                                cached = navCache[relName] = refBuilder.createMockTargetRow();
+                            }
+                            return cached;
+                        },
+                        enumerable: false,
+                        configurable: true,
+                    };
                 }
             }
-            return mock;
-        }
-        else {
-            // Fallback: use the shared nested proxy that supports deep property access
-            return createNestedFieldRefProxy(this.relationName);
         }
+        return descriptors;
     }
 }
 exports.ReferenceQueryBuilder = ReferenceQueryBuilder;