@b9g/filesystem 0.1.11 → 0.2.0

package/README.md

@@ -1,14 +1,6 @@
 # @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
+[File System Access API](https://developer.mozilla.org/en-US/docs/Web/API/File_System_API) implementations for server-side runtimes. Provides `FileSystemDirectoryHandle` and `FileSystemFileHandle` backed by local disk, memory, or S3-compatible storage.
 
 ## Installation
 
@@ -16,364 +8,155 @@ Universal filesystem abstraction with multiple backend implementations for diffe
 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');
+## Backends
 
-// Create directory
-const dir = await fs.getDirectoryHandle('projects', { create: true });
+Each backend is a separate entry point:
 
-// Create file
-const file = await dir.getFileHandle('readme.txt', { create: true });
+### Node.js / Bun local filesystem
 
-// 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';
+```typescript
+import {NodeFSDirectory} from "@b9g/filesystem/node-fs";
 
-const fs = new MemoryFilesystem();
+const dir = new NodeFSDirectory("data", {path: "./data"});
 ```
 
-### NodeFilesystem
-
-Node.js filesystem backend:
+### In-memory
 
-```javascript
-import { NodeFilesystem } from '@b9g/filesystem';
+```typescript
+import {MemoryDirectory} from "@b9g/filesystem/memory";
 
-const fs = new NodeFilesystem('/app/data');
+const dir = new MemoryDirectory();
 ```
 
-### BunS3Filesystem  
-
-Bun with S3-compatible storage:
+### Bun S3
 
-```javascript
-import { BunS3Filesystem } from '@b9g/filesystem';
+```typescript
+import {S3Directory} from "@b9g/filesystem/bun-s3";
 
-const fs = new BunS3Filesystem({
-  bucket: 'my-bucket',
-  region: 'us-east-1',
+const dir = new S3Directory("uploads", {
+  bucket: "my-bucket",
   accessKeyId: process.env.AWS_ACCESS_KEY_ID,
-  secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY
+  secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
 });
 ```
 
-## Registry Usage
-
-```javascript
-import { 
-  FilesystemRegistry,
-  MemoryFilesystem,
-  NodeFilesystem
-} from '@b9g/filesystem';
+## Usage
 
-const registry = new FilesystemRegistry();
+All backends implement the standard `FileSystemDirectoryHandle` interface:
 
-// 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 });
+```typescript
+// Create a directory
+const subdir = await dir.getDirectoryHandle("uploads", {create: true});
 
-// Create writable stream
+// Create and write a file
+const file = await subdir.getFileHandle("readme.txt", {create: true});
 const writable = await file.createWritable();
-
-// Write data
-await writable.write(JSON.stringify({ setting: 'value' }));
+await writable.write("Hello World!");
 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
+// Read a file
 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();
+// List entries
+for await (const [name, handle] of dir.entries()) {
+  console.log(name, handle.kind); // "file" or "directory"
+}
 
-// Read as stream
-const stream = fileData.stream();
+// Remove entries
+await dir.removeEntry("old-file.txt");
+await dir.removeEntry("old-dir", {recursive: true});
 ```
 
 ## Shovel Configuration
 
-When used with Shovel, directories are configured in `shovel.json`. The built-in names `server`, `public`, and `tmp` have platform defaults. Custom directory names require an explicit `module`:
+When used with Shovel, directories are configured in `shovel.json`:
 
 ```json
 {
   "directories": {
     "uploads": {
       "module": "@b9g/filesystem/node-fs",
+      "export": "NodeFSDirectory",
       "path": "./uploads"
-    },
-    "docs": {
-      "module": "@b9g/filesystem/node-fs",
-      "path": "../docs"
     }
   }
 }
 ```
 
-The `path` field is resolved relative to the project root. Paths outside the project (e.g. `"../docs"`) are supported — the root path itself is unrestricted, while directory traversal within opened directories is blocked at the filesystem level.
-
-Access configured directories via the global `self.directories`:
+The `path` field is resolved relative to the project root. Access configured directories via `self.directories`:
 
 ```typescript
 const uploads = await self.directories.open("uploads");
 ```
 
-## Integration Examples
-
-### Cache Storage
+## CustomDirectoryStorage
 
-```javascript
-import { FilesystemRegistry, NodeFilesystem } from '@b9g/filesystem';
+The main entry point exports `CustomDirectoryStorage`, a registry for named directories with lazy instantiation:
 
-const registry = new FilesystemRegistry();
-registry.register('cache', () => new NodeFilesystem('./cache'));
+```typescript
+import {CustomDirectoryStorage} from "@b9g/filesystem";
+import {NodeFSDirectory} from "@b9g/filesystem/node-fs";
 
-// Use with cache
-const fs = await registry.get('cache');
-const cacheDir = await fs.getDirectoryHandle('pages', { create: true });
+const directories = new CustomDirectoryStorage((name) => {
+  return new NodeFSDirectory(name, {path: `./data/${name}`});
+});
 
-// 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();
+const uploads = await directories.open("uploads");
+const tmp = await directories.open("tmp");
 ```
 
-### Asset Pipeline
+## Custom Backends
 
-```javascript
-// Static assets filesystem
-registry.register('assets', () => new NodeFilesystem('./dist/assets'));
+Implement the `FileSystemBackend` interface to create custom storage backends:
 
-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();
+```typescript
+import {type FileSystemBackend, ShovelDirectoryHandle} from "@b9g/filesystem";
+
+class MyBackend implements FileSystemBackend {
+  async stat(path: string) { /* ... */ }
+  async readFile(path: string) { /* ... */ }
+  async writeFile(path: string, data: Uint8Array) { /* ... */ }
+  async listDir(path: string) { /* ... */ }
+  async createDir?(path: string) { /* ... */ }
+  async remove?(path: string, recursive?: boolean) { /* ... */ }
 }
-```
 
-### 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');
-});
+const dir = new ShovelDirectoryHandle(new MyBackend(), "/");
 ```
 
 ## Exports
 
-### Classes
+### Main (`@b9g/filesystem`)
 
-- `ShovelFileHandle` - FileSystemFileHandle implementation
-- `ShovelDirectoryHandle` - FileSystemDirectoryHandle implementation
-- `ShovelHandle` - Base handle class
-- `CustomDirectoryStorage` - Directory storage with custom backend factories
+- `ShovelHandle` - Abstract base handle class
+- `ShovelFileHandle` - `FileSystemFileHandle` implementation
+- `ShovelDirectoryHandle` - `FileSystemDirectoryHandle` implementation
+- `CustomDirectoryStorage` - Named directory registry
 
 ### Types
 
-- `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
+- `FileSystemBackend` - Backend interface for custom implementations
+- `FileSystemConfig` - Configuration interface
+- `FileSystemPermissionDescriptor` - Permission descriptor
+- `DirectoryStorage` - Directory storage interface (`open`, `has`, `delete`, `keys`)
+- `DirectoryFactory` - Factory function type `(name: string) => FileSystemDirectoryHandle`
 
-## API Reference
+### `@b9g/filesystem/node-fs`
 
-### DirectoryStorage
+- `NodeFSDirectory` - Local filesystem directory (Node.js/Bun)
+- `NodeFSBackend` - Local filesystem backend
 
-```typescript
-interface DirectoryStorage {
-  open(name: string): Promise<FileSystemDirectoryHandle>;
-}
+### `@b9g/filesystem/memory`
 
-class CustomDirectoryStorage implements DirectoryStorage {
-  register(name: string, factory: DirectoryFactory): void;
-  open(name: string): Promise<FileSystemDirectoryHandle>;
-}
-```
+- `MemoryDirectory` - In-memory directory
+- `MemoryFileSystemBackend` - In-memory backend
 
-### FileSystemHandle Interface
+### `@b9g/filesystem/bun-s3`
 
-```typescript
-interface FileSystemDirectoryHandle {
-  kind: 'directory';
-  name: string;
-  getDirectoryHandle(name: string, options?: { create?: boolean }): Promise<FileSystemDirectoryHandle>;
-  getFileHandle(name: string, options?: { create?: boolean }): Promise<FileSystemFileHandle>;
-  removeEntry(name: string, options?: { recursive?: boolean }): Promise<void>;
-  entries(): AsyncIterableIterator<[string, FileSystemDirectoryHandle | FileSystemFileHandle]>;
-  keys(): AsyncIterableIterator<string>;
-  values(): AsyncIterableIterator<FileSystemDirectoryHandle | FileSystemFileHandle>;
-}
-
-interface FileSystemFileHandle {
-  kind: 'file';
-  name: string;
-  getFile(): Promise<File>;
-  createWritable(): Promise<FileSystemWritableFileStream>;
-}
-```
-
-## 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);
-```
+- `S3Directory` - S3-compatible storage directory
+- `S3FileSystemBackend` - S3 storage backend
 
 ## License
 
-MIT
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@b9g/filesystem",
-  "version": "0.1.11",
+  "version": "0.2.0",
   "description": "Universal File System Access API implementations for all platforms",
   "license": "MIT",
   "repository": {