velocious 1.0.431 → 1.0.433

package/build/database/query/preloader.js

@@ -0,0 +1,201 @@
+// @ts-check
+
+import BelongsToPreloader from "./preloader/belongs-to.js"
+import HasManyPreloader from "./preloader/has-many.js"
+import HasOnePreloader from "./preloader/has-one.js"
+import PreloaderSelection from "./preloader/selection.js"
+import restArgsError from "../../utils/rest-args-error.js"
+
+/**
+ * Runs normalize nested preload.
+ * @param {import("../query/index.js").NestedPreloadRecord | string | string[] | boolean} preload - Preload data in shorthand or nested form.
+ * @returns {import("../query/index.js").NestedPreloadRecord | null} - Normalized nested preload record.
+ */
+function normalizeNestedPreload(preload) {
+  if (!preload || typeof preload == "boolean") return null
+
+  if (typeof preload == "string") {
+    return {[preload]: true}
+  }
+
+  if (Array.isArray(preload)) {
+    /**
+     * Result.
+      @type {import("../query/index.js").NestedPreloadRecord} */
+    const result = {}
+
+    for (const entry of preload) {
+      if (typeof entry == "string") {
+        result[entry] = true
+        continue
+      }
+
+      if (entry && typeof entry == "object") {
+        const normalizedEntry = normalizeNestedPreload(entry)
+
+        if (normalizedEntry) {
+          for (const [key, value] of Object.entries(normalizedEntry)) {
+            result[key] = value
+          }
+        }
+        continue
+      }
+
+      throw new Error(`Invalid preload entry type: ${typeof entry}`)
+    }
+
+    return result
+  }
+
+  if (preload && typeof preload == "object") {
+    /**
+     * Result.
+      @type {import("../query/index.js").NestedPreloadRecord} */
+    const result = {}
+
+    for (const [key, value] of Object.entries(preload)) {
+      if (value === true || value === false) {
+        result[key] = value
+        continue
+      }
+
+      const normalizedValue = normalizeNestedPreload(value)
+
+      if (normalizedValue) {
+        result[key] = normalizedValue
+      } else {
+        throw new Error(`Invalid preload value for ${key}: ${typeof value}`)
+      }
+    }
+
+    return result
+  }
+
+  throw new Error(`Invalid preload type: ${typeof preload}`)
+}
+
+export default class VelociousDatabaseQueryPreloader {
+  /**
+   * Preloads relationship(s) onto one or more already-loaded model instances.
+   * Accepts either a query built via `Model.preload(...).select(...)` (its
+   * preload graph and selects are used) or a raw preload spec
+   * (string / array / nested object).
+   * @param {Array<import("../record/index.js").default>} models - Model instances to preload onto.
+   * @param {import("./model-class-query.js").default | import("./index.js").NestedPreloadRecord | string | Array<string | import("./index.js").NestedPreloadRecord>} queryOrSpec - Preload source.
+   * @param {{force?: boolean}} [options] - Options.
+   * @returns {Promise<void>} - Resolves when preloading completes.
+   */
+  static async preload(models, queryOrSpec, {force = false} = {}) {
+    if (models.length == 0) return
+
+    const modelClass = /**
+                        * Narrows the runtime value to the documented type.
+                         @type {typeof import("../record/index.js").default} */ (models[0].constructor)
+    const isQuery = Boolean(queryOrSpec) && typeof queryOrSpec == "object" && "_preload" in queryOrSpec
+    // Reuse the query builder's preload/select normalization for raw specs
+    // instead of duplicating it here.
+    const query = isQuery
+      ? /**
+         * Narrows the runtime value to the documented type.
+          @type {import("./model-class-query.js").default} */ (queryOrSpec)
+      : modelClass.preload(/**
+                            * Narrows the runtime value to the documented type.
+                             @type {?} */ (queryOrSpec))
+
+    const preloader = new VelociousDatabaseQueryPreloader({
+      modelClass,
+      models,
+      preload: query._preload,
+      selection: new PreloaderSelection({
+        preloadSelects: query._preloadSelects,
+        preloadSelectsExtra: query._preloadSelectsExtra,
+        force
+      })
+    })
+
+    await preloader.run()
+  }
+
+  /**
+   * Runs constructor.
+   * @param {object} args - Options object.
+   * @param {typeof import("../record/index.js").default} args.modelClass - Model class.
+   * @param {import("../record/index.js").default[]} args.models - Model instances.
+   * @param {import("../query/index.js").NestedPreloadRecord} args.preload - Preload.
+   * @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 {PreloaderSelection} [args.selection] - Pre-built selection (takes precedence over the select maps when given).
+   */
+  constructor({modelClass, models, preload, preloadSelects = {}, preloadSelectsExtra = {}, selection, ...restArgs}) {
+    restArgsError(restArgs)
+
+    this.modelClass = modelClass
+    this.models = models
+    this.preload = preload
+    this.selection = selection || new PreloaderSelection({preloadSelects, preloadSelectsExtra})
+  }
+
+  async run() {
+    for (const preloadRelationshipName in this.preload) {
+      const relationship = this.modelClass.getRelationshipByName(preloadRelationshipName)
+      let preloadResult
+
+      if (relationship.getType() == "belongsTo") {
+        const belongsToRelationship = /**
+                                       * Narrows the runtime value to the documented type.
+                                        @type {import("../record/relationships/belongs-to.js").default} */ (relationship)
+        const hasManyPreloader = new BelongsToPreloader({models: this.models, relationship: belongsToRelationship, selection: this.selection})
+
+        preloadResult = await hasManyPreloader.run()
+      } else if (relationship.getType() == "hasMany") {
+        const hasManyRelationship = /**
+                                     * Narrows the runtime value to the documented type.
+                                      @type {import("../record/relationships/has-many.js").default} */ (relationship)
+        const hasManyPreloader = new HasManyPreloader({models: this.models, relationship: hasManyRelationship, selection: this.selection})
+
+        preloadResult = await hasManyPreloader.run()
+      } else if (relationship.getType() == "hasOne") {
+        const hasOneRelationship = /**
+                                    * Narrows the runtime value to the documented type.
+                                     @type {import("../record/relationships/has-one.js").default} */ (relationship)
+        const hasOnePreloader = new HasOnePreloader({models: this.models, relationship: hasOneRelationship, selection: this.selection})
+
+        preloadResult = await hasOnePreloader.run()
+      } else {
+        throw new Error(`Unknown relationship type: ${relationship.getType()}`)
+      }
+
+      const targetModels = Array.isArray(preloadResult) ? preloadResult : (preloadResult?.targetModels || [])
+      const targetModelsByClassName = Array.isArray(preloadResult) ? undefined : preloadResult?.targetModelsByClassName
+
+      // Handle any further preloads in the tree
+      const newPreload = this.preload[preloadRelationshipName]
+      const normalizedPreload = normalizeNestedPreload(newPreload)
+
+      if (normalizedPreload && targetModels.length > 0) {
+        if (relationship.getPolymorphic() && targetModelsByClassName) {
+          const configuration = relationship.getConfiguration()
+
+          for (const className in targetModelsByClassName) {
+            const models = targetModelsByClassName[className]
+
+            if (models.length == 0) continue
+
+            const targetModelClass = configuration.getModelClass(className)
+            const preloader = new VelociousDatabaseQueryPreloader({modelClass: targetModelClass, models, preload: normalizedPreload, selection: this.selection})
+
+            await preloader.run()
+          }
+        } else {
+          const targetModelClass = relationship.getTargetModelClass()
+
+          if (!targetModelClass) throw new Error("No target model class could be gotten from relationship")
+
+          const preloader = new VelociousDatabaseQueryPreloader({modelClass: targetModelClass, models: targetModels, preload: normalizedPreload, selection: this.selection})
+
+          await preloader.run()
+        }
+      }
+    }
+  }
+}

