velocious 1.0.429 → 1.0.431

package/src/database/query/with-count.js

@@ -0,0 +1,219 @@
+// @ts-check
+
+/**
+ * WithCountEntry type.
+ * @typedef {object} WithCountEntry
+ * @property {string} attributeName - Attribute to set on each parent record holding the count.
+ * @property {string} relationshipName - Has-many relationship whose rows are counted.
+ * @property {Record<string, ?> | undefined} where - Optional extra where clause applied to the count query.
+ */
+
+/**
+ * Defines this typedef.
+ * @typedef {string | string[] | Record<string, boolean | {relationship?: string, where?: Record<string, ?>}>} WithCountSpec
+ */
+
+/**
+ * Normalize the flexible user-facing `.withCount(...)` argument into the
+ * strict internal list of {attributeName, relationshipName, where} entries
+ * the runner consumes.
+ *
+ * Accepted shapes:
+ *   "projects"                                         → one entry
+ *   ["projects", "timelogs"]                           → one entry per name
+ *   {projects: true}                                   → one entry (attr = "projectsCount")
+ *   {activeMembersCount:                               → custom attribute name
+ *     {relationship: "users", where: {active: true}}}
+ * @param {WithCountSpec} spec - User-supplied spec.
+ * @returns {WithCountEntry[]} - Normalized entries.
+ */
+export function normalizeWithCount(spec) {
+  if (spec == null) return []
+
+  if (typeof spec === "string") {
+    return [entryFromName(spec)]
+  }
+
+  if (Array.isArray(spec)) {
+    return spec.flatMap((item) => {
+      if (typeof item !== "string") {
+        throw new Error(`withCount array entries must be strings; got ${typeof item}`)
+      }
+
+      return entryFromName(item)
+    })
+  }
+
+  if (typeof spec === "object") {
+    /**
+     * Entries.
+      @type {WithCountEntry[]} */
+    const entries = []
+
+    for (const [key, value] of Object.entries(spec)) {
+      if (value === true) {
+        entries.push(entryFromName(key))
+        continue
+      }
+
+      if (value === false) {
+        continue
+      }
+
+      if (typeof value === "object" && value !== null) {
+        /**
+         * Options.
+          @type {{relationship?: string, where?: Record<string, ?>}} */
+        const options = value
+        entries.push({
+          attributeName: key,
+          relationshipName: options.relationship || key,
+          where: options.where
+        })
+        continue
+      }
+
+      throw new Error(`Invalid withCount value for ${key}: ${typeof value}`)
+    }
+
+    return entries
+  }
+
+  throw new Error(`Invalid withCount spec: ${typeof spec}`)
+}
+
+/**
+ * Runs entry from name.
+ * @param {string} name - Relationship name (attribute name is derived by appending "Count").
+ * @returns {WithCountEntry}
+ */
+function entryFromName(name) {
+  return {
+    attributeName: `${name}Count`,
+    relationshipName: name,
+    where: undefined
+  }
+}
+
+/**
+ * Run every withCount entry against the loaded parent records, attaching
+ * the resulting counts as attributes on each record. Mirrors the
+ * Preloader's data-flow shape — one grouped count query per entry, then
+ * `setAttribute` on each parent.
+ * @param {object} args - Options.
+ * @param {import("../record/index.js").default[]} args.models - Loaded parent records.
+ * @param {typeof import("../record/index.js").default} args.modelClass - Parent model class.
+ * @param {WithCountEntry[]} args.entries - Normalized withCount entries.
+ * @returns {Promise<void>}
+ */
+export async function runWithCount({models, modelClass, entries}) {
+  if (models.length === 0 || entries.length === 0) return
+
+  const primaryKey = modelClass.primaryKey()
+  const parentIds = models.map((model) => /**
+                                           * Narrows the runtime value to the documented type.
+                                            @type {string | number} */ (model.readColumn(primaryKey)))
+
+  for (const entry of entries) {
+    const counts = await countForEntry({entries, entry, modelClass, parentIds})
+
+    for (const model of models) {
+      const modelPrimaryKeyValue = /**
+                                    * Narrows the runtime value to the documented type.
+                                     @type {string | number} */ (model.readColumn(primaryKey))
+      // Tolerate driver differences in numeric return types: SQLite
+      // returns integers as JS numbers, but MySQL's raw driver can
+      // return count primary keys as strings. Try both.
+      const resolvedCount = counts.has(modelPrimaryKeyValue)
+        ? /**
+           * Narrows the runtime value to the documented type.
+            @type {number} */ (counts.get(modelPrimaryKeyValue))
+        : Number(counts.get(String(modelPrimaryKeyValue)) ?? 0)
+
+      // Counts go on the record's dedicated association-count map,
+      // NOT on `_attributes`, so a virtual `tasksCount` can't shadow a
+      // real `tasks_count` column (e.g. a counter_cache) nor leak into
+      // attribute-level serialization / change tracking.
+      model._setAssociationCount(entry.attributeName, resolvedCount)
+    }
+  }
+}
+
+/**
+ * Runs count for entry.
+ * @param {object} args - Options.
+ * @param {WithCountEntry[]} args.entries - All entries, used for error context only.
+ * @param {WithCountEntry} args.entry - Entry being evaluated.
+ * @param {typeof import("../record/index.js").default} args.modelClass - Parent model class.
+ * @param {Array<string | number>} args.parentIds - Primary keys of the loaded parents.
+ * @returns {Promise<Map<string | number, number>>} - Map of parent pk → count.
+ */
+async function countForEntry({entries, entry, modelClass, parentIds}) {
+  void entries
+
+  const relationship = modelClass.getRelationshipByName(entry.relationshipName)
+
+  if (!relationship) {
+    throw new Error(`${modelClass.name} has no relationship named ${JSON.stringify(entry.relationshipName)} (withCount attribute ${JSON.stringify(entry.attributeName)})`)
+  }
+
+  if (relationship.type !== "hasMany") {
+    throw new Error(`withCount currently supports only hasMany relationships; ${modelClass.name}#${entry.relationshipName} is ${relationship.type}`)
+  }
+
+  const targetModelClass = relationship.getTargetModelClass()
+
+  if (!targetModelClass) {
+    throw new Error(`withCount: could not resolve target model for ${modelClass.name}#${entry.relationshipName}`)
+  }
+
+  const foreignKey = relationship.getForeignKey()
+  /**
+   * Where conditions.
+    @type {Record<string, ?>} */
+  const whereConditions = {[foreignKey]: parentIds}
+
+  if (relationship.getPolymorphic && relationship.getPolymorphic()) {
+    const typeColumn = relationship.getPolymorphicTypeColumn()
+    whereConditions[typeColumn] = modelClass.getModelName()
+  }
+
+  if (entry.where) {
+    Object.assign(whereConditions, entry.where)
+  }
+
+  const countQuery = targetModelClass
+    .where(whereConditions)
+    .group(foreignKey)
+
+  countQuery._preload = {}
+  countQuery._selects = []
+
+  const driver = countQuery.driver
+  const quotedTable = driver.quoteTable(targetModelClass.tableName())
+  const quotedFk = driver.quoteColumn(foreignKey)
+
+  countQuery.select(`${quotedTable}.${quotedFk} AS parent_id`)
+  countQuery.select("COUNT(*) AS count_value")
+
+  const rows = /**
+                * Narrows the runtime value to the documented type.
+                 @type {Array<{parent_id: string | number, count_value: string | number}>} */ (
+    await countQuery._executeQuery()
+  )
+
+  /**
+   * Counts.
+    @type {Map<string | number, number>} */
+  const counts = new Map()
+
+  for (const row of rows) {
+    const parentId = /**
+                      * Narrows the runtime value to the documented type.
+                       @type {string | number} */ (row.parent_id)
+    const countValue = Number(row.count_value) || 0
+    counts.set(parentId, countValue)
+  }
+
+  return counts
+}

