velocious 1.0.562 → 1.0.564

package/src/database/pool/async-tracked-multi-connection.js

@@ -3,14 +3,6 @@
 import {AsyncLocalStorage} from "async_hooks"
 import BasePool, {POOL_CONFIGURATION_KEY} from "./base.js"
 
-export const CLOSED_CONNECTION = Symbol("velociousClosedConnection")
-const IDLE_CONNECTION_CHECKED_IN_AT = Symbol("velociousIdleConnectionCheckedInAt")
-const CONNECTION_CHECKED_OUT_AT = Symbol("velociousConnectionCheckedOutAt")
-const SUPPRESSED_CONNECTION_CONTEXT = Symbol("velociousSuppressedConnectionContext")
-const DEFAULT_MAX_CONNECTIONS = 10
-const DEFAULT_IDLE_TIMEOUT_MILLIS = 5000
-const DEFAULT_CHECKOUT_TIMEOUT_MILLIS = 10000
-
 /**
  * PendingCheckout type.
  * @typedef {object} PendingCheckout
@@ -24,6 +16,13 @@ const DEFAULT_CHECKOUT_TIMEOUT_MILLIS = 10000
  * @property {number | null} timeoutMillis - Milliseconds to wait before rejecting, or null when disabled.
  * @property {ReturnType<typeof setTimeout> | undefined} timeoutTimer - Timer that rejects the pending checkout.
  */
