velocious 1.0.562 → 1.0.564

package/src/sync/sync-envelope-replay-service.js

@@ -7,6 +7,23 @@ import SyncReplayUpsertApplier from "./sync-replay-upsert-applier.js"
 import {ValidationError} from "../database/record/index.js"
 import VelociousError from "../velocious-error.js"
 
+/**
+ * Resolved routed-resource registration for one replay resource type.
+ * @typedef {object} SyncReplayResourceRegistration
+ * @property {string} modelName - Effective frontend model name.
+ * @property {import("../configuration-types.js").FrontendModelResourceClassType} resourceClass - Routed resource class.
+ * @property {import("../configuration-types.js").NormalizedFrontendModelResourceConfiguration | null} resourceConfiguration - Normalized resource configuration when registry-resolved.
+ */
+/**
+ * @typedef {object} SyncReplayMutation
+ * @property {Date} clientUpdatedAt - Client-side mutation timestamp.
+ * @property {Record<string, ?>} data - Parsed mutation payload.
+ * @property {?} id - Client sync row id for per-sync responses.
+ * @property {string} resourceId - Resource id as a string.
+ * @property {string} resourceType - Resource/model name.
+ * @property {string} serializedData - JSON serialized mutation payload.
+ * @property {string} syncType - Sync operation type.
+ */
 /**
  * One declarative broadcast fanned out after a mutation applies.
  * @typedef {object} SyncReplayBroadcast
@@ -778,22 +795,3 @@ export default class SyncEnvelopeReplayService {
     await deliverDeclaredBroadcasts({args, broadcaster: this.broadcaster, broadcasts: this.broadcasts})
   }
 }
-
-/**
- * Resolved routed-resource registration for one replay resource type.
- * @typedef {object} SyncReplayResourceRegistration
- * @property {string} modelName - Effective frontend model name.
- * @property {import("../configuration-types.js").FrontendModelResourceClassType} resourceClass - Routed resource class.
- * @property {import("../configuration-types.js").NormalizedFrontendModelResourceConfiguration | null} resourceConfiguration - Normalized resource configuration when registry-resolved.
- */
-
-/**
- * @typedef {object} SyncReplayMutation
- * @property {Date} clientUpdatedAt - Client-side mutation timestamp.
- * @property {Record<string, ?>} data - Parsed mutation payload.
- * @property {?} id - Client sync row id for per-sync responses.
- * @property {string} resourceId - Resource id as a string.
- * @property {string} resourceType - Resource/model name.
- * @property {string} serializedData - JSON serialized mutation payload.
- * @property {string} syncType - Sync operation type.
- */

package/src/sync/sync-resource-base.js

@@ -7,8 +7,6 @@ import SyncEnvelopeReplayService from "./sync-envelope-replay-service.js"
 import SyncModelChangeFeedService from "./sync-model-change-feed-service.js"
 import VelociousError from "../velocious-error.js"
 
-const QUICK_SEARCH_COLUMN = "quickSearch"
-
 /**
  * Optional client-declared sync scope carried on a changes request.
  * @typedef {object} SerializedChangesScope
@@ -16,6 +14,7 @@ const QUICK_SEARCH_COLUMN = "quickSearch"
  * @property {string | null} resourceType - Client resource/model name the scope was declared for, or null for the all-types (user) scope: one scope covering every resource type this resource authorizes for the caller, so a sync authorizes once however many types it serves.
  * @property {string[] | null} resourceTypes - For the all-types scope, the resource types the client can apply. A cheap delivery/type filter only - it narrows, never widens, what the app's authorization already allows. Null for a type-declared scope.
  */
