@b9g/filesystem 0.1.1 → 0.1.4

package/README.md

@@ -0,0 +1,339 @@
+# @b9g/filesystem
+
+Universal filesystem abstraction with multiple backend implementations for different runtimes and storage systems.
+
+## Features
+
+- **Universal API**: Same interface across Node.js, Bun, browsers, and edge platforms
+- **Multiple Backends**: Memory, Node.js fs, Bun, S3, R2, and more
+- **Registry Pattern**: Register filesystem implementations by name
+- **Async/Await**: Promise-based API throughout
+- **Directory Handles**: File System Access API compatible
+
+## Installation
+
+```bash
+npm install @b9g/filesystem
+```
+
+## Quick Start
+
+```javascript
+import { FilesystemRegistry, MemoryFilesystem } from '@b9g/filesystem';
+
+// Create registry
+const registry = new FilesystemRegistry();
+
+// Register backends
+registry.register('memory', () => new MemoryFilesystem());
+registry.register('temp', () => new NodeFilesystem('/tmp'));
+
+// Get filesystem
+const fs = await registry.get('memory');
+
+// Create directory
+const dir = await fs.getDirectoryHandle('projects', { create: true });
+
+// Create file
+const file = await dir.getFileHandle('readme.txt', { create: true });
+
+// Write content
+const writable = await file.createWritable();
+await writable.write('Hello World!');
+await writable.close();
+
+// Read content
+const fileData = await file.getFile();
+const text = await fileData.text();
+console.log(text); // 'Hello World!'
+```
+
+## Filesystem Implementations
+
+### MemoryFilesystem
+
+In-memory filesystem for testing and temporary storage:
+
+```javascript
+import { MemoryFilesystem } from '@b9g/filesystem';
+
+const fs = new MemoryFilesystem();
+```
+
+### NodeFilesystem
+
+Node.js filesystem backend:
+
+```javascript
+import { NodeFilesystem } from '@b9g/filesystem';
+
+const fs = new NodeFilesystem('/app/data');
+```
+
+### BunS3Filesystem  
+
+Bun with S3-compatible storage:
+
+```javascript
+import { BunS3Filesystem } from '@b9g/filesystem';
+
+const fs = new BunS3Filesystem({
+  bucket: 'my-bucket',
+  region: 'us-east-1',
+  accessKeyId: process.env.AWS_ACCESS_KEY_ID,
+  secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY
+});
+```
+
+## Registry Usage
+
+```javascript
+import { 
+  FilesystemRegistry,
+  MemoryFilesystem,
+  NodeFilesystem
+} from '@b9g/filesystem';
+
+const registry = new FilesystemRegistry();
+
+// Register implementations
+registry.register('memory', () => new MemoryFilesystem());
+registry.register('local', () => new NodeFilesystem('./data'));
+registry.register('temp', () => new NodeFilesystem('/tmp'));
+
+// Use by name
+const memFs = await registry.get('memory');
+const localFs = await registry.get('local');
+```
+
+## File System Access API
+
+Compatible with the File System Access API:
+
+```javascript
+// Get directory handle
+const dirHandle = await fs.getDirectoryHandle('uploads', { create: true });
+
+// List directory contents
+for await (const [name, handle] of dirHandle.entries()) {
+  if (handle.kind === 'file') {
+    console.log(`File: ${name}`);
+  } else {
+    console.log(`Directory: ${name}`);
+  }
+}
+
+// Get file handle
+const fileHandle = await dirHandle.getFileHandle('data.json', { create: true });
+
+// Check if exists
+try {
+  await dirHandle.getFileHandle('missing.txt');
+} catch (error) {
+  console.log('File does not exist');
+}
+
+// Remove file
+await dirHandle.removeEntry('old-file.txt');
+
+// Remove directory
+await dirHandle.removeEntry('old-dir', { recursive: true });
+```
+
+## File Operations
+
+### Writing Files
+
+```javascript
+// Get file handle
+const file = await dir.getFileHandle('config.json', { create: true });
+
+// Create writable stream
+const writable = await file.createWritable();
+
+// Write data
+await writable.write(JSON.stringify({ setting: 'value' }));
+await writable.close();
+
+// Or write all at once
+await writable.write(new Blob(['Hello World']));
+await writable.close();
+```
+
+### Reading Files
+
+```javascript
+// Get file handle
+const file = await dir.getFileHandle('config.json');
+
+// Get file object
+const fileData = await file.getFile();
+
+// Read as text
+const text = await fileData.text();
+
+// Read as JSON
+const json = JSON.parse(text);
+
+// Read as ArrayBuffer
+const buffer = await fileData.arrayBuffer();
+
+// Read as stream
+const stream = fileData.stream();
+```
+
+## Integration Examples
+
+### Cache Storage
+
+```javascript
+import { FilesystemRegistry, NodeFilesystem } from '@b9g/filesystem';
+
+const registry = new FilesystemRegistry();
+registry.register('cache', () => new NodeFilesystem('./cache'));
+
+// Use with cache
+const fs = await registry.get('cache');
+const cacheDir = await fs.getDirectoryHandle('pages', { create: true });
+
+// Store cached response
+const file = await cacheDir.getFileHandle('index.html', { create: true });
+const writable = await file.createWritable();
+await writable.write('<html>...</html>');
+await writable.close();
+```
+
+### Asset Pipeline
+
+```javascript
+// Static assets filesystem
+registry.register('assets', () => new NodeFilesystem('./dist/assets'));
+
+const assets = await registry.get('assets');
+const staticDir = await assets.getDirectoryHandle('static', { create: true });
+
+// Copy build assets
+for (const asset of buildAssets) {
+  const file = await staticDir.getFileHandle(asset.name, { create: true });
+  const writable = await file.createWritable();
+  await writable.write(asset.content);
+  await writable.close();
+}
+```
+
+### Upload Handling
+
+```javascript
+router.post('/upload', async (request) => {
+  const formData = await request.formData();
+  const file = formData.get('file');
+  
+  if (file) {
+    const uploads = await registry.get('uploads');
+    const uploadsDir = await uploads.getDirectoryHandle('files', { create: true });
+    
+    const fileHandle = await uploadsDir.getFileHandle(file.name, { create: true });
+    const writable = await fileHandle.createWritable();
+    await writable.write(await file.arrayBuffer());
+    await writable.close();
+    
+    return Response.json({ success: true, filename: file.name });
+  }
+  
+  return BadRequest('No file provided');
+});
+```
+
+## API Reference
+
+### FilesystemRegistry
+
+```typescript
+class FilesystemRegistry {
+  register(name: string, factory: () => Filesystem): void;
+  get(name: string): Promise<Filesystem>;
+  has(name: string): boolean;
+  delete(name: string): boolean;
+  keys(): string[];
+}
+```
+
+### Filesystem Interface
+
+```typescript
+interface Filesystem {
+  getDirectoryHandle(name: string, options?: GetDirectoryOptions): Promise<DirectoryHandle>;
+}
+
+interface DirectoryHandle {
+  kind: 'directory';
+  name: string;
+  
+  getDirectoryHandle(name: string, options?: GetDirectoryOptions): Promise<DirectoryHandle>;
+  getFileHandle(name: string, options?: GetFileOptions): Promise<FileHandle>;
+  removeEntry(name: string, options?: RemoveOptions): Promise<void>;
+  entries(): AsyncIterableIterator<[string, DirectoryHandle | FileHandle]>;
+  keys(): AsyncIterableIterator<string>;
+  values(): AsyncIterableIterator<DirectoryHandle | FileHandle>;
+}
+
+interface FileHandle {
+  kind: 'file';
+  name: string;
+  
+  getFile(): Promise<File>;
+  createWritable(options?: CreateWritableOptions): Promise<WritableStream>;
+}
+```
+
+## Backend-Specific Options
+
+### S3 Configuration
+
+```javascript
+import { BunS3Filesystem } from '@b9g/filesystem';
+
+const s3fs = new BunS3Filesystem({
+  bucket: 'my-bucket',
+  region: 'us-west-2',
+  endpoint: 'https://s3.us-west-2.amazonaws.com',
+  accessKeyId: process.env.AWS_ACCESS_KEY_ID,
+  secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
+  pathStyle: false,
+  prefix: 'app-data/'
+});
+```
+
+### Memory Options
+
+```javascript
+import { MemoryFilesystem } from '@b9g/filesystem';
+
+const memfs = new MemoryFilesystem({
+  maxSize: 100 * 1024 * 1024, // 100MB limit
+  caseSensitive: true
+});
+```
+
+## Error Handling
+
+```javascript
+try {
+  const file = await dir.getFileHandle('missing.txt');
+} catch (error) {
+  if (error.name === 'NotFoundError') {
+    console.log('File not found');
+  } else {
+    console.error('Unexpected error:', error);
+  }
+}
+
+// Check before accessing
+const exists = await dir.getFileHandle('data.txt')
+  .then(() => true)
+  .catch(() => false);
+```
+
+## License
+
+MIT

