velocious 1.0.430 → 1.0.432

package/src/database/record/instance-relationships/base.js

@@ -0,0 +1,289 @@
+// @ts-check
+
+import BelongsToPreloader from "../../query/preloader/belongs-to.js"
+import HasManyPreloader from "../../query/preloader/has-many.js"
+import HasOnePreloader from "../../query/preloader/has-one.js"
+
+/**
+ * InstanceRelationshipsBaseArgs type.
+ * @template {typeof import("../index.js").default} [MC=typeof import("../index.js").default]
+ * @template {typeof import("../index.js").default} [TMC=typeof import("../index.js").default]
+ * @typedef {object} InstanceRelationshipsBaseArgs
+ * @property {InstanceType<MC>} model - Parent model instance.
+ * @property {import("../relationships/base.js").default} relationship - Relationship metadata definition.
+ */
+
+/**
+ * A generic query over some model type.
+ * @template {typeof import("../index.js").default} [MC=typeof import("../index.js").default]
+ * @template {typeof import("../index.js").default} [TMC=typeof import("../index.js").default]
+ */
+export default class VelociousDatabaseRecordBaseInstanceRelationship {
+  /**
+   * Auto save.
+    @type {boolean | undefined} */
+  _autoSave = undefined
+  /**
+   * Preloaded.
+    @type {boolean | undefined} */
+  _preloaded = undefined
+  /**
+   * Loaded.
+    @type {InstanceType<TMC> | Array<InstanceType<TMC>> | undefined} */
+  _loaded = undefined
+
+  /**
+   * Runs constructor.
+   * @param {InstanceRelationshipsBaseArgs<MC, TMC>} args - Options object.
+   */
+  constructor({model, relationship}) {
+    this._dirty = false
+    this.model = model
+    this.relationship = relationship
+  }
+
+  /**
+   * Runs add to loaded.
+   * @abstract
+   * @param {InstanceType<TMC>[] | InstanceType<TMC>} models - Model instances.
+   * @returns {void} - No return value.
+   */
+  addToLoaded(models) { // eslint-disable-line no-unused-vars
+    throw new Error("addToLoaded not implemented")
+  }
+
+  /**
+   * Runs build.
+   * @abstract
+   * @param {Record<string, ?>} attributes - Attributes.
+   * @returns {InstanceType<TMC>} - The build.
+   */
+  build(attributes) { // eslint-disable-line no-unused-vars
+    throw new Error("'build' not implemented")
+  }
+
+  /**
+   * Runs get auto save.
+   * @returns {boolean | undefined} Whether the relationship should be auto-saved before saving the parent model
+   */
+  getAutoSave() { return this._autoSave }
+
+  /**
+   * Runs set auto save.
+   * @param {boolean} newAutoSaveValue Whether the relationship should be auto-saved before saving the parent model
+   * @returns {void} - No return value.
+   */
+  setAutoSave(newAutoSaveValue) { this._autoSave = newAutoSaveValue }
+
+  /**
+   * Runs set dirty.
+   * @param {boolean} newValue Whether the relationship is dirty (has been modified)
+   * @returns {void} - No return value.
+   */
+  setDirty(newValue) { this._dirty = newValue }
+
+  /**
+   * Runs get dirty.
+   * @returns {boolean} Whether the relationship is dirty (has been modified)
+   */
+  getDirty() { return this._dirty }
+
+  /**
+   * Runs load.
+   * @abstract
+   * @returns {Promise<InstanceType<TMC> | Array<InstanceType<TMC>> | undefined>} - Resolves with loaded relationship value.
+   */
+  load() {
+    throw new Error("'load' not implemented")
+  }
+
+  /**
+   * Loads the relationship if not already loaded. When the parent record was
+   * loaded as part of a batch (cohort) and autoload is enabled, siblings in
+   * the cohort that share this relationship and have not preloaded it yet
+   * are batched into a single query via the existing preloader path.
+   * @returns {Promise<InstanceType<TMC> | Array<InstanceType<TMC>> | undefined>} - Resolves with loaded relationship value.
+   */
+  async autoloadOrLoad() {
+    if (this._loaded !== undefined) return this._loaded
+
+    const batched = await this._tryCohortPreload()
+
+    if (!batched) await this.load()
+
+    return this._loaded
+  }
+
+  /**
+   * Attempts to batch-load this relationship across cohort siblings via the
+   * existing preloader path. Returns true when a batch ran (self is always
+   * included because callers reset their own `_preloaded` state before
+   * calling), false when autoload is off, there is no cohort, or no batch
+   * candidates remain. Siblings that have already preloaded this relationship
+   * are skipped so their cached value is preserved.
+   * @returns {Promise<boolean>} - Whether a cohort batch preload ran.
+   */
+  async _tryCohortPreload() {
+    const relationshipDef = this.getRelationship()
+    const configuration = relationshipDef.getConfiguration()
+    const cohort = /**
+                    * Narrows the runtime value to the documented type.
+                     @type {Array<import("../index.js").default> | undefined} */ (/**
+                                                                                   * Narrows the runtime value to the documented type.
+                                                                                    @type {?} */ (this.model)._loadCohort)
+
+    if (!configuration.getAutoload() || !relationshipDef.getAutoload() || !cohort || cohort.length <= 1) {
+      return false
+    }
+
+    const relationshipName = relationshipDef.getRelationshipName()
+    const OwnerModelClass = /**
+                             * Narrows the runtime value to the documented type.
+                              @type {?} */ (this.model).constructor
+    /**
+     * Batch.
+      @type {Array<import("../index.js").default>} */
+    const batch = []
+
+    // Exact same class, persisted, no existing in-memory relationship state.
+    // Skip siblings where `_loaded` is already set — they may have been
+    // preloaded (preserve cache) OR locally manipulated via `build...` /
+    // `set...` (preserve unsaved edits). Either way the preloader would
+    // overwrite that state.
+    for (const sibling of cohort) {
+      if (sibling.constructor !== OwnerModelClass) continue
+      if (!sibling.isPersisted()) continue
+
+      const siblingInstanceRelationship = sibling.getRelationshipByName(relationshipName)
+
+      if (siblingInstanceRelationship.getLoadedOrUndefined() !== undefined) continue
+
+      batch.push(sibling)
+    }
+
+    if (batch.length === 0) return false
+
+    const type = relationshipDef.getType()
+
+    if (type == "belongsTo") {
+      const belongsToRelationship = /**
+                                     * Narrows the runtime value to the documented type.
+                                      @type {import("../relationships/belongs-to.js").default} */ (relationshipDef)
+      const preloader = new BelongsToPreloader({models: batch, relationship: belongsToRelationship})
+
+      await preloader.run()
+    } else if (type == "hasMany") {
+      const hasManyRelationship = /**
+                                   * Narrows the runtime value to the documented type.
+                                    @type {import("../relationships/has-many.js").default} */ (relationshipDef)
+      const preloader = new HasManyPreloader({models: batch, relationship: hasManyRelationship})
+
+      await preloader.run()
+    } else if (type == "hasOne") {
+      const hasOneRelationship = /**
+                                  * Narrows the runtime value to the documented type.
+                                   @type {import("../relationships/has-one.js").default} */ (relationshipDef)
+      const preloader = new HasOnePreloader({models: batch, relationship: hasOneRelationship})
+
+      await preloader.run()
+    } else {
+      throw new Error(`Unknown relationship type: ${type}`)
+    }
+
+    return true
+  }
+
+  /**
+   * Runs is loaded.
+   * @returns {boolean} Whether the relationship has been preloaded
+   */
+  isLoaded() { return Boolean(this._loaded) }
+
+  /**
+   * Runs loaded.
+   * @returns {InstanceType<TMC> | Array<InstanceType<TMC>> | undefined} The loaded model or models (depending on relationship type)
+   */
+  loaded() {
+    if (!this._preloaded && this.model.isPersisted()) {
+      throw new Error(`${this.model.constructor.name}#${this.relationship.getRelationshipName()} hasn't been preloaded`)
+    }
+
+    return this._loaded
+  }
+
+  /**
+   * Runs set loaded.
+   * @param {InstanceType<TMC> | Array<InstanceType<TMC>> | undefined} model - Related model(s) to mark as loaded.
+   */
+  setLoaded(model) { this._loaded = model }
+
+  /**
+   * Runs get loaded or undefined.
+   * @returns {InstanceType<TMC> | InstanceType<TMC>[] | undefined} - The loaded or undefined.
+   */
+  getLoadedOrUndefined() { return this._loaded }
+
+  /**
+   * Runs get preloaded.
+   * @returns {boolean} The loaded model or models (depending on relationship type)
+   */
+  getPreloaded() { return this._preloaded || false }
+
+  /**
+   * Runs set preloaded.
+   * @param {boolean} isPreloaded - Whether the relationship is preloaded.
+   */
+  setPreloaded(isPreloaded) { this._preloaded = isPreloaded }
+
+  /**
+   * Runs get foreign key.
+   * @returns {string} The foreign key for this relationship
+   */
+  getForeignKey() { return this.getRelationship().getForeignKey() }
+
+  /**
+   * Runs get model.
+   * @returns {InstanceType<MC>} - The model.
+   */
+  getModel() { return this.model }
+
+  /**
+   * Runs get primary key.
+   * @returns {string} The primary key for this relationship's model
+   */
+  getPrimaryKey() { return this.getRelationship().getPrimaryKey() }
+
+  /**
+   * Runs get relationship.
+   * @returns {import("../relationships/base.js").default} The relationship object that this instance relationship is based on
+   */
+  getRelationship() { return this.relationship }
+
+  /**
+   * Runs apply scope.
+   * @template T
+   * @param {T} query - Query instance.
+   * @returns {T} - Scoped query.
+   */
+  applyScope(query) {
+    return this.getRelationship().applyScope(query)
+  }
+
+  /**
+   * Runs get target model class.
+   * @returns {TMC | undefined} The model class that this instance relationship
+   */
+  getTargetModelClass() {
+    const TargetModelClass = /**
+                              * Narrows the runtime value to the documented type.
+                               @type {TMC} */ (this.getRelationship().getTargetModelClass())
+
+    return TargetModelClass
+  }
+
+  /**
+   * Runs get type.
+   * @returns {string} The type of relationship (e.g. "has_many", "belongs_to", etc.)
+   */
+  getType() { return this.getRelationship().getType() }
+}