package/src/database/query-parser/base-query-parser.js

@@ -0,0 +1,40 @@
+// @ts-check
+
+import FromParser from "./from-parser.js"
+import GroupParser from "./group-parser.js"
+import JoinsParser from "./joins-parser.js"
+import LimitParser from "./limit-parser.js"
+import OrderParser from "./order-parser.js"
+import SelectParser from "./select-parser.js"
+import WhereParser from "./where-parser.js"
+
+export default class VelociousDatabaseBaseQueryParser {
+  /**
+   * Runs constructor.
+   * @param {object} args - Options object.
+   * @param {boolean} [args.pretty] - Whether pretty.
+   * @param {import("../query/index.js").default} args.query - Query instance.
+   */
+  constructor({pretty = false, query}) {
+    if (!query) throw new Error("No query given")
+
+    this.pretty = pretty
+    this.query = query
+  }
+
+  toSql() {
+    const {pretty, query} = this
+
+    let sql = ""
+
+    sql += new SelectParser({pretty, query}).toSql()
+    sql += new FromParser({pretty, query}).toSql()
+    sql += new JoinsParser({pretty, query}).toSql()
+    sql += new WhereParser({pretty, query}).toSql()
+    sql += new GroupParser({pretty, query}).toSql()
+    sql += new OrderParser({pretty, query}).toSql()
+    sql += new LimitParser({pretty, query}).toSql()
+
+    return sql
+  }
+}

