velocious 1.0.475 → 1.0.477

package/README.md

@@ -723,6 +723,8 @@ Task.validates("name", {presence: true, uniqueness: true})
 export default Task
 ```
 
+Generated belongs-to setters synchronize the loaded relationship and foreign key before save, so `task.setProject(project)` updates `task.projectId()`, `task.changes()`, callbacks, and scoped features such as `actsAsList`. Custom relationship primary keys are also used after autosaving an assigned new or dirty related record. Generated backend write attributes accept belongs-to relationship names for `create` and `update` payloads. See [docs/relationships.md](docs/relationships.md#assigning-belongs-to-relationships).
+
 Translated models also get a `currentTranslation` `hasOne` relationship scoped to the first available row in the current locale fallback order. See [docs/translations.md](docs/translations.md) for preloading and frontend-model sorting behavior.
 
 Async class APIs initialize record metadata on first use when a model has not
@@ -1076,6 +1078,7 @@ export default class CreateEvents extends Migration {
   }
 
   async down() {
+    await this.removeIndex("task_translations", ["task_id", "locale"])
     await this.dropTable("task_translations")
     await this.dropTable("examples")
     await this.dropTable("tasks")

package/build/configuration-types.js

@@ -348,6 +348,7 @@
  * frontends and peers; `policy` is hashed but intentionally omitted from
  * frontend-safe manifests.
  * @typedef {object} FrontendModelResourceSyncConfiguration
+ * @property {"optimisticVersion" | "serverWins" | "lastWriterWins" | "fieldThreeWay" | "appendOnly"} [conflictStrategy] - Strategy used when replay detects server/client divergence. Defaults to `optimisticVersion`.
  * @property {boolean} [enabled] - Whether the resource is sync-enabled. Defaults to true when `sync` is configured.
  * @property {string[]} [operations] - Sync operation names such as `index`, `find`, `create`, `update`, custom domain commands, etc.
  * @property {string | number} [policyVersion] - App-controlled policy version used as a stable change signal.
@@ -358,6 +359,8 @@
 /**
  * Velocious sync configuration.
  * @typedef {object} VelociousSyncConfiguration
+ * @property {import("./sync/device-identity.js").SyncJsonWebKey | null} [deviceCertificateBackendPublicKey] - Public backend key used to verify offline device certificates for sync replay.
+ * @property {number} [changeFeedRetentionSize] - Number of accepted server changes retained before clients must refresh from snapshot.
  * @property {Array<import("./sync/offline-grant.js").OfflineGrantSigningKey>} offlineGrantSigningKeys - Signing keys used to issue and verify offline grants. Secrets must never be exposed to clients.
  * @property {number} [offlineGrantTtlMs] - Default offline grant TTL in milliseconds. Defaults to 24 hours.
  */
@@ -365,6 +368,7 @@
 /**
  * Frontend-safe normalized sync metadata.
  * @typedef {object} NormalizedFrontendModelResourceSyncConfiguration
+ * @property {"optimisticVersion" | "serverWins" | "lastWriterWins" | "fieldThreeWay" | "appendOnly"} conflictStrategy - Normalized replay conflict strategy.
  * @property {boolean} enabled - Whether the resource is sync-enabled.
  * @property {string[]} operations - Sorted, duplicate-free sync operation names.
  * @property {string | null} policyVersion - App-controlled policy version, or null.

package/build/configuration.js

@@ -232,6 +232,9 @@ export default class VelociousConfiguration {
     /** Grace period for paused WebSocket sessions before permanent teardown. */
     this._websocketSessionGraceSeconds = 300
 
+    /** Interval (seconds) between server→client heartbeat pings; 0 disables reaping of silent sockets. */
+    this._websocketSessionHeartbeatSeconds = 30
+
     /**
      * Optional wrapper called around every WebSocket-borne request /
      * connection message / channel dispatch. Apps register it here
@@ -406,15 +409,25 @@ export default class VelociousConfiguration {
    * @returns {import("./configuration-types.js").VelociousSyncConfiguration} - Normalized sync configuration.
    */
   _normalizeSyncConfiguration(sync) {
+    const deviceCertificateBackendPublicKey = sync?.deviceCertificateBackendPublicKey || null
+    const changeFeedRetentionSize = sync?.changeFeedRetentionSize
     const offlineGrantSigningKeys = sync?.offlineGrantSigningKeys || []
     const offlineGrantTtlMs = sync?.offlineGrantTtlMs
 
+    if (deviceCertificateBackendPublicKey !== null && (typeof deviceCertificateBackendPublicKey !== "object" || Array.isArray(deviceCertificateBackendPublicKey))) {
+      throw new Error("sync.deviceCertificateBackendPublicKey must be a public JSON Web Key object")
+    }
+    if (changeFeedRetentionSize !== undefined && (!Number.isInteger(changeFeedRetentionSize) || changeFeedRetentionSize <= 0)) {
+      throw new Error("sync.changeFeedRetentionSize must be a positive integer")
+    }
     if (!Array.isArray(offlineGrantSigningKeys)) throw new Error("sync.offlineGrantSigningKeys must be an array")
     if (offlineGrantTtlMs !== undefined && (!Number.isInteger(offlineGrantTtlMs) || offlineGrantTtlMs <= 0)) {
       throw new Error("sync.offlineGrantTtlMs must be a positive integer number of milliseconds")
     }
 
     return {
+      changeFeedRetentionSize: changeFeedRetentionSize || 10000,
+      deviceCertificateBackendPublicKey,
       offlineGrantSigningKeys: offlineGrantSigningKeys.map((key) => normalizeOfflineGrantSigningKey(key)),
       offlineGrantTtlMs: offlineGrantTtlMs || 24 * 60 * 60 * 1000
     }
@@ -2042,6 +2055,12 @@ export default class VelociousConfiguration {
    */
   getWebsocketSessionGraceSeconds() { return this._websocketSessionGraceSeconds }
 
+  /**
+   * Runs get websocket session heartbeat seconds.
+   * @returns {number} - Interval (seconds) between server→client heartbeat pings; 0 disables reaping.
+   */
+  getWebsocketSessionHeartbeatSeconds() { return this._websocketSessionHeartbeatSeconds }
+
   /**
    * Registers a wrapper invoked around every WS-borne request /
    * connection message / channel dispatch. The wrapper receives the
@@ -2119,6 +2138,16 @@ export default class VelociousConfiguration {
     this._websocketSessionGraceSeconds = seconds
   }
 
+  /**
+   * Runs set websocket session heartbeat seconds.
+   * @param {number} seconds
+   * @returns {void}
+   */
+  setWebsocketSessionHeartbeatSeconds(seconds) {
+    if (!Number.isFinite(seconds) || seconds < 0) throw new Error(`Invalid heartbeat seconds: ${seconds}`)
+    this._websocketSessionHeartbeatSeconds = seconds
+  }
+
   /**
    * Moves a session into the paused registry and starts the grace
    * timer. When the timer fires, the session's permanent teardown

package/build/database/drivers/base.js

@@ -9,6 +9,12 @@
  * @property {boolean} [unique] - Whether the index should enforce uniqueness.
  * @property {string} tableName - Name of the table to add the index to.
  */
+/**
+ * RemoveIndexSqlArgs type.
+ * @typedef {object} RemoveIndexSqlArgs
+ * @property {string} name - Index name to drop.
+ * @property {string} tableName - Name of the table the index belongs to.
+ */
 /**
  * DropTableSqlArgsType type.
  * @typedef {object} DropTableSqlArgsType
@@ -307,6 +313,16 @@ export default class VelociousDatabaseDriversBase {
     throw new Error("'createIndexSQLs' not implemented")
   }
 
+  /**
+   * Runs remove index sqls.
+   * @abstract
+   * @param {RemoveIndexSqlArgs} indexData - Index data.
+   * @returns {Promise<string[]>} - Resolves with SQL statements.
+   */
+  async removeIndexSQLs(indexData) { // eslint-disable-line no-unused-vars
+    throw new Error("'removeIndexSQLs' not implemented")
+  }
+
   /**
    * Runs create table.
    * @param {import("../table-data/index.js").default} tableData - Table data.

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

@@ -15,6 +15,7 @@ import Options from "./options.js"
 import mssql from "mssql"
 import net from "node:net"
 import QueryParser from "./query-parser.js"
+import RemoveIndex from "./sql/remove-index.js"
 import Table from "./table.js"
 import StructureSql from "./structure-sql.js"
 import timeout from "awaitery/build/timeout.js"
@@ -113,6 +114,18 @@ export default class VelociousDatabaseDriversMssql extends Base{
     return await createIndex.toSQLs()
   }
 
+  /**
+   * Runs remove index sqls.
+   * @param {import("../base.js").RemoveIndexSqlArgs} indexData - Index data.
+   * @returns {Promise<string[]>} - Resolves with SQL statements.
+   */
+  async removeIndexSQLs(indexData) {
+    const removeArgs = Object.assign({driver: this}, indexData)
+    const removeIndex = new RemoveIndex(removeArgs)
+
+    return await removeIndex.toSQLs()
+  }
+
   /**
    * Runs create table sql.
    * @param {import("../../table-data/index.js").default} tableData - Table data.

package/build/database/drivers/mssql/sql/remove-index.js

@@ -0,0 +1,6 @@
+// @ts-check
+
+import RemoveIndexBase from "../../../query/remove-index-base.js"
+
+export default class VelociousDatabaseConnectionDriversMssqlSqlRemoveIndex extends RemoveIndexBase {
+}

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

@@ -14,6 +14,7 @@ import Options from "./options.js"
 import mysql from "mysql"
 import query from "./query.js"
 import QueryParser from "./query-parser.js"
+import RemoveIndex from "./sql/remove-index.js"
 import Table from "./table.js"
 import StructureSql from "./structure-sql.js"
 import Upsert from "./sql/upsert.js"
@@ -227,6 +228,18 @@ export default class VelociousDatabaseDriversMysql extends Base{
     return await createIndex.toSQLs()
   }
 
+  /**
+   * Runs remove index sqls.
+   * @param {import("../base.js").RemoveIndexSqlArgs} indexData - Index data.
+   * @returns {Promise<string[]>} - Resolves with SQL statements.
+   */
+  async removeIndexSQLs(indexData) {
+    const removeArgs = Object.assign({driver: this}, indexData)
+    const removeIndex = new RemoveIndex(removeArgs)
+
+    return await removeIndex.toSQLs()
+  }
+
   /**
    * Runs create table sql.
    * @param {import("../../table-data/index.js").default} tableData - Table data.

package/build/database/drivers/mysql/sql/remove-index.js

@@ -0,0 +1,6 @@
+// @ts-check
+
+import RemoveIndexBase from "../../../query/remove-index-base.js"
+
+export default class VelociousDatabaseConnectionDriversMysqlSqlRemoveIndex extends RemoveIndexBase {
+}

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

@@ -14,6 +14,7 @@ import DropTable from "./sql/drop-table.js"
 import Insert from "./sql/insert.js"
 import Options from "./options.js"
 import QueryParser from "./query-parser.js"
+import RemoveIndex from "./sql/remove-index.js"
 import Table from "./table.js"
 import StructureSql from "./structure-sql.js"
 import Upsert from "./sql/upsert.js"
@@ -149,6 +150,18 @@ export default class VelociousDatabaseDriversPgsql extends Base{
     return await createIndex.toSQLs()
   }
 
+  /**
+   * Runs remove index sqls.
+   * @param {import("../base.js").RemoveIndexSqlArgs} indexData - Index data.
+   * @returns {Promise<string[]>} - Resolves with SQL statements.
+   */
+  async removeIndexSQLs(indexData) {
+    const removeArgs = Object.assign({driver: this}, indexData)
+    const removeIndex = new RemoveIndex(removeArgs)
+
+    return await removeIndex.toSQLs()
+  }
+
   /**
    * Runs create table sql.
    * @param {import("../../table-data/index.js").default} tableData - Table data.

package/build/database/drivers/pgsql/sql/remove-index.js

@@ -0,0 +1,6 @@
+// @ts-check
+
+import RemoveIndexBase from "../../../query/remove-index-base.js"
+
+export default class VelociousDatabaseConnectionDriversPgsqlSqlRemoveIndex extends RemoveIndexBase {
+}

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

@@ -12,6 +12,7 @@ import escapeString from "sql-escape-string"
 import Insert from "./sql/insert.js"
 import Options from "./options.js"
 import QueryParser from "./query-parser.js"
+import RemoveIndex from "./sql/remove-index.js"
 import Table from "./table.js"
 import StructureSql from "./structure-sql.js"
 import Upsert from "./sql/upsert.js"
@@ -55,6 +56,18 @@ export default class VelociousDatabaseDriversSqliteBase extends Base {
     return await createIndex.toSQLs()
   }
 
+  /**
+   * Runs remove index sqls.
+   * @param {import("../base.js").RemoveIndexSqlArgs} indexData - Index data.
+   * @returns {Promise<string[]>} - Resolves with SQL statements.
+   */
+  async removeIndexSQLs(indexData) {
+    const removeArgs = Object.assign({driver: this}, indexData)
+    const removeIndex = new RemoveIndex(removeArgs)
+
+    return await removeIndex.toSQLs()
+  }
+
   /**
    * Runs create table sql.
    * @abstract

package/build/database/drivers/sqlite/sql/remove-index.js

@@ -0,0 +1,6 @@
+// @ts-check
+
+import RemoveIndexBase from "../../../query/remove-index-base.js"
+
+export default class VelociousDatabaseConnectionDriversSqliteSqlRemoveIndex extends RemoveIndexBase {
+}

package/build/database/migration/index.js

@@ -39,6 +39,7 @@
 import { convertLegacyDateValueToUtcStorage } from "../datetime-storage.js"
 import * as inflection from "inflection"
 import restArgsError from "../../utils/rest-args-error.js"
+import CreateIndexBase from "../query/create-index-base.js"
 import TableData from "../table-data/index.js"
 class NotImplementedError extends Error {}
 
@@ -184,6 +185,49 @@ export default class VelociousDatabaseMigration {
     }
   }
 
+  /**
+   * RemoveIndexArgsType type.
+   * @typedef {object} RemoveIndexArgsType
+   * @property {string} [name] - Explicit index name to remove.
+   */
+  /**
+   * Runs remove index.
+   * @param {string} tableName - Table name.
+   * @param {string | Array<string | import("../table-data/table-column.js").default>} nameOrColumns - Index name or columns whose default addIndex name should be removed.
+   * @param {RemoveIndexArgsType} [args] - Options object.
+   * @returns {Promise<void>} - Resolves when complete.
+   */
+  async removeIndex(tableName, nameOrColumns, args = {}) {
+    const {name, ...restArgs} = args
+
+    restArgsError(restArgs)
+
+    const removeIndexName = name || this._removeIndexName(tableName, nameOrColumns)
+    const sqls = await this.getDriver().removeIndexSQLs({name: removeIndexName, tableName})
+
+    for (const sql of sqls) {
+      await this.getDriver().query(sql)
+    }
+  }
+
+  /**
+   * Runs remove index name.
+   * @param {string} tableName - Table name.
+   * @param {string | Array<string | import("../table-data/table-column.js").default>} nameOrColumns - Index name or columns.
+   * @returns {string} - The index name.
+   */
+  _removeIndexName(tableName, nameOrColumns) {
+    if (typeof nameOrColumns === "string") return nameOrColumns
+
+    const createIndex = new CreateIndexBase({
+      columns: nameOrColumns,
+      driver: this.getDriver(),
+      tableName
+    })
+
+    return createIndex.generateIndexName()
+  }
+
   /**
    * AddForeignKeyArgsType type.
    * @typedef {object} AddForeignKeyArgsType

package/build/database/pool/base-methods-forward.js

@@ -23,6 +23,7 @@ export default function baseMethodsForward(PoolBase) {
     "quote",
     "quoteColumn",
     "quoteTable",
+    "removeIndexSQLs",
     "select",
     "update",
     "updateSql"

package/build/database/query/remove-index-base.js

@@ -0,0 +1,39 @@
+// @ts-check
+
+import QueryBase from "./base.js"
+
+/**
+ * RemoveIndexBaseArgsType type.
+ * @typedef {object} RemoveIndexBaseArgsType
+ * @property {import("../drivers/base.js").default} driver - Database driver used to generate SQL.
+ * @property {string} name - Index name to drop.
+ * @property {string} tableName - Name of the table the index belongs to.
+ */
+
+export default class VelociousDatabaseQueryRemoveIndexBase extends QueryBase {
+  /**
+   * Runs constructor.
+   * @param {RemoveIndexBaseArgsType} args - Options object.
+   */
+  constructor({driver, name, tableName}) {
+    super({driver})
+    this.name = name
+    this.tableName = tableName
+  }
+
+  /**
+   * Runs to sqls.
+   * @returns {Promise<string[]>} - Resolves with SQL statements.
+   */
+  async toSQLs() {
+    const databaseType = this.getDriver().getType()
+    const options = this.getOptions()
+    let sql = `DROP INDEX ${options.quoteIndexName(this.name)}`
+
+    if (databaseType == "mssql" || databaseType == "mysql") {
+      sql += ` ON ${options.quoteTableName(this.tableName)}`
+    }
+
+    return [sql]
+  }
+}

package/build/database/record/index.js

@@ -690,11 +690,14 @@ class VelociousDatabaseRecord {
         return await this.relationshipOrLoad(relationshipName, {preloadTranslations: true})
       }
 
-      prototype[`set${inflection.camelize(relationshipName)}`] = function(/** @type {?} */ model) {
+      prototype[`set${inflection.camelize(relationshipName)}`] = function(/** @type {VelociousDatabaseRecord | null | undefined} */ model) {
         const relationship = this.getRelationshipByName(relationshipName)
+        const foreignKeyValue = this._belongsToForeignKeyValue({model, relationship})
 
-        relationship.setLoaded(model)
+        relationship.setLoaded(model || undefined)
+        relationship.setPreloaded(true)
         relationship.setDirty(true)
+        this._setColumnAttribute(relationship.getForeignKey(), foreignKeyValue)
       }
     } else if (actualData.type == "hasMany") {
       relationship = new HasManyRelationship(actualData)
@@ -1783,6 +1786,20 @@ class VelociousDatabaseRecord {
     return loaded.readColumn(relationship.getPrimaryKey()) == normalizedValue
   }
 
+  /**
+   * Returns the foreign key value for a belongs-to relationship assignment.
+   * @param {object} args - Relationship assignment arguments.
+   * @param {VelociousDatabaseRecord | null | undefined} args.model - Assigned model.
+   * @param {import("./instance-relationships/base.js").default} args.relationship - Belongs-to relationship instance.
+   * @returns {string | number | null | undefined} - Foreign key value for the assignment.
+   */
+  _belongsToForeignKeyValue({model, relationship}) {
+    if (model == null) return null
+    if (!(model instanceof VelociousDatabaseRecord)) throw new Error(`Unexpected model type: ${typeof model}`)
+
+    return /** @type {string | number | null | undefined} */ (model.readColumn(relationship.getPrimaryKey()))
+  }
+
   /**
    * Runs clear loaded belongs to relationship.
    * @param {?} relationship - Relationship instance.
@@ -2364,8 +2381,9 @@ class VelociousDatabaseRecord {
             await model.save()
 
             const foreignKey = this._relationshipForeignKeyAttribute(instanceRelationship)
+            const foreignKeyValue = this._belongsToForeignKeyValue({model, relationship: instanceRelationship})
 
-            this.setAttribute(foreignKey, model.id())
+            this.setAttribute(foreignKey, foreignKeyValue)
 
             instanceRelationship.setPreloaded(true)
             instanceRelationship.setDirty(false)
@@ -3801,14 +3819,12 @@ class VelociousDatabaseRecord {
         const relationship = this._instanceRelationships[relationshipName]
 
         if (relationship.getType() == "belongsTo" && relationship.getDirty()) {
-          const model = relationship.loaded()
+          const model = relationship.getLoadedOrUndefined()
 
           if (model) {
-            if (model instanceof VelociousDatabaseRecord) {
-              belongsToChanges[relationship.getForeignKey()] = model?.id()
-            } else {
-              throw new Error(`Unexpected model type: ${typeof model}`)
-            }
+            if (Array.isArray(model)) throw new Error("Unexpected belongs-to model array")
+
+            belongsToChanges[relationship.getForeignKey()] = this._belongsToForeignKeyValue({model, relationship})
           }
         }
       }

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

@@ -120,6 +120,7 @@ export default class DbGenerateModel extends BaseCommand {
 
         const columns = await table.getColumns()
         const writeAttributeTypeName = `${modelNameCamelized}WriteAttributes`
+        const belongsToWriteAttributes = await this.belongsToWriteAttributesForModel({modelClass, modelsDir})
         const nestedWriteAttributes = this.nestedWriteAttributesForModel({modelClass})
 
         fileContent += `import DatabaseRecord from "${velociousPath}/database/record/index.js"\n\n`
@@ -135,6 +136,9 @@ export default class DbGenerateModel extends BaseCommand {
             fileContent += ` * @property {${setterJsdocType}${column.getNull() ? " | null" : ""}} [${camelizedColumnName}] - Value for the ${camelizedColumnName} attribute.\n`
           }
         }
+        for (const belongsToWriteAttribute of belongsToWriteAttributes) {
+          fileContent += ` * @property {${belongsToWriteAttribute.propertyType}} [${belongsToWriteAttribute.propertyName}] - Related ${belongsToWriteAttribute.relationshipName} record.\n`
+        }
         for (const nestedWriteAttribute of nestedWriteAttributes) {
           fileContent += ` * @property {${nestedWriteAttribute.propertyType}} [${nestedWriteAttribute.propertyName}] - Nested ${nestedWriteAttribute.relationshipName} attributes.\n`
         }
@@ -440,6 +444,38 @@ export default class DbGenerateModel extends BaseCommand {
     return this.jsDocTypeFromColumn(column, modelClass)
   }
 
+  /**
+   * Runs belongs to write attributes for model.
+   * @param {object} args - Arguments.
+   * @param {typeof import("../../../../../database/record/index.js").default} args.modelClass - Model class.
+   * @param {string} args.modelsDir - Source models directory.
+   * @returns {Promise<Array<{propertyName: string, propertyType: string, relationshipName: string}>>} - Belongs-to write attributes.
+   */
+  async belongsToWriteAttributesForModel({modelClass, modelsDir}) {
+    const writeAttributes = []
+
+    for (const relationship of modelClass.getRelationships()) {
+      if (relationship.getType() !== "belongsTo") continue
+      if (relationship.getPolymorphic()) continue
+
+      const targetModelClass = relationship.getTargetModelClass()
+
+      if (!targetModelClass) throw new Error(`Relationship '${relationship.getRelationshipName()}' on '${modelClass.getModelName()}' has no target model class`)
+
+      const targetModelFileName = inflection.dasherize(inflection.underscore(targetModelClass.getModelName()))
+      const targetModelPath = `${modelsDir}/${targetModelFileName}.js`
+      const targetImportPath = await fileExists(targetModelPath) ? `../models/${targetModelFileName}.js` : `./${targetModelFileName}.js`
+
+      writeAttributes.push({
+        propertyName: relationship.getRelationshipName(),
+        propertyType: `import("${targetImportPath}").default`,
+        relationshipName: relationship.getRelationshipName()
+      })
+    }
+
+    return writeAttributes
+  }
+
   /**
    * Runs nested write attributes for model.
    * @param {object} args - Arguments.