velocious 1.0.567 → 1.0.569

package/src/database/query/model-class-query.js

@@ -24,7 +24,7 @@ import WhereParser from "../query-parser/where-parser.js"
 /**
  * Defines this typedef.
  * @template {typeof import("../record/index.js").default} [MC=typeof import("../record/index.js").default]
- * @typedef {import("./index.js").QueryArgsType & {modelClass: MC, joinBasePath?: string[], joinTracker?: import("./join-tracker.js").default, forceQualifyBaseTable?: boolean, withCount?: import("./with-count.js").WithCountEntry[], queryData?: import("./query-data.js").QueryDataEntry[]}} ModelClassQueryArgsType
+ * @typedef {import("./index.js").QueryArgsType & {modelClass: MC, joinBasePath?: string[], joinTracker?: import("./join-tracker.js").default, forceQualifyBaseTable?: boolean, withCount?: import("./with-count.js").WithCountEntry[], queryData?: import("./query-data.js").QueryDataEntry[], operation?: import("../operation.js").default}} ModelClassQueryArgsType
  */
 /**
  * Runs unquote sql identifier.
@@ -200,6 +200,7 @@ export default class VelociousDatabaseQueryModelClassQuery extends DatabaseQuery
     this._joinBasePath = args.joinBasePath || []
     this._joinTracker = args.joinTracker || new JoinTracker({modelClass: this.modelClass})
     this._forceQualifyBaseTable = Boolean(args.forceQualifyBaseTable)
+    this._operation = args.operation
 
     /**
      * Narrows the runtime value to the documented type.
@@ -240,7 +241,8 @@ export default class VelociousDatabaseQueryModelClassQuery extends DatabaseQuery
       joinTracker: this._joinTracker.clone(),
       forceQualifyBaseTable: this._forceQualifyBaseTable,
       withCount: [...this._withCount],
-      queryData: [...this._queryData]
+      queryData: [...this._queryData],
+      operation: this._operation
     }))
 
     // @ts-expect-error
@@ -723,7 +725,11 @@ export default class VelociousDatabaseQueryModelClassQuery extends DatabaseQuery
    * @returns {VelociousDatabaseQueryModelClassQuery<MC>} - The scoped join query.
    */
   buildJoinScopeQuery(targetModelClass, joinPath) {
-    const scopedQuery = /** @type {VelociousDatabaseQueryModelClassQuery<MC>} */ (targetModelClass._newQuery())
+    const scopedQuery = /** @type {VelociousDatabaseQueryModelClassQuery<MC>} */ (
+      this._operation
+        ? this._operation.forModel(targetModelClass)
+        : targetModelClass._newQuery()
+    )
 
     scopedQuery._joinTracker = this._joinTracker
     scopedQuery._joinBasePath = joinPath
@@ -864,8 +870,7 @@ export default class VelociousDatabaseQueryModelClassQuery extends DatabaseQuery
 
     if (record) return record
 
-    const ModelClass = this.getModelClass()
-    const newRecord = /** @type {InstanceType<MC>} */ (new ModelClass(conditions))
+    const newRecord = this.build(conditions)
 
     if (callback) {
       callback(newRecord)
@@ -874,6 +879,33 @@ export default class VelociousDatabaseQueryModelClassQuery extends DatabaseQuery
     return newRecord
   }
 
+  /**
+   * Builds a record owned by the query's operation, when present.
+   * @param {Record<string, ?>} [attributes] - Initial attributes.
+   * @returns {InstanceType<MC>} - Built record.
+   */
+  build(attributes = {}) {
+    const ModelClass = this.getModelClass()
+    const record = /** @type {InstanceType<MC>} */ (new ModelClass(attributes))
+
+    if (this._operation) this._operation.bindRecord(record)
+
+    return record
+  }
+
+  /**
+   * Creates a record owned by the query's operation, when present.
+   * @param {Record<string, ?>} [attributes] - Initial attributes.
+   * @returns {Promise<InstanceType<MC>>} - Created record.
+   */
+  async create(attributes = {}) {
+    const record = this.build(attributes)
+
+    await record.save()
+
+    return record
+  }
+
   /**
    * Runs first.
    * @returns {Promise<InstanceType<MC> | null>} - Resolves with the first.
@@ -917,8 +949,7 @@ export default class VelociousDatabaseQueryModelClassQuery extends DatabaseQuery
     const results = await this.results()
 
     for (const result of results) {
-      const ModelClass = this.getModelClass()
-      const model = /** @type {InstanceType<MC>} */ (new ModelClass())
+      const model = this.build()
 
       model.loadExistingRecord(result)
       models.push(model)

package/src/database/query/preloader/belongs-to.js

@@ -2,6 +2,7 @@
 
 import ensureModelClassInitialized from "./ensure-model-class-initialized.js"
 import PreloaderSelection from "./selection.js"
+import preloadQueryForModel from "./query-for-model.js"
 import restArgsError from "../../../utils/rest-args-error.js"
 
 export default class VelociousDatabaseQueryPreloaderBelongsTo {
@@ -94,7 +95,7 @@ export default class VelociousDatabaseQueryPreloaderBelongsTo {
       whereArgs[primaryKey] = [...foreignKeyValues]
 
       // Load target models to be preloaded on the given models
-      let query = targetModelClass.where(whereArgs)
+      let query = preloadQueryForModel(modelsToLoad, targetModelClass).where(whereArgs)
 
       query = this.relationship.applyScope(query)
       query = this.selection.applyToQuery({query, targetModelClass, mappingColumns: [primaryKey]})
@@ -211,7 +212,7 @@ export default class VelociousDatabaseQueryPreloaderBelongsTo {
 
       whereArgs[primaryKey] = [...foreignKeyValuesByType[targetType]]
 
-      let query = targetModelClass.where(whereArgs)
+      let query = preloadQueryForModel(this.models, targetModelClass).where(whereArgs)
 
       query = this.relationship.applyScope(query)
       query = this.selection.applyToQuery({query, targetModelClass, mappingColumns: [primaryKey]})

package/src/database/query/preloader/has-many.js

@@ -2,6 +2,7 @@
 
 import ensureModelClassInitialized from "./ensure-model-class-initialized.js"
 import PreloaderSelection from "./selection.js"
+import preloadQueryForModel from "./query-for-model.js"
 import restArgsError from "../../../utils/rest-args-error.js"
 
 /**
@@ -155,7 +156,7 @@ export default class VelociousDatabaseQueryPreloaderHasMany {
     }
 
     // Step 1: Query the through table to build parent→target ID mapping
-    const throughModels = await throughModelClass
+    const throughModels = await preloadQueryForModel(modelsToLoad, throughModelClass)
       .where({[throughForeignKey]: [...modelsPrimaryKeyValues]})
       .toArray()
 
@@ -186,7 +187,7 @@ export default class VelociousDatabaseQueryPreloaderHasMany {
     let targetModels = []
 
     if (allTargetIds.size > 0) {
-      let query = targetModelClass.where({[targetForeignKey]: [...allTargetIds]})
+      let query = preloadQueryForModel(modelsToLoad, targetModelClass).where({[targetForeignKey]: [...allTargetIds]})
 
       query = this.relationship.applyScope(query)
       query = this.selection.applyToQuery({query, targetModelClass, mappingColumns: [targetForeignKey]})
@@ -299,7 +300,7 @@ export default class VelociousDatabaseQueryPreloaderHasMany {
 
     await ensureModelClassInitialized(targetModelClass, this.relationship.getConfiguration())
 
-    let query = targetModelClass.where(whereArgs)
+    let query = preloadQueryForModel(modelsToLoad, targetModelClass).where(whereArgs)
 
     query = this.relationship.applyScope(query)
     query = this.selection.applyToQuery({query, targetModelClass, mappingColumns: [foreignKey]})

package/src/database/query/preloader/has-one.js

@@ -2,6 +2,7 @@
 
 import ensureModelClassInitialized from "./ensure-model-class-initialized.js"
 import PreloaderSelection from "./selection.js"
+import preloadQueryForModel from "./query-for-model.js"
 import restArgsError from "../../../utils/rest-args-error.js"
 
 export default class VelociousDatabaseQueryPreloaderHasOne {
@@ -87,7 +88,7 @@ export default class VelociousDatabaseQueryPreloaderHasOne {
     await ensureModelClassInitialized(targetModelClass, this.relationship.getConfiguration())
 
     // Load target models to be preloaded on the given models
-    let query = targetModelClass.where(whereArgs)
+    let query = preloadQueryForModel(this.models, targetModelClass).where(whereArgs)
 
     query = this.relationship.applyScope(query)
     query = this.selection.applyToQuery({query, targetModelClass, mappingColumns: [foreignKey]})

package/src/database/query/preloader/query-for-model.js

@@ -0,0 +1,17 @@
+// @ts-check
+
+/**
+ * Builds a target query preserving the explicit database operation owned by
+ * the source records.
+ * @template {typeof import("../../record/index.js").default} MC
+ * @param {import("../../record/index.js").default[]} models - Source records.
+ * @param {MC} ModelClass - Target model class.
+ * @returns {import("../model-class-query.js").default<MC>} - Target query.
+ */
+export default function preloadQueryForModel(models, ModelClass) {
+  const sourceModel = models[0]
+
+  if (!sourceModel) throw new Error("Cannot build a preload query without source records")
+
+  return sourceModel.queryForModel(ModelClass)
+}

package/src/database/query/query-data.js

@@ -190,7 +190,15 @@ export async function runQueryData({rootModelClass, rootModels, entries}) {
 
   const primaryKey = rootModelClass.primaryKey()
   const rootIds = rootModels.map((model) => /** @type {string | number} */ (model.readColumn(primaryKey)))
-  const preparedEntries = entries.map((entry, entryIndex) => prepareEntry({entry, entryIndex, primaryKey, rootIds, rootModelClass}))
+  const sourceModel = rootModels[0]
+  const preparedEntries = entries.map((entry, entryIndex) => prepareEntry({
+    entry,
+    entryIndex,
+    primaryKey,
+    rootIds,
+    rootModelClass,
+    sourceModel
+  }))
   /**
    * Compatible query groups.
    * @type {Array<{aliases: Set<string>, query: import("./model-class-query.js").default, signature: string}>} */
@@ -231,9 +239,10 @@ export async function runQueryData({rootModelClass, rootModels, entries}) {
  * @param {string} args.primaryKey - Root model primary key column.
  * @param {Array<string | number>} args.rootIds - Root primary-key values.
  * @param {typeof import("../record/index.js").default} args.rootModelClass - Root model class.
+ * @param {import("../record/index.js").default} args.sourceModel - Loaded operation owner.
  * @returns {{aliases: string[], query: import("./model-class-query.js").default, signature: string}} - Prepared entry.
  */
-function prepareEntry({entry, entryIndex, primaryKey, rootIds, rootModelClass}) {
+function prepareEntry({entry, entryIndex, primaryKey, rootIds, rootModelClass, sourceModel}) {
   const targetModelClass = resolveTargetModelClass(rootModelClass, entry.chain)
   const fn = targetModelClass.getQueryDataByName(entry.fnName)
 
@@ -242,7 +251,7 @@ function prepareEntry({entry, entryIndex, primaryKey, rootIds, rootModelClass})
       `Declare it with ${targetModelClass.name}.queryData(${JSON.stringify(entry.fnName)}, ({query, tableName}) => query.select(...))`)
   }
 
-  const query = rootModelClass._newQuery()
+  const query = sourceModel.queryForModel(rootModelClass)
 
   // Empty out any defaults the query factory added — queryData runs
   // a bare aggregate, not a full model load.

package/src/database/query/with-count.js

@@ -111,10 +111,11 @@ export async function runWithCount({models, modelClass, entries}) {
 
   const primaryKey = modelClass.primaryKey()
   const parentIds = models.map((model) => /** @type {string | number} */ (model.readColumn(primaryKey)))
+  const sourceModel = models[0]
   const queryGroups = new Map()
 
   for (const entry of entries) {
-    const countQuery = queryForEntry({entry, modelClass, parentIds})
+    const countQuery = queryForEntry({entry, modelClass, parentIds, sourceModel})
     const sql = countQuery.toSql()
     const existingGroup = queryGroups.get(sql)
 
@@ -138,9 +139,10 @@ export async function runWithCount({models, modelClass, entries}) {
  * @param {WithCountEntry} args.entry - Entry being evaluated.
  * @param {typeof import("../record/index.js").default} args.modelClass - Parent model class.
  * @param {Array<string | number>} args.parentIds - Primary keys of the loaded parents.
+ * @param {import("../record/index.js").default} args.sourceModel - Loaded operation owner.
  * @returns {import("./model-class-query.js").default} - Prepared count query.
  */
-function queryForEntry({entry, modelClass, parentIds}) {
+function queryForEntry({entry, modelClass, parentIds, sourceModel}) {
   const relationship = modelClass.getRelationshipByName(entry.relationshipName)
 
   if (!relationship) {
@@ -172,7 +174,7 @@ function queryForEntry({entry, modelClass, parentIds}) {
     Object.assign(whereConditions, entry.where)
   }
 
-  const baseQuery = targetModelClass._newQuery()
+  const baseQuery = sourceModel.queryForModel(targetModelClass)
   baseQuery._forceQualifyBaseTable = true
   baseQuery.where(whereConditions)
 

package/src/database/record/acts-as-list.js

@@ -173,7 +173,7 @@ function assertPositivePosition({position, positionColumn, persisted = false}) {
  */
 async function placeMovedRecord({record, positionColumn, scope, scopeValue, position}) {
   const modelClass = /** @type {typeof import("./index.js").default} */ (record.constructor)
-  const connection = modelClass.connection()
+  const connection = record.connection()
   const tableSql = connection.quoteTable(modelClass._getTable().getName())
   const scopeCol = modelClass.getColumnNameForAttributeName(scope)
   const posCol = modelClass.getColumnNameForAttributeName(positionColumn)
@@ -224,7 +224,7 @@ function clearBelongsToChangeForScope(record) {
  */
 async function shiftPositionsUp({record, positionColumn, scope, fromPosition, toPosition, scopeValue, excludeRecordId}) {
   const modelClass = /** @type {typeof import("./index.js").default} */ (record.constructor)
-  const connection = modelClass.connection()
+  const connection = record.connection()
   const tableName = modelClass._getTable().getName()
   const resolvedScopeValue = scopeValue != null ? scopeValue : resolveScopeValue(record, scope)
   const scopeColumnName = modelClass.getColumnNameForAttributeName(scope)
@@ -239,7 +239,8 @@ async function shiftPositionsUp({record, positionColumn, scope, fromPosition, to
   const quotedScope = connection.quote(resolvedScopeValue)
 
   // Load rows in descending order so we bump the highest first
-  let query = modelClass
+  let query = record
+    .queryForModel(modelClass)
     .select(modelClass.primaryKey())
     .select(positionColumn)
     .where({[scopeColumnName]: resolvedScopeValue})
@@ -289,7 +290,7 @@ async function shiftPositionsUp({record, positionColumn, scope, fromPosition, to
  */
 async function shiftPositionsDown({record, positionColumn, scope, fromPosition, toPosition, scopeValue}) {
   const modelClass = /** @type {typeof import("./index.js").default} */ (record.constructor)
-  const connection = modelClass.connection()
+  const connection = record.connection()
   const tableName = modelClass._getTable().getName()
   const resolvedScopeValue = scopeValue != null ? scopeValue : resolveScopeValue(record, scope)
   const scopeColumnName = modelClass.getColumnNameForAttributeName(scope)
@@ -304,7 +305,8 @@ async function shiftPositionsDown({record, positionColumn, scope, fromPosition,
   const quotedScope = connection.quote(resolvedScopeValue)
 
   // Load rows in ascending order so we shift the lowest gap first
-  let query = modelClass
+  let query = record
+    .queryForModel(modelClass)
     .select(modelClass.primaryKey())
     .select(positionColumn)
     .where({[scopeColumnName]: resolvedScopeValue})
@@ -345,7 +347,7 @@ async function shiftPositionsDown({record, positionColumn, scope, fromPosition,
  */
 async function highestPositionInScope({record, positionColumn, scope, scopeValue}) {
   const modelClass = /** @type {typeof import("./index.js").default} */ (record.constructor)
-  const connection = modelClass.connection()
+  const connection = record.connection()
   const scopeColumnName = modelClass.getColumnNameForAttributeName(scope)
   const positionColumnName = modelClass.getColumnNameForAttributeName(positionColumn)
   const positionColumnSql = connection.quoteColumn(positionColumnName)
@@ -353,7 +355,8 @@ async function highestPositionInScope({record, positionColumn, scope, scopeValue
 
   if (resolvedScopeValue == null) return 0
 
-  const rows = await modelClass
+  const rows = await record
+    .queryForModel(modelClass)
     .select(positionColumn)
     .where({[scopeColumnName]: resolvedScopeValue})
     .order(`${positionColumnSql} DESC`)
@@ -415,7 +418,7 @@ function resolveScopeValue(record, scope) {
  */
 async function moveOutOfWay({record, positionColumn, scope, scopeValue}) {
   const modelClass = /** @type {typeof import("./index.js").default} */ (record.constructor)
-  const connection = modelClass.connection()
+  const connection = record.connection()
   const tableName = modelClass._getTable().getName()
   const resolvedScopeValue = scopeValue != null ? scopeValue : resolveScopeValue(record, scope)
 

package/src/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/src/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/src/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/src/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}
   }