velocious 1.0.430 → 1.0.432

package/src/database/query/preloader/has-many.js

@@ -0,0 +1,316 @@
+// @ts-check
+
+import ensureModelClassInitialized from "./ensure-model-class-initialized.js"
+import PreloaderSelection from "./selection.js"
+import restArgsError from "../../../utils/rest-args-error.js"
+
+export default class VelociousDatabaseQueryPreloaderHasMany {
+  /**
+   * Runs constructor.
+   * @param {object} args - Options object.
+   * @param {import("../../record/index.js").default[]} args.models - Model instances.
+   * @param {import("../../record/relationships/has-many.js").default} args.relationship - Relationship.
+   * @param {PreloaderSelection} [args.selection] - Column selection and idempotency rules.
+   */
+  constructor({models, relationship, selection, ...restArgs}) {
+    restArgsError(restArgs)
+
+    this.models = models
+    this.relationship = relationship
+    this.selection = selection || new PreloaderSelection()
+  }
+
+  /**
+   * Runs run.
+   * @returns {Promise<import("../../record/index.js").default[]>} - Loaded target models.
+   */
+  async run() {
+    if (this.relationship.through) {
+      return await this._runThrough()
+    }
+
+    return await this._runDirect()
+  }
+
+  /**
+   * Partitions `this.models` into those already satisfied by the current
+   * selection (skip) and those that still need loading. Satisfied models'
+   * already-loaded targets are collected so nested preloads keep working.
+   * @param {typeof import("../../record/index.js").default} targetModelClass - Target model class.
+   * @param {string[]} mappingColumns - Columns required for mapping (foreign key).
+   * @returns {{modelsToLoad: import("../../record/index.js").default[], satisfiedTargets: import("../../record/index.js").default[]}} - The partition.
+   */
+  _partition(targetModelClass, mappingColumns) {
+    const relationshipName = this.relationship.getRelationshipName()
+    /**
+     * Models to load.
+      @type {import("../../record/index.js").default[]} */
+    const modelsToLoad = []
+    /**
+     * Satisfied targets.
+      @type {import("../../record/index.js").default[]} */
+    const satisfiedTargets = []
+
+    for (const model of this.models) {
+      const instanceRelationship = model.getRelationshipByName(relationshipName)
+
+      if (this.selection.isSatisfied({instanceRelationship, targetModelClass, mappingColumns})) {
+        const loaded = instanceRelationship.getLoadedOrUndefined()
+
+        if (Array.isArray(loaded)) satisfiedTargets.push(...loaded)
+      } else {
+        modelsToLoad.push(model)
+      }
+    }
+
+    return {modelsToLoad, satisfiedTargets}
+  }
+
+  /**
+   * Preload through a join table (e.g. hasMany("invoiceGroups", {through: "invoiceGroupLinks"})).
+   * @returns {Promise<import("../../record/index.js").default[]>} - Loaded target models.
+   */
+  async _runThrough() {
+    const primaryKey = this.relationship.getPrimaryKey()
+
+    if (!primaryKey) {
+      throw new Error(`${this.relationship.getModelClass().name}#${this.relationship.getRelationshipName()} doesn't have a primary key`)
+    }
+
+    const throughRelationshipName = /**
+                                     * Narrows the runtime value to the documented type.
+                                      @type {string} */ (this.relationship.through)
+    const parentModelClass = this.relationship.getModelClass()
+    const throughRelationship = parentModelClass.getRelationshipByName(throughRelationshipName)
+    const throughModelClass = throughRelationship.getTargetModelClass()
+
+    if (!throughModelClass) throw new Error(`Through relationship ${throughRelationshipName} has no target model class`)
+
+    const targetModelClass = this.relationship.getTargetModelClass()
+
+    if (!targetModelClass) throw new Error("No target model class could be gotten from relationship")
+
+    const targetForeignKey = this.relationship.getForeignKey()
+    const {modelsToLoad, satisfiedTargets} = this._partition(targetModelClass, [targetForeignKey])
+
+    if (modelsToLoad.length == 0) return satisfiedTargets
+
+    const configuration = this.relationship.getConfiguration()
+
+    await ensureModelClassInitialized(throughModelClass, configuration)
+    await ensureModelClassInitialized(targetModelClass, configuration)
+
+    const throughForeignKey = throughRelationship.getForeignKey()
+
+    /**
+     * Models primary key values.
+      @type {Array<number | string>} */
+    const modelsPrimaryKeyValues = []
+
+    /**
+     * Models by primary key value.
+      @type {Record<number | string, Array<import("../../record/index.js").default>>} */
+    const modelsByPrimaryKeyValue = {}
+
+    /**
+     * Preload collections.
+      @type {Record<number | string, Array<import("../../record/index.js").default>>} */
+    const preloadCollections = {}
+
+    for (const model of modelsToLoad) {
+      const primaryKeyValue = /**
+                               * Narrows the runtime value to the documented type.
+                                @type {string | number} */ (model.readColumn(primaryKey))
+
+      preloadCollections[primaryKeyValue] = []
+
+      if (!modelsPrimaryKeyValues.includes(primaryKeyValue)) modelsPrimaryKeyValues.push(primaryKeyValue)
+      if (!(primaryKeyValue in modelsByPrimaryKeyValue)) modelsByPrimaryKeyValue[primaryKeyValue] = []
+
+      modelsByPrimaryKeyValue[primaryKeyValue].push(model)
+    }
+
+    // Step 1: Query the through table to build parent→target ID mapping
+    const throughModels = await throughModelClass
+      .where({[throughForeignKey]: modelsPrimaryKeyValues})
+      .toArray()
+
+    /**
+     * Parent to target ids.
+      @type {Record<string | number, Array<string | number>>} */
+    const parentToTargetIds = {}
+
+    /**
+     * All target ids.
+      @type {Set<string | number>} */
+    const allTargetIds = new Set()
+
+    for (const throughModel of throughModels) {
+      const parentId = /**
+                        * Narrows the runtime value to the documented type.
+                         @type {string | number} */ (throughModel.readColumn(throughForeignKey))
+      const throughId = /**
+                         * Narrows the runtime value to the documented type.
+                          @type {string | number} */ (throughModel.readColumn(throughModelClass.primaryKey()))
+
+      if (!(parentId in parentToTargetIds)) parentToTargetIds[parentId] = []
+
+      parentToTargetIds[parentId].push(throughId)
+      allTargetIds.add(throughId)
+    }
+
+    // Step 2: Load target models by the foreign key that points to the through table
+    /**
+     * Target models.
+      @type {import("../../record/index.js").default[]} */
+    let targetModels = []
+
+    if (allTargetIds.size > 0) {
+      let query = targetModelClass.where({[targetForeignKey]: [...allTargetIds]})
+
+      query = this.relationship.applyScope(query)
+      query = this.selection.applyToQuery({query, targetModelClass, mappingColumns: [targetForeignKey]})
+      targetModels = await query.toArray()
+    }
+
+    // Step 3: Index target models by their foreign key (maps to through model ID)
+    /**
+     * Target models by foreign key.
+      @type {Record<string | number, Array<import("../../record/index.js").default>>} */
+    const targetModelsByForeignKey = {}
+
+    for (const targetModel of targetModels) {
+      const fkValue = /**
+                       * Narrows the runtime value to the documented type.
+                        @type {string | number} */ (targetModel.readColumn(targetForeignKey))
+
+      if (!(fkValue in targetModelsByForeignKey)) targetModelsByForeignKey[fkValue] = []
+
+      targetModelsByForeignKey[fkValue].push(targetModel)
+    }
+
+    // Step 4: Map targets to parents via the through mapping
+    for (const parentId in parentToTargetIds) {
+      const throughIds = parentToTargetIds[parentId]
+
+      for (const throughId of throughIds) {
+        const matchingTargets = targetModelsByForeignKey[throughId] || []
+
+        for (const targetModel of matchingTargets) {
+          if (parentId in preloadCollections) {
+            preloadCollections[parentId].push(targetModel)
+          }
+        }
+      }
+    }
+
+    for (const modelValue in preloadCollections) {
+      const preloadedCollection = preloadCollections[modelValue]
+
+      for (const model of modelsByPrimaryKeyValue[modelValue]) {
+        const modelRelationship = model.getRelationshipByName(this.relationship.getRelationshipName())
+
+        // Replace rather than append: `modelsToLoad` are exactly the records we
+        // intend to (re)load, so a forced re-preload must not duplicate entries.
+        modelRelationship.setLoaded(preloadedCollection)
+        modelRelationship.setPreloaded(true)
+      }
+    }
+
+    return [...satisfiedTargets, ...targetModels]
+  }
+
+  /**
+   * Preload direct has-many relationships.
+   * @returns {Promise<import("../../record/index.js").default[]>} - Loaded target models.
+   */
+  async _runDirect() {
+    const foreignKey = this.relationship.getForeignKey()
+    const primaryKey = this.relationship.getPrimaryKey()
+
+    if (!primaryKey) {
+      throw new Error(`${this.relationship.getModelClass().name}#${this.relationship.getRelationshipName()} doesn't have a primary key`)
+    }
+
+    const targetModelClass = this.relationship.getTargetModelClass()
+
+    if (!targetModelClass) throw new Error("No target model class could be gotten from relationship")
+
+    const {modelsToLoad, satisfiedTargets} = this._partition(targetModelClass, [foreignKey])
+
+    if (modelsToLoad.length == 0) return satisfiedTargets
+
+    /**
+     * Models primary key values.
+      @type {Array<number | string>} */
+    const modelsPrimaryKeyValues = []
+
+    /**
+     * Models by primary key value.
+      @type {Record<number | string, Array<import("../../record/index.js").default>>} */
+    const modelsByPrimaryKeyValue = {}
+
+    /**
+     * Preload collections.
+      @type {Record<number | string, Array<import("../../record/index.js").default>>} */
+    const preloadCollections = {}
+
+    for (const model of modelsToLoad) {
+      const primaryKeyValue = /**
+                               * Narrows the runtime value to the documented type.
+                                @type {string | number} */ (model.readColumn(primaryKey))
+
+      preloadCollections[primaryKeyValue] = []
+
+      if (!modelsPrimaryKeyValues.includes(primaryKeyValue)) modelsPrimaryKeyValues.push(primaryKeyValue)
+      if (!(primaryKeyValue in modelsByPrimaryKeyValue)) modelsByPrimaryKeyValue[primaryKeyValue] = []
+
+      modelsByPrimaryKeyValue[primaryKeyValue].push(model)
+    }
+
+    /**
+     * Where args.
+      @type {Record<string, string | number | Array<string | number>>} */
+    const whereArgs = {}
+
+    whereArgs[foreignKey] = modelsPrimaryKeyValues
+
+    if (this.relationship.getPolymorphic()) {
+      const typeColumn = this.relationship.getPolymorphicTypeColumn()
+
+      whereArgs[typeColumn] = this.relationship.getModelClass().getModelName()
+    }
+
+    await ensureModelClassInitialized(targetModelClass, this.relationship.getConfiguration())
+
+    let query = targetModelClass.where(whereArgs)
+
+    query = this.relationship.applyScope(query)
+    query = this.selection.applyToQuery({query, targetModelClass, mappingColumns: [foreignKey]})
+
+    const targetModels = await query.toArray()
+
+    for (const targetModel of targetModels) {
+      const foreignKeyValue = /**
+                               * Narrows the runtime value to the documented type.
+                                @type {string | number} */ (targetModel.readColumn(foreignKey))
+
+      preloadCollections[foreignKeyValue].push(targetModel)
+    }
+
+    for (const modelValue in preloadCollections) {
+      const preloadedCollection = preloadCollections[modelValue]
+
+      for (const model of modelsByPrimaryKeyValue[modelValue]) {
+        const modelRelationship = model.getRelationshipByName(this.relationship.getRelationshipName())
+
+        // Replace rather than append: `modelsToLoad` are exactly the records we
+        // intend to (re)load, so a forced re-preload must not duplicate entries.
+        modelRelationship.setLoaded(preloadedCollection)
+        modelRelationship.setPreloaded(true)
+      }
+    }
+
+    return [...satisfiedTargets, ...targetModels]
+  }
+}

