@visulima/storage 1.0.0-alpha.17 → 1.0.0-alpha.19

package/dist/packem_shared/storage-5XW1E7XU.js

@@ -1,1188 +0,0 @@
-import { Readable } from 'node:stream';
-import { setInterval } from 'node:timers';
-import { inspect } from 'node:util';
-import typeis from 'type-is';
-import NoOpMetrics from './NoOpMetrics-DhAk5rXc.js';
-import { N as NoOpCache } from './cache-B88MXQ_2.js';
-import { ErrorMap, throwErrorCode, ERRORS } from './ERRORS-D0apMqnc.js';
-import { LRUCache } from 'lru-cache';
-import { a as Validator } from './validator-DuO17wFF.js';
-import { n as normalize, i as isAbsolute } from './path-aV9lMdcn-DMU5H1-h.js';
-import { i as isExpired } from './is-expired-CTThU1q5.js';
-
-const PARSE_BYTES_REGEX = /^(?<value>-?\d+(?:[.,]\d+)*) *(?<type>[a-z]+)?$/i;
-const KIBI_REGEX = /^KIBI/;
-const MIBI_REGEX = /^MIBI/;
-const GIBI_REGEX = /^GIBI/;
-const TEBI_REGEX = /^TEBI/;
-const PEBI_REGEX = /^PEBI/;
-const EXBI_REGEX = /^EXBI/;
-const ZEBI_REGEX = /^ZEBI/;
-const YIBI_REGEX = /^YIBI/;
-const IB_SUFFIX_REGEX = /^(.)IB$/;
-const BYTE_SIZES = {
-  iec: [
-    {
-      long: "Bytes",
-      short: "B"
-    },
-    {
-      long: "Kibibytes",
-      short: "KiB"
-    },
-    {
-      long: "Mebibytes",
-      short: "MiB"
-    },
-    {
-      long: "Gibibytes",
-      short: "GiB"
-    },
-    {
-      long: "Tebibytes",
-      short: "TiB"
-    },
-    {
-      long: "Pebibytes",
-      short: "PiB"
-    },
-    {
-      long: "Exbibytes",
-      short: "EiB"
-    },
-    {
-      long: "Zebibytes",
-      short: "ZiB"
-    },
-    {
-      long: "Yobibytes",
-      short: "YiB"
-    }
-  ],
-  iec_octet: [
-    {
-      long: "Octets",
-      short: "o"
-    },
-    {
-      long: "Kibioctets",
-      short: "Kio"
-    },
-    {
-      long: "Mebioctets",
-      short: "Mio"
-    },
-    {
-      long: "Gibioctets",
-      short: "Gio"
-    },
-    {
-      long: "Tebioctets",
-      short: "Tio"
-    },
-    {
-      long: "Pebioctets",
-      short: "Pio"
-    },
-    {
-      long: "Exbioctets",
-      short: "Eio"
-    },
-    {
-      long: "Zebioctets",
-      short: "Zio"
-    },
-    {
-      long: "Yobioctets",
-      short: "Yio"
-    }
-  ],
-  metric: [
-    {
-      long: "Bytes",
-      short: "Bytes"
-    },
-    {
-      long: "Kilobytes",
-      short: "KB"
-    },
-    {
-      long: "Megabytes",
-      short: "MB"
-    },
-    {
-      long: "Gigabytes",
-      short: "GB"
-    },
-    {
-      long: "Terabytes",
-      short: "TB"
-    },
-    {
-      long: "Petabytes",
-      short: "PB"
-    },
-    {
-      long: "Exabytes",
-      short: "EB"
-    },
-    {
-      long: "Zettabytes",
-      short: "ZB"
-    },
-    {
-      long: "Yottabytes",
-      short: "YB"
-    }
-  ],
-  metric_octet: [
-    {
-      long: "Octets",
-      short: "o"
-    },
-    {
-      long: "Kilo-octets",
-      short: "ko"
-    },
-    {
-      long: "Mega-octets",
-      short: "Mo"
-    },
-    {
-      long: "Giga-octets",
-      short: "Go"
-    },
-    {
-      long: "Tera-octets",
-      short: "To"
-    },
-    {
-      long: "Peta-octets",
-      short: "Po"
-    },
-    {
-      long: "Exa-octets",
-      short: "Eo"
-    },
-    {
-      long: "Zetta-octets",
-      short: "Zo"
-    },
-    {
-      long: "Yotta-octets",
-      short: "Yo"
-    }
-  ]
-};
-const parseLocalizedNumber = (stringNumber, locale) => {
-  const thousandSeparator = new Intl.NumberFormat(locale).format(11111).replaceAll(new RegExp("\\p{Number}", "gu"), "");
-  const decimalSeparator = new Intl.NumberFormat(locale).format(1.1).replaceAll(new RegExp("\\p{Number}", "gu"), "");
-  return Number.parseFloat(stringNumber.replaceAll(new RegExp(`\\${thousandSeparator}`, "g"), "").replace(new RegExp(`\\${decimalSeparator}`), "."));
-};
-const fromBase = (base) => {
-  switch (base) {
-    case 2: {
-      return 1024;
-    }
-    case 10: {
-      return 1e3;
-    }
-    default: {
-      throw new Error("Unsupported base.");
-    }
-  }
-};
-const parseBytes = (value, options) => {
-  const config = {
-    base: 2,
-    locale: "en-US",
-    units: "metric",
-    ...options
-  };
-  if (typeof value !== "string" || value.length === 0) {
-    throw new TypeError("Value is not a string or is empty.");
-  }
-  if (value.length > 100) {
-    throw new TypeError("Value exceeds the maximum length of 100 characters.");
-  }
-  const match = PARSE_BYTES_REGEX.exec(value);
-  const groups = match?.groups;
-  if (!groups) {
-    return Number.NaN;
-  }
-  const localizedNumber = parseLocalizedNumber(groups.value, config.locale);
-  const type = (groups.type ?? "Bytes").toUpperCase().replace(KIBI_REGEX, "KILO").replace(MIBI_REGEX, "MEGA").replace(GIBI_REGEX, "GIGA").replace(TEBI_REGEX, "TERA").replace(PEBI_REGEX, "PETA").replace(EXBI_REGEX, "EXA").replace(ZEBI_REGEX, "ZETTA").replace(YIBI_REGEX, "YOTTA").replace(IB_SUFFIX_REGEX, "$1B");
-  const level = BYTE_SIZES[config.units].findIndex((unit) => unit.short[0].toUpperCase() === type[0]);
-  const base = fromBase(config.base);
-  return localizedNumber * base ** level;
-};
-
-const createDurationLanguage = (y, mo, w, d, h, m, s, ms, future, past, decimal, unitMap, groupSeparator, placeholderSeparator) => {
-  const result = {
-    d,
-    h,
-    m,
-    mo,
-    ms,
-    s,
-    w,
-    y
-  };
-  {
-    result.future = future;
-  }
-  {
-    result.past = past;
-  }
-  {
-    result.decimal = decimal;
-  }
-  if (unitMap !== void 0) {
-    result.unitMap = unitMap;
-  }
-  {
-    result.groupSeparator = groupSeparator;
-  }
-  {
-    result.placeholderSeparator = placeholderSeparator;
-  }
-  return result;
-};
-
-const englishUnitMap = {
-  d: "d",
-  day: "d",
-  days: "d",
-  h: "h",
-  hour: "h",
-  hours: "h",
-  hr: "h",
-  hrs: "h",
-  m: "m",
-  millisecond: "ms",
-  milliseconds: "ms",
-  min: "m",
-  mins: "m",
-  minute: "m",
-  minutes: "m",
-  mo: "mo",
-  month: "mo",
-  months: "mo",
-  ms: "ms",
-  s: "s",
-  sec: "s",
-  second: "s",
-  seconds: "s",
-  secs: "s",
-  w: "w",
-  week: "w",
-  weeks: "w",
-  y: "y",
-  year: "y",
-  years: "y",
-  yr: "y",
-  yrs: "y"
-};
-const durationLanguage = createDurationLanguage(
-  (counter) => `year${counter === 1 ? "" : "s"}`,
-  (counter) => `month${counter === 1 ? "" : "s"}`,
-  (counter) => `week${counter === 1 ? "" : "s"}`,
-  (counter) => `day${counter === 1 ? "" : "s"}`,
-  (counter) => `hour${counter === 1 ? "" : "s"}`,
-  (counter) => `minute${counter === 1 ? "" : "s"}`,
-  (counter) => `second${counter === 1 ? "" : "s"}`,
-  (counter) => `millisecond${counter === 1 ? "" : "s"}`,
-  "in %s",
-  "%s ago",
-  ".",
-  // decimal
-  englishUnitMap,
-  ",",
-  // groupSeparator
-  "_"
-  // placeholderSeparator
-);
-
-const validateDurationLanguage = (language) => {
-  const requiredProperties = ["y", "mo", "w", "d", "h", "m", "s", "ms", "future", "past"];
-  for (const property of requiredProperties) {
-    if (!Object.hasOwn(language, property)) {
-      throw new TypeError(`Missing required property: ${property}`);
-    }
-  }
-  if (typeof language.future !== "string" || typeof language.past !== "string") {
-    throw new TypeError("Properties future and past must be of type string");
-  }
-  const unitProperties = ["y", "mo", "w", "d", "h", "m", "s", "ms"];
-  for (const property of unitProperties) {
-    if (typeof language[property] !== "string" && typeof language[property] !== "function") {
-      throw new TypeError(`Property ${property} must be of type string or function`);
-    }
-  }
-  if (language.decimal && typeof language.decimal !== "string") {
-    throw new TypeError("Property decimal must be of type string");
-  }
-  if (language.delimiter && typeof language.delimiter !== "string") {
-    throw new TypeError("Property delimiter must be of type string");
-  }
-  if (language._digitReplacements && !Array.isArray(language._digitReplacements)) {
-    throw new TypeError("Property _digitReplacements must be an array");
-  }
-  if (language._numberFirst && typeof language._numberFirst !== "boolean") {
-    throw new TypeError("Property _numberFirst must be of type boolean");
-  }
-  if (language.unitMap && typeof language.unitMap !== "object") {
-    throw new TypeError("Property unitMap must be an object");
-  }
-  if (language.unitMap && Object.values(language.unitMap).some((value) => typeof value !== "string")) {
-    throw new TypeError("All values in unitMap must be of type string");
-  }
-};
-
-const STANDARD_UNIT_MEASURES = {
-  d: 864e5,
-  h: 36e5,
-  m: 6e4,
-  mo: 2629746e3,
-  ms: 1,
-  s: 1e3,
-  w: 6048e5,
-  y: 31556952e3
-};
-const ESCAPE_REGEX = /[-/\\^$*+?.()|[\]{}]/g;
-const ISO_FORMAT = /^PT(?:(\d+)H)?(?:(\d+)M)?(?:(\d+)S)?$/i;
-const COLON_FORMAT = /^(?:(\d+):)?(?:(\d+):)?(\d+)$/;
-const NUMERIC_STRING_REGEX = /^[+-]?\d+(?:\.\d+)?$/;
-const SIGN_PREFIX_REGEX = /^[-+]/;
-const parseDuration = (value, options) => {
-  if (typeof value !== "string" || value.length === 0) {
-    return void 0;
-  }
-  const { defaultUnit = "ms", language = durationLanguage } = {};
-  validateDurationLanguage(language);
-  const decimalSeparator = language.decimal ?? ".";
-  const groupSeparator = language.groupSeparator ?? ",";
-  const placeholderSeparator = language.placeholderSeparator ?? "_";
-  const escapedDecimal = decimalSeparator.replaceAll(ESCAPE_REGEX, String.raw`\$&`);
-  const escapedGroup = groupSeparator.replaceAll(ESCAPE_REGEX, String.raw`\$&`);
-  const escapedPlaceholder = placeholderSeparator.replaceAll(ESCAPE_REGEX, String.raw`\$&`);
-  const currentUnitMap = language.unitMap ?? englishUnitMap;
-  let processedValue = value.replaceAll(new RegExp(String.raw`(\d)[${escapedPlaceholder}${escapedGroup}](\d)`, "g"), "$1$2");
-  if (decimalSeparator !== ".") {
-    processedValue = processedValue.replace(escapedDecimal, ".");
-  }
-  if (NUMERIC_STRING_REGEX.test(value)) {
-    const numberOnly = Number.parseFloat(processedValue.trim());
-    if (!Number.isNaN(numberOnly)) {
-      const unitKey = currentUnitMap[defaultUnit];
-      if (unitKey !== void 0) {
-        return numberOnly * STANDARD_UNIT_MEASURES[unitKey];
-      }
-    }
-    return void 0;
-  }
-  const isoMatch = ISO_FORMAT.exec(value);
-  if (isoMatch) {
-    const hours = Number.parseInt(isoMatch[1] ?? "0", 10);
-    const minutes = Number.parseInt(isoMatch[2] ?? "0", 10);
-    const seconds = Number.parseInt(isoMatch[3] ?? "0", 10);
-    return hours * 36e5 + minutes * 6e4 + seconds * 1e3;
-  }
-  const colonMatch = COLON_FORMAT.exec(value);
-  if (colonMatch) {
-    let hours = 0;
-    let minutes = 0;
-    if (colonMatch[2] !== void 0) {
-      hours = Number.parseInt(colonMatch[1] ?? "0", 10);
-      minutes = Number.parseInt(colonMatch[2], 10);
-    } else if (colonMatch[1] !== void 0) {
-      minutes = Number.parseInt(colonMatch[1], 10);
-    }
-    const seconds = Number.parseInt(colonMatch[3] ?? "0", 10);
-    return hours * 36e5 + minutes * 6e4 + seconds * 1e3;
-  }
-  const currentUnitMapKeys = Object.keys(currentUnitMap);
-  const regexKeys = currentUnitMapKeys.toSorted((a, b) => b.length - a.length).map((k) => k.replaceAll(ESCAPE_REGEX, String.raw`\$&`)).join("|");
-  const durationRegex = new RegExp(String.raw`(-?\d*\.?\d+)\s*(${regexKeys})`, "gi");
-  let totalMs = 0;
-  let match;
-  let unitsFound = false;
-  let firstMatchIndex = -1;
-  let lastMatchEndIndex = 0;
-  durationRegex.lastIndex = 0;
-  while ((match = durationRegex.exec(processedValue)) !== null) {
-    if (!unitsFound) {
-      firstMatchIndex = match.index;
-    }
-    unitsFound = true;
-    const numberString = match[1];
-    const unitString = match[2];
-    if (!numberString || !unitString) {
-      continue;
-    }
-    const trimmedNumberString = numberString.trim();
-    const sign = trimmedNumberString.startsWith("-") ? -1 : 1;
-    const absNumberString = trimmedNumberString.replace(SIGN_PREFIX_REGEX, "");
-    const parsedNumber = Number.parseFloat(absNumberString);
-    const unitKey = currentUnitMap[unitString.toLowerCase()];
-    if (unitKey === void 0) {
-      continue;
-    }
-    const unitValue = STANDARD_UNIT_MEASURES[unitKey];
-    if (Number.isNaN(parsedNumber)) {
-      return void 0;
-    }
-    totalMs += sign * parsedNumber * unitValue;
-    lastMatchEndIndex = durationRegex.lastIndex;
-  }
-  const leadingText = processedValue.slice(0, firstMatchIndex).trim();
-  const trailingText = processedValue.slice(lastMatchEndIndex).trim();
-  if (unitsFound && (leadingText.length > 0 || trailingText.length > 0)) {
-    return void 0;
-  }
-  if (!unitsFound) {
-    return void 0;
-  }
-  return totalMs;
-};
-
-const toMilliseconds = (value) => {
-  if (value === Number(value)) {
-    return value;
-  }
-  if (!value) {
-    return void 0;
-  }
-  const parsed = parseDuration(value);
-  if (parsed === void 0) {
-    return void 0;
-  }
-  return parsed;
-};
-
-class Locker extends LRUCache {
-  /**
-   * Creates a new Locker instance with configurable TTL and cache options.
-   * @param options LRU cache configuration options
-   */
-  constructor(options) {
-    super({
-      ttl: 1e3,
-      ttlAutopurge: true,
-      ...options
-    });
-  }
-  /**
-   * Acquires a lock for the specified key.
-   * Throws an error if the key is already locked.
-   * @param key The key to lock
-   * @returns The lock token (same as the key)
-   * @throws Error if the key is already locked
-   */
-  lock(key) {
-    const locked = this.get(key);
-    if (locked) {
-      throw new Error(`${key} is locked`);
-    }
-    this.set(key, key);
-    return key;
-  }
-  /**
-   * Releases the lock for the specified key.
-   * @param key The key to unlock
-   */
-  unlock(key) {
-    this.delete(key);
-  }
-}
-
-const extractOriginalName = (meta) => {
-  if (typeof meta.name === "string") {
-    return meta.name;
-  }
-  if (typeof meta.title === "string") {
-    return meta.title;
-  }
-  if (typeof meta.originalName === "string") {
-    return meta.originalName;
-  }
-  if (typeof meta.filename === "string") {
-    return meta.filename;
-  }
-  return void 0;
-};
-const deepMerge = (target, source) => {
-  const result = { ...target };
-  Object.keys(source).forEach((key) => {
-    const sourceValue = source[key];
-    if (sourceValue !== null && typeof sourceValue === "object" && !Array.isArray(sourceValue)) {
-      const targetValue = result[key];
-      const targetObject = targetValue && typeof targetValue === "object" && !Array.isArray(targetValue) ? targetValue : {};
-      result[key] = deepMerge(targetObject, sourceValue);
-    } else {
-      result[key] = sourceValue;
-    }
-  });
-  return result;
-};
-const updateMetadata = (file, metadata) => {
-  const merged = deepMerge(file, metadata);
-  Object.assign(file, merged);
-  file.originalName = extractOriginalName(file.metadata) || file.originalName;
-};
-
-const defaults = {
-  allowMIME: ["*/*"],
-  filename: ({ id }) => id,
-  maxMetadataSize: "8MB",
-  maxUploadSize: "5TB",
-  onComplete: () => {
-  },
-  onCreate: () => {
-  },
-  onDelete: () => {
-  },
-  onError: () => {
-  },
-  onUpdate: () => {
-  },
-  useRelativeLocation: false,
-  validation: {}
-};
-const defaultCloudStorageFileNameValidation = (name) => {
-  if (!name || name.length < 3 || name.length > 255 || isAbsolute(name)) {
-    return false;
-  }
-  const upperCase = name.toUpperCase();
-  return !(upperCase.includes("../") || name.includes("\0"));
-};
-const defaultFilesystemFileNameValidation = (name) => {
-  if (!name || name.length < 3 || name.length > 255 || isAbsolute(name)) {
-    return false;
-  }
-  const upperCase = name.toUpperCase();
-  const filesystemInvalidChars = ['"', "*", ":", "<", ">", "?", "\\", "|", "../", "\0"];
-  return !filesystemInvalidChars.some((char) => upperCase.includes(char));
-};
-class BaseStorage {
-  /**
-   * Hook called when a new file is created.
-   * @param file The newly created file object.
-   * @remarks This hook is called after file metadata is saved but before returning the file.
-   * Can be used for side effects like logging, notifications, or custom processing.
-   */
-  onCreate;
-  /**
-   * Hook called when file metadata is updated.
-   * @param file The updated file object.
-   * @remarks This hook is called after metadata is updated and saved.
-   * Can be used for side effects like logging or custom processing.
-   */
-  onUpdate;
-  /**
-   * Hook called when a file upload is completed.
-   * @param file The completed file object.
-   * @param response The response object that can be modified in place (headers, statusCode, body).
-   * @param request Optional request object for additional context.
-   * @remarks This hook is called when file status becomes "completed".
-   * The response object can be modified directly to add headers or change the status code.
-   */
-  onComplete;
-  /**
-   * Hook called when a file is deleted.
-   * @param file The deleted file object.
-   * @remarks This hook is called after the file is deleted but before returning.
-   * Can be used for side effects like cleanup or logging.
-   */
-  onDelete;
-  /**
-   * Hook called when an error occurs during storage operations.
-   * @param error The HTTP error object that can be modified in place.
-   * @remarks This hook allows customizing error responses by modifying the error object.
-   * The error object can be modified to change headers, statusCode, or body properties.
-   * Error formatting happens in handlers after this hook is called.
-   */
-  onError;
-  isReady = true;
-  errorResponses = {};
-  cache;
-  logger;
-  metrics;
-  genericConfig;
-  maxMetadataSize;
-  checksumTypes = [];
-  maxUploadSize;
-  expiration;
-  locker;
-  namingFunction;
-  validation = new Validator();
-  assetFolder = void 0;
-  /**
-   * Limits the number of concurrent upload requests
-   */
-  concurrency;
-  constructor(config) {
-    const options = { ...defaults, ...config };
-    this.onCreate = options.onCreate;
-    this.onUpdate = options.onUpdate;
-    this.onComplete = options.onComplete;
-    this.onDelete = options.onDelete;
-    this.onError = options.onError;
-    this.namingFunction = options.filename;
-    this.maxUploadSize = typeof options.maxUploadSize === "string" ? parseBytes(options.maxUploadSize) : options.maxUploadSize;
-    this.maxMetadataSize = typeof options.maxMetadataSize === "string" ? parseBytes(options.maxMetadataSize) : options.maxMetadataSize;
-    this.expiration = options.expiration;
-    this.genericConfig = options;
-    if (options.assetFolder !== void 0) {
-      this.assetFolder = normalize(options.assetFolder);
-    }
-    this.locker = new Locker({
-      max: 1e3,
-      ttl: 3e4,
-      ttlAutopurge: true
-    });
-    this.cache = options.cache ?? new NoOpCache();
-    this.logger = options.logger;
-    this.metrics = options.metrics ?? new NoOpMetrics();
-    this.logger?.debug(`${this.constructor.name} config: ${inspect({ ...config, logger: this.logger.constructor })}`);
-    const purgeInterval = toMilliseconds(options.expiration?.purgeInterval);
-    if (purgeInterval) {
-      this.startAutoPurge(purgeInterval);
-    }
-    const size = {
-      isValid(file) {
-        if (file.size === void 0) {
-          return true;
-        }
-        const fileSizeValue = file.size;
-        if (fileSizeValue === void 0 || fileSizeValue === null) {
-          return false;
-        }
-        const fileSize = typeof fileSizeValue === "number" ? fileSizeValue : Number(fileSizeValue);
-        if (Number.isNaN(fileSize) || fileSize < 0) {
-          return false;
-        }
-        const maxSize = typeof this.value === "number" ? this.value : Number(this.value);
-        return !Number.isNaN(maxSize) && fileSize <= maxSize;
-      },
-      response: ErrorMap.RequestEntityTooLarge,
-      value: this.maxUploadSize
-    };
-    const mime = {
-      isValid(file) {
-        return !!typeis.is(file.contentType, this.value);
-      },
-      // @TODO: add better error handling for mime types
-      response: ErrorMap.UnsupportedMediaType,
-      value: options.allowMIME
-    };
-    const fileNameValidation = options.fileNameValidation ?? defaultCloudStorageFileNameValidation;
-    const filename = {
-      isValid(file) {
-        return fileNameValidation(file.name);
-      },
-      response: ErrorMap.InvalidFileName
-    };
-    this.validation.add({ filename, mime, size });
-    this.validation.add({ ...options.validation });
-  }
-  get tusExtension() {
-    const extensions = ["creation", "creation-with-upload", "termination", "checksum", "creation-defer-length", "concatenation"];
-    if (this.expiration) {
-      extensions.push("expiration");
-    }
-    return extensions;
-  }
-  /**
-   * Validates a file against configured validation rules.
-   * @param file File object to validate.
-   * @returns Promise resolving to undefined if file is valid, throws ValidationError otherwise.
-   * @throws {ValidationError} If validation fails
-   */
-  async validate(file) {
-    await this.validation.verify(file);
-  }
-  /**
-   * Checks if a file exists by querying its metadata.
-   * @param query File query containing the file ID to check.
-   * @param query.id File ID to check.
-   * @returns Promise resolving to true if file exists, false otherwise.
-   * @remarks This method does not throw errors - it returns false if the file is not found.
-   */
-  async exists(query) {
-    return this.instrumentOperation("exists", async () => {
-      try {
-        await this.getMeta(query.id);
-        return true;
-      } catch {
-        return false;
-      }
-    });
-  }
-  /**
-   * Normalizes errors with storage-specific context.
-   * @param error The error to normalize.
-   * @returns Normalized HTTP error with storage class context added to the message.
-   * @remarks Errors are enhanced with the storage class name for better debugging.
-   */
-  normalizeError(error) {
-    const baseError = {
-      code: error.name,
-      message: error.message,
-      name: error.name,
-      statusCode: 500
-    };
-    return {
-      ...baseError,
-      message: `[${this.constructor.name}] ${baseError.message}`
-    };
-  }
-  /**
-   * Gets the storage configuration.
-   * @returns The current storage configuration options.
-   */
-  get config() {
-    return this.genericConfig;
-  }
-  /**
-   * Saves upload metadata to the metadata storage.
-   * @param file File object containing metadata to save.
-   * @returns Promise resolving to the saved file object.
-   * @remarks Updates timestamps and caches the file metadata.
-   */
-  async saveMeta(file) {
-    this.updateTimestamps(file);
-    this.cache.set(file.id, file);
-    return this.meta.save(file.id, file);
-  }
-  /**
-   * Deletes upload metadata from the metadata storage.
-   * @param id File ID whose metadata should be deleted.
-   * @returns Promise resolving when metadata is deleted.
-   * @remarks Also removes the file from the cache.
-   */
-  async deleteMeta(id) {
-    this.cache.delete(id);
-    return this.meta.delete(id);
-  }
-  /**
-   * Retrieves upload metadata by file ID.
-   * @param id File ID to retrieve metadata for.
-   * @returns Promise resolving to the file metadata object.
-   * @throws {UploadError} If the file metadata cannot be found (ERRORS.FILE_NOT_FOUND).
-   * @remarks Caches the retrieved metadata for faster subsequent access.
-   */
-  async getMeta(id) {
-    try {
-      const file = await this.meta.get(id);
-      this.cache.set(file.id, file);
-      return { ...file };
-    } catch (error) {
-      const httpError = this.normalizeError(error instanceof Error ? error : new Error(String(error)));
-      await this.onError(httpError);
-      return throwErrorCode(ERRORS.FILE_NOT_FOUND);
-    }
-  }
-  /**
-   * Checks if a file has expired and deletes it if so.
-   * @param file File object to check for expiration.
-   * @returns Promise resolving to the file object if not expired.
-   * @throws {UploadError} If the file has expired (ERRORS.GONE).
-   * @remarks If the file is expired, it is automatically deleted and the metadata is removed.
-   */
-  async checkIfExpired(file) {
-    if (isExpired(file)) {
-      this.delete(file).catch(() => void 0);
-      this.deleteMeta(file.id).catch(() => void 0);
-      return throwErrorCode(ERRORS.GONE);
-    }
-    return file;
-  }
-  /**
-   * Searches for and purges expired uploads.
-   * @param maxAge Maximum age of files to keep (files older than this will be purged).
-   * Can be a number (milliseconds) or string (e.g., "1h", "30m", "7d").
-   * If not provided, uses the expiration.maxAge from configuration.
-   * @returns Promise resolving to a list of purged files.
-   * @remarks
-   * Errors during individual file deletions are logged but do not stop the purge process.
-   * Files with corrupted metadata are skipped with a warning.
-   * Uses rolling expiration if configured (based on modifiedAt) or fixed expiration (based on createdAt).
-   */
-  async purge(maxAge) {
-    return this.instrumentOperation("purge", async () => {
-      const maxAgeMs = toMilliseconds(maxAge || this.expiration?.maxAge);
-      const purged = { items: [], maxAgeMs };
-      if (maxAgeMs) {
-        const before = Date.now() - maxAgeMs;
-        const list = await this.list();
-        const expired = list.filter(
-          (item) => Number(new Date(this.expiration?.rolling ? item.modifiedAt || item.createdAt : item.createdAt)) < before
-        );
-        for await (const { id, ...rest } of expired) {
-          try {
-            const deleted = await this.delete({ id });
-            purged.items.push({ ...deleted, ...rest });
-          } catch (error) {
-            this.logger?.warn(`Failed to delete file ${id} during purge: ${error instanceof Error ? error.message : String(error)}`);
-          }
-        }
-        if (purged.items.length > 0) {
-          this.logger?.info(`Purge: removed ${purged.items.length} uploads`);
-          this.metrics.gauge("storage.operations.purge.items_count", purged.items.length, {
-            storage: this.constructor.name.toLowerCase().replace("storage", "")
-          });
-        }
-      }
-      return purged;
-    });
-  }
-  /**
-   * 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
-   * Default implementation falls back to get() and creates a stream from the buffer.
-   * Storage implementations should override this for better streaming performance.
-   * Headers include Content-Type, Content-Length, ETag, and Last-Modified.
-   */
-  async getStream({ id }) {
-    return this.instrumentOperation("getStream", async () => {
-      const file = await this.get({ id });
-      const stream = Readable.from(file.content);
-      return {
-        headers: {
-          "Content-Length": String(file.size),
-          "Content-Type": file.contentType,
-          ...file.ETag && { ETag: file.ETag },
-          ...file.modifiedAt && { "Last-Modified": file.modifiedAt.toString() }
-        },
-        size: typeof file.size === "number" ? file.size : void 0,
-        stream
-      };
-    });
-  }
-  /**
-   * Retrieves a list of uploaded files.
-   * @param _limit Maximum number of files to return (default: 1000).
-   * @returns Promise resolving to an array of file metadata objects.
-   * @throws {Error} If not implemented by the storage backend.
-   * @remarks Storage implementations must override this method.
-   */
-  async list(_limit = 1e3) {
-    return this.instrumentOperation("list", async () => {
-      throw new Error("Not implemented");
-    });
-  }
-  /**
-   * Updates file metadata with user-provided key-value pairs.
-   * @param query File query containing the file ID to update.
-   * @param query.id File ID to update.
-   * @param metadata Partial file object containing fields to update.
-   * @returns Promise resolving to the updated file object.
-   * @throws {UploadError} If the file cannot be found (ERRORS.FILE_NOT_FOUND).
-   * @remarks
-   * Supports TTL (time-to-live) option: if metadata contains a 'ttl' field,
-   * it will be converted to an 'expiredAt' timestamp.
-   * TTL can be a number (milliseconds) or string (e.g., "1h", "30m", "7d").
-   */
-  async update({ id }, metadata) {
-    return this.instrumentOperation("update", async () => {
-      const file = await this.getMeta(id);
-      const processedMetadata = { ...metadata };
-      if ("ttl" in processedMetadata && processedMetadata.ttl !== void 0) {
-        const ttlValue = processedMetadata.ttl;
-        const ttlMs = typeof ttlValue === "string" ? toMilliseconds(ttlValue) : ttlValue;
-        if (ttlMs !== void 0) {
-          processedMetadata.expiredAt = Date.now() + ttlMs;
-        }
-        delete processedMetadata.ttl;
-      }
-      updateMetadata(file, processedMetadata);
-      await this.saveMeta(file);
-      const updatedFile = { ...file, status: "updated" };
-      await this.onUpdate(updatedFile);
-      return updatedFile;
-    });
-  }
-  /**
-   * Deletes multiple files in a single batch operation.
-   * @param ids Array of file IDs to delete.
-   * @returns Promise resolving to batch operation response with successful and failed deletions.
-   * @remarks
-   * Processes all deletions in parallel using Promise.allSettled.
-   * Individual failures do not stop the batch operation.
-   * Each deletion is wrapped in error handling to capture failures.
-   * Metrics are recorded for the batch operation and individual failures.
-   * Returns both successful and failed operations with detailed error information.
-   */
-  async deleteBatch(ids) {
-    const startTime = Date.now();
-    const storageType = this.constructor.name.toLowerCase().replace("storage", "");
-    this.metrics.increment("storage.operations.batch.delete.count", 1, {
-      batch_size: ids.length,
-      storage: storageType
-    });
-    const successful = [];
-    const failed = [];
-    const deletePromises = ids.map(async (id) => {
-      try {
-        const file = await this.delete({ id });
-        return { file, id, success: true };
-      } catch (error) {
-        const errorMessage = error instanceof Error ? error.message : "Delete failed";
-        this.metrics.increment("storage.operations.delete.error.count", 1, {
-          error: errorMessage,
-          storage: storageType
-        });
-        return { error: errorMessage, id, success: false };
-      }
-    });
-    const results = await Promise.allSettled(deletePromises);
-    for (const result of results) {
-      if (result.status === "fulfilled") {
-        if (result.value.success) {
-          successful.push(result.value.file);
-        } else {
-          failed.push({ error: result.value.error, id: result.value.id });
-        }
-      } else {
-        failed.push({ error: result.reason?.message || "Delete failed", id: "" });
-      }
-    }
-    const duration = Date.now() - startTime;
-    this.metrics.timing("storage.operations.batch.delete.duration", duration, {
-      batch_size: ids.length,
-      storage: storageType
-    });
-    this.metrics.gauge("storage.operations.batch.delete.success_count", successful.length, {
-      storage: storageType
-    });
-    this.metrics.gauge("storage.operations.batch.delete.failed_count", failed.length, {
-      storage: storageType
-    });
-    return {
-      failed,
-      failedCount: failed.length,
-      successful,
-      successfulCount: successful.length
-    };
-  }
-  /**
-   * Copies multiple files in a single batch operation.
-   * @param operations Array of copy operations, each containing:
-   * source: Source file ID.
-   * destination: Destination file ID or path.
-   * options: Optional copy options including storage class.
-   * @returns Promise resolving to batch operation response with successful and failed copies.
-   * @remarks
-   * Processes all copies in parallel using Promise.allSettled.
-   * Individual failures do not stop the batch operation.
-   * Each copy operation is wrapped in error handling to capture failures.
-   * Metrics are recorded for the batch operation and individual failures.
-   * Returns both successful and failed operations with detailed error information.
-   */
-  async copyBatch(operations) {
-    const startTime = Date.now();
-    const storageType = this.constructor.name.toLowerCase().replace("storage", "");
-    this.metrics.increment("storage.operations.batch.copy.count", 1, {
-      batch_size: operations.length,
-      storage: storageType
-    });
-    const successful = [];
-    const failed = [];
-    const copyPromises = operations.map(async ({ destination, options, source }) => {
-      try {
-        const copiedFile = await this.copy(source, destination, options);
-        return { file: copiedFile, id: destination, success: true };
-      } catch (error) {
-        const errorMessage = error instanceof Error ? error.message : "Copy failed";
-        this.metrics.increment("storage.operations.copy.error.count", 1, {
-          error: errorMessage,
-          storage: storageType
-        });
-        return { error: errorMessage, id: destination, success: false };
-      }
-    });
-    const results = await Promise.allSettled(copyPromises);
-    for (const result of results) {
-      if (result.status === "fulfilled") {
-        if (result.value.success && result.value.file) {
-          successful.push(result.value.file);
-        } else {
-          failed.push({ error: result.value.error || "Copy failed", id: result.value.id });
-        }
-      } else {
-        failed.push({ error: result.reason?.message || "Copy failed", id: "" });
-      }
-    }
-    const duration = Date.now() - startTime;
-    this.metrics.timing("storage.operations.batch.copy.duration", duration, {
-      batch_size: operations.length,
-      storage: storageType
-    });
-    this.metrics.gauge("storage.operations.batch.copy.success_count", successful.length, {
-      storage: storageType
-    });
-    this.metrics.gauge("storage.operations.batch.copy.failed_count", failed.length, {
-      storage: storageType
-    });
-    return {
-      failed,
-      failedCount: failed.length,
-      successful,
-      successfulCount: successful.length
-    };
-  }
-  /**
-   * Moves multiple files in a single batch operation.
-   * @param operations Array of move operations, each containing:
-   * source: Source file ID.
-   * destination: Destination file ID or path.
-   * @returns Promise resolving to batch operation response with successful and failed moves.
-   * @remarks
-   * Processes all moves in parallel using Promise.allSettled.
-   * Individual failures do not stop the batch operation.
-   * Each move operation is wrapped in error handling to capture failures.
-   * Metrics are recorded for the batch operation and individual failures.
-   * Returns both successful and failed operations with detailed error information.
-   */
-  async moveBatch(operations) {
-    const startTime = Date.now();
-    const storageType = this.constructor.name.toLowerCase().replace("storage", "");
-    this.metrics.increment("storage.operations.batch.move.count", 1, {
-      batch_size: operations.length,
-      storage: storageType
-    });
-    const successful = [];
-    const failed = [];
-    const movePromises = operations.map(async ({ destination, source }) => {
-      try {
-        const movedFile = await this.move(source, destination);
-        return { file: movedFile, id: destination, success: true };
-      } catch (error) {
-        const errorMessage = error instanceof Error ? error.message : "Move failed";
-        this.metrics.increment("storage.operations.move.error.count", 1, {
-          error: errorMessage,
-          storage: storageType
-        });
-        return { error: errorMessage, id: destination, success: false };
-      }
-    });
-    const results = await Promise.allSettled(movePromises);
-    for (const result of results) {
-      if (result.status === "fulfilled") {
-        if (result.value.success && result.value.file) {
-          successful.push(result.value.file);
-        } else {
-          failed.push({ error: result.value.error || "Move failed", id: result.value.id });
-        }
-      } else {
-        failed.push({ error: result.reason?.message || "Move failed", id: result.reason?.id || "" });
-      }
-    }
-    const duration = Date.now() - startTime;
-    this.metrics.timing("storage.operations.batch.move.duration", duration, {
-      batch_size: operations.length,
-      storage: storageType
-    });
-    this.metrics.gauge("storage.operations.batch.move.success_count", successful.length, {
-      storage: storageType
-    });
-    this.metrics.gauge("storage.operations.batch.move.failed_count", failed.length, {
-      storage: storageType
-    });
-    return {
-      failed,
-      failedCount: failed.length,
-      successful,
-      successfulCount: successful.length
-    };
-  }
-  /**
-   * Prevent upload from being accessed by multiple requests
-   */
-  async lock(key) {
-    const activeUploads = [...this.locker.keys()];
-    if (activeUploads.includes(key)) {
-      return throwErrorCode(ERRORS.FILE_LOCKED);
-    }
-    if (this.config.concurrency && typeof this.config.concurrency === "number" && this.config.concurrency < activeUploads.length) {
-      return throwErrorCode(ERRORS.STORAGE_BUSY);
-    }
-    this.locker.set(key, key);
-    return key;
-  }
-  async unlock(key) {
-    this.locker.unlock(key);
-  }
-  isUnsupportedChecksum(algorithm = "") {
-    return !!algorithm && !this.checksumTypes.includes(algorithm);
-  }
-  startAutoPurge(purgeInterval) {
-    if (purgeInterval >= 2147483647) {
-      throw new Error("“purgeInterval” must be less than 2147483647 ms");
-    }
-    setInterval(() => {
-      this.purge().catch((error) => this.logger?.error(error));
-    }, purgeInterval);
-  }
-  updateTimestamps(file) {
-    file.createdAt ??= (/* @__PURE__ */ new Date()).toISOString();
-    const maxAgeMs = toMilliseconds(this.expiration?.maxAge);
-    if (maxAgeMs && !file.expiredAt) {
-      file.expiredAt = this.expiration?.rolling ? Date.now() + maxAgeMs : +new Date(file.createdAt) + maxAgeMs;
-    }
-    return file;
-  }
-  /**
-   * Instruments a storage operation with metrics and error tracking.
-   * @param operation Operation name (e.g., "create", "delete", "copy").
-   * @param function_ The operation function to execute.
-   * @param attributes Additional attributes to include in metrics.
-   * @returns Promise resolving to the operation result.
-   * @throws Re-throws any errors from the operation function.
-   * @remarks
-   * Records operation count, duration, and error metrics.
-   * Tracks file sizes for operations returning file objects.
-   * Error metrics include error messages for debugging.
-   * All public methods should use this wrapper for consistent instrumentation.
-   */
-  async instrumentOperation(operation, function_, attributes) {
-    const startTime = Date.now();
-    const storageType = this.constructor.name.toLowerCase().replace("storage", "");
-    const baseAttributes = {
-      storage: storageType,
-      ...attributes
-    };
-    try {
-      this.metrics.increment(`storage.operations.${operation}.count`, 1, baseAttributes);
-      const result = await function_();
-      const duration = Date.now() - startTime;
-      this.metrics.timing(`storage.operations.${operation}.duration`, duration, baseAttributes);
-      if (result && typeof result === "object" && "size" in result && typeof result.size === "number") {
-        this.metrics.gauge("storage.files.size", result.size, {
-          ...baseAttributes,
-          operation
-        });
-      }
-      return result;
-    } catch (error) {
-      const duration = Date.now() - startTime;
-      const errorMessage = error instanceof Error ? error.message : "Unknown error";
-      this.metrics.timing(`storage.operations.${operation}.duration`, duration, {
-        ...baseAttributes,
-        error: "true"
-      });
-      this.metrics.increment(`storage.operations.${operation}.error.count`, 1, {
-        ...baseAttributes,
-        error: errorMessage
-      });
-      throw error;
-    }
-  }
-}
-
-export { BaseStorage as B, defaultFilesystemFileNameValidation as a, parseBytes as b, defaultCloudStorageFileNameValidation as d, parseDuration as p, toMilliseconds as t, updateMetadata as u };