opfs-worker 2.0.0 → 2.1.1

package/docs/types.md

@@ -1,38 +1,22 @@
 # Types
 
-This document contains all TypeScript types and interfaces provided by OPFS Worker.
-
-## Core Types
-
-### `FileStat`
-
-File or directory statistics.
+## `FileStat`
 
 ```typescript
 interface FileStat {
     kind: 'file' | 'directory';
     size: number;
-    mtime: string; // ISO string
-    ctime: string; // ISO string
+    mtime: string; // ISO
+    ctime: string; // ISO
     isFile: boolean;
     isDirectory: boolean;
-    hash?: string; // Hash of file content (only for files)
+    hash?: string; // files only, when hashing is enabled
 }
 ```
 
-**Properties:**
-
-- `kind`: Type of the file system entry
-- `size`: Size in bytes (0 for directories)
-- `mtime`: Last modification time as ISO string
-- `ctime`: Creation time as ISO string
-- `isFile`: True if this is a file
-- `isDirectory`: True if this is a directory
-- `hash`: Optional hash of file content (only present for files when hashing is enabled)
-
-### `DirentData`
+`size` is `0` for directories.
 
-Directory entry information.
+## `DirentData`
 
 ```typescript
 interface DirentData {
@@ -43,75 +27,90 @@ interface DirentData {
 }
 ```
 
-**Properties:**
+## `WatchOptions`
 
-- `name`: Name of the file or directory
-- `kind`: Type of the entry
-- `isFile`: True if this is a file
-- `isDirectory`: True if this is a directory
+```typescript
+interface WatchOptions {
+    recursive?: boolean; // default: true
+    include?: string | string[]; // minimatch, default: ['**']
+    exclude?: string | string[]; // minimatch, default: []
+}
+```
 
-### `WatchOptions`
+## `ImportFilesProgress`
 
-Options for file watching operations.
+Fired by `importFiles` / `onProgress` for each chunk written:
 
 ```typescript
-interface WatchOptions {
-    recursive?: boolean; // Whether to watch recursively (default: true)
-    include?: string | string[]; // Glob patterns to include in watching (minimatch syntax, default: ['**'])
-    exclude?: string | string[]; // Glob patterns to exclude from watching (minimatch syntax, default: [])
+interface ImportFilesProgress {
+    path: string;            // file currently being written
+    index: number;           // 0-based
+    count: number;           // total entries
+    bytesWritten: number;    // within current file
+    bytesTotal: number;      // size of current file
+    totalBytesWritten: number;
+    totalBytes: number;      // sum of all entry sizes
 }
 ```
 
-**Properties:**
+## `ImportFilesResult`
 
-- `recursive`: Whether to watch the entire directory tree (default: true)
-- `include`: Glob patterns to include in watching (default: all files)
-- `exclude`: Glob patterns to exclude from watching (default: none)
+Returned when `importFiles` finishes:
 
-### `RemoteOPFSWorker`
+```typescript
+interface ImportFilesResult {
+    paths: string[];      // written paths, in order
+    count: number;        // paths.length
+    bytesWritten: number; // total bytes across all files
+}
+```
+
+Entries accept `Iterable<[path, string | Uint8Array | Blob]>` or `Map<string, …>` — see [streaming](./guides/streaming.md).
+
+## `OPFSApi`
+
+Promise-based surface shared by all backends — a Comlink proxy to `OPFSSync`, or an in-process `OPFSAsync`. What `OPFSFacade` talks to (see `OPFSBackend` in [Create helpers](./api/create.md)).
+
+```typescript
+type OPFSApi = { [K in keyof OPFSSync]: OPFSSync[K] };
+```
 
-Remote file system interface type for Comlink communication.
+## `PathLike`
 
 ```typescript
-type RemoteOPFSWorker = Remote<OPFSWorker>;
+type PathLike = string | URL;
 ```
 
-This type represents the remote interface when using the worker with Comlink.
+## `FileOpenOptions`
 
-## Configuration Types
+```typescript
+interface FileOpenOptions {
+    create?: boolean;
+    exclusive?: boolean;
+    truncate?: boolean;
+}
+```
 
-### `OPFSOptions`
+## `OPFSOptions`
 