package/src/database/record/instance-relationships/belongs-to.js

@@ -0,0 +1,84 @@
+// @ts-check
+
+import BaseInstanceRelationship from "./base.js"
+
+/**
+ * A generic query over some model type.
+ * @template {typeof import("../index.js").default} MC
+ * @template {typeof import("../index.js").default} TMC
+ * @augments {BaseInstanceRelationship<MC, TMC>}
+ */
+export default class VelociousDatabaseRecordBelongsToInstanceRelationship extends BaseInstanceRelationship {
+  /**
+   * Runs constructor.
+   * @param {import("./base.js").InstanceRelationshipsBaseArgs<MC, TMC>} args - Options object.
+   */
+  constructor(args) {
+    super(args)
+  }
+
+  /**
+   * Runs build.
+   * @param {Record<string, ?>} data - Data payload.
+   * @returns {InstanceType<TMC>} - The build.
+   */
+  build(data) {
+    const TargetModelClass = /**
+                              * Narrows the runtime value to the documented type.
+                               @type {TMC} */ (this.getTargetModelClass())
+
+    if (!TargetModelClass) throw new Error("Can't build a new record without a target model")
+
+    const newInstance = /**
+                         * Narrows the runtime value to the documented type.
+                          @type {InstanceType<TMC>} */ (new TargetModelClass(data))
+
+    this._loaded = newInstance
+
+    return newInstance
+  }
+
+  getLoadedOrUndefined() { return this._loaded }
+
+  async load() {
+    // Force-reload: discard the cached value and fetch fresh. When the parent
+    // record was loaded as part of a batch, batch the belongs-to lookup across
+    // cohort siblings that have not preloaded this relationship yet.
+    this._preloaded = false
+    this._loaded = undefined
+
+    const batched = await this._tryCohortPreload()
+
+    if (batched) return this.loaded()
+
+    const foreignKey = this.getForeignKey()
+    const foreignModelID = this.getModel().readColumn(foreignKey)
+    const TargetModelClass = this.getTargetModelClass()
+
+    if (!TargetModelClass) throw new Error("Can't load without a target model")
+
+    const primaryKey = TargetModelClass.primaryKey()
+    /**
+     * Where args.
+      @type {Record<string, string | number | null | undefined>} */
+    const whereArgs = {}
+
+    whereArgs[primaryKey] = foreignModelID
+
+    let query = TargetModelClass.where(whereArgs)
+
+    query = this.applyScope(query)
+
+    const foreignModel = await query.first()
+
+    if (foreignModel) {
+      this.setLoaded(foreignModel)
+    } else {
+      this.setLoaded(undefined)
+    }
+    this.setDirty(false)
+    this.setPreloaded(true)
+
+    return this.loaded()
+  }
+}