package/src/database/query-parser/from-parser.js

@@ -0,0 +1,49 @@
+// @ts-check
+
+import restArgsError from "../../utils/rest-args-error.js"
+
+export default class VelociousDatabaseQueryParserFromParser {
+  /**
+   * Runs constructor.
+   * @param {object} args - Options object.
+   * @param {boolean} args.pretty - Whether pretty.
+   * @param {import("../query/index.js").default} args.query - Query instance.
+   */
+  constructor({pretty, query, ...restArgs}) {
+    restArgsError(restArgs)
+
+    this.pretty = pretty
+    this.query = query
+  }
+
+  /**
+   * Runs to sql.
+   * @returns {string} - SQL string.
+   */
+  toSql() {
+    const {pretty, query} = this
+    const froms = query.getFroms()
+
+    let sql = " FROM"
+
+    for (const fromKey in froms) {
+      const from = froms[fromKey]
+
+      if (typeof fromKey == "number" && fromKey > 0) {
+        sql += ","
+      }
+
+      if (pretty) {
+        sql += "\n  "
+      } else {
+        sql += " "
+      }
+
+      from.setQuery(query)
+
+      sql += from.toSql()
+    }
+
+    return sql
+  }
+}

package/src/database/query-parser/group-parser.js

@@ -0,0 +1,55 @@
+// @ts-check
+
+import restArgsError from "../../utils/rest-args-error.js"
+
+export default class VelociousDatabaseQueryParserFromParser {
+  /**
+   * Runs constructor.
+   * @param {object} args - Options object.
+   * @param {boolean} args.pretty - Whether pretty.
+   * @param {import("../query/index.js").default} args.query - Query instance.
+   */
+  constructor({pretty, query, ...restArgs}) {
+    restArgsError(restArgs)
+
+    this.pretty = pretty
+    this.query = query
+  }
+
+  /**
+   * Runs to sql.
+   * @returns {string} - SQL string.
+   */
+  toSql() {
+    const {pretty, query} = this
+    const groups = query.getGroups()
+
+    if (groups.length == 0) {
+      return ""
+    }
+
+    let sql = " GROUP BY"
+
+    for (const groupKey in groups) {
+      const group = groups[groupKey]
+
+      if (typeof groupKey == "number" && groupKey > 0) {
+        sql += ","
+      }
+
+      if (pretty) {
+        sql += "\n  "
+      } else {
+        sql += " "
+      }
+
+      if (typeof group == "string") {
+        sql += group
+      } else {
+        throw new Error(`Unsupported group type: ${typeof group}`)
+      }
+    }
+
+    return sql
+  }
+}

package/src/database/query-parser/joins-parser.js

@@ -0,0 +1,37 @@
+// @ts-check
+
+export default class VelocuiousDatabaseQueryParserJoinsParser {
+  /**
+   * Runs constructor.
+   * @param {object} args - Options object.
+   * @param {boolean} args.pretty - Whether pretty.
+   * @param {import("../query/index.js").default} args.query - Query instance.
+   */
+  constructor({pretty, query}) {
+    this.pretty = pretty
+    this.query = query
+    this.conn = this.query.driver
+  }
+
+  toSql() {
+    const {pretty, query} = this
+    let sql = ""
+
+    for (const joinKey in query._joins) {
+      const join = query._joins[joinKey]
+
+      join.setPretty(pretty)
+      join.setQuery(query)
+
+      if (pretty) {
+        sql += "\n\n"
+      } else {
+        sql += " "
+      }
+
+      sql += join.toSql()
+    }
+
+    return sql
+  }
+}

