velocious 1.0.567 → 1.0.569

package/src/database/record/instance-relationships/has-many.js

@@ -29,8 +29,9 @@ export default class VelociousDatabaseRecordHasManyInstanceRelationship extends
 
     if (!targetModelClass) throw new Error("Can't build a new record without a taget model class")
 
-    const newInstance = /** @type {InstanceType<TMC>} */ (new targetModelClass(data))
-
+    const newInstance = this.getModel().bindRelatedRecord(
+      /** @type {InstanceType<TMC>} */ (new targetModelClass(data))
+    )
 
     // Add it to the loaded models of this relationship
     if (this._loaded === undefined) {
@@ -196,13 +197,14 @@ export default class VelociousDatabaseRecordHasManyInstanceRelationship extends
       )
       const targetTable = TargetModelClass.tableName()
       const throughTable = throughModelClass.tableName()
-      const driver = TargetModelClass.connection()
+      const baseQuery = this.getModel().queryForModel(TargetModelClass)
+      const driver = baseQuery.driver
       const parentPrimaryKey = this.getPrimaryKey()
       const parentId = /** @type {string | number} */ (this.getModel().readColumn(parentPrimaryKey))
       const joinSql = `LEFT JOIN ${driver.quoteTable(throughTable)} ON ${driver.quoteTable(throughTable)}.${driver.quoteColumn(throughPrimaryKey)} = ${driver.quoteTable(targetTable)}.${driver.quoteColumn(targetForeignKey)}`
       const whereSql = `${driver.quoteTable(throughTable)}.${driver.quoteColumn(throughForeignKey)} = ${driver.options().quote(parentId)}`
 
-      const query = TargetModelClass.joins(joinSql).where(whereSql)
+      const query = baseQuery.joins(joinSql).where(whereSql)
 
       return this.applyScope(query)
     }
@@ -224,7 +226,7 @@ export default class VelociousDatabaseRecordHasManyInstanceRelationship extends
       whereArgs[typeColumn] = this.getModel().getModelClass().getModelName()
     }
 
-    const query = TargetModelClass.where(whereArgs)
+    const query = this.getModel().queryForModel(TargetModelClass).where(whereArgs)
 
     return this.applyScope(query)
   }

package/src/database/record/instance-relationships/has-one.js

@@ -32,7 +32,9 @@ export default class VelociousDatabaseRecordHasOneInstanceRelationship extends B
 
     if (!TargetModelClass) throw new Error("Can't build a new record without a target model class")
 
-    const newInstance = /** @type {InstanceType<TMC>} */ (new TargetModelClass(data))
+    const newInstance = this.getModel().bindRelatedRecord(
+      /** @type {InstanceType<TMC>} */ (new TargetModelClass(data))
+    )
 
     this._loaded = newInstance
 
@@ -64,7 +66,7 @@ export default class VelociousDatabaseRecordHasOneInstanceRelationship extends B
 
     whereArgs[foreignKey] = primaryModelID
 
-    let query = TargetModelClass.where(whereArgs)
+    let query = this.getModel().queryForModel(TargetModelClass).where(whereArgs)
 
     query = this.applyScope(query)
 

package/src/database/record/validators/uniqueness.js