package/package.json

@@ -1,14 +1,20 @@
 {
   "name": "@b9g/filesystem",
-  "version": "0.1.1",
+  "version": "0.1.4",
   "description": "Universal File System Access API implementations for all platforms",
   "license": "MIT",
   "devDependencies": {
-    "@b9g/libuild": "^0.1.10",
+    "@b9g/libuild": "^0.1.11",
     "@types/bun": "^1.2.2"
   },
   "peerDependencies": {
-    "@types/wicg-file-system-access": "^2023.10.7"
+    "@types/wicg-file-system-access": "^2023.10.7",
+    "@types/node": "^18.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@types/node": {
+      "optional": true
+    }
   },
   "type": "module",
   "types": "src/index.d.ts",
@@ -66,6 +72,14 @@
       "types": "./src/types.d.ts",
       "import": "./src/types.js"
     },
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./directory-storage": {
+      "types": "./src/directory-storage.d.ts",
+      "import": "./src/directory-storage.js"
+    },
+    "./directory-storage.js": {
+      "types": "./src/directory-storage.d.ts",
+      "import": "./src/directory-storage.js"
+    }
   }
 }

package/src/bun-s3.d.ts

@@ -4,7 +4,7 @@
  * Leverages Bun's native S3Client and S3File for high-performance
  * cloud storage operations with File System Access API compatibility.
  */
