@b9g/filesystem 0.1.7 → 0.1.8

package/README.md

@@ -251,28 +251,28 @@ router.post('/upload', async (request) => {
 - `ShovelFileHandle` - FileSystemFileHandle implementation
 - `ShovelDirectoryHandle` - FileSystemDirectoryHandle implementation
 - `ShovelHandle` - Base handle class
-- `CustomBucketStorage` - Bucket storage with custom backend factories
+- `CustomDirectoryStorage` - Directory storage with custom backend factories
 
 ### Types
 
-- `Bucket` - Alias for FileSystemDirectoryHandle
-- `BucketStorage` - Interface for bucket storage (`open(name): Promise<FileSystemDirectoryHandle>`)
-- `BucketFactory` - Factory function type for creating bucket backends
+- `Directory` - Alias for FileSystemDirectoryHandle
+- `DirectoryStorage` - Interface for directory storage (`open(name): Promise<FileSystemDirectoryHandle>`)
+- `DirectoryFactory` - Factory function type for creating directory backends
 - `FileSystemConfig` - Configuration for filesystem backends
 - `FileSystemPermissionDescriptor` - Permission descriptor type
 - `FileSystemBackend` - Backend interface for filesystem implementations
 
 ## API Reference
 
-### BucketStorage
+### DirectoryStorage
 
 ```typescript
-interface BucketStorage {
+interface DirectoryStorage {
   open(name: string): Promise<FileSystemDirectoryHandle>;
 }
 
-class CustomBucketStorage implements BucketStorage {
-  register(name: string, factory: BucketFactory): void;
+class CustomDirectoryStorage implements DirectoryStorage {
+  register(name: string, factory: DirectoryFactory): void;
   open(name: string): Promise<FileSystemDirectoryHandle>;
 }
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@b9g/filesystem",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "Universal File System Access API implementations for all platforms",
   "license": "MIT",
   "dependencies": {
@@ -50,13 +50,13 @@
       "types": "./src/memory.d.ts",
       "import": "./src/memory.js"
     },
-    "./node": {
-      "types": "./src/node.d.ts",
-      "import": "./src/node.js"
+    "./node-fs": {
+      "types": "./src/node-fs.d.ts",
+      "import": "./src/node-fs.js"
     },
-    "./node.js": {
-      "types": "./src/node.d.ts",
-      "import": "./src/node.js"
+    "./node-fs.js": {
+      "types": "./src/node-fs.d.ts",
+      "import": "./src/node-fs.js"
     },
     "./package.json": "./package.json"
   }

package/src/bun-s3.d.ts

@@ -1,7 +1,7 @@
 /**
  * Bun S3 filesystem implementation
  *
- * Provides S3Bucket (root) and S3FileSystemBackend for storage operations
+ * Provides S3Directory (root) and S3FileSystemBackend for storage operations
  * using Bun's native S3 client.
  */
 import { type FileSystemBackend } from "./index.js";
@@ -27,16 +27,16 @@ export declare class S3FileSystemBackend implements FileSystemBackend {
     remove(path: string, recursive?: boolean): Promise<void>;
 }
 /**
- * S3 bucket - root entry point for S3 filesystem using Bun's S3 client
+ * S3 directory - root entry point for S3 filesystem using Bun's S3 client
  * Implements FileSystemDirectoryHandle for S3 object storage
  *
  * Example usage with namespacing:
  * ```typescript
  * const s3 = new S3Client({ ... });
  *
- * // Use in CustomBucketStorage factory for multi-tenancy
- * const buckets = new CustomBucketStorage(async (name) => {
- *   return new S3Bucket(
+ * // Use in CustomDirectoryStorage factory for multi-tenancy
+ * const directories = new CustomDirectoryStorage(async (name) => {
+ *   return new S3Directory(
  *     s3,
  *     "my-company-bucket",
  *     `my-app/production/${name}`  // Prefix for isolation
@@ -44,7 +44,7 @@ export declare class S3FileSystemBackend implements FileSystemBackend {
  * });
  * ```
  */
-export declare class S3Bucket implements FileSystemDirectoryHandle {
+export declare class S3Directory implements FileSystemDirectoryHandle {
     #private;
     readonly kind: "directory";
     readonly name: string;

package/src/bun-s3.js

@@ -154,8 +154,7 @@ var S3FileSystemBackend = class {
         }
       }
     } catch (error) {
-      if (error instanceof DOMException)
-        throw error;
+      if (error instanceof DOMException) throw error;
       throw new DOMException("Entry not found", "NotFoundError");
     }
   }
@@ -179,7 +178,7 @@ var S3FileSystemBackend = class {
     return this.#prefix ? `${this.#prefix}/${cleanPath}` : cleanPath;
   }
 };
-var S3Bucket = class _S3Bucket {
+var S3Directory = class _S3Directory {
   kind;
   name;
   #backend;
@@ -257,9 +256,8 @@ var S3Bucket = class _S3Bucket {
     return this.entries();
   }
   async isSameEntry(other) {
-    if (other.kind !== "directory")
-      return false;
-    return other instanceof _S3Bucket && other.name === this.name;
+    if (other.kind !== "directory") return false;
+    return other instanceof _S3Directory && other.name === this.name;
   }
   async queryPermission() {
     return "granted";
@@ -269,6 +267,6 @@ var S3Bucket = class _S3Bucket {
   }
 };
 export {
-  S3Bucket,
+  S3Directory,
   S3FileSystemBackend
 };

package/src/index.d.ts

@@ -7,11 +7,6 @@ export interface FileSystemConfig {
     /** 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
  */
@@ -84,11 +79,12 @@ export declare abstract class ShovelHandle implements FileSystemHandle {
     get name(): string;
     get backend(): FileSystemBackend;
     isSameEntry(other: FileSystemHandle): Promise<boolean>;
-    queryPermission(descriptor?: FileSystemPermissionDescriptor): Promise<PermissionState>;
-    requestPermission(descriptor?: FileSystemPermissionDescriptor): Promise<PermissionState>;
+    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
+     * WPT expects TypeError for invalid names
      */
     validateName(name: string): void;
 }
@@ -134,82 +130,81 @@ export declare class ShovelDirectoryHandle extends ShovelHandle implements FileS
     ]>;
 }
 /**
- * Bucket storage interface - parallels CacheStorage for filesystem access
- * This could become a future web standard
+ * Directory storage interface - parallels CacheStorage for filesystem access
  */
-export interface BucketStorage {
+export interface DirectoryStorage {
     /**
-     * Open a named bucket - returns FileSystemDirectoryHandle (root of that bucket)
+     * Open a named directory - returns FileSystemDirectoryHandle (root)
      * Well-known names: 'static', 'tmp'
      */
     open(name: string): Promise<FileSystemDirectoryHandle>;
     /**
-     * Check if a named bucket exists
+     * Check if a named directory exists
      */
     has(name: string): Promise<boolean>;
     /**
-     * Delete a named bucket and all its contents
+     * Delete a named directory and all its contents
      */
     delete(name: string): Promise<boolean>;
     /**
-     * List all available bucket names
+     * List all available directory names
      */
     keys(): Promise<string[]>;
 }
 /**
- * Factory function type for creating buckets
- * @param name Bucket name to create
- * @returns FileSystemDirectoryHandle (Bucket) instance
+ * Factory function type for creating directories
+ * @param name Directory name to create
+ * @returns FileSystemDirectoryHandle instance
  */
-export type BucketFactory = (name: string) => FileSystemDirectoryHandle | Promise<FileSystemDirectoryHandle>;
+export type DirectoryFactory = (name: string) => FileSystemDirectoryHandle | Promise<FileSystemDirectoryHandle>;
 /**
- * Custom bucket storage with factory-based bucket creation
+ * Custom directory storage with factory-based directory creation
  *
- * Provides a registry of named buckets (FileSystemDirectoryHandle instances)
- * with lazy instantiation and singleton behavior per bucket name.
+ * Provides a registry of named directories (FileSystemDirectoryHandle instances)
+ * with lazy instantiation and singleton behavior per directory name.
  *
  * Mirrors the CustomCacheStorage pattern for consistency across the platform.
  */
-export declare class CustomBucketStorage {
+export declare class CustomDirectoryStorage {
     #private;
     /**
-     * @param factory Function that creates bucket instances by name
+     * @param factory Function that creates directory instances by name
      */
-    constructor(factory: BucketFactory);
+    constructor(factory: DirectoryFactory);
     /**
-     * Open a named bucket - creates if it doesn't exist
+     * Open a named directory - creates if it doesn't exist
      *
-     * @param name Bucket name (e.g., 'tmp', 'dist', 'uploads')
-     * @returns FileSystemDirectoryHandle for the bucket
+     * @param name Directory name (e.g., 'tmp', 'dist', 'uploads')
+     * @returns FileSystemDirectoryHandle for the directory
      */
     open(name: string): Promise<FileSystemDirectoryHandle>;
     /**
-     * Check if a named bucket exists
+     * Check if a named directory exists
      *
-     * @param name Bucket name to check
-     * @returns true if bucket has been opened
+     * @param name Directory name to check
+     * @returns true if directory has been opened
      */
     has(name: string): Promise<boolean>;
     /**
-     * Delete a named bucket
+     * Delete a named directory
      *
-     * @param name Bucket name to delete
-     * @returns true if bucket was deleted, false if it didn't exist
+     * @param name Directory name to delete
+     * @returns true if directory was deleted, false if it didn't exist
      */
     delete(name: string): Promise<boolean>;
     /**
-     * List all opened bucket names
+     * List all opened directory names
      *
-     * @returns Array of bucket names
+     * @returns Array of directory names
      */
     keys(): Promise<string[]>;
     /**
-     * Get statistics about opened buckets (non-standard utility method)
+     * Get statistics about opened directories (non-standard utility method)
      *
-     * @returns Object with bucket statistics
+     * @returns Object with directory statistics
      */
     getStats(): {
         openInstances: number;
-        bucketNames: string[];
+        directoryNames: string[];
     };
 }

package/src/index.js

@@ -41,11 +41,29 @@ var ShovelWritableFileStream = class extends WritableStream {
     try {
       if (typeof data === "string") {
         await writer.write(new TextEncoder().encode(data));
-      } else if (data instanceof Uint8Array || data instanceof ArrayBuffer) {
-        const bytes = data instanceof ArrayBuffer ? new Uint8Array(data) : data;
-        await writer.write(bytes);
+      } else if (data instanceof Uint8Array) {
+        await writer.write(data);
+      } else if (data instanceof ArrayBuffer) {
+        await writer.write(new Uint8Array(data));
+      } else if (data instanceof Blob) {
+        const buffer = await data.arrayBuffer();
+        await writer.write(new Uint8Array(buffer));
+      } else if (ArrayBuffer.isView(data)) {
+        await writer.write(
+          new Uint8Array(data.buffer, data.byteOffset, data.byteLength)
+        );
+      } else if (typeof data === "object" && data !== null && "type" in data) {
+        const params = data;
+        if (params.type === "write" && params.data !== void 0) {
+          await this.write(params.data);
+          return;
+        }
+        throw new DOMException("Invalid write params", "NotSupportedError");
       } else {
-        await writer.write(new TextEncoder().encode(String(data)));
+        throw new DOMException(
+          "Invalid data type for write",
+          "NotSupportedError"
+        );
       }
     } finally {
       writer.releaseLock();
@@ -78,36 +96,30 @@ var ShovelHandle = class _ShovelHandle {
     return this.#backend;
   }
   async isSameEntry(other) {
-    if (other.kind !== this.kind)
-      return false;
-    if (!(other instanceof _ShovelHandle))
-      return false;
+    if (other.kind !== this.kind) return false;
+    if (!(other instanceof _ShovelHandle)) return false;
     return this.path === other.path;
   }
-  async queryPermission(descriptor) {
-    const _mode = descriptor?.mode || "read";
+  async queryPermission(_descriptor) {
     return "granted";
   }
-  async requestPermission(descriptor) {
-    const _mode = descriptor?.mode || "read";
+  async requestPermission(_descriptor) {
     return "granted";
   }
   /**
    * Validates that a name is actually a name and not a path
    * The File System Access API only accepts names, not paths
+   * WPT expects TypeError for invalid names
    */
   validateName(name) {
     if (!name || name.trim() === "") {
-      throw new DOMException("Name cannot be empty", "NotAllowedError");
+      throw new TypeError("Name cannot be empty");
     }
     if (name.includes("/") || name.includes("\\")) {
-      throw new DOMException(
-        "Name cannot contain path separators",
-        "NotAllowedError"
-      );
+      throw new TypeError("Name cannot contain path separators");
     }
     if (name === "." || name === "..") {
-      throw new DOMException("Name cannot be '.' or '..'", "NotAllowedError");
+      throw new TypeError("Name cannot be '.' or '..'");
     }
   }
 };
@@ -249,45 +261,45 @@ var ShovelDirectoryHandle = class _ShovelDirectoryHandle extends ShovelHandle {
     return `${base}/${name}`;
   }
 };
-var CustomBucketStorage = class {
+var CustomDirectoryStorage = class {
   #instances;
   #factory;
   /**
-   * @param factory Function that creates bucket instances by name
+   * @param factory Function that creates directory instances by name
    */
   constructor(factory) {
     this.#instances = /* @__PURE__ */ new Map();
     this.#factory = factory;
   }
   /**
-   * Open a named bucket - creates if it doesn't exist
+   * Open a named directory - creates if it doesn't exist
    *
-   * @param name Bucket name (e.g., 'tmp', 'dist', 'uploads')
-   * @returns FileSystemDirectoryHandle for the bucket
+   * @param name Directory name (e.g., 'tmp', 'dist', 'uploads')
+   * @returns FileSystemDirectoryHandle for the directory
    */
   async open(name) {
     const existing = this.#instances.get(name);
     if (existing) {
       return existing;
     }
-    const bucket = await this.#factory(name);
-    this.#instances.set(name, bucket);
-    return bucket;
+    const dir = await this.#factory(name);
+    this.#instances.set(name, dir);
+    return dir;
   }
   /**
-   * Check if a named bucket exists
+   * Check if a named directory exists
    *
-   * @param name Bucket name to check
-   * @returns true if bucket has been opened
+   * @param name Directory name to check
+   * @returns true if directory has been opened
    */
   async has(name) {
     return this.#instances.has(name);
   }
   /**
-   * Delete a named bucket
+   * Delete a named directory
    *
-   * @param name Bucket name to delete
-   * @returns true if bucket was deleted, false if it didn't exist
+   * @param name Directory name to delete
+   * @returns true if directory was deleted, false if it didn't exist
    */
   async delete(name) {
     const instance = this.#instances.get(name);
@@ -298,27 +310,27 @@ var CustomBucketStorage = class {
     return false;
   }
   /**
-   * List all opened bucket names
+   * List all opened directory names
    *
-   * @returns Array of bucket names
+   * @returns Array of directory names
    */
   async keys() {
     return Array.from(this.#instances.keys());
   }
   /**
-   * Get statistics about opened buckets (non-standard utility method)
+   * Get statistics about opened directories (non-standard utility method)
    *
-   * @returns Object with bucket statistics
+   * @returns Object with directory statistics
    */
   getStats() {
     return {
       openInstances: this.#instances.size,
-      bucketNames: Array.from(this.#instances.keys())
+      directoryNames: Array.from(this.#instances.keys())
     };
   }
 };
 export {
-  CustomBucketStorage,
+  CustomDirectoryStorage,
   ShovelDirectoryHandle,
   ShovelFileHandle,
   ShovelHandle

package/src/memory.d.ts

@@ -1,7 +1,7 @@
 /**
  * In-memory filesystem implementation
  *
- * Provides MemoryBucket (root) and MemoryFileSystemBackend for storage operations
+ * Provides MemoryDirectory (root) and MemoryFileSystemBackend for storage operations
  * using in-memory data structures.
  */
 import { type FileSystemBackend } from "./index.js";
@@ -15,19 +15,19 @@ interface MemoryFile {
     type: string;
 }
 /**
- * In-memory directory data
+ * In-memory directory data (internal structure)
  */
-interface MemoryDirectory {
+interface MemoryDirectoryData {
     name: string;
     files: Map<string, MemoryFile>;
-    directories: Map<string, MemoryDirectory>;
+    directories: Map<string, MemoryDirectoryData>;
 }
 /**
  * In-memory storage backend that implements FileSystemBackend
  */
 export declare class MemoryFileSystemBackend implements FileSystemBackend {
     #private;
-    constructor(root: MemoryDirectory);
+    constructor(root: MemoryDirectoryData);
     stat(path: string): Promise<{
         kind: "file" | "directory";
     } | null>;
@@ -44,10 +44,10 @@ export declare class MemoryFileSystemBackend implements FileSystemBackend {
     remove(path: string, recursive?: boolean): Promise<void>;
 }
 /**
- * Memory bucket - root entry point for in-memory filesystem
+ * Memory directory - root entry point for in-memory filesystem
  * Implements FileSystemDirectoryHandle and owns the root data structure
  */
-export declare class MemoryBucket implements FileSystemDirectoryHandle {
+export declare class MemoryDirectory implements FileSystemDirectoryHandle {
     #private;
     readonly kind: "directory";
     readonly name: string;

package/src/memory.js

@@ -11,8 +11,7 @@ var MemoryFileSystemBackend = class {
   }
   async stat(path) {
     const entry = this.#resolvePath(path);
-    if (!entry)
-      return null;
+    if (!entry) return null;
     if ("content" in entry) {
       return { kind: "file" };
     } else {
@@ -115,17 +114,14 @@ var MemoryFileSystemBackend = class {
     let current = this.#root;
     for (let i = 0; i < parts.length - 1; i++) {
       const nextDir = current.directories.get(parts[i]);
-      if (!nextDir)
-        return null;
+      if (!nextDir) return null;
       current = nextDir;
     }
     const finalName = parts[parts.length - 1];
     const file = current.files.get(finalName);
-    if (file)
-      return file;
+    if (file) return file;
     const dir = current.directories.get(finalName);
-    if (dir)
-      return dir;
+    if (dir) return dir;
     return null;
   }
   #resolveParent(path) {
@@ -145,7 +141,7 @@ var MemoryFileSystemBackend = class {
     return { parentDir: current, name };
   }
 };
-var MemoryBucket = class _MemoryBucket {
+var MemoryDirectory = class _MemoryDirectory {
   kind;
   name;
   #backend;
@@ -160,6 +156,15 @@ var MemoryBucket = class _MemoryBucket {
     this.#backend = new MemoryFileSystemBackend(root);
   }
   async getFileHandle(name, options) {
+    if (!name || name.trim() === "") {
+      throw new TypeError("Name cannot be empty");
+    }
+    if (name.includes("/") || name.includes("\\")) {
+      throw new TypeError("Name cannot contain path separators");
+    }
+    if (name === "." || name === "..") {
+      throw new TypeError("Name cannot be '.' or '..'");
+    }
     const filePath = `/${name}`;
     const stat = await this.#backend.stat(filePath);
     if (!stat && options?.create) {
@@ -175,6 +180,15 @@ var MemoryBucket = class _MemoryBucket {
     return new ShovelFileHandle(this.#backend, filePath);
   }
   async getDirectoryHandle(name, options) {
+    if (!name || name.trim() === "") {
+      throw new TypeError("Name cannot be empty");
+    }
+    if (name.includes("/") || name.includes("\\")) {
+      throw new TypeError("Name cannot contain path separators");
+    }
+    if (name === "." || name === "..") {
+      throw new TypeError("Name cannot be '.' or '..'");
+    }
     const dirPath = `/${name}`;
     const stat = await this.#backend.stat(dirPath);
     if (!stat && options?.create) {
@@ -194,6 +208,12 @@ var MemoryBucket = class _MemoryBucket {
     await this.#backend.remove(entryPath, options?.recursive);
   }
   async resolve(possibleDescendant) {
+    if (possibleDescendant instanceof _MemoryDirectory) {
+      if (await this.isSameEntry(possibleDescendant)) {
+        return [];
+      }
+      return null;
+    }
     if (!(possibleDescendant instanceof ShovelDirectoryHandle || possibleDescendant instanceof ShovelFileHandle)) {
       return null;
     }
@@ -228,9 +248,8 @@ var MemoryBucket = class _MemoryBucket {
     return this.entries();
   }
   async isSameEntry(other) {
-    if (other.kind !== "directory")
-      return false;
-    return other instanceof _MemoryBucket && other.name === this.name;
+    if (other.kind !== "directory") return false;
+    return other instanceof _MemoryDirectory && other.name === this.name;
   }
   async queryPermission() {
     return "granted";
@@ -240,6 +259,6 @@ var MemoryBucket = class _MemoryBucket {
   }
 };
 export {
-  MemoryBucket,
+  MemoryDirectory,
   MemoryFileSystemBackend
 };

package/src/node-fs.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Node.js filesystem implementation using node:fs
+ *
+ * Provides NodeFSDirectory (root) and NodeFSBackend for storage operations
+ * using Node.js fs module. Works in both Node.js and Bun.
+ */
+import { type FileSystemBackend, ShovelDirectoryHandle } from "./index.js";
+/**
+ * Node.js storage backend using node:fs
+ */
+export declare class NodeFSBackend implements FileSystemBackend {
+    #private;
+    constructor(rootPath: string);
+    stat(filePath: string): Promise<{
+        kind: "file" | "directory";
+    } | null>;
+    readFile(filePath: string): Promise<{
+        content: Uint8Array;
+        lastModified?: number;
+    }>;
+    writeFile(filePath: string, data: Uint8Array): Promise<void>;
+    listDir(dirPath: string): Promise<Array<{
+        name: string;
+        kind: "file" | "directory";
+    }>>;
+    createDir(dirPath: string): Promise<void>;
+    remove(entryPath: string, recursive?: boolean): Promise<void>;
+}
+/**
+ * Node.js directory using node:fs - root entry point for local filesystem
+ * Extends ShovelDirectoryHandle with "/" as root path
+ */
+export declare class NodeFSDirectory extends ShovelDirectoryHandle {
+    #private;
+    /**
+     * Create a NodeFSDirectory
+     * @param name - Directory name (used for display)
+     * @param options - Options object containing the filesystem path
+     * @param options.path - The actual filesystem path to use as root
+     */
+    constructor(name: string, options?: {
+        path?: string;
+    });
+    get name(): string;
+}

package/src/{node.js → node-fs.js}

@@ -1,9 +1,12 @@
-/// <reference types="./node.d.ts" />
-// src/node.ts
+/// <reference types="./node-fs.d.ts" />
+// src/node-fs.ts
 import { ShovelDirectoryHandle } from "./index.js";
 import * as FS from "fs/promises";
 import * as Path from "path";
-var NodeFileSystemBackend = class {
+function isErrnoException(error) {
+  return error instanceof Error && "code" in error;
+}
+var NodeFSBackend = class {
   #rootPath;
   constructor(rootPath) {
     this.#rootPath = rootPath;
@@ -20,7 +23,7 @@ var NodeFileSystemBackend = class {
         return null;
       }
     } catch (error) {
-      if (error.code === "ENOENT") {
+      if (isErrnoException(error) && error.code === "ENOENT") {
         return null;
       }
       throw error;
@@ -38,7 +41,7 @@ var NodeFileSystemBackend = class {
         lastModified: stats.mtimeMs
       };
     } catch (error) {
-      if (error.code === "ENOENT") {
+      if (isErrnoException(error) && error.code === "ENOENT") {
         throw new DOMException("File not found", "NotFoundError");
       }
       throw error;
@@ -70,7 +73,7 @@ var NodeFileSystemBackend = class {
       }
       return results;
     } catch (error) {
-      if (error.code === "ENOENT") {
+      if (isErrnoException(error) && error.code === "ENOENT") {
         throw new DOMException("Directory not found", "NotFoundError");
       }
       throw error;
@@ -108,7 +111,7 @@ var NodeFileSystemBackend = class {
         }
       }
     } catch (error) {
-      if (error.code === "ENOENT") {
+      if (isErrnoException(error) && error.code === "ENOENT") {
         throw new DOMException("Entry not found", "NotFoundError");
       }
       throw error;
@@ -135,10 +138,17 @@ var NodeFileSystemBackend = class {
     return resolvedPath;
   }
 };
-var NodeBucket = class extends ShovelDirectoryHandle {
+var NodeFSDirectory = class extends ShovelDirectoryHandle {
   #rootPath;
-  constructor(rootPath) {
-    super(new NodeFileSystemBackend(rootPath), "/");
+  /**
+   * Create a NodeFSDirectory
+   * @param name - Directory name (used for display)
+   * @param options - Options object containing the filesystem path
+   * @param options.path - The actual filesystem path to use as root
+   */
+  constructor(name, options) {
+    const rootPath = options?.path ?? name;
+    super(new NodeFSBackend(rootPath), "/");
     this.#rootPath = rootPath;
   }
   // Override name to use the directory basename instead of "/"
@@ -147,6 +157,6 @@ var NodeBucket = class extends ShovelDirectoryHandle {
   }
 };
 export {
-  NodeBucket,
-  NodeFileSystemBackend
+  NodeFSBackend,
+  NodeFSDirectory
 };

package/src/node.d.ts

@@ -1,37 +0,0 @@
-/**
- * Node.js filesystem implementation
- *
- * Provides NodeBucket (root) and NodeFileSystemBackend for storage operations
- * using Node.js fs module.
- */
-import { type FileSystemBackend, ShovelDirectoryHandle } from "./index.js";
-/**
- * Node.js storage backend that implements FileSystemBackend
- */
-export declare class NodeFileSystemBackend implements FileSystemBackend {
-    #private;
-    constructor(rootPath: string);
-    stat(filePath: string): Promise<{
-        kind: "file" | "directory";
-    } | null>;
-    readFile(filePath: string): Promise<{
-        content: Uint8Array;
-        lastModified?: number;
-    }>;
-    writeFile(filePath: string, data: Uint8Array): Promise<void>;
-    listDir(dirPath: string): Promise<Array<{
-        name: string;
-        kind: "file" | "directory";
-    }>>;
-    createDir(dirPath: string): Promise<void>;
-    remove(entryPath: string, recursive?: boolean): Promise<void>;
-}
-/**
- * Node bucket - root entry point for Node.js filesystem
- * Extends ShovelDirectoryHandle with "/" as root path
- */
-export declare class NodeBucket extends ShovelDirectoryHandle {
-    #private;
-    constructor(rootPath: string);
-    get name(): string;
-}