velocious 1.0.577 → 1.0.579

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

@@ -6,7 +6,7 @@ export default class VelociousDatabaseQueryDeleteBase extends QueryBase {
   /**
    * Runs constructor.
    * @param {object} args - Options object.
-   * @param {Record<string, ?>} args.conditions - Conditions.
+   * @param {Record<string, ReturnType<typeof JSON.parse>>} args.conditions - Conditions.
    * @param {import("../drivers/base.js").default} args.driver - Database driver instance.
    * @param {string} args.tableName - Table name.
    */

package/build/database/query/index.js

@@ -190,7 +190,7 @@ export default class VelociousDatabaseQuery {
      * @type {import("./where-base.js").default[]} */
     this._wheres = wheres
 
-    const boundWhere = /** @type {?} */ (this.where.bind(this))
+    const boundWhere = /** @type {ReturnType<typeof JSON.parse>} */ (this.where.bind(this))
     boundWhere.not = this.whereNot.bind(this)
     this.where = boundWhere
   }
@@ -240,7 +240,7 @@ export default class VelociousDatabaseQuery {
 
   /**
    * Runs get joins.
-   * @returns {Array<?>} - The joins.
+   * @returns {Array<ReturnType<typeof JSON.parse>>} - The joins.
    */
   getJoins() { return this._joins }
 
@@ -264,7 +264,7 @@ export default class VelociousDatabaseQuery {
 
   /**
    * Runs get orders.
-   * @returns {Array<?>} - The orders.
+   * @returns {Array<ReturnType<typeof JSON.parse>>} - The orders.
    */
   getOrders() { return this._orders }
 

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

@@ -6,13 +6,13 @@ export default class VelociousDatabaseQueryInsertBase {
   /**
    * Runs constructor.
    * @param {object} args - Options object.
-   * @param {Record<string, ?>} [args.data] - Data payload.
+   * @param {Record<string, ReturnType<typeof JSON.parse>>} [args.data] - Data payload.
    * @param {import("../drivers/base.js").default} args.driver - Database driver instance.
    * @param {string} args.tableName - Table name.
    * @param {Array<string>} [args.columns] - Column names.
    * @param {boolean} [args.multiple] - Whether multiple.
    * @param {string[]} [args.returnLastInsertedColumnNames] - Return last inserted column names.
-   * @param {Array<Array<?>>} [args.rows] - Rows to insert.
+   * @param {Array<Array<ReturnType<typeof JSON.parse>>>} [args.rows] - Rows to insert.
    */
   constructor({columns, data, driver, multiple, tableName, returnLastInsertedColumnNames, rows, ...restArgs}) {
     if (!driver) throw new Error("No driver given to insert base")
@@ -39,7 +39,7 @@ export default class VelociousDatabaseQueryInsertBase {
 
   /**
    * Runs format value.
-   * @param {?} value - Value to format.
+   * @param {ReturnType<typeof JSON.parse>} value - Value to format.
    * @returns {string | number} - SQL literal.
    */
   formatValue(value) {
@@ -151,7 +151,7 @@ export default class VelociousDatabaseQueryInsertBase {
 
   /**
    * Runs values sql.
-   * @param {Array<?>} data - Data payload.
+   * @param {Array<ReturnType<typeof JSON.parse>>} data - Data payload.
    * @returns {string} - SQL string.
    */
   _valuesSql(data) {

package/build/database/query/model-class-query.js

@@ -467,12 +467,12 @@ export default class VelociousDatabaseQueryModelClassQuery extends DatabaseQuery
     const froms = this.getFroms()
     const lastFrom = froms[froms.length - 1]
 
-    if (lastFrom && typeof /** @type {?} */ (lastFrom).tableName === "string") {
-      return /** @type {?} */ (lastFrom).tableName
+    if (lastFrom && typeof /** @type {ReturnType<typeof JSON.parse>} */ (lastFrom).tableName === "string") {
+      return /** @type {ReturnType<typeof JSON.parse>} */ (lastFrom).tableName
     }
 
-    if (lastFrom && typeof /** @type {?} */ (lastFrom).plain === "string") {
-      const parsedReference = parseFromPlainTableReference(/** @type {?} */ (lastFrom).plain)
+    if (lastFrom && typeof /** @type {ReturnType<typeof JSON.parse>} */ (lastFrom).plain === "string") {
+      const parsedReference = parseFromPlainTableReference(/** @type {ReturnType<typeof JSON.parse>} */ (lastFrom).plain)
 
       if (parsedReference) return parsedReference
     }
@@ -754,7 +754,7 @@ export default class VelociousDatabaseQueryModelClassQuery extends DatabaseQuery
    * Executes a bulk UPDATE on all rows matching the query's WHERE
    * clause. Bypasses model lifecycle callbacks — use this for
    * efficient batch updates where per-row hooks aren't needed.
-   * @param {Record<string, ?>} data - camelCase attribute names → values.
+   * @param {Record<string, ReturnType<typeof JSON.parse>>} data - camelCase attribute names → values.
    * @returns {Promise<void>} - Resolves when the update completes.
    */
   async updateAll(data) {
@@ -831,7 +831,7 @@ export default class VelociousDatabaseQueryModelClassQuery extends DatabaseQuery
   /**
    * Runs find or create by.
    * @param {{[key: string]: string | number}} conditions - Conditions hash keyed by attribute name.
-   * @param {function(InstanceType<MC>) : void} [callback] - Callback function.
+   * @param {(arg: InstanceType<MC>) => void} [callback] - Callback function.
    * @returns {Promise<InstanceType<MC>>} - Resolves with the or create by.
    */
   async findOrCreateBy(conditions, callback) {
@@ -861,8 +861,8 @@ export default class VelociousDatabaseQueryModelClassQuery extends DatabaseQuery
 
   /**
    * Runs find or initialize by.
-   * @param {Record<string, ?>} conditions - Conditions.
-   * @param {function(InstanceType<MC>) : void} [callback] - Callback function.
+   * @param {Record<string, ReturnType<typeof JSON.parse>>} conditions - Conditions.
+   * @param {(arg: InstanceType<MC>) => void} [callback] - Callback function.
    * @returns {Promise<InstanceType<MC>>} - Resolves with the or initialize by.
    */
   async findOrInitializeBy(conditions, callback) {
@@ -881,7 +881,7 @@ export default class VelociousDatabaseQueryModelClassQuery extends DatabaseQuery
 
   /**
    * Builds a record owned by the query's operation, when present.
-   * @param {Record<string, ?>} [attributes] - Initial attributes.
+   * @param {Record<string, ReturnType<typeof JSON.parse>>} [attributes] - Initial attributes.
    * @returns {InstanceType<MC>} - Built record.
    */
   build(attributes = {}) {
@@ -895,7 +895,7 @@ export default class VelociousDatabaseQueryModelClassQuery extends DatabaseQuery
 
   /**
    * Creates a record owned by the query's operation, when present.
-   * @param {Record<string, ?>} [attributes] - Initial attributes.
+   * @param {Record<string, ReturnType<typeof JSON.parse>>} [attributes] - Initial attributes.
    * @returns {Promise<InstanceType<MC>>} - Created record.
    */
   async create(attributes = {}) {
@@ -1003,7 +1003,7 @@ export default class VelociousDatabaseQueryModelClassQuery extends DatabaseQuery
   /**
    * Plucks one or more columns directly from the database without instantiating models.
    * @param {...string|string[]} columns - Column names.
-   * @returns {Promise<Array<?>>} - Resolves with the pluck.
+   * @returns {Promise<Array<ReturnType<typeof JSON.parse>>>} - Resolves with the pluck.
    */
   async pluck(...columns) {
     const flatColumns = columns.flat()
@@ -1030,11 +1030,11 @@ export default class VelociousDatabaseQueryModelClassQuery extends DatabaseQuery
 
     if (columnNames.length === 1) {
       const [columnName] = columnNames
-      return rows.map((row) => /** @type {Record<string, ?>} */ (row)[columnName])
+      return rows.map((row) => /** @type {Record<string, ReturnType<typeof JSON.parse>>} */ (row)[columnName])
     }
 
     return rows.map((row) => {
-      const rowHash = /** @type {Record<string, ?>} */ (row)
+      const rowHash = /** @type {Record<string, ReturnType<typeof JSON.parse>>} */ (row)
 
       return columnNames.map((columnName) => rowHash[columnName])
     })
@@ -1080,7 +1080,7 @@ export default class VelociousDatabaseQueryModelClassQuery extends DatabaseQuery
 
   /**
    * Runs ransack.
-   * @param {Record<string, ?>} params - Ransack-style params hash. Supports `s` key for sorting (e.g., `{s: "name asc"}`).
+   * @param {Record<string, ReturnType<typeof JSON.parse>>} params - Ransack-style params hash. Supports `s` key for sorting (e.g., `{s: "name asc"}`).
    * @returns {this} - Query with Ransack filters and sort applied.
    */
   ransack(params) {
@@ -1149,7 +1149,7 @@ export default class VelociousDatabaseQueryModelClassQuery extends DatabaseQuery
 
   /**
    * Declares this query as a sync scope on the current sync client.
-   * @returns {Promise<?>} - Declared scope and pull result.
+   * @returns {Promise<ReturnType<typeof JSON.parse>>} - Declared scope and pull result.
    */
   async sync() {
     return await currentSyncClient().sync(this)
@@ -1168,7 +1168,7 @@ export default class VelociousDatabaseQueryModelClassQuery extends DatabaseQuery
  * Runs apply ransack group.
  * @param {object} args - Options.
  * @param {import("../../utils/ransack.js").RansackGroup} args.group - Normalized Ransack group.
- * @param {import("./model-class-query.js").default<?>} args.query - Query instance.
+ * @param {import("./model-class-query.js").default<ReturnType<typeof JSON.parse>>} args.query - Query instance.
  * @returns {void}
  */
 function applyRansackGroup({group, query}) {
@@ -1183,7 +1183,7 @@ function applyRansackGroup({group, query}) {
  * Runs build ransack group where.
  * @param {object} args - Options.
  * @param {import("../../utils/ransack.js").RansackGroup} args.group - Normalized Ransack group.
- * @param {import("./model-class-query.js").default<?>} args.query - Query instance.
+ * @param {import("./model-class-query.js").default<ReturnType<typeof JSON.parse>>} args.query - Query instance.
  * @returns {import("./where-base.js").default | null} - Combined where clause.
  */
 function buildRansackGroupWhere({group, query}) {
@@ -1218,7 +1218,7 @@ function buildRansackGroupWhere({group, query}) {
  * Runs build ransack condition where.
  * @param {object} args - Options.
  * @param {import("../../utils/ransack.js").RansackCondition} args.condition - Normalized Ransack condition.
- * @param {import("./model-class-query.js").default<?>} args.query - Query instance.
+ * @param {import("./model-class-query.js").default<ReturnType<typeof JSON.parse>>} args.query - Query instance.
  * @returns {import("./where-base.js").default | null} - Condition where clause.
  */
 function buildRansackConditionWhere({condition, query}) {
@@ -1246,7 +1246,7 @@ function buildRansackConditionWhere({condition, query}) {
  * @param {object} args - Options.
  * @param {import("../../utils/ransack.js").RansackAttribute} args.attribute - Normalized Ransack attribute.
  * @param {import("../../utils/ransack.js").RansackCondition} args.condition - Normalized Ransack condition.
- * @param {import("./model-class-query.js").default<?>} args.query - Query instance.
+ * @param {import("./model-class-query.js").default<ReturnType<typeof JSON.parse>>} args.query - Query instance.
  * @returns {import("./where-base.js").default} - Attribute where clause.
  */
 function buildRansackAttributeWhere({attribute, condition, query}) {
@@ -1280,7 +1280,7 @@ function buildRansackAttributeWhere({attribute, condition, query}) {
  * @param {object} args - Options.
  * @param {import("../../utils/ransack.js").RansackAttribute} args.attribute - Normalized Ransack attribute.
  * @param {import("../../utils/ransack.js").RansackCondition} args.condition - Normalized Ransack condition.
- * @returns {Record<string, ?>} - Nested hash suitable for query where nodes.
+ * @returns {Record<string, ReturnType<typeof JSON.parse>>} - Nested hash suitable for query where nodes.
  */
 function buildRansackAttributeHash({attribute, condition}) {
   if (condition.predicate === "eq" || condition.predicate === "in" || condition.predicate === "not_eq" || condition.predicate === "not_in") {
@@ -1302,13 +1302,13 @@ function buildRansackAttributeHash({attribute, condition}) {
  * Runs build nested ransack hash.
  * @param {object} args - Options.
  * @param {import("../../utils/ransack.js").RansackAttribute} args.attribute - Normalized Ransack attribute.
- * @param {?} args.value - Final value.
- * @returns {Record<string, ?>} - Nested hash suitable for query where nodes.
+ * @param {ReturnType<typeof JSON.parse>} args.value - Final value.
+ * @returns {Record<string, ReturnType<typeof JSON.parse>>} - Nested hash suitable for query where nodes.
  */
 function buildNestedRansackHash({attribute, value}) {
   /**
    * Hash.
-   * @type {Record<string, ?>} */
+   * @type {Record<string, ReturnType<typeof JSON.parse>>} */
   let hash = {[attribute.attributeName]: value}
 
   for (let index = attribute.path.length - 1; index >= 0; index -= 1) {
@@ -1323,13 +1323,13 @@ function buildNestedRansackHash({attribute, value}) {
  * @param {object} args - Options.
  * @param {import("../../utils/ransack.js").RansackAttribute} args.attribute - Normalized Ransack attribute.
  * @param {"gt" | "gteq" | "lt" | "lteq" | "like"} args.operator - Tuple operator.
- * @param {?} args.value - Final value.
- * @returns {Record<string, ?>} - Nested tuple hash suitable for query.where.
+ * @param {ReturnType<typeof JSON.parse>} args.value - Final value.
+ * @returns {Record<string, ReturnType<typeof JSON.parse>>} - Nested tuple hash suitable for query.where.
  */
 function buildNestedRansackTupleHash({attribute, operator, value}) {
   /**
    * Hash.
-   * @type {Record<string, ?>} */
+   * @type {Record<string, ReturnType<typeof JSON.parse>>} */
   let hash = {
     [attribute.attributeName]: [[attribute.attributeName, operator, value]]
   }
@@ -1357,7 +1357,7 @@ function ransackTupleOperator(predicate) {
 /**
  * Runs ransack tuple value.
  * @param {import("../../utils/ransack.js").RansackCondition} condition - Ransack condition.
- * @returns {?} - Query tuple value.
+ * @returns {ReturnType<typeof JSON.parse>} - Query tuple value.
  */
 function ransackTupleValue(condition) {
   if (condition.predicate === "cont") return `%${condition.value}%`
@@ -1397,18 +1397,18 @@ function resolveColumnName(modelClass, key) {
 /**
  * Runs split where hash.
  * @param {object} args - Options.
- * @param {Record<string, ?>} args.hash - Where hash.
+ * @param {Record<string, ReturnType<typeof JSON.parse>>} args.hash - Where hash.
  * @param {typeof import("../record/index.js").default} args.modelClass - Model class.
- * @returns {{resolvedHash: Record<string, ?>, fallbackHash: Record<string, ?>}} - Split hashes.
+ * @returns {{resolvedHash: Record<string, ReturnType<typeof JSON.parse>>, fallbackHash: Record<string, ReturnType<typeof JSON.parse>>}} - Split hashes.
  */
 function splitWhereHash({hash, modelClass}) {
   /**
    * Resolved hash.
-   * @type {Record<string, ?>} */
+   * @type {Record<string, ReturnType<typeof JSON.parse>>} */
   const resolvedHash = {}
   /**
    * Fallback hash.
-   * @type {Record<string, ?>} */
+   * @type {Record<string, ReturnType<typeof JSON.parse>>} */
   const fallbackHash = {}
 
   for (const key in hash) {
@@ -1459,14 +1459,14 @@ function splitWhereHash({hash, modelClass}) {
 /**
  * Runs build join object from where hash.
  * @param {object} args - Options.
- * @param {Record<string, ?>} args.hash - Where hash.
+ * @param {Record<string, ReturnType<typeof JSON.parse>>} args.hash - Where hash.
  * @param {typeof import("../record/index.js").default} args.modelClass - Model class.
- * @returns {Record<string, ?>} - Join object.
+ * @returns {Record<string, ReturnType<typeof JSON.parse>>} - Join object.
  */
 function buildJoinObjectFromWhereHash({hash, modelClass}) {
   /**
    * Join object.
-   * @type {Record<string, ?>} */
+   * @type {Record<string, ReturnType<typeof JSON.parse>>} */
   const joinObject = {}
 
   for (const key in hash) {
@@ -1514,7 +1514,7 @@ function normalizeRelationshipWhereOperator(operator) {
 
 /**
  * Runs is relationship where operator tuple.
- * @param {?} tupleValue - Candidate tuple.
+ * @param {ReturnType<typeof JSON.parse>} tupleValue - Candidate tuple.
  * @returns {boolean} - Whether this is a relationship where tuple.
  */
 function isRelationshipWhereOperatorTuple(tupleValue) {
@@ -1529,7 +1529,7 @@ function isRelationshipWhereOperatorTuple(tupleValue) {
 
 /**
  * Runs normalize relationship where operator tuples.
- * @param {?} value - Candidate value.
+ * @param {ReturnType<typeof JSON.parse>} value - Candidate value.
  * @returns {Array<[string, "eq" | "notEq" | "gt" | "gteq" | "lt" | "lteq" | "like", unknown]>} - Normalized tuples.
  */
 function normalizeRelationshipWhereOperatorTuples(value) {
@@ -1543,7 +1543,7 @@ function normalizeRelationshipWhereOperatorTuples(value) {
   const normalized = []
     /**
      * Add condition.
-     * @param {?} conditionValue - Candidate nested condition.
+     * @param {ReturnType<typeof JSON.parse>} conditionValue - Candidate nested condition.
      */
     const addCondition = (conditionValue) => {
       if (isRelationshipWhereOperatorTuple(conditionValue)) {
@@ -1569,7 +1569,7 @@ function normalizeRelationshipWhereOperatorTuples(value) {
       throw new Error("Relationship where conditions must be tuples")
     }
 
-    /** @type {Array<?>} */ (conditionValue).forEach((nestedConditionValue) => {
+    /** @type {Array<ReturnType<typeof JSON.parse>>} */ (conditionValue).forEach((nestedConditionValue) => {
       addCondition(nestedConditionValue)
     })
   }
@@ -1585,7 +1585,7 @@ function normalizeRelationshipWhereOperatorTuples(value) {
 
 /**
  * Runs has relationship where operator tuples.
- * @param {?} value - Candidate relationship where value.
+ * @param {ReturnType<typeof JSON.parse>} value - Candidate relationship where value.
  * @returns {boolean} - Whether value can be normalized to relationship tuples.
  */
 function hasRelationshipWhereOperatorTuples(value) {

package/build/database/query/preloader/belongs-to.js

@@ -85,7 +85,7 @@ export default class VelociousDatabaseQueryPreloaderBelongsTo {
 
     // Only query when at least one model has a non-null foreign key.
     if (foreignKeyValues.size > 0) {
-      await ensureModelClassInitialized(targetModelClass, this.relationship.getConfiguration())
+      await ensureModelClassInitialized(targetModelClass, this.relationship.getConfiguration(), modelsToLoad[0])
 
       /**
        * Where args.
@@ -203,7 +203,7 @@ export default class VelociousDatabaseQueryPreloaderBelongsTo {
     for (const targetType in foreignKeyValuesByType) {
       const targetModelClass = configuration.getModelClass(targetType)
 
-      await ensureModelClassInitialized(targetModelClass, configuration)
+      await ensureModelClassInitialized(targetModelClass, configuration, this.models[0])
 
       /**
        * Where args.

package/build/database/query/preloader/ensure-model-class-initialized.js

@@ -4,10 +4,11 @@
  * Runs ensure model class initialized.
  * @param {typeof import("../../record/index.js").default} modelClass - Model class to initialize.
  * @param {import("../../../configuration.js").default} configuration - Current configuration.
+ * @param {import("../../record/index.js").default} sourceModel - Operation-owning source record.
  * @returns {Promise<void>} - Resolves when the model class is initialized.
  */
-export default async function ensureModelClassInitialized(modelClass, configuration) {
+export default async function ensureModelClassInitialized(modelClass, configuration, sourceModel) {
   if (modelClass.isInitialized()) return
 
-  await modelClass.ensureInitialized({configuration})
+  await sourceModel.ensureModelClassInitialized(modelClass, configuration)
 }

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

@@ -124,8 +124,8 @@ export default class VelociousDatabaseQueryPreloaderHasMany {
 
     const configuration = this.relationship.getConfiguration()
 
-    await ensureModelClassInitialized(throughModelClass, configuration)
-    await ensureModelClassInitialized(targetModelClass, configuration)
+    await ensureModelClassInitialized(throughModelClass, configuration, modelsToLoad[0])
+    await ensureModelClassInitialized(targetModelClass, configuration, modelsToLoad[0])
 
     const throughForeignKey = throughRelationship.getForeignKey()
 
@@ -298,7 +298,7 @@ export default class VelociousDatabaseQueryPreloaderHasMany {
       whereArgs[typeColumn] = this.relationship.getModelClass().getModelName()
     }
 
-    await ensureModelClassInitialized(targetModelClass, this.relationship.getConfiguration())
+    await ensureModelClassInitialized(targetModelClass, this.relationship.getConfiguration(), modelsToLoad[0])
 
     let query = preloadQueryForModel(modelsToLoad, targetModelClass).where(whereArgs)
 

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

@@ -85,7 +85,7 @@ export default class VelociousDatabaseQueryPreloaderHasOne {
       whereArgs[typeColumn] = this.relationship.getModelClass().getModelName()
     }
 
-    await ensureModelClassInitialized(targetModelClass, this.relationship.getConfiguration())
+    await ensureModelClassInitialized(targetModelClass, this.relationship.getConfiguration(), this.models[0])
 
     // Load target models to be preloaded on the given models
     let query = preloadQueryForModel(this.models, targetModelClass).where(whereArgs)

package/build/database/query/preloader.js

@@ -94,7 +94,7 @@ export default class VelociousDatabaseQueryPreloader {
     // instead of duplicating it here.
     const query = isQuery
       ? /** @type {import("./model-class-query.js").default} */ (queryOrSpec)
-      : modelClass.preload(/** @type {?} */ (queryOrSpec))
+      : modelClass.preload(/** @type {ReturnType<typeof JSON.parse>} */ (queryOrSpec))
 
     const preloader = new VelociousDatabaseQueryPreloader({
       modelClass,
@@ -131,7 +131,14 @@ export default class VelociousDatabaseQueryPreloader {
 
   async run() {
     for (const preloadRelationshipName in this.preload) {
-      const relationship = this.modelClass.getRelationshipByName(preloadRelationshipName)
+      const modelClassRelationship = this.modelClass.getRelationshipByName(preloadRelationshipName)
+      const relationship = this.models.length > 0 ? modelClassRelationship.resolveForRecord(this.models[0]) : modelClassRelationship
+
+      for (const model of this.models) {
+        if (modelClassRelationship.resolveForRecord(model) !== relationship) {
+          throw new Error(`Cannot preload ${this.modelClass.name}#${preloadRelationshipName} across physical database identities`)
+        }
+      }
       let preloadResult
 
       if (relationship.getType() == "belongsTo") {

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

@@ -11,7 +11,7 @@ import {isPlainObject} from "is-plain-object"
 
 /**
  * Defines this typedef.
- * @typedef {string | Array<string | Record<string, ?>> | {[key: string]: true | false | string | string[] | Record<string, ?>}} QueryDataSpec
+ * @typedef {string | Array<string | Record<string, ReturnType<typeof JSON.parse>>> | {[key: string]: true | false | string | string[] | Record<string, ReturnType<typeof JSON.parse>>}} QueryDataSpec
  */
 
 /**
@@ -69,7 +69,7 @@ export function normalizeQueryDataSpec(spec, chain = []) {
       }
 
       if (isPlainObject(item)) {
-        for (const nested of normalizeQueryDataSpec(/** @type {?} */ (item), chain)) {
+        for (const nested of normalizeQueryDataSpec(/** @type {ReturnType<typeof JSON.parse>} */ (item), chain)) {
           entries.push(nested)
         }
         continue
@@ -96,7 +96,7 @@ export function normalizeQueryDataSpec(spec, chain = []) {
       if (value === false) continue
 
       if (typeof value === "string" || Array.isArray(value) || isPlainObject(value)) {
-        for (const nested of normalizeQueryDataSpec(/** @type {?} */ (value), [...chain, key])) {
+        for (const nested of normalizeQueryDataSpec(/** @type {ReturnType<typeof JSON.parse>} */ (value), [...chain, key])) {
           entries.push(nested)
         }
         continue
@@ -117,14 +117,14 @@ export function normalizeQueryDataSpec(spec, chain = []) {
  * 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.
+ * @returns {true | Record<string, ReturnType<typeof JSON.parse>>} - Nested join descriptor, or `true` when the chain is empty.
  */
 function buildNestedJoinDescriptor(chain) {
   if (chain.length === 0) return true
 
   /**
    * Obj.
-   * @type {Record<string, ?>} */
+   * @type {Record<string, ReturnType<typeof JSON.parse>>} */
   const obj = {}
   let cursor = obj
 
@@ -269,7 +269,7 @@ function prepareEntry({entry, entryIndex, primaryKey, rootIds, rootModelClass, s
 
   /**
    * Root where.
-   * @type {Record<string, ?>} */
+   * @type {Record<string, ReturnType<typeof JSON.parse>>} */
   const rootWhere = {}
   rootWhere[primaryKey] = rootIds
   query.where(rootWhere)
@@ -341,7 +341,7 @@ function selectedAliases(query) {
  * @returns {Promise<void>}
  */
 async function executeEntryQuery({primaryKey, query, rootModels}) {
-  const rows = /** @type {Array<Record<string, ?>>} */ (await query._executeQuery())
+  const rows = /** @type {Array<Record<string, ReturnType<typeof JSON.parse>>>} */ (await query._executeQuery())
   const byParent = new Map()
 
   for (const row of rows) {

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

@@ -4,8 +4,8 @@ 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 {Record<string, ReturnType<typeof JSON.parse>>} args.conditions - Conditions.
+   * @param {Record<string, ReturnType<typeof JSON.parse>>} args.data - Data payload.
    * @param {import("../drivers/base.js").default} args.driver - Database driver instance.
    * @param {string} args.tableName - Table name.
    */
@@ -26,7 +26,7 @@ export default class VelociousDatabaseQueryUpdateBase {
 
   /**
    * Runs format value.
-   * @param {?} value - Value to format.
+   * @param {ReturnType<typeof JSON.parse>} value - Value to format.
    * @returns {string | number} - SQL literal.
    */
   formatValue(value) {

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

@@ -7,7 +7,7 @@ export default class VelociousDatabaseQueryUpsertBase {
    * Runs constructor.
    * @param {object} args - Options object.
    * @param {Array<string>} args.conflictColumns - Columns that identify duplicates.
-   * @param {Record<string, ?>} args.data - Data payload.
+   * @param {Record<string, ReturnType<typeof JSON.parse>>} args.data - Data payload.
    * @param {import("../drivers/base.js").default} args.driver - Database driver instance.
    * @param {Array<string>} args.updateColumns - Columns to update on conflict.
    * @param {string} args.tableName - Table name.
@@ -47,7 +47,7 @@ export default class VelociousDatabaseQueryUpsertBase {
 
   /**
    * Runs format value.
-   * @param {?} value - Value to format.
+   * @param {ReturnType<typeof JSON.parse>} value - Value to format.
    * @returns {string | number} - SQL literal.
    */
   formatValue(value) {

package/build/database/query/where-model-class-hash.js

@@ -6,7 +6,7 @@ import WhereBase from "./where-base.js"
 
 /**
  * No match.
- * @typedef {{[key: string]: string | number | boolean | null | Array<string | number | boolean | null> | Record<string, ?>}} WhereHash
+ * @typedef {{[key: string]: string | number | boolean | null | Array<string | number | boolean | null> | Record<string, ReturnType<typeof JSON.parse>>}} WhereHash
  */
 
 const NO_MATCH = Symbol("no-match")
@@ -107,7 +107,7 @@ export default class VelociousDatabaseQueryWhereModelClassHash extends WhereBase
 
   /**
    * Runs is relationship where operator tuple.
-   * @param {?} tupleValue - Candidate tuple.
+   * @param {ReturnType<typeof JSON.parse>} tupleValue - Candidate tuple.
    * @returns {boolean} - Whether this is a relationship where tuple.
    */
   _isRelationshipWhereOperatorTuple(tupleValue) {
@@ -122,7 +122,7 @@ export default class VelociousDatabaseQueryWhereModelClassHash extends WhereBase
 
   /**
    * Runs normalize relationship where operator tuples.
-   * @param {?} value - Candidate relationship where value.
+   * @param {ReturnType<typeof JSON.parse>} value - Candidate relationship where value.
    * @returns {Array<[string, "eq" | "notEq" | "gt" | "gteq" | "lt" | "lteq" | "like", unknown]>} - Normalized tuples.
    */
   _normalizeRelationshipWhereOperatorTuples(value) {
@@ -136,7 +136,7 @@ export default class VelociousDatabaseQueryWhereModelClassHash extends WhereBase
     const normalized = []
     /**
      * Add condition.
-     * @param {?} conditionValue - Candidate nested condition.
+     * @param {ReturnType<typeof JSON.parse>} conditionValue - Candidate nested condition.
      */
     const addCondition = (conditionValue) => {
       if (this._isRelationshipWhereOperatorTuple(conditionValue)) {
@@ -178,7 +178,7 @@ export default class VelociousDatabaseQueryWhereModelClassHash extends WhereBase
 
   /**
    * Runs is relationship where operator tuple container.
-   * @param {?} value - Candidate relationship where value.
+   * @param {ReturnType<typeof JSON.parse>} value - Candidate relationship where value.
    * @returns {boolean} - Whether value can be normalized to relationship tuples.
    */
   _isRelationshipWhereOperatorTupleContainer(value) {
@@ -302,8 +302,8 @@ export default class VelociousDatabaseQueryWhereModelClassHash extends WhereBase
    * @param {object} args - Options object.
    * @param {typeof import("../record/index.js").default} args.modelClass - Model class.
    * @param {string} args.columnName - Column name.
-   * @param {?} args.value - Value to normalize.
-   * @returns {?} - Normalized value.
+   * @param {ReturnType<typeof JSON.parse>} args.value - Value to normalize.
+   * @returns {ReturnType<typeof JSON.parse>} - Normalized value.
    */
   _normalizeSqliteBooleanValue({modelClass, columnName, value}) {
     if (modelClass.getDatabaseType() != "sqlite") return value
@@ -315,8 +315,8 @@ export default class VelociousDatabaseQueryWhereModelClassHash extends WhereBase
 
     /**
      * Normalize.
-     * @param {?} entry - Value to normalize.
-     * @returns {?} - SQLite predicate value with booleans encoded as 1 or 0.
+     * @param {ReturnType<typeof JSON.parse>} entry - Value to normalize.
+     * @returns {ReturnType<typeof JSON.parse>} - SQLite predicate value with booleans encoded as 1 or 0.
      */
     const normalize = (entry) => {
       if (entry === true) return 1
@@ -336,8 +336,8 @@ export default class VelociousDatabaseQueryWhereModelClassHash extends WhereBase
    * @param {object} args - Options object.
    * @param {typeof import("../record/index.js").default} args.modelClass - Model class.
    * @param {string} args.columnName - Column name.
-   * @param {?} args.value - Value to normalize.
-   * @returns {?} - Normalized value.
+   * @param {ReturnType<typeof JSON.parse>} args.value - Value to normalize.
+   * @returns {ReturnType<typeof JSON.parse>} - Normalized value.
    */
   _normalizeValueForColumnType({modelClass, columnName, value}) {
     const columnType = modelClass.getColumnTypeByName(columnName)
@@ -353,8 +353,8 @@ export default class VelociousDatabaseQueryWhereModelClassHash extends WhereBase
 
     /**
      * Normalize.
-     * @param {?} entry - Value to normalize.
-     * @returns {?} - Column-compatible predicate value, or the no-match sentinel for numeric UUIDs.
+     * @param {ReturnType<typeof JSON.parse>} entry - Value to normalize.
+     * @returns {ReturnType<typeof JSON.parse>} - Column-compatible predicate value, or the no-match sentinel for numeric UUIDs.
      */
     const normalize = (entry) => {
       if (isUuidType && typeof entry === "number") return NO_MATCH