@maestro-js/file-storage 1.0.0-alpha.0

package/dist/index.d.ts

@@ -0,0 +1,168 @@
+import { Iso } from 'iso-fns2';
+import { Readable } from 'node:stream';
+import { ReadableStream } from 'node:stream/web';
+import { File } from 'node:buffer';
+import { S3Client } from '@aws-sdk/client-s3';
+
+interface Driver<TemporaryUrlParams> {
+    get(path: string): Promise<Buffer>;
+    exists(path: string): Promise<boolean>;
+    url(path: string): string;
+    temporaryUrl(path: string, expiration: Iso.Instant, params?: TemporaryUrlParams): Promise<string>;
+    temporaryUploadUrl(path: string, expiration: Iso.Instant): Promise<{
+        url: string;
+        headers: Headers;
+    }>;
+    size(path: string): Promise<number>;
+    lastModified(path: string): Promise<Iso.Instant>;
+    mimeType(path: string): Promise<string | null>;
+    path(path: string): string;
+    put(path: string, contents: string | Buffer | ReadableStream | Readable): Promise<void>;
+    prepend(path: string, contents: string | Buffer | ReadableStream | Readable): Promise<void>;
+    append(path: string, contents: string | Buffer | ReadableStream | Readable): Promise<void>;
+    copy(source: string, destination: string): Promise<void>;
+    move(source: string, destination: string): Promise<void>;
+    remove(...paths: string[]): Promise<void>;
+    files(directory: string): Promise<string[]>;
+    allFiles(directory: string): Promise<string[]>;
+    directories(directory: string): Promise<string[]>;
+    allDirectories(directory: string): Promise<string[]>;
+    makeDirectory(directory: string): Promise<void>;
+    removeDirectory(directory: string): Promise<void>;
+}
+
+declare function createLocalDriver<TemporaryUrlParams>({ pathPrefix, buildTemporaryUrlsUsing }: {
+    pathPrefix?: string;
+    buildTemporaryUrlsUsing?(path: string, expiration: Iso.Instant, params?: TemporaryUrlParams): string | Promise<string>;
+}): Driver<TemporaryUrlParams>;
+
+declare function createS3Driver({ client, bucket, prefix, url: baseUrl }: {
+    client: S3Client;
+    bucket: string;
+    prefix?: string;
+    url?: string;
+}): Driver<void>;
+
+declare function create(config: FileStorage.Provider.FileStorageServiceConfig): FileStorage.FileStorageService;
+type KeysWithFallback = keyof FileStorage.Provider.Keys extends never ? {
+    default: unknown;
+} : FileStorage.Provider.Keys;
+declare function provider(key: FileStorage.Provider.Key): {
+    get: (path: string) => Promise<Buffer>;
+    text: (path: string, encoding?: BufferEncoding) => Promise<string>;
+    json: (path: string, encoding?: BufferEncoding) => Promise<any>;
+    exists: (path: string) => Promise<boolean>;
+    missing: (path: string) => Promise<boolean>;
+    download: (path: string, filename?: string, headers?: HeadersInit) => Promise<Response>;
+    url: (path: string) => string;
+    temporaryUrl: (path: string, expires: Iso.Instant, params?: any) => Promise<string>;
+    temporaryUploadUrl: (path: string, expires: Iso.Instant) => Promise<{
+        url: string;
+        headers: Headers;
+    }>;
+    size: (path: string) => Promise<number>;
+    lastModified: (path: string) => Promise<Iso.Instant>;
+    mimeType: (path: string) => Promise<string | null>;
+    path: (path: string) => string;
+    put: (path: string, contents: string | Buffer | Readable | ReadableStream) => Promise<void>;
+    prepend: (path: string, contents: string | Buffer | Readable | ReadableStream) => Promise<void>;
+    append: (path: string, contents: string | Buffer | Readable | ReadableStream) => Promise<void>;
+    copy: (source: string, destination: string) => Promise<void>;
+    move: (source: string, destination: string) => Promise<void>;
+    putFileAs: (dir: string, file: File, filename: string) => Promise<string>;
+    putFile: (dir: string, file: File) => Promise<string>;
+    remove: (...paths: string[]) => Promise<void>;
+    files: (directory: string) => Promise<string[]>;
+    allFiles: (directory: string) => Promise<string[]>;
+    directories: (directory: string) => Promise<string[]>;
+    allDirectories: (directory: string) => Promise<string[]>;
+    makeDirectory: (directory: string) => Promise<void>;
+    removeDirectory: (directory: string) => Promise<void>;
+};
+declare const FileStorage: {
+    provider: typeof provider;
+    drivers: {
+        local: typeof createLocalDriver;
+        s3: typeof createS3Driver;
+    };
+    get: (path: string) => Promise<Buffer>;
+    text: (path: string, encoding?: BufferEncoding) => Promise<string>;
+    json: (path: string, encoding?: BufferEncoding) => Promise<any>;
+    exists: (path: string) => Promise<boolean>;
+    missing: (path: string) => Promise<boolean>;
+    download: (path: string, filename?: string, headers?: HeadersInit) => Promise<Response>;
+    url: (path: string) => string;
+    temporaryUrl: (path: string, expires: Iso.Instant, params?: any) => Promise<string>;
+    temporaryUploadUrl: (path: string, expires: Iso.Instant) => Promise<{
+        url: string;
+        headers: Headers;
+    }>;
+    size: (path: string) => Promise<number>;
+    lastModified: (path: string) => Promise<Iso.Instant>;
+    mimeType: (path: string) => Promise<string | null>;
+    path: (path: string) => string;
+    put: (path: string, contents: string | Buffer | Readable | ReadableStream) => Promise<void>;
+    prepend: (path: string, contents: string | Buffer | Readable | ReadableStream) => Promise<void>;
+    append: (path: string, contents: string | Buffer | Readable | ReadableStream) => Promise<void>;
+    copy: (source: string, destination: string) => Promise<void>;
+    move: (source: string, destination: string) => Promise<void>;
+    putFileAs: (dir: string, file: File, filename: string) => Promise<string>;
+    putFile: (dir: string, file: File) => Promise<string>;
+    remove: (...paths: string[]) => Promise<void>;
+    files: (directory: string) => Promise<string[]>;
+    allFiles: (directory: string) => Promise<string[]>;
+    directories: (directory: string) => Promise<string[]>;
+    allDirectories: (directory: string) => Promise<string[]>;
+    makeDirectory: (directory: string) => Promise<void>;
+    removeDirectory: (directory: string) => Promise<void>;
+    Provider: {
+        create: typeof create;
+        register: (name: FileStorage.Provider.Key, item: FileStorage.FileStorageService) => void;
+    };
+};
+declare namespace FileStorage {
+    type Driver<T = any> = Driver<T>;
+    interface FileStorageService {
+        get(path: string): Promise<Buffer>;
+        text(path: string, encoding?: BufferEncoding): Promise<string>;
+        json(path: string, encoding?: BufferEncoding): Promise<any>;
+        exists(path: string): Promise<boolean>;
+        missing(path: string): Promise<boolean>;
+        download(path: string, filename?: string, headers?: HeadersInit): Promise<Response>;
+        url(path: string): string;
+        temporaryUrl(path: string, expires: Iso.Instant, params?: any): Promise<string>;
+        temporaryUploadUrl(path: string, expires: Iso.Instant): Promise<{
+            url: string;
+            headers: Headers;
+        }>;
+        size(path: string): Promise<number>;
+        lastModified(path: string): Promise<Iso.Instant>;
+        mimeType(path: string): Promise<string | null>;
+        path(path: string): string;
+        put(path: string, contents: string | Buffer | Readable | ReadableStream): Promise<void>;
+        prepend(path: string, contents: string | Buffer | Readable | ReadableStream): Promise<void>;
+        append(path: string, contents: string | Buffer | Readable | ReadableStream): Promise<void>;
+        copy(source: string, destination: string): Promise<void>;
+        move(source: string, destination: string): Promise<void>;
+        putFileAs(dir: string, file: File, filename: string): Promise<string>;
+        putFile(dir: string, file: File): Promise<string>;
+        remove(...paths: string[]): Promise<void>;
+        files(directory: string): Promise<string[]>;
+        allFiles(directory: string): Promise<string[]>;
+        directories(directory: string): Promise<string[]>;
+        allDirectories(directory: string): Promise<string[]>;
+        makeDirectory(directory: string): Promise<void>;
+        removeDirectory(directory: string): Promise<void>;
+    }
+    namespace Provider {
+        interface FileStorageServiceConfig {
+            driver: Driver<any>;
+        }
+        type Key = keyof KeysWithFallback;
+        interface Keys {
+        }
+    }
+}
+type HeadersInit = string[][] | Record<string, string | ReadonlyArray<string>> | Headers;
+
+export { FileStorage };

