velocious 1.0.567 → 1.0.568

package/build/database/migration/index.js

@@ -270,6 +270,57 @@ export default class VelociousDatabaseMigration {
     )
   }
 
+  /**
+   * RemoveForeignKeyArgsType type.
+   * @typedef {object} RemoveForeignKeyArgsType
+   * @property {string} [columnName] - Override the derived foreign-key column name.
+   */
+  /**
+   * Runs remove foreign key.
+   * @param {string} tableName - Table the foreign key lives on.
+   * @param {string} referenceName - Singular reference name used to derive the FK column.
+   * @param {RemoveForeignKeyArgsType} [args] - Optional overrides.
+   * @returns {Promise<void>} - Resolves when complete.
+   */
+  async removeForeignKey(tableName, referenceName, args = {}) {
+    const {columnName, ...restArgs} = args
+
+    restArgsError(restArgs)
+
+    const resolvedColumnName = columnName || `${inflection.underscore(referenceName)}_id`
+    const driver = this.getDriver()
+    let maximumRemovals = 0
+    let previousMatchingCount = 0
+
+    for (let removalAttempt = 0; ; removalAttempt++) {
+      const table = await driver.getTableByName(tableName)
+
+      if (!table) throw new Error(`Table ${tableName} does not exist`)
+
+      const foreignKeys = await table.getForeignKeys()
+      const matchingForeignKeys = foreignKeys.filter((foreignKey) => foreignKey.getColumnName() == resolvedColumnName)
+
+      if (matchingForeignKeys.length === 0) {
+        if (removalAttempt === 0) throw new Error(`No foreign key on ${tableName}.${resolvedColumnName}`)
+
+        return
+      }
+
+      if (removalAttempt === 0) {
+        maximumRemovals = matchingForeignKeys.length
+      } else if (matchingForeignKeys.length >= previousMatchingCount) {
+        throw new Error(`Foreign key removal did not reduce matches on ${tableName}.${resolvedColumnName}`)
+      }
+
+      if (removalAttempt >= maximumRemovals) {
+        throw new Error(`Foreign key removal exceeded expected matches on ${tableName}.${resolvedColumnName}`)
+      }
+
+      previousMatchingCount = matchingForeignKeys.length
+      await driver.removeForeignKey(tableName, matchingForeignKeys[0])
+    }
+  }
+
   /**
    * Runs add reference.
    * @param {string} tableName - Table name.
@@ -298,16 +349,54 @@ export default class VelociousDatabaseMigration {
     }
   }
 
+  /**
+   * RemoveReferenceArgsType type.
+   * @typedef {object} RemoveReferenceArgsType
+   * @property {string} [columnName] - Override the derived reference column name.
+   * @property {string} [indexName] - Explicit generated index name to remove.
+   */
   /**
    * Runs remove reference.
    * @param {string} tableName - Table name.
    * @param {string} referenceName - Reference name.
+   * @param {RemoveReferenceArgsType} [args] - Optional overrides.
    * @returns {Promise<void>} - Resolves when complete.
    */
-  async removeReference(tableName, referenceName) {
-    const columnName = `${inflection.underscore(referenceName)}_id`
+  async removeReference(tableName, referenceName, args = {}) {
+    const {columnName, indexName, ...restArgs} = args
+
+    restArgsError(restArgs)
+
+    const resolvedColumnName = columnName || `${inflection.underscore(referenceName)}_id`
+    const driver = this.getDriver()
+    const table = await driver.getTableByName(tableName)
+
+    if (!table) throw new Error(`Table ${tableName} does not exist`)
+
+    const foreignKeys = await table.getForeignKeys()
+
+    for (const foreignKey of foreignKeys) {
+      if (foreignKey.getColumnName() != resolvedColumnName) continue
+
+      await driver.removeForeignKey(tableName, foreignKey)
+    }
+
+    const expectedIndexName = indexName || this._removeIndexName(tableName, [resolvedColumnName])
+    const indexes = await table.getIndexes()
+    const generatedIndex = indexes.find((index) => {
+      const indexColumnNames = index.getColumnNames()
+
+      return !index.isPrimaryKey() &&
+        index.getName() == expectedIndexName &&
+        indexColumnNames.length == 1 &&
+        indexColumnNames[0] == resolvedColumnName
+    })
+
+    if (generatedIndex) {
+      await this.removeIndex(tableName, generatedIndex.getName())
+    }
 
-    this.removeColumn(tableName, columnName)
+    await this.removeColumn(tableName, resolvedColumnName)
   }
 
   /**

package/build/database/query/alter-table-base.js

@@ -64,10 +64,16 @@ export default class VelociousDatabaseQueryAlterTableBase extends QueryBase {
     // SQLite's ALTER TABLE does not support adding constraints; the SQLite driver overrides
     // alterTableSQLs entirely (via TableRebuilder) so this base path is never invoked there.
     for (const foreignKey of tableData.getForeignKeys()) {
-      if (!foreignKey.getIsNewForeignKey()) continue
+      if (!foreignKey.getIsNewForeignKey() && !foreignKey.getDropForeignKey()) continue
 
       if (actionCount > 0) sql += ", "
 
+      if (foreignKey.getDropForeignKey()) {
+        sql += this.getDropForeignKeySQL(foreignKey)
+        actionCount++
+        continue
+      }
+
       sql += "ADD"
 
       if (foreignKey.getName()) {
@@ -101,4 +107,17 @@ export default class VelociousDatabaseQueryAlterTableBase extends QueryBase {
 
     return sqls
   }
+
+  /**
+   * Runs get drop foreign key sql.
+   * @param {import("../table-data/table-foreign-key.js").default} foreignKey - Foreign key to drop.
+   * @returns {string} - SQL fragment that removes the foreign key.
+   */
+  getDropForeignKeySQL(foreignKey) {
+    const name = foreignKey.getName()
+
+    if (!name) throw new Error(`Cannot remove unnamed foreign key on ${foreignKey.getTableName()}.${foreignKey.getColumnName()}`)
+
+    return `DROP CONSTRAINT ${this.getOptions().quoteIndexName(name)}`
+  }
 }