package/src/database/query-parser/limit-parser.js

@@ -0,0 +1,77 @@
+// @ts-check
+
+export default class VelocuiousDatabaseQueryParserLimitParser {
+  /**
+   * Runs constructor.
+   * @param {object} args - Options object.
+   * @param {boolean} args.pretty - Whether pretty.
+   * @param {import("../query/index.js").default} args.query - Query instance.
+   */
+  constructor({pretty, query}) {
+    this.pretty = pretty
+    this.query = query
+  }
+
+  toSql() {
+    const {pretty, query} = this
+    const driver = query.driver
+    const options = this.query.getOptions()
+    let sql = ""
+    const limit = query._limit
+    const offset = query._offset
+    const databaseType = driver.getType()
+    const isMssql = databaseType == "mssql"
+    const hasLimit = limit !== null
+    const hasOffset = offset !== null
+
+    if (!hasLimit && !hasOffset) return sql
+
+    if (pretty) {
+      sql += "\n\n"
+    } else {
+      sql += " "
+    }
+
+    if (isMssql) {
+      if (query._orders.length === 0) {
+        sql += "ORDER BY (SELECT NULL) "
+      }
+
+      sql += `OFFSET ${options.quote(offset === null ? 0 : offset)} ROWS`
+
+      if (hasLimit) {
+        sql += ` FETCH NEXT ${options.quote(limit)} ROWS ONLY`
+      }
+    } else {
+      sql += "LIMIT"
+
+      if (pretty) {
+        sql += "\n  "
+      } else {
+        sql += " "
+      }
+
+      if (hasLimit) {
+        sql += options.quote(limit)
+      } else if (databaseType == "pgsql") {
+        sql += "ALL"
+      } else if (databaseType == "sqlite") {
+        sql += "-1"
+      } else {
+        sql += "18446744073709551615"
+      }
+
+      if (hasOffset) {
+        if (pretty) {
+          sql += "\n  "
+        } else {
+          sql += " "
+        }
+
+        sql += `OFFSET ${options.quote(offset)}`
+      }
+    }
+
+    return sql
+  }
+}

package/src/database/query-parser/options.js

@@ -0,0 +1,94 @@
+// @ts-check
+
+/**
+ * OptionsObjectArgsType type.
+ * @typedef {object} OptionsObjectArgsType
+ * @property {string} columnQuote - Quote character for column names.
+ * @property {string} indexQuote - Quote character for index names.
+ * @property {import("../drivers/base.js").default} driver - Database driver instance.
+ * @property {string} tableQuote - Quote character for table names.
+ * @property {string} stringQuote - Quote character for string literals.
+ */
+
+export default class VelociousDatabaseQueryParserOptions {
+  /**
+   * Runs constructor.
+   * @param {OptionsObjectArgsType} options - Options object.
+   */
+  constructor(options) {
+    this.columnQuote = options.columnQuote
+    this.indexQuote = options.indexQuote
+    this.driver = options.driver
+    this.tableQuote = options.tableQuote
+    this.stringQuote = options.stringQuote
+
+    if (!this.driver) throw new Error("No driver given to parser options")
+  }
+
+  /**
+   * Runs quote.
+   * @param {?} value - Value to use.
+   * @returns {number | string} - The quote.
+   */
+  quote(value) {
+    if (typeof value == "number") return value
+
+    return this.quoteString(value)
+  }
+
+  /**
+   * Runs quote database name.
+   * @param {string} databaseName - Database name.
+   * @returns {string} - The quote database name.
+   */
+  quoteDatabaseName(databaseName) {
+    if (databaseName.includes(this.tableQuote)) throw new Error(`Possible SQL injection in database name: ${databaseName}`)
+
+    return `${this.tableQuote}${databaseName}${this.tableQuote}`
+  }
+
+  /**
+   * Runs quote column name.
+   * @param {string} columnName - Column name.
+   * @returns {string} - The quote column name.
+   */
+  quoteColumnName(columnName) {
+    if (!columnName) throw new Error("No column name was given")
+    if (columnName.includes(this.columnQuote)) throw new Error(`Invalid column name: ${columnName}`)
+
+    return `${this.columnQuote}${columnName}${this.columnQuote}`
+  }
+
+  /**
+   * Runs quote index name.
+   * @param {string} indexName - Index name.
+   * @returns {string} - The quote index name.
+   */
+  quoteIndexName(indexName) {
+    if (!indexName || indexName.includes(this.columnQuote)) throw new Error(`Invalid column name: ${indexName}`)
+
+    return `${this.columnQuote}${indexName}${this.columnQuote}`
+  }
+
+  /**
+   * Runs quote string.
+   * @abstract
+   * @param {?} string - String.
+   * @returns {string} - The quote string.
+   */
+  quoteString(string) { // eslint-disable-line no-unused-vars
+    throw new Error("quoteString not implemented")
+  }
+
+  /**
+   * Runs quote table name.
+   * @param {string} tableName - Table name.
+   * @returns {string} - The quote table name.
+   */
+  quoteTableName(tableName) {
+    if (!tableName || tableName.includes(this.tableQuote)) throw new Error(`Invalid table name: ${tableName}`)
+
+    return `${this.tableQuote}${tableName}${this.tableQuote}`
+  }
+}
+

