@visulima/storage 1.0.0-alpha.1 → 1.0.0-alpha.3

package/dist/packem_shared/disk-storage-Bh2wy3YW.js

@@ -0,0 +1,810 @@
+import { createReadStream, createWriteStream } from 'node:fs';
+import { truncate, stat as stat$1, copyFile as copyFile$1 } from 'node:fs/promises';
+import { PassThrough, Transform, pipeline } from 'node:stream';
+import { g as getDefaultExportFromCjs } from './_commonjsHelpers-B85MJLTf.js';
+import require$$0 from 'crypto';
+import require$$1 from 'fs';
+import { g as getFileStatus, p as partMatch, d as detectFileTypeFromStream } from './part-match-BMNqHDYD.js';
+import { throwErrorCode, isUploadError, ERRORS } from './ERRORS-D0apMqnc.js';
+import { createHash } from 'node:crypto';
+import { B as BaseStorage, a as defaultFilesystemFileNameValidation, t as toMilliseconds } from './storage-C6NSXb8h.js';
+import { a as assertValidFileOrDirectoryPath, g as getFileInfoType, e as ensureDir, t as toPath, i as isAccessible, L as LocalMetaStorage, b as readFile, r as remove } from './local-meta-storage-By-3SNBI.js';
+import File from './File-Bb3P23dr.js';
+import { createRequire } from 'node:module';
+import { d as dirname, r as resolve, j as join, n as normalize, b as basename, i as isAbsolute } from './path-CR6YkPXX-7R1-9CMk.js';
+import { u as updateSize } from './update-size-CCGm6i1J.js';
+import { h as hasContent } from './has-content-CY66ehMK.js';
+
+const __cjs_require$2 = createRequire(import.meta.url);
+const __cjs_getProcess$2 = typeof globalThis !== "undefined" && typeof globalThis.process !== "undefined" ? globalThis.process : process;
+const __cjs_getBuiltinModule$2 = (module) => {
+  if (typeof __cjs_getProcess$2 !== "undefined" && __cjs_getProcess$2.versions && __cjs_getProcess$2.versions.node) {
+    const [major, minor] = __cjs_getProcess$2.versions.node.split(".").map(Number);
+    if (major > 22 || major === 22 && minor >= 3 || major === 20 && minor >= 16) {
+      return __cjs_getProcess$2.getBuiltinModule(module);
+    }
+  }
+  return __cjs_require$2(module);
+};
+const {
+  lstat,
+  writeFile
+} = __cjs_getBuiltinModule$2("node:fs/promises");
+const ensureFile = async (filePath) => {
+  assertValidFileOrDirectoryPath(filePath);
+  try {
+    const stat = await lstat(filePath);
+    if (!stat.isFile()) {
+      throw new Error(`Ensure path exists, expected 'file', got '${getFileInfoType(stat)}'`);
+    }
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      await ensureDir(dirname(toPath(filePath)));
+      await writeFile(filePath, new Uint8Array());
+      return;
+    }
+    throw error;
+  }
+};
+
+class WalkError extends Error {
+  /** File path of the root that's being walked. */
+  root;
+  /**
+   * Constructs a new instance.
+   * @param cause The underlying error or reason for the walk failure.
+   * @param root The root directory path where the walk operation started or encountered the error.
+   */
+  constructor(cause, root) {
+    super(`${cause instanceof Error ? cause.message : cause} for path "${root}"`);
+    this.cause = cause;
+    this.root = root;
+  }
+  // eslint-disable-next-line class-methods-use-this
+  get name() {
+    return "WalkError";
+  }
+  // eslint-disable-next-line class-methods-use-this,@typescript-eslint/explicit-module-boundary-types
+  set name(_name) {
+    throw new Error("Cannot overwrite name of WalkError");
+  }
+}
+
+const globToRegExp = (glob) => {
+  const reString = glob.replace(/\.\*/g, ".([^/]*)").replace(/\*\*/g, "(.*)").replace(/(?<!\.)\*(?!\*)/g, "([^/]*)").replace(/\?/g, "[^/]").replace(/\.(?!\*)/g, String.raw`\.`).replace(/\{/g, "(").replace(/\}/g, ")").replace(/,/g, "|").replace(/\[!(.*?)\]/g, "[^$1]");
+  return new RegExp(`^${reString}$`);
+};
+const walkInclude = (path, extensions, match, skip) => {
+  if (Array.isArray(extensions) && extensions.length > 0 && !extensions.some((extension) => path.endsWith(extension))) {
+    return false;
+  }
+  if (match && !match.some((pattern) => pattern.test(path))) {
+    return false;
+  }
+  return !skip?.some((pattern) => pattern.test(path));
+};
+
+const __cjs_require$1 = createRequire(import.meta.url);
+const __cjs_getProcess$1 = typeof globalThis !== "undefined" && typeof globalThis.process !== "undefined" ? globalThis.process : process;
+const __cjs_getBuiltinModule$1 = (module) => {
+  if (typeof __cjs_getProcess$1 !== "undefined" && __cjs_getProcess$1.versions && __cjs_getProcess$1.versions.node) {
+    const [major, minor] = __cjs_getProcess$1.versions.node.split(".").map(Number);
+    if (major > 22 || major === 22 && minor >= 3 || major === 20 && minor >= 16) {
+      return __cjs_getProcess$1.getBuiltinModule(module);
+    }
+  }
+  return __cjs_require$1(module);
+};
+const {
+  readdir,
+  realpath,
+  stat
+} = __cjs_getBuiltinModule$1("node:fs/promises");
+const _createWalkEntry = async (path) => {
+  const normalizePath = normalize(path);
+  const name = basename(normalizePath);
+  const info = await stat(normalizePath);
+  return {
+    isDirectory: () => info.isDirectory(),
+    isFile: () => info.isFile(),
+    isSymbolicLink: () => info.isSymbolicLink(),
+    name,
+    path: normalizePath
+  };
+};
+async function* walk(directory, {
+  extensions,
+  followSymlinks = false,
+  includeDirs: includeDirectories = true,
+  includeFiles = true,
+  includeSymlinks = true,
+  match,
+  maxDepth = Number.POSITIVE_INFINITY,
+  skip
+} = {}) {
+  assertValidFileOrDirectoryPath(directory);
+  if (maxDepth < 0) {
+    return;
+  }
+  const mappedMatch = match ? match.map((pattern) => typeof pattern === "string" ? globToRegExp(pattern) : pattern) : void 0;
+  const mappedSkip = skip ? skip.map((pattern) => typeof pattern === "string" ? globToRegExp(pattern) : pattern) : void 0;
+  directory = resolve(toPath(directory));
+  if (includeDirectories && walkInclude(directory, extensions, mappedMatch, mappedSkip)) {
+    yield await _createWalkEntry(directory);
+  }
+  if (maxDepth < 1 || !walkInclude(directory, void 0, void 0, mappedSkip)) {
+    return;
+  }
+  try {
+    for await (const entry of await readdir(directory, {
+      withFileTypes: true
+    })) {
+      let path = join(directory, entry.name);
+      if (entry.isSymbolicLink()) {
+        if (followSymlinks) {
+          path = await realpath(path);
+        } else if (includeSymlinks && walkInclude(path, extensions, mappedMatch, mappedSkip)) {
+          yield {
+            isDirectory: entry.isDirectory,
+            isFile: entry.isFile,
+            isSymbolicLink: entry.isSymbolicLink,
+            name: entry.name,
+            path
+          };
+        } else {
+          continue;
+        }
+      }
+      if (entry.isSymbolicLink() || entry.isDirectory()) {
+        yield* walk(path, {
+          extensions,
+          followSymlinks,
+          includeDirs: includeDirectories,
+          includeFiles,
+          includeSymlinks,
+          match: mappedMatch,
+          maxDepth: maxDepth - 1,
+          skip: mappedSkip
+        });
+      } else if (entry.isFile() && includeFiles && walkInclude(path, extensions, mappedMatch, mappedSkip)) {
+        yield {
+          isDirectory: () => entry.isDirectory(),
+          isFile: () => entry.isFile(),
+          isSymbolicLink: () => entry.isSymbolicLink(),
+          name: entry.name,
+          path
+        };
+      }
+    }
+  } catch (error) {
+    if (error instanceof WalkError) {
+      throw error;
+    }
+    throw new WalkError(error, directory);
+  }
+}
+
+const __cjs_require = createRequire(import.meta.url);
+const __cjs_getProcess = typeof globalThis !== "undefined" && typeof globalThis.process !== "undefined" ? globalThis.process : process;
+const __cjs_getBuiltinModule = (module) => {
+  if (typeof __cjs_getProcess !== "undefined" && __cjs_getProcess.versions && __cjs_getProcess.versions.node) {
+    const [major, minor] = __cjs_getProcess.versions.node.split(".").map(Number);
+    if (major > 22 || major === 22 && minor >= 3 || major === 20 && minor >= 16) {
+      return __cjs_getProcess.getBuiltinModule(module);
+    }
+  }
+  return __cjs_require(module);
+};
+const {
+  cwd
+} = __cjs_getProcess;
+const {
+  mkdir,
+  rename: rename$1,
+  copyFile,
+  unlink
+} = __cjs_getBuiltinModule("node:fs/promises");
+__cjs_getBuiltinModule("node:fs");
+class SameDirectoryError extends Error {
+  constructor(source, destination) {
+    super(`Source directory "${dirname(source)}" does not match destination directory "${dirname(destination)}"`);
+    this.name = "SameDirectoryError";
+  }
+}
+const validateSameDirectory = (source, destination) => {
+  if (!source || !destination) {
+    throw new Error("Source and destination paths must not be empty");
+  }
+  if (dirname(source) !== dirname(destination)) {
+    throw new SameDirectoryError(source, destination);
+  }
+};
+const internalMoveFile = async (sourcePath, destinationPath, { cwd: cwd2, directoryMode, overwrite, validateDirectory }) => {
+  if (cwd2) {
+    sourcePath = resolve(cwd2, sourcePath);
+    destinationPath = resolve(cwd2, destinationPath);
+  }
+  if (validateDirectory) {
+    validateSameDirectory(sourcePath, destinationPath);
+  }
+  if (!overwrite && await isAccessible(destinationPath)) {
+    throw new Error(`The destination file exists: ${destinationPath}`);
+  }
+  await mkdir(dirname(destinationPath), {
+    mode: directoryMode,
+    recursive: true
+  });
+  try {
+    await rename$1(sourcePath, destinationPath);
+  } catch (error) {
+    if (error.code === "EXDEV") {
+      await copyFile(sourcePath, destinationPath);
+      await unlink(sourcePath);
+    } else {
+      throw error;
+    }
+  }
+};
+const move = async (sourcePath, destinationPath, options = {}) => {
+  const internalOptions = {
+    overwrite: true,
+    validateDirectory: false,
+    ...options,
+    cwd: options.cwd ? toPath(options.cwd) : cwd()
+  };
+  await internalMoveFile(sourcePath, destinationPath, internalOptions);
+};
+
+var etag_1;
+var hasRequiredEtag;
+
+function requireEtag () {
+	if (hasRequiredEtag) return etag_1;
+	hasRequiredEtag = 1;
+	/*!
+	 * etag
+	 * Copyright(c) 2014-2016 Douglas Christopher Wilson
+	 * MIT Licensed
+	 */
+	etag_1 = etag;
+	var crypto = require$$0;
+	var Stats = require$$1.Stats;
+	var toString = Object.prototype.toString;
+	function entitytag(entity) {
+	  if (entity.length === 0) {
+	    return '"0-2jmj7l5rSw0yVb/vlWAYkK/YBwk"';
+	  }
+	  var hash = crypto.createHash("sha1").update(entity, "utf8").digest("base64").substring(0, 27);
+	  var len = typeof entity === "string" ? Buffer.byteLength(entity, "utf8") : entity.length;
+	  return '"' + len.toString(16) + "-" + hash + '"';
+	}
+	function etag(entity, options) {
+	  if (entity == null) {
+	    throw new TypeError("argument entity is required");
+	  }
+	  var isStats = isstats(entity);
+	  var weak = options && typeof options.weak === "boolean" ? options.weak : isStats;
+	  if (!isStats && typeof entity !== "string" && !Buffer.isBuffer(entity)) {
+	    throw new TypeError("argument entity must be string, Buffer, or fs.Stats");
+	  }
+	  var tag = isStats ? stattag(entity) : entitytag(entity);
+	  return weak ? "W/" + tag : tag;
+	}
+	function isstats(obj) {
+	  if (typeof Stats === "function" && obj instanceof Stats) {
+	    return true;
+	  }
+	  return obj && typeof obj === "object" && "ctime" in obj && toString.call(obj.ctime) === "[object Date]" && "mtime" in obj && toString.call(obj.mtime) === "[object Date]" && "ino" in obj && typeof obj.ino === "number" && "size" in obj && typeof obj.size === "number";
+	}
+	function stattag(stat) {
+	  var mtime = stat.mtime.getTime().toString(16);
+	  var size = stat.size.toString(16);
+	  return '"' + size + "-" + mtime + '"';
+	}
+	return etag_1;
+}
+
+var etagExports = requireEtag();
+const etag = /*@__PURE__*/getDefaultExportFromCjs(etagExports);
+
+class StreamChecksum extends Transform {
+  /**
+   * Creates a new StreamChecksum transform stream.
+   * @param checksum Expected checksum value to validate against
+   * @param algorithm Hash algorithm to use (e.g., 'md5', 'sha256')
+   * @param encoding Encoding for the checksum comparison (defaults to 'base64')
+   */
+  constructor(checksum, algorithm, encoding = "base64") {
+    super();
+    this.checksum = checksum;
+    this.algorithm = algorithm;
+    this.encoding = encoding;
+    this.hash = createHash(algorithm);
+  }
+  length = 0;
+  digest = "";
+  hash;
+  /**
+   * Gets the calculated digest value after the stream has finished processing.
+   * @returns The digest value in the configured encoding, or empty string if not yet calculated
+   */
+  get calculatedDigest() {
+    return this.digest;
+  }
+  /**
+   * Transform method that updates the hash with incoming data.
+   * @param chunk Buffer chunk to process
+   * @param _encoding Unused encoding parameter
+   * @param done Callback to signal completion
+   */
+  // eslint-disable-next-line no-underscore-dangle
+  _transform(chunk, _encoding, done) {
+    this.push(chunk);
+    this.hash.update(chunk);
+    this.length += chunk.length;
+    done();
+  }
+  /**
+   * Finalization method that validates the checksum.
+   * @param callback Callback called with error if checksum validation fails
+   */
+  // eslint-disable-next-line no-underscore-dangle
+  _flush(callback) {
+    this.digest = this.hash.digest(this.encoding);
+    if (this.checksum && this.checksum !== this.digest) {
+      callback(new Error("Checksum mismatch"));
+    } else {
+      callback();
+    }
+  }
+}
+const streamChecksum = (checksum, algorithm, encoding = "base64") => algorithm ? new StreamChecksum(checksum, algorithm, encoding) : new PassThrough();
+
+class StreamLength extends Transform {
+  /**
+   * Creates a new StreamLength transform stream.
+   * @param limit Maximum number of bytes allowed (defaults to infinity)
+   */
+  constructor(limit = Number.POSITIVE_INFINITY) {
+    super();
+    this.limit = limit;
+  }
+  length = 0;
+  /**
+   * Transform method that counts bytes and enforces size limits.
+   * @param chunk Buffer chunk to process
+   * @param _encoding Unused encoding parameter
+   * @param callback Callback called with error if limit exceeded
+   */
+  // eslint-disable-next-line no-underscore-dangle
+  _transform(chunk, _encoding, callback) {
+    const expected = this.length + chunk.length;
+    if (this.limit >= expected) {
+      this.push(chunk);
+      this.length = expected;
+      callback();
+    } else {
+      callback(new Error("Stream length limit exceeded"));
+    }
+  }
+}
+
+class DiskStorage extends BaseStorage {
+  static name = "disk";
+  checksumTypes = ["md5", "sha1"];
+  directory;
+  meta;
+  constructor(config) {
+    super(config);
+    this.directory = config.directory;
+    if (config.metaStorage) {
+      this.meta = config.metaStorage;
+    } else {
+      const metaConfig = { ...config, ...config.metaStorageConfig, logger: this.logger };
+      this.meta = new LocalMetaStorage(metaConfig);
+    }
+    if (!config.fileNameValidation) {
+      config.fileNameValidation = defaultFilesystemFileNameValidation;
+    }
+    this.isReady = false;
+    this.accessCheck().then(() => {
+      this.isReady = true;
+      return void 0;
+    }).catch((error) => {
+      this.logger?.error("Storage access check failed: %O", error);
+    });
+  }
+  /**
+   * Normalizes errors with disk storage context.
+   * @param error The error to normalize.
+   * @returns Normalized HTTP error.
+   */
+  normalizeError(error) {
+    return super.normalizeError(error);
+  }
+  /**
+   * Creates a new file upload and saves its metadata.
+   * @param fileInit File initialization configuration.
+   * @returns Promise resolving to the created file object.
+   * @throws {Error} If validation fails or file already exists and is completed.
+   * @remarks
+   * Supports TTL (time-to-live) option in fileInit.
+   * Creates the file on disk if it doesn't exist.
+   * Returns existing file if it's already completed.
+   */
+  async create(fileInit) {
+    return this.instrumentOperation("create", async () => {
+      const processedConfig = { ...fileInit };
+      if (fileInit.ttl) {
+        const ttlMs = typeof fileInit.ttl === "string" ? toMilliseconds(fileInit.ttl) : fileInit.ttl;
+        if (ttlMs !== void 0) {
+          processedConfig.expiredAt = Date.now() + ttlMs;
+        }
+      }
+      if (processedConfig.size !== void 0 && Number(processedConfig.size) < 0) {
+        throwErrorCode(ERRORS.REQUEST_ENTITY_TOO_LARGE, "Request entity too large");
+      }
+      const file = new File(processedConfig);
+      try {
+        const existing = await this.getMeta(file.id);
+        if (existing.status === "completed") {
+          return existing;
+        }
+      } catch {
+      }
+      file.name = this.namingFunction(file);
+      if (file.size === void 0 || Number.isNaN(file.size)) {
+        if (file.size === void 0) ; else {
+          file.size = this.maxUploadSize;
+        }
+      }
+      await this.validate(file);
+      const path = this.getFilePath(file.name);
+      try {
+        await ensureFile(path);
+        file.bytesWritten = 0;
+      } catch (error) {
+        const httpError = this.normalizeError(error instanceof Error ? error : new Error(String(error)));
+        await this.onError(httpError);
+        throwErrorCode(ERRORS.FILE_ERROR, httpError.message);
+      }
+      file.status = getFileStatus(file);
+      await this.saveMeta(file);
+      await this.onCreate(file);
+      return file;
+    });
+  }
+  /**
+   * Writes data to a file upload.
+   * @param part File part containing data to write, file query, or full file object.
+   * @returns Promise resolving to the updated file object.
+   * @throws {Error} If file is expired (ERRORS.GONE), locked (ERRORS.FILE_LOCKED), or conflicts occur (ERRORS.FILE_CONFLICT).
+   * @remarks
+   * Supports chunked uploads with start position.
+   * Automatically detects file type from stream on first chunk if contentType is not set.
+   * Validates checksum algorithms if provided.
+   * Uses file locking to prevent concurrent writes.
+   * Updates file status to "completed" when all bytes are written.
+   */
+  async write(part) {
+    return this.instrumentOperation("write", async () => {
+      let file;
+      const isFullFile = "contentType" in part && "metadata" in part && !("body" in part) && !("start" in part);
+      if (isFullFile) {
+        file = part;
+      } else {
+        file = await this.getMeta(part.id);
+        await this.checkIfExpired(file);
+      }
+      if (file.status === "completed") {
+        return file;
+      }
+      if (part.size !== void 0) {
+        updateSize(file, part.size);
+      }
+      if (!partMatch(part, file)) {
+        return throwErrorCode(ERRORS.FILE_CONFLICT);
+      }
+      const path = this.getFilePath(file.name);
+      await this.lock(path);
+      try {
+        const startPosition = part.start || 0;
+        await ensureFile(path);
+        if (file.bytesWritten === 0) {
+          file.bytesWritten = startPosition;
+        }
+        if (hasContent(part)) {
+          if (this.isUnsupportedChecksum(part.checksumAlgorithm)) {
+            return throwErrorCode(ERRORS.UNSUPPORTED_CHECKSUM_ALGORITHM);
+          }
+          const isFirstChunk = part.start === 0 || part.start === void 0;
+          if (isFirstChunk && (file.bytesWritten === 0 || Number.isNaN(file.bytesWritten)) && (!file.contentType || file.contentType === "application/octet-stream")) {
+            try {
+              const { fileType, stream: detectedStream } = await detectFileTypeFromStream(part.body);
+              if (fileType?.mime) {
+                file.contentType = fileType.mime;
+              }
+              part.body = detectedStream;
+            } catch {
+            }
+          }
+          const signalFromPart = part.signal;
+          const lazyWritePart = { ...file, ...part, body: part.body };
+          if (signalFromPart) {
+            lazyWritePart.signal = signalFromPart;
+          }
+          const [bytesWritten, errorCode] = await this.lazyWrite(lazyWritePart);
+          if (errorCode) {
+            await truncate(path, file.bytesWritten);
+            return throwErrorCode(errorCode);
+          }
+          const expectedBytesWritten = startPosition + (part.contentLength || 0);
+          file.bytesWritten = Math.max(file.bytesWritten || 0, expectedBytesWritten);
+          file.bytesWritten = Math.max(file.bytesWritten || 0, bytesWritten);
+          file.status = getFileStatus(file);
+          await this.saveMeta(file);
+        } else {
+          await ensureFile(path);
+          file.bytesWritten = 0;
+        }
+        return file;
+      } catch (error) {
+        if (isUploadError(error)) {
+          throw error;
+        }
+        const httpError = this.normalizeError(error instanceof Error ? error : new Error(String(error)));
+        await this.onError(httpError);
+        return throwErrorCode(ERRORS.FILE_ERROR, (typeof httpError.message === "string" ? httpError.message : String(error)) || String(error));
+      } finally {
+        await this.unlock(path);
+      }
+    });
+  }
+  /**
+   * Gets an uploaded file by ID.
+   * @param query File query containing the file ID to retrieve.
+   * @param query.id File ID to retrieve.
+   * @returns Promise resolving to the file data including content buffer.
+   * @throws {Error} If the file cannot be found (ERRORS.FILE_NOT_FOUND) or has expired (ERRORS.GONE).
+   * @remarks
+   * Loads the entire file content into memory as a Buffer.
+   * For large files, consider using getStream() instead.
+   * Includes ETag (MD5 hash) for content verification.
+   */
+  async get({ id }) {
+    return this.instrumentOperation("get", async () => {
+      const file = await this.checkIfExpired(await this.meta.get(id));
+      const { bytesWritten, contentType, expiredAt, metadata, modifiedAt, name, originalName, size } = file;
+      let content;
+      try {
+        content = await readFile(this.getFilePath(name), { buffer: true });
+      } catch (error) {
+        const errorWithCode = error;
+        if (errorWithCode.code === "ENOENT" || errorWithCode.code === "EPERM") {
+          const httpError2 = this.normalizeError(error instanceof Error ? error : new Error(errorWithCode.message || String(error)));
+          await this.onError(httpError2);
+          return throwErrorCode(ERRORS.FILE_NOT_FOUND, (typeof httpError2.message === "string" ? httpError2.message : String(error)) || String(error));
+        }
+        const httpError = this.normalizeError(error instanceof Error ? error : new Error(String(error)));
+        await this.onError(httpError);
+        throw error;
+      }
+      return {
+        content,
+        contentType,
+        ETag: etag(content),
+        expiredAt,
+        id,
+        metadata,
+        modifiedAt,
+        name,
+        originalName,
+        size: size || bytesWritten
+      };
+    });
+  }
+  /**
+   * Checks if a file exists by verifying both metadata and the actual filesystem file.
+   * Returns true only if both the metadata and the file exist.
+   * @param query File query containing the file ID to check.
+   * @returns Promise resolving to true if both metadata and file exist, false otherwise.
+   */
+  async exists({ id }) {
+    return this.instrumentOperation("exists", async () => {
+      try {
+        const file = await this.getMeta(id);
+        const filePath = this.getFilePath(file.name);
+        await stat$1(filePath);
+        return true;
+      } catch (error) {
+        const errorWithCode = error;
+        if (errorWithCode.code === "ENOENT") {
+          return false;
+        }
+        return false;
+      }
+    });
+  }
+  /**
+   * Gets an uploaded file as a readable stream for efficient large file handling.
+   * @param query File query containing the file ID to stream.
+   * @param query.id File ID to stream.
+   * @returns Promise resolving to an object containing the stream, headers, and size.
+   * @throws {UploadError} If the file cannot be found (ERRORS.FILE_NOT_FOUND) or has expired (ERRORS.GONE).
+   * @remarks Creates a readable stream directly from the file system for efficient memory usage.
+   */
+  async getStream({ id }) {
+    return this.instrumentOperation("getStream", async () => {
+      try {
+        const file = await this.checkIfExpired(await this.meta.get(id));
+        const { bytesWritten, contentType, expiredAt, modifiedAt, name, size } = file;
+        const stream = createReadStream(this.getFilePath(name));
+        return {
+          headers: {
+            "Content-Length": String(size || bytesWritten),
+            "Content-Type": contentType,
+            ...expiredAt && { "X-Upload-Expires": expiredAt.toString() },
+            ...modifiedAt && { "Last-Modified": modifiedAt.toString() }
+            // Note: ETag requires reading the file content, so we don't include it for streaming
+            // Clients can use HEAD requests to get ETag if needed
+          },
+          size: size || bytesWritten,
+          stream
+        };
+      } catch (error) {
+        const httpError = this.normalizeError(error instanceof Error ? error : new Error(String(error)));
+        await this.onError(httpError);
+        throw throwErrorCode(ERRORS.FILE_NOT_FOUND, (typeof httpError.message === "string" ? httpError.message : String(error)) || String(error));
+      }
+    });
+  }
+  /**
+   * Deletes an upload and its metadata.
+   * @param query File query containing the file ID to delete.
+   * @param query.id File ID to delete.
+   * @returns Promise resolving to the deleted file object with status: "deleted".
+   * @throws {UploadError} If the file metadata cannot be found.
+   */
+  async delete({ id }) {
+    return this.instrumentOperation("delete", async () => {
+      const file = await this.getMeta(id);
+      await remove(this.getFilePath(file.name));
+      await this.deleteMeta(id);
+      const deletedFile = { ...file, status: "deleted" };
+      await this.onDelete(deletedFile);
+      return deletedFile;
+    });
+  }
+  /**
+   * Copies an upload file to a new location.
+   * @param name Source file name/ID.
+   * @param destination Destination file name/ID.
+   * @returns Promise resolving to the copied file object.
+   * @throws {UploadError} If the source file cannot be found.
+   */
+  async copy(name, destination) {
+    return this.instrumentOperation("copy", async () => {
+      const sourceFile = await this.getMeta(name);
+      await copyFile$1(this.getFilePath(sourceFile.name), this.getFilePath(destination));
+      return { ...sourceFile, name: destination };
+    });
+  }
+  /**
+   * Moves an upload file to a new location.
+   * @param name Source file name/ID.
+   * @param destination Destination file name/ID.
+   * @returns Promise resolving to the moved file object.
+   * @throws {Error} If the source file cannot be found.
+   */
+  async move(name, destination) {
+    return this.instrumentOperation("move", async () => {
+      const sourceFile = await this.getMeta(name);
+      const source = this.getFilePath(sourceFile.name);
+      const destinationPath = this.getFilePath(destination);
+      try {
+        await move(source, destinationPath);
+      } catch (error) {
+        const errorWithCode = error;
+        if (errorWithCode?.code === "EXDEV") {
+          await copyFile$1(source, destinationPath);
+          await remove(source);
+        } else {
+          const httpError = this.normalizeError(error instanceof Error ? error : new Error(String(error)));
+          await this.onError(httpError);
+          throw error;
+        }
+      }
+      return { ...sourceFile, id: sourceFile.id, name: destination };
+    });
+  }
+  /**
+   * Retrieves a list of uploaded files.
+   * @returns Promise resolving to an array of file metadata objects.
+   * @remarks Walks the storage directory and returns all files, excluding metadata files.
+   */
+  async list() {
+    return this.instrumentOperation("list", async () => {
+      const config = {
+        followSymlinks: false,
+        includeDirs: false,
+        includeFiles: true,
+        skip: ["*.META$"]
+      };
+      const uploads = [];
+      const { directory } = this;
+      for await (const founding of walk(directory, config)) {
+        const { suffix } = this.meta;
+        const { path } = founding;
+        if (!path.includes(suffix)) {
+          const { birthtime, ctime, mtime } = await stat$1(path);
+          uploads.push({ createdAt: birthtime || ctime, id: path.replace(directory, ""), modifiedAt: mtime });
+        }
+      }
+      return uploads;
+    });
+  }
+  /**
+   * Returns path for the uploaded file
+   * If filename is already an absolute path, returns it as-is.
+   * Otherwise, joins it with the storage directory.
+   */
+  getFilePath(filename) {
+    if (isAbsolute(filename)) {
+      return filename;
+    }
+    return join(this.directory, filename);
+  }
+  lazyWrite(part) {
+    return new Promise((resolve, reject) => {
+      const destination = createWriteStream(this.getFilePath(part.name), { flags: "r+", start: part.start });
+      const lengthChecker = new StreamLength(part.contentLength || part.size - part.start);
+      const checksumChecker = streamChecksum(part.checksum, part.checksumAlgorithm);
+      const keepPartial = !part.checksum;
+      const { signal } = part;
+      const cleanupStreams = () => {
+        destination.close();
+        lengthChecker.destroy();
+        checksumChecker.destroy();
+      };
+      const failWithCode = (code) => {
+        cleanupStreams();
+        resolve([Number.NaN, code]);
+      };
+      lengthChecker.on("error", () => failWithCode(ERRORS.FILE_CONFLICT));
+      checksumChecker.on("error", () => failWithCode(ERRORS.CHECKSUM_MISMATCH));
+      part.body.on("aborted", () => failWithCode(keepPartial ? void 0 : ERRORS.REQUEST_ABORTED));
+      part.body.on("error", (error) => {
+        cleanupStreams();
+        reject(error);
+      });
+      if (signal?.aborted) {
+        return failWithCode(keepPartial ? void 0 : ERRORS.REQUEST_ABORTED);
+      }
+      if (signal) {
+        signal.addEventListener("abort", () => {
+          cleanupStreams();
+          destination.destroy();
+          lengthChecker.destroy();
+          checksumChecker.destroy();
+          part.body.destroy();
+          resolve([Number.NaN, keepPartial ? void 0 : ERRORS.REQUEST_ABORTED]);
+        });
+      }
+      pipeline(part.body, lengthChecker, checksumChecker, destination, (error) => {
+        if (error) {
+          cleanupStreams();
+          if (signal && signal.aborted) {
+            return resolve([Number.NaN, keepPartial ? void 0 : ERRORS.REQUEST_ABORTED]);
+          }
+          return resolve([Number.NaN, ERRORS.FILE_ERROR]);
+        }
+        return resolve([part.start + destination.bytesWritten]);
+      });
+    });
+  }
+  async accessCheck() {
+    await ensureDir(this.directory);
+  }
+}
+
+export { DiskStorage as D, StreamLength as S, ensureFile as e, streamChecksum as s };