+const QUICK_SEARCH_COLUMN = "quickSearch"
 
 /**
  * Base resource for Velocious sync endpoints.

package/src/sync/sync-scope-store.js

@@ -6,6 +6,15 @@ import UUID from "pure-uuid"
 import {scopeKey} from "./query-scope.js"
 import stableJsonStringify from "./stable-json.js"
 
+/**
+ * @typedef {object} SyncScopeRow
+ * @property {Record<string, ?>} conditions - Scope attribute conditions.
+ * @property {string | null} cursorPayload - Persisted cursor JSON payload.
+ * @property {string} id - Scope row id.
+ * @property {string | null} resourceType - Scope resource/model name, or null for the all-types (user) scope.
+ * @property {string} scopeDigest - Fixed-size deterministic digest of the canonical scope key.
+ * @property {string} state - Scope state ("active" or "removed").
+ */
 const TABLE_NAME = "velocious_sync_scopes"
 const SCOPE_DIGEST_PREFIX = "velocious-sync-scope:"
 
@@ -19,16 +28,6 @@ function scopeDigestForScope(scope) {
   return new UUID(5, "ns:URL", `${SCOPE_DIGEST_PREFIX}${scopeKey(scope)}`).format()
 }
 
-/**
- * @typedef {object} SyncScopeRow
- * @property {Record<string, ?>} conditions - Scope attribute conditions.
- * @property {string | null} cursorPayload - Persisted cursor JSON payload.
- * @property {string} id - Scope row id.
- * @property {string | null} resourceType - Scope resource/model name, or null for the all-types (user) scope.
- * @property {string} scopeDigest - Fixed-size deterministic digest of the canonical scope key.
- * @property {string} state - Scope state ("active" or "removed").
- */
-
 /**
  * Framework-owned local persistence for declared sync scopes and their cursors.
  *

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

@@ -1,3 +1,13 @@
+/**
+ * ParseFiltersResult type.
+ * @typedef {object} ParseFiltersResult
+ * @property {string[]} includeTags - Tags to include.
+ * @property {string[]} excludeTags - Tags to exclude.
+ * @property {string[]} examplePatterns - Example name patterns.
+ * @property {string[]} filteredProcessArgs - Remaining process args with filter flags removed.
+ * @property {number | undefined} groups - Total number of groups for test splitting.
+ * @property {number | undefined} groupNumber - Which group to run (1-indexed).
+ */
 // @ts-check
 
 const INCLUDE_TAG_FLAGS = new Set(["--tag", "--include-tag", "-t"])
@@ -50,17 +60,6 @@ export function normalizeExamplePatterns(patterns) {
   return normalized
 }
 
