velocious 1.0.451 → 1.0.453

package/README.md

@@ -447,6 +447,7 @@ Frontend-model `where(...)` supports nested relationship descriptors (for exampl
 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 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.
 
@@ -546,11 +547,14 @@ For frontend models, configure `resourceConfig().attachments` and use:
 await frontendTask.update({descriptionFile: file})
 const descriptionFile = await frontendTask.descriptionFile().download()
 const descriptionFileUrl = await frontendTask.descriptionFile().url()
+const descriptionFileMetadata = await frontendTask.descriptionFile().first()
+const filesMetadata = await frontendTask.files().toArray()
 await frontendTask.attach(file)
 ```
 
 Frontend model attachment input does not support `{path: ...}`.
 Use `File`/`Blob`/bytes/`contentBase64` payloads instead.
+Attachment metadata is exposed through the built-in `VelociousAttachment` frontend model with safe fields only: `id`, `recordType`, `recordId`, `name`, `position`, `filename`, `contentType`, `byteSize`, `createdAt`, and `updatedAt`. Storage internals such as `driver`, `storageKey`, and `contentBase64` remain hidden and non-queryable. Direct metadata queries require owner filters: `recordType`, `recordId`, and `name`.
 
 When your frontend app calls a backend on another host/port (or under a path prefix), configure transport once:
 
@@ -583,7 +587,7 @@ const configuration = new Configuration({
 
 This opt-in is ignored in `production`; production frontend-model responses never include internal exception details.
 
-Backends can append client-safe metadata to frontend-model error responses with `configuration.addClientErrorPayloadReporter(...)`. Reporters receive the caught `error`, the current `request`, and a small `context` object, and should only return fields that are safe for clients to see. This is useful for attaching an error-reporting URL while keeping the normal production error message generic:
+Backends can append client-safe metadata to frontend-model error responses with `configuration.addClientErrorPayloadReporter(...)`. Reporters receive the caught `error`, the current `request`, and a small `context` object, and should only return fields that are safe for clients to see. Frontend-model endpoint failures include `context.frontendModelEndpoint`, `action`, `commandType`, `model`, `requestId`, and `expectedError`. This is useful for attaching an error-reporting URL while keeping the normal production error message generic:
 
 ```js
 configuration.addClientErrorPayloadReporter(async ({error, request, context}) => {
@@ -1002,6 +1006,8 @@ npx velocious g:migration create-tasks
 ```
 
 ## Write a migration
+Implicit `id` primary keys and `references(...)` columns use UUIDs by default. Use an explicit numeric `id` or reference `type` only for legacy schemas or external compatibility.
+
 ```js
 import Migration from "velocious/build/src/database/migration/index.js"
 
@@ -1011,9 +1017,9 @@ export default class CreateEvents extends Migration {
       t.timestamps()
     })
 
-    // UUID primary key
-    await this.createTable("uuid_items", {id: {type: "uuid"}}, (t) => {
-      t.string("title", {null: false})
+    // Legacy numeric primary key
+    await this.createTable("legacy_events", {id: {type: "bigint"}}, (t) => {
+      t.references("task", {type: "bigint"})
       t.timestamps()
     })
 
@@ -1597,7 +1603,7 @@ configuration.getErrorEvents().on("all-error", ({error, errorType}) => {
 })
 ```
 
-Genuinely unexpected frontend-model command failures reach this bus too. The frontend-model controller catches them to return a client-safe `Request failed.` response, but it also emits them as `framework-error`/`all-error` (with `context.frontendModelEndpoint === true`) so they are reported instead of being silently swallowed. Expected user-flow errors are excluded: validation failures are forwarded with their real message (for example `Name can't be blank`) rather than the generic one, and `error.velocious`-annotated / `safeToExpose` errors keep their own message — none of these reach the error bus.
+Genuinely unexpected frontend-model command failures reach this bus too. The frontend-model controller catches them to return a client-safe `Request failed.` response, but it also emits them as `framework-error`/`all-error` (with `context.frontendModelEndpoint === true`) so they are reported instead of being silently swallowed. Expected user-flow errors are excluded: validation failures are forwarded with their real message (for example `Name can't be blank`) rather than the generic one, and `error.velocious`-annotated / `safeToExpose` / `errorType`-marked errors keep their expected-error status — none of these reach the error bus.
 
 ## Use the Websocket client API (HTTP-like)
 

package/build/configuration-types.js

@@ -207,6 +207,29 @@
  * @typedef {Record<string, string>} VelociousParams
  */
 
+/**
+ * @typedef {Record<string, import("./frontend-models/query.js").FrontendModelTransportValue>} ClientErrorPayloadReporterPayload
+ */
+
+/**
+ * @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 {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.
+ * @property {string} [requestId] - Shared frontend-model request id.
+ */
+
+/**
+ * @typedef {function({
+ *   context: ClientErrorPayloadContext,
+ *   error: Error,
+ *   request: import("./http-server/client/request.js").default | import("./http-server/client/websocket-request.js").default | undefined
+ * }): Promise<ClientErrorPayloadReporterPayload | void> | ClientErrorPayloadReporterPayload | void} ClientErrorPayloadReporterType
+ */
+
 /**
  * @typedef {Record<string, unknown> & {configuration?: import("./configuration.js").default, currentUser?: unknown, params?: VelociousParams, request?: import("./http-server/client/request.js").default | import("./http-server/client/websocket-request.js").default}} VelociousLooseObject
  */

package/build/configuration.js

@@ -143,7 +143,7 @@ export default class VelociousConfiguration {
     this._scheduledBackgroundJobs = scheduledBackgroundJobs
     this._attachments = attachments || {}
     this._backendProjects = backendProjects || []
-    /** @type {Array<(args: {context: ?, error: Error, request: ?}) => Promise<Record<string, ?> | void> | Record<string, ?> | void>} */
+    /** @type {import("./configuration-types.js").ClientErrorPayloadReporterType[]} */
     this._clientErrorPayloadReporters = []
     this.cors = cors
     this._cookieSecret = cookieSecret
@@ -2386,7 +2386,7 @@ export default class VelociousConfiguration {
 
   /**
    * Registers a reporter that can add client-safe metadata to frontend-model error payloads.
-   * @param {(args: {context: ?, error: Error, request: ?}) => Promise<Record<string, ?> | void> | Record<string, ?> | void} reporter - Reporter callback.
+   * @param {import("./configuration-types.js").ClientErrorPayloadReporterType} reporter - Reporter callback.
    * @returns {void}
    */
   addClientErrorPayloadReporter(reporter) {
@@ -2395,11 +2395,11 @@ export default class VelociousConfiguration {
 
   /**
    * Runs registered client error payload reporters.
-   * @param {{context: ?, error: Error, request: ?}} args - Reporter args.
-   * @returns {Promise<Record<string, ?>>} - Merged client-safe reporter payload.
+   * @param {{context: import("./configuration-types.js").ClientErrorPayloadContext, error: Error, request: import("./http-server/client/request.js").default | import("./http-server/client/websocket-request.js").default | undefined}} args - Reporter args.
+   * @returns {Promise<import("./configuration-types.js").ClientErrorPayloadReporterPayload>} - Merged client-safe reporter payload.
    */
   async clientErrorPayloadForError(args) {
-    /** @type {Record<string, ?>} */
+    /** @type {import("./configuration-types.js").ClientErrorPayloadReporterPayload} */
     const payload = {}
 
     for (const reporter of this._clientErrorPayloadReporters) {

package/build/database/drivers/mssql/index.js

@@ -203,7 +203,7 @@ export default class VelociousDatabaseDriversMssql extends Base{
    * Runs primary key type.
    * @returns {string} - The primary key type.
    */
-  primaryKeyType() { return "bigint" }
+  primaryKeyType() { return "uuid" }
 
   /**
    * Runs query actual.

package/build/database/drivers/mysql/index.js

@@ -211,7 +211,7 @@ export default class VelociousDatabaseDriversMysql extends Base{
    * Runs primary key type.
    * @returns {string} - The primary key type.
    */
-  primaryKeyType() { return "bigint" }
+  primaryKeyType() { return "uuid" }
 
   /**
    * Runs retryable database error.

package/build/database/drivers/pgsql/index.js

@@ -177,7 +177,7 @@ export default class VelociousDatabaseDriversPgsql extends Base{
   }
 
   getType() { return "pgsql" }
-  primaryKeyType() { return "bigint" }
+  primaryKeyType() { return "uuid" }
 
   /**
    * Runs query actual.

package/build/database/drivers/sqlite/base.js

@@ -269,7 +269,7 @@ export default class VelociousDatabaseDriversSqliteBase extends Base {
    * Runs primary key type.
    * @returns {string} - The type of the primary key for this driver.
    */
-  primaryKeyType() { return "integer" } // Because bigint on SQLite doesn't support auto increment
+  primaryKeyType() { return "uuid" }
 
   /**
    * Runs query to sql.

package/build/database/record/attachments/attachment-record.js

@@ -0,0 +1,121 @@
+// @ts-check
+
+import DatabaseRecord from "../index.js"
+import RecordAttachmentsStore from "./store.js"
+
+const INTEGER_STRING_PATTERN = /^-?\d+$/
+
+/** Frontend-readable metadata row for `velocious_attachments`. */
+export default class VelociousAttachment extends DatabaseRecord {
+  /**
+   * Returns the backing attachment table name.
+   * @returns {string} - Backing attachment table name.
+   */
+  static tableName() {
+    return "velocious_attachments"
+  }
+
+  /**
+   * Ensures the framework-owned attachment table exists before loading metadata.
+   * @param {object} args - Options object.
+   * @param {import("../../../configuration.js").default} args.configuration - Configuration instance.
+   * @returns {Promise<void>} - Resolves when complete.
+   */
+  static async initializeRecord({configuration}) {
+    const store = new RecordAttachmentsStore({
+      configuration,
+      databaseIdentifier: this.getConfiguredDatabaseIdentifier()
+    })
+
+    await store.ensureReady()
+    await super.initializeRecord({configuration})
+  }
+
+  /**
+   * Returns the attachment id.
+   * @returns {string} - Attachment id.
+   */
+  id() { return this.readAttribute("id") }
+
+  /**
+   * Returns the owner model name.
+   * @returns {string} - Owner model name.
+   */
+  recordType() { return this.readAttribute("recordType") }
+
+  /**
+   * Returns the owner record id.
+   * @returns {string} - Owner record id.
+   */
+  recordId() { return this.readAttribute("recordId") }
+
+  /**
+   * Returns the attachment name on the owner model.
+   * @returns {string} - Attachment name on the owner model.
+   */
+  name() { return this.readAttribute("name") }
+
+  /**
+   * Returns the attachment position.
+   * @returns {number} - Attachment position.
+   */
+  position() { return this.readAttribute("position") }
+
+  /**
+   * Returns the attachment filename.
+   * @returns {string} - Attachment filename.
+   */
+  filename() { return this.readAttribute("filename") }
+
+  /**
+   * Returns the attachment content type.
+   * @returns {string | null} - Attachment content type.
+   */
+  contentType() { return this.readAttribute("contentType") }
+
+  /**
+   * Returns the attachment byte size.
+   * @returns {number} - Attachment byte size.
+   */
+  byteSize() { return this.safeIntegerAttribute({attributeName: "byteSize", expectedDescription: "attachment byte size"}) }
+
+  /**
+   * Returns the created-at timestamp in milliseconds.
+   * @returns {number} - Created-at timestamp in milliseconds.
+   */
+  createdAtMs() { return this.safeIntegerAttribute({attributeName: "createdAtMs", expectedDescription: "safe millisecond timestamp"}) }
+
+  /**
+   * Returns the updated-at timestamp in milliseconds.
+   * @returns {number} - Updated-at timestamp in milliseconds.
+   */
+  updatedAtMs() { return this.safeIntegerAttribute({attributeName: "updatedAtMs", expectedDescription: "safe millisecond timestamp"}) }
+
+  /**
+   * Returns a checked integer attribute value.
+   * @param {object} args - Options object.
+   * @param {"byteSize" | "createdAtMs" | "updatedAtMs"} args.attributeName - Integer attribute name.
+   * @param {string} args.expectedDescription - Description for error messages.
+   * @returns {number} - Safe integer value.
+   */
+  safeIntegerAttribute({attributeName, expectedDescription}) {
+    const value = this.readAttribute(attributeName)
+    let integer
+
+    if (typeof value === "number") {
+      integer = value
+    } else if (typeof value === "bigint") {
+      integer = Number(value)
+    } else if (typeof value === "string" && INTEGER_STRING_PATTERN.test(value)) {
+      integer = Number(value)
+    } else {
+      throw new Error(`Expected ${attributeName} to be a ${expectedDescription}`)
+    }
+
+    if (!Number.isSafeInteger(integer)) {
+      throw new Error(`Expected ${attributeName} to be a ${expectedDescription}`)
+    }
+
+    return integer
+  }
+}

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

@@ -98,6 +98,8 @@ export default class RecordAttachmentsStore {
 
     this._readyPromise = (async () => {
       await this._withDb(async (db) => {
+        db.clearSchemaCache()
+
         if (await db.tableExists(ATTACHMENTS_TABLE)) {
           await this.ensureAttachmentStoreSchema({db})
           return

package/build/database/table-data/index.js

@@ -188,7 +188,7 @@ export default class TableData {
     const referenceArgs = args || {}
     const reference = new TableReference(name, referenceArgs)
     const {index, polymorphic, ...restArgs} = referenceArgs
-    const columnArgs = Object.assign({isNewColumn: true, type: "bigint"}, restArgs)
+    const columnArgs = Object.assign({isNewColumn: true, type: "uuid"}, restArgs)
     const column = new TableColumn(columnName, columnArgs)
     const indexArgs = typeof index == "object" ? {unique: index.unique === true} : undefined
     const tableIndex = new TableIndex([column], indexArgs)

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

@@ -2,7 +2,8 @@ import BaseCommand from "../../../../../cli/base-command.js"
 import fs from "fs/promises"
 import path from "node:path"
 import * as inflection from "inflection"
-import {frontendModelResourceClassFromDefinition, frontendModelResourceConfigurationFromDefinition, frontendModelResourcesForBackendProject} from "../../../../../frontend-models/resource-definition.js"
+import {frontendModelResourceIsBuiltIn, frontendModelResourcesWithBuiltInsForBackendProject} from "../../../../../frontend-models/built-in-resources.js"
+import {frontendModelResourceClassFromDefinition, frontendModelResourceConfigurationFromDefinition} from "../../../../../frontend-models/resource-definition.js"
 
 /**
  * Attribute metadata used for generated frontend-model JSDoc.
@@ -110,6 +111,10 @@ export default class DbGenerateFrontendModels extends BaseCommand {
         this.validateModelConfig({availableFrontendModelClassNames, className, modelConfig, resourceClass})
 
         if (generatedModelNames.has(className)) {
+          if (frontendModelResourceIsBuiltIn({modelName: modelClassName, resourceDefinition: resources[modelClassName]})) {
+            continue
+          }
+
           throw new Error(`Duplicate frontend model definition for '${className}'`)
         }
 
@@ -191,7 +196,7 @@ export default class DbGenerateFrontendModels extends BaseCommand {
    * @returns {Record<string, import("../../../../../configuration-types.js").FrontendModelResourceDefinition>} - Resource definitions keyed by model class name.
    */
   resourcesForBackendProject(backendProject) {
-    return frontendModelResourcesForBackendProject(backendProject)
+    return frontendModelResourcesWithBuiltInsForBackendProject(backendProject)
   }
 
   /**