velocious 1.0.430 → 1.0.431

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

@@ -0,0 +1,117 @@
+// @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 VelociousDatabaseRecordHasOneInstanceRelationship extends BaseInstanceRelationship {
+  /**
+   * Runs constructor.
+   * @param {import("./base.js").InstanceRelationshipsBaseArgs<MC, TMC>} args - Options object.
+   */
+  constructor(args) {
+    super(args)
+  }
+
+  /**
+   * Loaded.
+    @type {InstanceType<TMC> | undefined} */
+  _loaded = undefined
+
+  /**
+   * 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 class")
+
+    const newInstance = /**
+                         * Narrows the runtime value to the documented type.
+                          @type {InstanceType<TMC>} */ (new TargetModelClass(data))
+
+    this._loaded = newInstance
+
+    return newInstance
+  }
+
+  async load() {
+    // Force-reload: discard the cached value and fetch fresh. When the parent
+    // record was loaded as part of a batch, batch the has-one 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 primaryKey = this.getPrimaryKey()
+    const primaryModelID = /**
+                            * Narrows the runtime value to the documented type.
+                             @type {string | number} */ (this.getModel().readColumn(primaryKey))
+    const TargetModelClass = /**
+                              * Narrows the runtime value to the documented type.
+                               @type {TMC} */ (this.getTargetModelClass())
+
+    if (!TargetModelClass) throw new Error("Can't load without a target model class")
+
+    /**
+     * Where args.
+      @type {Record<string, string | number>} */
+    const whereArgs = {}
+
+    whereArgs[foreignKey] = primaryModelID
+
+    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()
+  }
+
+  /**
+   * 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
+  }
+
+  getLoadedOrUndefined() { return this._loaded }
+
+  /**
+   * Runs set loaded.
+   * @param {InstanceType<TMC> | Array<InstanceType<TMC>> | undefined} model - Related model(s).
+   */
+  setLoaded(model) {
+    if (Array.isArray(model)) throw new Error(`Argument given to setLoaded was an array: ${typeof model}`)
+
+    this._loaded = model
+  }
+
+  getTargetModelClass() { return /** Narrows the runtime value to the documented type. @type {TMC | undefined} */ (this.relationship.getTargetModelClass()) }
+}

package/src/database/record/record-not-found-error.js

@@ -0,0 +1,3 @@
+// @ts-check
+
+export default class RecordNotFoundError extends Error {}

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

