velocious 1.0.454 → 1.0.456

package/README.md

@@ -376,6 +376,7 @@ export default new Configuration({
 ```
 
 `frontendModels` entries must be `FrontendModelBaseResource` subclasses. Built-in CRUD/find/index/serialize behavior lives in the base class, and app resources override only the pieces they actually need.
+Resource-level index customization should prefer `indexQuery()` or the pagination/search/sort hooks over replacing `records()`, so built-in pluck and aggregate count support can keep using the same query. See [`docs/frontend-model-resources.md`](docs/frontend-model-resources.md) for the resource extension points.
 
 Resources expose the full CRUD ability set (`create`, `destroy`, `read`, `update`) by default. To restrict the API surface — for example to a read-only resource — declare an explicit subset:
 
@@ -446,7 +447,7 @@ Frontend-model `group(...)` is attribute/path based and does not accept raw SQL
 Frontend-model `where(...)` supports nested relationship descriptors (for example `Task.where({project: {creatingUser: {reference: "owner-b"}}})`) and does not accept raw SQL fragments.
 Frontend-model `joins(...)` supports relationship-object descriptors only (for example `Task.joins({project: {creatingUser: true}})`) and rejects raw SQL join strings.
 Frontend-model `distinct(...)` only accepts booleans (`true` by default) and is applied server-side through the backend query API.
-Frontend-model `pluck(...)` validates attribute/path descriptors against configured model metadata and does not accept SQL fragments.
+Frontend-model `pluck(...)` validates attribute/path descriptors against configured resource/model metadata and does not accept SQL fragments or hidden raw model columns when the resource declares an explicit attribute list.
 Frontend-model query fields are limited to attributes exposed by the backend resource. Use `{name: "attributeName", selectedByDefault: false}` for fields that may be selected or filtered explicitly but should stay out of default payloads.
 
 When backend payloads include `__preloadedRelationships`, nested frontend-model relationships are hydrated recursively. Relationship methods can use `getRelationshipByName("relationship").loaded()` and will throw when a relationship was not preloaded.

package/build/authorization/ability.js

@@ -72,7 +72,7 @@ export default class VelociousAuthorizationAbility {
   _resolveResourcesFromConfiguration() {
     const configuration = this.context?.configuration
 
-    if (!configuration || typeof configuration.getBackendProjects !== "function") {
+    if (!configuration) {
       return []
     }
 
@@ -85,12 +85,10 @@ export default class VelociousAuthorizationAbility {
     for (const backendProject of backendProjects) {
       const frontendModels = backendProject.frontendModels
 
-      if (!frontendModels || typeof frontendModels !== "object") continue
+      if (!frontendModels) continue
 
       for (const resourceDefinition of Object.values(frontendModels)) {
-        if (typeof resourceDefinition === "function" && typeof resourceDefinition.modelClass === "function") {
-          resolved.push(resourceDefinition)
-        }
+        resolved.push(resourceDefinition)
       }
     }
 
@@ -173,7 +171,6 @@ export default class VelociousAuthorizationAbility {
     for (const ResourceClass of this.resources) {
       const resourceModelClass = ResourceClass.modelClass()
 
-      if (!resourceModelClass) continue
       if (resourceModelClass !== modelClass) continue
 
       const resourceInstance = new ResourceClass({

package/build/authorization/base-resource.js

@@ -22,9 +22,13 @@ export default class AuthorizationBaseResource {
 
   /**
    * Runs model class.
-   * @returns {typeof import("../database/record/index.js").default | undefined} - Model class handled by this resource.
+   * @returns {typeof import("../database/record/index.js").default} - Model class handled by this resource.
    */
   static modelClass() {
+    if (!this.ModelClass) {
+      throw new Error(`${this.name} must define static ModelClass before calling ability helpers.`)
+    }
+
     return this.ModelClass
   }
 
@@ -69,15 +73,9 @@ export default class AuthorizationBaseResource {
    * @returns {typeof import("../database/record/index.js").default} - Model class handled by this resource.
    */
   requiredModelClass() {
-    const modelClass = /**
-                        * Narrows the runtime value to the documented type.
-                        * @type {typeof AuthorizationBaseResource} */ (this.constructor).modelClass()
-
-    if (!modelClass) {
-      throw new Error(`${this.constructor.name} must define static ModelClass before calling ability helpers.`)
-    }
+    const ResourceClass = /** @type {typeof AuthorizationBaseResource} */ (this.constructor)
 
-    return modelClass
+    return ResourceClass.modelClass()
   }
 
   /**

package/build/configuration-types.js

@@ -216,7 +216,7 @@
  * @typedef {object} ClientErrorPayloadContext
  * @property {string} controller - Controller class name.
  * @property {string} [action] - Controller action or endpoint label.
- * @property {"index" | "find" | "create" | "update" | "destroy" | "attach" | "download" | "url" | "custom-command"} [commandType] - Frontend-model command type.
+ * @property {"index" | "find" | "create" | "update" | "destroy" | "attach" | "attachmentList" | "download" | "url" | "custom-command"} [commandType] - Frontend-model command type.
  * @property {boolean} [expectedError] - Whether the error is an expected user-flow failure.
  * @property {boolean} [frontendModelEndpoint] - Whether the error came from the frontend-model endpoint.
  * @property {string} [model] - Frontend-model name from the failed request.
@@ -342,10 +342,10 @@
 
 /**
  * @typedef {object} FrontendModelResourceServerConfiguration
- * @property {function({action: "index" | "find" | "create" | "update" | "destroy" | "attach" | "download" | "url", controller: import("./controller.js").default, params: Record<string, ?>, modelClass: typeof import("./database/record/index.js").default}) : (boolean | void | Promise<boolean | void>)} [beforeAction] - Optional callback run before built-in frontend actions.
+ * @property {function({action: "index" | "find" | "create" | "update" | "destroy" | "attach" | "attachmentList" | "download" | "url", controller: import("./controller.js").default, params: Record<string, ?>, modelClass: typeof import("./database/record/index.js").default}) : (boolean | void | Promise<boolean | void>)} [beforeAction] - Optional callback run before built-in frontend actions.
  * @property {function({action: "index", controller: import("./controller.js").default, params: Record<string, ?>, modelClass: typeof import("./database/record/index.js").default}) : Promise<import("./database/record/index.js").default[]>} [records] - Records loader for frontendIndex.
  * @property {function({action: "index" | "find" | "create" | "update", controller: import("./controller.js").default, params: Record<string, ?>, modelClass: typeof import("./database/record/index.js").default, model: import("./database/record/index.js").default}) : Record<string, ?> | Promise<Record<string, ?>>} [serialize] - Record serializer for response payloads.
- * @property {function({action: "find" | "update" | "destroy" | "attach" | "download" | "url", controller: import("./controller.js").default, params: Record<string, ?>, modelClass: typeof import("./database/record/index.js").default, id: string | number}) : Promise<import("./database/record/index.js").default | null>} [find] - Record loader for find/update/destroy/attach/download/url actions.
+ * @property {function({action: "find" | "update" | "destroy" | "attach" | "attachmentList" | "download" | "url", controller: import("./controller.js").default, params: Record<string, ?>, modelClass: typeof import("./database/record/index.js").default, id: string | number}) : Promise<import("./database/record/index.js").default | null>} [find] - Record loader for find/update/destroy/attach/download/url actions.
  * @property {function({action: "create", controller: import("./controller.js").default, params: Record<string, ?>, modelClass: typeof import("./database/record/index.js").default, attributes: Record<string, ?>}) : Promise<import("./database/record/index.js").default>} [create] - Custom create callback.
  * @property {function({action: "update", controller: import("./controller.js").default, params: Record<string, ?>, modelClass: typeof import("./database/record/index.js").default, model: import("./database/record/index.js").default, attributes: Record<string, ?>}) : Promise<import("./database/record/index.js").default | void>} [update] - Custom update callback.
  * @property {function({action: "destroy", controller: import("./controller.js").default, params: Record<string, ?>, modelClass: typeof import("./database/record/index.js").default, model: import("./database/record/index.js").default}) : Promise<void>} [destroy] - Custom destroy callback.

package/build/configuration.js

@@ -18,7 +18,7 @@ import Ability from "./authorization/ability.js"
 import EventEmitter from "./utils/event-emitter.js"
 import VelociousWebsocketChannelSubscribers from "./http-server/websocket-channel-subscribers.js"
 import {CurrentConfigurationNotSetError, currentConfiguration, setCurrentConfiguration} from "./current-configuration.js"
-import {frontendModelResourceConfigurationFromDefinition, frontendModelResourcesForBackendProject} from "./frontend-models/resource-definition.js"
+import {frontendModelResourceClassFromDefinition, frontendModelResourceConfigurationFromDefinition, frontendModelResourcesForBackendProject} from "./frontend-models/resource-definition.js"
 import PluginRoutes from "./routes/plugin-routes.js"
 import restArgsError from "./utils/rest-args-error.js"
 import {withTrackedStack} from "./utils/with-tracked-stack.js"
@@ -1673,12 +1673,13 @@ export default class VelociousConfiguration {
           throw new Error(`Resource for ${modelName} defines relationships as an object. Use an array instead: static relationships = ${JSON.stringify(Object.keys(resourceConfig.relationships))}`)
         }
 
-        const modelClass = /**
-                            * Types the following value.
-                            * @type {typeof import("./database/record/index.js").default | undefined} */ (this.modelClasses[modelName])
+        const resourceClass = frontendModelResourceClassFromDefinition(resourceDefinition)
 
-        if (!modelClass) continue
+        if (!resourceClass) {
+          throw new Error(`Frontend model resource for ${modelName} must be a FrontendModelBaseResource subclass.`)
+        }
 
+        const modelClass = resourceClass.modelClass()
         const existingRelationships = modelClass.getRelationshipsMap()
 
         for (const relationshipName of resourceConfig.relationships) {
@@ -2567,27 +2568,21 @@ export default class VelociousConfiguration {
       return
     }
 
+    /** @type {Set<typeof import("./database/pool/base.js").default>} */
     const constructors = new Set()
 
     this._closeDatabaseConnectionsPromise = (async () => {
       for (const pool of Object.values(this.databasePools)) {
         if (!pool) continue
 
-        if (typeof pool.closeAll === "function") {
-          await pool.closeAll()
-        }
-
-        const poolConstructor = /**
-                                 * Types the following value.
-                                 * @type {{clearGlobalConnections?: (configuration: VelociousConfiguration) => void}} */ (pool.constructor)
+        await pool.closeAll()
 
-        if (typeof poolConstructor?.clearGlobalConnections === "function") {
-          constructors.add(poolConstructor)
-        }
+        const PoolClass = /** @type {typeof import("./database/pool/base.js").default} */ (pool.constructor)
+        constructors.add(PoolClass)
       }
 
-      for (const constructor of constructors) {
-        constructor.clearGlobalConnections?.(this)
+      for (const PoolClass of constructors) {
+        PoolClass.clearGlobalConnections(this)
       }
 
       // Allow models to be re-initialized after connections are closed.

package/build/database/drivers/base.js

@@ -1178,7 +1178,7 @@ export default class VelociousDatabaseDriversBase {
    * @returns {boolean} - Whether query logging is enabled for this driver.
    */
   _queryLoggingEnabled() {
-    if (typeof this.configuration?.getQueryLoggingEnabled !== "function") return true
+    if (!this.configuration) return true
     if (!this.configuration.getQueryLoggingEnabled()) return false
 
     const logger = new Logger("SQL", {configuration: this.configuration})
@@ -1213,9 +1213,9 @@ export default class VelociousDatabaseDriversBase {
   _querySourceLine(sourceStack) {
     if (!sourceStack) return undefined
 
-    const applicationDirectory = typeof this.configuration?.getDirectoryIfAvailable === "function"
+    const applicationDirectory = this.configuration
       ? this.configuration.getDirectoryIfAvailable()
-      : this.configuration?.getDirectory?.()
+      : undefined
 
     if (!applicationDirectory) return undefined
 

package/build/database/pool/base.js

@@ -90,9 +90,10 @@ class VelociousDatabasePoolBase {
 
   /**
    * Clears any global connections for the given configuration.
+   * @param {import("../../configuration.js").default} configuration - Configuration owning the pool.
    * @returns {void} - No return value.
    */
-  static clearGlobalConnections() {}
+  static clearGlobalConnections(configuration) { void configuration }
 
   /**
    * Runs constructor.

package/build/database/query/preloader/ensure-model-class-initialized.js

@@ -9,10 +9,5 @@
 export default async function ensureModelClassInitialized(modelClass, configuration) {
   if (modelClass.isInitialized()) return
 
-  if (typeof modelClass.ensureInitialized === "function") {
-    await modelClass.ensureInitialized({configuration})
-    return
-  }
-
-  await modelClass.initializeRecord({configuration})
+  await modelClass.ensureInitialized({configuration})
 }

package/build/database/record/attachments/handle.js

@@ -170,6 +170,38 @@ export default class RecordAttachmentHandle {
     return downloads
   }
 
+  /**
+   * Runs list metadata. Returns metadata (no content bytes) for every attachment
+   * under this (record, name), so callers can enumerate has-many attachments
+   * without downloading their content.
+   * @returns {Promise<Array<{byteSize: number, contentType: string | null, filename: string, id: string, url: string | null}>>} - Attachment metadata entries.
+   */
+  async listMetadata() {
+    if (!this.model.isPersisted()) return []
+
+    const store = recordAttachmentsStoreForModel(this.model)
+    const rows = await store.findMany({model: this.model, name: this.name})
+    /**
+     * Metadata entries.
+     * @type {Array<{byteSize: number, contentType: string | null, filename: string, id: string, url: string | null}>} */
+    const entries = []
+
+    for (const row of rows) {
+      const url = await store.attachmentRowUrl({model: this.model, name: this.name, row})
+      const byteSize = Number(row.byte_size)
+
+      entries.push({
+        byteSize: Number.isFinite(byteSize) ? byteSize : 0,
+        contentType: row.content_type || null,
+        filename: row.filename || "attachment.bin",
+        id: row.id,
+        url
+      })
+    }
+
+    return entries
+  }
+
   /**
    * Runs url.
    * @param {string} [id] - Optional attachment id for has-many attachments.

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

@@ -106,7 +106,13 @@ export default class DbGenerateFrontendModels extends BaseCommand {
           throw new Error(`Invalid frontend model resource definition for '${className}'`)
         }
 
-        const resourceClass = frontendModelResourceClassFromDefinition(resources[modelClassName])
+        const resolvedResourceClass = frontendModelResourceClassFromDefinition(resources[modelClassName])
+        // An abstract base resource (no static ModelClass — e.g. an app's shared
+        // `BaseResource` that other resources extend) can't back a generated
+        // frontend model. Treat it as resource-less so the generator falls back
+        // to by-name model lookup + empty write params instead of throwing when
+        // it eagerly calls `modelClass()` / `permittedParams()` on it.
+        const resourceClass = resolvedResourceClass && resolvedResourceClass.ModelClass ? resolvedResourceClass : null
 
         this.validateModelConfig({availableFrontendModelClassNames, className, modelConfig, resourceClass})
 
@@ -123,7 +129,7 @@ export default class DbGenerateFrontendModels extends BaseCommand {
         const fileContent = await this.buildModelFileContent({
           className,
           importPath,
-          modelClass: resourceClass?.ModelClass || configuration.getModelClasses()[className],
+          modelClass: resourceClass ? resourceClass.modelClass() : configuration.getModelClasses()[className],
           modelConfig,
           resourceClass
         })
@@ -817,22 +823,17 @@ export default class DbGenerateFrontendModels extends BaseCommand {
    * @returns {FrontendModelGeneratorPermitSpec} - Permitted params spec.
    */
   permittedParamsForGenerator(resourceClass, action) {
-    if (!resourceClass || typeof resourceClass !== "function") return []
-
-    const prototypeWithMethod = /**
-                                 * Resource prototype.
-                                 * @type {{permittedParams?: (arg?: object) => FrontendModelGeneratorPermitSpec}}
-                                 */ (resourceClass.prototype)
-
-    if (typeof prototypeWithMethod?.permittedParams !== "function") return []
+    if (!resourceClass) return []
 
     try {
+      const modelClass = resourceClass.modelClass()
+
       const instance = new resourceClass({
         ability: undefined,
         context: {},
         locals: {},
-        modelClass: resourceClass.ModelClass,
-        modelName: resourceClass.ModelClass?.getModelName?.() || resourceClass.name,
+        modelClass,
+        modelName: modelClass.getModelName(),
         params: {},
         resourceConfiguration: /**
                                 * Resource configuration.
@@ -860,24 +861,19 @@ export default class DbGenerateFrontendModels extends BaseCommand {
    * @returns {string[]} - Relationship names that accept nested writes (empty when none).
    */
   nestedRelationshipNamesForGenerator(resourceClass) {
-    if (!resourceClass || typeof resourceClass !== "function") return []
-
-    const prototypeWithMethod = /**
-                                 * Resource prototype.
-                                 * @type {{permittedParams?: (arg?: object) => FrontendModelGeneratorPermitSpec}}
-                                 */ (resourceClass.prototype)
-
-    if (typeof prototypeWithMethod?.permittedParams !== "function") return []
+    if (!resourceClass) return []
 
     let spec
 
     try {
+      const modelClass = resourceClass.modelClass()
+
       const instance = new resourceClass({
         ability: undefined,
         context: {},
         locals: {},
-        modelClass: resourceClass.ModelClass,
-        modelName: resourceClass.ModelClass?.getModelName?.() || resourceClass.name,
+        modelClass,
+        modelName: modelClass.getModelName(),
         params: {},
         resourceConfiguration: /**
                                 * Resource configuration.
@@ -1073,6 +1069,7 @@ export default class DbGenerateFrontendModels extends BaseCommand {
    */
   frontendAttributeConfigForGeneratedAttribute({attributeConfig, attributeName, modelClass}) {
     if (!this.frontendAttributeIsModelPrimaryKey({attributeName, modelClass})) return attributeConfig
+    if (this.frontendAttributeConfigHasNullability(attributeConfig)) return attributeConfig
 
     return {...attributeConfig, null: false}
   }
@@ -1141,6 +1138,18 @@ export default class DbGenerateFrontendModels extends BaseCommand {
       || typeof attributeConfig?.jsDocType == "string"
   }
 
+  /**
+   * Runs frontend attribute config has nullability.
+   * @param {FrontendAttributeConfig | null | undefined} attributeConfig - Attribute config.
+   * @returns {boolean} - Whether the config declares nullability.
+   */
+  frontendAttributeConfigHasNullability(attributeConfig) {
+    if (!attributeConfig || typeof attributeConfig !== "object") return false
+    if (Object.prototype.hasOwnProperty.call(attributeConfig, "null")) return true
+
+    return typeof attributeConfig.getNull == "function"
+  }
+
   /**
    * Runs js doc type for frontend attribute.
    * @param {object} args - Arguments.
@@ -1513,7 +1522,12 @@ export default class DbGenerateFrontendModels extends BaseCommand {
       const classBodyEnd = this.matchingBraceIndex({openIndex: classBodyStart - 1, sourceText})
 
       if (classBodyEnd == null) {
-        throw new Error(`Could not find closing brace for resource class '${className}' while reading frontend attribute JSDoc`)
+        // The brace matcher can't tokenize every construct (e.g. a regex literal
+        // whose quotes look like string delimiters), so it can fail to locate a
+        // class body. Skip metadata extraction for that class rather than
+        // aborting the whole frontend-model generation; resources that parse
+        // cleanly still get their JSDoc-derived return/param types.
+        continue
       }
 
       const classBody = sourceText.slice(classBodyStart, classBodyEnd)
@@ -1554,7 +1568,12 @@ export default class DbGenerateFrontendModels extends BaseCommand {
       const classBodyEnd = this.matchingBraceIndex({openIndex: classBodyStart - 1, sourceText})
 
       if (classBodyEnd == null) {
-        throw new Error(`Could not find closing brace for resource class '${className}' while reading frontend attribute JSDoc`)
+        // The brace matcher can't tokenize every construct (e.g. a regex literal
+        // whose quotes look like string delimiters), so it can fail to locate a
+        // class body. Skip metadata extraction for that class rather than
+        // aborting the whole frontend-model generation; resources that parse
+        // cleanly still get their JSDoc-derived return/param types.
+        continue
       }
 
       const classBody = sourceText.slice(classBodyStart, classBodyEnd)
@@ -1832,11 +1851,7 @@ export default class DbGenerateFrontendModels extends BaseCommand {
    * @returns {{autoload: boolean, relationshipName: string, targetClassName: string, targetFileName: string, type: "belongsTo" | "hasOne" | "hasMany"}} Inferred relationship definition.
    */
   inferredRelationshipDefinition({className, relationshipName, resourceClass}) {
-    const modelClass = resourceClass?.ModelClass || this.getConfiguration().getModelClass(className)
-
-    if (!modelClass) {
-      throw new Error(`Could not find backend model class '${className}' for relationship '${relationshipName}'`)
-    }
+    const modelClass = resourceClass ? resourceClass.modelClass() : this.getConfiguration().getModelClass(className)
 
     const relationship = modelClass.getRelationshipByName(relationshipName)
     const relationshipType = relationship.getType()