velocious 1.0.577 → 1.0.579

package/src/testing/factory/factory-registry.js

@@ -13,13 +13,13 @@ import {isPlainObject} from "is-plain-object"
 /**
  * Normalizes a strategy invocation's variadic tail into ordered trait names plus
  * a single final overrides object (`strategy(name, ...traits, overrides?)`).
- * @param {Array<?>} args - Arguments after the factory name (and count for lists).
- * @returns {{traits: string[], overrides: Record<string, ?>}} - Normalized invocation.
+ * @param {Array<ReturnType<typeof JSON.parse>>} args - Arguments after the factory name (and count for lists).
+ * @returns {{traits: string[], overrides: Record<string, ReturnType<typeof JSON.parse>>}} - Normalized invocation.
  */
 function normalizeInvocationArgs(args) {
   /** @type {string[]} */
   const traits = []
-  /** @type {Record<string, ?>} */
+  /** @type {Record<string, ReturnType<typeof JSON.parse>>} */
   let overrides = {}
   let sawOverrides = false
 
@@ -115,7 +115,7 @@ export default class FactoryRegistry {
   /**
    * Subscribes to factory debug events (`start`, `success`, `failure`).
    * @param {string} event - Event name.
-   * @param {(payload: {invocationId: string, factory: string, strategy: string, traits: string[], durationMs?: number, error?: ?}) => void} handler - Event handler.
+   * @param {(payload: {invocationId: string, factory: string, strategy: string, traits: string[], durationMs?: number, error?: ReturnType<typeof JSON.parse>}) => void} handler - Event handler.
    * @returns {this} - This registry (for chaining).
    */
   on(event, handler) {
@@ -127,7 +127,7 @@ export default class FactoryRegistry {
   /**
    * Unsubscribes a previously-registered event handler.
    * @param {string} event - Event name.
-   * @param {(payload: ?) => void} handler - Event handler to remove.
+   * @param {(payload: ReturnType<typeof JSON.parse>) => void} handler - Event handler to remove.
    * @returns {this} - This registry (for chaining).
    */
   off(event, handler) {
@@ -139,8 +139,8 @@ export default class FactoryRegistry {
   /**
    * Resolves attributes without constructing a model or building associations.
    * @param {string} factoryName - Factory name.
-   * @param {Array<?>} args - Trait names then an optional overrides object.
-   * @returns {Promise<Record<string, ?>>} - The resolved attributes.
+   * @param {Array<ReturnType<typeof JSON.parse>>} args - Trait names then an optional overrides object.
+   * @returns {Promise<Record<string, ReturnType<typeof JSON.parse>>>} - The resolved attributes.
    */
   async attributesFor(factoryName, ...args) {
     const {traits, overrides} = normalizeInvocationArgs(args)
@@ -151,8 +151,8 @@ export default class FactoryRegistry {
   /**
    * Builds an unsaved record graph.
    * @param {string} factoryName - Factory name.
-   * @param {Array<?>} args - Trait names then an optional overrides object.
-   * @returns {Promise<?>} - The built record.
+   * @param {Array<ReturnType<typeof JSON.parse>>} args - Trait names then an optional overrides object.
+   * @returns {Promise<ReturnType<typeof JSON.parse>>} - The built record.
    */
   async build(factoryName, ...args) {
     const {traits, overrides} = normalizeInvocationArgs(args)
@@ -163,8 +163,8 @@ export default class FactoryRegistry {
   /**
    * Builds and persists a record graph.
    * @param {string} factoryName - Factory name.
-   * @param {Array<?>} args - Trait names then an optional overrides object.
-   * @returns {Promise<?>} - The persisted record.
+   * @param {Array<ReturnType<typeof JSON.parse>>} args - Trait names then an optional overrides object.
+   * @returns {Promise<ReturnType<typeof JSON.parse>>} - The persisted record.
    */
   async create(factoryName, ...args) {
     const {traits, overrides} = normalizeInvocationArgs(args)
@@ -176,8 +176,8 @@ export default class FactoryRegistry {
    * Resolves attributes for a list of records sequentially.
    * @param {string} factoryName - Factory name.
    * @param {number} count - Number of entries.
-   * @param {Array<?>} args - Trait names then an optional overrides object.
-   * @returns {Promise<Array<Record<string, ?>>>} - The resolved attribute objects.
+   * @param {Array<ReturnType<typeof JSON.parse>>} args - Trait names then an optional overrides object.
+   * @returns {Promise<Array<Record<string, ReturnType<typeof JSON.parse>>>>} - The resolved attribute objects.
    */
   async attributesForList(factoryName, count, ...args) {
     return await this._runList("attributesFor", factoryName, count, args)
@@ -187,8 +187,8 @@ export default class FactoryRegistry {
    * Builds a list of unsaved records sequentially.
    * @param {string} factoryName - Factory name.
    * @param {number} count - Number of records.
-   * @param {Array<?>} args - Trait names then an optional overrides object.
-   * @returns {Promise<Array<?>>} - The built records.
+   * @param {Array<ReturnType<typeof JSON.parse>>} args - Trait names then an optional overrides object.
+   * @returns {Promise<Array<ReturnType<typeof JSON.parse>>>} - The built records.
    */
   async buildList(factoryName, count, ...args) {
     return await this._runList("build", factoryName, count, args)
@@ -198,8 +198,8 @@ export default class FactoryRegistry {
    * Creates a list of persisted records sequentially.
    * @param {string} factoryName - Factory name.
    * @param {number} count - Number of records.
-   * @param {Array<?>} args - Trait names then an optional overrides object.
-   * @returns {Promise<Array<?>>} - The persisted records.
+   * @param {Array<ReturnType<typeof JSON.parse>>} args - Trait names then an optional overrides object.
+   * @returns {Promise<Array<ReturnType<typeof JSON.parse>>>} - The persisted records.
    */
   async createList(factoryName, count, ...args) {
     return await this._runList("create", factoryName, count, args)
@@ -208,8 +208,8 @@ export default class FactoryRegistry {
   /**
    * Resolves attributes for exactly two records.
    * @param {string} factoryName - Factory name.
-   * @param {Array<?>} args - Trait names then an optional overrides object.
-   * @returns {Promise<Array<Record<string, ?>>>} - The two resolved attribute objects.
+   * @param {Array<ReturnType<typeof JSON.parse>>} args - Trait names then an optional overrides object.
+   * @returns {Promise<Array<Record<string, ReturnType<typeof JSON.parse>>>>} - The two resolved attribute objects.
    */
   async attributesForPair(factoryName, ...args) {
     return await this._runList("attributesFor", factoryName, 2, args)
@@ -218,8 +218,8 @@ export default class FactoryRegistry {
   /**
    * Builds exactly two unsaved records.
    * @param {string} factoryName - Factory name.
-   * @param {Array<?>} args - Trait names then an optional overrides object.
-   * @returns {Promise<Array<?>>} - The two built records.
+   * @param {Array<ReturnType<typeof JSON.parse>>} args - Trait names then an optional overrides object.
+   * @returns {Promise<Array<ReturnType<typeof JSON.parse>>>} - The two built records.
    */
   async buildPair(factoryName, ...args) {
     return await this._runList("build", factoryName, 2, args)
@@ -228,8 +228,8 @@ export default class FactoryRegistry {
   /**
    * Creates exactly two persisted records.
    * @param {string} factoryName - Factory name.
-   * @param {Array<?>} args - Trait names then an optional overrides object.
-   * @returns {Promise<Array<?>>} - The two persisted records.
+   * @param {Array<ReturnType<typeof JSON.parse>>} args - Trait names then an optional overrides object.
+   * @returns {Promise<Array<ReturnType<typeof JSON.parse>>>} - The two persisted records.
    */
   async createPair(factoryName, ...args) {
     return await this._runList("create", factoryName, 2, args)
@@ -238,7 +238,7 @@ export default class FactoryRegistry {
   /**
    * Advances a sequence and returns its formatted value.
    * @param {string} sequenceName - Sequence name.
-   * @returns {Promise<?>} - The formatted value.
+   * @returns {Promise<ReturnType<typeof JSON.parse>>} - The formatted value.
    */
   async generate(sequenceName) {
     return await this._generateScoped(sequenceName, [])
@@ -248,10 +248,10 @@ export default class FactoryRegistry {
    * Advances a sequence `count` times and returns the formatted values.
    * @param {string} sequenceName - Sequence name.
    * @param {number} count - Number of values.
-   * @returns {Promise<Array<?>>} - The formatted values.
+   * @returns {Promise<Array<ReturnType<typeof JSON.parse>>>} - The formatted values.
    */
   async generateList(sequenceName, count) {
-    /** @type {Array<?>} */
+    /** @type {Array<ReturnType<typeof JSON.parse>>} */
     const values = []
 
     for (let index = 0; index < count; index++) {
@@ -326,12 +326,12 @@ export default class FactoryRegistry {
    * @param {"attributesFor" | "build" | "create"} strategy - Strategy name.
    * @param {string} factoryName - Factory name.
    * @param {number} count - Number of entries.
-   * @param {Array<?>} args - Trait names then an optional overrides object.
-   * @returns {Promise<Array<?>>} - The results.
+   * @param {Array<ReturnType<typeof JSON.parse>>} args - Trait names then an optional overrides object.
+   * @returns {Promise<Array<ReturnType<typeof JSON.parse>>>} - The results.
    */
   async _runList(strategy, factoryName, count, args) {
     const {traits, overrides} = normalizeInvocationArgs(args)
-    /** @type {Array<?>} */
+    /** @type {Array<ReturnType<typeof JSON.parse>>} */
     const results = []
     /** @type {import("./factory-runner.js").CompiledPlan | undefined} */
     let planTemplate
@@ -357,9 +357,9 @@ export default class FactoryRegistry {
    * @param {object} args - Options.
    * @param {string} args.factoryName - Factory name.
    * @param {string[]} args.traits - Ordered traits.
-   * @param {Record<string, ?>} args.overrides - Overrides.
+   * @param {Record<string, ReturnType<typeof JSON.parse>>} args.overrides - Overrides.
    * @param {"attributesFor" | "build" | "create"} args.strategy - Strategy name.
-   * @returns {Promise<?>} - The strategy result.
+   * @returns {Promise<ReturnType<typeof JSON.parse>>} - The strategy result.
    */
   async _runFactory(args) {
     return (await this._runFactoryInvocation(args)).result
@@ -370,10 +370,10 @@ export default class FactoryRegistry {
    * @param {object} args - Options.
    * @param {string} args.factoryName - Factory name.
    * @param {string[]} args.traits - Ordered traits.
-   * @param {Record<string, ?>} args.overrides - Overrides.
+   * @param {Record<string, ReturnType<typeof JSON.parse>>} args.overrides - Overrides.
    * @param {"attributesFor" | "build" | "create"} args.strategy - Strategy name.
    * @param {import("./factory-runner.js").CompiledPlan} [args.planTemplate] - Reusable declaration plan.
-   * @returns {Promise<{result: ?, planTemplate: import("./factory-runner.js").CompiledPlan}>} - Result and declaration plan.
+   * @returns {Promise<{result: ReturnType<typeof JSON.parse>, planTemplate: import("./factory-runner.js").CompiledPlan}>} - Result and declaration plan.
    */
   async _runFactoryInvocation({factoryName, traits, overrides, strategy, planTemplate}) {
     this._activeEvaluations += 1
@@ -484,7 +484,7 @@ export default class FactoryRegistry {
    * global scope and advances it.
    * @param {string} sequenceName - Sequence name.
    * @param {string[]} chainNames - Inheritance chain names (child last).
-   * @returns {Promise<?>} - The formatted value.
+   * @returns {Promise<ReturnType<typeof JSON.parse>>} - The formatted value.
    */
   async _generateScoped(sequenceName, chainNames) {
     for (let index = chainNames.length - 1; index >= 0; index--) {

package/src/testing/factory/factory-runner.js

@@ -7,7 +7,7 @@ import {FactoryCycleError, UndefinedFactoryError, UndefinedTraitError} from "./e
  * A resolved attribute/transient/association slot in a compiled plan.
  * @typedef {object} Slot
  * @property {"attribute" | "transient" | "association"} slotKind - Slot nature.
- * @property {?} value - Literal/lazy value, override value, or AssociationDeclaration.
+ * @property {ReturnType<typeof JSON.parse>} value - Literal/lazy value, override value, or AssociationDeclaration.
  * @property {boolean} isOverride - Whether the value came from a call-site override.
  */
 
@@ -16,7 +16,7 @@ import {FactoryCycleError, UndefinedFactoryError, UndefinedTraitError} from "./e
  * @typedef {object} CompiledPlan
  * @property {string} factoryName - Target factory name.
  * @property {import("./factory-definition.js").default} factoryDefinition - Target definition.
- * @property {(new (attributes?: Record<string, ?>) => ?) | null} modelClass - Resolved model class.
+ * @property {(new (attributes?: Record<string, ReturnType<typeof JSON.parse>>) => ReturnType<typeof JSON.parse>) | null} modelClass - Resolved model class.
  * @property {string[]} chainNames - Inheritance chain names (child last) for sequence scope.
  * @property {Map<string, Slot>} resolved - Name→slot map (last declaration wins).
  * @property {Map<string, import("./declarations.js").CallbackDeclaration[]>} callbacks - Deduped callbacks by event.
@@ -44,7 +44,7 @@ export default class FactoryRunner {
    * Compiles a factory invocation into a plan.
    * @param {string} factoryName - Factory to run.
    * @param {string[]} requestedTraits - Traits requested at the call site, in order.
-   * @param {Record<string, ?>} overrides - Call-site overrides (highest precedence).
+   * @param {Record<string, ReturnType<typeof JSON.parse>>} overrides - Call-site overrides (highest precedence).
    * @returns {CompiledPlan} - The compiled plan.
    */
   compile(factoryName, requestedTraits, overrides) {
@@ -83,7 +83,7 @@ export default class FactoryRunner {
   /**
    * Applies the current call-site overrides without mutating the reusable template.
    * @param {CompiledPlan} planTemplate - Reusable declaration plan.
-   * @param {Record<string, ?>} overrides - Current call-site overrides.
+   * @param {Record<string, ReturnType<typeof JSON.parse>>} overrides - Current call-site overrides.
    * @returns {CompiledPlan} - Per-invocation plan.
    */
   applyOverrides(planTemplate, overrides) {
@@ -148,7 +148,7 @@ export default class FactoryRunner {
   /**
    * Picks the nearest declared model class in the chain (child overrides parent).
    * @param {import("./factory-definition.js").default[]} chain - Inheritance chain.
-   * @returns {(new (attributes?: Record<string, ?>) => ?) | null} - The model class, or null.
+   * @returns {(new (attributes?: Record<string, ReturnType<typeof JSON.parse>>) => ReturnType<typeof JSON.parse>) | null} - The model class, or null.
    */
   _resolveModelClass(chain) {
     for (let index = chain.length - 1; index >= 0; index--) {
@@ -230,7 +230,7 @@ export default class FactoryRunner {
    * Folds flattened declarations into a reusable compiled plan.
    * @param {object} args - Options.
    * @param {Array<{decl: import("./declarations.js").Declaration}>} args.flattened - Flattened declarations.
-   * @param {(new (attributes?: Record<string, ?>) => ?) | null} args.modelClass - Resolved model class.
+   * @param {(new (attributes?: Record<string, ReturnType<typeof JSON.parse>>) => ReturnType<typeof JSON.parse>) | null} args.modelClass - Resolved model class.
    * @param {import("./factory-definition.js").default} args.target - Target factory definition.
    * @param {string[]} args.chainNames - Inheritance chain names.
    * @returns {CompiledPlan} - The compiled plan.
@@ -289,8 +289,8 @@ export default class FactoryRunner {
    * real foreign-key metadata. An explicit association object wins over its key;
    * otherwise an explicit key suppresses the factory-declared association.
    * @param {Map<string, Slot>} resolved - Folded slots.
-   * @param {Record<string, ?>} overrides - Call-site overrides.
-   * @param {(new (attributes?: Record<string, ?>) => ?) | null} modelClass - Resolved model class.
+   * @param {Record<string, ReturnType<typeof JSON.parse>>} overrides - Call-site overrides.
+   * @param {(new (attributes?: Record<string, ReturnType<typeof JSON.parse>>) => ReturnType<typeof JSON.parse>) | null} modelClass - Resolved model class.
    * @returns {void}
    */
   _arbitrateAssociationOverrides(resolved, overrides, modelClass) {

package/src/testing/factory/linter.js

@@ -37,7 +37,7 @@ export default class FactoryLinter {
    */
   async lint({factories, traits = false, strategy = "create"} = {}) {
     const definitions = this._selectDefinitions(factories)
-    /** @type {Array<{label: string, error: ?}>} */
+    /** @type {Array<{label: string, error: ReturnType<typeof JSON.parse>}>} */
     const failures = []
 
     for (const definition of definitions) {
@@ -75,7 +75,7 @@ export default class FactoryLinter {
    * @param {import("./factory-definition.js").default} definition - Factory definition.
    * @param {string[]} traits - Traits to apply for this case.
    * @param {"attributesFor" | "build" | "create"} strategy - Strategy to run.
-   * @param {Array<{label: string, error: ?}>} failures - Failure sink.
+   * @param {Array<{label: string, error: ReturnType<typeof JSON.parse>}>} failures - Failure sink.
    * @returns {Promise<void>} - Resolves when the case has been evaluated.
    */
   async _lintCase(definition, traits, strategy, failures) {

package/src/testing/factory/model-contract.js

@@ -8,9 +8,9 @@ import {ModelContractError} from "./errors.js"
  * initialized backend Velocious `DatabaseRecord` subclass. Uninitialized backend
  * classes and non-backend classes (e.g. generated frontend models) are rejected
  * with a named, actionable error rather than failing deep inside construction.
- * @param {?} modelClass - The candidate model class.
+ * @param {ReturnType<typeof JSON.parse>} modelClass - The candidate model class.
  * @param {string} factoryName - Factory name, for the error message.
- * @returns {new (attributes?: Record<string, ?>) => import("../../database/record/index.js").default} - The validated model class.
+ * @returns {new (attributes?: Record<string, ReturnType<typeof JSON.parse>>) => import("../../database/record/index.js").default} - The validated model class.
  */
 export function assertModelClass(modelClass, factoryName) {
   if (typeof modelClass !== "function") {
@@ -27,5 +27,5 @@ export function assertModelClass(modelClass, factoryName) {
     throw new ModelContractError(`Factory "${factoryName}" model ${backendModelClass.name} has not been initialized. Ensure the model class is initialized (e.g. via configuration.initialize()/ensureInitialized) before build/create.`)
   }
 
-  return /** @type {new (attributes?: Record<string, ?>) => import("../../database/record/index.js").default} */ (modelClass)
+  return /** @type {new (attributes?: Record<string, ReturnType<typeof JSON.parse>>) => import("../../database/record/index.js").default} */ (modelClass)
 }

package/src/testing/factory/sequence.js

@@ -3,7 +3,7 @@
 /**
  * SequenceFormatter type. Receives the synchronously-allocated numeric value and
  * returns the formatted value (optionally asynchronously).
- * @typedef {(args: {value: number}) => (? | Promise<?>)} SequenceFormatter
+ * @typedef {(args: {value: number}) => (ReturnType<typeof JSON.parse> | Promise<ReturnType<typeof JSON.parse>>)} SequenceFormatter
  */
 
 /**
@@ -54,7 +54,7 @@ export default class Sequence {
    * Advances the sequence and returns the formatted value. The numeric value is
    * consumed synchronously before awaiting the formatter, so a rejected formatter
    * still advances the counter.
-   * @returns {Promise<?>} - The formatted value.
+   * @returns {Promise<ReturnType<typeof JSON.parse>>} - The formatted value.
    */
   async next() {
     const value = this._allocate()

package/src/testing/factory/strategies/attributes-for.js

@@ -14,7 +14,7 @@ export default class AttributesForStrategy extends BaseStrategy {
    * @param {object} args - Options.
    * @param {import("../factory-registry.js").default} args.registry - Owning registry.
    * @param {import("../factory-runner.js").CompiledPlan} args.plan - Compiled plan.
-   * @returns {Promise<Record<string, ?>>} - The resolved attributes.
+   * @returns {Promise<Record<string, ReturnType<typeof JSON.parse>>>} - The resolved attributes.
    */
   async run({registry, plan}) {
     const context = this._newContext(registry, plan, "attributesFor")

package/src/testing/factory/strategies/base.js

@@ -27,8 +27,8 @@ export default class BaseStrategy {
    * Builds the callback `context` object: evaluated transients exposed as plain
    * properties (no Proxy) plus the named evaluator methods.
    * @param {EvaluationContext} context - Evaluation context.
-   * @param {Record<string, ?>} transients - Evaluated transient values.
-   * @returns {Record<string, ?>} - The callback context.
+   * @param {Record<string, ReturnType<typeof JSON.parse>>} transients - Evaluated transient values.
+   * @returns {Record<string, ReturnType<typeof JSON.parse>>} - The callback context.
    */
   _callbackContext(context, transients) {
     return Object.assign({}, transients, context.contextFor([]))
@@ -39,7 +39,7 @@ export default class BaseStrategy {
    * @param {EvaluationContext} context - Evaluation context.
    * @param {import("../factory-runner.js").CompiledPlan} plan - Compiled plan.
    * @param {string} event - Event name (e.g. "afterCreate").
-   * @param {{record: ?, transients: Record<string, ?>, strategy: string}} state - Current record/transients/strategy.
+   * @param {{record: ReturnType<typeof JSON.parse>, transients: Record<string, ReturnType<typeof JSON.parse>>, strategy: string}} state - Current record/transients/strategy.
    * @returns {Promise<void>} - Resolves when all callbacks complete.
    */
   async _runCallbacks(context, plan, event, state) {
@@ -60,14 +60,14 @@ export default class BaseStrategy {
    * is attached as a detail rather than masking it.
    * @param {EvaluationContext} context - Evaluation context.
    * @param {import("../factory-runner.js").CompiledPlan} plan - Compiled plan.
-   * @param {() => {record: ?, transients: Record<string, ?>, strategy: string}} state - Late-bound state accessor.
-   * @param {() => Promise<?>} body - The strategy body.
-   * @returns {Promise<?>} - The body's result.
+   * @param {() => {record: ReturnType<typeof JSON.parse>, transients: Record<string, ReturnType<typeof JSON.parse>>, strategy: string}} state - Late-bound state accessor.
+   * @param {() => Promise<ReturnType<typeof JSON.parse>>} body - The strategy body.
+   * @returns {Promise<ReturnType<typeof JSON.parse>>} - The body's result.
    */
   async _runWithAfterAll(context, plan, state, body) {
-    /** @type {?} */
+    /** @type {ReturnType<typeof JSON.parse>} */
     let result
-    /** @type {?} */
+    /** @type {ReturnType<typeof JSON.parse>} */
     let primaryError
     let hasPrimaryError = false
 
@@ -78,7 +78,7 @@ export default class BaseStrategy {
       hasPrimaryError = true
     }
 
-    /** @type {?} */
+    /** @type {ReturnType<typeof JSON.parse>} */
     let cleanupError
     let hasCleanupError = false
 
@@ -102,8 +102,8 @@ export default class BaseStrategy {
 
   /**
    * Attaches an afterAll cleanup failure to the primary error without masking it.
-   * @param {?} primaryError - The original error that will propagate.
-   * @param {?} cleanupError - The afterAll cleanup failure.
+   * @param {ReturnType<typeof JSON.parse>} primaryError - The original error that will propagate.
+   * @param {ReturnType<typeof JSON.parse>} cleanupError - The afterAll cleanup failure.
    * @returns {void}
    */
   _attachCleanupFailure(primaryError, cleanupError) {
@@ -118,10 +118,10 @@ export default class BaseStrategy {
    * `initializeWith` constructor and never assigning constructor-consumed
    * attributes twice.
    * @param {import("../factory-runner.js").CompiledPlan} plan - Compiled plan.
-   * @param {Record<string, ?>} publicAttributes - Evaluated public attributes.
+   * @param {Record<string, ReturnType<typeof JSON.parse>>} publicAttributes - Evaluated public attributes.
    * @param {EvaluationContext} context - Evaluation context.
-   * @param {Record<string, ?>} transients - Evaluated transients.
-   * @returns {Promise<?>} - The constructed record.
+   * @param {Record<string, ReturnType<typeof JSON.parse>>} transients - Evaluated transients.
+   * @returns {Promise<ReturnType<typeof JSON.parse>>} - The constructed record.
    */
   async _constructRecord(plan, publicAttributes, context, transients) {
     const ModelClass = assertModelClass(plan.modelClass, plan.factoryName)
@@ -138,11 +138,11 @@ export default class BaseStrategy {
    * the constructor consumed through its `get(name)` accessor and assigning only
    * the remaining public attributes afterwards.
    * @param {import("../factory-runner.js").CompiledPlan} plan - Compiled plan.
-   * @param {new (attributes?: Record<string, ?>) => import("../../../database/record/index.js").default} ModelClass - Validated declared model class.
-   * @param {Record<string, ?>} publicAttributes - Evaluated public attributes.
+   * @param {new (attributes?: Record<string, ReturnType<typeof JSON.parse>>) => import("../../../database/record/index.js").default} ModelClass - Validated declared model class.
+   * @param {Record<string, ReturnType<typeof JSON.parse>>} publicAttributes - Evaluated public attributes.
    * @param {EvaluationContext} context - Evaluation context.
-   * @param {Record<string, ?>} transients - Evaluated transients.
-   * @returns {Promise<?>} - The constructed record.
+   * @param {Record<string, ReturnType<typeof JSON.parse>>} transients - Evaluated transients.
+   * @returns {Promise<ReturnType<typeof JSON.parse>>} - The constructed record.
    */
   async _constructWithInitializer(plan, ModelClass, publicAttributes, context, transients) {
     /** @type {Set<string>} */
@@ -159,7 +159,7 @@ export default class BaseStrategy {
       throw new ModelContractError(`Factory "${plan.factoryName}" initializeWith must return an instance of ${ModelClass.name}, got: ${String(record)}`)
     }
 
-    /** @type {Record<string, ?>} */
+    /** @type {Record<string, ReturnType<typeof JSON.parse>>} */
     const remaining = {}
 
     for (const key of Object.keys(publicAttributes)) {
@@ -167,7 +167,7 @@ export default class BaseStrategy {
     }
 
     if (Object.keys(remaining).length > 0) {
-      /** @type {?} */ (record).assign(remaining)
+      /** @type {ReturnType<typeof JSON.parse>} */ (record).assign(remaining)
     }
 
     return record
@@ -176,8 +176,8 @@ export default class BaseStrategy {
   /**
    * Wires evaluated associations onto a record through public relationship
    * reflection and generated setters (never private caches or guessed keys).
-   * @param {?} record - The owning record.
-   * @param {Array<{name: string, record: ?}>} associations - Evaluated associations.
+   * @param {ReturnType<typeof JSON.parse>} record - The owning record.
+   * @param {Array<{name: string, record: ReturnType<typeof JSON.parse>}>} associations - Evaluated associations.
    * @returns {void}
    */
   _assignAssociations(record, associations) {
@@ -197,8 +197,8 @@ export default class BaseStrategy {
 
   /**
    * Normalizes a has-many association value into an array of records.
-   * @param {?} value - Association value (record, array, or null).
-   * @returns {Array<?>} - The normalized record array.
+   * @param {ReturnType<typeof JSON.parse>} value - Association value (record, array, or null).
+   * @returns {Array<ReturnType<typeof JSON.parse>>} - The normalized record array.
    */
   _toRecordArray(value) {
     if (value == null) return []

package/src/testing/factory/strategies/build.js

@@ -13,11 +13,11 @@ export default class BuildStrategy extends BaseStrategy {
    * @param {object} args - Options.
    * @param {import("../factory-registry.js").default} args.registry - Owning registry.
    * @param {import("../factory-runner.js").CompiledPlan} args.plan - Compiled plan.
-   * @returns {Promise<?>} - The built (unsaved) record.
+   * @returns {Promise<ReturnType<typeof JSON.parse>>} - The built (unsaved) record.
    */
   async run({registry, plan}) {
     const context = this._newContext(registry, plan, "build")
-    /** @type {{record: ?, transients: Record<string, ?>}} */
+    /** @type {{record: ReturnType<typeof JSON.parse>, transients: Record<string, ReturnType<typeof JSON.parse>>}} */
     const runState = {record: undefined, transients: {}}
     const state = () => ({record: runState.record, transients: runState.transients, strategy: "build"})
 

package/src/testing/factory/strategies/create.js

@@ -15,11 +15,11 @@ export default class CreateStrategy extends BaseStrategy {
    * @param {object} args - Options.
    * @param {import("../factory-registry.js").default} args.registry - Owning registry.
    * @param {import("../factory-runner.js").CompiledPlan} args.plan - Compiled plan.
-   * @returns {Promise<?>} - The persisted record.
+   * @returns {Promise<ReturnType<typeof JSON.parse>>} - The persisted record.
    */
   async run({registry, plan}) {
     const context = this._newContext(registry, plan, "create")
-    /** @type {{record: ?, transients: Record<string, ?>}} */
+    /** @type {{record: ReturnType<typeof JSON.parse>, transients: Record<string, ReturnType<typeof JSON.parse>>}} */
     const runState = {record: undefined, transients: {}}
     const state = () => ({record: runState.record, transients: runState.transients, strategy: "create"})
 
@@ -49,9 +49,9 @@ export default class CreateStrategy extends BaseStrategy {
    * Persists the record via a custom `toCreate`, native `save()`, or not at all
    * when `skipCreate` is declared.
    * @param {import("../factory-runner.js").CompiledPlan} plan - Compiled plan.
-   * @param {?} record - The record to persist.
+   * @param {ReturnType<typeof JSON.parse>} record - The record to persist.
    * @param {import("../evaluation-context.js").default} context - Evaluation context.
-   * @param {Record<string, ?>} transients - Evaluated transients.
+   * @param {Record<string, ReturnType<typeof JSON.parse>>} transients - Evaluated transients.
    * @returns {Promise<void>} - Resolves when persistence completes.
    */
   async _persist(plan, record, context, transients) {

package/src/testing/test-files-finder.js

@@ -147,7 +147,7 @@ export default class TestFilesFinder {
 
   /**
    * Runs with finding count.
-   * @param {function() : Promise<void>} callback - Callback function.
+   * @param {() => Promise<void>} callback - Callback function.
    * @returns {Promise<void>} - Resolves when complete.
    */
   withFindingCount(callback) {

package/src/testing/test-runner.js

@@ -44,7 +44,7 @@ import {clearDeliveries} from "../mailer.js"
  * @property {TestArgs} args - Arguments passed to the test.
  * @property {string} [filePath] - Source file path.
  * @property {number} [line] - Source line number.
- * @property {function(TestArgs) : (void|Promise<void>)} function - Test callback to execute.
+ * @property {(arg: TestArgs) => (void|Promise<void>)} function - Test callback to execute.
  */
 /**
  * FailedTestDetail type.
@@ -52,7 +52,7 @@ import {clearDeliveries} from "../mailer.js"
  * @property {string} fullDescription - Full test description.
  * @property {string} [filePath] - Source file path.
  * @property {number} [line] - Source line number.
- * @property {?} error - Failure error.
+ * @property {ReturnType<typeof JSON.parse>} error - Failure error.
  * @property {string} [consoleOutput] - Captured console output while test ran.
  * @property {string} [consoleLogPath] - Saved console log path.
  */
@@ -64,7 +64,7 @@ import {clearDeliveries} from "../mailer.js"
  */
 /**
  * Defines this typedef.
- * @typedef {function({configuration: import("../configuration.js").default, testArgs: TestArgs, testData: TestData}) : (void|Promise<void>)} AfterBeforeEachCallbackType
+ * @typedef {(args: {configuration: import("../configuration.js").default, testArgs: TestArgs, testData: TestData}) => (void|Promise<void>)} AfterBeforeEachCallbackType
  */
 /**
  * AfterBeforeEachCallbackObjectType type.
@@ -73,7 +73,7 @@ import {clearDeliveries} from "../mailer.js"
  */
 /**
  * Defines this typedef.
- * @typedef {function({configuration: import("../configuration.js").default}) : (void|Promise<void>)} BeforeAfterAllCallbackType
+ * @typedef {(args: {configuration: import("../configuration.js").default}) => (void|Promise<void>)} BeforeAfterAllCallbackType
  */
 /**
  * BeforeAfterAllCallbackObjectType type.
@@ -108,10 +108,10 @@ import {clearDeliveries} from "../mailer.js"
  * The rejected error is tagged with `velociousTestTimeout` so the runner knows
  * the lifecycle (and its afterEach database cleanup) is still in flight and can
  * wait for it to settle before the next test reuses the shared connection.
- * @param {Promise<?> | ?} promise - Promise or value.
+ * @param {Promise<ReturnType<typeof JSON.parse>> | ReturnType<typeof JSON.parse>} promise - Promise or value.
  * @param {number} timeoutMs - Timeout in milliseconds.
  * @param {string} testDescription - Test description.
- * @returns {Promise<?>} - Resolves or rejects based on timeout or promise result.
+ * @returns {Promise<ReturnType<typeof JSON.parse>>} - Resolves or rejects based on timeout or promise result.
  */
 function runWithTimeout(promise, timeoutMs, testDescription) {
   const timeoutSeconds = (timeoutMs / 1000).toFixed(3).replace(/\.?0+$/, "")
@@ -142,7 +142,7 @@ function runWithTimeout(promise, timeoutMs, testDescription) {
  * top-level await when the timed-out lifecycle has no ref'd handles of its own
  * (for example a stalled mocked async API). Once the caller continues past this
  * await, the timer has already resolved and no longer anchors the event loop.
- * @param {Promise<?>} lifecycle - The abandoned per-test lifecycle promise.
+ * @param {Promise<ReturnType<typeof JSON.parse>>} lifecycle - The abandoned per-test lifecycle promise.
  * @param {number} graceMs - Maximum time to wait for the lifecycle to settle.
  * @returns {Promise<boolean>} - Whether the lifecycle settled within the grace period.
  */
@@ -965,21 +965,21 @@ export default class TestRunner {
           let shouldRetry = false
           /**
            * Defines caughtError.
-           * @type {?} */
+           * @type {ReturnType<typeof JSON.parse>} */
           let caughtError
           /**
            * Defines failedError.
-           * @type {?} */
+           * @type {ReturnType<typeof JSON.parse>} */
           let failedError
           /**
            * Defines lastError.
-           * @type {?} */
+           * @type {ReturnType<typeof JSON.parse>} */
           let lastError
           let willRetry = false
           /**
            * The per-test lifecycle promise, hoisted so the timeout branch can
            * still wait for it to settle after runWithTimeout has abandoned it.
-           * @type {Promise<?> | undefined} */
+           * @type {Promise<ReturnType<typeof JSON.parse>> | undefined} */
           let testLifecycle
           /** @type {{pool: import("../database/pool/base.js").default, registration: import("../database/pool/base.js").TestSharedConnectionRegistration}[]} */
           let testSharedConnectionRegistrations = []
@@ -1390,11 +1390,11 @@ export default class TestRunner {
     const lines = []
     /**
      * Console object.
-     * @type {Record<ConsoleMethodName, (...args: Array<?>) => void>} */
-    const consoleObject = /** @type {Record<ConsoleMethodName, (...args: Array<?>) => void>} */ (console)
+     * @type {Record<ConsoleMethodName, (...args: Array<ReturnType<typeof JSON.parse>>) => void>} */
+    const consoleObject = /** @type {Record<ConsoleMethodName, (...args: Array<ReturnType<typeof JSON.parse>>) => void>} */ (console)
     /**
      * Original console methods.
-     * @type {Record<ConsoleMethodName, (...args: Array<?>) => void>} */
+     * @type {Record<ConsoleMethodName, (...args: Array<ReturnType<typeof JSON.parse>>) => void>} */
     const originalConsoleMethods = {
       debug: consoleObject.debug.bind(console),
       error: consoleObject.error.bind(console),