@@ -0,0 +1,195 @@
+// @ts-check
+
+import restArgsError from "../../../utils/rest-args-error.js"
+import * as inflection from "inflection"
+
+/**
+ * RelationshipScopeCallback type.
+ * @typedef {(query: import("../../query/model-class-query.js").default<typeof import("../index.js").default>) => (import("../../query/model-class-query.js").default<typeof import("../index.js").default> | void)} RelationshipScopeCallback
+ */
+/**
+ * RelationshipBaseArgsType type.
+ * @typedef {object} RelationshipBaseArgsType
+ * @property {boolean} [autoload] - Whether to auto-batch-preload siblings when this relationship is lazy-loaded. Default true.
+ * @property {string} [className] - Name of the related model class.
+ * @property {boolean} [counterCache] - Auto-sync parent count column on create/update/destroy.
+ * @property {string} [dependent] - Dependent action when parent is destroyed.
+ * @property {string | undefined} [foreignKey] - Explicit foreign key column name.
+ * @property {string} [inverseOf] - Inverse relationship name on the related model.
+ * @property {typeof import("../index.js").default} [klass] - Related model class.
+ * @property {typeof import("../index.js").default} modelClass - Owning model class.
+ * @property {string} [primaryKey] - Primary key column on the owning model.
+ * @property {boolean} [polymorphic] - Whether the relationship is polymorphic.
+ * @property {string} relationshipName - Name of the relationship on the model.
+ * @property {RelationshipScopeCallback} [scope] - Optional scope callback for the relationship.
+ * @property {string} [through] - Name of the through association.
+ * @property {string} type - Relationship type (e.g. "hasMany").
+ */
+
+export default class VelociousDatabaseRecordBaseRelationship {
+  /**
+   * Runs constructor.
+   * @param {RelationshipBaseArgsType} args - Relationship definition arguments.
+   */
+  constructor({autoload, className, counterCache, dependent, foreignKey, inverseOf, klass, modelClass, primaryKey = "id", polymorphic, relationshipName, scope, through, type, ...restArgs}) {
+    restArgsError(restArgs)
+
+    if (!modelClass) throw new Error(`'modelClass' wasn't given for ${relationshipName}`)
+    if (!className && !klass && !polymorphic) throw new Error(`Neither 'className' or 'klass' was given for ${modelClass.name}#${relationshipName}`)
+
+    if (className == "EventSery") {
+      throw new Error(`Invalid model name: ${className}`)
+    }
+
+    this._autoload = autoload !== false
+    this.className = className
+    this._counterCache = counterCache || false
+    this._dependent = dependent
+    this.foreignKey = foreignKey
+    this._inverseOf = inverseOf
+    this.klass = klass
+    this.modelClass = modelClass
+    this._polymorphic = polymorphic
+    this._primaryKey = primaryKey
+    this.relationshipName = relationshipName
+    this._scope = scope
+    this.through = through
+    this.type = type
+  }
+
+  /**
+   * Runs get autoload.
+   * @returns {boolean} Whether this relationship auto-batch-preloads siblings on lazy access.
+   */
+  getAutoload() { return this._autoload }
+
+  getConfiguration() { return this.modelClass._getConfiguration() }
+
+  /**
+   * Runs get counter cache.
+   * @returns {boolean} Whether a counter cache column is synced on the parent.
+   */
+  getCounterCache() { return this._counterCache }
+
+  /**
+   * Runs get dependent.
+   * @returns {string | undefined} What will be done when the parent record is destroyed. E.g. "destroy", "nullify", "restrict" etc.
+   */
+  getDependent() { return this._dependent }
+
+  /**
+   * Runs get foreign key.
+   * @abstract
+   * @returns {string} The name of the foreign key, e.g. "user_id", "post_id" etc.
+   */
+  getForeignKey() {
+    throw new Error("getForeignKey not implemented")
+  }
+
+  /**
+   * Runs get inverse of.
+   * @abstract
+   * @returns {string | undefined} The name of the inverse relationship, e.g. "posts", "comments" etc.
+   */
+  getInverseOf() {
+    throw new Error("getInverseOf not implemented")
+  }
+
+  /**
+   * Runs get model class.
+   * @returns {typeof import("../index.js").default} - The model class.
+   */
+  getModelClass() { return this.modelClass }
+
+  /**
+   * Runs get relationship name.
+   * @returns {string} The name of the relationship, e.g. "posts", "user", "comments" etc.
+   */
+  getRelationshipName() { return this.relationshipName }
+
+  /**
+   * Runs get scope.
+   * @returns {RelationshipScopeCallback | undefined} - The scope callback.
+   */
+  getScope() { return this._scope }
+
+  /**
+   * Runs apply scope.
+   * @template T
+   * @param {T} query - Query instance.
+   * @returns {T} - Scoped query.
+   */
+  applyScope(query) {
+    const scope = this.getScope()
+
+    if (!scope) return query
+
+    const scopedQuery = /**
+                         * Narrows the runtime value to the documented type.
+                          @type {T | void} */ (scope.call(query, /**
+                                                                  * Narrows the runtime value to the documented type.
+                                                                    @type {import("../../query/model-class-query.js").default<typeof import("../index.js").default>} */ (query)))
+
+    return scopedQuery || query
+  }
+
+  /**
+   * Runs get polymorphic.
+   * @returns {boolean} - Whether polymorphic.
+   */
+  getPolymorphic() {
+    return this._polymorphic || false
+  }
+
+  /**
+   * Runs get polymorphic type column.
+   * @returns {string} - The polymorphic type column.
+   */
+  getPolymorphicTypeColumn() {
+    if (!this.getPolymorphic()) {
+      throw new Error(`${this.modelClass.name}#${this.relationshipName} isn't polymorphic`)
+    }
+
+    if (!this._polymorphicTypeColumn) {
+      const foreignKey = this.getForeignKey()
+
+      if (foreignKey && foreignKey.endsWith("_id")) {
+        this._polymorphicTypeColumn = foreignKey.replace(/_id$/, "_type")
+      } else {
+        const underscoredName = inflection.underscore(this.getRelationshipName())
+
+        this._polymorphicTypeColumn = `${underscoredName}_type`
+      }
+    }
+
+    return this._polymorphicTypeColumn
+  }
+
+  /**
+   * Runs get primary key.
+   * @returns {string} The name of the foreign key, e.g. "id" etc.
+   */
+  getPrimaryKey() { return this._primaryKey }
+
+  /**
+   * Runs get type.
+   * @returns {string} The type of the relationship, e.g. "has_many", "belongs_to", "has_one", "has_and_belongs_to_many" etc.
+   */
+  getType() { return this.type }
+
+  /**
+   * Runs get target model class.
+   * @returns {typeof import("../index.js").default | undefined} The target model class for this relationship, e.g. if the relationship is "posts" then the target model class is the Post class.
+   */
+  getTargetModelClass() {
+    if (this.getPolymorphic() && this.type == "belongsTo") {
+      return undefined
+    } else if (this.className) {
+      return this.getConfiguration().getModelClass(this.className)
+    } else if (this.klass) {
+      return this.klass
+    }
+
+    throw new Error("Couldn't figure out the target model class")
+  }
+}

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

