@b9g/filesystem 0.1.4 → 0.1.6

package/src/bun-s3.js

@@ -1,197 +1,248 @@
 /// <reference types="./bun-s3.d.ts" />
 // src/bun-s3.ts
-var BunS3FileSystemWritableFileStream = class extends WritableStream {
-  constructor(s3file) {
-    super({
-      start: async () => {
-        this.writer = this.s3file.writer();
-      },
-      write: async (chunk) => {
-        await this.writer.write(chunk);
-      },
-      close: async () => {
-        await this.writer.end();
-      },
-      abort: async () => {
-        await this.writer.abort?.();
-      }
-    });
-    this.s3file = s3file;
-  }
-  writer;
-};
-var BunS3FileSystemFileHandle = class _BunS3FileSystemFileHandle {
-  constructor(s3Client, key) {
-    this.s3Client = s3Client;
-    this.key = key;
-    this.name = key.split("/").pop() || key;
+import {
+  ShovelDirectoryHandle,
+  ShovelFileHandle
+} from "./index.js";
+var S3FileSystemBackend = class {
+  #s3Client;
+  #bucketName;
+  #prefix;
+  constructor(s3Client, bucketName, prefix = "") {
+    this.#s3Client = s3Client;
+    this.#bucketName = bucketName;
+    this.#prefix = prefix;
   }
-  kind = "file";
-  name;
-  async getFile() {
-    const s3file = this.s3Client.file(this.key);
+  async stat(path) {
     try {
-      const exists = await s3file.exists();
-      if (!exists) {
-        throw new DOMException("File not found", "NotFoundError");
+      const key = this.#getS3Key(path);
+      try {
+        await this.#s3Client.head({ key });
+        return { kind: "file" };
+      } catch (error) {
+        const dirPrefix = key.endsWith("/") ? key : `${key}/`;
+        const result = await this.#s3Client.list({
+          prefix: dirPrefix,
+          maxKeys: 1
+        });
+        if (result.Contents && result.Contents.length > 0) {
+          return { kind: "directory" };
+        }
+        return null;
       }
-      const stats = await s3file.stat();
-      const blob = s3file;
-      return new File([blob], this.name, {
-        lastModified: stats?.lastModified ? new Date(stats.lastModified).getTime() : Date.now(),
-        type: stats?.contentType || this.getMimeType(this.key)
-      });
     } catch (error) {
-      if (error.message?.includes("NoSuchKey") || error.message?.includes("Not Found")) {
-        throw new DOMException("File not found", "NotFoundError");
-      }
-      throw error;
+      return null;
     }
   }
-  async createWritable() {
-    const s3file = this.s3Client.file(this.key);
-    return new BunS3FileSystemWritableFileStream(s3file);
-  }
-  async createSyncAccessHandle() {
-    throw new DOMException(
-      "Synchronous access handles are not supported for S3 storage",
-      "InvalidStateError"
-    );
-  }
-  async isSameEntry(other) {
-    if (other.kind !== "file")
-      return false;
-    if (!(other instanceof _BunS3FileSystemFileHandle))
-      return false;
-    return this.key === other.key;
-  }
-  async queryPermission() {
-    return "granted";
-  }
-  async requestPermission() {
-    return "granted";
-  }
-  getMimeType(key) {
-    const ext = key.split(".").pop()?.toLowerCase();
-    const mimeTypes = {
-      txt: "text/plain",
-      html: "text/html",
-      css: "text/css",
-      js: "text/javascript",
-      json: "application/json",
-      png: "image/png",
-      jpg: "image/jpeg",
-      jpeg: "image/jpeg",
-      gif: "image/gif",
-      svg: "image/svg+xml",
-      pdf: "application/pdf",
-      zip: "application/zip"
-    };
-    return mimeTypes[ext || ""] || "application/octet-stream";
-  }
-};
-var BunS3FileSystemDirectoryHandle = class _BunS3FileSystemDirectoryHandle {
-  constructor(s3Client, prefix) {
-    this.s3Client = s3Client;
-    this.prefix = prefix;
-    this.prefix = prefix.endsWith("/") ? prefix.slice(0, -1) : prefix;
-    this.name = this.prefix.split("/").pop() || "root";
-  }
-  kind = "directory";
-  name;
-  async getFileHandle(name, options) {
-    const key = this.prefix ? `${this.prefix}/${name}` : name;
-    const s3file = this.s3Client.file(key);
-    const exists = await s3file.exists();
-    if (!exists && options?.create) {
-      await s3file.write("");
-    } else if (!exists) {
-      throw new DOMException("File not found", "NotFoundError");
-    }
-    return new BunS3FileSystemFileHandle(this.s3Client, key);
-  }
-  async getDirectoryHandle(name, options) {
-    const newPrefix = this.prefix ? `${this.prefix}/${name}` : name;
-    if (options?.create) {
-      const markerKey = `${newPrefix}/.shovel_directory_marker`;
-      const markerFile = this.s3Client.file(markerKey);
-      const exists = await markerFile.exists();
-      if (!exists) {
-        await markerFile.write("");
+  async readFile(path) {
+    try {
+      const key = this.#getS3Key(path);
+      const result = await this.#s3Client.get({ key });
+      if (result.Body) {
+        let content;
+        if (result.Body instanceof Uint8Array) {
+          content = result.Body;
+        } else if (typeof result.Body === "string") {
+          content = new TextEncoder().encode(result.Body);
+        } else {
+          const arrayBuffer = await result.Body.arrayBuffer();
+          content = new Uint8Array(arrayBuffer);
+        }
+        const lastModified = result.LastModified ? new Date(result.LastModified).getTime() : void 0;
+        return { content, lastModified };
       }
+      throw new DOMException("File not found", "NotFoundError");
+    } catch (error) {
+      throw new DOMException("File not found", "NotFoundError");
     }
-    return new _BunS3FileSystemDirectoryHandle(this.s3Client, newPrefix);
   }
-  async removeEntry(name, options) {
-    const key = this.prefix ? `${this.prefix}/${name}` : name;
-    const s3file = this.s3Client.file(key);
-    const fileExists = await s3file.exists();
-    if (fileExists) {
-      await s3file.delete();
-      return;
-    }
-    if (options?.recursive) {
-      const dirPrefix = `${key}/`;
-      const files = await this.s3Client.list({ prefix: dirPrefix });
-      const deletePromises = files.map(
-        (file) => this.s3Client.file(file.Key || file.key).delete()
-      );
-      await Promise.all(deletePromises);
-      const markerFile = this.s3Client.file(`${key}/.shovel_directory_marker`);
-      const markerExists = await markerFile.exists();
-      if (markerExists) {
-        await markerFile.delete();
-      }
-    } else {
+  async writeFile(path, data) {
+    try {
+      const key = this.#getS3Key(path);
+      await this.#s3Client.put({
+        key,
+        body: data
+      });
+    } catch (error) {
       throw new DOMException(
-        "Directory is not empty",
+        `Failed to write file: ${error}`,
         "InvalidModificationError"
       );
     }
   }
-  async resolve(_possibleDescendant) {
-    return null;
-  }
-  async *entries() {
-    const listPrefix = this.prefix ? `${this.prefix}/` : "";
+  async listDir(path) {
     try {
-      const result = await this.s3Client.list({
+      const dirPrefix = this.#getS3Key(path);
+      const listPrefix = dirPrefix ? `${dirPrefix}/` : "";
+      const result = await this.#s3Client.list({
         prefix: listPrefix,
         delimiter: "/"
-        // Only get immediate children
       });
+      const results = [];
       if (result.Contents) {
-        for (const item of result.Contents) {
-          const key = item.Key || item.key;
-          if (key && key !== listPrefix) {
-            const name = key.substring(listPrefix.length);
-            if (!name.includes("/") && !name.endsWith(".shovel_directory_marker")) {
-              yield [name, new BunS3FileSystemFileHandle(this.s3Client, key)];
+        for (const object of result.Contents) {
+          if (object.Key && object.Key !== listPrefix) {
+            const name = object.Key.replace(listPrefix, "");
+            if (name && !name.includes("/")) {
+              results.push({ name, kind: "file" });
             }
           }
         }
       }
       if (result.CommonPrefixes) {
         for (const prefix of result.CommonPrefixes) {
-          const prefixKey = prefix.Prefix || prefix.prefix;
-          if (prefixKey) {
-            const name = prefixKey.substring(listPrefix.length).replace(/\/$/, "");
+          if (prefix.Prefix) {
+            const name = prefix.Prefix.replace(listPrefix, "").replace("/", "");
             if (name) {
-              yield [
-                name,
-                new _BunS3FileSystemDirectoryHandle(
-                  this.s3Client,
-                  prefixKey.replace(/\/$/, "")
-                )
-              ];
+              results.push({ name, kind: "directory" });
             }
           }
         }
       }
+      return results;
     } catch (error) {
       throw new DOMException("Directory not found", "NotFoundError");
     }
   }
+  async createDir(path) {
+    try {
+      const key = this.#getS3Key(path);
+      const dirKey = key.endsWith("/") ? key : `${key}/`;
+      await this.#s3Client.put({
+        key: dirKey,
+        body: new Uint8Array(0)
+      });
+    } catch (error) {
+      throw new DOMException(
+        `Failed to create directory: ${error}`,
+        "InvalidModificationError"
+      );
+    }
+  }
+  async remove(path, recursive) {
+    try {
+      const key = this.#getS3Key(path);
+      try {
+        await this.#s3Client.head({ key });
+        await this.#s3Client.delete({ key });
+        return;
+      } catch (error) {
+      }
+      const dirPrefix = key.endsWith("/") ? key : `${key}/`;
+      if (recursive) {
+        const result = await this.#s3Client.list({ prefix: dirPrefix });
+        if (result.Contents && result.Contents.length > 0) {
+          const deleteKeys = result.Contents.map((obj) => ({
+            key: obj.Key
+          }));
+          await this.#s3Client.deleteObjects({ delete: { objects: deleteKeys } });
+        }
+      } else {
+        const result = await this.#s3Client.list({
+          prefix: dirPrefix,
+          maxKeys: 1
+        });
+        if (result.Contents && result.Contents.length > 0) {
+          throw new DOMException(
+            "Directory is not empty",
+            "InvalidModificationError"
+          );
+        }
+        try {
+          await this.#s3Client.delete({ key: dirPrefix });
+        } catch (error) {
+        }
+      }
+    } catch (error) {
+      if (error instanceof DOMException)
+        throw error;
+      throw new DOMException("Entry not found", "NotFoundError");
+    }
+  }
+  #getS3Key(path) {
+    if (path.includes("..") || path.includes("\0")) {
+      throw new DOMException(
+        "Invalid path: contains path traversal or null bytes",
+        "NotAllowedError"
+      );
+    }
+    const cleanPath = path.startsWith("/") ? path.slice(1) : path;
+    if (!cleanPath) {
+      return this.#prefix;
+    }
+    const parts = cleanPath.split("/");
+    for (const part of parts) {
+      if (part === "." || part === ".." || part.includes("\\")) {
+        throw new DOMException("Invalid S3 key component", "NotAllowedError");
+      }
+    }
+    return this.#prefix ? `${this.#prefix}/${cleanPath}` : cleanPath;
+  }
+};
+var S3Bucket = class _S3Bucket {
+  kind;
+  name;
+  #backend;
+  constructor(s3Client, bucketName, prefix = "") {
+    this.kind = "directory";
+    this.#backend = new S3FileSystemBackend(s3Client, bucketName, prefix);
+    this.name = prefix.split("/").filter(Boolean).pop() || bucketName;
+  }
+  async getFileHandle(name, options) {
+    const filePath = `/${name}`;
+    const stat = await this.#backend.stat(filePath);
+    if (!stat && options?.create) {
+      await this.#backend.writeFile(filePath, new Uint8Array(0));
+    } else if (!stat) {
+      throw new DOMException("File not found", "NotFoundError");
+    } else if (stat.kind !== "file") {
+      throw new DOMException(
+        "Path exists but is not a file",
+        "TypeMismatchError"
+      );
+    }
+    return new ShovelFileHandle(this.#backend, filePath);
+  }
+  async getDirectoryHandle(name, options) {
+    const dirPath = `/${name}`;
+    const stat = await this.#backend.stat(dirPath);
+    if (!stat && options?.create) {
+      await this.#backend.createDir(dirPath);
+    } else if (!stat) {
+      throw new DOMException("Directory not found", "NotFoundError");
+    } else if (stat.kind !== "directory") {
+      throw new DOMException(
+        "Path exists but is not a directory",
+        "TypeMismatchError"
+      );
+    }
+    return new ShovelDirectoryHandle(this.#backend, dirPath);
+  }
+  async removeEntry(name, options) {
+    const entryPath = `/${name}`;
+    await this.#backend.remove(entryPath, options?.recursive);
+  }
+  async resolve(possibleDescendant) {
+    if (!(possibleDescendant instanceof ShovelDirectoryHandle || possibleDescendant instanceof ShovelFileHandle)) {
+      return null;
+    }
+    const descendantPath = possibleDescendant.path;
+    if (typeof descendantPath === "string" && descendantPath.startsWith("/")) {
+      return descendantPath.split("/").filter(Boolean);
+    }
+    return null;
+  }
+  async *entries() {
+    const entries = await this.#backend.listDir("/");
+    for (const entry of entries) {
+      const entryPath = `/${entry.name}`;
+      if (entry.kind === "file") {
+        yield [entry.name, new ShovelFileHandle(this.#backend, entryPath)];
+      } else {
+        yield [entry.name, new ShovelDirectoryHandle(this.#backend, entryPath)];
+      }
+    }
+  }
   async *keys() {
     for await (const [name] of this.entries()) {
       yield name;
@@ -202,12 +253,13 @@ var BunS3FileSystemDirectoryHandle = class _BunS3FileSystemDirectoryHandle {
       yield handle;
     }
   }
+  [Symbol.asyncIterator]() {
+    return this.entries();
+  }
   async isSameEntry(other) {
     if (other.kind !== "directory")
       return false;
-    if (!(other instanceof _BunS3FileSystemDirectoryHandle))
-      return false;
-    return this.prefix === other.prefix;
+    return other instanceof _S3Bucket && other.name === this.name;
   }
   async queryPermission() {
     return "granted";
@@ -216,29 +268,7 @@ var BunS3FileSystemDirectoryHandle = class _BunS3FileSystemDirectoryHandle {
     return "granted";
   }
 };
-var S3Bucket = class {
-  config;
-  s3Client;
-  constructor(s3Client, config = {}) {
-    this.config = {
-      name: "bun-s3",
-      ...config
-    };
-    this.s3Client = s3Client;
-  }
-  async getDirectoryHandle(name) {
-    const prefix = name ? `filesystems/${name}` : "filesystems/root";
-    return new BunS3FileSystemDirectoryHandle(this.s3Client, prefix);
-  }
-  getConfig() {
-    return { ...this.config };
-  }
-  async dispose() {
-  }
-};
 export {
-  BunS3FileSystemDirectoryHandle,
-  BunS3FileSystemFileHandle,
-  BunS3FileSystemWritableFileStream,
-  S3Bucket
+  S3Bucket,
+  S3FileSystemBackend
 };

package/src/index.d.ts

@@ -1,6 +1,215 @@
-export type { Bucket, FileSystemConfig } from "./types.js";
-export { MemoryBucket } from "./memory.js";
-export { LocalBucket, NodeFileSystemDirectoryHandle, NodeFileSystemFileHandle } from "./node.js";
-export { S3Bucket, BunS3FileSystemDirectoryHandle, BunS3FileSystemFileHandle } from "./bun-s3.js";
-export { BucketStorage } from "./directory-storage.js";
-export { FileSystemRegistry, getDirectoryHandle, getBucket, getFileSystemRoot } from "./registry.js";
+/**
+ * Configuration for filesystem adapters
+ */
+export interface FileSystemConfig {
+    /** Human readable name for this filesystem */
+    name?: string;
+    /** Platform-specific configuration */
+    [key: string]: any;
+}
+/**
+ * Bucket is a semantic alias for FileSystemDirectoryHandle
+ * Represents a named storage bucket that provides direct filesystem access
+ */
+export type Bucket = FileSystemDirectoryHandle;
+/**
+ * Permission descriptor for File System Access API
+ */
+export interface FileSystemPermissionDescriptor {
+    mode?: "read" | "readwrite";
+}
+/**
+ * Storage backend interface that abstracts filesystem operations
+ * across different storage types (memory, local disk, S3, R2, etc.)
+ */
+export interface FileSystemBackend {
+    /**
+     * Check if entry exists and return its type
+     * @param path Path to the entry
+     * @returns Entry info if exists, null if not found
+     */
+    stat(path: string): Promise<{
+        kind: "file" | "directory";
+    } | null>;
+    /**
+     * Read file content and metadata
+     * @param path Path to the file
+     * @returns File content and metadata
+     * @throws NotFoundError if file doesn't exist
+     */
+    readFile(path: string): Promise<{
+        content: Uint8Array;
+        lastModified?: number;
+    }>;
+    /**
+     * Write file content
+     * @param path Path to the file
+     * @param data File content as Uint8Array
+     * @throws Error if write fails
+     */
+    writeFile(path: string, data: Uint8Array): Promise<void>;
+    /**
+     * List directory entries
+     * @param path Path to the directory
+     * @returns Array of entry info (name + type)
+     * @throws NotFoundError if directory doesn't exist
+     */
+    listDir(path: string): Promise<Array<{
+        name: string;
+        kind: "file" | "directory";
+    }>>;
+    /**
+     * Create directory (optional - some backends may not support this)
+     * @param path Path to the directory to create
+     * @throws NotSupportedError if backend doesn't support directory creation
+     */
+    createDir?(path: string): Promise<void>;
+    /**
+     * Remove entry (optional - some backends may not support this)
+     * @param path Path to the entry to remove
+     * @param recursive Whether to remove directories recursively
+     * @throws NotSupportedError if backend doesn't support removal
+     */
+    remove?(path: string, recursive?: boolean): Promise<void>;
+}
+/**
+ * Shared FileSystemHandle base implementation
+ * Provides common functionality for both file and directory handles
+ */
+export declare abstract class ShovelHandle implements FileSystemHandle {
+    #private;
+    abstract readonly kind: "file" | "directory";
+    readonly path: string;
+    constructor(backend: FileSystemBackend, path: string);
+    get name(): string;
+    get backend(): FileSystemBackend;
+    isSameEntry(other: FileSystemHandle): Promise<boolean>;
+    queryPermission(descriptor?: FileSystemPermissionDescriptor): Promise<PermissionState>;
+    requestPermission(descriptor?: FileSystemPermissionDescriptor): Promise<PermissionState>;
+    /**
+     * Validates that a name is actually a name and not a path
+     * The File System Access API only accepts names, not paths
+     */
+    validateName(name: string): void;
+}
+/**
+ * Shared FileSystemFileHandle implementation that works with any backend
+ * Uses non-standard constructor that takes backend + path
+ */
+export declare class ShovelFileHandle extends ShovelHandle implements FileSystemFileHandle {
+    #private;
+    readonly kind: "file";
+    constructor(backend: FileSystemBackend, path: string);
+    getFile(): Promise<File>;
+    createWritable(): Promise<FileSystemWritableFileStream>;
+    createSyncAccessHandle(): Promise<FileSystemSyncAccessHandle>;
+}
+/**
+ * Shared FileSystemDirectoryHandle implementation that works with any backend
+ * Uses non-standard constructor that takes backend + path
+ */
+export declare class ShovelDirectoryHandle extends ShovelHandle implements FileSystemDirectoryHandle {
+    #private;
+    readonly kind: "directory";
+    constructor(backend: FileSystemBackend, path: string);
+    getFileHandle(name: string, options?: {
+        create?: boolean;
+    }): Promise<FileSystemFileHandle>;
+    getDirectoryHandle(name: string, options?: {
+        create?: boolean;
+    }): Promise<FileSystemDirectoryHandle>;
+    removeEntry(name: string, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    resolve(possibleDescendant: FileSystemHandle): Promise<string[] | null>;
+    entries(): AsyncIterableIterator<[
+        string,
+        FileSystemFileHandle | FileSystemDirectoryHandle
+    ]>;
+    keys(): AsyncIterableIterator<string>;
+    values(): AsyncIterableIterator<FileSystemFileHandle | FileSystemDirectoryHandle>;
+    [Symbol.asyncIterator](): AsyncIterableIterator<[
+        string,
+        FileSystemFileHandle | FileSystemDirectoryHandle
+    ]>;
+}
+/**
+ * Bucket storage interface - parallels CacheStorage for filesystem access
+ * This could become a future web standard
+ */
+export interface BucketStorage {
+    /**
+     * Open a named bucket - returns FileSystemDirectoryHandle (root of that bucket)
+     * Well-known names: 'static', 'tmp'
+     */
+    open(name: string): Promise<FileSystemDirectoryHandle>;
+    /**
+     * Check if a named bucket exists
+     */
+    has(name: string): Promise<boolean>;
+    /**
+     * Delete a named bucket and all its contents
+     */
+    delete(name: string): Promise<boolean>;
+    /**
+     * List all available bucket names
+     */
+    keys(): Promise<string[]>;
+}
+/**
+ * Factory function type for creating buckets
+ * @param name Bucket name to create
+ * @returns FileSystemDirectoryHandle (Bucket) instance
+ */
+export type BucketFactory = (name: string) => FileSystemDirectoryHandle | Promise<FileSystemDirectoryHandle>;
+/**
+ * Custom bucket storage with factory-based bucket creation
+ *
+ * Provides a registry of named buckets (FileSystemDirectoryHandle instances)
+ * with lazy instantiation and singleton behavior per bucket name.
+ *
+ * Mirrors the CustomCacheStorage pattern for consistency across the platform.
+ */
+export declare class CustomBucketStorage {
+    #private;
+    /**
+     * @param factory Function that creates bucket instances by name
+     */
+    constructor(factory: BucketFactory);
+    /**
+     * Open a named bucket - creates if it doesn't exist
+     *
+     * @param name Bucket name (e.g., 'tmp', 'dist', 'uploads')
+     * @returns FileSystemDirectoryHandle for the bucket
+     */
+    open(name: string): Promise<FileSystemDirectoryHandle>;
+    /**
+     * Check if a named bucket exists
+     *
+     * @param name Bucket name to check
+     * @returns true if bucket has been opened
+     */
+    has(name: string): Promise<boolean>;
+    /**
+     * Delete a named bucket
+     *
+     * @param name Bucket name to delete
+     * @returns true if bucket was deleted, false if it didn't exist
+     */
+    delete(name: string): Promise<boolean>;
+    /**
+     * List all opened bucket names
+     *
+     * @returns Array of bucket names
+     */
+    keys(): Promise<string[]>;
+    /**
+     * Get statistics about opened buckets (non-standard utility method)
+     *
+     * @returns Object with bucket statistics
+     */
+    getStats(): {
+        openInstances: number;
+        bucketNames: string[];
+    };
+}