package/src/database/query/preloader/has-one.js

@@ -0,0 +1,123 @@
+// @ts-check
+
+import ensureModelClassInitialized from "./ensure-model-class-initialized.js"
+import PreloaderSelection from "./selection.js"
+import restArgsError from "../../../utils/rest-args-error.js"
+
+export default class VelociousDatabaseQueryPreloaderHasOne {
+  /**
+   * Runs constructor.
+   * @param {object} args - Options object.
+   * @param {Array<import("../../record/index.js").default>} args.models - Model instances.
+   * @param {import("../../record/relationships/has-one.js").default} args.relationship - Relationship.
+   * @param {PreloaderSelection} [args.selection] - Column selection and idempotency rules.
+   */
+  constructor({models, relationship, selection, ...restArgs}) {
+    restArgsError(restArgs)
+
+    this.models = models
+    this.relationship = relationship
+    this.selection = selection || new PreloaderSelection()
+  }
+
+  async run() {
+    /**
+     * Models primary key values.
+      @type {Array<number | string>} */
+    const modelsPrimaryKeyValues = []
+
+    /**
+     * Models by primary key value.
+      @type {Record<number | string, Array<import("../../record/index.js").default>>} */
+    const modelsByPrimaryKeyValue = {}
+
+    const foreignKey = this.relationship.getForeignKey()
+    const primaryKey = this.relationship.getPrimaryKey()
+    const relationshipName = this.relationship.getRelationshipName()
+
+    const targetModelClass = this.relationship.getTargetModelClass()
+
+    if (!targetModelClass) throw new Error("No target model class could be gotten from relationship")
+
+    /**
+     * Preload collections.
+      @type {Record<number | string, import("../../record/index.js").default | undefined>} */
+    const preloadCollections = {}
+
+    /**
+     * Satisfied targets.
+      @type {import("../../record/index.js").default[]} */
+    const satisfiedTargets = []
+
+    for (const model of this.models) {
+      const instanceRelationship = model.getRelationshipByName(relationshipName)
+
+      if (this.selection.isSatisfied({instanceRelationship, targetModelClass, mappingColumns: [foreignKey]})) {
+        const loaded = /**
+                        * Narrows the runtime value to the documented type.
+                         @type {import("../../record/index.js").default | undefined} */ (instanceRelationship.getLoadedOrUndefined())
+
+        if (loaded) satisfiedTargets.push(loaded)
+        continue
+      }
+
+      const primaryKeyValue = /**
+                               * Narrows the runtime value to the documented type.
+                                @type {string | number} */ (model.readColumn(primaryKey))
+
+      preloadCollections[primaryKeyValue] = undefined
+
+      if (!modelsPrimaryKeyValues.includes(primaryKeyValue)) modelsPrimaryKeyValues.push(primaryKeyValue)
+      if (!(primaryKeyValue in modelsByPrimaryKeyValue)) modelsByPrimaryKeyValue[primaryKeyValue] = []
+
+      modelsByPrimaryKeyValue[primaryKeyValue].push(model)
+    }
+
+    if (modelsPrimaryKeyValues.length == 0) return satisfiedTargets
+
+    /**
+     * Where args.
+      @type {Record<string, string | number | Array<string | number>>} */
+    const whereArgs = {}
+
+    whereArgs[foreignKey] = modelsPrimaryKeyValues
+
+    if (this.relationship.getPolymorphic()) {
+      const typeColumn = this.relationship.getPolymorphicTypeColumn()
+
+      whereArgs[typeColumn] = this.relationship.getModelClass().getModelName()
+    }
+
+    await ensureModelClassInitialized(targetModelClass, this.relationship.getConfiguration())
+
+    // Load target models to be preloaded on the given models
+    let query = targetModelClass.where(whereArgs)
+
+    query = this.relationship.applyScope(query)
+    query = this.selection.applyToQuery({query, targetModelClass, mappingColumns: [foreignKey]})
+
+    const targetModels = await query.toArray()
+
+    for (const targetModel of targetModels) {
+      const foreignKeyValue = /**
+                               * Narrows the runtime value to the documented type.
+                                @type {string | number} */ (targetModel.readColumn(foreignKey))
+
+      preloadCollections[foreignKeyValue] = targetModel
+    }
+
+    // Set the target preloaded models on the given models
+    for (const modelValue in preloadCollections) {
+      const preloadedModel = preloadCollections[modelValue]
+
+      for (const model of modelsByPrimaryKeyValue[modelValue]) {
+        const modelRelationship = model.getRelationshipByName(relationshipName)
+
+        modelRelationship.setPreloaded(true)
+        modelRelationship.setLoaded(preloadedModel)
+      }
+    }
+
+    return [...satisfiedTargets, ...targetModels]
+  }
+}