-/**
- * ParseFiltersResult type.
- * @typedef {object} ParseFiltersResult
- * @property {string[]} includeTags - Tags to include.
- * @property {string[]} excludeTags - Tags to exclude.
- * @property {string[]} examplePatterns - Example name patterns.
- * @property {string[]} filteredProcessArgs - Remaining process args with filter flags removed.
- * @property {number | undefined} groups - Total number of groups for test splitting.
- * @property {number | undefined} groupNumber - Which group to run (1-indexed).
- */
-
 /**
  * Runs the parseFilters helper.
  * @param {string[]} processArgs - Process args.

package/src/testing/test-runner.js

@@ -13,6 +13,87 @@ import {testConfig, testEvents, tests} from "./test.js"
 import {pathToFileURL} from "url"
 import {clearDeliveries} from "../mailer.js"
 
+/**
+ * ConsoleMethodName type.
+ * @typedef {"log" | "info" | "warn" | "error" | "debug"} ConsoleMethodName */
+/**
+ * AttemptConsoleOutput type.
+ * @typedef {object} AttemptConsoleOutput
+ * @property {number} attemptNumber - Attempt number.
+ * @property {string} output - Captured console output.
+ */
+/**
+ * TestArgs type.
+ * @typedef {object} TestArgs
+ * @property {Application} [application] - Application instance for integration tests.
+ * @property {RequestClient} [client] - HTTP client for request tests.
+ * @property {object} [databaseCleaning] - Database cleanup options for tests.
+ * @property {boolean} [databaseCleaning.transaction] - Use transactions to rollback between tests.
+ * @property {boolean} [databaseCleaning.truncate] - Truncate tables between tests.
+ * @property {boolean} [databaseCleaning.truncateBefore] - Truncate tables before each test, in addition to the default cleanup.
+ * @property {boolean} [focus] - Whether this test is focused.
+ * @property {() => (void|Promise<void>)} [function] - Test callback function.
+ * @property {number} [retry] - Number of retries when a test fails.
+ * @property {string[] | string} [tags] - Tags for filtering.
+ * @property {number} [timeoutSeconds] - Timeout in seconds for the test.
+ * @property {string} [type] - Test type identifier.
+ */
+/**
+ * TestData type.
+ * @typedef {object} TestData
+ * @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.
+ */
+/**
+ * FailedTestDetail type.
+ * @typedef {object} FailedTestDetail
+ * @property {string} fullDescription - Full test description.
+ * @property {string} [filePath] - Source file path.
+ * @property {number} [line] - Source line number.
+ * @property {?} error - Failure error.
+ * @property {string} [consoleOutput] - Captured console output while test ran.
+ * @property {string} [consoleLogPath] - Saved console log path.
+ */
+/**
+ * ActiveAfterAllScopeEntry type.
+ * @typedef {object} ActiveAfterAllScopeEntry
+ * @property {TestsArgument} tests - Scope test tree.
+ * @property {boolean} afterAllsRun - Whether cleanup hooks have run.
+ */
+/**
+ * Defines this typedef.
+ * @typedef {function({configuration: import("../configuration.js").default, testArgs: TestArgs, testData: TestData}) : (void|Promise<void>)} AfterBeforeEachCallbackType
+ */
+/**
+ * AfterBeforeEachCallbackObjectType type.
+ * @typedef {object} AfterBeforeEachCallbackObjectType
+ * @property {AfterBeforeEachCallbackType} callback - Hook callback to execute.
+ */
+/**
+ * Defines this typedef.
+ * @typedef {function({configuration: import("../configuration.js").default}) : (void|Promise<void>)} BeforeAfterAllCallbackType
+ */
+/**
+ * BeforeAfterAllCallbackObjectType type.
+ * @typedef {object} BeforeAfterAllCallbackObjectType
+ * @property {BeforeAfterAllCallbackType} callback - Hook callback to execute.
+ */
+/**
+ * TestsArgument type.
+ * @typedef {object} TestsArgument
+ * @property {Record<string, TestData>} args - Arguments keyed by test description.
+ * @property {boolean} [anyTestsFocussed] - Whether any tests in the tree are focused.
+ * @property {AfterBeforeEachCallbackObjectType[]} afterEaches - After-each hooks for this scope.
+ * @property {BeforeAfterAllCallbackObjectType[]} afterAlls - After-all hooks for this scope.
+ * @property {BeforeAfterAllCallbackObjectType[]} beforeAlls - Before-all hooks for this scope.
+ * @property {AfterBeforeEachCallbackObjectType[]} beforeEaches - Before-each hooks for this scope.
+ * @property {string} [filePath] - Source file path.
+ * @property {number} [line] - Source line number.
+ * @property {Record<string, TestData>} tests - A unique identifier for the node.
+ * @property {Record<string, TestsArgument>} subs - Optional child nodes. Each item is another `Node`, allowing recursion.
+ */
 /**
  * Marks the error thrown by {@link runWithTimeout} so the caller can tell a
  * lifecycle timeout (the promise is still running detached) apart from an
@@ -85,22 +166,11 @@ function awaitSettledOrGrace(lifecycle, graceMs) {
   })
 }
 
-/**
- * ConsoleMethodName type.
- * @typedef {"log" | "info" | "warn" | "error" | "debug"} ConsoleMethodName */
-
 /**
  * Captured console methods.
  * @type {ConsoleMethodName[]} */
 const CAPTURED_CONSOLE_METHODS = ["log", "info", "warn", "error", "debug"]
 