-import type { FileSystemAdapter, FileSystemConfig } from "@b9g/filesystem";
+import type { Bucket, FileSystemConfig } from "./types.js";
 /**
  * Bun S3 implementation of FileSystemWritableFileStream
  */
@@ -59,13 +59,13 @@ export declare class BunS3FileSystemDirectoryHandle implements FileSystemDirecto
     requestPermission(): Promise<PermissionState>;
 }
 /**
- * Bun S3 filesystem adapter using Bun's native S3Client
+ * S3 bucket using Bun's native S3Client
  */
-export declare class BunS3FileSystemAdapter implements FileSystemAdapter {
+export declare class S3Bucket implements Bucket {
     private config;
     private s3Client;
     constructor(s3Client: any, config?: FileSystemConfig);
-    getFileSystemRoot(name?: string): Promise<FileSystemDirectoryHandle>;
+    getDirectoryHandle(name: string): Promise<FileSystemDirectoryHandle>;
     getConfig(): FileSystemConfig;
     dispose(): Promise<void>;
 }

package/src/bun-s3.js

@@ -216,7 +216,7 @@ var BunS3FileSystemDirectoryHandle = class _BunS3FileSystemDirectoryHandle {
     return "granted";
   }
 };
-var BunS3FileSystemAdapter = class {
+var S3Bucket = class {
   config;
   s3Client;
   constructor(s3Client, config = {}) {
@@ -226,8 +226,8 @@ var BunS3FileSystemAdapter = class {
     };
     this.s3Client = s3Client;
   }
-  async getFileSystemRoot(name = "default") {
-    const prefix = `filesystems/${name}`;
+  async getDirectoryHandle(name) {
+    const prefix = name ? `filesystems/${name}` : "filesystems/root";
     return new BunS3FileSystemDirectoryHandle(this.s3Client, prefix);
   }
   getConfig() {
@@ -237,8 +237,8 @@ var BunS3FileSystemAdapter = class {
   }
 };
 export {
-  BunS3FileSystemAdapter,
   BunS3FileSystemDirectoryHandle,
   BunS3FileSystemFileHandle,
-  BunS3FileSystemWritableFileStream
+  BunS3FileSystemWritableFileStream,
+  S3Bucket
 };

package/src/directory-storage.d.ts

@@ -0,0 +1,50 @@
+import type { Bucket } from "./types.js";
+/**
+ * BucketStorage implements bucket storage with a configurable factory
+ * The factory function receives the bucket name and can return different filesystem types
+ * This mirrors the CustomCacheStorage pattern for consistency
+ *
+ * Example usage:
+ * ```typescript
+ * const buckets = new BucketStorage((name) => {
+ *   if (name === 'uploads') return new S3Bucket('my-bucket');
+ *   if (name === 'temp') return new LocalBucket('/tmp');
+ *   return new LocalBucket('./dist'); // Default to dist
+ * });
+ * ```
+ */
+export declare class BucketStorage {
+    private factory;
+    private instances;
+    constructor(factory: (name: string) => Bucket | Promise<Bucket>);
+    /**
+     * Opens a bucket with the given name
+     * Returns existing instance if already opened, otherwise creates a new one
+     */
+    open(name: string): Promise<FileSystemDirectoryHandle>;
+    /**
+     * Returns true if a bucket with the given name exists (has been opened)
+     */
+    has(name: string): Promise<boolean>;
+    /**
+     * Deletes a bucket with the given name
+     * Disposes of the instance if it exists
+     */
+    delete(name: string): Promise<boolean>;
+    /**
+     * Returns a list of all opened bucket names
+     */
+    keys(): Promise<string[]>;
+    /**
+     * Get statistics about the bucket storage
+     */
+    getStats(): {
+        openInstances: number;
+        bucketNames: string[];
+    };
+    /**
+     * Dispose of all open adapter instances
+     * Useful for cleanup during shutdown
+     */
+    dispose(): Promise<void>;
+}

package/src/directory-storage.js

@@ -0,0 +1,74 @@
+/// <reference types="./directory-storage.d.ts" />
+// src/directory-storage.ts
+var BucketStorage = class {
+  constructor(factory) {
+    this.factory = factory;
+  }
+  instances = /* @__PURE__ */ new Map();
+  /**
+   * Opens a bucket with the given name
+   * Returns existing instance if already opened, otherwise creates a new one
+   */
+  async open(name) {
+    const existingInstance = this.instances.get(name);
+    if (existingInstance) {
+      return await existingInstance.getDirectoryHandle("");
+    }
+    const adapter = await this.factory(name);
+    this.instances.set(name, adapter);
+    return await adapter.getDirectoryHandle("");
+  }
+  /**
+   * Returns true if a bucket with the given name exists (has been opened)
+   */
+  async has(name) {
+    return this.instances.has(name);
+  }
+  /**
+   * Deletes a bucket with the given name
+   * Disposes of the instance if it exists
+   */
+  async delete(name) {
+    const instance = this.instances.get(name);
+    if (instance) {
+      if (instance.dispose) {
+        await instance.dispose();
+      }
+      this.instances.delete(name);
+      return true;
+    }
+    return false;
+  }
+  /**
+   * Returns a list of all opened bucket names
+   */
+  async keys() {
+    return Array.from(this.instances.keys());
+  }
+  /**
+   * Get statistics about the bucket storage
+   */
+  getStats() {
+    return {
+      openInstances: this.instances.size,
+      bucketNames: Array.from(this.instances.keys())
+    };
+  }
+  /**
+   * Dispose of all open adapter instances
+   * Useful for cleanup during shutdown
+   */
+  async dispose() {
+    const disposePromises = [];
+    for (const [_name, instance] of this.instances) {
+      if (instance.dispose) {
+        disposePromises.push(instance.dispose());
+      }
+    }
+    await Promise.all(disposePromises);
+    this.instances.clear();
+  }
+};
+export {
+  BucketStorage
+};

package/src/index.d.ts

@@ -1,5 +1,6 @@
-export type { FileSystemAdapter, FileSystemConfig } from "./types.js";
-export { MemoryFileSystemAdapter } from "./memory.js";
-export { NodeFileSystemAdapter, NodeFileSystemDirectoryHandle, NodeFileSystemFileHandle } from "./node.js";
-export { BunS3FileSystemAdapter, BunS3FileSystemDirectoryHandle, BunS3FileSystemFileHandle } from "./bun-s3.js";
-export { FileSystemRegistry, getFileSystemRoot } from "./registry.js";
+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";

package/src/index.js

@@ -1,17 +1,21 @@
 /// <reference types="./index.d.ts" />
 // src/index.ts
-import { MemoryFileSystemAdapter } from "./memory.js";
-import { NodeFileSystemAdapter, NodeFileSystemDirectoryHandle, NodeFileSystemFileHandle } from "./node.js";
-import { BunS3FileSystemAdapter, BunS3FileSystemDirectoryHandle, BunS3FileSystemFileHandle } from "./bun-s3.js";
-import { FileSystemRegistry, getFileSystemRoot } from "./registry.js";
+import { MemoryBucket } from "./memory.js";
+import { LocalBucket, NodeFileSystemDirectoryHandle, NodeFileSystemFileHandle } from "./node.js";
+import { S3Bucket, BunS3FileSystemDirectoryHandle, BunS3FileSystemFileHandle } from "./bun-s3.js";
+import { BucketStorage } from "./directory-storage.js";
+import { FileSystemRegistry, getDirectoryHandle, getBucket, getFileSystemRoot } from "./registry.js";
 export {
-  BunS3FileSystemAdapter,
+  BucketStorage,
   BunS3FileSystemDirectoryHandle,
   BunS3FileSystemFileHandle,
   FileSystemRegistry,
-  MemoryFileSystemAdapter,
-  NodeFileSystemAdapter,
+  LocalBucket,
+  MemoryBucket,
   NodeFileSystemDirectoryHandle,
   NodeFileSystemFileHandle,
+  S3Bucket,
+  getBucket,
+  getDirectoryHandle,
   getFileSystemRoot
 };

package/src/memory.d.ts

@@ -4,15 +4,15 @@
  * Provides a complete filesystem interface using in-memory data structures.
  * Useful for testing, development, and temporary storage scenarios.
  */
-import type { FileSystemAdapter, FileSystemConfig } from "./types.js";
+import type { Bucket, FileSystemConfig } from "./types.js";
 /**
- * Memory filesystem adapter
+ * Memory bucket
  */
-export declare class MemoryFileSystemAdapter implements FileSystemAdapter {
+export declare class MemoryBucket implements Bucket {
     private config;
     private filesystems;
     constructor(config?: FileSystemConfig);
-    getFileSystemRoot(name?: string): Promise<FileSystemDirectoryHandle>;
+    getDirectoryHandle(name: string): Promise<FileSystemDirectoryHandle>;
     getConfig(): FileSystemConfig;
     dispose(): Promise<void>;
 }

package/src/memory.js

@@ -190,7 +190,7 @@ var MemoryFileSystemDirectoryHandle = class _MemoryFileSystemDirectoryHandle {
     return "granted";
   }
 };
-var MemoryFileSystemAdapter = class {
+var MemoryBucket = class {
   config;
   filesystems = /* @__PURE__ */ new Map();
   constructor(config = {}) {
@@ -199,16 +199,17 @@ var MemoryFileSystemAdapter = class {
       ...config
     };
   }
-  async getFileSystemRoot(name = "default") {
-    if (!this.filesystems.has(name)) {
+  async getDirectoryHandle(name) {
+    const dirName = name || "root";
+    if (!this.filesystems.has(dirName)) {
       const root2 = {
         name: "root",
         files: /* @__PURE__ */ new Map(),
         directories: /* @__PURE__ */ new Map()
       };
-      this.filesystems.set(name, root2);
+      this.filesystems.set(dirName, root2);
     }
-    const root = this.filesystems.get(name);
+    const root = this.filesystems.get(dirName);
     return new MemoryFileSystemDirectoryHandle(root);
   }
   getConfig() {
@@ -219,5 +220,5 @@ var MemoryFileSystemAdapter = class {
   }
 };
 export {
-  MemoryFileSystemAdapter
+  MemoryBucket
 };

package/src/node.d.ts

@@ -4,7 +4,7 @@
  * Implements FileSystemDirectoryHandle and FileSystemFileHandle using fs/promises
  * to provide universal File System Access API on Node.js platforms.
  */
-import type { FileSystemAdapter, FileSystemConfig } from "./types.js";
+import type { Bucket, FileSystemConfig } from "./types.js";
 /**
  * Node.js implementation of FileSystemWritableFileStream
  */
@@ -56,12 +56,12 @@ export declare class NodeFileSystemDirectoryHandle implements FileSystemDirector
     requestPermission(): Promise<PermissionState>;
 }
 /**
- * Node.js filesystem adapter
+ * Local filesystem bucket using Node.js fs
  */
-export declare class NodeFileSystemAdapter implements FileSystemAdapter {
+export declare class LocalBucket implements Bucket {
     private config;
     private rootPath;
     constructor(config?: FileSystemConfig);
-    getFileSystemRoot(name?: string): Promise<FileSystemDirectoryHandle>;
+    getDirectoryHandle(name: string): Promise<FileSystemDirectoryHandle>;
     getConfig(): FileSystemConfig;
 }

package/src/node.js

@@ -236,7 +236,7 @@ var NodeFileSystemDirectoryHandle = class _NodeFileSystemDirectoryHandle {
     return "granted";
   }
 };
-var NodeFileSystemAdapter = class {
+var LocalBucket = class {
   config;
   rootPath;
   constructor(config = {}) {
@@ -246,20 +246,20 @@ var NodeFileSystemAdapter = class {
     };
     this.rootPath = config.rootPath || path.join(process.cwd(), "dist");
   }
-  async getFileSystemRoot(name = "default") {
-    const bucketPath = path.join(this.rootPath, name);
+  async getDirectoryHandle(name) {
+    const dirPath = name ? path.join(this.rootPath, name) : this.rootPath;
     try {
-      await fs.mkdir(bucketPath, { recursive: true });
+      await fs.mkdir(dirPath, { recursive: true });
     } catch (error) {
     }
-    return new NodeFileSystemDirectoryHandle(bucketPath);
+    return new NodeFileSystemDirectoryHandle(dirPath);
   }
   getConfig() {
     return { ...this.config };
   }
 };
 export {
-  NodeFileSystemAdapter,
+  LocalBucket,
   NodeFileSystemDirectoryHandle,
   NodeFileSystemFileHandle,
   NodeFileSystemWritableFileStream

package/src/registry.d.ts

@@ -36,8 +36,17 @@ declare class Registry {
  */
 export declare const FileSystemRegistry: Registry;
 /**
- * Get a file system root handle using the registered adapters
- * @param name Optional adapter name (uses default if not specified)
+ * Get a file system directory handle using the registered adapters
+ * @param name Directory name. Use "" for root directory
+ * @param adapterName Optional adapter name (uses default if not specified)
+ */
+export declare function getDirectoryHandle(name: string, adapterName?: string): Promise<FileSystemDirectoryHandle>;
+/**
+ * @deprecated Use getDirectoryHandle() instead
+ */
+export declare function getBucket(name?: string, adapterName?: string): Promise<FileSystemDirectoryHandle>;
+/**
+ * @deprecated Use getDirectoryHandle() instead
  */
 export declare function getFileSystemRoot(name?: string): Promise<FileSystemDirectoryHandle>;
 export {};

package/src/registry.js

@@ -1,11 +1,11 @@
 /// <reference types="./registry.d.ts" />
 // src/registry.ts
-import { MemoryFileSystemAdapter } from "./memory.js";
+import { MemoryBucket } from "./memory.js";
 var Registry = class {
   adapters = /* @__PURE__ */ new Map();
   defaultAdapter;
   constructor() {
-    this.defaultAdapter = new MemoryFileSystemAdapter();
+    this.defaultAdapter = new MemoryBucket();
   }
   /**
    * Register a filesystem adapter with a name
@@ -46,18 +46,34 @@ var Registry = class {
   }
 };
 var FileSystemRegistry = new Registry();
-async function getFileSystemRoot(name) {
-  const adapter = FileSystemRegistry.get(name);
+async function getDirectoryHandle(name, adapterName) {
+  const adapter = FileSystemRegistry.get(adapterName);
   if (!adapter) {
-    if (name) {
-      throw new Error(`No filesystem adapter registered with name: ${name}`);
+    if (adapterName) {
+      throw new Error(`No filesystem adapter registered with name: ${adapterName}`);
     } else {
       throw new Error("No default filesystem adapter registered");
     }
   }
-  return await adapter.getFileSystemRoot(name);
+  return await adapter.getDirectoryHandle(name);
+}
+async function getBucket(name, adapterName) {
+  const adapter = FileSystemRegistry.get(adapterName);
+  if (!adapter) {
+    throw new Error("No default filesystem adapter registered");
+  }
+  return await adapter.getDirectoryHandle(name || "");
+}
+async function getFileSystemRoot(name) {
+  const adapter = FileSystemRegistry.get();
+  if (!adapter) {
+    throw new Error("No default filesystem adapter registered");
+  }
+  return await adapter.getDirectoryHandle(name || "");
 }
 export {
   FileSystemRegistry,
+  getBucket,
+  getDirectoryHandle,
   getFileSystemRoot
 };

package/src/types.d.ts

@@ -11,21 +11,21 @@ export interface FileSystemConfig {
     [key: string]: any;
 }
 /**
- * Core interface that all filesystem adapters must implement
+ * Core interface that all buckets must implement
  * Provides File System Access API compatibility across all platforms
  */
-export interface FileSystemAdapter {
+export interface Bucket {
     /**
-     * Get a root directory handle for the filesystem
-     * @param name Optional filesystem name/bucket identifier
+     * Get a directory handle for the bucket
+     * @param name Directory name. Use "" for root directory
      */
-    getFileSystemRoot(name?: string): Promise<FileSystemDirectoryHandle>;
+    getDirectoryHandle(name: string): Promise<FileSystemDirectoryHandle>;
     /**
-     * Get configuration for this adapter
+     * Get configuration for this bucket
      */
     getConfig(): FileSystemConfig;
     /**
-     * Cleanup resources when adapter is no longer needed
+     * Cleanup resources when bucket is no longer needed
      */
     dispose?(): Promise<void>;
 }