package/build/database/record/attachments/normalize-input.js

@@ -2,14 +2,24 @@
 
 import UploadedFile from "../../../http-server/client/uploaded-file/uploaded-file.js"
 
+/**
+ * AttachmentPathSource type.
+ * @typedef {object} AttachmentPathSource
+ * @property {number} byteSize - Opened file snapshot size.
+ * @property {string} filePath - Validated source path for metadata only.
+ * @property {() => Promise<import("node:stream").Readable>} createReadStream - Creates a bounded snapshot stream.
+ * @property {() => Promise<Buffer>} readBuffer - Reads snapshot bytes for compatibility callers.
+ * @property {() => Promise<void>} close - Closes the owned source.
+ */
 /**
  * NormalizedAttachmentInput type.
  * @typedef {object} NormalizedAttachmentInput
  * @property {number} byteSize - File size in bytes.
- * @property {Buffer} contentBuffer - Raw content bytes.
- * @property {string} contentBase64 - Base64 encoded content.
+ * @property {Buffer | null} contentBuffer - Raw in-memory content bytes.
+ * @property {string | null} contentBase64 - Base64 encoded in-memory content.
  * @property {string | null} contentType - Content type.
  * @property {string} filename - Filename.
+ * @property {AttachmentPathSource | null} pathSource - Environment-owned opened path source.
  */
 /**
  * Runs base name.
@@ -120,8 +130,16 @@ export default async function normalizeRecordAttachmentInput(input, args = {}) {
   const environmentHandler = args.environmentHandler
   /**
    * Defines buffer.
-   * @type {Buffer} */
-  let buffer
+   * @type {Buffer | null} */
+  let buffer = null
+  /**
+   * Defines byte size.
+   * @type {number | null} */
+  let byteSize = null
+  /**
+   * Defines path source.
+   * @type {AttachmentPathSource | null} */
+  let pathSource = null
   /**
    * Content type.
    * @type {string | null} */
