velocious 1.0.577 → 1.0.579

package/src/testing/test.js

@@ -149,9 +149,9 @@ function configureTests({consoleOutput, excludeTags, defaultTimeoutSeconds, fail
 
 /**
  * Runs merge test args.
- * @param {Record<string, ?>} baseArgs - Base args.
- * @param {Record<string, ?>} extraArgs - Extra args.
- * @returns {Record<string, ?>} - Merged args.
+ * @param {Record<string, ReturnType<typeof JSON.parse>>} baseArgs - Base args.
+ * @param {Record<string, ReturnType<typeof JSON.parse>>} extraArgs - Extra args.
+ * @returns {Record<string, ReturnType<typeof JSON.parse>>} - Merged args.
  */
 function mergeTestArgs(baseArgs, extraArgs) {
   const merged = Object.assign({}, baseArgs, extraArgs)
@@ -220,7 +220,7 @@ function afterAll(callback) {
 async function describe(description, arg1, arg2) {
   /**
    * Defines testArgs.
-   * @type {Record<string, ?>} */
+   * @type {Record<string, ReturnType<typeof JSON.parse>>} */
   let testArgs, testFunction
 
   if (typeof arg2 == "function") {
@@ -265,7 +265,7 @@ async function describe(description, arg1, arg2) {
 
 /**
  * Runs expect.
- * @param {?} arg - Arg.
+ * @param {ReturnType<typeof JSON.parse>} arg - Arg.
  * @returns {Expect} - The expect.
  */
 function expect(arg) {
@@ -286,7 +286,7 @@ function it(description, arg1, arg2) {
   const currentTest = currentPath[currentPath.length - 1]
   /**
    * Defines testArgs.
-   * @type {Record<string, ?>} */
+   * @type {Record<string, ReturnType<typeof JSON.parse>>} */
   let testArgs
 
   /**
@@ -326,7 +326,7 @@ function it(description, arg1, arg2) {
 function fit(description, arg1, arg2) {
   /**
    * Defines testArgs.
-   * @type {Record<string, ?>} */
+   * @type {Record<string, ReturnType<typeof JSON.parse>>} */
   let testArgs
 
   /**
@@ -348,15 +348,17 @@ function fit(description, arg1, arg2) {
 }
 
 // Make the methods global so they can be used in test files
-globalThis.afterEach = afterEach
-globalThis.afterAll = afterAll
-globalThis.beforeEach = beforeEach
-globalThis.beforeAll = beforeAll
-globalThis.describe = describe
-globalThis.expect = expect
-globalThis.it = it
-globalThis.fit = fit
-globalThis.testEvents = testEvents
-globalThis.configureTests = configureTests
+Object.assign(globalThis, {
+  afterAll,
+  afterEach,
+  beforeAll,
+  beforeEach,
+  configureTests,
+  describe,
+  expect,
+  fit,
+  it,
+  testEvents
+})
 
 export {afterAll, afterEach, beforeAll, beforeEach, configureTests, describe, expect, fit, it, arrayContaining, objectContaining, testConfig, testEvents, tests, waitForEvent}

package/src/testing/wait-for-event.js

@@ -3,13 +3,13 @@
 /**
  * @typedef {object} WaitForEventOptions
  * @property {number} [timeoutMs] Timeout in milliseconds (default: 5000).
- * @property {(...args: Array<?>) => boolean} [filter] Only resolve when this predicate returns true for the emitted arguments.
+ * @property {(...args: Array<ReturnType<typeof JSON.parse>>) => boolean} [filter] Only resolve when this predicate returns true for the emitted arguments.
  */
 
 /**
  * @typedef {object} EventEmitterLike
- * @property {(event: string, listener: (...args: Array<?>) => void) => void} on Registers a listener.
- * @property {(event: string, listener: (...args: Array<?>) => void) => void} off Removes a listener.
+ * @property {(event: string, listener: (...args: Array<ReturnType<typeof JSON.parse>>) => void) => void} on Registers a listener.
+ * @property {(event: string, listener: (...args: Array<ReturnType<typeof JSON.parse>>) => void) => void} off Removes a listener.
  */
 
 /**
@@ -24,7 +24,7 @@
  * @param {EventEmitterLike} emitter - Event emitter exposing `on`/`off` (Node EventEmitter, eventemitter3, velocious `testEvents`, ...).
  * @param {string} eventName - The event to wait for.
  * @param {WaitForEventOptions} [options] - Options.
- * @returns {Promise<?>} - Resolves with the single emitted argument, an array when the event emits multiple, or undefined when it emits none.
+ * @returns {Promise<ReturnType<typeof JSON.parse>>} - Resolves with the single emitted argument, an array when the event emits multiple, or undefined when it emits none.
  */
 export default function waitForEvent(emitter, eventName, options = {}) {
   const {timeoutMs = 5000, filter} = options
@@ -37,7 +37,7 @@ export default function waitForEvent(emitter, eventName, options = {}) {
      * Resolves the wait when a matching event fires, removing itself first. A filter
      * that throws (e.g. it assumes an event shape an intermediate emission doesn't
      * have) rejects immediately rather than leaving the waiter pending until timeout.
-     * @param {...?} args - Emitted arguments.
+     * @param {...ReturnType<typeof JSON.parse>} args - Emitted arguments.
      * @returns {void}
      */
     const listener = (...args) => {

package/src/utils/event-emitter.js

@@ -3,6 +3,6 @@
 import EventEmitterDefault from "eventemitter3"
 
 /** @type {typeof import("eventemitter3").EventEmitter} */
-const EventEmitter = /** @type {?} */ (EventEmitterDefault)
+const EventEmitter = /** @type {ReturnType<typeof JSON.parse>} */ (EventEmitterDefault)
 
 export default EventEmitter

package/src/utils/format-value.js

@@ -4,7 +4,7 @@ const MAX_STRINGIFY_DEPTH = 5
 
 /**
  * Runs is plain object.
- * @param {?} value - Value to use.
+ * @param {ReturnType<typeof JSON.parse>} value - Value to use.
  * @returns {boolean} - Whether plain object.
  */
 function isPlainObject(value) {
@@ -17,7 +17,7 @@ function isPlainObject(value) {
 
 /**
  * Minified stringify with circular and depth protection.
- * @param {?} value - Value to use.
+ * @param {ReturnType<typeof JSON.parse>} value - Value to use.
  * @returns {string} - The minified stringify.
  */
 function minifiedStringify(value) {
@@ -25,9 +25,9 @@ function minifiedStringify(value) {
 
   /**
    * Runs serialize.
-   * @param {?} current - Current.
+   * @param {ReturnType<typeof JSON.parse>} current - Current.
    * @param {number} depth - Depth.
-   * @returns {?} - The serialize.
+   * @returns {ReturnType<typeof JSON.parse>} - The serialize.
    */
   function serialize(current, depth) {
     if (depth > MAX_STRINGIFY_DEPTH) return "[MaxDepth]"
@@ -51,7 +51,7 @@ function minifiedStringify(value) {
 
     /**
      * Output.
-     * @type {Record<string, ?>} */
+     * @type {Record<string, ReturnType<typeof JSON.parse>>} */
     const output = {}
 
     for (const key of Object.keys(current)) {
@@ -70,7 +70,7 @@ function minifiedStringify(value) {
 
 /**
  * Runs format value.
- * @param {?} value - Value to use.
+ * @param {ReturnType<typeof JSON.parse>} value - Value to use.
  * @returns {string} - The value.
  */
 function formatValue(value) {

package/src/utils/is-date.js

@@ -5,7 +5,7 @@
  * console REPL context or a node:vm context), where `instanceof Date` is false because the other
  * realm has its own Date constructor. Without this, such a Date bypasses date normalization and SQL
  * value conversion and ends up as an empty value in the generated SQL.
- * @param {?} value - Value to test.
+ * @param {ReturnType<typeof JSON.parse>} value - Value to test.
  * @returns {value is Date} - Whether the value is a Date from any realm.
  */
 export default function isDate(value) {

package/src/utils/model-scope.js

@@ -2,9 +2,9 @@
  * ModelScopeDescriptor type.
  * @typedef {object} ModelScopeDescriptor
  * @property {true} [velociousModelScopeDescriptor] - Internal marker.
- * @property {(...args: Array<?>) => ?} callback - Scope callback.
+ * @property {(...args: Array<ReturnType<typeof JSON.parse>>) => ReturnType<typeof JSON.parse>} callback - Scope callback.
  * @property {typeof import("../database/record/index.js").default | import("../frontend-models/base.js").FrontendModelClass} modelClass - Owning model class.
- * @property {Array<?>} scopeArgs - Scope arguments.
+ * @property {Array<ReturnType<typeof JSON.parse>>} scopeArgs - Scope arguments.
  */
 // @ts-check
 
@@ -13,16 +13,16 @@ const MODEL_SCOPE_DESCRIPTOR_MARKER = "velociousModelScopeDescriptor"
 /**
  * Runs the defineModelScope helper.
  * @param {object} args - Definition arguments.
- * @param {(...args: Array<?>) => ?} args.callback - Scope callback.
+ * @param {(...args: Array<ReturnType<typeof JSON.parse>>) => ReturnType<typeof JSON.parse>} args.callback - Scope callback.
  * @param {typeof import("../database/record/index.js").default | import("../frontend-models/base.js").FrontendModelClass} args.modelClass - Owning model class.
- * @param {() => ?} args.startQuery - Factory that returns a fresh query for the owning model class.
- * @returns {((...args: Array<?>) => ?) & {scope: (...args: Array<?>) => ModelScopeDescriptor}} - Scope helper.
+ * @param {() => ReturnType<typeof JSON.parse>} args.startQuery - Factory that returns a fresh query for the owning model class.
+ * @returns {((...args: Array<ReturnType<typeof JSON.parse>>) => ReturnType<typeof JSON.parse>) & {scope: (...args: Array<ReturnType<typeof JSON.parse>>) => ModelScopeDescriptor}} - Scope helper.
  */
 export function defineModelScope({callback, modelClass, startQuery}) {
   /**
    * Runs defined scope.
-   * @param {...?} scopeArgs - Scope arguments.
-   * @returns {?} - Scoped root query.
+   * @param {...ReturnType<typeof JSON.parse>} scopeArgs - Scope arguments.
+   * @returns {ReturnType<typeof JSON.parse>} - Scoped root query.
    */
   function definedScope(...scopeArgs) {
     return startQuery().scope(definedScope.scope(...scopeArgs))
@@ -30,7 +30,7 @@ export function defineModelScope({callback, modelClass, startQuery}) {
 
   /**
    * Builds a reusable scope descriptor.
-   * @param {...?} scopeArgs - Scope arguments.
+   * @param {...ReturnType<typeof JSON.parse>} scopeArgs - Scope arguments.
    * @returns {ModelScopeDescriptor} - Reusable scope descriptor.
    */
   definedScope.scope = (...scopeArgs) => ({
@@ -45,9 +45,9 @@ export function defineModelScope({callback, modelClass, startQuery}) {
 
 /**
  * Runs the isModelScopeDescriptor helper.
- * @param {?} value - Candidate descriptor.
+ * @param {ReturnType<typeof JSON.parse>} value - Candidate descriptor.
  * @returns {value is ModelScopeDescriptor} - Whether the value is a scope descriptor.
  */
 export function isModelScopeDescriptor(value) {
-  return Boolean(value && typeof value === "object" && /** @type {Record<string, ?>} */ (value)[MODEL_SCOPE_DESCRIPTOR_MARKER] === true)
+  return Boolean(value && typeof value === "object" && /** @type {Record<string, ReturnType<typeof JSON.parse>>} */ (value)[MODEL_SCOPE_DESCRIPTOR_MARKER] === true)
 }

package/src/utils/plain-object.js

@@ -2,8 +2,8 @@
 
 /**
  * Detect plain object literals without accepting arrays or class instances.
- * @param {?} value - Candidate value.
- * @returns {value is Record<string, ?>} - Whether value is a plain object.
+ * @param {ReturnType<typeof JSON.parse>} value - Candidate value.
+ * @returns {value is Record<string, ReturnType<typeof JSON.parse>>} - Whether value is a plain object.
  */
 export default function isPlainObject(value) {
   if (Object.prototype.toString.call(value) !== "[object Object]") return false

package/src/utils/ransack.js

@@ -28,7 +28,7 @@ import {resolveFrontendModelClass} from "../frontend-models/model-registry.js"
  * @property {RansackAttribute[]} attributes - Resolved attributes to test.
  * @property {RansackCombinator} combinator - How multiple attributes are combined.
  * @property {RansackPredicate} predicate - Parsed Ransack predicate.
- * @property {?} value - Normalized value.
+ * @property {ReturnType<typeof JSON.parse>} value - Normalized value.
  */
 /**
  * RansackGroup type.
@@ -83,7 +83,7 @@ const supportedPredicates = [
 /**
  * Runs the normalizeRansackParams helper.
  * @param {RansackModelClass} modelClass - Model class.
- * @param {Record<string, ?>} params - Ransack-style params hash.
+ * @param {Record<string, ReturnType<typeof JSON.parse>>} params - Ransack-style params hash.
  * @returns {RansackCondition[]} - Normalized conditions.
  */
 export function normalizeRansackParams(modelClass, params) {
@@ -93,7 +93,7 @@ export function normalizeRansackParams(modelClass, params) {
 /**
  * Runs the normalizeRansackGroup helper.
  * @param {RansackModelClass} modelClass - Model class.
- * @param {Record<string, ?>} params - Ransack-style params hash.
+ * @param {Record<string, ReturnType<typeof JSON.parse>>} params - Ransack-style params hash.
  * @returns {RansackGroup} - Normalized group.
  */
 export function normalizeRansackGroup(modelClass, params) {
@@ -139,7 +139,7 @@ const SKIP_RANSACK_CONDITION = Symbol("skip-ransack-condition")
  * @param {object} args - Options.
  * @param {string} args.key - Simple Ransack key.
  * @param {RansackModelClass} args.modelClass - Model class.
- * @param {?} args.rawValue - Raw condition value.
+ * @param {ReturnType<typeof JSON.parse>} args.rawValue - Raw condition value.
  * @returns {RansackCondition | null} - Normalized condition, or null when skipped.
  */
 function normalizeSimpleRansackCondition({key, modelClass, rawValue}) {
@@ -170,7 +170,7 @@ function normalizeSimpleRansackCondition({key, modelClass, rawValue}) {
  * Runs normalize advanced ransack conditions.
  * @param {object} args - Options.
  * @param {RansackModelClass} args.modelClass - Model class.
- * @param {?} args.value - Advanced conditions collection.
+ * @param {ReturnType<typeof JSON.parse>} args.value - Advanced conditions collection.
  * @returns {RansackCondition[]} - Normalized conditions.
  */
 function normalizeAdvancedRansackConditions({modelClass, value}) {
@@ -217,7 +217,7 @@ function normalizeAdvancedRansackConditions({modelClass, value}) {
  * Runs normalize advanced ransack groups.
  * @param {object} args - Options.
  * @param {RansackModelClass} args.modelClass - Model class.
- * @param {?} args.value - Advanced groups collection.
+ * @param {ReturnType<typeof JSON.parse>} args.value - Advanced groups collection.
  * @returns {RansackGroup[]} - Normalized groups.
  */
 function normalizeAdvancedRansackGroups({modelClass, value}) {
@@ -239,7 +239,7 @@ function normalizeAdvancedRansackGroups({modelClass, value}) {
 
 /**
  * Runs normalize ransack combinator.
- * @param {?} value - Candidate combinator.
+ * @param {ReturnType<typeof JSON.parse>} value - Candidate combinator.
  * @param {RansackCombinator} defaultValue - Default combinator.
  * @returns {RansackCombinator} - Normalized combinator.
  */
@@ -252,9 +252,9 @@ function normalizeRansackCombinator(value, defaultValue) {
 
 /**
  * Runs normalize ransack collection.
- * @param {?} value - Candidate collection.
+ * @param {ReturnType<typeof JSON.parse>} value - Candidate collection.
  * @param {string} name - Collection name for errors.
- * @returns {Array<?>} - Collection values in stable order.
+ * @returns {Array<ReturnType<typeof JSON.parse>>} - Collection values in stable order.
  */
 function normalizeRansackCollection(value, name) {
   if (value === undefined || value === null || value === "") return []
@@ -282,8 +282,8 @@ function normalizeRansackCollection(value, name) {
  * Runs advanced ransack condition value.
  * @param {object} args - Options.
  * @param {RansackPredicate} args.predicate - Parsed predicate.
- * @param {?} args.value - Advanced condition value.
- * @returns {?} - Value passed to predicate normalization.
+ * @param {ReturnType<typeof JSON.parse>} args.value - Advanced condition value.
+ * @returns {ReturnType<typeof JSON.parse>} - Value passed to predicate normalization.
  */
 function advancedRansackConditionValue({predicate, value}) {
   if (predicate === "in" || predicate === "not_in") return value
@@ -299,7 +299,7 @@ function advancedRansackConditionValue({predicate, value}) {
  * Runs resolve ransack attributes from advanced value.
  * @param {object} args - Options.
  * @param {RansackModelClass} args.modelClass - Model class.
- * @param {?} args.value - Advanced attribute value.
+ * @param {ReturnType<typeof JSON.parse>} args.value - Advanced attribute value.
  * @returns {RansackAttribute[]} - Resolved attributes.
  */
 function resolveRansackAttributesFromAdvancedValue({modelClass, value}) {
@@ -322,7 +322,7 @@ function resolveRansackAttributesFromAdvancedValue({modelClass, value}) {
 
 /**
  * Runs normalize advanced attribute values.
- * @param {?} value - Advanced attribute value.
+ * @param {ReturnType<typeof JSON.parse>} value - Advanced attribute value.
  * @returns {string[]} - Attribute path strings.
  */
 function normalizeAdvancedAttributeValues(value) {
@@ -341,7 +341,7 @@ function normalizeAdvancedAttributeValues(value) {
 
 /**
  * Runs normalize advanced attribute value.
- * @param {?} value - Advanced attribute entry.
+ * @param {ReturnType<typeof JSON.parse>} value - Advanced attribute entry.
  * @returns {string} - Attribute path string.
  */
 function normalizeAdvancedAttributeValue(value) {
@@ -543,12 +543,12 @@ function resolveAttributeName({modelClass, value}) {
  * @returns {Record<string, {targetModelClass: RansackModelClass}>} - Relationship entries keyed by name.
  */
 function relationshipEntries(modelClass) {
-  if (typeof /** @type {?} */ (modelClass).getRelationshipsMap === "function") {
+  if (typeof /** @type {ReturnType<typeof JSON.parse>} */ (modelClass).getRelationshipsMap === "function") {
     return backendRelationshipEntries(modelClass)
   }
 
-  if (typeof /** @type {?} */ (modelClass).relationshipDefinitions === "function" &&
-    typeof /** @type {?} */ (modelClass).relationshipModelClasses === "function") {
+  if (typeof /** @type {ReturnType<typeof JSON.parse>} */ (modelClass).relationshipDefinitions === "function" &&
+    typeof /** @type {ReturnType<typeof JSON.parse>} */ (modelClass).relationshipModelClasses === "function") {
     return frontendRelationshipEntries(modelClass)
   }
 
@@ -565,7 +565,7 @@ function backendRelationshipEntries(modelClass) {
    * Entries.
    * @type {Record<string, {targetModelClass: RansackModelClass}>} */
   const entries = {}
-  const relationshipsMap = /** @type {?} */ (modelClass).getRelationshipsMap()
+  const relationshipsMap = /** @type {ReturnType<typeof JSON.parse>} */ (modelClass).getRelationshipsMap()
 
   for (const relationshipName of Object.keys(relationshipsMap)) {
     const relationship = relationshipsMap[relationshipName]
@@ -592,8 +592,8 @@ function frontendRelationshipEntries(modelClass) {
    * Entries.
    * @type {Record<string, {targetModelClass: RansackModelClass}>} */
   const entries = {}
-  const definitions = /** @type {?} */ (modelClass).relationshipDefinitions()
-  const relationshipModelClasses = /** @type {?} */ (modelClass).relationshipModelClasses()
+  const definitions = /** @type {ReturnType<typeof JSON.parse>} */ (modelClass).relationshipDefinitions()
+  const relationshipModelClasses = /** @type {ReturnType<typeof JSON.parse>} */ (modelClass).relationshipModelClasses()
 
   for (const relationshipName of Object.keys(definitions)) {
     const targetModelClass = resolveFrontendModelClass(relationshipModelClasses[relationshipName])
@@ -612,12 +612,12 @@ function frontendRelationshipEntries(modelClass) {
  * @returns {Record<string, string>} - Attribute-to-column entries keyed by attribute name.
  */
 function attributeEntries(modelClass) {
-  if (typeof /** @type {?} */ (modelClass).getAttributeNameToColumnNameMap === "function") {
-    return /** @type {Record<string, string>} */ ((/** @type {?} */ (modelClass).getAttributeNameToColumnNameMap()))
+  if (typeof /** @type {ReturnType<typeof JSON.parse>} */ (modelClass).getAttributeNameToColumnNameMap === "function") {
+    return /** @type {Record<string, string>} */ ((/** @type {ReturnType<typeof JSON.parse>} */ (modelClass).getAttributeNameToColumnNameMap()))
   }
 
-  const resourceConfig = typeof /** @type {?} */ (modelClass).resourceConfig === "function"
-    ? /** @type {?} */ (modelClass).resourceConfig()
+  const resourceConfig = typeof /** @type {ReturnType<typeof JSON.parse>} */ (modelClass).resourceConfig === "function"
+    ? /** @type {ReturnType<typeof JSON.parse>} */ (modelClass).resourceConfig()
     : {}
   const attributes = resourceConfig.attributes
   /**
@@ -714,8 +714,8 @@ function snakeToCamelSuffix(value) {
  * Runs normalize ransack value.
  * @param {object} args - Options.
  * @param {RansackPredicate} args.predicate - Parsed predicate.
- * @param {?} args.value - Raw value.
- * @returns {?} - Normalized value.
+ * @param {ReturnType<typeof JSON.parse>} args.value - Raw value.
+ * @returns {ReturnType<typeof JSON.parse>} - Normalized value.
  */
 function normalizeRansackValue({predicate, value}) {
   if (predicate === "null") {
@@ -733,7 +733,7 @@ function normalizeRansackValue({predicate, value}) {
 
 /**
  * Runs normalize ransack null value.
- * @param {?} value - Candidate null predicate value.
+ * @param {ReturnType<typeof JSON.parse>} value - Candidate null predicate value.
  * @returns {boolean | typeof SKIP_RANSACK_CONDITION} - Normalized value.
  */
 function normalizeRansackNullValue(value) {
@@ -744,8 +744,8 @@ function normalizeRansackNullValue(value) {
 
 /**
  * Runs normalize ransack list value.
- * @param {?} value - Candidate list predicate value.
- * @returns {Array<?> | typeof SKIP_RANSACK_CONDITION} - Normalized value.
+ * @param {ReturnType<typeof JSON.parse>} value - Candidate list predicate value.
+ * @returns {Array<ReturnType<typeof JSON.parse>> | typeof SKIP_RANSACK_CONDITION} - Normalized value.
  */
 function normalizeRansackListValue(value) {
   const normalizedArray = normalizeRansackArray(value)
@@ -755,16 +755,16 @@ function normalizeRansackListValue(value) {
 
 /**
  * Ransack true values.
- * @type {Set<?>} */
+ * @type {Set<ReturnType<typeof JSON.parse>>} */
 const ransackTrueValues = new Set([true, 1, "1", "true"])
 /**
  * Ransack false values.
- * @type {Set<?>} */
+ * @type {Set<ReturnType<typeof JSON.parse>>} */
 const ransackFalseValues = new Set([false, 0, "0", "false"])
 
 /**
  * Runs normalize ransack boolean.
- * @param {?} value - Candidate boolean.
+ * @param {ReturnType<typeof JSON.parse>} value - Candidate boolean.
  * @returns {boolean | null} - Normalized boolean or null when blank.
  */
 function normalizeRansackBoolean(value) {
@@ -777,7 +777,7 @@ function normalizeRansackBoolean(value) {
 
 /**
  * Runs ransack value is blank.
- * @param {?} value - Candidate value.
+ * @param {ReturnType<typeof JSON.parse>} value - Candidate value.
  * @returns {boolean} - Whether value should be ignored as blank.
  */
 function ransackValueIsBlank(value) {
@@ -786,8 +786,8 @@ function ransackValueIsBlank(value) {
 
 /**
  * Runs normalize ransack array.
- * @param {?} value - Candidate array-ish value.
- * @returns {Array<?>} - Normalized array values.
+ * @param {ReturnType<typeof JSON.parse>} value - Candidate array-ish value.
+ * @returns {Array<ReturnType<typeof JSON.parse>>} - Normalized array values.
  */
 function normalizeRansackArray(value) {
   if (Array.isArray(value)) {

package/src/utils/with-tracked-stack-async-hooks.js

@@ -9,8 +9,8 @@ let asyncLocalStorage
 
 /**
  * Tracked stack global.
- * @type {{withTrackedStack?: {addTrackedStackToError: (error: Error) => void, withTrackedStack: (arg1: string | (() => Promise<?>), arg2?: (() => Promise<?>) | Error) => Promise<?>}}} */
-const trackedStackGlobal = /** @type {?} */ (globalThis)
+ * @type {{withTrackedStack?: {addTrackedStackToError: (error: Error) => void, withTrackedStack: (arg1: string | (() => Promise<ReturnType<typeof JSON.parse>>), arg2?: (() => Promise<ReturnType<typeof JSON.parse>>) | Error) => Promise<ReturnType<typeof JSON.parse>>}}} */
+const trackedStackGlobal = /** @type {ReturnType<typeof JSON.parse>} */ (globalThis)
 
 if (AsyncLocalStorage) {
   asyncLocalStorage = new AsyncLocalStorage()
@@ -39,14 +39,14 @@ function addTrackedStackToError(error) {
 
 /**
  * Runs with tracked stack.
- * @param {(() => Promise<?>) | string} arg1 - Arg1.
- * @param {(() => Promise<?>) | Error} [arg2] - Arg2.
- * @returns {Promise<?>} - Resolves with the callback result.
+ * @param {(() => Promise<ReturnType<typeof JSON.parse>>) | string} arg1 - Arg1.
+ * @param {(() => Promise<ReturnType<typeof JSON.parse>>) | Error} [arg2] - Arg2.
+ * @returns {Promise<ReturnType<typeof JSON.parse>>} - Resolves with the callback result.
  */
 async function withTrackedStack(arg1, arg2) {
   /**
    * Defines callback.
-   * @type {() => Promise<?>} */
+   * @type {() => Promise<ReturnType<typeof JSON.parse>>} */
   let callback
 
   /**
@@ -55,10 +55,10 @@ async function withTrackedStack(arg1, arg2) {
   let stack
 
   if (typeof arg2 == "function" && typeof arg1 == "string") {
-    callback = /** @type {() => Promise<?>} */ (arg2)
+    callback = /** @type {() => Promise<ReturnType<typeof JSON.parse>>} */ (arg2)
     stack = arg1
   } else {
-    callback = /** @type {() => Promise<?>} */ (arg1)
+    callback = /** @type {() => Promise<ReturnType<typeof JSON.parse>>} */ (arg1)
     stack = Error().stack || ""
   }
 

package/src/utils/with-tracked-stack.js

@@ -2,8 +2,8 @@
 
 /**
  * Tracked stack global.
- * @type {{withTrackedStack?: {withTrackedStack?: (stack: string | undefined, fn: () => Promise<?>) => Promise<?>, addTrackedStackToError?: (error: Error) => void}}} */
-const trackedStackGlobal = /** @type {?} */ (globalThis)
+ * @type {{withTrackedStack?: {withTrackedStack?: (stack: string | undefined, fn: () => Promise<ReturnType<typeof JSON.parse>>) => Promise<ReturnType<typeof JSON.parse>>, addTrackedStackToError?: (error: Error) => void}}} */
+const trackedStackGlobal = /** @type {ReturnType<typeof JSON.parse>} */ (globalThis)
 
 /**
  * Runs add tracked stack to error.
@@ -15,13 +15,13 @@ function addTrackedStackToError(error) {
 
 /**
  * Runs with tracked stack.
- * @param {string | (() => Promise<?>)} stackOrCallback - Stack string or callback.
- * @param {(() => Promise<?>)} [callback] - Callback to execute.
- * @returns {Promise<?>} - Resolves with value.
+ * @param {string | (() => Promise<ReturnType<typeof JSON.parse>>)} stackOrCallback - Stack string or callback.
+ * @param {(() => Promise<ReturnType<typeof JSON.parse>>)} [callback] - Callback to execute.
+ * @returns {Promise<ReturnType<typeof JSON.parse>>} - Resolves with value.
  */
 async function withTrackedStack(stackOrCallback, callback) {
   const tracked = trackedStackGlobal.withTrackedStack?.withTrackedStack
-  const resolvedCallback = callback ?? /** @type {() => Promise<?>} */ (stackOrCallback)
+  const resolvedCallback = callback ?? /** @type {() => Promise<ReturnType<typeof JSON.parse>>} */ (stackOrCallback)
   const stack = typeof stackOrCallback == "string" ? stackOrCallback : undefined
 
   if (tracked) {

package/src/velocious-error.js

@@ -6,17 +6,21 @@ export default class VelociousError extends Error {
    * Runs constructor.
    * @param {string} message - Error message.
    * @param {object} [args] - Options.
-   * @param {?} [args.cause] - Error cause.
+   * @param {ReturnType<typeof JSON.parse>} [args.cause] - Error cause.
    * @param {string} [args.code] - Optional error code.
+   * @param {import("./configuration-types.js").ClientErrorPayloadReporterPayload} [args.details] - Structured client-safe error details.
+   * @param {"application_error" | "authorization_error" | "record_not_found" | "validation_error"} [args.errorType] - Stable client-facing error category.
    * @param {boolean} [args.safeToExpose] - Whether the message is safe to return to clients.
    */
   constructor(message, args = {}) {
-    const {cause, code, safeToExpose = false} = args
+    const {cause, code, details, errorType, safeToExpose = false} = args
 
     super(message, {cause})
 
     this.name = "VelociousError"
     this.code = code
+    this.details = details
+    this.errorType = errorType
     this.safeToExpose = safeToExpose
   }
 
@@ -24,8 +28,10 @@ export default class VelociousError extends Error {
    * Runs safe.
    * @param {string} message - Error message.
    * @param {object} [args] - Options.
-   * @param {?} [args.cause] - Error cause.
+   * @param {ReturnType<typeof JSON.parse>} [args.cause] - Error cause.
    * @param {string} [args.code] - Optional error code.
+   * @param {import("./configuration-types.js").ClientErrorPayloadReporterPayload} [args.details] - Structured client-safe error details.
+   * @param {"application_error" | "authorization_error" | "record_not_found" | "validation_error"} [args.errorType] - Stable client-facing error category.
    * @returns {VelociousError} - Client-safe error instance.
    */
   static safe(message, args = {}) {