velocious 1.0.577 → 1.0.579

package/build/tenants/tenant-handle.js

@@ -0,0 +1,252 @@
+// @ts-check
+
+/**
+ * TenantDescriptorValue type.
+ * @typedef {null | boolean | number | string | TenantDescriptorValue[] | {[key: string]: TenantDescriptorValue}} TenantDescriptorValue
+ */
+/** @typedef {{[key: string]: TenantDescriptorValue}} TenantDescriptor */
+
+/**
+ * Returns a readable path for a captured descriptor/configuration value.
+ * @param {string} path - Parent path.
+ * @param {string | number} key - Child key.
+ * @returns {string} - Child path.
+ */
+function childPath(path, key) {
+  if (typeof key === "number") return `${path}[${key}]`
+
+  return path ? `${path}.${key}` : key
+}
+
+/**
+ * Returns the runtime class label for an unsupported capture value.
+ * @param {object} value - Unsupported value.
+ * @returns {string} - Runtime class label.
+ */
+function valueClassName(value) {
+  return value.constructor?.name || "object"
+}
+
+/**
+ * Defines one captured key without invoking inherited setters such as
+ * `Object.prototype.__proto__`.
+ * @param {Record<string, ReturnType<typeof JSON.parse>>} target - Captured object.
+ * @param {string} key - Own key to define.
+ * @param {ReturnType<typeof JSON.parse>} value - Captured value.
+ */
+function defineCapturedDataProperty(target, key, value) {
+  Object.defineProperty(target, key, {
+    configurable: true,
+    enumerable: true,
+    value,
+    writable: true
+  })
+}
+
+/**
+ * Deeply copies and freezes a JSON-compatible tenant descriptor value.
+ * @param {ReturnType<typeof JSON.parse>} value - Value to capture.
+ * @param {string} path - Descriptor path.
+ * @param {Set<object>} ancestors - Active ancestor objects used for cycle detection.
+ * @returns {TenantDescriptorValue} - Immutable captured value.
+ */
+function captureTenantValue(value, path, ancestors) {
+  if (value === null || typeof value === "string" || typeof value === "boolean") return value
+  if (typeof value === "number" && Number.isFinite(value)) return value
+
+  if (!value || typeof value !== "object") {
+    throw new TypeError(`Tenant descriptor contains an unsupported value at ${path}: ${typeof value}`)
+  }
+  if (ancestors.has(value)) throw new TypeError(`Tenant descriptor contains a cycle at ${path}`)
+
+  ancestors.add(value)
+
+  try {
+    if (Array.isArray(value)) {
+      const capturedEntries = value.map((entry, index) => captureTenantValue(entry, childPath(path, index), ancestors))
+
+      Object.freeze(capturedEntries)
+
+      return capturedEntries
+    }
+
+    const prototype = Object.getPrototypeOf(value)
+
+    if (prototype !== Object.prototype && prototype !== null) {
+      throw new TypeError(`Tenant descriptor contains an unsupported value at ${path}: ${valueClassName(value)}`)
+    }
+
+    /** @type {TenantDescriptor} */
+    const captured = {}
+
+    for (const [key, entry] of Object.entries(value)) {
+      defineCapturedDataProperty(captured, key, captureTenantValue(entry, childPath(path, key), ancestors))
+    }
+
+    return Object.freeze(captured)
+  } finally {
+    ancestors.delete(value)
+  }
+}
+
+/**
+ * Captures a root application tenant descriptor.
+ * @param {object} tenant - Ordinary or null-prototype JSON-compatible tenant descriptor.
+ * @returns {TenantDescriptor} - Immutable descriptor snapshot.
+ */
+function captureTenant(tenant) {
+  return /** @type {TenantDescriptor} */ (captureTenantValue(tenant, "", new Set()))
+}
+
+/**
+ * Deeply captures configuration values while retaining function/class identities.
+ * Mutable non-plain runtime objects are rejected because retaining them would let
+ * callers redirect a handle after construction.
+ * @param {ReturnType<typeof JSON.parse>} value - Configuration value.
+ * @param {string} path - Configuration path.
+ * @param {Set<object>} ancestors - Active ancestor objects.
+ * @returns {ReturnType<typeof JSON.parse>} - Immutable captured value.
+ */
+function captureConfigurationValue(value, path, ancestors) {
+  if (value === null || value === undefined || typeof value === "string" || typeof value === "boolean" || typeof value === "number" || typeof value === "function") {
+    return value
+  }
+  if (typeof value !== "object") {
+    throw new TypeError(`Tenant database configuration contains an unsupported value at ${path}: ${typeof value}`)
+  }
+  if (ancestors.has(value)) throw new TypeError(`Tenant database configuration contains a cycle at ${path}`)
+
+  const prototype = Object.getPrototypeOf(value)
+
+  if (!Array.isArray(value) && prototype !== Object.prototype && prototype !== null) {
+    if (Object.isFrozen(value)) return value
+
+    throw new TypeError(`Tenant database configuration contains an unsupported mutable value at ${path}: ${valueClassName(value)}`)
+  }
+
+  ancestors.add(value)
+
+  try {
+    if (Array.isArray(value)) {
+      return Object.freeze(value.map((entry, index) => captureConfigurationValue(entry, childPath(path, index), ancestors)))
+    }
+
+    /** @type {Record<string, ReturnType<typeof JSON.parse>>} */
+    const captured = {}
+
+    for (const [key, entry] of Object.entries(value)) {
+      defineCapturedDataProperty(captured, key, captureConfigurationValue(entry, childPath(path, key), ancestors))
+    }
+
+    return Object.freeze(captured)
+  } finally {
+    ancestors.delete(value)
+  }
+}
+
+/**
+ * Copies and deeply freezes a resolved physical database configuration.
+ * @param {import("../configuration-types.js").DatabaseConfigurationType} databaseConfiguration - Resolved database configuration.
+ * @returns {import("../configuration-types.js").DatabaseConfigurationType} - Captured configuration.
+ */
+function captureDatabaseConfiguration(databaseConfiguration) {
+  return /** @type {import("../configuration-types.js").DatabaseConfigurationType} */ (
+    captureConfigurationValue(databaseConfiguration, "databaseConfiguration", new Set())
+  )
+}
+
+/**
+ * Immutable tenant/database handle. Physical database configurations are
+ * resolved and captured at construction, so later ambient tenant changes
+ * cannot redirect work performed through this handle.
+ */
+export default class TenantHandle {
+  /**
+   * Runs constructor.
+   * @param {object} args - Handle arguments.
+   * @param {import("../configuration.js").default} args.configuration - Owning configuration.
+   * @param {object} args.tenant - Ordinary or null-prototype JSON-compatible application tenant descriptor.
+   */
+  constructor({configuration, tenant}) {
+    if (!configuration) throw new Error("TenantHandle requires a configuration")
+    if (!tenant || typeof tenant !== "object" || Array.isArray(tenant)) {
+      throw new TypeError("TenantHandle requires a tenant object")
+    }
+
+    const capturedTenant = captureTenant(tenant)
+    /** @type {Record<string, import("../configuration-types.js").DatabaseConfigurationType>} */
+    const databaseConfigurations = Object.create(null)
+    const disabledIdentifiers = configuration.getDisabledDatabaseIdentifiers()
+
+    for (const identifier of Object.keys(configuration.getDatabaseConfiguration())) {
+      if (disabledIdentifiers.has(identifier)) continue
+      if (!configuration.isDatabaseIdentifierActive(identifier, capturedTenant)) continue
+
+      databaseConfigurations[identifier] = captureDatabaseConfiguration(
+        configuration.resolveDatabaseConfiguration(identifier, capturedTenant)
+      )
+    }
+
+    this._configuration = configuration
+    this._databaseConfigurations = Object.freeze(databaseConfigurations)
+    this._tenant = capturedTenant
+
+    Object.freeze(this)
+  }
+
+  /**
+   * Returns the captured tenant descriptor. Routing never re-resolves physical
+   * identity from this value after handle construction.
+   * @returns {TenantDescriptor} - Tenant descriptor.
+   */
+  tenant() {
+    return this._tenant
+  }
+
+  /**
+   * Returns the captured physical configuration for an active identifier.
+   * @param {string} databaseIdentifier - Logical database identifier.
+   * @returns {import("../configuration-types.js").DatabaseConfigurationType} - Captured resolved configuration.
+   */
+  databaseConfiguration(databaseIdentifier) {
+    const databaseConfiguration = this._databaseConfigurations[databaseIdentifier]
+
+    if (!databaseConfiguration) {
+      throw new Error(`Unknown or inactive database identifier for tenant handle: ${databaseIdentifier}`)
+    }
+
+    return databaseConfiguration
+  }
+
+  /**
+   * Runs explicit ORM work on one pinned connection for this handle's captured
+   * physical database. Use `operation.forModel(ModelClass)` for queries and
+   * writes; loaded records and association/preload work retain that operation.
+   * @template T
+   * @param {{databaseIdentifier: string, name?: string}} options - Logical database and checkout name.
+   * @param {(operation: import("../database/operation.js").default) => Promise<T>} callback - Owned work callback.
+   * @returns {Promise<T>} - Callback result.
+   */
+  async databaseOperation({databaseIdentifier, name = "TenantHandle.databaseOperation"}, callback) {
+    return await this._configuration.withDatabaseOperation({
+      databaseConfiguration: this.databaseConfiguration(databaseIdentifier),
+      databaseIdentifier,
+      name,
+      tenant: this._tenant
+    }, callback)
+  }
+
+  /**
+   * Runs explicit ORM work in a transaction pinned to this handle's captured
+   * physical database.
+   * @template T
+   * @param {{databaseIdentifier: string, name?: string}} options - Logical database and checkout name.
+   * @param {(operation: import("../database/operation.js").default) => Promise<T>} callback - Transaction callback.
+   * @returns {Promise<T>} - Callback result.
+   */
+  async transaction({databaseIdentifier, name = "TenantHandle.transaction"}, callback) {
+    return await this.databaseOperation({databaseIdentifier, name}, async (operation) => {
+      return await operation.transaction(async () => await callback(operation))
+    })
+  }
+}