@@ -15,7 +15,7 @@ export default class VelociousDatabaseRecordValidatorsUniqueness extends Base {
   async validate({model, attributeName}) {
     const modelClass = /** @type {typeof import("../index.js").default} */ (model.constructor)
 
-    const connection = modelClass.connection()
+    const connection = model.connection()
     const tableName = modelClass._getTable().getName()
     const attributeValue = /** @type {string | number} */ (model.readAttribute(attributeName))
     const attributeNameUnderscore = inflection.underscore(attributeName)
@@ -49,7 +49,8 @@ export default class VelociousDatabaseRecordValidatorsUniqueness extends Base {
       whereArgs[scopeUnderscore] = /** @type {string | number} */ (scopeValue)
     }
 
-    let existingRecordQuery = modelClass
+    let existingRecordQuery = model
+      .queryForModel(modelClass)
       .select(modelClass.primaryKey())
       .where(whereArgs)
 

package/src/database/table-data/table-foreign-key.js

@@ -7,16 +7,18 @@ export default class TableForeignKey {
    * Runs constructor.
    * @param {object} args - Options object.
    * @param {string} args.columnName - Column name.
+   * @param {boolean} [args.dropForeignKey] - Whether to drop this foreign key.
    * @param {boolean} [args.isNewForeignKey] - Whether is new foreign key.
    * @param {string} [args.name] - Name.
    * @param {string} args.tableName - Table name.
    * @param {string} args.referencedColumnName - Referenced column name.
    * @param {string} args.referencedTableName - Referenced table name.
    */
-  constructor({columnName, isNewForeignKey, name, tableName, referencedColumnName, referencedTableName, ...restArgs}) {
+  constructor({columnName, dropForeignKey, isNewForeignKey, name, tableName, referencedColumnName, referencedTableName, ...restArgs}) {
     restArgsError(restArgs)
 
     this._columnName = columnName
+    this._dropForeignKey = dropForeignKey
     this._isNewForeignKey = isNewForeignKey
     this._name = name
     this._tableName = tableName
@@ -30,6 +32,12 @@ export default class TableForeignKey {
    */
   getColumnName() { return this._columnName }
 
+  /**
+   * Runs get drop foreign key.
+   * @returns {boolean} - Whether this foreign key should be dropped.
+   */
+  getDropForeignKey() { return this._dropForeignKey || false }
+
   /**
    * Runs get is new foreign key.
    * @returns {boolean} - Whether is new foreign key.

package/src/environment-handlers/base.js

@@ -559,7 +559,7 @@ export default class VelociousEnvironmentHandlerBase {
    * @param {object} _args - Args.
    * @param {string[]} _args.allowedPathPrefixes - Allowed path prefixes.
    * @param {string} _args.inputPath - Input path.
-   * @returns {Promise<{buffer: Buffer, filePath: string}>} - Resolved path and file bytes.
+   * @returns {Promise<import("../database/record/attachments/normalize-input.js").AttachmentPathSource>} - Opened path source.
    */
   async resolveAttachmentInputPath(_args) {
     throw new Error("Attachment path input is not supported in this environment")

package/src/environment-handlers/node/attachment-path-source.js

@@ -0,0 +1,144 @@
+// @ts-check
+
+import { Readable } from "node:stream"
+
+const READ_CHUNK_SIZE = 64 * 1024
+
+/**
+ * Opened Node attachment path source.
+ *
+ * The opened file handle fixes the source identity at normalization time. Reads
+ * are limited to the stat snapshot and fail if the file becomes shorter.
+ */
+export default class AttachmentPathSource {
+  /**
+   * Creates an opened attachment path source.
+   * @param {object} args - Source args.
+   * @param {number} args.byteSize - Opened-handle stat size.
+   * @param {import("node:fs/promises").FileHandle} args.fileHandle - Open file handle.
+   * @param {string} args.filePath - Validated path used to open the handle.
+   */
+  constructor({byteSize, fileHandle, filePath}) {
+    this.byteSize = byteSize
+    this.fileHandle = fileHandle
+    this.filePath = filePath
+    /** @type {Set<Readable>} */
+    this.activeStreams = new Set()
+    /** @type {Promise<void> | null} */
+    this.closePromise = null
+    this.closed = false
+  }
+
+  /**
+   * Creates a bounded, backpressured stream over the opened file snapshot.
+   * @returns {Promise<Readable>} - Snapshot read stream.
+   */
+  async createReadStream() {
+    this.assertOpen()
+
+    const stream = Readable.from(this.readChunks())
+
+    this.activeStreams.add(stream)
+    stream.once("close", () => {
+      this.activeStreams.delete(stream)
+    })
+
+    return stream
+  }
+
+  /**
+   * Reads the opened file snapshot into memory for compatibility-only callers.
+   * @returns {Promise<Buffer>} - Exact snapshot bytes.
+   */
+  async readBuffer() {
+    this.assertOpen()
+
+    const contentBuffer = Buffer.allocUnsafe(this.byteSize)
+    let offset = 0
+
+    while (offset < this.byteSize) {
+      this.assertOpen()
+
+      const {bytesRead} = await this.fileHandle.read(
+        contentBuffer,
+        offset,
+        Math.min(READ_CHUNK_SIZE, this.byteSize - offset),
+        offset
+      )
+
+      if (bytesRead === 0) this.throwTruncated({bytesRead: offset})
+
+      offset += bytesRead
+    }
+
+    return contentBuffer
+  }
+
+  /**
+   * Closes all active streams and the owned file handle.
+   * @returns {Promise<void>} - Resolves after close.
+   */
+  async close() {
+    if (!this.closePromise) {
+      this.closed = true
+      this.closePromise = (async () => {
+        const streams = Array.from(this.activeStreams)
+        const streamClosePromises = streams.map(async (stream) => {
+          if (stream.closed) return
+
+          await new Promise((resolve) => {
+            stream.once("close", resolve)
+            stream.destroy()
+          })
+        })
+
+        await Promise.all(streamClosePromises)
+        await this.fileHandle.close()
+      })()
+    }
+
+    await this.closePromise
+  }
+
+  /**
+   * Produces bounded chunks from the opened file handle.
+   * @yields {Buffer} - Snapshot chunks.
+   */
+  async *readChunks() {
+    let offset = 0
+
+    while (offset < this.byteSize) {
+      this.assertOpen()
+
+      const chunkBuffer = Buffer.allocUnsafe(Math.min(READ_CHUNK_SIZE, this.byteSize - offset))
+      const {bytesRead} = await this.fileHandle.read(chunkBuffer, 0, chunkBuffer.length, offset)
+
+      if (bytesRead === 0) this.throwTruncated({bytesRead: offset})
+
+      offset += bytesRead
+      yield bytesRead === chunkBuffer.length ? chunkBuffer : chunkBuffer.subarray(0, bytesRead)
+    }
+  }
+
+  /**
+   * Asserts that the source remains open.
+   * @returns {void} - Throws if closed.
+   */
+  assertOpen() {
+    if (this.closed) {
+      throw new Error(`Attachment path source is closed: ${this.filePath}`)
+    }
+  }
+
+  /**
+   * Throws a truncation error.
+   * @param {object} args - Args.
+   * @param {number} args.bytesRead - Bytes read before EOF.
+   * @returns {never} - Always throws.
+   */
+  throwTruncated({bytesRead}) {
+    throw new Error(
+      `Attachment path source was truncated: expected ${this.byteSize} bytes but read ${bytesRead} from ${this.filePath}`
+    )
+  }
+}

package/src/environment-handlers/node.js

@@ -35,6 +35,7 @@ import requireContext from "require-context"
 import InitializerFromRequireContext from "../database/initializer-from-require-context.js"
 import toImportSpecifier from "../utils/to-import-specifier.js"
 import {validateTimeZone} from "../time-zone.js"
+import AttachmentPathSource from "./node/attachment-path-source.js"
 
 /**
  * Defines this typedef.
@@ -227,7 +228,7 @@ export default class VelociousEnvironmentHandlerNode extends Base{
    * @param {object} args - Args.
    * @param {string[]} args.allowedPathPrefixes - Allowed path prefixes.
    * @param {string} args.inputPath - Input path.
-   * @returns {Promise<{buffer: Buffer, filePath: string}>} - Resolved path and bytes.
+   * @returns {Promise<AttachmentPathSource>} - Opened regular-file path source.
    */
   async resolveAttachmentInputPath({allowedPathPrefixes, inputPath}) {
     const filePath = path.resolve(inputPath)
@@ -239,9 +240,33 @@ export default class VelociousEnvironmentHandlerNode extends Base{
       throw new Error("Attachment path is outside allowed directories")
     }
 
-    const buffer = await this.readAttachmentInputFile(filePath)
+    const fileHandle = await fs.open(filePath, "r")
 
-    return {buffer, filePath}
+    try {
+      const fileStats = await fileHandle.stat()
+
+      if (!fileStats.isFile()) {
+        throw new Error("Attachment path must reference a regular file")
+      }
+
+      return new AttachmentPathSource({
+        byteSize: fileStats.size,
+        fileHandle,
+        filePath
+      })
+    } catch (error) {
+      try {
+        await fileHandle.close()
+      } catch (closeError) {
+        throw new AggregateError(
+          [error, closeError],
+          `Attachment path validation and source close both failed for ${filePath}`,
+          {cause: closeError}
+        )
+      }
+
+      throw error
+    }
   }
 
   /**

package/src/frontend-models/websocket-publishers.js

@@ -145,7 +145,7 @@ export async function ensureFrontendModelWebsocketPublishersRegistered(configura
 
       if (action !== "create" && action !== "update") return
 
-      void model.getModelClass().connection().afterCommit(async () => {
+      void model.connection().afterCommit(async () => {
         broadcastFrontendModelEvent(model._getConfiguration(), modelName, {
           action,
           id: model.id(),
@@ -156,7 +156,7 @@ export async function ensureFrontendModelWebsocketPublishersRegistered(configura
     })
 
     modelClass.afterDestroy((model) => {
-      void model.getModelClass().connection().afterCommit(async () => {
+      void model.connection().afterCommit(async () => {
         broadcastFrontendModelEvent(model._getConfiguration(), modelName, {
           action: "destroy",
           id: model.id()

package/src/sync/server-sequence-allocator.js

@@ -49,23 +49,52 @@ export default class ServerSequenceAllocator {
    * parallel `next()` calls - including calls from other allocator instances
    * sharing the same table and connection - cannot interleave their insert
    * and last-insert-id reads and hand out duplicate sequences.
+   * @param {{connection?: import("../database/drivers/base.js").default}} [options] - Explicit record-owned connection.
    * @returns {Promise<number>} Next sequence value.
    */
-  async next() {
+  async next({connection} = {}) {
     const queueKey = `${this.databaseIdentifier}::${this.tableName}`
     const previousAllocation = allocationQueues.get(queueKey) ?? Promise.resolve()
-    const allocation = previousAllocation.then(() => this._allocateNext())
+    const allocation = previousAllocation.then(() => this._allocateNext(connection))
 
     allocationQueues.set(queueKey, allocation.then(() => undefined, () => undefined))
 
     return await allocation
   }
 
+  /**
+   * Allocates for a record while preserving allocator routing and operation ownership.
+   * @param {import("../database/record/index.js").default} record - Record receiving the sequence.
+   * @returns {Promise<number>} Next sequence value.
+   */
+  async _nextForRecord(record) {
+    const operation = record.databaseOperation()
+
+    if (!operation) return await this.next()
+
+    const ModelClass = record.getModelClass()
+
+    if (this._getConfiguration() !== ModelClass._getConfiguration()) {
+      throw new Error("Server sequence allocator belongs to another Velocious configuration")
+    }
+
+    const modelDatabaseIdentifier = ModelClass.getDatabaseIdentifier()
+
+    if (this.databaseIdentifier !== modelDatabaseIdentifier) {
+      throw new Error(`Server sequence allocator uses database ${JSON.stringify(this.databaseIdentifier)}, not operation model database ${JSON.stringify(modelDatabaseIdentifier)}`)
+    }
+
+    const operationScope = operation.forModel(ModelClass)
+
+    return await this.next({connection: operationScope.driver})
+  }
+
   /**
    * Ensures the backing table exists.
+   * @param {import("../database/drivers/base.js").default} [connection] - Explicit record-owned connection.
    * @returns {Promise<void>} Resolves when ready.
    */
-  async ensureReady() {
+  async ensureReady(connection) {
     if (this._isReady) return
 
     if (this._usesMemoryStorage()) {
@@ -85,7 +114,7 @@ export default class ServerSequenceAllocator {
       // cache readiness when the table was not created inside an active
       // transaction; otherwise the next allocation re-verifies the table.
       if (!created || !db.insideTransaction()) this._isReady = true
-    })
+    }, connection)
 
     try {
       await this._readyPromise
@@ -96,10 +125,11 @@ export default class ServerSequenceAllocator {
 
   /**
    * Allocates one sequence value after queueing.
+   * @param {import("../database/drivers/base.js").default} [connection] - Explicit record-owned connection.
    * @returns {Promise<number>} Allocated sequence value.
    */
-  async _allocateNext() {
-    await this.ensureReady()
+  async _allocateNext(connection) {
+    await this.ensureReady(connection)
 
     if (this._usesMemoryStorage()) {
       return ++this._memorySequence
@@ -123,7 +153,7 @@ export default class ServerSequenceAllocator {
       if (insertedId !== undefined && insertedId !== null) return Number(insertedId)
 
       return Number(await db.lastInsertID())
-    })
+    }, connection)
   }
 
   /**
@@ -158,9 +188,12 @@ export default class ServerSequenceAllocator {
    * Runs a callback with a database connection.
    * @template Result
    * @param {(db: import("../database/drivers/base.js").default) => Promise<Result>} callback - Database callback.
+   * @param {import("../database/drivers/base.js").default} [connection] - Explicit record-owned connection.
    * @returns {Promise<Result>} Callback result.
    */
-  async _withDb(callback) {
+  async _withDb(callback, connection) {
+    if (connection) return await callback(connection)
+
     return await this._getConfiguration().ensureConnections({databaseIdentifiers: [this.databaseIdentifier], name: "Server sequence allocator"}, async (dbs) => {
       const db = dbs[this.databaseIdentifier]
 
@@ -225,11 +258,11 @@ export function withServerSequence(ModelClass, {allocator, column = "serverSeque
   if (typeof prototype[advanceMethodName] != "function") {
     /**
      * Assigns the next server-side sequence.
-     * @this {Record<string, ?>}
+     * @this {import("../database/record/index.js").default & Record<string, ?>}
      * @returns {Promise<void>}
      */
     prototype[advanceMethodName] = async function advanceServerSequenceThroughAllocator() {
-      this[setterMethodName](await allocator.next())
+      this[setterMethodName](await allocator._nextForRecord(this))
     }
   }
 

package/src/sync/sync-client.js

@@ -220,13 +220,17 @@ export default class SyncClient {
         resource: record
       })
       const syncType = this.defaultSyncType({operation, record, resourceConfig})
+      const databaseOperation = record.databaseOperation()
+      const operationScope = databaseOperation
+        ? databaseOperation.forModel(this.config.syncModel)
+        : this.config.syncModel
 
-      await resourceConfig.modelClass.connection().afterCommit(async () => {
+      await record.connection().afterCommit(async () => {
         try {
           await SyncApiClient.queueLocalSync({
             data,
             resource: record,
-            syncModel: this.config.syncModel,
+            syncModel: operationScope,
             syncType
           })
         } catch (error) {

package/src/sync/sync-publisher.js

@@ -203,10 +203,14 @@ export default class SyncPublisher {
         sync_type: syncType,
         ...scopeValues.columns
       }
+      const databaseOperation = record.databaseOperation()
+      const operationScope = databaseOperation
+        ? databaseOperation.forModel(this.config.syncModel)
+        : this.config.syncModel
 
-      await resourceConfig.modelClass.connection().afterCommit(async () => {
+      await record.connection().afterCommit(async () => {
         try {
-          const syncRow = await this.upsertPublishedSyncRow(attributes)
+          const syncRow = await this.upsertPublishedSyncRow(attributes, operationScope)
 
           await this.broadcaster()({
             body: {
@@ -273,10 +277,11 @@ export default class SyncPublisher {
    * change back to), so repeated server changes to one resource reuse and
    * re-sequence one feed row.
    * @param {Record<string, ?>} attributes - Snapshotted sync row attributes.
+   * @param {?} syncModel - Operation-bound or static Sync model interface.
    * @returns {Promise<?>} Upserted sync row.
    */
-  async upsertPublishedSyncRow(attributes) {
-    const existingSync = await this.config.syncModel
+  async upsertPublishedSyncRow(attributes, syncModel = this.config.syncModel) {
+    const existingSync = await syncModel
       .where({
         [this.config.actorForeignKeyColumn]: null,
         resource_id: attributes.resource_id,
@@ -284,7 +289,7 @@ export default class SyncPublisher {
       })
       .first()
 
-    return await upsertSyncRow({attributes, existingSync, syncModel: this.config.syncModel})
+    return await upsertSyncRow({attributes, existingSync, syncModel})
   }
 
   /**