package/build/database/query/query-data.js

@@ -0,0 +1,305 @@
+// @ts-check
+
+import {isPlainObject} from "is-plain-object"
+
+/**
+ * QueryDataEntry type.
+ * @typedef {object} QueryDataEntry
+ * @property {string[]} chain - Relationship chain from the root model to the model that declares the fn. Empty for a root-level entry.
+ * @property {string} fnName - Identifier under which the fn is registered on the declaring model.
+ */
+
+/**
+ * Defines this typedef.
+ * @typedef {string | Array<string | Record<string, ?>> | {[key: string]: true | false | string | string[] | Record<string, ?>}} QueryDataSpec
+ */
+
+/**
+ * QueryDataCallbackArgs type.
+ * @typedef {object} QueryDataCallbackArgs
+ * @property {string} attributeName - Name under which the fn was registered. Convenient when a fn is reused across aliases.
+ * @property {import("../drivers/base.js").default} driver - Active database driver, for quoting helpers and type-specific SQL.
+ * @property {typeof import("../record/index.js").default} modelClass - Model class the fn is registered on (the chain's target).
+ * @property {Array<string | number>} parentIds - Primary-key values of the loaded root records.
+ * @property {import("./model-class-query.js").default} query - Grouped query already joined down the chain, filtered by `parentIds`, with `parent_id` pre-selected.
+ * @property {string} tableName - Unquoted table reference (alias or table name) for the chain's target, ready to paste into SQL.
+ */
+
+/**
+ * QueryDataFn type.
+ * @typedef {(args: QueryDataCallbackArgs) => void | import("./model-class-query.js").default} QueryDataFn
+ */
+
+/**
+ * Normalize a user-supplied queryData spec into a flat list of entries
+ * the runner can consume. The spec mirrors the shape of `preload`, with
+ * the important distinction that **leaf strings are fn names**, not
+ * further relationship segments. Nested keys are relationship names
+ * along the join chain from the root model to the declaring model.
+ *
+ * Accepted shapes (all yield the same flat entries):
+ *   "foo"                                      → [{chain: [], fnName: "foo"}]
+ *   ["foo", "bar"]                             → [{chain: [], fnName: "foo"}, {chain: [], fnName: "bar"}]
+ *   {foo: true}                                → [{chain: [], fnName: "foo"}]
+ *   {projects: ["tasksCount"]}                 → [{chain: ["projects"], fnName: "tasksCount"}]
+ *   {projects: {tasks: ["transportSecondsSum", {timelogs: ["timeSecondsSum"]}]}}
+ *     → [{chain: ["projects","tasks"], fnName: "transportSecondsSum"},
+ *        {chain: ["projects","tasks","timelogs"], fnName: "timeSecondsSum"}]
+ * @param {QueryDataSpec} spec - User-supplied spec.
+ * @param {string[]} [chain] - Current chain (internal recursion).
+ * @returns {QueryDataEntry[]} - Flat list of entries.
+ */
+export function normalizeQueryDataSpec(spec, chain = []) {
+  if (spec == null) return []
+
+  if (typeof spec === "string") {
+    return [{chain: [...chain], fnName: spec}]
+  }
+
+  if (Array.isArray(spec)) {
+    /**
+     * Entries.
+      @type {QueryDataEntry[]} */
+    const entries = []
+
+    for (const item of spec) {
+      if (typeof item === "string") {
+        entries.push({chain: [...chain], fnName: item})
+        continue
+      }
+
+      if (isPlainObject(item)) {
+        for (const nested of normalizeQueryDataSpec(/**
+                                                     * Narrows the runtime value to the documented type.
+                                                      @type {?} */ (item), chain)) {
+          entries.push(nested)
+        }
+        continue
+      }
+
+      throw new Error(`Invalid queryData array entry: ${typeof item}`)
+    }
+
+    return entries
+  }
+
+  if (isPlainObject(spec)) {
+    /**
+     * Entries.
+      @type {QueryDataEntry[]} */
+    const entries = []
+
+    for (const [key, value] of Object.entries(spec)) {
+      if (value === true) {
+        entries.push({chain: [...chain], fnName: key})
+        continue
+      }
+
+      if (value === false) continue
+
+      if (typeof value === "string" || Array.isArray(value) || isPlainObject(value)) {
+        for (const nested of normalizeQueryDataSpec(/**
+                                                     * Narrows the runtime value to the documented type.
+                                                      @type {?} */ (value), [...chain, key])) {
+          entries.push(nested)
+        }
+        continue
+      }
+
+      throw new Error(`Invalid queryData value for "${key}": ${typeof value}`)
+    }
+
+    return entries
+  }
+
+  throw new Error(`Invalid queryData spec: ${typeof spec}`)
+}
+
+/**
+ * Build the nested `joins(...)` descriptor for a chain of relationship names.
+ * `["projects", "tasks"]` → `{projects: {tasks: true}}`. Used internally so
+ * the runner can reuse the existing `joins` path-registration machinery
+ * (JoinTracker, alias generation, scope application).
+ * @param {string[]} chain - Relationship chain.
+ * @returns {true | Record<string, ?>} - Nested join descriptor, or `true` when the chain is empty.
+ */
+function buildNestedJoinDescriptor(chain) {
+  if (chain.length === 0) return true
+
+  /**
+   * Obj.
+    @type {Record<string, ?>} */
+  const obj = {}
+  let cursor = obj
+
+  for (let i = 0; i < chain.length; i += 1) {
+    const seg = chain[i]
+    const isLast = i === chain.length - 1
+
+    cursor[seg] = isLast ? true : {}
+
+    if (!isLast) cursor = cursor[seg]
+  }
+
+  return obj
+}
+
+/**
+ * Walk a relationship chain from the root model and return the model
+ * class at its tail. Throws with a clear message when any segment is
+ * unknown.
+ * @param {typeof import("../record/index.js").default} rootModelClass - Root model class.
+ * @param {string[]} chain - Relationship chain.
+ * @returns {typeof import("../record/index.js").default} - Target model class.
+ */
+function resolveTargetModelClass(rootModelClass, chain) {
+  let modelClass = rootModelClass
+
+  for (const segment of chain) {
+    const relationship = modelClass.getRelationshipByName(segment)
+    const target = relationship.getTargetModelClass()
+
+    if (!target) {
+      throw new Error(`queryData: could not resolve target model for ${modelClass.name}#${segment}`)
+    }
+
+    modelClass = target
+  }
+
+  return modelClass
+}
+
+/**
+ * Run every queryData entry against the loaded root records, attaching
+ * the resulting values as queryData entries on each root record.
+ *
+ * One grouped query per entry: the runner builds a fresh query over the
+ * root model, joins down the chain, groups by the root table's primary
+ * key, and invokes the registered fn to add its own SELECT (and any
+ * additional joins/where). Results are mapped back to root models by
+ * primary key and attached via `_setQueryData(name, value)` for every
+ * selected alias (except the reserved `parent_id`). Rows missing from
+ * the result keep `null` — matches the feature's documented default.
+ *
+ * Mirrors the shape of `runWithCount`: one query per entry, a separate
+ * storage map on the record, never touches `_attributes`.
+ * @param {object} args - Options.
+ * @param {typeof import("../record/index.js").default} args.rootModelClass - Root model class.
+ * @param {import("../record/index.js").default[]} args.rootModels - Loaded root records.
+ * @param {QueryDataEntry[]} args.entries - Normalized queryData entries.
+ * @returns {Promise<void>}
+ */
+export async function runQueryData({rootModelClass, rootModels, entries}) {
+  if (rootModels.length === 0 || entries.length === 0) return
+
+  const primaryKey = rootModelClass.primaryKey()
+  const rootIds = rootModels.map((model) => /**
+                                             * Narrows the runtime value to the documented type.
+                                              @type {string | number} */ (model.readColumn(primaryKey)))
+
+  for (const entry of entries) {
+    await runEntry({entry, primaryKey, rootIds, rootModelClass, rootModels})
+  }
+}
+
+/**
+ * Runs run entry.
+ * @param {object} args - Options.
+ * @param {QueryDataEntry} args.entry - Entry being evaluated.
+ * @param {string} args.primaryKey - Root model primary key column.
+ * @param {Array<string | number>} args.rootIds - Root primary-key values.
+ * @param {typeof import("../record/index.js").default} args.rootModelClass - Root model class.
+ * @param {import("../record/index.js").default[]} args.rootModels - Loaded root records.
+ * @returns {Promise<void>}
+ */
+async function runEntry({entry, primaryKey, rootIds, rootModelClass, rootModels}) {
+  const targetModelClass = resolveTargetModelClass(rootModelClass, entry.chain)
+  const fn = targetModelClass.getQueryDataByName(entry.fnName)
+
+  if (!fn) {
+    throw new Error(`queryData: ${targetModelClass.name} has no entry registered as ${JSON.stringify(entry.fnName)}. ` +
+      `Declare it with ${targetModelClass.name}.queryData(${JSON.stringify(entry.fnName)}, ({query, tableName}) => query.select(...))`)
+  }
+
+  const query = rootModelClass._newQuery()
+
+  // Empty out any defaults the query factory added — queryData runs
+  // a bare aggregate, not a full model load.
+  query._selects = []
+  query._preload = {}
+
+  // Force the root WHERE to qualify by table name so it survives the
+  // joins the fn may add later (otherwise a child table sharing the
+  // root PK column name, e.g. `id`, makes the clause ambiguous).
+  query._forceQualifyBaseTable = true
+
+  const driver = query.driver
+  const rootTable = rootModelClass.tableName()
+  const rootPkSql = `${driver.quoteTable(rootTable)}.${driver.quoteColumn(primaryKey)}`
+
+  /**
+   * Root where.
+    @type {Record<string, ?>} */
+  const rootWhere = {}
+  rootWhere[primaryKey] = rootIds
+  query.where(rootWhere)
+
+  const joinDescriptor = buildNestedJoinDescriptor(entry.chain)
+
+  if (joinDescriptor !== true) {
+    query.joins(joinDescriptor)
+  }
+
+  query.group(rootPkSql)
+  query.select(`${rootPkSql} AS parent_id`)
+
+  const targetTableRef = entry.chain.length === 0
+    ? rootTable
+    : query.getTableReferenceForJoin(...entry.chain)
+
+  // NB: we intentionally leave `_joinBasePath` at [] so the outer chain
+  // joins continue to resolve from the root model at render time. The
+  // fn gets `tableName` for self-reference; additional joins from
+  // nested levels should use full paths from the root.
+  fn({
+    attributeName: entry.fnName,
+    driver,
+    modelClass: targetModelClass,
+    parentIds: rootIds,
+    query,
+    tableName: targetTableRef
+  })
+
+  const rows = /**
+                * Narrows the runtime value to the documented type.
+                 @type {Array<Record<string, ?>>} */ (await query._executeQuery())
+  const byParent = new Map()
+
+  for (const row of rows) {
+    const parentId = row.parent_id
+
+    if (parentId == null) continue
+
+    byParent.set(parentId, row)
+  }
+
+  for (const model of rootModels) {
+    const modelId = /**
+                     * Narrows the runtime value to the documented type.
+                      @type {string | number} */ (model.readColumn(primaryKey))
+    // Driver-type tolerance: MySQL can return PKs as strings even when
+    // the column is numeric. Fall back to a string lookup so results
+    // still land on the right model.
+    const row = byParent.has(modelId)
+      ? byParent.get(modelId)
+      : byParent.get(String(modelId))
+
+    if (!row) continue
+
+    for (const [columnName, value] of Object.entries(row)) {
+      if (columnName === "parent_id") continue
+
+      model._setQueryData(columnName, value)
+    }
+  }
+}