package/dist/index.js

@@ -0,0 +1,659 @@
+// src/index.ts
+import "iso-fns2";
+import { parse as parsePath, join as joinPath } from "path";
+import "stream";
+import "stream/web";
+
+// src/file-storage-types.ts
+import "stream";
+import "stream/web";
+
+// src/index.ts
+import "buffer";
+import { randomUUID as randomUUID2 } from "crypto";
+import mimeTypes from "mime-types";
+
+// src/sanitize-filename.ts
+var illegalRe = /[\/\?<>\\:\*\|"]/g;
+var controlRe = /[\x00-\x1f\x80-\x9f]/g;
+var reservedRe = /^\.+$/;
+var windowsReservedRe = /^(con|prn|aux|nul|com[0-9]|lpt[0-9])(\..*)?$/i;
+var windowsTrailingRe = /[\. ]+$/;
+function sanitizeFilename(input) {
+  if (typeof input !== "string") {
+    throw new Error("Input must be string");
+  }
+  const sanitized = input.replace(illegalRe, "").replace(controlRe, "").replace(reservedRe, "").replace(windowsReservedRe, "").replace(windowsTrailingRe, "");
+  return truncate(sanitized, 255);
+}
+function truncate(string, byteLength) {
+  if (typeof string !== "string") {
+    throw new Error("Input must be string");
+  }
+  const charLength = string.length;
+  let curByteLength = 0;
+  let codePoint;
+  let segment;
+  for (let i = 0; i < charLength; i += 1) {
+    codePoint = string.charCodeAt(i);
+    segment = string[i];
+    if (isHighSurrogate(codePoint) && isLowSurrogate(string.charCodeAt(i + 1))) {
+      i += 1;
+      segment += string[i];
+    }
+    curByteLength += Buffer.byteLength(segment);
+    if (curByteLength === byteLength) {
+      return string.slice(0, i + 1);
+    } else if (curByteLength > byteLength) {
+      return string.slice(0, i - segment.length + 1);
+    }
+  }
+  return string;
+}
+function isHighSurrogate(codePoint) {
+  return codePoint >= 55296 && codePoint <= 56319;
+}
+function isLowSurrogate(codePoint) {
+  return codePoint >= 56320 && codePoint <= 57343;
+}
+
+// src/index.ts
+import { ServiceRegistry } from "@maestro-js/service-registry";
+
+// src/local-driver.ts
+import fs from "fs/promises";
+import { createWriteStream, createReadStream } from "fs";
+import * as nodePath from "path";
+import "iso-fns2";
+import promiseStream from "stream/promises";
+import { randomUUID } from "crypto";
+import os from "os";
+import "stream/web";
+import stream from "stream";
+import { lookup } from "mime-types";
+function createLocalDriver({
+  pathPrefix = "storage",
+  buildTemporaryUrlsUsing
+}) {
+  return {
+    get(path) {
+      return fs.readFile(nodePath.join(pathPrefix, path));
+    },
+    async exists(path) {
+      try {
+        await fs.access(nodePath.join(pathPrefix, path), fs.constants.F_OK);
+        return true;
+      } catch {
+        return false;
+      }
+    },
+    url(path) {
+      return nodePath.join(pathPrefix, path);
+    },
+    async temporaryUrl(path, expiration, params) {
+      if (buildTemporaryUrlsUsing) {
+        return await buildTemporaryUrlsUsing(nodePath.join(pathPrefix, path), expiration, params);
+      } else {
+        throw new Error('Temporary url is not supported by this local driver. See "buildTemporaryUrlsUsing" option.');
+      }
+    },
+    async temporaryUploadUrl(path, expiration) {
+      throw new Error("Temporary upload url is not supported by local driver");
+    },
+    async size(path) {
+      const stat = await fs.stat(nodePath.join(pathPrefix, path));
+      return stat.size;
+    },
+    async lastModified(path) {
+      const stat = await fs.stat(nodePath.join(pathPrefix, path));
+      return stat.mtime.toISOString();
+    },
+    async mimeType(path) {
+      return lookup(path) || null;
+    },
+    path(path) {
+      return nodePath.resolve(nodePath.join(pathPrefix, path));
+    },
+    async put(path, contents) {
+      await fs.writeFile(nodePath.join(pathPrefix, path), contents);
+    },
+    async prepend(path, contents) {
+      await prepend(nodePath.join(pathPrefix, path), contents);
+    },
+    async append(path, contents) {
+      if (Buffer.isBuffer(contents) || typeof contents == "string") {
+        await fs.appendFile(nodePath.join(pathPrefix, path), contents);
+      } else {
+        const writeStream2 = createWriteStream(nodePath.join(pathPrefix, path), { flags: "a" });
+        await promiseStream.pipeline(contents, writeStream2);
+      }
+    },
+    async copy(source, destination) {
+      await fs.copyFile(nodePath.join(pathPrefix, source), nodePath.join(pathPrefix, destination));
+    },
+    async move(source, destination) {
+      await fs.rename(nodePath.join(pathPrefix, source), nodePath.join(pathPrefix, destination));
+    },
+    async remove(...paths) {
+      await Promise.all(paths.map((p) => fs.rm(nodePath.join(pathPrefix, p))));
+    },
+    async files(directory) {
+      const results = await fs.readdir(nodePath.join(pathPrefix, directory), { withFileTypes: true });
+      return results.filter((r) => r.isFile()).map((r) => nodePath.join(r.parentPath, r.name));
+    },
+    async allFiles(directory) {
+      const results = await fs.readdir(nodePath.join(pathPrefix, directory), { recursive: true, withFileTypes: true });
+      return results.filter((r) => r.isFile()).map((r) => nodePath.join(r.parentPath, r.name));
+    },
+    async directories(directory) {
+      const results = await fs.readdir(nodePath.join(pathPrefix, directory), { withFileTypes: true });
+      return results.filter((r) => r.isDirectory()).map((r) => nodePath.join(r.parentPath, r.name));
+    },
+    async allDirectories(directory) {
+      const results = await fs.readdir(nodePath.join(pathPrefix, directory), { recursive: true, withFileTypes: true });
+      return results.filter((r) => r.isDirectory()).map((r) => nodePath.join(r.parentPath, r.name));
+    },
+    async makeDirectory(directory) {
+      await fs.mkdir(nodePath.join(pathPrefix, directory), { recursive: true });
+    },
+    async removeDirectory(directory) {
+      await fs.rmdir(nodePath.join(pathPrefix, directory), { recursive: true });
+    }
+  };
+}
+async function prepend(filename, contents) {
+  let bomFound = false;
+  let bomPlaced = false;
+  const checkStripBomTransformer = new stream.Transform({
+    transform(chunk, _, callback) {
+      let fileData = chunk;
+      if (!bomFound) {
+        bomFound = hasBOM(fileData);
+        fileData = hasBOM(fileData) ? stripBOM(fileData) : fileData;
+      }
+      callback(null, Buffer.from(fileData));
+    }
+  });
+  const checkPrependBomTransformer = new stream.Transform({
+    transform(chunk, _, callback) {
+      let fileData = chunk.toString();
+      if (bomFound && !bomPlaced) {
+        fileData = prependBOM(fileData);
+        bomPlaced = true;
+      }
+      callback(null, Buffer.from(fileData));
+    }
+  });
+  const temporaryFile = await tempWrite(contents);
+  try {
+    await promiseStream.pipeline(
+      createReadStream(filename),
+      checkStripBomTransformer,
+      createWriteStream(temporaryFile, { flags: "a" })
+    );
+  } catch (error) {
+    if (typeof error === "object" && error && error["code"] === "ENOENT" && error["path"] === filename) {
+      await fs.writeFile(filename, contents);
+      return;
+    }
+    throw error;
+  }
+  await promiseStream.pipeline(createReadStream(temporaryFile), checkPrependBomTransformer, createWriteStream(filename));
+  await fs.unlink(temporaryFile);
+}
+async function tempWrite(fileContent) {
+  const temporaryPath = await tempfile();
+  await fs.mkdir(nodePath.dirname(temporaryPath), { recursive: true });
+  if (Buffer.isBuffer(fileContent) || typeof fileContent === "string") {
+    await fs.writeFile(temporaryPath, fileContent);
+  } else {
+    await writeStream(temporaryPath, fileContent);
+  }
+  return temporaryPath;
+}
+async function tempfile(filePath = "") {
+  return nodePath.join(await tempDirectory, randomUUID(), filePath);
+}
+async function writeStream(filePath, data) {
+  return promiseStream.pipeline(data, createWriteStream(filePath));
+}
+var tempDirectory = fs.realpath(os.tmpdir());
+function hasBOM(text) {
+  return text.toString().charCodeAt(0) === 65279;
+}
+function prependBOM(text) {
+  return "\uFEFF" + text;
+}
+function stripBOM(text) {
+  return text.toString().slice(1);
+}
+
+// src/s3-driver.ts
+import {
+  GetObjectCommand,
+  HeadObjectCommand,
+  PutObjectCommand,
+  CopyObjectCommand,
+  DeleteObjectCommand,
+  DeleteObjectsCommand,
+  ListObjectsV2Command
+} from "@aws-sdk/client-s3";
+import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
+import "iso-fns2";
+import "stream";
+import { ReadableStream as ReadableStream2 } from "stream/web";
+import { lookup as lookup2 } from "mime-types";
+function createS3Driver({
+  client,
+  bucket,
+  prefix = "",
+  url: baseUrl
+}) {
+  return {
+    async get(path) {
+      const response = await client.send(new GetObjectCommand({ Bucket: bucket, Key: resolveKey(prefix, path) }));
+      return Buffer.from(await response.Body.transformToByteArray());
+    },
+    async exists(path) {
+      try {
+        await client.send(new HeadObjectCommand({ Bucket: bucket, Key: resolveKey(prefix, path) }));
+        return true;
+      } catch (error) {
+        if (error.name === "NotFound" || error.$metadata?.httpStatusCode === 404) return false;
+        throw error;
+      }
+    },
+    url(path) {
+      const key = resolveKey(prefix, path);
+      if (baseUrl) return `${baseUrl.replace(/\/$/, "")}/${key}`;
+      return `https://${bucket}.s3.amazonaws.com/${key}`;
+    },
+    async temporaryUrl(path, expiration) {
+      const command = new GetObjectCommand({ Bucket: bucket, Key: resolveKey(prefix, path) });
+      return await getSignedUrl(client, command, { expiresIn: expirationToSeconds(expiration) });
+    },
+    async temporaryUploadUrl(path, expiration) {
+      const key = resolveKey(prefix, path);
+      const contentType = lookup2(path) || "application/octet-stream";
+      const command = new PutObjectCommand({ Bucket: bucket, Key: key, ContentType: contentType });
+      const url = await getSignedUrl(client, command, { expiresIn: expirationToSeconds(expiration) });
+      return { url, headers: new Headers({ "Content-Type": contentType }) };
+    },
+    async size(path) {
+      const response = await client.send(new HeadObjectCommand({ Bucket: bucket, Key: resolveKey(prefix, path) }));
+      return response.ContentLength;
+    },
+    async lastModified(path) {
+      const response = await client.send(new HeadObjectCommand({ Bucket: bucket, Key: resolveKey(prefix, path) }));
+      return response.LastModified.toISOString();
+    },
+    async mimeType(path) {
+      const response = await client.send(new HeadObjectCommand({ Bucket: bucket, Key: resolveKey(prefix, path) }));
+      return response.ContentType ?? null;
+    },
+    path(path) {
+      return `s3://${bucket}/${resolveKey(prefix, path)}`;
+    },
+    async put(path, contents) {
+      const key = resolveKey(prefix, path);
+      const contentType = lookup2(path) || "application/octet-stream";
+      const body = await toBuffer(contents);
+      await client.send(new PutObjectCommand({ Bucket: bucket, Key: key, Body: body, ContentType: contentType }));
+    },
+    async prepend(path, contents) {
+      const key = resolveKey(prefix, path);
+      let existing = Buffer.alloc(0);
+      try {
+        const response = await client.send(new GetObjectCommand({ Bucket: bucket, Key: key }));
+        existing = Buffer.from(await response.Body.transformToByteArray());
+      } catch (error) {
+        if (error.name !== "NoSuchKey" && error.$metadata?.httpStatusCode !== 404) throw error;
+      }
+      const prepended = Buffer.concat([await toBuffer(contents), existing]);
+      const contentType = lookup2(path) || "application/octet-stream";
+      await client.send(new PutObjectCommand({ Bucket: bucket, Key: key, Body: prepended, ContentType: contentType }));
+    },
+    async append(path, contents) {
+      const key = resolveKey(prefix, path);
+      let existing = Buffer.alloc(0);
+      try {
+        const response = await client.send(new GetObjectCommand({ Bucket: bucket, Key: key }));
+        existing = Buffer.from(await response.Body.transformToByteArray());
+      } catch (error) {
+        if (error.name !== "NoSuchKey" && error.$metadata?.httpStatusCode !== 404) throw error;
+      }
+      const appended = Buffer.concat([existing, await toBuffer(contents)]);
+      const contentType = lookup2(path) || "application/octet-stream";
+      await client.send(new PutObjectCommand({ Bucket: bucket, Key: key, Body: appended, ContentType: contentType }));
+    },
+    async copy(source, destination) {
+      await client.send(
+        new CopyObjectCommand({
+          Bucket: bucket,
+          CopySource: `${bucket}/${resolveKey(prefix, source)}`,
+          Key: resolveKey(prefix, destination)
+        })
+      );
+    },
+    async move(source, destination) {
+      await this.copy(source, destination);
+      await client.send(new DeleteObjectCommand({ Bucket: bucket, Key: resolveKey(prefix, source) }));
+    },
+    async remove(...paths) {
+      if (paths.length === 1) {
+        await client.send(new DeleteObjectCommand({ Bucket: bucket, Key: resolveKey(prefix, paths[0]) }));
+        return;
+      }
+      for (let i = 0; i < paths.length; i += 1e3) {
+        const batch = paths.slice(i, i + 1e3);
+        await client.send(
+          new DeleteObjectsCommand({
+            Bucket: bucket,
+            Delete: { Objects: batch.map((p) => ({ Key: resolveKey(prefix, p) })) }
+          })
+        );
+      }
+    },
+    async files(directory) {
+      const results = [];
+      let continuationToken;
+      const dirPrefix = resolveKey(prefix, directory).replace(/\/?$/, "/");
+      do {
+        const response = await client.send(
+          new ListObjectsV2Command({
+            Bucket: bucket,
+            Prefix: dirPrefix,
+            Delimiter: "/",
+            ContinuationToken: continuationToken
+          })
+        );
+        for (const item of response.Contents ?? []) {
+          if (item.Key) results.push(item.Key);
+        }
+        continuationToken = response.NextContinuationToken;
+      } while (continuationToken);
+      return results;
+    },
+    async allFiles(directory) {
+      const results = [];
+      let continuationToken;
+      const dirPrefix = resolveKey(prefix, directory).replace(/\/?$/, "/");
+      do {
+        const response = await client.send(
+          new ListObjectsV2Command({
+            Bucket: bucket,
+            Prefix: dirPrefix,
+            ContinuationToken: continuationToken
+          })
+        );
+        for (const item of response.Contents ?? []) {
+          if (item.Key) results.push(item.Key);
+        }
+        continuationToken = response.NextContinuationToken;
+      } while (continuationToken);
+      return results;
+    },
+    async directories(directory) {
+      const results = [];
+      let continuationToken;
+      const dirPrefix = resolveKey(prefix, directory).replace(/\/?$/, "/");
+      do {
+        const response = await client.send(
+          new ListObjectsV2Command({
+            Bucket: bucket,
+            Prefix: dirPrefix,
+            Delimiter: "/",
+            ContinuationToken: continuationToken
+          })
+        );
+        for (const item of response.CommonPrefixes ?? []) {
+          if (item.Prefix) results.push(item.Prefix);
+        }
+        continuationToken = response.NextContinuationToken;
+      } while (continuationToken);
+      return results;
+    },
+    async allDirectories(directory) {
+      const allKeys = await this.allFiles(directory);
+      const dirs = /* @__PURE__ */ new Set();
+      for (const key of allKeys) {
+        const parts = key.split("/");
+        for (let i = 1; i < parts.length; i++) {
+          dirs.add(parts.slice(0, i).join("/") + "/");
+        }
+      }
+      return [...dirs].sort();
+    },
+    async makeDirectory() {
+    },
+    async removeDirectory(directory) {
+      const keys = await this.allFiles(directory);
+      if (keys.length === 0) return;
+      for (let i = 0; i < keys.length; i += 1e3) {
+        const batch = keys.slice(i, i + 1e3);
+        await client.send(
+          new DeleteObjectsCommand({
+            Bucket: bucket,
+            Delete: { Objects: batch.map((key) => ({ Key: key })) }
+          })
+        );
+      }
+    }
+  };
+}
+function resolveKey(prefix, path) {
+  const normalized = prefix ? `${prefix.replace(/\/$/, "")}/${path.replace(/^\//, "")}` : path.replace(/^\//, "");
+  return normalized;
+}
+function expirationToSeconds(expiration) {
+  const expiresAt = new Date(expiration).getTime();
+  const now = Date.now();
+  return Math.max(1, Math.floor((expiresAt - now) / 1e3));
+}
+async function toBuffer(contents) {
+  if (Buffer.isBuffer(contents)) return contents;
+  if (typeof contents === "string") return Buffer.from(contents);
+  if (contents instanceof ReadableStream2) {
+    const chunks2 = [];
+    const reader = contents.getReader();
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      chunks2.push(value);
+    }
+    return Buffer.concat(chunks2);
+  }
+  const chunks = [];
+  for await (const chunk of contents) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+  }
+  return Buffer.concat(chunks);
+}
+
+// src/index.ts
+function create(config) {
+  const driver = config.driver;
+  async function get(path2) {
+    return await driver.get(path2);
+  }
+  async function text(path2, encoding) {
+    const contents = await driver.get(path2);
+    return contents.toString(encoding);
+  }
+  async function json(path2, encoding) {
+    const contents = await driver.get(path2);
+    return JSON.parse(contents.toString(encoding));
+  }
+  async function exists(path2) {
+    return await driver.exists(path2);
+  }
+  async function missing(path2) {
+    return !await driver.exists(path2);
+  }
+  async function download(path2, filename, headers) {
+    const contents = await driver.get(path2);
+    const parsed = parsePath(path2);
+    const dispositionFilename = filename !== void 0 ? filename : `${parsed.name}${parsed.ext}`;
+    return new Response(contents, {
+      status: 200,
+      headers: combineHeaders({ "Content-Disposition": `inline; filename="${dispositionFilename}"` }, headers)
+    });
+  }
+  function url(path2) {
+    return driver.url(path2);
+  }
+  async function temporaryUrl(path2, expires, params) {
+    return await driver.temporaryUrl(path2, expires, params);
+  }
+  async function temporaryUploadUrl(path2, expires) {
+    return await driver.temporaryUploadUrl(path2, expires);
+  }
+  async function size(path2) {
+    return await driver.size(path2);
+  }
+  async function lastModified(path2) {
+    return await driver.lastModified(path2);
+  }
+  async function mimeType(path2) {
+    return await driver.mimeType(path2);
+  }
+  function path(path2) {
+    return driver.path(path2);
+  }
+  async function put(path2, contents) {
+    await driver.put(path2, contents);
+  }
+  async function prepend2(path2, contents) {
+    await driver.prepend(path2, contents);
+  }
+  async function append(path2, contents) {
+    await driver.append(path2, contents);
+  }
+  async function copy(source, destination) {
+    await driver.copy(source, destination);
+  }
+  async function move(source, destination) {
+    await driver.move(source, destination);
+  }
+  async function putFileAs(dir, file, filename) {
+    const filePath = joinPath(dir, filename);
+    await driver.put(filePath, file.stream());
+    return filePath;
+  }
+  async function putFile(dir, file) {
+    const parsed = parsePath(file.name);
+    const ext = mimeTypes.extension(file.type);
+    const name = `${sanitizeFilename(parsed.name)}-${randomUUID2()}${ext ? `.${ext}` : ""}`;
+    return await putFileAs(dir, file, name);
+  }
+  async function remove(...paths) {
+    await driver.remove(...paths);
+  }
+  async function files(directory) {
+    return await driver.files(directory);
+  }
+  async function allFiles(directory) {
+    return await driver.allFiles(directory);
+  }
+  async function directories(directory) {
+    return await driver.directories(directory);
+  }
+  async function allDirectories(directory) {
+    return await driver.allDirectories(directory);
+  }
+  async function makeDirectory(directory) {
+    await driver.makeDirectory(directory);
+  }
+  async function removeDirectory(directory) {
+    await driver.removeDirectory(directory);
+  }
+  return {
+    get,
+    text,
+    json,
+    exists,
+    missing,
+    download,
+    url,
+    temporaryUrl,
+    temporaryUploadUrl,
+    size,
+    lastModified,
+    mimeType,
+    path,
+    put,
+    prepend: prepend2,
+    append,
+    copy,
+    move,
+    putFileAs,
+    putFile,
+    remove,
+    files,
+    allFiles,
+    directories,
+    allDirectories,
+    makeDirectory,
+    removeDirectory
+  };
+}
+var registry = ServiceRegistry.createRegistry(
+  ServiceRegistry.proxyFunctionsForObject
+);
+var Provider = {
+  create,
+  register: registry.register
+};
+function provider(key) {
+  const service = registry.resolve(key);
+  return {
+    get: service.get,
+    text: service.text,
+    json: service.json,
+    exists: service.exists,
+    missing: service.missing,
+    download: service.download,
+    url: service.url,
+    temporaryUrl: service.temporaryUrl,
+    temporaryUploadUrl: service.temporaryUploadUrl,
+    size: service.size,
+    lastModified: service.lastModified,
+    mimeType: service.mimeType,
+    path: service.path,
+    put: service.put,
+    prepend: service.prepend,
+    append: service.append,
+    copy: service.copy,
+    move: service.move,
+    putFileAs: service.putFileAs,
+    putFile: service.putFile,
+    remove: service.remove,
+    files: service.files,
+    allFiles: service.allFiles,
+    directories: service.directories,
+    allDirectories: service.allDirectories,
+    makeDirectory: service.makeDirectory,
+    removeDirectory: service.removeDirectory
+  };
+}
+var FileStorage = {
+  Provider,
+  ...provider("default"),
+  provider,
+  drivers: {
+    local: createLocalDriver,
+    s3: createS3Driver
+  }
+};
+function combineHeaders(base, extra) {
+  const merged = new Headers(base);
+  if (extra) {
+    new Headers(extra).forEach((value, key) => {
+      merged.set(key, value);
+    });
+  }
+  return merged;
+}
+export {
+  FileStorage
+};

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@maestro-js/file-storage",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "version": "1.0.0-alpha.0",
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@aws-sdk/client-s3": "^3.750.0",
+    "@aws-sdk/s3-request-presigner": "^3.750.0",
+    "iso-fns2": "npm:iso-fns@2.0.0-alpha.26",
+    "mime-types": "^2.1.35",
+    "@maestro-js/service-registry": "1.0.0-alpha.0",
+    "@maestro-js/crypt": "1.0.0-alpha.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.11",
+    "@types/mime-types": "^2.1.4"
+  },
+  "license": "UNLICENSED",
+  "engines": {
+    "node": ">=22.18.0"
+  },
+  "repository": "https://github.com/Marcato-Partners/maestro-js",
+  "scripts": {
+    "build": "tsup --config ../../tsup.config.ts",
+    "typecheck": "tsc --noEmit",
+    "format": "prettier --write src/",
+    "lint": "prettier --check src/"
+  }
+}