@@ -147,13 +165,15 @@ export default async function normalizeRecordAttachmentInput(input, args = {}) {
     const allowedPathPrefixes = Array.isArray(args.allowedPathPrefixes)
       ? args.allowedPathPrefixes.filter((entry) => typeof entry === "string" && entry.length > 0)
       : []
-    const {buffer: fileBuffer, filePath} = await environmentHandler.resolveAttachmentInputPath({
+    pathSource = await environmentHandler.resolveAttachmentInputPath({
       allowedPathPrefixes,
       inputPath: input.path
     })
 
-    buffer = fileBuffer
-    filename = typeof input.filename === "string" && input.filename.length > 0 ? input.filename : baseName(filePath)
+    byteSize = pathSource.byteSize
+    filename = typeof input.filename === "string" && input.filename.length > 0
+      ? input.filename
+      : baseName(pathSource.filePath)
     contentType = typeof input.contentType === "string" && input.contentType.length > 0 ? input.contentType : null
   } else if (isPlainObject(input) && typeof input.contentBase64 === "string") {
     buffer = Buffer.from(input.contentBase64, "base64")
@@ -184,11 +204,19 @@ export default async function normalizeRecordAttachmentInput(input, args = {}) {
     ? baseName(filename)
     : ""
 
+  if (!buffer && !pathSource) {
+    throw new Error("Attachment input normalization produced no content")
+  }
+
+  if (buffer) byteSize = buffer.length
+  if (byteSize === null) throw new Error("Attachment input normalization produced no byte size")
+
   return {
-    byteSize: buffer.length,
+    byteSize,
     contentBuffer: buffer,
-    contentBase64: buffer.toString("base64"),
+    contentBase64: buffer ? buffer.toString("base64") : null,
     contentType,
-    filename: normalizedFilename || defaultFilename
+    filename: normalizedFilename || defaultFilename,
+    pathSource
   }
 }

package/build/database/record/attachments/storage-drivers/filesystem.js

@@ -1,7 +1,9 @@
 // @ts-check
 
+import { createWriteStream } from "node:fs"
 import fs from "fs/promises"
 import path from "path"
+import { pipeline } from "node:stream/promises"
 
 /**
  * Runs normalize base url.
@@ -52,16 +54,45 @@ export default class FilesystemAttachmentStorageDriver {
    * Runs write.
    * @param {object} args - Options.
    * @param {string} args.attachmentId - Attachment id.
-   * @param {{contentBuffer: Buffer, filename: string}} args.input - Normalized attachment input.
+   * @param {import("../normalize-input.js").NormalizedAttachmentInput} args.input - Normalized attachment input.
    * @returns {Promise<{storageKey: string}>} - Storage key result.
    */
   async write({attachmentId, input}) {
     const normalizedFilename = path.basename(input.filename || "attachment.bin")
     const storageKey = `${attachmentId}-${normalizedFilename}`
     const filePath = path.resolve(this.directory(), storageKey)
+    const temporaryFilePath = `${filePath}.tmp`
 
     await fs.mkdir(path.dirname(filePath), {recursive: true})
-    await fs.writeFile(filePath, input.contentBuffer)
+
+    try {
+      if (input.pathSource) {
+        await pipeline(
+          await input.pathSource.createReadStream(),
+          createWriteStream(temporaryFilePath)
+        )
+      } else if (input.contentBuffer) {
+        await fs.writeFile(temporaryFilePath, input.contentBuffer)
+      } else {
+        throw new Error("Filesystem attachment input has no content")
+      }
+
+      await fs.rename(temporaryFilePath, filePath)
+    } catch (error) {
+      try {
+        await fs.unlink(temporaryFilePath)
+      } catch (cleanupError) {
+        if (!(cleanupError instanceof Error) || !("code" in cleanupError) || cleanupError.code !== "ENOENT") {
+          throw new AggregateError(
+            [error, cleanupError],
+            `Filesystem attachment write and partial-file cleanup both failed for ${storageKey}`,
+            {cause: cleanupError}
+          )
+        }
+      }
+
+      throw error
+    }
 
     return {storageKey}
   }

package/build/database/record/attachments/storage-drivers/native.js

@@ -47,7 +47,7 @@ export default class NativeAttachmentStorageDriver {
    * Runs write.
    * @param {object} args - Write args.
    * @param {string} args.attachmentId - Attachment id.
-   * @param {{contentBase64: string, contentType: string | null, filename: string}} args.input - Normalized attachment input.
+   * @param {import("../normalize-input.js").NormalizedAttachmentInput} args.input - Normalized attachment input.
    * @param {import("../../index.js").default} args.model - Model instance.
    * @param {string} args.name - Attachment name.
    * @returns {Promise<{storageKey: string}>} - Storage key result.
@@ -57,10 +57,25 @@ export default class NativeAttachmentStorageDriver {
       throwMissingMethod({driverName: this.name, methodName: "write"})
     }
 
+    let contentBase64 = input.contentBase64
+
+    if (input.pathSource) {
+      // Native write callbacks have always received Base64. Path input is
+      // intentionally buffered here, after driver selection, to preserve that
+      // public callback contract without forcing filesystem/S3 to buffer.
+      const contentBuffer = await input.pathSource.readBuffer()
+
+      contentBase64 = contentBuffer.toString("base64")
+    }
+
+    if (contentBase64 === null) {
+      throw new Error(`Attachment storage driver "${this.name}" input has no content`)
+    }
+
     const result = await this.options.write({
       attachmentId,
       attachmentName: name,
-      contentBase64: input.contentBase64,
+      contentBase64,
       contentType: input.contentType,
       filename: input.filename,
       model

package/build/database/record/attachments/storage-drivers/s3.js

@@ -167,20 +167,40 @@ export default class S3AttachmentStorageDriver {
    * Runs write.
    * @param {object} args - Write args.
    * @param {string} args.attachmentId - Attachment id.
-   * @param {{contentBuffer: Buffer, contentType: string | null, filename: string}} args.input - Normalized attachment input.
+   * @param {import("../normalize-input.js").NormalizedAttachmentInput} args.input - Normalized attachment input.
    * @returns {Promise<{storageKey: string}>} - Storage key.
    */
   async write({attachmentId, input}) {
     const {PutObjectCommand} = await this.s3Runtime()
     const client = await this.client()
     const storageKey = `${attachmentId}-${input.filename}`
+    /**
+     * S3 request body.
+     * @type {Buffer | import("node:stream").Readable | null} */
+    let body = input.contentBuffer
+    /**
+     * Path input stream.
+     * @type {import("node:stream").Readable | null} */
+    let pathInputStream = null
+
+    if (input.pathSource) {
+      pathInputStream = await input.pathSource.createReadStream()
+      body = pathInputStream
+    }
 
-    await client.send(new PutObjectCommand({
-      Body: input.contentBuffer,
-      Bucket: this.bucket(),
-      ContentType: input.contentType || undefined,
-      Key: storageKey
-    }))
+    if (!body) throw new Error("S3 attachment input has no content")
+
+    try {
+      await client.send(new PutObjectCommand({
+        Body: body,
+        Bucket: this.bucket(),
+        ContentLength: input.byteSize,
+        ContentType: input.contentType || undefined,
+        Key: storageKey
+      }))
+    } finally {
+      if (pathInputStream) pathInputStream.destroy()
+    }
 
     return {storageKey}
   }

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

@@ -156,65 +156,181 @@ export default class RecordAttachmentsStore {
       allowedPathPrefixes,
       environmentHandler: this.configuration.getEnvironmentHandler()
     })
+    /**
+     * Attachment persistence error.
+     * This stays opaque so any JavaScript thrown value is preserved exactly.
+     * @type {unknown} */
+    let persistenceError = null
+    let persistenceFailed = false
+
+    try {
+      const persistenceInput = await this.persistenceInputFor(normalizedInput)
+
+      await this.persistNormalizedAttachment({
+        model,
+        name,
+        normalizedInput: persistenceInput,
+        replace
+      })
+    } catch (error) {
+      persistenceFailed = true
+      persistenceError = error
+    }
+
+    if (normalizedInput.pathSource) {
+      try {
+        await normalizedInput.pathSource.close()
+      } catch (closeError) {
+        if (persistenceFailed) {
+          throw new AggregateError(
+            [persistenceError, closeError],
+            `Attachment persistence and path-source close both failed for ${model.getModelClass().getModelName()}#${String(model.id())} (${name})`,
+            {cause: closeError}
+          )
+        }
+
+        throw closeError
+      }
+    }
+
+    if (persistenceFailed) throw persistenceError
+  }
+
+  /**
+   * Materializes path content once when a legacy schema requires Base64.
+   * @param {import("./normalize-input.js").NormalizedAttachmentInput} normalizedInput - Normalized attachment input.
+   * @returns {Promise<import("./normalize-input.js").NormalizedAttachmentInput>} - Input used by the driver and database.
+   */
+  async persistenceInputFor(normalizedInput) {
+    if (this._contentBase64Nullable || !normalizedInput.pathSource) return normalizedInput
+
+    const contentBuffer = await normalizedInput.pathSource.readBuffer()
+
+    return {
+      ...normalizedInput,
+      contentBase64: contentBuffer.toString("base64"),
+      contentBuffer,
+      pathSource: null
+    }
+  }
+
+  /**
+   * Persists one normalized attachment while its path source remains open.
+   * @param {object} args - Options.
+   * @param {import("../index.js").default} args.model - Model instance.
+   * @param {string} args.name - Attachment name.
+   * @param {import("./normalize-input.js").NormalizedAttachmentInput} args.normalizedInput - Normalized attachment.
+   * @param {boolean} args.replace - Whether to replace existing attachments.
+   * @returns {Promise<void>} - Resolves after persistence.
+   */
+  async persistNormalizedAttachment({model, name, normalizedInput, replace}) {
     const attachmentDriver = await this.resolveAttachmentDriver({model, name})
     const attachmentDriverName = this._attachmentDriverNameFor({model, name})
     const now = Date.now()
     const recordType = model.getModelClass().getModelName()
     const recordId = String(model.id())
     const attachmentId = generateUUID()
-    const {storageKey} = await attachmentDriver.write({
-      attachmentId,
-      input: normalizedInput,
-      model,
-      name
-    })
+    /**
+     * Written storage key.
+     * @type {string | null} */
+    let storageKey = null
+    let rowPersisted = false
+
+    try {
+      const writeResult = await attachmentDriver.write({
+        attachmentId,
+        input: normalizedInput,
+        model,
+        name
+      })
+
+      storageKey = writeResult.storageKey
+
+      // Current schemas keep content_base64 nullable and avoid duplicating
+      // driver-backed content. Legacy path input was materialized once before
+      // the driver write so this value describes those exact persisted bytes.
+      const databaseContentBase64 = await this.databaseContentBase64For(normalizedInput)
+
+      await this._withDb(async (db) => {
+        if (replace) {
+          const existingRows = await db
+            .newQuery()
+            .from(ATTACHMENTS_TABLE)
+            .where({name, record_id: recordId, record_type: recordType})
+            .results()
+
+          for (const existingRow of existingRows) {
+            await this.deleteAttachmentRowStorage({model, name, row: existingRow})
+          }
+
+          await db.delete({
+            conditions: {name, record_id: recordId, record_type: recordType},
+            tableName: ATTACHMENTS_TABLE
+          })
+        }
 
-    await this._withDb(async (db) => {
-      if (replace) {
-        const existingRows = await db
-          .newQuery()
-          .from(ATTACHMENTS_TABLE)
-          .where({name, record_id: recordId, record_type: recordType})
-          .results()
+        const position = replace ? 0 : await this._nextPosition({db, name, recordId, recordType})
+        /**
+         * Insert data.
+         * @type {Record<string, ?>} */
+        const insertData = {
+          byte_size: normalizedInput.byteSize,
+          content_base64: databaseContentBase64,
+          content_type: normalizedInput.contentType,
+          created_at_ms: now,
+          filename: normalizedInput.filename,
+          id: attachmentId,
+          name,
+          position,
+          record_id: recordId,
+          record_type: recordType,
+          updated_at_ms: now
+        }
 
-        for (const existingRow of existingRows) {
-          await this.deleteAttachmentRowStorage({model, name, row: existingRow})
+        if (this._driverColumnsAvailable) {
+          insertData.driver = attachmentDriverName
+          insertData.storage_key = storageKey
         }
 
-        await db.delete({
-          conditions: {name, record_id: recordId, record_type: recordType},
+        await db.insert({
+          data: insertData,
           tableName: ATTACHMENTS_TABLE
         })
-      }
 
-      const position = replace ? 0 : await this._nextPosition({db, name, recordId, recordType})
-      /**
-       * Insert data.
-       * @type {Record<string, ?>} */
-      const insertData = {
-        byte_size: normalizedInput.byteSize,
-        content_base64: this._contentBase64Nullable ? null : normalizedInput.contentBase64,
-        content_type: normalizedInput.contentType,
-        created_at_ms: now,
-        filename: normalizedInput.filename,
-        id: attachmentId,
-        name,
-        position,
-        record_id: recordId,
-        record_type: recordType,
-        updated_at_ms: now
+        rowPersisted = true
+      })
+    } catch (error) {
+      if (!rowPersisted && storageKey && typeof attachmentDriver.delete === "function") {
+        try {
+          await attachmentDriver.delete({
+            model,
+            name,
+            row: {id: attachmentId, storage_key: storageKey},
+            storageKey
+          })
+        } catch (cleanupError) {
+          throw new AggregateError(
+            [error, cleanupError],
+            `Attachment write finalization and new-storage cleanup both failed for ${recordType}#${recordId} (${name})`,
+            {cause: cleanupError}
+          )
+        }
       }
 
-      if (this._driverColumnsAvailable) {
-        insertData.driver = attachmentDriverName
-        insertData.storage_key = storageKey
-      }
+      throw error
+    }
+  }
 
-      await db.insert({
-        data: insertData,
-        tableName: ATTACHMENTS_TABLE
-      })
-    })
+  /**
+   * Resolves the database content_base64 value for current and legacy schemas.
+   * @param {import("./normalize-input.js").NormalizedAttachmentInput} normalizedInput - Normalized attachment input.
+   * @returns {Promise<string | null>} - Nullable or legacy Base64 database value.
+   */
+  async databaseContentBase64For(normalizedInput) {
+    if (this._contentBase64Nullable) return null
+    if (normalizedInput.contentBase64 !== null) return normalizedInput.contentBase64
+
+    throw new Error("Legacy attachment schema requires materialized content bytes")
   }
 
   /**

package/build/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/build/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")