velocious 1.0.581 → 1.0.583

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

@@ -115,19 +115,19 @@ export async function runWithCount({models, modelClass, entries}) {
   const queryGroups = new Map()
 
   for (const entry of entries) {
-    const countQuery = queryForEntry({entry, modelClass, parentIds, sourceModel})
-    const sql = countQuery.toSql()
+    const {baseQuery, foreignKey} = queryForEntry({entry, modelClass, sourceModel})
+    const sql = baseQuery.toSql()
     const existingGroup = queryGroups.get(sql)
 
     if (existingGroup) {
       existingGroup.entries.push(entry)
     } else {
-      queryGroups.set(sql, {countQuery, entries: [entry]})
+      queryGroups.set(sql, {baseQuery, entries: [entry], foreignKey})
     }
   }
 
-  for (const {countQuery, entries: groupedEntries} of queryGroups.values()) {
-    const counts = await executeCountQuery(countQuery)
+  for (const {baseQuery, entries: groupedEntries, foreignKey} of queryGroups.values()) {
+    const counts = await executeChunkedCountQuery({baseQuery, foreignKey, parentIds})
 
     for (const entry of groupedEntries) attachCounts({counts, entry, models, primaryKey})
   }
@@ -135,14 +135,16 @@ export async function runWithCount({models, modelClass, entries}) {
 
 /**
  * Builds the grouped count query for an entry.
+ *
+ * The returned query does NOT yet filter by parent IDs; callers chunk the
+ * parent cohort and apply the foreign-key IN clause per chunk.
  * @param {object} args - Options.
  * @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.
  * @param {import("../record/index.js").default} args.sourceModel - Loaded operation owner.
- * @returns {import("./model-class-query.js").default} - Prepared count query.
+ * @returns {{baseQuery: import("./model-class-query.js").default, foreignKey: string}} - Prepared count query and its foreign key.
  */
-function queryForEntry({entry, modelClass, parentIds, sourceModel}) {
+function queryForEntry({entry, modelClass, sourceModel}) {
   const relationship = modelClass.getRelationshipByName(entry.relationshipName)
 
   if (!relationship) {
@@ -163,7 +165,7 @@ function queryForEntry({entry, modelClass, parentIds, sourceModel}) {
   /**
    * Mandatory cohort conditions.
    * @type {Record<string, ReturnType<typeof JSON.parse>>} */
-  const mandatoryWhereConditions = {[foreignKey]: parentIds}
+  const mandatoryWhereConditions = {}
 
   if (relationship.getPolymorphic && relationship.getPolymorphic()) {
     const typeColumn = relationship.getPolymorphicTypeColumn()
@@ -171,8 +173,12 @@ function queryForEntry({entry, modelClass, parentIds, sourceModel}) {
   }
 
   const baseQuery = sourceModel.queryForModel(targetModelClass)
+
   baseQuery._forceQualifyBaseTable = true
-  baseQuery.where(mandatoryWhereConditions)
+
+  if (Object.keys(mandatoryWhereConditions).length > 0) {
+    baseQuery.where(mandatoryWhereConditions)
+  }
 
   if (entry.where) {
     baseQuery.where(entry.where)
@@ -192,7 +198,7 @@ function queryForEntry({entry, modelClass, parentIds, sourceModel}) {
   countQuery.select(`${qualifiedForeignKey} AS parent_id`)
   countQuery.select("COUNT(*) AS count_value")
 
-  return countQuery
+  return {baseQuery: countQuery, foreignKey}
 }
 
 /**
@@ -219,6 +225,36 @@ async function executeCountQuery(countQuery) {
   return counts
 }
 
+/**
+ * Executes a grouped count query in cohorts so the parent ID IN-list stays
+ * within driver limits, merging per-parent counts across chunks.
+ * @param {object} args - Options.
+ * @param {import("./model-class-query.js").default} args.baseQuery - Prepared count query without parent IDs.
+ * @param {string} args.foreignKey - Foreign key used to join to the parents.
+ * @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 executeChunkedCountQuery({baseQuery, foreignKey, parentIds}) {
+  const driver = baseQuery.driver
+  const cohorts = driver.chunkValues(parentIds, (chunk) => baseQuery.clone().where({[foreignKey]: chunk}).toSql())
+
+  /**
+   * Counts.
+   * @type {Map<string | number, number>} */
+  const counts = new Map()
+
+  for (const cohort of cohorts) {
+    const cohortQuery = baseQuery.clone().where({[foreignKey]: cohort})
+    const cohortCounts = await executeCountQuery(cohortQuery)
+
+    for (const [parentId, count] of cohortCounts) {
+      counts.set(parentId, count)
+    }
+  }
+
+  return counts
+}
+
 /**
  * Attaches one entry's resolved counts to the loaded models.
  * @param {object} args - Options.

package/src/environment-handlers/node/cli/commands/test.js

@@ -1,6 +1,7 @@
 // @ts-check
 
 import BaseCommand from "../../../../cli/base-command.js"
+import fs from "fs/promises"
 import picocolors from "picocolors"
 import TestFilesFinder from "../../../../testing/test-files-finder.js"
 import TestRunner from "../../../../testing/test-runner.js"
@@ -26,7 +27,7 @@ export default class VelociousCliCommandsTest extends BaseCommand {
       directories.push(`${this.directory()}/spec`)
     }
 
-    const {includeTags, excludeTags, examplePatterns, filteredProcessArgs, groups, groupNumber} = parseFilters(this.processArgs || [])
+    const {includeTags, excludeTags, examplePatterns, filteredProcessArgs, groups, groupNumber, timingManifestPath} = parseFilters(this.processArgs || [])
     const testFilesFinder = new TestFilesFinder({directory, directories, processArgs: filteredProcessArgs})
     let testFiles = await testFilesFinder.findTestFiles()
 
@@ -35,7 +36,8 @@ export default class VelociousCliCommandsTest extends BaseCommand {
         throw new Error("Both --groups and --group-number must be provided together")
       }
 
-      const splitter = new TestSuiteSplitter({groups, groupNumber, testFiles, baseDirectory: directory})
+      const timingManifest = await loadTimingManifest(timingManifestPath)
+      const splitter = new TestSuiteSplitter({groups, groupNumber, testFiles, baseDirectory: directory, timingManifest})
 
       testFiles = splitter.getGroupFiles()
       console.log(picocolors.cyan(`Running group ${groupNumber} of ${groups} (${testFiles.length} files)`))
@@ -138,6 +140,23 @@ export default class VelociousCliCommandsTest extends BaseCommand {
   }
 }
 
+/**
+ * Loads an optional JSON timing manifest. Unreadable or malformed input intentionally falls back to heuristics.
+ * @param {string | undefined} timingManifestPath - Timing manifest path.
+ * @returns {Promise<ReturnType<typeof JSON.parse> | undefined>} - Parsed manifest when readable and valid JSON.
+ */
+export async function loadTimingManifest(timingManifestPath) {
+  if (!timingManifestPath) return undefined
+
+  try {
+    return JSON.parse(await fs.readFile(timingManifestPath, "utf8"))
+  } catch (error) {
+    if (error instanceof Error) return undefined
+
+    throw error
+  }
+}
+
 /**
  * Resolves how many slowest tests to report from the `VELOCIOUS_SLOW_TEST_COUNT`
  * env value: defaults to 10 when unset; 0 (or an unparseable value) disables the

package/src/frontend-model-controller.js

@@ -72,6 +72,12 @@ import {RansackQueryError, normalizeRansackGroup, parseRansackSort} from "./util
  * @property {import("./frontend-model-resource/base-resource.js").default} [resource] - Resource providing query hooks.
  */
 /** @typedef {import("./database/query/model-class-query.js").default & Record<symbol, Set<string> | undefined>} FrontendModelQueryMetadata */
+/**
+ * @callback FrontendModelSerializationResourceInstanceHook
+ * @param {import("./database/record/index.js").default} model - Model instance being serialized.
+ * @param {import("./frontend-model-resource/base-resource.js").default | null} resource - Resolved serialization resource instance, if any.
+ * @returns {void}
+ */
 
 /**
  * Runs normalize frontend model preload.
@@ -603,6 +609,17 @@ export default class FrontendModelController extends Controller {
    * own arguments rather than the route metadata. Only set on the shared-endpoint path.
    * @type {Record<string, ReturnType<typeof JSON.parse>> | undefined} */
   _frontendModelCustomCommandClientArguments = undefined
+  /**
+   * Request-scoped cache for serialization resource instances.
+   * Keyed by model class, then by whether the resource is for a related model
+   * (so self-referential relationships do not accidentally reuse root params).
+   * @type {Map<typeof import("./database/record/index.js").default, Map<boolean, import("./frontend-model-resource/base-resource.js").default>> | undefined} */
+  _frontendModelSerializationResourceInstances = undefined
+  /**
+   * Optional per-instance hook invoked for every serialization resource instance
+   * resolution. Intended for tests and benchmarks; absent in production.
+   * @type {FrontendModelSerializationResourceInstanceHook | null | undefined} */
+  _frontendModelSerializationResourceInstanceHook = undefined
 
   /**
    * Runs frontend model params.
@@ -628,15 +645,18 @@ export default class FrontendModelController extends Controller {
   async withFrontendModelParams(params, callback) {
     const previousOverride = this._frontendModelParamsOverride
     const previousParams = this._frontendModelParams
+    const previousSerializationResourceInstances = this._frontendModelSerializationResourceInstances
 
     this._frontendModelParamsOverride = params
     this._frontendModelParams = undefined
+    this._frontendModelSerializationResourceInstances = undefined
 
     try {
       return await callback()
     } finally {
       this._frontendModelParamsOverride = previousOverride
       this._frontendModelParams = previousParams
+      this._frontendModelSerializationResourceInstances = previousSerializationResourceInstances
     }
   }
 
@@ -2792,47 +2812,130 @@ export default class FrontendModelController extends Controller {
     return serializedAttributes
   }
 
+  /**
+   * Returns the request-scoped serialization resource instance cache.
+   * @returns {Map<typeof import("./database/record/index.js").default, Map<boolean, import("./frontend-model-resource/base-resource.js").default>>} - Cache.
+   */
+  _frontendModelSerializationResourceInstancesMap() {
+    if (!this._frontendModelSerializationResourceInstances) {
+      this._frontendModelSerializationResourceInstances = new Map()
+    }
+
+    return this._frontendModelSerializationResourceInstances
+  }
+
+  /**
+   * Looks up a cached serialization resource instance.
+   * @param {typeof import("./database/record/index.js").default} modelClass - Model class.
+   * @param {boolean} isRelated - Whether the resource is for a related (non-root) model.
+   * @returns {import("./frontend-model-resource/base-resource.js").default | undefined} - Cached resource or undefined.
+   */
+  _cachedSerializationResourceInstance(modelClass, isRelated) {
+    return this._frontendModelSerializationResourceInstancesMap().get(modelClass)?.get(isRelated)
+  }
+
+  /**
+   * Stores a serialization resource instance in the request-scoped cache.
+   * @param {typeof import("./database/record/index.js").default} modelClass - Model class.
+   * @param {boolean} isRelated - Whether the resource is for a related (non-root) model.
+   * @param {import("./frontend-model-resource/base-resource.js").default} resource - Resource instance.
+   * @returns {void}
+   */
+  _setCachedSerializationResourceInstance(modelClass, isRelated, resource) {
+    const byClass = this._frontendModelSerializationResourceInstancesMap()
+    let byRelated = byClass.get(modelClass)
+
+    if (!byRelated) {
+      byRelated = new Map()
+      byClass.set(modelClass, byRelated)
+    }
+
+    byRelated.set(isRelated, resource)
+  }
+
+  /**
+   * Sets a per-instance hook invoked for every serialization resource instance
+   * resolution. The hook is scoped to this controller; it never affects other
+   * controller instances. Passing `null` clears the hook.
+   * @param {FrontendModelSerializationResourceInstanceHook | null} hook - Hook callback or null.
+   * @returns {() => void} - Cleanup function that restores the previous hook.
+   */
+  setSerializationResourceInstanceHook(hook) {
+    const previousHook = this._frontendModelSerializationResourceInstanceHook
+
+    this._frontendModelSerializationResourceInstanceHook = hook
+
+    return () => {
+      this._frontendModelSerializationResourceInstanceHook = previousHook
+    }
+  }
+
   /**
    * Runs serialization resource instance for model.
    * @param {import("./database/record/index.js").default} model - Model instance.
    * @returns {import("./frontend-model-resource/base-resource.js").default | null} - Resource instance or null.
    */
   _serializationResourceInstanceForModel(model) {
-    const resource = this.frontendModelResourceInstance()
+    const modelClass = /** @type {typeof import("./database/record/index.js").default} */ (model.constructor)
+    const isRelated = modelClass !== this.frontendModelClass()
+    const cachedResource = this._cachedSerializationResourceInstance(modelClass, isRelated)
+
+    if (cachedResource) {
+      if (this._frontendModelSerializationResourceInstanceHook) {
+        this._frontendModelSerializationResourceInstanceHook(model, cachedResource)
+      }
 
-    if (resource.modelClass() === model.constructor) {
-      return resource
+      return cachedResource
     }
 
-    const configuration = this.getConfiguration()
-    const backendProjects = configuration.getBackendProjects()
-    const modelClassName = /** @type {typeof import("./database/record/index.js").default} */ (model.constructor).getModelName()
+    /** @type {import("./frontend-model-resource/base-resource.js").default | null} */
+    let resource
 
-    for (const backendProject of backendProjects) {
-      const resources = frontendModelResourcesWithBuiltInsForBackendProject(backendProject)
-      const resourceDefinition = resources[modelClassName]
-      const resourceClass = resourceDefinition ? frontendModelResourceClassFromDefinition(resourceDefinition) : null
-
-      if (resourceClass) {
-        return new resourceClass({
-          ability: this.currentAbility(),
-          // Propagate the controller so a related/preloaded model's serialization
-          // resource can use request context (e.g. `requestBaseUrl()` for signed
-          // download URLs). Without it, any `<attr>Attribute` method that reaches
-          // for the controller throws "requires a controller instance." when a
-          // relationship is serialized as a preload.
-          controller: this,
-          context: this.currentAbility()?.getContext() || {},
-          locals: this.currentAbility()?.getLocals() || {},
-          modelClass: /** @type {typeof import("./database/record/index.js").default} */ (model.constructor),
-          modelName: modelClassName,
-          params: {},
-          resourceConfiguration: resourceClass.resourceConfig()
-        })
+    if (!isRelated) {
+      resource = this.frontendModelResourceInstance()
+
+      this._setCachedSerializationResourceInstance(modelClass, false, resource)
+    } else {
+      const configuration = this.getConfiguration()
+      const backendProjects = configuration.getBackendProjects()
+      const modelClassName = modelClass.getModelName()
+
+      resource = null
+
+      for (const backendProject of backendProjects) {
+        const resources = frontendModelResourcesWithBuiltInsForBackendProject(backendProject)
+        const resourceDefinition = resources[modelClassName]
+        const resourceClass = resourceDefinition ? frontendModelResourceClassFromDefinition(resourceDefinition) : null
+
+        if (resourceClass) {
+          resource = new resourceClass({
+            ability: this.currentAbility(),
+            // Propagate the controller so a related/preloaded model's serialization
+            // resource can use request context (e.g. `requestBaseUrl()` for signed
+            // download URLs). Without it, any `<attr>Attribute` method that reaches
+            // for the controller throws "requires a controller instance." when a
+            // relationship is serialized as a preload.
+            controller: this,
+            context: this.currentAbility()?.getContext() || {},
+            locals: this.currentAbility()?.getLocals() || {},
+            modelClass,
+            modelName: modelClassName,
+            params: {},
+            resourceConfiguration: resourceClass.resourceConfig()
+          })
+
+          this._setCachedSerializationResourceInstance(modelClass, true, resource)
+
+          break
+        }
       }
     }
 
-    return null
+    if (this._frontendModelSerializationResourceInstanceHook) {
+      this._frontendModelSerializationResourceInstanceHook(model, resource)
+    }
+
+    return resource
   }
 
   /**

package/src/testing/test-filter-parser.js

@@ -7,6 +7,7 @@
  * @property {string[]} filteredProcessArgs - Remaining process args with filter flags removed.
  * @property {number | undefined} groups - Total number of groups for test splitting.
  * @property {number | undefined} groupNumber - Which group to run (1-indexed).
+ * @property {string | undefined} timingManifestPath - JSON timing manifest path.
  */
 // @ts-check
 
@@ -15,6 +16,7 @@ const EXCLUDE_TAG_FLAGS = new Set(["--exclude-tag", "--skip-tag", "-x"])
 const EXAMPLE_FLAGS = new Set(["--example", "--name", "-e"])
 const GROUPS_FLAGS = new Set(["--groups"])
 const GROUP_NUMBER_FLAGS = new Set(["--group-number"])
+const TIMING_MANIFEST_FLAGS = new Set(["--timing-manifest"])
 
 /**
  * Runs split tags.
@@ -79,6 +81,8 @@ export function parseFilters(processArgs) {
    * Defines groupNumber.
    * @type {number | undefined} */
   let groupNumber
+  /** @type {string | undefined} */
+  let timingManifestPath
 
   let inRestArgs = false
 
@@ -181,6 +185,21 @@ export function parseFilters(processArgs) {
         groupNumber = parseInt(arg.slice("--group-number=".length), 10)
         continue
       }
+
+      if (TIMING_MANIFEST_FLAGS.has(arg)) {
+        const nextValue = processArgs[i + 1]
+
+        if (nextValue && !nextValue.startsWith("-")) {
+          timingManifestPath = nextValue
+          i++
+        }
+        continue
+      }
+
+      if (arg.startsWith("--timing-manifest=")) {
+        timingManifestPath = arg.slice("--timing-manifest=".length)
+        continue
+      }
     }
 
     filteredProcessArgs.push(arg)
@@ -192,6 +211,7 @@ export function parseFilters(processArgs) {
     examplePatterns,
     filteredProcessArgs,
     groups,
-    groupNumber
+    groupNumber,
+    timingManifestPath
   }
 }

package/src/testing/test-suite-splitter.js

@@ -46,8 +46,9 @@ export default class TestSuiteSplitter {
    * @param {number} args.groupNumber - Which group to return (1-indexed).
    * @param {string[]} args.testFiles - All discovered test file paths.
    * @param {string} [args.baseDirectory] - Base directory for relative path computation.
+   * @param {ReturnType<typeof JSON.parse>} [args.timingManifest] - Relative test paths mapped to durations.
    */
-  constructor({groups, groupNumber, testFiles, baseDirectory, ...restArgs}) {
+  constructor({groups, groupNumber, testFiles, baseDirectory, timingManifest, ...restArgs}) {
     restArgsError(restArgs)
 
     if (!Number.isInteger(groups) || groups < 1) {
@@ -62,6 +63,7 @@ export default class TestSuiteSplitter {
     this._groupNumber = groupNumber
     this._testFiles = testFiles
     this._baseDirectory = baseDirectory || process.cwd()
+    this._timingManifest = this.normalizeTimingManifest(timingManifest)
   }
 
   /**
@@ -93,7 +95,14 @@ export default class TestSuiteSplitter {
    * @returns {number} - Weight value.
    */
   computeWeight(filePath) {
-    const relativePath = path.relative(this._baseDirectory, filePath).split(path.sep).join("/")
+    const relativePath = this.normalizeRelativePath(path.relative(this._baseDirectory, filePath))
+    const projectRelativePath = this.normalizeRelativePath(path.join(path.basename(this._baseDirectory), relativePath))
+    const duration = this._timingManifest[relativePath] ?? this._timingManifest[projectRelativePath]
+
+    if (duration !== undefined) {
+      return duration
+    }
+
     let weight = DEFAULT_WEIGHT
 
     // Extract the type directory from the relative path.
@@ -116,6 +125,39 @@ export default class TestSuiteSplitter {
     return weight
   }
 
+  /**
+   * Keeps only usable positive finite duration entries keyed by normalized relative path.
+   * @param {ReturnType<typeof JSON.parse>} timingManifest - Parsed timing manifest.
+   * @returns {Record<string, number>} - Valid normalized duration weights.
+   */
+  normalizeTimingManifest(timingManifest) {
+    /** @type {Record<string, number>} */
+    const normalized = {}
+
+    if (!timingManifest || typeof timingManifest !== "object" || Array.isArray(timingManifest)) {
+      return normalized
+    }
+
+    for (const [filePath, duration] of Object.entries(timingManifest)) {
+      if (typeof duration === "number" && Number.isFinite(duration) && duration > 0) {
+        normalized[this.normalizeRelativePath(filePath)] = duration
+      }
+    }
+
+    return normalized
+  }
+
+  /**
+   * Normalizes a relative test path to the manifest's portable slash format.
+   * @param {string} filePath - Relative test path.
+   * @returns {string} - Normalized relative test path.
+   */
+  normalizeRelativePath(filePath) {
+    return filePath
+      .replaceAll("\\", "/")
+      .replace(/^\.\//, "")
+  }
+
   /**
    * Sorts files by weight descending, then by path for determinism.
    * @param {SplitterFileEntry[]} files - Weighted files.