package/src/database/record/instance-relationships/has-many.js

@@ -0,0 +1,284 @@
+// @ts-check
+
+import BaseInstanceRelationship from "./base.js"
+
+/**
+ * A generic query over some model type.
+ * @template {typeof import("../index.js").default} MC
+ * @template {typeof import("../index.js").default} TMC
+ * @augments {BaseInstanceRelationship<MC, TMC>}
+ */
+export default class VelociousDatabaseRecordHasManyInstanceRelationship extends BaseInstanceRelationship {
+  /**
+   * Runs constructor.
+   * @param {import("./base.js").InstanceRelationshipsBaseArgs<MC, TMC>} args - Options object.
+   */
+  constructor(args) {
+    super(args)
+  }
+
+  /**
+   * Runs build.
+   * @param {Record<string, ?>} data - Data payload.
+   * @returns {InstanceType<TMC>} - The build.
+   */
+  build(data) {
+    // Spawn new model of the targeted class
+    const targetModelClass = this.getTargetModelClass()
+
+    if (!targetModelClass) throw new Error("Can't build a new record without a taget model class")
+
+    const newInstance = /**
+                         * Narrows the runtime value to the documented type.
+                          @type {InstanceType<TMC>} */ (new targetModelClass(data))
+
+
+    // Add it to the loaded models of this relationship
+    if (this._loaded === undefined) {
+      this._loaded = [newInstance]
+    } else if (Array.isArray(this._loaded)) {
+      this._loaded.push(newInstance)
+    } else {
+      throw new Error(`Loaded had an unexpected type: ${typeof this._loaded}`)
+    }
+
+
+    // Set loaded on the models inversed relationship
+    const inverseOf = this.getRelationship().getInverseOf()
+
+    if (inverseOf) {
+      const inverseInstanceRelationship = newInstance.getRelationshipByName(inverseOf)
+
+      inverseInstanceRelationship.setAutoSave(false)
+      inverseInstanceRelationship.setLoaded(this.getModel())
+    }
+
+
+    // Assign the foreign key to the new model
+    const parentModel = this.getModel()
+
+    if (parentModel.isPersisted()) {
+      const foreignKeyName = this.getForeignKey()
+      const columnNameMap = targetModelClass.getColumnNameToAttributeNameMap()
+      const foreignKeyAttributeName = columnNameMap[foreignKeyName]
+      if (!foreignKeyAttributeName) throw new Error(`Unknown foreign key attribute name for ${foreignKeyName}`)
+      const primaryKeyName = this.getPrimaryKey()
+      const foreignKeyValue = parentModel.readColumn(primaryKeyName)
+      /**
+       * Assign data.
+        @type {Record<string, ?>} */
+      const assignData = {}
+
+      assignData[foreignKeyAttributeName] = foreignKeyValue
+
+      newInstance.assign(assignData)
+    }
+
+
+    // Return the new contructed model
+    return newInstance
+  }
+
+  /**
+   * Runs create.
+   * @param {Record<string, ?>} data - Data payload.
+   * @returns {Promise<InstanceType<TMC>>} - Resolves with the create.
+   */
+  async create(data) {
+    const model = this.build(data)
+
+    await model.save()
+
+    return model
+  }
+
+  /**
+   * Runs load.
+   * @returns {Promise<InstanceType<TMC>[]>} - Resolves with loaded models.
+   */
+  async load() {
+    // Force-reload: discard the cached value and fetch fresh. When the parent
+    // record was loaded as part of a batch, route through the cohort preloader
+    // so siblings that have not preloaded this relationship get batched too.
+    // The scoped query path (`instance.query().where(...).load()`) bypasses
+    // this and stays a single-record load by design.
+    this._preloaded = false
+    this._loaded = undefined
+
+    const batched = await this._tryCohortPreload()
+
+    if (batched) {
+      return /** Narrows the runtime value to the documented type. @type {InstanceType<TMC>[]} */ (Array.isArray(this._loaded) ? this._loaded : [])
+    }
+
+    const foreignModels = /**
+                           * Narrows the runtime value to the documented type.
+                            @type {InstanceType<TMC>[]} */ (await this.query().load())
+
+    this.setLoaded(foreignModels)
+    this.setDirty(false)
+    this.setPreloaded(true)
+
+    return foreignModels
+  }
+
+  /**
+   * Runs to array.
+   * @returns {Promise<InstanceType<TMC>[]>} - Resolves with the array.
+   */
+  async toArray() {
+    const loadedValue = await this.autoloadOrLoad()
+
+    if (loadedValue === undefined) return []
+
+    return Array.isArray(loadedValue) ? loadedValue : [loadedValue]
+  }
+
+  /**
+   * Runs size.
+   * @returns {Promise<number>} - Resolves with the relationship size, using loaded records when available.
+   */
+  async size() {
+    const loadedValue = this.getLoadedOrUndefined()
+
+    if (loadedValue !== undefined) {
+      if (!Array.isArray(loadedValue)) throw new Error(`Loaded had an unexpected type: ${typeof loadedValue}`)
+
+      return loadedValue.length
+    }
+
+    if (this.getModel().isNewRecord()) return 0
+
+    return await this.query().count()
+  }
+
+  /**
+   * Runs preload.
+   * @param {import("../../query/index.js").NestedPreloadRecord} preloads - Preload map for related records.
+   * @returns {import("../../query/model-class-query.js").default<TMC>} - The preload.
+   */
+  preload(preloads) {
+    return this.query().clone().preload(preloads)
+  }
+
+  /**
+   * Runs find.
+   * @param {string | number} modelID - Related model identifier.
+   * @returns {Promise<InstanceType<TMC>>} - Resolves with the find.
+   */
+  async find(modelID) {
+    return /** Narrows the runtime value to the documented type. @type {Promise<InstanceType<TMC>>} */ (this.query().find(modelID))
+  }
+
+  /**
+   * Runs query.
+   * @returns {import("../../query/model-class-query.js").default<TMC>} - The query.
+   */
+  query() {
+    if (!this.getModel().isPersisted()) throw new Error("Cannot build a query for an unpersisted parent model")
+
+    const TargetModelClass = this.getTargetModelClass()
+
+    if (!TargetModelClass) throw new Error("Cannot load without a target model class")
+
+    const throughRelationshipName = this.getRelationship().through
+
+    if (throughRelationshipName) {
+      const parentModelClass = this.getModel().getModelClass()
+      const throughRelationship = parentModelClass.getRelationshipByName(throughRelationshipName)
+      const throughModelClass = throughRelationship.getTargetModelClass()
+
+      if (!throughModelClass) throw new Error(`Through relationship ${throughRelationshipName} has no target model class`)
+
+      const throughForeignKey = throughRelationship.getForeignKey()
+      const throughPrimaryKey = throughRelationship.getPrimaryKey()
+      const targetForeignKey = this.getForeignKey()
+      const targetTable = TargetModelClass.tableName()
+      const throughTable = throughModelClass.tableName()
+      const driver = TargetModelClass.connection()
+      const parentPrimaryKey = this.getPrimaryKey()
+      const parentId = /**
+                        * Narrows the runtime value to the documented type.
+                         @type {string | number} */ (this.getModel().readColumn(parentPrimaryKey))
+      const joinSql = `LEFT JOIN ${driver.quoteTable(throughTable)} ON ${driver.quoteTable(throughTable)}.${driver.quoteColumn(throughPrimaryKey)} = ${driver.quoteTable(targetTable)}.${driver.quoteColumn(targetForeignKey)}`
+      const whereSql = `${driver.quoteTable(throughTable)}.${driver.quoteColumn(throughForeignKey)} = ${driver.options().quote(parentId)}`
+
+      const query = TargetModelClass.joins(joinSql).where(whereSql)
+
+      return this.applyScope(query)
+    }
+
+    const foreignKey = this.getForeignKey()
+    const primaryKey = this.getPrimaryKey()
+    const primaryModelID = /**
+                            * Narrows the runtime value to the documented type.
+                             @type {string | number} */ (this.getModel().readColumn(primaryKey))
+
+    /**
+     * Where args.
+      @type {Record<string, string | number>} */
+    const whereArgs = {}
+
+    whereArgs[foreignKey] = primaryModelID
+
+    const query = TargetModelClass.where(whereArgs)
+
+    return this.applyScope(query)
+  }
+
+  /**
+   * Runs loaded.
+   * @returns {Array<InstanceType<TMC>>} The loaded model or models (depending on relationship type)
+   */
+  loaded() {
+    if (!this._preloaded && this.model.isPersisted()) {
+      throw new Error(`${this.model.constructor.name}#${this.relationship.getRelationshipName()} hasn't been preloaded`)
+    }
+
+    if (this._loaded === undefined && this.model.isNewRecord()) {
+      return []
+    }
+
+    return Array.isArray(this._loaded) ? this._loaded : []
+  }
+
+  /**
+   * Runs add to loaded.
+   * @param {InstanceType<TMC>[] | InstanceType<TMC>} models - Model instances.
+   * @returns {void} - No return value.
+   */
+  addToLoaded(models) {
+    if (!models) {
+      throw new Error("Need to give something")
+    } else if (Array.isArray(models)) {
+      for (const model of models) {
+        if (this._loaded === undefined) {
+          this._loaded = [model]
+        } else if (Array.isArray(this._loaded)) {
+          this._loaded.push(model)
+        } else {
+          throw new Error(`Unexpected loaded type: ${typeof this._loaded}`)
+        }
+      }
+    } else {
+      if (this._loaded === undefined) {
+        this._loaded = [models]
+      } else if (Array.isArray(this._loaded)) {
+        this._loaded.push(models)
+      } else {
+        throw new Error(`Unexpected loaded type: ${typeof this._loaded}`)
+      }
+    }
+  }
+
+  /**
+   * Runs set loaded.
+   * @param {InstanceType<TMC>[]} models - Model instances.
+   * @returns {void} - No return value.
+   */
+  setLoaded(models) {
+    if (!Array.isArray(models)) throw new Error(`Argument given to setLoaded wasn't an array: ${typeof models}`)
+
+    this._loaded = models
+  }
+}