@@ -0,0 +1,57 @@
+// @ts-check
+
+import BaseRelationship from "./base.js"
+import * as inflection from "inflection"
+
+export default class VelociousDatabaseRecordBelongsToRelationship extends BaseRelationship {
+  /**
+   * Runs get foreign key.
+   * @returns {string} - The foreign key.
+   */
+  getForeignKey() {
+    if (!this.foreignKey) {
+      if (this.getPolymorphic()) {
+        this.foreignKey = `${inflection.underscore(this.getRelationshipName())}_id`
+      } else {
+        const targetModelClass = this.getTargetModelClass()
+
+        if (!targetModelClass) throw new Error("Can't calculate foreign key without a target model class")
+
+        this.foreignKey = `${inflection.underscore(targetModelClass.getModelName())}_id`
+      }
+    }
+
+    return this.foreignKey
+  }
+
+  /**
+   * Runs get inverse of.
+   * @returns {string | undefined} - The inverse of.
+   */
+  getInverseOf() {
+    if (!this._inverseOf && !this._autoGenerateInverseOfAttempted) {
+      this._autoGenerateInverseOfAttempted = true
+
+      // Only make auto-inverse-of if the relationships name matches the target model class's name
+      const targetClassSimpleName = `${this.getRelationshipName().substring(0, 1).toUpperCase()}${this.getRelationshipName().substring(1, this.getRelationshipName().length)}`
+
+      const targetModelClass = this.getTargetModelClass()
+
+      if (targetModelClass && targetClassSimpleName == targetModelClass.getModelName()) {
+        // Only make auto-inverse-of if the expected relationship exist in a has-one or has-many form
+        const targetClassRelationshipNames = targetModelClass.getRelationshipNames()
+        const modelName = this.modelClass.getModelName()
+        const autoGeneratedHasOneInverseOfName = `${modelName.substring(0, 1).toLowerCase()}${modelName.substring(1, modelName.length)}`
+        const autoGeneratedHasManyInverseOfName = inflection.pluralize(autoGeneratedHasOneInverseOfName)
+
+        if (targetClassRelationshipNames.includes(autoGeneratedHasOneInverseOfName)) {
+          this._inverseOf = autoGeneratedHasOneInverseOfName
+        } else if (targetClassRelationshipNames.includes(autoGeneratedHasManyInverseOfName)) {
+          this._inverseOf = autoGeneratedHasManyInverseOfName
+        }
+      }
+    }
+
+    return this._inverseOf
+  }
+}

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

