velocious 1.0.515 → 1.0.516

package/src/database/record/validators/uniqueness.js

@@ -74,9 +74,9 @@ export default class VelociousDatabaseRecordValidatorsUniqueness extends Base {
    * `new Task({project})`, the FK (`projectId`) is only flushed onto
    * the attribute store during save — but the relationship object is
    * already loaded and carries the id we need for the WHERE clause.
-   * @param {import("../index.js").default} model
+   * @param {import("../index.js").default} model - Record whose loaded relationship may supply the scope value.
    * @param {string} scopeColumn - camelCase attribute name (e.g. `"projectId"`).
-   * @returns {string | number | null}
+   * @returns {string | number | null} - Value normalized for comparison.
    */
   _resolveScopeValueFromRelationship(model, scopeColumn) {
     const modelClass = /** @type {typeof import("../index.js").default} */ (model.constructor)
@@ -106,7 +106,7 @@ export default class VelociousDatabaseRecordValidatorsUniqueness extends Base {
    * Normalize the `scope` option into an array of attribute names.
    * Supports string (`"userId"`), array of strings (`["userId", "projectId"]`),
    * or absent (empty array — no scope, original single-column behavior).
-   * @returns {string[]}
+   * @returns {string[]} - Columns participating in the uniqueness check.
    */
   _normalizeScopeColumns() {
     const scope = this.args?.scope

package/src/database/tenants/data-copier.js

@@ -6,9 +6,9 @@ const DEFAULT_QUERY_CHUNK_SIZE = 500
 /**
  * Splits an array into chunks of at most `chunkSize` items.
  * @template T
- * @param {T[]} values
- * @param {number} chunkSize
- * @returns {T[][]}
+ * @param {T[]} values - Ordered items to partition.
+ * @param {number} chunkSize - Maximum items per chunk.
+ * @returns {T[][]} - Consecutive chunks preserving input order.
  */
 function chunks(values, chunkSize) {
   const chunkedValues = []
@@ -22,8 +22,8 @@ function chunks(values, chunkSize) {
 
 /**
  * Stringifies values and returns the distinct, non-blank ones, preserving first-seen order.
- * @param {unknown[]} values
- * @returns {string[]}
+ * @param {unknown[]} values - Candidate database identifiers to stringify and deduplicate.
+ * @returns {string[]} - Distinct non-blank identifiers in first-seen order.
  */
 function uniqueStrings(values) {
   return Array.from(new Set(values.map((value) => String(value)).filter((value) => value.trim())))
@@ -60,7 +60,7 @@ export default class DataCopier {
    *   insertChunkSize?: number,
    *   queryChunkSize?: number,
    *   onProgress?: (message: string) => void
-   * }} args
+   * }} args - Source, target, traversal plan, chunk limits, and progress handler.
    */
   constructor({sourceDb, targetDb, tablePlan, idColumn = "id", insertChunkSize = DEFAULT_INSERT_CHUNK_SIZE, queryChunkSize = DEFAULT_QUERY_CHUNK_SIZE, onProgress}) {
     this.sourceDb = sourceDb
@@ -77,8 +77,8 @@ export default class DataCopier {
    * returns the copied source rows keyed by table name. The target's current tenant rows
    * are deleted (children first) and the source rows inserted (parents first) in a single
    * target transaction with foreign keys disabled.
-   * @param {string} keyValue
-   * @returns {Promise<Map<string, Record<string, unknown>[]>>}
+   * @param {string} keyValue - Tenant key selecting the rows to copy.
+   * @returns {Promise<Map<string, Record<string, unknown>[]>>} - Copied source rows grouped by table name.
    */
   async copy(keyValue) {
     const sourceRowsByTableName = await this.loadRows(this.sourceDb, keyValue)
@@ -125,9 +125,9 @@ export default class DataCopier {
    * Loads the rows for `keyValue` for every table in the plan from `db`, resolving
    * parent-scoped tables from the ids already selected for their parent table. Used for
    * both the source rows to copy and the target's current tenant rows to delete.
-   * @param {import("../drivers/base.js").default} db
-   * @param {string} keyValue
-   * @returns {Promise<Map<string, Record<string, unknown>[]>>}
+   * @param {import("../drivers/base.js").default} db - Source or target database to traverse.
+   * @param {string} keyValue - Tenant key selecting the root plan rows.
+   * @returns {Promise<Map<string, Record<string, unknown>[]>>} - Loaded rows grouped by table name.
    */
   async loadRows(db, keyValue) {
     /** @type {Map<string, string[]>} */
@@ -175,8 +175,8 @@ export default class DataCopier {
 
   /**
    * Selects all rows of `tableName` in `db` whose `columnName` is in `values`, chunked.
-   * @param {{columnName: string, db: import("../drivers/base.js").default, tableName: string, values: string[]}} args
-   * @returns {Promise<Record<string, unknown>[]>}
+   * @param {{columnName: string, db: import("../drivers/base.js").default, tableName: string, values: string[]}} args - Table, column, database, and values for the chunked lookup.
+   * @returns {Promise<Record<string, unknown>[]>} - Rows matching the supplied column values.
    */
   async queryRowsByColumn({columnName, db, tableName, values}) {
     const normalizedValues = uniqueStrings(values)
@@ -201,7 +201,7 @@ export default class DataCopier {
   /**
    * Deletes the matching target rows for every plan table, children before parents, so the
    * reinsert that follows starts from a clean slate without violating foreign keys.
-   * @param {Map<string, Record<string, unknown>[]>} rowsByTableName
+   * @param {Map<string, Record<string, unknown>[]>} rowsByTableName - Rows grouped by table name.
    * @returns {Promise<void>}
    */
   async deleteTargetRows(rowsByTableName) {
@@ -227,7 +227,7 @@ export default class DataCopier {
   /**
    * Inserts the loaded source rows into the target for every plan table, parents before
    * children, chunked to bound statement size.
-   * @param {Map<string, Record<string, unknown>[]>} rowsByTableName
+   * @param {Map<string, Record<string, unknown>[]>} rowsByTableName - Rows grouped by table name.
    * @returns {Promise<void>}
    */
   async insertTargetRows(rowsByTableName) {
@@ -256,9 +256,9 @@ export default class DataCopier {
 
   /**
    * Quotes and comma-joins values for an SQL `IN (...)` list against the given database.
-   * @param {import("../drivers/base.js").default} db
-   * @param {string[]} values
-   * @returns {string}
+   * @param {import("../drivers/base.js").default} db - Database whose quoting rules format the values.
+   * @param {string[]} values - Values to quote for the `IN` list.
+   * @returns {string} - Quoted SQL value list.
    */
   quotedValuesSql(db, values) {
     return values.map((value) => db.quote(value)).join(", ")
@@ -266,9 +266,9 @@ export default class DataCopier {
 
   /**
    * Runs a query without per-query logging, used for the high-volume copy statements.
-   * @param {import("../drivers/base.js").default} db
-   * @param {string} sql
-   * @returns {Promise<Record<string, unknown>[]>}
+   * @param {import("../drivers/base.js").default} db - Database on which to execute the copy query.
+   * @param {string} sql - Copy-related SQL statement to execute quietly.
+   * @returns {Promise<Record<string, unknown>[]>} - Query result rows.
    */
   async executeQuietQuery(db, sql) {
     return await db.query(sql, {logQuery: false})
@@ -276,7 +276,7 @@ export default class DataCopier {
 
   /**
    * Inserts column-aligned row tuples into a table without per-query logging.
-   * @param {{columns: string[], db: import("../drivers/base.js").default, rows: Array<Array<unknown>>, tableName: string}} args
+   * @param {{columns: string[], db: import("../drivers/base.js").default, rows: Array<Array<unknown>>, tableName: string}} args - Destination table and column-aligned row values to insert.
    * @returns {Promise<void>}
    */
   async insertRowsQuietly({columns, db, rows, tableName}) {
@@ -285,7 +285,7 @@ export default class DataCopier {
 
   /**
    * Forwards a progress message to the optional `onProgress` callback when one was given.
-   * @param {string} message
+   * @param {string} message - Copy progress message to forward when reporting is enabled.
    * @returns {void}
    */
   reportProgress(message) {

package/src/database/tenants/schema-cloner.js

@@ -31,7 +31,7 @@ const TEXT_TYPE_RANKS = {
 export default class SchemaCloner {
   /**
    * Creates a cloner that copies table structure from `sourceDb` into `targetDb`.
-   * @param {{sourceDb: import("../drivers/base.js").default, targetDb: import("../drivers/base.js").default}} args
+   * @param {{sourceDb: import("../drivers/base.js").default, targetDb: import("../drivers/base.js").default}} args - Databases to clone structure from and into.
    */
   constructor({sourceDb, targetDb}) {
     this.sourceDb = sourceDb
@@ -41,7 +41,7 @@ export default class SchemaCloner {
   /**
    * Clones every given table from the source into the target, then baselines the
    * target's ledger so the cloned schema is recorded as already-migrated.
-   * @param {string[]} tableNames
+   * @param {string[]} tableNames - Source tables whose structure should be cloned.
    * @returns {Promise<void>}
    */
   async syncTables(tableNames) {
@@ -55,7 +55,7 @@ export default class SchemaCloner {
   /**
    * Clones a single table from the source into the target, creating it or adding and
    * widening columns and indexes as needed.
-   * @param {string} tableName
+   * @param {string} tableName - Source table to synchronize with the target.
    * @returns {Promise<void>}
    */
   async syncTable(tableName) {
@@ -82,7 +82,7 @@ export default class SchemaCloner {
   /**
    * Creates the table in the target from the source table's columns and its
    * non-primary-key indexes.
-   * @param {{sourceTable: import("../drivers/base-table.js").default, tableName: string}} args
+   * @param {{sourceTable: import("../drivers/base-table.js").default, tableName: string}} args - Source table metadata and target table name.
    * @returns {Promise<void>}
    */
   async createTargetTable({sourceTable, tableName}) {
@@ -105,7 +105,7 @@ export default class SchemaCloner {
   /**
    * Adds columns present on the source but missing from the target, and widens
    * too-narrow target text columns.
-   * @param {{sourceTable: import("../drivers/base-table.js").default, tableName: string}} args
+   * @param {{sourceTable: import("../drivers/base-table.js").default, tableName: string}} args - Source table metadata and target table name.
    * @returns {Promise<boolean>} Whether any column was added or widened.
    */
   async ensureTargetColumns({sourceTable, tableName}) {
@@ -154,7 +154,7 @@ export default class SchemaCloner {
    * Creates non-primary-key indexes present on the source but missing from the target,
    * and replaces target indexes whose definition (columns or uniqueness) drifted from
    * the source.
-   * @param {{sourceTable: import("../drivers/base-table.js").default, tableName: string}} args
+   * @param {{sourceTable: import("../drivers/base-table.js").default, tableName: string}} args - Source table metadata and target table name.
    * @returns {Promise<void>}
    */
   async ensureTargetIndexes({sourceTable, tableName}) {
@@ -230,7 +230,7 @@ export default class SchemaCloner {
 
   /**
    * Drops an index on the target database.
-   * @param {{tableName: string, targetIndex: import("../drivers/base-columns-index.js").default}} args
+   * @param {{tableName: string, targetIndex: import("../drivers/base-columns-index.js").default}} args - Target table and index to remove.
    * @returns {Promise<void>}
    */
   async dropTargetIndex({tableName, targetIndex}) {
@@ -252,7 +252,7 @@ export default class SchemaCloner {
   /**
    * Whether the target ledger is missing any version applied on the source — i.e. the
    * target schema may have been advanced out of band without recording it.
-   * @returns {Promise<boolean>}
+   * @returns {Promise<boolean>} - Whether the target ledger differs from the source.
    */
   async ledgerDriftsFromSource() {
     if (!await MigrationsLedger.tableExists(this.targetDb)) {
@@ -268,8 +268,8 @@ export default class SchemaCloner {
   /**
    * Maps a source index into a TableData index for table creation (SQLite omits the
    * index name so the driver can generate a unique one).
-   * @param {import("../drivers/base-columns-index.js").default} sourceIndex
-   * @returns {TableIndex}
+   * @param {import("../drivers/base-columns-index.js").default} sourceIndex - Source index definition.
+   * @returns {TableIndex} - Framework-independent index definition.
    */
   tableDataIndexFromSourceIndex(sourceIndex) {
     /** @type {{name?: string, unique: boolean}} */
@@ -289,8 +289,8 @@ export default class SchemaCloner {
   /**
    * Builds driver create-index args from a source index (the index name is omitted on
    * SQLite, where index names are unique per-database rather than per-table).
-   * @param {{sourceIndex: import("../drivers/base-columns-index.js").default, tableName: string}} args
-   * @returns {{columns: string[], name?: string, tableName: string, unique: boolean}}
+   * @param {{sourceIndex: import("../drivers/base-columns-index.js").default, tableName: string}} args - Source index and target table receiving it.
+   * @returns {{columns: string[], name?: string, tableName: string, unique: boolean}} - Arguments for creating the target index.
    */
   createIndexArgsFromSourceIndex({sourceIndex, tableName}) {
     /** @type {{columns: string[], name?: string, tableName: string, unique: boolean}} */
@@ -309,9 +309,9 @@ export default class SchemaCloner {
 
   /**
    * Whether two indexes have the same uniqueness and ordered column list.
-   * @param {import("../drivers/base-columns-index.js").default} sourceIndex
-   * @param {import("../drivers/base-columns-index.js").default} targetIndex
-   * @returns {boolean}
+   * @param {import("../drivers/base-columns-index.js").default} sourceIndex - Source index definition.
+   * @param {import("../drivers/base-columns-index.js").default} targetIndex - Target index definition.
+   * @returns {boolean} - Whether both indexes have the same shape.
    */
   indexesMatch(sourceIndex, targetIndex) {
     const sourceColumnNames = sourceIndex.getColumnNames()
@@ -336,8 +336,8 @@ export default class SchemaCloner {
 
   /**
    * A stable signature for an index, used to match cloned indexes by shape.
-   * @param {import("../drivers/base-columns-index.js").default} index
-   * @returns {string}
+   * @param {import("../drivers/base-columns-index.js").default} index - Index definition.
+   * @returns {string} - Stable index-shape signature.
    */
   indexSignature(index) {
     return `${index.isUnique() ? "unique" : "index"}:${index.getColumnNames().join(",")}`
@@ -345,8 +345,8 @@ export default class SchemaCloner {
 
   /**
    * Normalizes a column type to its canonical lowercase form (`int` becomes `integer`).
-   * @param {string} columnType
-   * @returns {string}
+   * @param {string} columnType - Database column type.
+   * @returns {string} - Canonical lowercase column type.
    */
   normalizedColumnType(columnType) {
     const normalizedType = columnType.toLowerCase()
@@ -360,8 +360,8 @@ export default class SchemaCloner {
 
   /**
    * The widening rank of a text column type (0 when not a text type).
-   * @param {string} columnType
-   * @returns {number}
+   * @param {string} columnType - Database column type.
+   * @returns {number} - Text-type widening rank.
    */
   textTypeRank(columnType) {
     return TEXT_TYPE_RANKS[this.normalizedColumnType(columnType)] || 0
@@ -369,9 +369,9 @@ export default class SchemaCloner {
 
   /**
    * Whether the target's text column is narrower than the source's and must be widened.
-   * @param {import("../drivers/base-column.js").default} sourceColumn
-   * @param {import("../drivers/base-column.js").default} targetColumn
-   * @returns {boolean}
+   * @param {import("../drivers/base-column.js").default} sourceColumn - Source column definition.
+   * @param {import("../drivers/base-column.js").default} targetColumn - Target column definition.
+   * @returns {boolean} - Whether the target text column must be widened.
    */
   columnNeedsWidening(sourceColumn, targetColumn) {
     const sourceRank = this.textTypeRank(sourceColumn.getType())
@@ -383,9 +383,9 @@ export default class SchemaCloner {
   /**
    * Builds TableData column args from a source column, copying type, nullability,
    * length, notes, simple defaults and (for full clones) primary-key flag.
-   * @param {import("../drivers/base-column.js").default} sourceColumn
-   * @param {{isNewColumn: boolean}} args
-   * @returns {Record<string, unknown>}
+   * @param {import("../drivers/base-column.js").default} sourceColumn - Source column definition.
+   * @param {{isNewColumn: boolean}} args - Whether the column is being added instead of cloned with its table.
+   * @returns {Record<string, unknown>} - Arguments for altering the target column.
    */
   columnArgsFromSourceColumn(sourceColumn, {isNewColumn}) {
     /** @type {{autoIncrement?: boolean, default?: unknown, isNewColumn: boolean, maxLength?: number, notes?: string, null: boolean, primaryKey?: boolean, type: string}} */

package/src/environment-handlers/browser.js

@@ -290,7 +290,6 @@ export default class VelociousEnvironmentsHandlerBrowser extends Base {
    * Runs after migrations.
    * @param {object} args - Options object.
    * @param {Record<string, import("../database/drivers/base.js").default>} args.dbs - Dbs.
-   * @param {"migration" | "schemaDump"} [args.reason] - Why the structure hook is running.
    * @returns {Promise<void>} - Resolves when complete.
    */
   async afterMigrations({dbs}) {

package/src/environment-handlers/node/cli/commands/background-jobs-runner.js

@@ -19,6 +19,7 @@ export default class BackgroundJobsRunnerCommand extends BaseCommand {
     const decoded = Buffer.from(payload, "base64").toString("utf8")
     const jobPayload = JSON.parse(decoded)
 
-    await runJobPayload(jobPayload)
+    await runJobPayload(jobPayload, {closeConnections: false})
+    process.exit(0)
   }
 }

package/src/environment-handlers/node/cli/commands/lint/relationships.js

@@ -124,7 +124,7 @@ export default class VelociousCliCommandsLintRelationships extends BaseCommand {
 
       if (!stats.isDirectory()) return false
     } catch (error) {
-      if (/** @type {NodeJS.ErrnoException} */ (error).code == "ENOENT") return false
+      if (/** @type {Error & {code?: string}} */ (error).code == "ENOENT") return false
 
       throw error
     }
@@ -213,7 +213,7 @@ export default class VelociousCliCommandsLintRelationships extends BaseCommand {
     try {
       configContent = await fs.readFile(configPath, "utf8")
     } catch (error) {
-      if (!explicitConfigPath && /** @type {NodeJS.ErrnoException} */ (error).code == "ENOENT") {
+      if (!explicitConfigPath && /** @type {Error & {code?: string}} */ (error).code == "ENOENT") {
         return new Set()
       }
 

package/src/environment-handlers/node.js

@@ -860,7 +860,7 @@ export default class VelociousEnvironmentHandlerNode extends Base{
         files.push({file, fullPath, date, migrationClassName})
       }
     } catch (error) {
-      if (/** @type {NodeJS.ErrnoException} */ (error)?.code !== "ENOENT") {
+      if (/** @type {Error & {code?: string}} */ (error)?.code !== "ENOENT") {
         throw error
       }
     }

package/src/frontend-model-controller.js

@@ -20,6 +20,8 @@ import isDate from "./utils/is-date.js"
 import isPlainObject from "./utils/plain-object.js"
 import {RansackQueryError, normalizeRansackGroup, parseRansackSort} from "./utils/ransack.js"
 
+/** @typedef {import("./database/query/model-class-query.js").default & Record<symbol, Set<string> | undefined>} FrontendModelQueryMetadata */
+
 /**
  * Runs normalize frontend model preload.
  * @param {import("./database/query/index.js").NestedPreloadRecord | string | string[] | boolean | undefined | null} preload - Preload shorthand.
@@ -31,7 +33,7 @@ function normalizeFrontendModelPreload(preload) {
   try {
     return normalizeQueryPreload(preload)
   } catch (error) {
-    throwFrontendModelQueryErrorForParserError(error)
+    return throwFrontendModelQueryErrorForParserError(error)
   }
 }
 
@@ -46,7 +48,7 @@ function normalizeFrontendModelJoins(joins) {
   try {
     return normalizeQueryJoins(joins)
   } catch (error) {
-    throwFrontendModelQueryErrorForParserError(error)
+    return throwFrontendModelQueryErrorForParserError(error)
   }
 }
 
@@ -190,10 +192,10 @@ function frontendSyncReplaySafeError(message, cause) {
 /**
  * Runs frontend model query metadata.
  * @param {import("./database/query/model-class-query.js").default} query - Query instance.
- * @returns {import("./database/query/model-class-query.js").default & {[frontendModelJoinedPathsSymbol]?: Set<string>, [frontendModelGroupedColumnsSymbol]?: Set<string>}} - Query metadata access helper.
+ * @returns {FrontendModelQueryMetadata} - Query metadata access helper.
  */
 function frontendModelQueryMetadata(query) {
-  return /** @type {import("./database/query/model-class-query.js").default & {[frontendModelJoinedPathsSymbol]?: Set<string>, [frontendModelGroupedColumnsSymbol]?: Set<string>}} */ (query)
+  return /** @type {FrontendModelQueryMetadata} */ (query)
 }
 
 /**
@@ -1253,7 +1255,7 @@ export default class FrontendModelController extends Controller {
     try {
       return normalizeQuerySort(this.frontendModelParams().sort)
     } catch (error) {
-      throwFrontendModelQueryErrorForParserError(error)
+      return throwFrontendModelQueryErrorForParserError(error)
     }
   }
 
@@ -1265,7 +1267,7 @@ export default class FrontendModelController extends Controller {
     try {
       return normalizeQueryGroup(this.frontendModelParams().group)
     } catch (error) {
-      throwFrontendModelQueryErrorForParserError(error)
+      return throwFrontendModelQueryErrorForParserError(error)
     }
   }
 
@@ -1304,7 +1306,7 @@ export default class FrontendModelController extends Controller {
 
       return pluck
     } catch (error) {
-      throwFrontendModelQueryErrorForParserError(error)
+      return throwFrontendModelQueryErrorForParserError(error)
     }
   }
 
@@ -1351,8 +1353,8 @@ export default class FrontendModelController extends Controller {
    * its backend model class by looking up the resource by modelName
    * across all configured backend projects. Returns null when no
    * resource matches the user-provided ability entry.
-   * @param {string} modelName
-   * @returns {typeof import("./database/record/index.js").default | null}
+   * @param {string} modelName - Frontend model name from an ability request.
+   * @returns {typeof import("./database/record/index.js").default | null} - Backend model class exposed under that frontend name, if present.
    */
   _frontendModelClassForAbilities(modelName) {
     if (typeof modelName !== "string" || modelName.length === 0) return null
@@ -1383,9 +1385,9 @@ export default class FrontendModelController extends Controller {
    * preloaded relationships at any depth. Used to evaluate per-record
    * abilities against nested preloaded children with a single batched
    * query per (modelClass, action) pair.
-   * @param {import("./database/record/index.js").default[]} rootModels
-   * @param {string} modelName
-   * @returns {import("./database/record/index.js").default[]}
+   * @param {import("./database/record/index.js").default[]} rootModels - Loaded roots whose relationship graphs should be traversed.
+   * @param {string} modelName - Model name records must match.
+   * @returns {import("./database/record/index.js").default[]} - Matching records reachable from the loaded roots.
    */
   _frontendModelCollectRecordsForName(rootModels, modelName) {
     /**
@@ -1399,7 +1401,8 @@ export default class FrontendModelController extends Controller {
 
     /**
      * Walk.
-     * @param {import("./database/record/index.js").default | null | undefined} record */
+     * @param {import("./database/record/index.js").default | null | undefined} record - Loaded record whose relationship graph should be visited.
+     */
     const walk = (record) => {
       if (!record || typeof record !== "object") return
       if (seen.has(record)) return
@@ -1437,7 +1440,7 @@ export default class FrontendModelController extends Controller {
    * `_setComputedAbility`. Runs one batched `authorized query + pluck`
    * per (modelClass, action) pair, regardless of how many records
    * were loaded.
-   * @param {import("./database/record/index.js").default[]} rootModels
+   * @param {import("./database/record/index.js").default[]} rootModels - Loaded roots that receive computed ability results.
    * @returns {Promise<void>}
    */
   async frontendModelComputeAbilities(rootModels) {
@@ -1491,7 +1494,7 @@ export default class FrontendModelController extends Controller {
    * Unknown entries are silently skipped — downstream code resolves
    * model names to classes when applying the check, so unresolved
    * names naturally become no-ops.
-   * @returns {Array<{modelName: string, actions: string[]}>}
+   * @returns {Array<{modelName: string, actions: string[]}>} - Normalized model ability requests.
    */
   frontendModelAbilities() {
     const raw = this.frontendModelParams().abilities
@@ -1529,7 +1532,7 @@ export default class FrontendModelController extends Controller {
    *
    * Returns the raw nested-record spec (shape validated by the
    * normalizer inside `Query.queryData`) or `null` when not requested.
-   * @returns {import("./database/query/query-data.js").QueryDataSpec | null}
+   * @returns {import("./database/query/query-data.js").QueryDataSpec | null} - Normalized query-data specification.
    */
   frontendModelQueryData() {
     const raw = this.frontendModelParams().queryData
@@ -1853,7 +1856,7 @@ export default class FrontendModelController extends Controller {
     try {
       return normalizeRansackGroup(this.frontendModelClass(), filterParams)
     } catch (error) {
-      throwFrontendModelQueryErrorForParserError(error)
+      return throwFrontendModelQueryErrorForParserError(error)
     }
   }
 
@@ -1866,7 +1869,7 @@ export default class FrontendModelController extends Controller {
     try {
       return parseRansackSort(this.frontendModelClass(), sortString)
     } catch (error) {
-      throwFrontendModelQueryErrorForParserError(error)
+      return throwFrontendModelQueryErrorForParserError(error)
     }
   }
 
@@ -2698,12 +2701,14 @@ export default class FrontendModelController extends Controller {
     /**
      * Resource attribute method name.
      * @param {string} attributeName - Attribute name.
+     * @returns {string} - Resource attribute method name.
      */
     const resourceAttributeMethodName = (attributeName) => `${attributeName}Attribute`
 
     /**
      * Resource has attribute.
      * @param {string} attributeName - Attribute name.
+     * @returns {ReturnType<FrontendModelBaseResource["resourceMethod"]>} - Resource attribute method details.
      */
     const resourceAttributeMethod = (attributeName) => {
       const methodName = resourceAttributeMethodName(attributeName)
@@ -2714,6 +2719,7 @@ export default class FrontendModelController extends Controller {
     /**
      * Prototype attribute method.
      * @param {string} attributeName - Attribute name.
+     * @returns {{method: (...args: Array<?>) => ?, ownerName: string} | undefined} - Prototype method details when present.
      */
     const prototypeAttributeMethod = (attributeName) => {
       let currentPrototype = Object.getPrototypeOf(model)
@@ -2735,6 +2741,7 @@ export default class FrontendModelController extends Controller {
     /**
      * Serialized attribute value.
      * @param {string} attributeName - Attribute name.
+     * @returns {Promise<?>} - Serialized attribute value.
      */
     const serializedAttributeValue = async (attributeName) => {
       // Check resource instance first (virtual/computed attributes via ${name}Attribute convention)
@@ -2758,6 +2765,7 @@ export default class FrontendModelController extends Controller {
     /**
      * Attribute exists.
      * @param {string} attributeName - Attribute name.
+     * @returns {boolean} - Whether the attribute exists.
      */
     const attributeExists = (attributeName) => {
       return (attributeName in modelAttributes) || (attributeName in /** @type {Record<string, ?>} */ (model)) || Boolean(resourceAttributeMethod(attributeName))

package/src/frontend-models/base.js

@@ -104,7 +104,7 @@ import {readPayloadAssociationCount, readPayloadComputedAbility, readPayloadQuer
  * frontend models passed model classes into relationship helpers, while newer
  * generated models pass instance types.
  * @template {FrontendModelBase<any, any, any> | typeof FrontendModelBase} T
- * @typedef {T extends new (...args: any[]) => infer Instance ? Instance : T} FrontendModelRelationshipModel
+ * @typedef {T extends typeof FrontendModelBase ? InstanceType<T> : T} FrontendModelRelationshipModel
  */
 /**
  * FrontendModelTransportConfig type.
@@ -1799,7 +1799,7 @@ async function performSharedFrontendModelApiRequest(requestPayload) {
 /**
  * Throws a frontend-model HTTP error with backend-provided envelope details when available.
  * @param {{commandLabel: string, response: Response, responseText: string}} args - Error response details.
- * @returns {never}
+ * @returns {never} - Always throws an unknown-attribute error.
  */
 function throwFrontendModelHttpError({commandLabel, response, responseText}) {
   // Surface the backend's friendly errorMessage envelope (the
@@ -2612,7 +2612,7 @@ export default class FrontendModelBase {
    * column of the same name. Returns the attached value, or 0 when
    * `.withCount(...)` wasn't requested for this attribute.
    * @param {string} attributeName - Attribute name, e.g. `"tasksCount"` or a custom name from `.withCount({customName: {...}})`.
-   * @returns {number}
+   * @returns {number} - Attached association count, or zero when absent.
    */
   readCount(attributeName) {
     return readPayloadAssociationCount(/** @type {import("../record-payload-values.js").RecordPayloadValuesTarget} */ (/** @type {?} */ (this)), attributeName)
@@ -2638,7 +2638,7 @@ export default class FrontendModelBase {
    * on `record.can("update")` without first checking whether the
    * ability was loaded.
    * @param {string} action - Ability action name, e.g. `"update"`.
-   * @returns {boolean}
+   * @returns {boolean} - Whether the requested ability is allowed.
    */
   can(action) {
     return readPayloadComputedAbility(/** @type {import("../record-payload-values.js").RecordPayloadValuesTarget} */ (/** @type {?} */ (this)), action)
@@ -2663,7 +2663,7 @@ export default class FrontendModelBase {
    * name. Returns `null` when no registered fn produced that alias for
    * this record (e.g. no child rows matched the aggregate).
    * @param {string} name - queryData alias name.
-   * @returns {?}
+   * @returns {?} - Attached query-data value.
    */
   queryData(name) {
     return readPayloadQueryData(/** @type {import("../record-payload-values.js").RecordPayloadValuesTarget} */ (/** @type {?} */ (this)), name)

package/src/frontend-models/query.js

@@ -166,8 +166,8 @@ export function normalizePreload(preload) {
  * query API into the strict internal entries used in the transport
  * payload. Shares the shape semantics with the backend normalizer in
  * `database/query/with-count.js`.
- * @param {string | string[] | Record<string, boolean | {relationship?: string, where?: Record<string, ?>}>} spec
- * @returns {Array<{attributeName: string, relationshipName: string, where?: Record<string, ?>}>}
+ * @param {string | string[] | Record<string, boolean | {relationship?: string, where?: Record<string, ?>}>} spec - Association-count shorthand to normalize.
+ * @returns {Array<{attributeName: string, relationshipName: string, where?: Record<string, ?>}>} - Normalized association-count requests.
  */
 function normalizeWithCountFrontend(spec) {
   if (spec == null) return []
@@ -222,9 +222,9 @@ function normalizeWithCountFrontend(spec) {
  * shorthand (applies to the query's own model class) and the keyed
  * `{ModelName: [action, ...]}` form (applies to records of that model
  * class, useful for preloaded children).
- * @param {string[] | Record<string, string[]>} spec
- * @param {{getModelName: () => string}} rootModelClass
- * @returns {Array<{modelName: string, actions: string[]}>}
+ * @param {string[] | Record<string, string[]>} spec - Ability actions grouped by model, or root-model action shorthand.
+ * @param {{getModelName: () => string}} rootModelClass - Query root used by the flat action shorthand.
+ * @returns {Array<{modelName: string, actions: string[]}>} - Normalized model ability requests.
  */
 function normalizeAbilitiesSpec(spec, rootModelClass) {
   if (spec == null) return []
@@ -1181,8 +1181,8 @@ export default class FrontendModelQuery {
    * strings — typically `"update"` / `"destroy"` / `"create"` /
    * `"read"`, but any custom action registered on the resource's
    * authorization ability is accepted.
-   * @param {string[] | Record<string, string[]>} spec
-   * @returns {this}
+   * @param {string[] | Record<string, string[]>} spec - Ability actions to request for root or named models.
+   * @returns {this} - This query for chaining.
    */
   abilities(spec) {
     for (const entry of normalizeAbilitiesSpec(spec, this.modelClass)) {
@@ -1194,7 +1194,7 @@ export default class FrontendModelQuery {
 
   /**
    * Runs merge ability entry.
-   * @param {{modelName: string, actions: string[]}} entry
+   * @param {{modelName: string, actions: string[]}} entry - Normalized model ability request to append.
    * @returns {void}
    */
   _mergeAbilityEntry(entry) {
@@ -1215,8 +1215,8 @@ export default class FrontendModelQuery {
    * counts to each returned record. Parses the same shapes as the
    * backend `ModelClassQuery#withCount`, then ships the normalized
    * entries as part of the `index` command payload.
-   * @param {string | string[] | Record<string, boolean | {relationship?: string, where?: Record<string, ?>}>} spec
-   * @returns {this}
+   * @param {string | string[] | Record<string, boolean | {relationship?: string, where?: Record<string, ?>}>} spec - Relationships whose counts should be serialized.
+   * @returns {this} - This query for chaining.
    */
   withCount(spec) {
     for (const entry of normalizeWithCountFrontend(spec)) {
@@ -1233,8 +1233,8 @@ export default class FrontendModelQuery {
    * frontend ships only these names; the SQL fragments stay server-
    * side. All resulting aliases are attached to the root record and
    * read back with `record.queryData(aliasName)`.
-   * @param {string | Array<string | Record<string, ?>> | Record<string, ?>} spec
-   * @returns {this}
+   * @param {string | Array<string | Record<string, ?>> | Record<string, ?>} spec - Backend query-data names and arguments to serialize.
+   * @returns {this} - This query for chaining.
    */
   queryData(spec) {
     if (spec == null) return this