velocious 1.0.452 → 1.0.454

package/README.md

@@ -5,7 +5,7 @@
 * Database models with migrations and validations
 * Database models that work almost the same in frontend and backend
 * Declarative state machines for models (see [docs/state-machine.md](docs/state-machine.md))
-* Migrations for schema changes
+* Migrations for schema changes (see [docs/database-migrations.md](docs/database-migrations.md))
 * Controllers and views for HTTP endpoints
 * Frontend-model transport for creating, updating, querying, and subscribing to query-filtered lifecycle events over HTTP/WebSocket, with structured per-attribute validation error responses (see [docs/frontend-models.md](docs/frontend-models.md))
 * Expo / Metro compatibility guidance and a real Expo export check (see [docs/expo-metro-compatibility.md](docs/expo-metro-compatibility.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:
 
@@ -1002,6 +1006,21 @@ npx velocious g:migration create-tasks
 ```
 
 ## Write a migration
+Implicit `id` primary keys and `references(...)` columns use UUIDs by default. Set `primaryKeyType` on a database config to change the implicit type for that database, or pass an explicit `id` / reference `type` for legacy schemas and external compatibility.
+
+```js
+export default new Configuration({
+  database: {
+    production: {
+      default: {
+        type: "pgsql",
+        primaryKeyType: "bigint"
+      }
+    }
+  }
+})
+```
+
 ```js
 import Migration from "velocious/build/src/database/migration/index.js"
 
@@ -1011,9 +1030,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()
     })
 

package/build/configuration-types.js

@@ -71,6 +71,7 @@
  * @property {boolean} [migrations] - Whether migrations are enabled for this database.
  * @property {string} [password] - Password for the database user.
  * @property {number} [port] - Database port.
+ * @property {string} [primaryKeyType] - Default type for implicit migration primary keys and references. Defaults to `uuid`.
  * @property {DatabasePoolConfiguration} [pool] - Velocious database pool lifecycle configuration.
  * @property {string} [name] - Friendly name for the configuration.
  * @property {(file: string) => string} [locateFile] - Optional sqlite-web sql.js wasm resolver (`initSqlJs({locateFile})`).

package/build/database/drivers/base.js

@@ -406,6 +406,14 @@ export default class VelociousDatabaseDriversBase {
     return this.idSeq
   }
 
+  /**
+   * Runs primary key type.
+   * @returns {string} - Configured primary key type, defaulting to UUID.
+   */
+  primaryKeyType() {
+    return this.getArgs().primaryKeyType || "uuid"
+  }
+
   /**
    * Clears cached schema metadata for this driver instance.
    * @returns {void} - No return value.

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

@@ -199,12 +199,6 @@ export default class VelociousDatabaseDriversMssql extends Base{
    */
   getType() { return "mssql" }
 
-  /**
-   * Runs primary key type.
-   * @returns {string} - The primary key type.
-   */
-  primaryKeyType() { return "bigint" }
-
   /**
    * Runs query actual.
    * @param {string} sql - SQL string.

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

@@ -207,12 +207,6 @@ export default class VelociousDatabaseDriversMysql extends Base{
    */
   getType() { return "mysql" }
 
-  /**
-   * Runs primary key type.
-   * @returns {string} - The primary key type.
-   */
-  primaryKeyType() { return "bigint" }
-
   /**
    * Runs retryable database error.
    * @param {Error} error - Error instance.

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

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

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

@@ -265,12 +265,6 @@ export default class VelociousDatabaseDriversSqliteBase extends Base {
     return this._options
   }
 
-  /**
-   * 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
-
   /**
    * Runs query to sql.
    * @param {import("../../query/index.js").default} query - Query instance.

package/build/database/migration/index.js

@@ -351,8 +351,8 @@ export default class VelociousDatabaseMigration {
     }
 
     const {id = {}, ifNotExists = false, ...restArgs} = args
-    const databaseIdentifier = this._getDatabaseIdentifier()
-    const databasePool = this.configuration.getDatabasePool(databaseIdentifier)
+    const driver = this.getDriver()
+    const defaultPrimaryKeyType = driver.primaryKeyType()
     let idDefault, idType, restArgsId
 
     if (id !== false) {
@@ -362,9 +362,9 @@ export default class VelociousDatabaseMigration {
     }
 
     if (!idType) {
-      idType = databasePool.primaryKeyType()
+      idType = defaultPrimaryKeyType
     }
-    const driverSupportsDefaultUUID = this.getDriver().supportsDefaultPrimaryKeyUUID?.()
+    const driverSupportsDefaultUUID = driver.supportsDefaultPrimaryKeyUUID?.()
     const lowerIdType = idType?.toLowerCase()
     const isUUIDPrimaryKey = lowerIdType == "uuid"
     const numericAutoIncrementTypes = ["int", "integer", "bigint", "smallint", "tinyint"]
@@ -384,7 +384,7 @@ export default class VelociousDatabaseMigration {
       // If driver doesn't support UUID() but the caller explicitly set a default, respect it.
     }
 
-    const tableData = new TableData(tableName, {ifNotExists})
+    const tableData = new TableData(tableName, {ifNotExists, primaryKeyType: defaultPrimaryKeyType})
 
     restArgsError(restArgs)
 
@@ -398,7 +398,7 @@ export default class VelociousDatabaseMigration {
       callback(tableData)
     }
 
-    const sqls = await this.getDriver().createTableSql(tableData)
+    const sqls = await driver.createTableSql(tableData)
 
     for (const sql of sqls) {
       await this._db.query(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

@@ -8,6 +8,7 @@ import TableReference from "./table-reference.js"
  * TableDataArgsType type.
  * @typedef {object} TableDataArgsType
  * @property {boolean} ifNotExists - Whether to create the table only if it does not exist.
+ * @property {string} [primaryKeyType] - Default type for implicit primary-key references.
  */
 
 export default class TableData {
@@ -188,7 +189,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: this.args?.primaryKeyType || "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/database/table-data/table-column.js

@@ -326,7 +326,13 @@ export default class TableColumn {
     }
 
     if (databaseType == "pgsql" && this.getAutoIncrement() && this.getPrimaryKey()) {
-      type = "SERIAL"
+      if (type == "BIGINT") {
+        type = "BIGSERIAL"
+      } else if (type == "SMALLINT") {
+        type = "SMALLSERIAL"
+      } else {
+        type = "SERIAL"
+      }
     }
 
     let sql = `${options.quoteColumnName(this.getActualName())} `

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)
   }
 
   /**