package/build/tenants/tenant-iterator.js

@@ -22,8 +22,8 @@ export default class TenantIterator {
 
   /**
    * Runs `callback` within each tenant's context and returns how many tenants were processed.
-   * @param {Array<?>} tenants - Tenant descriptors to enter and process.
-   * @param {function({databaseConfiguration: import("../configuration-types.js").DatabaseConfigurationType, tenant: ?}) : Promise<void>} callback - Per-tenant operation receiving the active database configuration.
+   * @param {Array<ReturnType<typeof JSON.parse>>} tenants - Tenant descriptors to enter and process.
+   * @param {(args: {databaseConfiguration: import("../configuration-types.js").DatabaseConfigurationType, tenant: ReturnType<typeof JSON.parse>}) => Promise<void>} callback - Per-tenant operation receiving the active database configuration.
    * @returns {Promise<number>} - Number of processed tenants.
    */
   async run(tenants, callback) {
@@ -35,7 +35,7 @@ export default class TenantIterator {
       return tenants.length
     }
 
-    /** @type {Array<{error: Error, tenant: ?}>} */
+    /** @type {Array<{error: Error, tenant: ReturnType<typeof JSON.parse>}>} */
     const failures = []
     const workers = []
     let tenantIndex = 0
@@ -76,7 +76,7 @@ export default class TenantIterator {
 
   /**
    * Enters one tenant's context and runs the callback, asserting the database is active first.
-   * @param {{callback: function({databaseConfiguration: import("../configuration-types.js").DatabaseConfigurationType, tenant: ?}) : Promise<void>, tenant: ?}} args - Tenant descriptor and operation to run in its context.
+   * @param {{callback: (args: {databaseConfiguration: import("../configuration-types.js").DatabaseConfigurationType, tenant: ReturnType<typeof JSON.parse>}) => Promise<void>, tenant: ReturnType<typeof JSON.parse>}} args - Tenant descriptor and operation to run in its context.
    * @returns {Promise<void>}
    */
   async runTenantCallback({callback, tenant}) {
@@ -94,12 +94,12 @@ export default class TenantIterator {
 
   /**
    * Builds a human-readable label for a tenant for use in error messages.
-   * @param {?} tenant - Tenant descriptor to identify in an error.
+   * @param {ReturnType<typeof JSON.parse>} tenant - Tenant descriptor to identify in an error.
    * @returns {string} - Human-readable tenant label.
    */
   static tenantLabel(tenant) {
     if (tenant && typeof tenant === "object") {
-      const tenantObject = /** @type {{id?: ?, name?: ?, slug?: ?}} */ (tenant)
+      const tenantObject = /** @type {{id?: ReturnType<typeof JSON.parse>, name?: ReturnType<typeof JSON.parse>, slug?: ReturnType<typeof JSON.parse>}} */ (tenant)
 
       for (const attributeName of /** @type {Array<"slug" | "name" | "id">} */ (["slug", "name", "id"])) {
         const attributeOrAccessor = tenantObject[attributeName]

package/build/tenants/tenant-model-scope.js

@@ -0,0 +1,132 @@
+// @ts-check
+
+import TenantHandle from "./tenant-handle.js"
+
+/**
+ * Model query/create scope bound to one immutable tenant handle.
+ * @template {typeof import("../database/record/index.js").default} MC
+ */
+export default class TenantModelScope {
+  /**
+   * Runs constructor.
+   * @param {object} args - Scope arguments.
+   * @param {import("../configuration.js").default} args.configuration - Owning configuration.
+   * @param {MC} args.modelClass - Model class to bind.
+   * @param {object} args.tenant - Ordinary or null-prototype JSON-compatible tenant descriptor.
+   */
+  constructor({configuration, modelClass, tenant}) {
+    this._handle = new TenantHandle({configuration, tenant})
+    this._modelClass = modelClass
+    this._databaseIdentifier = modelClass.getDatabaseIdentifier({tenant})
+
+    Object.freeze(this)
+  }
+
+  /**
+   * Runs a general model query/write callback on the captured physical tenant.
+   * The query and every record/association it loads are owned by the operation
+   * and must be used inside the callback.
+   * @template T
+   * @param {(query: import("../database/query/model-class-query.js").default<MC>, operation: import("../database/operation.js").default) => Promise<T>} callback - Bound model callback.
+   * @returns {Promise<T>} - Callback result.
+   */
+  async databaseOperation(callback) {
+    return await this._handle.databaseOperation({
+      databaseIdentifier: this._databaseIdentifier,
+      name: `usingTenant: ${this._modelClass.getModelName()}`
+    }, async (operation) => {
+      await operation.ensureModelInitialized(this._modelClass)
+
+      return await callback(operation.forModel(this._modelClass), operation)
+    })
+  }
+
+  /**
+   * Runs a model callback in a transaction on the captured physical tenant.
+   * @template T
+   * @param {(query: import("../database/query/model-class-query.js").default<MC>, operation: import("../database/operation.js").default) => Promise<T>} callback - Transaction callback.
+   * @returns {Promise<T>} - Callback result.
+   */
+  async transaction(callback) {
+    return await this._handle.transaction({
+      databaseIdentifier: this._databaseIdentifier,
+      name: `usingTenant transaction: ${this._modelClass.getModelName()}`
+    }, async (operation) => {
+      await operation.ensureModelInitialized(this._modelClass)
+
+      return await callback(operation.forModel(this._modelClass), operation)
+    })
+  }
+
+  /**
+   * Creates a record on the captured tenant.
+   * @param {Record<string, ReturnType<typeof JSON.parse>>} [attributes] - Create attributes.
+   * @returns {Promise<InstanceType<MC>>} - Created record.
+   */
+  async create(attributes = {}) {
+    return await this.databaseOperation(async (query, operation) => {
+      const record = await query.create(attributes)
+
+      return record.releaseDatabaseOperation(operation)
+    })
+  }
+
+  /**
+   * Counts records on the captured tenant.
+   * @returns {Promise<number>} - Count on the captured tenant.
+   */
+  async count() {
+    return await this.databaseOperation(async (query) => await query.count())
+  }
+
+  /**
+   * Finds a record by primary key on the captured tenant.
+   * @param {string | number} recordId - Record identifier.
+   * @returns {Promise<InstanceType<MC> | null>} - Found record.
+   */
+  async find(recordId) {
+    return await this.databaseOperation(async (query, operation) => {
+      const record = await query.find(recordId)
+
+      return record ? record.releaseDatabaseOperation(operation) : null
+    })
+  }
+
+  /**
+   * Finds a record by conditions on the captured tenant.
+   * @param {Record<string, string | number>} conditions - Finder conditions.
+   * @returns {Promise<InstanceType<MC> | null>} - Found record.
+   */
+  async findBy(conditions) {
+    return await this.databaseOperation(async (query, operation) => {
+      const record = await query.findBy(conditions)
+
+      return record ? record.releaseDatabaseOperation(operation) : null
+    })
+  }
+
+  /**
+   * Finds a record by conditions or raises on the captured tenant.
+   * @param {Record<string, string | number>} conditions - Finder conditions.
+   * @returns {Promise<InstanceType<MC>>} - Found record.
+   */
+  async findByOrFail(conditions) {
+    return await this.databaseOperation(async (query, operation) => {
+      const record = await query.findByOrFail(conditions)
+
+      return record.releaseDatabaseOperation(operation)
+    })
+  }
+
+  /**
+   * Loads all records on the captured tenant.
+   * @returns {Promise<InstanceType<MC>[]>} - All records on the captured tenant.
+   */
+  async toArray() {
+    return await this.databaseOperation(async (query, operation) => {
+      const records = await query.toArray()
+
+      return records.map((record) => record.releaseDatabaseOperation(operation))
+    })
+  }
+}

package/build/tenants/tenant.js

@@ -3,6 +3,7 @@
 import Current from "../current.js"
 import {dropTenantDatabase} from "./default-tenant-database-provisioning.js"
 import TenantAggregator from "./tenant-aggregator.js"
+import TenantHandle from "./tenant-handle.js"
 import TenantIterator from "./tenant-iterator.js"
 
 /**
@@ -18,6 +19,18 @@ import TenantIterator from "./tenant-iterator.js"
  * app's tenant database provider hooks.
  */
 export default class Tenant {
+  /**
+   * Captures an immutable tenant/database handle for explicit browser/native
+   * ORM operations. Physical database configurations are resolved now and are
+   * never recomputed from later ambient tenant changes.
+   * @param {object} tenant - Ordinary or null-prototype JSON-compatible descriptor understood by the app's tenant database resolver.
+   * @param {import("../configuration.js").default} [configuration] - Owning configuration.
+   * @returns {TenantHandle} - Immutable captured handle.
+   */
+  static handle(tenant, configuration = Current.configuration()) {
+    return new TenantHandle({configuration, tenant})
+  }
+
   /**
    * Runs `callback` with `tenant` as the current tenant, restoring the previous tenant after.
    * The callback runs inside `ensureConnections`, so every database identifier the tenant
@@ -87,7 +100,7 @@ export default class Tenant {
    * tenant-switched models are initialized, so each tenant's database is queryable without the
    * caller wiring up connections or model metadata. Returns how many tenants the callback ran
    * for (after filtering).
-   * @param {{identifier: string, callback: function({databaseConfiguration: import("../configuration-types.js").DatabaseConfigurationType, tenant: ?}) : Promise<void>, parallel?: number, filter?: (tenant: ?) => boolean, configuration?: import("../configuration.js").default}} args - Tenant database identifier, per-tenant operation, filtering, and concurrency settings.
+   * @param {{identifier: string, callback: (args: {databaseConfiguration: import("../configuration-types.js").DatabaseConfigurationType, tenant: ReturnType<typeof JSON.parse>}) => Promise<void>, parallel?: number, filter?: (tenant: ReturnType<typeof JSON.parse>) => boolean, configuration?: import("../configuration.js").default}} args - Tenant database identifier, per-tenant operation, filtering, and concurrency settings.
    * @returns {Promise<number>} - Number of processed tenants.
    */
   static async each({identifier, callback, parallel = 1, filter, configuration = Current.configuration()}) {
@@ -125,7 +138,7 @@ export default class Tenant {
    * per-tenant subquery and declares the key columns and aggregates; see
    * {@link import("./tenant-aggregator.js").TenantAggregateOptions}.
    * @param {import("./tenant-aggregator.js").TenantAggregateOptions} options - Aggregate configuration.
-   * @returns {Promise<Array<Record<string, ?>>>} - One merged row per distinct key-column combination.
+   * @returns {Promise<Array<Record<string, ReturnType<typeof JSON.parse>>>>} - One merged row per distinct key-column combination.
    */
   static async aggregateAcross(options) {
     return await new TenantAggregator(options).run()

package/build/testing/browser-test-app.js

@@ -25,8 +25,8 @@ root.appendChild(systemTestingComponent)
 const systemTestBrowserHelper = new SystemTestBrowserHelper()
 systemTestBrowserHelper.enableOnBrowser()
 
-globalThis.velociousBrowserTest = {
+Object.assign(globalThis, {velociousBrowserTest: {
   BrowserEnvironmentHandler,
   runFrontendModelEventHookScenario,
   systemTestBrowserHelper
-}
+}})

package/build/testing/expect-to-change.js

@@ -7,7 +7,7 @@ export default class ExpectToChange extends BaseExpect {
   /**
    * Runs constructor.
    * @param {object} args - Options object.
-   * @param {function(): Promise<number>} args.changeCallback - Change callback.
+   * @param {() => Promise<number>} args.changeCallback - Change callback.
    * @param {import("./expect.js").default} args.expect - Expect.
    */
   constructor({changeCallback, expect, ...restArgs}) {

package/build/testing/expect-utils.js

@@ -4,8 +4,8 @@ import {anythingDifferent} from "set-state-compare/build/diff-utils.js"
 
 /**
  * Runs object containing.
- * @param {?} value - Value.
- * @returns {{__velociousMatcher: string, value: ?}} - Matcher wrapper.
+ * @param {ReturnType<typeof JSON.parse>} value - Value.
+ * @returns {{__velociousMatcher: string, value: ReturnType<typeof JSON.parse>}} - Matcher wrapper.
  */
 function objectContaining(value) {
   if (value === null || typeof value !== "object") {
@@ -20,8 +20,8 @@ function objectContaining(value) {
 
 /**
  * Runs array containing.
- * @param {?} value - Value.
- * @returns {{__velociousMatcher: string, value: ?}} - Matcher wrapper.
+ * @param {ReturnType<typeof JSON.parse>} value - Value.
+ * @returns {{__velociousMatcher: string, value: ReturnType<typeof JSON.parse>}} - Matcher wrapper.
  */
 function arrayContaining(value) {
   if (!Array.isArray(value)) {
@@ -36,7 +36,7 @@ function arrayContaining(value) {
 
 /**
  * Runs is object like.
- * @param {?} value - Value.
+ * @param {ReturnType<typeof JSON.parse>} value - Value.
  * @returns {boolean} - Whether object-like.
  */
 function isObjectLike(value) {
@@ -45,25 +45,25 @@ function isObjectLike(value) {
 
 /**
  * Runs is array containing.
- * @param {?} value - Value.
+ * @param {ReturnType<typeof JSON.parse>} value - Value.
  * @returns {boolean} - Whether arrayContaining matcher.
  */
 function isArrayContaining(value) {
-  return !!value && typeof value === "object" && (/** @type {?} */ (value)).__velociousMatcher === "arrayContaining"
+  return !!value && typeof value === "object" && (/** @type {ReturnType<typeof JSON.parse>} */ (value)).__velociousMatcher === "arrayContaining"
 }
 
 /**
  * Runs is object containing.
- * @param {?} value - Value.
+ * @param {ReturnType<typeof JSON.parse>} value - Value.
  * @returns {boolean} - Whether objectContaining matcher.
  */
 function isObjectContaining(value) {
-  return !!value && typeof value === "object" && (/** @type {?} */ (value)).__velociousMatcher === "objectContaining"
+  return !!value && typeof value === "object" && (/** @type {ReturnType<typeof JSON.parse>} */ (value)).__velociousMatcher === "objectContaining"
 }
 
 /**
  * Runs is plain object.
- * @param {?} value - Value.
+ * @param {ReturnType<typeof JSON.parse>} value - Value.
  * @returns {boolean} - Whether plain object.
  */
 function isPlainObject(value) {
@@ -76,8 +76,8 @@ function isPlainObject(value) {
 
 /**
  * Runs values equal.
- * @param {?} actual - Actual value.
- * @param {?} expected - Expected value.
+ * @param {ReturnType<typeof JSON.parse>} actual - Actual value.
+ * @param {ReturnType<typeof JSON.parse>} expected - Expected value.
  * @returns {boolean} - Whether values are equal.
  */
 function valuesEqual(actual, expected) {
@@ -94,20 +94,20 @@ function valuesEqual(actual, expected) {
 
 /**
  * Runs collect match differences.
- * @param {?} actual - Actual value.
- * @param {?} expected - Expected value.
+ * @param {ReturnType<typeof JSON.parse>} actual - Actual value.
+ * @param {ReturnType<typeof JSON.parse>} expected - Expected value.
  * @param {string} path - Path.
- * @param {Record<string, Array<?>>} differences - Differences.
+ * @param {Record<string, Array<ReturnType<typeof JSON.parse>>>} differences - Differences.
  * @returns {void} - No return value.
  */
 function collectMatchDifferences(actual, expected, path, differences) {
   if (isObjectContaining(expected)) {
-    collectMatchDifferences(actual, /** @type {?} */ (expected).value, path, differences)
+    collectMatchDifferences(actual, /** @type {ReturnType<typeof JSON.parse>} */ (expected).value, path, differences)
     return
   }
 
   if (isArrayContaining(expected)) {
-    const {matches} = matchArrayContaining(actual, /** @type {Array<?>} */ (/** @type {?} */ (expected).value))
+    const {matches} = matchArrayContaining(actual, /** @type {Array<ReturnType<typeof JSON.parse>>} */ (/** @type {ReturnType<typeof JSON.parse>} */ (expected).value))
 
     if (!matches) {
       differences[path || "$"] = [expected, actual]
@@ -136,8 +136,8 @@ function collectMatchDifferences(actual, expected, path, differences) {
       return
     }
 
-    const expectedObject = /** @type {Record<string, ?>} */ (expected)
-    const actualObject = /** @type {Record<string, ?>} */ (actual)
+    const expectedObject = /** @type {Record<string, ReturnType<typeof JSON.parse>>} */ (expected)
+    const actualObject = /** @type {Record<string, ReturnType<typeof JSON.parse>>} */ (actual)
 
     for (const key of Object.keys(expectedObject)) {
       const nextPath = path ? `${path}.${key}` : key
@@ -160,14 +160,14 @@ function collectMatchDifferences(actual, expected, path, differences) {
 
 /**
  * Runs match object.
- * @param {?} actual - Actual value.
- * @param {Record<string, ?> | Array<?>} expected - Expected value.
- * @returns {{matches: boolean, differences: Record<string, Array<?>>}} - Match result.
+ * @param {ReturnType<typeof JSON.parse>} actual - Actual value.
+ * @param {Record<string, ReturnType<typeof JSON.parse>> | Array<ReturnType<typeof JSON.parse>>} expected - Expected value.
+ * @returns {{matches: boolean, differences: Record<string, Array<ReturnType<typeof JSON.parse>>>}} - Match result.
  */
 function matchObject(actual, expected) {
   /**
    * Differences.
-   * @type {Record<string, Array<?>>} */
+   * @type {Record<string, Array<ReturnType<typeof JSON.parse>>>} */
   const differences = {}
 
   collectMatchDifferences(actual, expected, "", differences)
@@ -180,14 +180,14 @@ function matchObject(actual, expected) {
 
 /**
  * Runs match array containing.
- * @param {?} actual - Actual value.
- * @param {Array<?>} expected - Expected values.
- * @returns {{matches: boolean, differences: Record<string, Array<?>>}} - Match result.
+ * @param {ReturnType<typeof JSON.parse>} actual - Actual value.
+ * @param {Array<ReturnType<typeof JSON.parse>>} expected - Expected values.
+ * @returns {{matches: boolean, differences: Record<string, Array<ReturnType<typeof JSON.parse>>>}} - Match result.
  */
 function matchArrayContaining(actual, expected) {
   /**
    * Differences.
-   * @type {Record<string, Array<?>>} */
+   * @type {Record<string, Array<ReturnType<typeof JSON.parse>>>} */
   const differences = {}
 
   if (!Array.isArray(actual)) {
@@ -204,7 +204,7 @@ function matchArrayContaining(actual, expected) {
       if (usedIndexes.has(i)) continue
 
       if (isObjectContaining(expectedItem)) {
-        const {matches} = matchObject(actual[i], /** @type {?} */ (expectedItem).value)
+        const {matches} = matchObject(actual[i], /** @type {ReturnType<typeof JSON.parse>} */ (expectedItem).value)
         if (matches) {
           matchedIndex = i
           break
@@ -213,7 +213,7 @@ function matchArrayContaining(actual, expected) {
       }
 
       if (isArrayContaining(expectedItem)) {
-        const {matches} = matchArrayContaining(actual[i], /** @type {?} */ (expectedItem).value)
+        const {matches} = matchArrayContaining(actual[i], /** @type {ReturnType<typeof JSON.parse>} */ (expectedItem).value)
         if (matches) {
           matchedIndex = i
           break