package/build/database/query/select-base.js

@@ -0,0 +1,30 @@
+// @ts-check
+
+export default class VelociousDatabaseQuerySelectBase {
+  /**
+   * Runs get options.
+   * @returns {import("../query-parser/options.js").default} - The options options.
+   */
+  getOptions() {
+    if (!this.query) throw new Error("'query' hasn't been set")
+
+    return this.query.driver.options()
+  }
+
+  /**
+   * Runs set query.
+   * @param {import("./index.js").default} query - Query instance.
+   */
+  setQuery(query) {
+    this.query = query
+  }
+
+  /**
+   * Runs to sql.
+   * @abstract
+   * @returns {string} - SQL string.
+   */
+  toSql() {
+    throw new Error("'toSql' wasn't implemented")
+  }
+}

package/build/database/query/select-plain.js

@@ -0,0 +1,18 @@
+// @ts-check
+
+import SelectBase from "./select-base.js"
+
+export default class VelociousDatabaseQuerySelectPlain extends SelectBase {
+  /**
+   * Runs constructor.
+   * @param {string} plain - Plain.
+   */
+  constructor(plain) {
+    super()
+    this.plain = plain
+  }
+
+  toSql() {
+    return this.plain
+  }
+}

package/build/database/query/select-table-and-column.js