+export const CLOSED_CONNECTION = Symbol("velociousClosedConnection")
+const IDLE_CONNECTION_CHECKED_IN_AT = Symbol("velociousIdleConnectionCheckedInAt")
+const CONNECTION_CHECKED_OUT_AT = Symbol("velociousConnectionCheckedOutAt")
+const SUPPRESSED_CONNECTION_CONTEXT = Symbol("velociousSuppressedConnectionContext")
+const DEFAULT_MAX_CONNECTIONS = 10
+const DEFAULT_IDLE_TIMEOUT_MILLIS = 5000
+const DEFAULT_CHECKOUT_TIMEOUT_MILLIS = 10000
 
 export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends BasePool {
   /**
@@ -42,6 +41,18 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
    */
   _testSharedConnection = undefined
 
+  /**
+   * Dynamically resolves the connection eligible for in-process test request sharing.
+   * @type {(() => import("../drivers/base.js").default | undefined) | undefined}
+   */
+  _testSharedConnectionProvider = undefined
+
+  /**
+   * Identifies the lifecycle that installed the current shared connection or provider.
+   * @type {import("./base.js").TestSharedConnectionRegistration | undefined}
+   */
+  _testSharedConnectionRegistration = undefined
+
   /**
    * Connections.
    * @type {import("../drivers/base.js").default[]} */
@@ -797,17 +808,44 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
    * Set a shared connection for test mode so that HTTP handlers running
    * in the same process can reuse the test runner's database connection.
    * @param {import("../drivers/base.js").default} connection - Shared connection.
-   * @returns {void}
+   * @returns {import("./base.js").TestSharedConnectionRegistration} - Opaque registration handle.
    */
   setTestSharedConnection(connection) {
+    const registration = {owner: Symbol("test-shared-connection")}
+
     this._testSharedConnection = connection
+    this._testSharedConnectionProvider = undefined
+    this._testSharedConnectionRegistration = registration
+
+    return registration
   }
 
   /**
-   * Runs clear test shared connection.
+   * Sets a provider that is evaluated when an in-process test request is dispatched.
+   * @param {() => import("../drivers/base.js").default | undefined} provider - Shared connection provider.
+   * @returns {import("./base.js").TestSharedConnectionRegistration} - Opaque registration handle.
+   */
+  setTestSharedConnectionProvider(provider) {
+    const registration = {owner: Symbol("test-shared-connection-provider")}
+
+    this._testSharedConnection = undefined
+    this._testSharedConnectionProvider = provider
+    this._testSharedConnectionRegistration = registration
+
+    return registration
+  }
+
+  /**
+   * Clears the current shared connection registration. A supplied stale registration
+   * cannot clear a provider installed by a newer lifecycle.
+   * @param {import("./base.js").TestSharedConnectionRegistration} [registration] - Opaque registration handle to clear conditionally.
    * @returns {void} */
-  clearTestSharedConnection() {
+  clearTestSharedConnection(registration) {
+    if (registration && registration !== this._testSharedConnectionRegistration) return
+
     this._testSharedConnection = undefined
+    this._testSharedConnectionProvider = undefined
+    this._testSharedConnectionRegistration = undefined
   }
 
   /**
@@ -821,9 +859,21 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
    * @returns {T} - Callback result.
    */
   runWithTestSharedConnection(callback) {
-    if (!this._testSharedConnection) return callback()
+    const connection = this.testSharedConnection()
 
-    return this.asyncLocalStorage.run(this._testSharedConnection.getIdSeq(), callback)
+    if (!connection) return callback()
+
+    return this.asyncLocalStorage.run(connection.getIdSeq(), callback)
+  }
+
+  /**
+   * Resolves the connection currently eligible for in-process test request sharing.
+   * @returns {import("../drivers/base.js").default | undefined} - Shared connection.
+   */
+  testSharedConnection() {
+    return this._testSharedConnectionProvider
+      ? this._testSharedConnectionProvider()
+      : this._testSharedConnection
   }
 
   /**
@@ -835,7 +885,7 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
     const id = this.asyncLocalStorage.getStore()
 
     if (id === SUPPRESSED_CONNECTION_CONTEXT) return undefined
-    if (id === undefined) return this._testSharedConnection
+    if (id === undefined) return this.testSharedConnection()
 
     return this.getCurrentConnection()
   }
@@ -1285,7 +1335,7 @@ export default class VelociousDatabasePoolAsyncTrackedMultiConnection extends Ba
 
     this.connections = []
     this.connectionsInUse = {}
-    this._testSharedConnection = undefined
+    this.clearTestSharedConnection()
     this.clearGlobalConnectionForIdentifier()
 
     for (const connection of connections) {

package/src/database/pool/base.js

@@ -4,14 +4,16 @@ import Configuration from "../../configuration.js"
 import Logger from "../../logger.js"
 import baseMethodsForward from "./base-methods-forward.js"
 
-export const POOL_CONFIGURATION_KEY = Symbol("velociousPoolConfigurationKey")
+/**
+ * Opaque ownership handle for an in-process test shared connection registration.
+ * @typedef {{owner: symbol}} TestSharedConnectionRegistration
+ */
 
 /**
  * ConnectionCheckoutOptions type.
  * @typedef {object} ConnectionCheckoutOptions
  * @property {string} [name] - Human-readable name for the checked-out connection.
  */
-
 /**
  * DatabasePoolPendingCheckoutDebugSnapshot type.
  * @typedef {object} DatabasePoolPendingCheckoutDebugSnapshot
@@ -24,7 +26,6 @@ export const POOL_CONFIGURATION_KEY = Symbol("velociousPoolConfigurationKey")
  * @property {number | null} timeoutMillis - Timeout configured for the checkout, or null when disabled.
  * @property {number} waitingForMs - Milliseconds already spent waiting.
  */
-
 /**
  * DatabasePoolDebugSnapshot type.
  * @typedef {object} DatabasePoolDebugSnapshot
@@ -38,6 +39,7 @@ export const POOL_CONFIGURATION_KEY = Symbol("velociousPoolConfigurationKey")
  * @property {number} pendingCheckoutCount - Number of queued checkout requests.
  * @property {string} poolClass - Pool class name.
  */
+export const POOL_CONFIGURATION_KEY = Symbol("velociousPoolConfigurationKey")
 
 /**
  * Shared.
@@ -149,15 +151,29 @@ class VelociousDatabasePoolBase {
    * pin (used by the test runner to share one connection with in-process HTTP handlers).
    * Base pools that do not track async context ignore it; async-context pools override.
    * @param {import("../drivers/base.js").default} _connection - Shared connection.
-   * @returns {void}
+   * @returns {TestSharedConnectionRegistration | undefined} - Opaque registration handle when supported.
    */
-  setTestSharedConnection(_connection) {}
+  setTestSharedConnection(_connection) {
+    return undefined
+  }
+
+  /**
+   * Sets a provider that resolves the connection eligible for in-process test request sharing.
+   * Base pools that do not track async context ignore it; async-context pools override.
+   * @param {() => import("../drivers/base.js").default | undefined} _provider - Shared connection provider.
+   * @returns {TestSharedConnectionRegistration | undefined} - Opaque registration handle when supported.
+   */
+  setTestSharedConnectionProvider(_provider) {
+    return undefined
+  }
 
   /**
-   * Clears the shared connection set by {@link setTestSharedConnection}. No-op by default.
+   * Clears the shared connection or provider set for in-process test requests. No-op by default.
+   * When a registration is provided, clears only if it is still the active registration.
+   * @param {TestSharedConnectionRegistration} [_registration] - Opaque handle returned when the shared value was set.
    * @returns {void}
    */
-  clearTestSharedConnection() {}
+  clearTestSharedConnection(_registration) {}
 
   /**
    * Runs a callback inside the test shared connection's context. Base pools that do not

package/src/database/query/index.js

@@ -14,6 +14,27 @@ import WhereHash from "./where-hash.js"
 import WhereNot from "./where-not.js"
 import WherePlain from "./where-plain.js"
 
+/**
+ * QueryArgsType type.
+ * @typedef {object} QueryArgsType
+ * @property {import("../drivers/base.js").default | (() => import("../drivers/base.js").default)} driver - Driver instance or factory for query execution.
+ * @property {Array<import("./from-base.js").default>} [froms] - FROM clauses for the query.
+ * @property {string[]} [groups] - GROUP BY columns.
+ * @property {Array<import("./join-base.js").default>} [joins] - JOIN clauses for the query.
+ * @property {import("../handler.js").default} handler - Handler used for executing and transforming results.
+ * @property {number | null} [limit] - LIMIT clause value.
+ * @property {number | null} [offset] - OFFSET clause value.
+ * @property {Array<import("./order-base.js").default>} [orders] - ORDER BY clauses.
+ * @property {number | null} [page] - Page number for pagination.
+ * @property {number} [perPage] - Records per page for pagination.
+ * @property {NestedPreloadRecord} [preload] - Preload graph for related records.
+ * @property {Record<string, string[]>} [preloadSelects] - Attribute names to load for preloaded relationships, keyed by target model name.
+ * @property {Record<string, string[]>} [preloadSelectsExtra] - Extra selects to load in addition to the defaults for preloaded relationships, keyed by target model name.
+ * @property {Array<import("./select-base.js").default>} [selects] - SELECT clauses for the query.
+ * @property {AbortSignal} [signal] - Signal passed to database query execution.
+ * @property {boolean} [distinct] - Whether the query should use DISTINCT.
+ * @property {Array<import("./where-base.js").default>} [wheres] - WHERE conditions for the query.
+ */
 /**
  * OrderArgumentType type.
  * @typedef {{[key: string]: boolean | string | string[] | NestedPreloadRecord }} NestedPreloadRecord
@@ -108,28 +129,6 @@ function mergeJoinValue(existing, incoming) {
   return incoming
 }
 
-/**
- * QueryArgsType type.
- * @typedef {object} QueryArgsType
- * @property {import("../drivers/base.js").default | (() => import("../drivers/base.js").default)} driver - Driver instance or factory for query execution.
- * @property {Array<import("./from-base.js").default>} [froms] - FROM clauses for the query.
- * @property {string[]} [groups] - GROUP BY columns.
- * @property {Array<import("./join-base.js").default>} [joins] - JOIN clauses for the query.
- * @property {import("../handler.js").default} handler - Handler used for executing and transforming results.
- * @property {number | null} [limit] - LIMIT clause value.
- * @property {number | null} [offset] - OFFSET clause value.
- * @property {Array<import("./order-base.js").default>} [orders] - ORDER BY clauses.
- * @property {number | null} [page] - Page number for pagination.
- * @property {number} [perPage] - Records per page for pagination.
- * @property {NestedPreloadRecord} [preload] - Preload graph for related records.
- * @property {Record<string, string[]>} [preloadSelects] - Attribute names to load for preloaded relationships, keyed by target model name.
- * @property {Record<string, string[]>} [preloadSelectsExtra] - Extra selects to load in addition to the defaults for preloaded relationships, keyed by target model name.
- * @property {Array<import("./select-base.js").default>} [selects] - SELECT clauses for the query.
- * @property {AbortSignal} [signal] - Signal passed to database query execution.
- * @property {boolean} [distinct] - Whether the query should use DISTINCT.
- * @property {Array<import("./where-base.js").default>} [wheres] - WHERE conditions for the query.
- */
-
 export default class VelociousDatabaseQuery {
   /**
    * Runs constructor.

package/src/database/query/model-class-query.js

@@ -21,6 +21,11 @@ import WhereNot from "./where-not.js"
 import JoinsParser from "../query-parser/joins-parser.js"
 import WhereParser from "../query-parser/where-parser.js"
 
+/**
+ * Defines this typedef.
+ * @template {typeof import("../record/index.js").default} [MC=typeof import("../record/index.js").default]
+ * @typedef {import("./index.js").QueryArgsType & {modelClass: MC, joinBasePath?: string[], joinTracker?: import("./join-tracker.js").default, forceQualifyBaseTable?: boolean, withCount?: import("./with-count.js").WithCountEntry[], queryData?: import("./query-data.js").QueryDataEntry[]}} ModelClassQueryArgsType
+ */
 /**
  * Runs unquote sql identifier.
  * @param {string} value - Potentially quoted SQL identifier.
@@ -166,11 +171,6 @@ function normalizePreloadRecord(preload) {
  * Defines this typedef.
  * @template {typeof import("../record/index.js").default} [MC=typeof import("../record/index.js").default]
  */
-/**
- * Defines this typedef.
- * @template {typeof import("../record/index.js").default} [MC=typeof import("../record/index.js").default]
- * @typedef {import("./index.js").QueryArgsType & {modelClass: MC, joinBasePath?: string[], joinTracker?: import("./join-tracker.js").default, forceQualifyBaseTable?: boolean, withCount?: import("./with-count.js").WithCountEntry[], queryData?: import("./query-data.js").QueryDataEntry[]}} ModelClassQueryArgsType
- */
 
 /**
  * A generic query over some model type.
@@ -330,7 +330,6 @@ export default class VelociousDatabaseQueryModelClassQuery extends DatabaseQuery
 
     sql += " AS count"
 
-
     // Clone query and execute count
     const countQuery = this.clone()
 

package/src/database/record/attachments/normalize-input.js

@@ -2,6 +2,15 @@
 
 import UploadedFile from "../../../http-server/client/uploaded-file/uploaded-file.js"
 
+/**
+ * NormalizedAttachmentInput type.
+ * @typedef {object} NormalizedAttachmentInput
+ * @property {number} byteSize - File size in bytes.
+ * @property {Buffer} contentBuffer - Raw content bytes.
+ * @property {string} contentBase64 - Base64 encoded content.
+ * @property {string | null} contentType - Content type.
+ * @property {string} filename - Filename.
+ */
 /**
  * Runs base name.
  * @param {string} value - Path-like value.
@@ -96,16 +105,6 @@ async function uploadedFileBuffer(uploadedFile, environmentHandler) {
   throw new Error("Unsupported uploaded file type")
 }
 
-/**
- * NormalizedAttachmentInput type.
- * @typedef {object} NormalizedAttachmentInput
- * @property {number} byteSize - File size in bytes.
- * @property {Buffer} contentBuffer - Raw content bytes.
- * @property {string} contentBase64 - Base64 encoded content.
- * @property {string | null} contentType - Content type.
- * @property {string} filename - Filename.
- */
-
 /**
  * Runs normalize record attachment input.
  * @param {?} input - Attachment input.

package/src/database/record/attachments/store.js

@@ -4,11 +4,11 @@ import UUID from "pure-uuid"
 import TableData from "../../table-data/index.js"
 import normalizeRecordAttachmentInput from "./normalize-input.js"
 
-const ATTACHMENTS_TABLE = "velocious_attachments"
-
 /**
  * AttachmentDriverConstructor type.
  * @typedef {import("../../../configuration-types.js").AttachmentDriverConstructor} AttachmentDriverConstructor */
+const ATTACHMENTS_TABLE = "velocious_attachments"
+
 /**
  * Stores by configuration.
  * @type {WeakMap<import("../../../configuration.js").default, Map<string, RecordAttachmentsStore>>} */

package/src/database/record/auditing.js

@@ -2,6 +2,13 @@
 
 import UUID from "pure-uuid"
 
+/**
+ * Global audit event bus matching ActiveRecordAuditable::Events.
+ * @typedef {object} AuditEventsType
+ * @property {(type: string, action: string, args: AuditEventPayload) => void} call - Fire all callbacks for a model type + action.
+ * @property {(type: string, action: string, callback: (args: AuditEventPayload) => void) => () => void} connect - Register a callback for a model type + action. Returns an unsubscribe function.
+ * @property {() => void} reset - Clear all registered callbacks.
+ */
 /**
  * AuditChanges type.
  * @typedef {Record<string, ?>} AuditChanges
@@ -64,14 +71,6 @@ const generatedAuditRelationships = new WeakSet()
 /** @type {Record<string, Record<string, Array<(args: AuditEventPayload) => void>>>} */
 let globalEventConnections = {}
 
-/**
- * Global audit event bus matching ActiveRecordAuditable::Events.
- * @typedef {object} AuditEventsType
- * @property {(type: string, action: string, args: AuditEventPayload) => void} call - Fire all callbacks for a model type + action.
- * @property {(type: string, action: string, callback: (args: AuditEventPayload) => void) => () => void} connect - Register a callback for a model type + action. Returns an unsubscribe function.
- * @property {() => void} reset - Clear all registered callbacks.
- */
-
 /** @type {AuditEventsType} */
 const AuditEvents = {
   /**

package/src/database/record/index.js

@@ -57,6 +57,10 @@ import ValidatorsUniqueness from "./validators/uniqueness.js"
 import registerActsAsListCallbacks from "./acts-as-list.js"
 import UUID from "pure-uuid"
 
+/**
+ * Translation record shape used by translated attributes.
+ * @typedef {VelociousDatabaseRecord & {locale: function(): string}} TranslationBase
+ */
 /**
  * AttachmentDriverConstructor type.
  * @typedef {import("../../configuration-types.js").AttachmentDriverConstructor} AttachmentDriverConstructor
@@ -4452,11 +4456,6 @@ class VelociousDatabaseRecord {
   }
 }
 
-/**
- * Translation record shape used by translated attributes.
- * @typedef {VelociousDatabaseRecord & {locale: function(): string}} TranslationBase
- */
-
 VelociousDatabaseRecord.registerValidatorType("format", ValidatorsFormat)
 VelociousDatabaseRecord.registerValidatorType("length", ValidatorsLength)
 VelociousDatabaseRecord.registerValidatorType("presence", ValidatorsPresence)

package/src/environment-handlers/node/cli/commands/generate/frontend-models.js

@@ -6,8 +6,6 @@ import * as inflection from "inflection"
 import {frontendModelResourceIsBuiltIn, frontendModelResourcesWithBuiltInsForBackendProject} from "../../../../../frontend-models/built-in-resources.js"
 import {frontendModelResourceClassFromDefinition, frontendModelResourceConfigurationFromDefinition} from "../../../../../frontend-models/resource-definition.js"
 
-const FRONTEND_MODELS_REGENERATE_COMMAND = "velocious generate:frontend-models"
-
 /**
  * Attribute metadata used for generated frontend-model JSDoc.
  * @typedef {object} FrontendAttributeConfig
@@ -47,6 +45,7 @@ const FRONTEND_MODELS_REGENERATE_COMMAND = "velocious generate:frontend-models"
  * @property {string | null} sourceFile - Source file that declared the method.
  * @property {string} type - JSDoc parameter type.
  */
+const FRONTEND_MODELS_REGENERATE_COMMAND = "velocious generate:frontend-models"
 
 /** Node CLI command that generates frontend model classes from backend project resource config. */
 export default class DbGenerateFrontendModels extends BaseCommand {

package/src/frontend-model-controller.js

@@ -20,6 +20,55 @@ import isDate from "./utils/is-date.js"
 import isPlainObject from "./utils/plain-object.js"
 import {RansackQueryError, normalizeRansackGroup, parseRansackSort} from "./utils/ransack.js"
 
+/**
+ * FrontendModelSearch type.
+ * @typedef {object} FrontendModelSearch
+ * @property {string[]} path - Relationship path.
+ * @property {string} column - Column or attribute name.
+ * @property {"eq" | "like" | "notEq" | "gt" | "gteq" | "lt" | "lteq"} operator - Search operator.
+ * @property {?} value - Search value.
+ */
+/**
+ * FrontendModelSort type.
+ * @typedef {object} FrontendModelSort
+ * @property {string} column - Attribute name to sort by.
+ * @property {"asc" | "desc"} direction - Sort direction.
+ * @property {string[]} path - Relationship path from root model.
+ */
+/**
+ * FrontendModelGroup type.
+ * @typedef {object} FrontendModelGroup
+ * @property {string} column - Attribute name to group by.
+ * @property {string[]} path - Relationship path from root model.
+ */
+/**
+ * FrontendModelPluck type.
+ * @typedef {object} FrontendModelPluck
+ * @property {string} column - Attribute name to pluck.
+ * @property {string[]} path - Relationship path from root model.
+ */
+/**
+ * FrontendModelPagination type.
+ * @typedef {object} FrontendModelPagination
+ * @property {number | null} limit - Maximum number of records.
+ * @property {number | null} offset - Number of records to skip.
+ * @property {number | null} page - 1-based page number.
+ * @property {number | null} perPage - Page size.
+ */
+/**
+ * @typedef {import("./configuration-types.js").ClientErrorPayloadContext & {
+ *   action: string,
+ *   expectedError: boolean,
+ *   frontendModelEndpoint: true
+ * }} FrontendModelEndpointErrorContext
+ */
+/**
+ * FrontendModelIndexQueryOptions type.
+ * @typedef {object} FrontendModelIndexQueryOptions
+ * @property {boolean} [includePagination] - Whether frontend-model pagination params should be applied.
+ * @property {boolean} [includeSort] - Whether frontend-model sort params should be applied.
+ * @property {import("./frontend-model-resource/base-resource.js").default} [resource] - Resource providing query hooks.
+ */
 /** @typedef {import("./database/query/model-class-query.js").default & Record<symbol, Set<string> | undefined>} FrontendModelQueryMetadata */
 
 /**
@@ -114,62 +163,6 @@ function normalizeFrontendModelSelect(select, rootModelName = null) {
   return normalized
 }
 
-/**
- * FrontendModelSearch type.
- * @typedef {object} FrontendModelSearch
- * @property {string[]} path - Relationship path.
- * @property {string} column - Column or attribute name.
- * @property {"eq" | "like" | "notEq" | "gt" | "gteq" | "lt" | "lteq"} operator - Search operator.
- * @property {?} value - Search value.
- */
-
-/**
- * FrontendModelSort type.
- * @typedef {object} FrontendModelSort
- * @property {string} column - Attribute name to sort by.
- * @property {"asc" | "desc"} direction - Sort direction.
- * @property {string[]} path - Relationship path from root model.
- */
-
-/**
- * FrontendModelGroup type.
- * @typedef {object} FrontendModelGroup
- * @property {string} column - Attribute name to group by.
- * @property {string[]} path - Relationship path from root model.
- */
-
-/**
- * FrontendModelPluck type.
- * @typedef {object} FrontendModelPluck
- * @property {string} column - Attribute name to pluck.
- * @property {string[]} path - Relationship path from root model.
- */
-
-/**
- * FrontendModelPagination type.
- * @typedef {object} FrontendModelPagination
- * @property {number | null} limit - Maximum number of records.
- * @property {number | null} offset - Number of records to skip.
- * @property {number | null} page - 1-based page number.
- * @property {number | null} perPage - Page size.
- */
-
-/**
- * @typedef {import("./configuration-types.js").ClientErrorPayloadContext & {
- *   action: string,
- *   expectedError: boolean,
- *   frontendModelEndpoint: true
- * }} FrontendModelEndpointErrorContext
- */
-
-/**
- * FrontendModelIndexQueryOptions type.
- * @typedef {object} FrontendModelIndexQueryOptions
- * @property {boolean} [includePagination] - Whether frontend-model pagination params should be applied.
- * @property {boolean} [includeSort] - Whether frontend-model sort params should be applied.
- * @property {import("./frontend-model-resource/base-resource.js").default} [resource] - Resource providing query hooks.
- */
-
 const frontendModelJoinedPathsSymbol = Symbol("frontendModelJoinedPaths")
 const frontendModelGroupedColumnsSymbol = Symbol("frontendModelGroupedColumns")
 const frontendModelWhereNoMatchSymbol = Symbol("frontendModelWhereNoMatch")

package/src/frontend-models/base.js

@@ -17,6 +17,23 @@ import {defineModelScope} from "../utils/model-scope.js"
 import isPlainObject from "../utils/plain-object.js"
 import {readPayloadAssociationCount, readPayloadComputedAbility, readPayloadQueryData, setPayloadAssociationCount, setPayloadComputedAbility, setPayloadQueryData} from "../record-payload-values.js"
 
+/**
+ * Frontend model relationship helper type. Returned by `getRelationshipByName`,
+ * which generated models immediately cast to their concrete relationship type
+ * (e.g. `FrontendModelSingularRelationship<Owner, Target, TargetCreateAttributes>`).
+ * The members use `any` type args so that cast is allowed regardless of the
+ * target model's typed-attribute generics — a concrete `FrontendModelBase` member
+ * here makes the cast a non-overlapping (TS2352) error for every typed model.
+ * @typedef {FrontendModelHasManyRelationship<any, any, any> | FrontendModelSingularRelationship<any, any, any>} FrontendModelRelationship
+ */
+/**
+ * Defines this typedef.
+ * @typedef {{callback: (payload: {id: string, model: FrontendModelBase}) => void, eventFilterKey: string | null, eventFilterPayload: import("./query.js").FrontendModelEventFilterPayload | null, projectionPayload: import("./query.js").FrontendModelProjectionPayload}} FrontendModelModelEventCallbackEntry
+ */
+/**
+ * Defines this typedef.
+ * @typedef {{callback: (payload: {id: string}) => void}} FrontendModelDestroyEventCallbackEntry
+ */
 /**
  * FrontendModelCommandType type.
  * @typedef {"create" | "find" | "index" | "update" | "destroy" | "attach" | "attachmentList" | "download" | "url"} FrontendModelCommandType */
@@ -658,16 +675,6 @@ export class FrontendModelHasManyRelationship {
   }
 }
 
-/**
- * Frontend model relationship helper type. Returned by `getRelationshipByName`,
- * which generated models immediately cast to their concrete relationship type
- * (e.g. `FrontendModelSingularRelationship<Owner, Target, TargetCreateAttributes>`).
- * The members use `any` type args so that cast is allowed regardless of the
- * target model's typed-attribute generics — a concrete `FrontendModelBase` member
- * here makes the cast a non-overlapping (TS2352) error for every typed model.
- * @typedef {FrontendModelHasManyRelationship<any, any, any> | FrontendModelSingularRelationship<any, any, any>} FrontendModelRelationship
- */
-
 /**
  * Copies loaded relationship state between helpers of the same relationship shape.
  * @param {object} args - Arguments.
@@ -1279,15 +1286,6 @@ function cloneFrontendModelAttributes(value) {
  */
 const FRONTEND_MODELS_CHANNEL_NAME = "frontend-models"
 
-/**
- * Defines this typedef.
- * @typedef {{callback: (payload: {id: string, model: FrontendModelBase}) => void, eventFilterKey: string | null, eventFilterPayload: import("./query.js").FrontendModelEventFilterPayload | null, projectionPayload: import("./query.js").FrontendModelProjectionPayload}} FrontendModelModelEventCallbackEntry
- */
-/**
- * Defines this typedef.
- * @typedef {{callback: (payload: {id: string}) => void}} FrontendModelDestroyEventCallbackEntry
- */
-
 /**
  * Runs merge frontend model event preload.
  * @param {Record<string, import("./query.js").FrontendModelTransportValue>} target - Target preload payload.

package/src/frontend-models/outgoing-event-buffer.js

@@ -1,13 +1,12 @@
-// @ts-check
-
-const MAX_BUFFERED_OUTGOING_EVENTS = 50
-
 /**
  * BufferedOutgoingEvent type.
  * @typedef {object} BufferedOutgoingEvent
  * @property {string} customPath - Request path.
  * @property {Record<string, ?>} payload - Command payload.
  */
+// @ts-check
+
+const MAX_BUFFERED_OUTGOING_EVENTS = 50
 
 /**
  * Buffer.