package/src/database/query/preloader/selection.js

@@ -0,0 +1,152 @@
+// @ts-check
+
+const IDENTIFIER_REGEX = /^[a-zA-Z_][a-zA-Z0-9_]*$/
+
+/**
+ * Encapsulates the column selection and idempotency rules for preloading.
+ *
+ * Two per-target-model-name maps drive the behaviour, both keyed by the target
+ * model name (e.g. `"Account"`):
+ *
+ * - `preloadSelects` (from `.select({Account: ["id"]})`) narrows the columns
+ *   loaded for that target to the listed attributes (plus the primary/foreign
+ *   keys needed to map results back to their parents).
+ * - `preloadSelectsExtra` (from `.selectsExtra({Account: ["..."]})`) keeps the
+ *   default `SELECT *` columns and loads the listed extra selects in addition.
+ *
+ * `force` re-loads relationships even when they are already preloaded.
+ */
+export default class VelociousDatabaseQueryPreloaderSelection {
+  /**
+   * Runs constructor.
+   * @param {object} [args] - Options object.
+   * @param {Record<string, string[]>} [args.preloadSelects] - Narrowing selects keyed by target model name.
+   * @param {Record<string, string[]>} [args.preloadSelectsExtra] - Extra selects keyed by target model name.
+   * @param {boolean} [args.force] - Whether to re-load already-preloaded relationships.
+   */
+  constructor({preloadSelects = {}, preloadSelectsExtra = {}, force = false} = {}) {
+    this.preloadSelects = preloadSelects
+    this.preloadSelectsExtra = preloadSelectsExtra
+    this.force = force
+  }
+
+  /**
+   * Runs get force.
+   * @returns {boolean} - Whether already-preloaded relationships should still be re-loaded.
+   */
+  getForce() { return this.force }
+
+  /**
+   * Runs narrowing for.
+   * @param {typeof import("../../record/index.js").default} targetModelClass - Target model class.
+   * @returns {string[] | undefined} - Narrowing select attributes for the class, if any.
+   */
+  _narrowingFor(targetModelClass) {
+    return this.preloadSelects[targetModelClass.getModelName()]
+  }
+
+  /**
+   * Runs extra for.
+   * @param {typeof import("../../record/index.js").default} targetModelClass - Target model class.
+   * @returns {string[] | undefined} - Extra select attributes/expressions for the class, if any.
+   */
+  _extraFor(targetModelClass) {
+    return this.preloadSelectsExtra[targetModelClass.getModelName()]
+  }
+
+  /**
+   * Apply the configured select clauses to a target query.
+   * @template {import("../model-class-query.js").default} T
+   * @param {object} args - Options object.
+   * @param {T} args.query - Target query to apply selects to.
+   * @param {typeof import("../../record/index.js").default} args.targetModelClass - Target model class.
+   * @param {string[]} args.mappingColumns - Columns that must always be loaded so results can be mapped back to parents (primary/foreign keys).
+   * @returns {T} - The query, with selects applied when a selection is configured.
+   */
+  applyToQuery({query, targetModelClass, mappingColumns}) {
+    const narrowing = this._narrowingFor(targetModelClass)
+    const extra = this._extraFor(targetModelClass)
+
+    if (narrowing) {
+      const selects = [...new Set([...narrowing, ...mappingColumns, ...(extra || [])])]
+
+      return /** Narrows the runtime value to the documented type. @type {T} */ (query.select(selects))
+    }
+
+    if (extra) {
+      const allColumns = `${query.driver.quoteTable(targetModelClass.tableName())}.*`
+
+      return /** Narrows the runtime value to the documented type. @type {T} */ (query.select([allColumns, ...extra]))
+    }
+
+    return query
+  }
+
+  /**
+   * Whether an already-preloaded relationship's loaded target(s) satisfy the
+   * configured selection, so the relationship can be skipped. Returns false
+   * when `force` is set, when the relationship hasn't been preloaded, or when a
+   * required column is missing from a loaded target.
+   * @param {object} args - Options object.
+   * @param {import("../../record/instance-relationships/base.js").default} args.instanceRelationship - The source model's instance relationship.
+   * @param {typeof import("../../record/index.js").default} args.targetModelClass - Target model class.
+   * @param {string[]} args.mappingColumns - Primary/foreign key columns required for mapping.
+   * @returns {boolean} - Whether the relationship is already satisfied.
+   */
+  isSatisfied({instanceRelationship, targetModelClass, mappingColumns}) {
+    if (this.force) return false
+    if (!instanceRelationship.getPreloaded()) return false
+
+    const required = this._requiredColumnsFor({targetModelClass, mappingColumns})
+
+    if (!required) return false
+
+    const loaded = instanceRelationship.getLoadedOrUndefined()
+    const targets = loaded === undefined ? [] : (Array.isArray(loaded) ? loaded : [loaded])
+
+    for (const target of targets) {
+      for (const column of required) {
+        if (!target.hasLoadedColumn(column)) return false
+      }
+    }
+
+    return true
+  }
+
+  /**
+   * The set of columns that must be present on a loaded target for it to count
+   * as satisfied. Returns null when satisfaction can't be verified (an extra
+   * select is a raw SQL expression whose resulting column can't be derived), in
+   * which case the relationship is always re-loaded.
+   * @param {object} args - Options object.
+   * @param {typeof import("../../record/index.js").default} args.targetModelClass - Target model class.
+   * @param {string[]} args.mappingColumns - Primary/foreign key columns required for mapping.
+   * @returns {string[] | null} - Required column names, or null when unverifiable.
+   */
+  _requiredColumnsFor({targetModelClass, mappingColumns}) {
+    const attributeMap = targetModelClass.getAttributeNameToColumnNameMap()
+    const narrowing = this._narrowingFor(targetModelClass)
+    const extra = this._extraFor(targetModelClass)
+    /**
+     * Columns.
+      @type {string[]} */
+    const columns = []
+
+    if (narrowing) {
+      for (const attribute of narrowing) columns.push(attributeMap[attribute] || attribute)
+      for (const column of mappingColumns) columns.push(column)
+    } else {
+      for (const column of targetModelClass.getColumnNames()) columns.push(column)
+    }
+
+    if (extra) {
+      for (const entry of extra) {
+        if (!IDENTIFIER_REGEX.test(entry)) return null
+
+        columns.push(attributeMap[entry] || entry)
+      }
+    }
+
+    return columns
+  }
+}