-/**
- * AttemptConsoleOutput type.
- * @typedef {object} AttemptConsoleOutput
- * @property {number} attemptNumber - Attempt number.
- * @property {string} output - Captured console output.
- */
-
 /**
  * Runs to file slug.
  * @param {string} value - Value to sanitize.
@@ -114,87 +184,6 @@ function toFileSlug(value) {
     .slice(0, 80) || "failed-test"
 }
 
-/**
- * TestArgs type.
- * @typedef {object} TestArgs
- * @property {Application} [application] - Application instance for integration tests.
- * @property {RequestClient} [client] - HTTP client for request tests.
- * @property {object} [databaseCleaning] - Database cleanup options for tests.
- * @property {boolean} [databaseCleaning.transaction] - Use transactions to rollback between tests.
- * @property {boolean} [databaseCleaning.truncate] - Truncate tables between tests.
- * @property {boolean} [databaseCleaning.truncateBefore] - Truncate tables before each test, in addition to the default cleanup.
- * @property {boolean} [focus] - Whether this test is focused.
- * @property {() => (void|Promise<void>)} [function] - Test callback function.
- * @property {number} [retry] - Number of retries when a test fails.
- * @property {string[] | string} [tags] - Tags for filtering.
- * @property {number} [timeoutSeconds] - Timeout in seconds for the test.
- * @property {string} [type] - Test type identifier.
- */
-
-/**
- * TestData type.
- * @typedef {object} TestData
- * @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.
- */
-
-/**
- * FailedTestDetail type.
- * @typedef {object} FailedTestDetail
- * @property {string} fullDescription - Full test description.
- * @property {string} [filePath] - Source file path.
- * @property {number} [line] - Source line number.
- * @property {?} error - Failure error.
- * @property {string} [consoleOutput] - Captured console output while test ran.
- * @property {string} [consoleLogPath] - Saved console log path.
- */
-
-/**
- * ActiveAfterAllScopeEntry type.
- * @typedef {object} ActiveAfterAllScopeEntry
- * @property {TestsArgument} tests - Scope test tree.
- * @property {boolean} afterAllsRun - Whether cleanup hooks have run.
- */
-
-/**
- * Defines this typedef.
- * @typedef {function({configuration: import("../configuration.js").default, testArgs: TestArgs, testData: TestData}) : (void|Promise<void>)} AfterBeforeEachCallbackType
- */
-
-/**
- * AfterBeforeEachCallbackObjectType type.
- * @typedef {object} AfterBeforeEachCallbackObjectType
- * @property {AfterBeforeEachCallbackType} callback - Hook callback to execute.
- */
-
-/**
- * Defines this typedef.
- * @typedef {function({configuration: import("../configuration.js").default}) : (void|Promise<void>)} BeforeAfterAllCallbackType
- */
-
-/**
- * BeforeAfterAllCallbackObjectType type.
- * @typedef {object} BeforeAfterAllCallbackObjectType
- * @property {BeforeAfterAllCallbackType} callback - Hook callback to execute.
- */
-
-/**
- * TestsArgument type.
- * @typedef {object} TestsArgument
- * @property {Record<string, TestData>} args - Arguments keyed by test description.
- * @property {boolean} [anyTestsFocussed] - Whether any tests in the tree are focused.
- * @property {AfterBeforeEachCallbackObjectType[]} afterEaches - After-each hooks for this scope.
- * @property {BeforeAfterAllCallbackObjectType[]} afterAlls - After-all hooks for this scope.
- * @property {BeforeAfterAllCallbackObjectType[]} beforeAlls - Before-all hooks for this scope.
- * @property {AfterBeforeEachCallbackObjectType[]} beforeEaches - Before-each hooks for this scope.
- * @property {string} [filePath] - Source file path.
- * @property {number} [line] - Source line number.
- * @property {Record<string, TestData>} tests - A unique identifier for the node.
- * @property {Record<string, TestsArgument>} subs - Optional child nodes. Each item is another `Node`, allowing recursion.
- */
-
 export default class TestRunner {
   /**
    * Narrows the runtime value to the documented type.
@@ -539,17 +528,18 @@ export default class TestRunner {
   }
 
   /**
-   * Pins each per-test connection as its pool's in-process test shared connection so
-   * HTTP request handlers dispatched during the test (which run in the main thread but
-   * in a fresh async context without the connection pin) resolve to the SAME connection
-   * — and therefore the same open transaction — as the test body. Pools that predate the
-   * shared-connection hook are skipped. Pair with {@link clearTestSharedConnections} in a
-   * finally.
-   * @returns {void}
+   * Registers each non-tenant per-test connection as a dynamic candidate for in-process
+   * request sharing. The pool evaluates transaction state when each request is dispatched,
+   * so a transaction started or ended during a hook callback takes effect immediately.
+   * Inactive and tenant-only connections remain independently pooled. Pair with
+   * {@link clearTestSharedConnections} in a finally.
+   * @returns {{pool: import("../database/pool/base.js").default, registration: import("../database/pool/base.js").TestSharedConnectionRegistration}[]} - Lifecycle-owned registrations.
    */
   activateTestSharedConnections() {
     const configuration = this.getConfiguration()
     const currentConnections = configuration.getCurrentConnections()
+    /** @type {{pool: import("../database/pool/base.js").default, registration: import("../database/pool/base.js").TestSharedConnectionRegistration}[]} */
+    const registrations = []
 
     for (const identifier of Object.keys(currentConnections)) {
       const pool = configuration.getDatabasePool(identifier)
@@ -561,16 +551,33 @@ export default class TestRunner {
       if (pool.getConfiguration().tenantOnly) {
         continue
       }
-      pool.setTestSharedConnection(currentConnections[identifier])
+
+      const connection = currentConnections[identifier]
+
+      const registration = pool.setTestSharedConnectionProvider(() => {
+        return connection.insideTransaction() ? connection : undefined
+      })
+
+      if (registration) registrations.push({pool, registration})
     }
+
+    return registrations
   }
 
   /**
    * Clears the in-process test shared connection on every configured pool. Idempotent and
    * safe to call when none was set.
+   * @param {{pool: import("../database/pool/base.js").default, registration: import("../database/pool/base.js").TestSharedConnectionRegistration}[]} [registrations] - Lifecycle-owned registrations to clear conditionally.
    * @returns {void}
    */
-  clearTestSharedConnections() {
+  clearTestSharedConnections(registrations) {
+    if (registrations) {
+      for (const {pool, registration} of registrations) {
+        pool.clearTestSharedConnection(registration)
+      }
+      return
+    }
+
     const configuration = this.getConfiguration()
 
     for (const identifier of configuration.getDatabaseIdentifiers()) {
@@ -976,6 +983,8 @@ export default class TestRunner {
            * still wait for it to settle after runWithTimeout has abandoned it.
            * @type {Promise<?> | undefined} */
           let testLifecycle
+          /** @type {{pool: import("../database/pool/base.js").default, registration: import("../database/pool/base.js").TestSharedConnectionRegistration}[]} */
+          let testSharedConnectionRegistrations = []
           /**
            * Shared mutable flag so the catch block can suppress the
            * `_successfulTests` increment inside the still-detached lifecycle:
@@ -1002,12 +1011,11 @@ export default class TestRunner {
               // stale async-context pin and force every later test onto a fresh checkout,
               // breaking isolation).
               await this.getConfiguration().ensureConnections({name: `Test: ${testDescription}`}, async () => {
-                // Only request-type tests dispatch through the in-process HTTP handler,
-                // so only they need the pinned connection shared with it. Sharing it for
-                // every test would let unrelated specs observe a test shared connection on
-                // pools they inspect directly. Cleared after afterEach either way.
+                // Register dynamic candidates before application hooks so transaction
+                // state changes made during a hook are visible to a request dispatched
+                // by that same callback.
                 if (testArgs.type == "request") {
-                  this.activateTestSharedConnections()
+                  testSharedConnectionRegistrations = this.activateTestSharedConnections()
                 }
 
                 try {
@@ -1035,7 +1043,7 @@ export default class TestRunner {
                     }
                   }
                 } finally {
-                  this.clearTestSharedConnections()
+                  this.clearTestSharedConnections(testSharedConnectionRegistrations)
                 }
               })
             })
@@ -1077,7 +1085,7 @@ export default class TestRunner {
               // ensureConnections before activateTestSharedConnections() replaces
               // it. Clear it here so the next test checks out a fresh connection.
               // Idempotent when the lifecycle did settle and already cleared.
-              this.clearTestSharedConnections()
+              this.clearTestSharedConnections(testSharedConnectionRegistrations)
             }
 
             willRetry = retriesUsed < retryCount

package/src/testing/test.js

@@ -7,6 +7,14 @@ import Expect from "./expect.js"
 import waitForEvent from "./wait-for-event.js"
 import {arrayContaining, objectContaining} from "./expect-utils.js"
 
+/**
+ * VelociousTestConfig type.
+ * @typedef {object} VelociousTestConfig
+ * @property {"failure" | "live"} consoleOutput - Console output mode.
+ * @property {string[]} excludeTags - Tags excluded by default.
+ * @property {number} defaultTimeoutSeconds - Default timeout in seconds.
+ * @property {number} failedConsoleOutputMaxLines - Maximum failed console lines to print inline.
+ */
 /**
  * Tests.
  * @type {import("./test-runner.js").TestsArgument} */
@@ -202,7 +210,6 @@ function afterAll(callback) {
   currentTest.afterAlls.push({callback})
 }
 
-
 /**
  * Runs describe.
  * @param {string} description - Description.
@@ -353,11 +360,3 @@ globalThis.testEvents = testEvents
 globalThis.configureTests = configureTests
 
 export {afterAll, afterEach, beforeAll, beforeEach, configureTests, describe, expect, fit, it, arrayContaining, objectContaining, testConfig, testEvents, tests, waitForEvent}
-/**
- * VelociousTestConfig type.
- * @typedef {object} VelociousTestConfig
- * @property {"failure" | "live"} consoleOutput - Console output mode.
- * @property {string[]} excludeTags - Tags excluded by default.
- * @property {number} defaultTimeoutSeconds - Default timeout in seconds.
- * @property {number} failedConsoleOutputMaxLines - Maximum failed console lines to print inline.
- */

package/src/utils/backtrace-cleaner.js

@@ -1,3 +1,11 @@
+/**
+ * ParsedStackFrame type.
+ * @typedef {object} ParsedStackFrame
+ * @property {string | undefined} methodName - Method/function name from the stack frame.
+ * @property {string} sourcePath - File or URL path from the stack frame.
+ * @property {number} lineNumber - Source line number.
+ * @property {number | undefined} columnNumber - Source column number.
+ */
 // @ts-check
 
 /**
@@ -9,15 +17,6 @@ function escapeRegExp(value) {
   return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")
 }
 
-/**
- * ParsedStackFrame type.
- * @typedef {object} ParsedStackFrame
- * @property {string | undefined} methodName - Method/function name from the stack frame.
- * @property {string} sourcePath - File or URL path from the stack frame.
- * @property {number} lineNumber - Source line number.
- * @property {number | undefined} columnNumber - Source column number.
- */
-
 /**
  * Runs normalize path.
  * @param {string | undefined} value - Path or file URL.

package/src/utils/model-scope.js

@@ -1,7 +1,3 @@
-// @ts-check
-
-const MODEL_SCOPE_DESCRIPTOR_MARKER = "velociousModelScopeDescriptor"
-
 /**
  * ModelScopeDescriptor type.
  * @typedef {object} ModelScopeDescriptor
@@ -10,6 +6,9 @@ const MODEL_SCOPE_DESCRIPTOR_MARKER = "velociousModelScopeDescriptor"
  * @property {typeof import("../database/record/index.js").default | import("../frontend-models/base.js").FrontendModelClass} modelClass - Owning model class.
  * @property {Array<?>} scopeArgs - Scope arguments.
  */
+// @ts-check
+
+const MODEL_SCOPE_DESCRIPTOR_MARKER = "velociousModelScopeDescriptor"
 
 /**
  * Runs the defineModelScope helper.

package/src/utils/ransack.js

@@ -4,50 +4,24 @@ import * as inflection from "inflection"
 import {isPlainObject} from "is-plain-object"
 import {resolveFrontendModelClass} from "../frontend-models/model-registry.js"
 
-/** Error raised when a Ransack descriptor is malformed. */
-export class RansackQueryError extends Error {
-  /**
-   * Creates a Ransack query error.
-   * @param {string} message - Error message.
-   */
-  constructor(message) {
-    super(message)
-
-    this.name = "RansackQueryError"
-  }
-}
-
-/**
- * Builds a Ransack query error.
- * @param {string} message - Error message.
- * @returns {RansackQueryError} - Ransack query error.
- */
-function ransackQueryError(message) {
-  return new RansackQueryError(message)
-}
-
 /**
  * RansackPredicate type.
  * @typedef {"cont" | "end" | "eq" | "gt" | "gteq" | "in" | "lt" | "lteq" | "not_eq" | "not_in" | "null" | "start"} RansackPredicate
  */
-
 /**
  * RansackCombinator type.
  * @typedef {"and" | "or"} RansackCombinator
  */
-
 /**
  * RansackModelClass type.
  * @typedef {typeof import("../database/record/index.js").default | import("../frontend-models/base.js").FrontendModelClass} RansackModelClass
  */
-
 /**
  * RansackAttribute type.
  * @typedef {object} RansackAttribute
  * @property {string} attributeName - Resolved attribute name.
  * @property {string[]} path - Resolved relationship path.
  */
-
 /**
  * RansackCondition type.
  * @typedef {object} RansackCondition
@@ -56,7 +30,6 @@ function ransackQueryError(message) {
  * @property {RansackPredicate} predicate - Parsed Ransack predicate.
  * @property {?} value - Normalized value.
  */
-
 /**
  * RansackGroup type.
  * @typedef {object} RansackGroup
@@ -64,6 +37,33 @@ function ransackQueryError(message) {
  * @property {RansackCondition[]} conditions - Conditions in this group.
  * @property {RansackGroup[]} groupings - Nested groups.
  */
+/**
+ * RansackSort type.
+ * @typedef {object} RansackSort
+ * @property {string} attribute - Resolved attribute name.
+ * @property {"asc" | "desc"} direction - Sort direction.
+ */
+/** Error raised when a Ransack descriptor is malformed. */
+export class RansackQueryError extends Error {
+  /**
+   * Creates a Ransack query error.
+   * @param {string} message - Error message.
+   */
+  constructor(message) {
+    super(message)
+
+    this.name = "RansackQueryError"
+  }
+}
+
+/**
+ * Builds a Ransack query error.
+ * @param {string} message - Error message.
+ * @returns {RansackQueryError} - Ransack query error.
+ */
+function ransackQueryError(message) {
+  return new RansackQueryError(message)
+}
 
 const supportedPredicates = [
   "not_in",
@@ -803,13 +803,6 @@ function normalizeRansackArray(value) {
   return [value]
 }
 
-/**
- * RansackSort type.
- * @typedef {object} RansackSort
- * @property {string} attribute - Resolved attribute name.
- * @property {"asc" | "desc"} direction - Sort direction.
- */
-
 /**
  * Parses a ransack `s` sort string against model attributes.
  * @param {RansackModelClass} modelClass - Model class for attribute lookup.