velocious 1.0.563 → 1.0.565

package/src/database/record/acts-as-list.js

@@ -50,6 +50,7 @@ export default function registerActsAsListCallbacks(modelClass, positionColumn,
     const position = record.readAttribute(positionColumn)
 
     if (position != null) {
+      assertPositivePosition({position, positionColumn})
       await shiftPositionsUp({record, positionColumn, scope, fromPosition: position})
     } else {
       const nextPosition = await highestPositionInScope({record, positionColumn, scope})
@@ -77,12 +78,19 @@ export default function registerActsAsListCallbacks(modelClass, positionColumn,
 
     if (!posChanged && !scopeChanged) return
 
+    assertPositivePosition({
+      position: rawAttributes[posColumn],
+      positionColumn,
+      persisted: true
+    })
+
     const oldPosition = posChanged ? /** @type {number} */ (rawAttributes[posColumn]) : /** @type {number} */ (record.readAttribute(positionColumn))
     const newPosition = posChanged ? /** @type {number} */ (changes[posColumn]) : /** @type {number} */ (record.readAttribute(positionColumn))
     const oldScopeValue = scopeChanged ? /** @type {number} */ (rawAttributes[scopeCol]) : /** @type {number} */ (record.readAttribute(scope))
     const newScopeValue = scopeChanged ? /** @type {number} */ (changes[scopeCol]) : /** @type {number} */ (record.readAttribute(scope))
 
-    if (oldPosition == null || newPosition == null) return
+    assertPositivePosition({position: newPosition, positionColumn})
+    if (oldPosition == null) return
     if (newPosition === oldPosition && newScopeValue === oldScopeValue) return
 
     if (scopeChanged && oldScopeValue !== newScopeValue) {
@@ -100,7 +108,7 @@ export default function registerActsAsListCallbacks(modelClass, positionColumn,
         return
       }
 
-      await moveOutOfWay({record, positionColumn, scope, scopeValue: oldScopeValue, targetScopeValue: newScopeValue})
+      await moveOutOfWay({record, positionColumn, scope, scopeValue: oldScopeValue})
       setShiftingFlag(record, false)
       await shiftPositionsDown({record, positionColumn, scope, scopeValue: oldScopeValue, fromPosition: oldPosition + 1})
       await shiftPositionsUp({record, positionColumn, scope, scopeValue: newScopeValue, fromPosition: newPosition, excludeRecordId: record.id()})
@@ -121,7 +129,14 @@ export default function registerActsAsListCallbacks(modelClass, positionColumn,
   modelClass.beforeDestroy(async (record) => {
     const position = record.readAttribute(positionColumn)
 
-    if (position == null) return
+    if (position == null) {
+      const modelClass = /** @type {typeof import("./index.js").default} */ (record.constructor)
+      const posColumn = modelClass.getColumnNameForAttributeName(positionColumn)
+
+      if (posColumn in record._attributes) assertPositivePosition({position, positionColumn, persisted: true})
+      return
+    }
+    assertPositivePosition({position, positionColumn, persisted: true})
 
     await moveOutOfWay({record, positionColumn, scope})
     setShiftingFlag(record, false)
@@ -130,6 +145,22 @@ export default function registerActsAsListCallbacks(modelClass, positionColumn,
   })
 }
 
+/**
+ * Enforces the public gap-less list position invariant before any shifting.
+ * @param {object} args - Arguments.
+ * @param {number | null | undefined} args.position - Position to validate.
+ * @param {string} args.positionColumn - Position attribute name.
+ * @param {boolean} [args.persisted] - Whether the invalid value came from persisted state.
+ * @returns {void}
+ */
+function assertPositivePosition({position, positionColumn, persisted = false}) {
+  if (typeof position === "number" && Number.isInteger(position) && position > 0) return
+
+  const source = persisted ? "Persisted" : "Requested"
+
+  throw new Error(`${source} actsAsList ${positionColumn} must be a positive integer`)
+}
+
 /**
  * Places a moved row after surrounding rows have shifted.
  * @param {object} args - Arguments.
@@ -380,30 +411,26 @@ function resolveScopeValue(record, scope) {
  * @param {string} args.positionColumn - camelCase position attribute.
  * @param {string} args.scope - camelCase scope attribute.
  * @param {string | number | null} [args.scopeValue] - Scope containing the record before move-out.
- * @param {string | number | null} [args.targetScopeValue] - Temporary scope value to assign.
  * @returns {Promise<void>}
  */
-async function moveOutOfWay({record, positionColumn, scope, scopeValue, targetScopeValue}) {
+async function moveOutOfWay({record, positionColumn, scope, scopeValue}) {
   const modelClass = /** @type {typeof import("./index.js").default} */ (record.constructor)
   const connection = modelClass.connection()
   const tableName = modelClass._getTable().getName()
   const resolvedScopeValue = scopeValue != null ? scopeValue : resolveScopeValue(record, scope)
-  const resolvedTargetScopeValue = targetScopeValue != null ? targetScopeValue : resolvedScopeValue
 
   if (resolvedScopeValue == null) return
-  if (resolvedTargetScopeValue == null) return
 
-  const tempPosition = -record.id()
   const positionColumnSql = connection.quoteColumn(modelClass.getColumnNameForAttributeName(positionColumn))
   const scopeColumnSql = connection.quoteColumn(modelClass.getColumnNameForAttributeName(scope))
   const tableSql = connection.quoteTable(tableName)
-  const pkSql = connection.quoteColumn("id")
+  const pkSql = connection.quoteColumn(modelClass.primaryKey())
 
   setShiftingFlag(record, true)
 
   try {
     await connection.query(
-      `UPDATE ${tableSql} SET ${scopeColumnSql} = ${connection.quote(resolvedTargetScopeValue)}, ${positionColumnSql} = ${connection.quote(tempPosition)} WHERE ${scopeColumnSql} = ${connection.quote(resolvedScopeValue)} AND ${pkSql} = ${connection.quote(record.id())}`
+      `UPDATE ${tableSql} SET ${positionColumnSql} = -${positionColumnSql} WHERE ${scopeColumnSql} = ${connection.quote(resolvedScopeValue)} AND ${pkSql} = ${connection.quote(record.id())}`
     )
   } finally {
     // Don't clear the flag here — the caller will do that after shifts

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/base-models.js

@@ -154,16 +154,12 @@ export default class DbGenerateModel extends BaseCommand {
       // --- getModelClass() override (fixes polymorphic typing in JS/JSDoc) ---
       if (await fileExists(sourceModelFullFilePath)) {
         // Model file exists (e.g. src/models/ticket.js) → return typeof Ticket
-        fileContent += "  /**\n"
-        fileContent += `   * @returns {typeof import("${sourceModelFilePath}").default}\n`
-        fileContent += "   */\n"
+        fileContent += `  /** @returns {typeof import("${sourceModelFilePath}").default} */\n`
         fileContent += "  // @ts-ignore - override narrows return type for better IntelliSense in generated model bases\n"
         fileContent += `  getModelClass() { return /** @type {typeof import("${sourceModelFilePath}").default} */ (this.constructor) }\n\n`
       } else {
         // No model file yet → fall back to typeof TicketBase
-        fileContent += "  /**\n"
-        fileContent += `   * @returns {typeof ${modelNameCamelized}Base}\n`
-        fileContent += "   */\n"
+        fileContent += `  /** @returns {typeof ${modelNameCamelized}Base} */\n`
         fileContent += "  // @ts-ignore - override narrows return type for better IntelliSense in generated model bases\n"
         fileContent += `  getModelClass() { return /** @type {typeof ${modelNameCamelized}Base} */ (this.constructor) }\n\n`
       }
@@ -181,9 +177,7 @@ export default class DbGenerateModel extends BaseCommand {
         }
 
         if (jsdocType) {
-          fileContent += "  /**\n"
-          fileContent += `   * @returns {${jsdocType}${column.getNull() ? " | null" : ""}}\n`
-          fileContent += "   */\n"
+          fileContent += `  /** @returns {${jsdocType}${column.getNull() ? " | null" : ""}} */\n`
         }
 
         fileContent += `  ${camelizedColumnName}() { return this.readAttribute("${camelizedColumnName}") }\n\n`
@@ -199,9 +193,7 @@ export default class DbGenerateModel extends BaseCommand {
 
         fileContent += `  set${camelizedColumnNameBigFirst}(newValue) { return this._setColumnAttribute("${camelizedColumnName}", newValue) }\n\n`
 
-        fileContent += "  /**\n"
-        fileContent += "   * @returns {boolean}\n"
-        fileContent += "   */\n"
+        fileContent += "  /** @returns {boolean} */\n"
         fileContent += `  has${camelizedColumnNameBigFirst}() { return this._hasAttribute(this.${camelizedColumnName}()) }\n`
 
         methodsCount++

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.

package/src/frontend-models/query.js

@@ -5,28 +5,6 @@ import {normalizeRansackGroup, parseRansackSort} from "../utils/ransack.js"
 import {isModelScopeDescriptor} from "../utils/model-scope.js"
 import isPlainObject from "../utils/plain-object.js"
 
-/** Error raised when a frontend-model query descriptor is malformed. */
-export class FrontendModelQueryError extends Error {
-  /**
-   * Creates a frontend-model query error.
-   * @param {string} message - Error message.
-   */
-  constructor(message) {
-    super(message)
-
-    this.name = "FrontendModelQueryError"
-  }
-}
-
-/**
- * Builds a query descriptor error.
- * @param {string} message - Error message.
- * @returns {FrontendModelQueryError} - Query descriptor error.
- */
-function frontendModelQueryError(message) {
-  return new FrontendModelQueryError(message)
-}
-
 /**
  * FrontendModelSearch type.
  * @typedef {object} FrontendModelSearch
@@ -97,6 +75,46 @@ function frontendModelQueryError(message) {
  * @property {FrontendModelEventFilterPayload | null} eventFilterPayload - Normalized event filter payload, or null when unfiltered.
  * @property {FrontendModelProjectionPayload} projectionPayload - Normalized event serialization projection payload.
  */
+/**
+ * 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.
+ */
+/** Error raised when a frontend-model query descriptor is malformed. */
+export class FrontendModelQueryError extends Error {
+  /**
+   * Creates a frontend-model query error.
+   * @param {string} message - Error message.
+   */
+  constructor(message) {
+    super(message)
+
+    this.name = "FrontendModelQueryError"
+  }
+}
+
+/**
+ * Builds a query descriptor error.
+ * @param {string} message - Error message.
+ * @returns {FrontendModelQueryError} - Query descriptor error.
+ */
+function frontendModelQueryError(message) {
+  return new FrontendModelQueryError(message)
+}
 
 /**
  * Runs the normalizePreload helper.
@@ -490,28 +508,6 @@ export function normalizeJoins(joins) {
   return normalized
 }
 
-/**
- * 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.
- */
-
 /**
  * Runs normalize sort direction.
  * @param {?} direction - Direction value.

package/src/frontend-models/resource-definition.js

@@ -5,6 +5,13 @@ import FrontendModelBaseResource from "../frontend-model-resource/base-resource.
 import restArgsError from "../utils/rest-args-error.js"
 import {validateFrontendModelResourceCommandName} from "./resource-config-validation.js"
 
+/**
+ * Resolved frontend-model resource registration for a replay resource type.
+ * @typedef {object} FrontendModelResolvedResourceRegistration
+ * @property {string} modelName - Effective frontend model name (modelName override or registry key).
+ * @property {import("../configuration-types.js").FrontendModelResourceClassType} resourceClass - Registered resource class.
+ * @property {import("../configuration-types.js").NormalizedFrontendModelResourceConfiguration} resourceConfiguration - Normalized resource configuration.
+ */
 const BASE_FRONTEND_MODEL_ABILITY_ACTIONS = ["create", "destroy", "read", "update"]
 const SHA256_INITIAL_HASH = [
   0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a,
@@ -1027,14 +1034,6 @@ function normalizeFrontendModelResourcePathForMatch(path) {
   return withLeadingSlash
 }
 
-/**
- * Resolved frontend-model resource registration for a replay resource type.
- * @typedef {object} FrontendModelResolvedResourceRegistration
- * @property {string} modelName - Effective frontend model name (modelName override or registry key).
- * @property {import("../configuration-types.js").FrontendModelResourceClassType} resourceClass - Registered resource class.
- * @property {import("../configuration-types.js").NormalizedFrontendModelResourceConfiguration} resourceConfiguration - Normalized resource configuration.
- */
-
 /**
  * Resolves the registered frontend-model resource class for a resource type
  * across all backend projects. A resource's effective name is its

package/src/frontend-models/transport-serialization.js

@@ -4,28 +4,26 @@ import {resolveFrontendModelClass} from "./model-registry.js"
 import isPlainObject from "../utils/plain-object.js"
 import {formatDateInTimeZone, validateTimeZone} from "../time-zone.js"
 
-const TYPE_KEY = "__velocious_type"
-const TYPE_DATE = "date"
-const TYPE_UNDEFINED = "undefined"
-const TYPE_BIGINT = "bigint"
-const TYPE_NUMBER = "number"
-const TYPE_FRONTEND_MODEL = "frontend_model"
-const NUMBER_NAN = "NaN"
-const NUMBER_POSITIVE_INFINITY = "Infinity"
-const NUMBER_NEGATIVE_INFINITY = "-Infinity"
-const PRELOADED_RELATIONSHIPS_KEY = "__preloadedRelationships"
-
 /**
  * Frontend model transport serialization options.
  * @typedef {object} FrontendModelTransportSerializationOptions
  * @property {string | undefined} [timeZone] - IANA timezone used when serializing Date instants.
  */
-
 /**
  * Normalized frontend model transport serialization options.
  * @typedef {object} NormalizedFrontendModelTransportSerializationOptions
  * @property {string | undefined} timeZone - Validated IANA timezone used when serializing Date instants.
  */
+const TYPE_KEY = "__velocious_type"
+const TYPE_DATE = "date"
+const TYPE_UNDEFINED = "undefined"
+const TYPE_BIGINT = "bigint"
+const TYPE_NUMBER = "number"
+const TYPE_FRONTEND_MODEL = "frontend_model"
+const NUMBER_NAN = "NaN"
+const NUMBER_POSITIVE_INFINITY = "Infinity"
+const NUMBER_NEGATIVE_INFINITY = "-Infinity"
+const PRELOADED_RELATIONSHIPS_KEY = "__preloadedRelationships"
 
 /**
  * Assign a key to a plain object without triggering the `__proto__` setter.