package/src/database/query-parser/order-parser.js

@@ -0,0 +1,45 @@
+// @ts-check
+
+export default class VelocuiousDatabaseQueryParserOrderParser {
+  /**
+   * Runs constructor.
+   * @param {object} args - Options object.
+   * @param {boolean} args.pretty - Whether pretty.
+   * @param {import("../query/index.js").default} args.query - Query instance.
+   */
+  constructor({pretty, query}) {
+    this.pretty = pretty
+    this.query = query
+  }
+
+  toSql() {
+    const {pretty, query} = this
+    let sql = ""
+
+    if (query._orders.length == 0) return sql
+
+    if (pretty) {
+      sql += "\n\n"
+    } else {
+      sql += " "
+    }
+
+    sql += "ORDER BY"
+    let count = 0
+
+    for (const order of query._orders) {
+      if (count > 0) sql += " ,"
+
+      if (pretty) {
+        sql += "\n  "
+      } else {
+        sql += " "
+      }
+
+      sql += order.toSql()
+      count++
+    }
+
+    return sql
+  }
+}

package/src/database/query-parser/select-parser.js

@@ -0,0 +1,67 @@
+// @ts-check
+
+import restArgsError from "../../utils/rest-args-error.js"
+
+export default class VelociousDatabaseQueryParserSelectParser {
+  /**
+   * Runs constructor.
+   * @param {object} args - Options object.
+   * @param {boolean} args.pretty - Whether pretty.
+   * @param {import("../query/index.js").default} args.query - Query instance.
+   */
+  constructor({pretty, query, ...restArgs}) {
+    restArgsError(restArgs)
+
+    this.pretty = pretty
+    this.query = query
+  }
+
+  toSql() {
+    const {pretty, query} = this
+
+    let sql = ""
+
+    sql += "SELECT"
+
+    if (query._distinct) {
+      sql += " DISTINCT"
+    }
+
+    if (pretty) {
+      sql += "\n"
+    } else {
+      sql += " "
+    }
+
+    let count = 0
+
+    for (const selectValue of query._selects) {
+      selectValue.setQuery(query)
+
+      sql += selectValue.toSql()
+
+      if (count + 1 < query._selects.length) {
+        if (pretty) {
+          sql += ","
+          sql += "  "
+        } else {
+          sql += ", "
+        }
+      }
+
+      count++
+    }
+
+    if (query.getSelects().length == 0) {
+      // @ts-expect-error
+      if (query.constructor.name == "VelociousDatabaseQueryModelClassQuery" && query.modelClass) {
+        // @ts-expect-error
+        sql += `${query.modelClass.connection().quoteTable(query.modelClass.tableName())}.*`
+      } else {
+        sql += "*"
+      }
+    }
+
+    return sql
+  }
+}