velocious 1.0.581 → 1.0.582

package/src/database/drivers/base.js

@@ -118,6 +118,14 @@
  * @property {string[]} updateColumns - Columns to update on conflict.
  */
 
+/**
+ * SqlTokenResult type.
+ * @typedef {object} SqlTokenResult
+ * @property {boolean} incomplete - Whether the scan hit its bound before finishing trivia/token parsing.
+ * @property {string | undefined} token - Lowercased token when parsing completed; undefined when no token was found.
+ * @property {number} index - Index immediately after the parsed token or trivia.
+ */
+
 import BacktraceCleaner from "../../utils/backtrace-cleaner.js"
 import { getDatabaseAnnotations } from "../annotations.js"
 import { formatDateForDatabase } from "../datetime-storage.js"
@@ -134,6 +142,11 @@ import TableForeignKey from "../table-data/table-foreign-key.js"
 import wait from "awaitery/build/wait.js"
 import {optionalPositiveInteger} from "typanic"
 
+/** Maximum characters inspected when building the debug SQL preview. */
+const SQL_PREVIEW_SCAN_LIMIT = 4096
+/** Maximum characters inspected when deciding whether a statement invalidates schema metadata. */
+const SCHEMA_INVALIDATION_SCAN_LIMIT = 8192
+
 /**
  * Marks a callback failure that happened after the owning transaction was durably committed.
  * The public transaction boundary unwraps it before deadlock classification.
@@ -1604,13 +1617,25 @@ export default class VelociousDatabaseDriversBase {
     }
   }
 
+  /**
+   * Returns a bounded prefix of `sql` for lightweight diagnostic scanning.
+   * @param {string} sql - SQL string.
+   * @param {number} limit - Maximum code units to inspect.
+   * @returns {string} - Prefix of `sql`.
+   */
+  _diagnosticSqlPrefix(sql, limit) {
+    return sql.length <= limit ? sql : sql.slice(0, limit)
+  }
+
   /**
    * Runs debug sql preview.
    * @param {string} sql - SQL to preview.
    * @returns {string} - Normalized truncated SQL preview for diagnostics.
    */
   _debugSqlPreview(sql) {
-    return sql
+    const prefix = this._diagnosticSqlPrefix(sql, SQL_PREVIEW_SCAN_LIMIT)
+
+    return prefix
       .replace(/\s+/g, " ")
       .trim()
       .slice(0, 500)
@@ -1664,25 +1689,121 @@ export default class VelociousDatabaseDriversBase {
       .replace(/"/g, "'")
   }
 
+  /**
+   * Reads the next SQL token starting at `startIndex`, skipping leading trivia
+   * (BOM, whitespace, block comments, line comments). If the scan cannot finish
+   * skipping trivia before `limit`, the result is marked incomplete so callers
+   * can conservatively treat the statement as schema-invalidating.
+   * @param {string} sql - SQL string.
+   * @param {number} startIndex - Index to start scanning.
+   * @param {number} limit - Maximum absolute index to scan while skipping leading trivia.
+   * @returns {SqlTokenResult} - Token result.
+   */
+  _readSqlToken(sql, startIndex, limit) {
+    let i = startIndex
+    const len = sql.length
+
+    while (i < len && i < limit) {
+      const char = sql[i]
+
+      if (char === "\ufeff" || /\s/.test(char)) {
+        i++
+        continue
+      }
+
+      if (char === "/" && sql[i + 1] === "*") {
+        const close = sql.indexOf("*/", i + 2)
+
+        if (close === -1 || close + 2 > limit) {
+          return {incomplete: true, index: i, token: undefined}
+        }
+
+        i = close + 2
+        continue
+      }
+
+      if (char === "-" && sql[i + 1] === "-") {
+        const newline = sql.indexOf("\n", i + 2)
+
+        if (newline === -1) {
+          return {incomplete: false, index: len, token: undefined}
+        }
+
+        if (newline + 1 > limit) {
+          return {incomplete: true, index: i, token: undefined}
+        }
+
+        i = newline + 1
+        continue
+      }
+
+      let token = ""
+
+      while (i < len) {
+        const c = sql[i]
+
+        if (/\s/.test(c) || c === "\ufeff") break
+        if (c === "/" && sql[i + 1] === "*") break
+        if (c === "-" && sql[i + 1] === "-") break
+
+        token += c
+        i++
+      }
+
+      return {incomplete: false, token: token.toLowerCase(), index: i}
+    }
+
+    if (i >= len) {
+      return {incomplete: false, index: len, token: undefined}
+    }
+
+    return {incomplete: true, index: i, token: undefined}
+  }
+
   /**
    * Runs schema cache invalidating sql.
    * @param {string} sql - SQL string.
    * @returns {boolean} - Whether the SQL should invalidate schema metadata.
    */
   _schemaCacheInvalidatingSql(sql) {
-    const normalized = sql
-      .trim()
-      .replace(/^\ufeff/, "")
-      .replace(/\/\*[\s\S]*?\*\//g, " ")
-      .replace(/--[^\n]*(\n|$)/g, " ")
-      .replace(/\s+/g, " ")
-      .toLowerCase()
+    const first = this._readSqlToken(sql, 0, SCHEMA_INVALIDATION_SCAN_LIMIT)
 
-    if (!normalized) return false
-    if (/^(create|alter|drop|rename)\b/.test(normalized)) return true
-    if (/^comment\s+on\b/.test(normalized)) return true
-    if (/^exec(?:ute)?\s+sp_rename\b/.test(normalized)) return true
-    if (/^if\b[\s\S]*\bbegin\s+(create|alter|drop|rename)\b/.test(normalized)) return true
+    if (first.incomplete) return true
+
+    const firstToken = first.token
+
+    if (!firstToken) return false
+    if (/^(create|alter|drop|rename)$/.test(firstToken)) return true
+
+    if (firstToken === "comment") {
+      const next = this._readSqlToken(sql, first.index, SCHEMA_INVALIDATION_SCAN_LIMIT)
+
+      return next.incomplete || next.token === "on"
+    }
+
+    if (firstToken === "exec" || firstToken === "execute") {
+      const next = this._readSqlToken(sql, first.index, SCHEMA_INVALIDATION_SCAN_LIMIT)
+
+      return next.incomplete || next.token === "sp_rename"
+    }
+
+    if (firstToken === "if") {
+      let index = first.index
+
+      while (true) {
+        const result = this._readSqlToken(sql, index, SCHEMA_INVALIDATION_SCAN_LIMIT)
+
+        if (result.incomplete) return true
+        if (!result.token) return false
+        if (result.token === "begin") {
+          const ddlResult = this._readSqlToken(sql, result.index, SCHEMA_INVALIDATION_SCAN_LIMIT)
+
+          return ddlResult.incomplete || /^(create|alter|drop|rename)$/.test(ddlResult.token || "")
+        }
+
+        index = result.index
+      }
+    }
 
     return false
   }

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.