@@ -0,0 +1,46 @@
+// @ts-check
+
+import BaseRelationship from "./base.js"
+import * as inflection from "inflection"
+
+export default class VelociousDatabaseRecordHasManyRelationship extends BaseRelationship {
+  /**
+   * Runs get foreign key.
+   * @returns {string} - The foreign key.
+   */
+  getForeignKey() {
+    if (!this.foreignKey) {
+      this.foreignKey = `${inflection.underscore(this.modelClass.getModelName())}_id`
+    }
+
+    return this.foreignKey
+  }
+
+  /**
+   * Runs get inverse of.
+   * @returns {string | undefined} - The inverse of.
+   */
+  getInverseOf() {
+    if (!this._inverseOf && !this._autoGenerateInverseOfAttempted) {
+      this._autoGenerateInverseOfAttempted = true
+
+      // Only make auto-inverse-of if the relationships name matches the target model class's name
+      const targetClassSimpleName = inflection.singularize(`${this.getRelationshipName().substring(0, 1).toUpperCase()}${this.getRelationshipName().substring(1, this.getRelationshipName().length)}`)
+
+      const targetModelClass = this.getTargetModelClass()
+
+      if (targetModelClass && targetClassSimpleName == targetModelClass.getModelName()) {
+        // Only make auto-inverse-of if the expected relationship exist in a has-one or has-many form
+        const targetClassRelationshipNames = targetModelClass.getRelationshipNames()
+        const modelName = this.modelClass.getModelName()
+        const autoGeneratedBelongsToInverseOfName = `${modelName.substring(0, 1).toLowerCase()}${modelName.substring(1, modelName.length)}`
+
+        if (targetClassRelationshipNames.includes(autoGeneratedBelongsToInverseOfName)) {
+          this._inverseOf = autoGeneratedBelongsToInverseOfName
+        }
+      }
+    }
+
+    return this._inverseOf
+  }
+}

package/src/database/record/relationships/has-one.js

@@ -0,0 +1,46 @@
+// @ts-check
+
+import BaseRelationship from "./base.js"
+import * as inflection from "inflection"
+
+export default class VelociousDatabaseRecordHasOneRelationship extends BaseRelationship {
+  /**
+   * Runs get foreign key.
+   * @returns {string} - The foreign key.
+   */
+  getForeignKey() {
+    if (!this.foreignKey) {
+      this.foreignKey = `${inflection.underscore(this.modelClass.getModelName())}_id`
+    }
+
+    return this.foreignKey
+  }
+
+  /**
+   * Runs get inverse of.
+   * @returns {string | undefined} - The inverse of.
+   */
+  getInverseOf() {
+    if (!this._inverseOf && !this._autoGenerateInverseOfAttempted) {
+      this._autoGenerateInverseOfAttempted = true
+
+      // Only make auto-inverse-of if the relationships name matches the target model class's name
+      const targetClassSimpleName = `${this.getRelationshipName().substring(0, 1).toUpperCase()}${this.getRelationshipName().substring(1, this.getRelationshipName().length)}`
+
+      const targetModelClass = this.getTargetModelClass()
+
+      if (targetModelClass && targetClassSimpleName == targetModelClass.getModelName()) {
+        // Only make auto-inverse-of if the expected relationship exist in a has-one or has-many form
+        const targetClassRelationshipNames = targetModelClass.getRelationshipNames()
+        const modelName = this.modelClass.getModelName()
+        const autoGeneratedBelongsToInverseOfName = `${modelName.substring(0, 1).toLowerCase()}${modelName.substring(1, modelName.length)}`
+
+        if (targetClassRelationshipNames.includes(autoGeneratedBelongsToInverseOfName)) {
+          this._inverseOf = autoGeneratedBelongsToInverseOfName
+        }
+      }
+    }
+
+    return this._inverseOf
+  }
+}