-Configuration options for creating an OPFS Worker instance.
+Table: [Create helpers → Options](./api/create.md#options).
 
 ```typescript
 interface OPFSOptions {
-    /** Root path for the file system (default: '/') */
+    /** Root path (default: '/') */
     root?: string;
-    /** Namespace for the events (default: 'opfs-worker:${root}') */
+    /** Event namespace (default: 'opfs-worker:${root}') */
     namespace?: string;
-    /** Hash algorithm for file hashing, or false/null to disable (default: 'etag') */
+    /** Hash algorithm, or false/null to disable (default: 'etag') */
     hashAlgorithm?: null | false | 'etag' | 'SHA-1' | 'SHA-256' | 'SHA-384' | 'SHA-512';
-    /** Maximum file size in bytes for SHA-* hashing (default: 50MB); ignored by 'etag' */
+    /** Max bytes for SHA-* hashing (default: 50MB); ignored by 'etag' */
     maxFileSize?: number;
-    /** Custom name for the broadcast channel (default: 'opfs-worker') */
+    /** Broadcast channel name or instance (default: 'opfs-worker') */
     broadcastChannel?: string | BroadcastChannel | null;
 }
 ```
 
-**Properties:**
-
-- `root`: Root path for the file system
-- `namespace`: Namespace for events and isolation
-- `hashAlgorithm`: `'etag'` (default, mtime+size), `'SHA-*'`, or `null`/`false` to disable
-- `maxFileSize`: Max bytes for SHA-* content hashing (etag ignores this)
-- `broadcastChannel`: Custom broadcast channel name or instance
-
-## Event Types
-
-### `WatchEventType`
-
-Enumeration of file system change event types.
+## `WatchEventType`
 
 ```typescript
 enum WatchEventType {
@@ -121,15 +120,7 @@ enum WatchEventType {
 }
 ```
 
-**Values:**
-
-- `Added`: File or directory was created
-- `Changed`: File or directory was modified
-- `Removed`: File or directory was deleted
-
-### `WatchEvent`
-
-File system change event sent via BroadcastChannel.
+## `WatchEvent`
 
 ```typescript
 interface WatchEvent {
@@ -142,91 +133,52 @@ interface WatchEvent {
 }
 ```
 
-**Properties:**
-
-- `namespace`: Event namespace for isolation
-- `path`: Path of the changed file/directory
-- `type`: Type of change (added, changed, removed)
-- `isDirectory`: Whether the changed item is a directory
-- `timestamp`: ISO timestamp of the change
-- `hash`: Optional hash of the file content (if hashing is enabled)
-
-## Utility Types
-
-### `Kind`
-
-File system entry type.
+## Utility types
 
 ```typescript
 type Kind = 'file' | 'directory';
-```
-
-### `Encoding`
-
-Supported text encodings.
-
-```typescript
 type Encoding = 'utf-8' | 'utf-16le' | 'ascii' | 'latin1' | 'base64' | 'hex' | 'binary';
 ```
 
-## Error Types
-
-The library provides comprehensive error handling with specific error types that are Node.js SystemError compatible:
-
-### Base Error Class
-
-- `OPFSError` - Base error class for all OPFS-related errors (Node.js SystemError compatible)
-
-**Properties:**
-
-- `errno: number` - Numeric error code (e.g., -2 for ENOENT)
-- `syscall?: string` - System call name (e.g., 'open', 'read', 'write')
-- `path?: string` - File path when applicable
-- `name: string` - Error class name ('OPFSError')
-- `message: string` - Human-readable error message
-- `cause?: any` - Underlying error (Node.js 16+ feature)
-
-### Specialized Error Classes
-
-- `OPFSNotSupportedError` - Thrown when OPFS is not supported in the browser
-- `PathError` - Thrown for invalid paths or path traversal attempts
-- `ExistenceError` - Thrown when files or directories don't exist
-  - Usage: `new ExistenceError('File not found: /path/to/file', 'ENOENT', '/path/to/file')`
-- `PermissionError` - Thrown when permission is denied for an operation
-- `StorageError` - Thrown when an operation fails due to insufficient storage
-- `TimeoutError` - Thrown when an operation times out
-- `FileBusyError` - Thrown when a file is busy (locked by another operation)
-- `FileTypeError` - Thrown when file/directory type expectations don't match
-  - Usage: `new FileTypeError('directory', '/path/to/dir')`
-- `ValidationError` - Thrown for validation failures (invalid arguments, formats, etc.)
-  - Usage: `new ValidationError('Invalid size', 'EINVAL', '/path/to/file')`
-- `OperationAbortedError` - Thrown when an operation is aborted
-- `IOError` - Thrown for I/O operation failures
-- `OperationNotSupportedError` - Thrown when an operation is not supported
-- `DirectoryOperationError` - Thrown when directory operations fail
-  - Usage: `new DirectoryOperationError('RM_FAILED', '/path/to/dir')`
-- `InitializationFailedError` - Thrown when OPFS initialization fails
-- `FileSystemOperationError` - Thrown when file system operations fail
-- `PathResolutionFailedError` - Thrown when path resolution fails
-- `AlreadyExistsError` - Thrown when a file or directory already exists
-
-### Error Code Mapping
-
-The library uses standard POSIX error codes with numeric errno mapping:
-
-- `ENOENT` (-2) - No such file or directory
-- `EISDIR` (-21) - Is a directory
-- `ENOTDIR` (-20) - Not a directory
-- `EACCES` (-13) - Permission denied
-- `EEXIST` (-17) - File exists
-- `ENOTEMPTY` (-39) - Directory not empty
-- `EINVAL` (-22) - Invalid argument
-- `EIO` (-5) - I/O error
-- `ENOSPC` (-28) - No space left on device
-- `EBUSY` (-16) - Device or resource busy
-- `EINTR` (-4) - Interrupted system call
-- `ENOTSUP` (-95) - Operation not supported
-- `ERANGE` (-34) - Result too large
-- `EBADF` (-9) - Bad file descriptor
-
-Each error type extends the base `OPFSError` class and provides specific error codes and context information for better debugging.
+## Errors
+
+Node.js SystemError-compatible. Base class: `OPFSError` (`errno`, `syscall?`, `path?`, `cause?`).
+
+| Class                        |                                                                     |
+| ---------------------------- | ------------------------------------------------------------------- |
+| `OPFSNotSupportedError`      | OPFS missing in the browser                                         |
+| `PathError`                  | Bad path / traversal                                                |
+| `ExistenceError`             | Missing entry — `new ExistenceError(msg, 'ENOENT', path)`           |
+| `PermissionError`            | Access denied                                                       |
+| `StorageError`               | Quota / storage full                                                |
+| `TimeoutError`               | Timed out                                                           |
+| `FileBusyError`              | Locked / busy                                                       |
+| `FileTypeError`              | File vs directory mismatch — `new FileTypeError('directory', path)` |
+| `ValidationError`            | Bad args — `new ValidationError(msg, 'EINVAL', path)`               |
+| `OperationAbortedError`      | Aborted                                                             |
+| `IOError`                    | I/O failure                                                         |
+| `OperationNotSupportedError` | Not supported (e.g. FDs on async)                                   |
+| `DirectoryOperationError`    | Dir op failed — `new DirectoryOperationError('RM_FAILED', path)`    |
+| `InitializationFailedError`  | Init failed                                                         |
+| `FileSystemOperationError`   | Generic FS failure                                                  |
+| `PathResolutionFailedError`  | Path resolve failed                                                 |
+| `AlreadyExistsError`         | Already exists                                                      |
+
+### errno
+
+| Code        | errno |                           |
+| ----------- | ----- | ------------------------- |
+| `ENOENT`    | -2    | No such file or directory |
+| `EISDIR`    | -21   | Is a directory            |
+| `ENOTDIR`   | -20   | Not a directory           |
+| `EACCES`    | -13   | Permission denied         |
+| `EEXIST`    | -17   | File exists               |
+| `ENOTEMPTY` | -39   | Directory not empty       |
+| `EINVAL`    | -22   | Invalid argument          |
+| `EIO`       | -5    | I/O error                 |
+| `ENOSPC`    | -28   | No space left             |
+| `EBUSY`     | -16   | Busy                      |
+| `EINTR`     | -4    | Interrupted               |
+| `ENOTSUP`   | -95   | Not supported             |
+| `ERANGE`    | -34   | Result too large          |
+| `EBADF`     | -9    | Bad file descriptor       |

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "opfs-worker",
-    "version": "2.0.0",
+    "version": "2.1.1",
     "description": "A robust TypeScript library for working with Origin Private File System (OPFS) through Web Workers",
     "type": "module",
     "main": "dist/index.js",
@@ -18,7 +18,27 @@
             "source": "./src/index.pure.ts",
             "import": "./dist/index.pure.js",
             "require": "./dist/index.pure.cjs"
-        }
+        },
+        "./sync": {
+            "types": "./dist/index.sync.d.ts",
+            "source": "./src/index.sync.ts",
+            "import": "./dist/index.sync.js",
+            "require": "./dist/index.sync.cjs"
+        },
+        "./async": {
+            "types": "./dist/index.async.d.ts",
+            "source": "./src/index.async.ts",
+            "import": "./dist/index.async.js",
+            "require": "./dist/index.async.cjs"
+        },
+        "./sharedworker": {
+            "types": "./dist/index.sharedworker.d.ts",
+            "source": "./src/index.sharedworker.ts",
+            "import": "./dist/index.sharedworker.js",
+            "require": "./dist/index.sharedworker.cjs"
+        },
+        "./dedicated.worker.js": "./dist/dedicated.worker.js",
+        "./shared.worker.js": "./dist/shared.worker.js"
     },
     "sideEffects": false,
     "files": [
@@ -29,9 +49,15 @@
         "LICENSE"
     ],
     "scripts": {
-        "build": "vite build && tsc -p tsconfig.build.json",
+        "build": "bun run build:lib && bun run build:workers && bun run build:types",
+        "build:lib": "vite build",
+        "build:workers": "bun run build:worker:dedicated && bun run build:worker:shared",
+        "build:worker:dedicated": "OPFS_WORKER=dedicated.worker vite build -c vite.worker.config.ts",
+        "build:worker:shared": "OPFS_WORKER=shared.worker vite build -c vite.worker.config.ts",
+        "build:types": "tsc -p tsconfig.build.json",
         "build:demo": "vite build demo --base=./",
         "dev": "concurrently \"vite build --watch --mode development\" \"tsc -p tsconfig.build.json --watch\"",
+        "dev:demo": "vite demo",
         "preview": "vite preview demo",
         "type-check": "tsc --noEmit",
         "lint": "eslint src --ext .ts,.tsx --fix --max-warnings=9999 --quiet",
@@ -40,7 +66,7 @@
         "prepublishOnly": "bun run lint && bun run type-check && bun run build",
         "changelog": "changeset",
         "version-packages": "changeset version",
-        "release": "changeset publish"
+        "release": "bun run scripts/release.mjs"
     },
     "keywords": [
         "opfs",
@@ -63,18 +89,40 @@
     "homepage": "https://github.com/kachurun/opfs-worker#readme",
     "devDependencies": {
         "@changesets/cli": "^2.29.5",
+        "@codemirror/lang-cpp": "6.0.3",
+        "@codemirror/lang-css": "6.3.1",
+        "@codemirror/lang-go": "6.0.1",
+        "@codemirror/lang-html": "6.4.11",
+        "@codemirror/lang-java": "6.0.2",
+        "@codemirror/lang-javascript": "6.2.5",
+        "@codemirror/lang-json": "6.0.2",
+        "@codemirror/lang-markdown": "6.5.1",
+        "@codemirror/lang-php": "6.0.2",
+        "@codemirror/lang-python": "6.2.1",
+        "@codemirror/lang-rust": "6.0.2",
+        "@codemirror/lang-sql": "6.10.0",
+        "@codemirror/lang-xml": "6.1.0",
+        "@codemirror/lang-yaml": "6.1.3",
+        "@codemirror/legacy-modes": "6.5.3",
+        "@codemirror/theme-one-dark": "6.1.3",
         "@flexbe/eslint-config": "^1.0.11",
+        "@tailwindcss/vite": "4.3.3",
         "@types/minimatch": "^6.0.0",
         "@types/node": "^24.2.0",
         "@types/react": "^19.1.9",
         "@types/react-dom": "^19.1.7",
         "@typescript-eslint/eslint-plugin": "^8.39.0",
         "@typescript-eslint/parser": "^8.39.0",
+        "@uiw/react-codemirror": "4.25.11",
         "@vitest/coverage-v8": "^3.2.4",
+        "daisyui": "5.7.4",
         "eslint": "^9.32.0",
         "happy-dom": "^18.0.1",
+        "lucide-react": "1.26.0",
         "react": "^19.1.1",
         "react-dom": "^19.1.1",
+        "react-icons": "5.7.0",
+        "tailwindcss": "4.3.3",
         "typescript": "^5.9.2",
         "vite": "^7.0.6",
         "vitest": "^3.2.4"
@@ -88,6 +136,7 @@
     "packageManager": "bun@1.2.19",
     "dependencies": {
         "comlink": "^4.4.2",
+        "fflate": "0.8.3",
         "minimatch": "^10.0.3"
     },
     "publishConfig": {