@@ -0,0 +1,28 @@
+// @ts-check
+
+import SelectBase from "./select-base.js"
+
+export default class VelociousDatabaseQuerySelectTableAndColumn extends SelectBase {
+  /**
+   * Runs constructor.
+   * @param {string} tableName - Table name.
+   * @param {string} columnName - Column name.
+   */
+  constructor(tableName, columnName) {
+    super()
+    this.columnName = columnName
+    this.tableName = tableName
+  }
+
+  getColumnName() {
+    return this.columnName
+  }
+
+  getTableName() {
+    return this.tableName
+  }
+
+  toSql() {
+    return `${this.getOptions().quoteTableName(this.tableName)}.${this.getOptions().quoteColumnName(this.columnName)}`
+  }
+}

package/build/database/query/update-base.js

@@ -0,0 +1,41 @@
+// @ts-check
+
+export default class VelociousDatabaseQueryUpdateBase {
+  /**
+   * Runs constructor.
+   * @param {object} args - Options object.
+   * @param {Record<string, ?>} args.conditions - Conditions.
+   * @param {Record<string, ?>} args.data - Data payload.
+   * @param {import("../drivers/base.js").default} args.driver - Database driver instance.
+   * @param {string} args.tableName - Table name.
+   */
+  constructor({conditions, data, driver, tableName}) {
+    this.conditions = conditions
+    this.data = data
+    this.driver = driver
+    this.tableName = tableName
+  }
+
+  /**
+   * Runs get options.
+   * @returns {import("../query-parser/options.js").default} - The options options.
+   */
+  getOptions() {
+    return this.driver.options()
+  }
+
+  /**
+   * Runs format value.
+   * @param {?} value - Value to format.
+   * @returns {string | number} - SQL literal.
+   */
+  formatValue(value) {
+    if (value === null) return "NULL"
+
+    return this.getOptions().quote(value)
+  }
+
+  toSql() {
+    throw new Error("'toSql' wasn't implemented")
+  }
+}