opfs-worker 2.1.0 → 2.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "opfs-worker",
-    "version": "2.1.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",
@@ -66,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",
@@ -89,12 +89,21 @@
     "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",
@@ -127,6 +136,7 @@
     "packageManager": "bun@1.2.19",
     "dependencies": {
         "comlink": "^4.4.2",
+        "fflate": "0.8.3",
         "minimatch": "^10.0.3"
     },
     "publishConfig": {

package/src/core/BaseOPFS.ts

@@ -16,7 +16,6 @@ import {
     basename,
     calculateFileHash,
     checkOPFSSupport,
-    convertBlobToUint8Array,
     dirname,
     joinPath,
     matchMinimatch,
@@ -27,7 +26,19 @@ import {
     splitPath
 } from '../utils/helpers';
 
-import type { DirentData, FileStat, OPFSOptions, RenameOptions, WatchEvent, WatchOptions, WatchSnapshot } from '../types';
+import type {
+    DirentData,
+    FileStat,
+    ImportFileData,
+    ImportFilesEntries,
+    ImportFilesProgress,
+    ImportFilesResult,
+    OPFSOptions,
+    RenameOptions,
+    WatchEvent,
+    WatchOptions,
+    WatchSnapshot,
+} from '../types';
 
 
 /**
@@ -891,42 +902,105 @@ export abstract class BaseOPFS {
     }
 
     /**
-     * Bulk-create files from `[path, data]` entries (strings, bytes, or Blobs).
+     * Read a file as a `Blob` without copying its bytes into memory.
      *
-     * @param entries - Array of `[path, data]` tuples
-     * @throws {OPFSError} If a write fails
+     * OPFS hands back a disk-backed `File`, so the browser can stream it on
+     * demand — pass it to `URL.createObjectURL()` for `<video>` / `<audio>` /
+     * `<img>` and only the played range is actually read. Structured clone keeps
+     * the reference intact when the file system runs in a worker.
+     *
+     * @param path - Path to the file
+     * @returns Lazy `File` handle backed by OPFS storage
+     * @throws {OPFSError} If the path is missing or is a directory
      *
      * @example
      * ```typescript
-     * await fs.createIndex([
-     *   ['/config.json', JSON.stringify({ theme: 'dark' })],
-     *   ['/data/binary.dat', new Uint8Array([1, 2, 3, 4])],
-     *   ['/upload.txt', new Blob(['file content'], { type: 'text/plain' })],
-     * ]);
+     * const blob = await fs.readBlob('/media/clip.mp4');
+     * video.src = URL.createObjectURL(blob);
      * ```
      */
-    async createIndex(entries: [string, string | Uint8Array | Blob][]): Promise<void> {
+    async readBlob(path: string): Promise<Blob> {
         await this.mount();
 
         try {
-            for (const [path, data] of entries) {
-                const normalizedPath = normalizePath(path);
+            const fileHandle = await this.getFileHandle(path, false);
 
-                let fileData: Uint8Array;
+            return await fileHandle.getFile();
+        }
+        catch (error: any) {
+            if (error instanceof OPFSError) {
+                throw error;
+            }
 
-                if (data instanceof Blob) {
-                    fileData = await convertBlobToUint8Array(data);
-                }
-                else if (typeof data === 'string') {
-                    // Convert string to Uint8Array using UTF-8 encoding
-                    fileData = new TextEncoder().encode(data);
-                }
-                else {
-                    fileData = data;
-                }
+            throw mapDomError(error, { path, isDirectory: error?.name === 'TypeMismatchError' });
+        }
+    }
+
+    /**
+     * Bulk-import files from `[path, data]` entries (strings, bytes, Blobs, or Files).
+     * Each entry is written via {@link writeStream} so large Blobs/Files are not
+     * fully buffered in memory.
+     *
+     * Accepts an array of tuples, a `Map`, or any iterable of `[path, data]` pairs.
+     *
+     * @param entries - Files to write
+     * @param onProgress - Per-chunk progress with path, index, and byte counts
+     * @returns Written paths, count, and total bytes
+     * @throws {OPFSError} If a write fails
+     *
+     * @example
+     * ```typescript
+     * const result = await fs.importFiles([
+     *   ['/config.json', JSON.stringify({ theme: 'dark' })],
+     *   ['/data/binary.dat', new Uint8Array([1, 2, 3, 4])],
+     *   ['/upload.txt', fileFromInput],
+     * ], (p) => console.log(`${p.path}: ${p.bytesWritten}/${p.bytesTotal}`));
+     *
+     * console.log(result.count, result.bytesWritten, result.paths);
+     * ```
+     */
+    async importFiles(
+        entries: ImportFilesEntries,
+        onProgress?: (progress: ImportFilesProgress) => unknown
+    ): Promise<ImportFilesResult> {
+        await this.mount();
+
+        const list = [...entries].map(([path, data]) => [normalizePath(path), data] as [string, ImportFileData]);
+        const count = list.length;
+        const paths = list.map(([path]) => path);
+        const totalBytes = list.reduce((sum, [, data]) => sum + importEntryByteLength(data), 0);
+        let totalBytesWritten = 0;
 
-                await this.writeFile(normalizedPath, fileData);
+        try {
+            for (let index = 0; index < count; index++) {
+                const [path, data] = list[index]!;
+                const { stream, size: bytesTotal } = toImportStream(data);
+                const base = totalBytesWritten;
+
+                const written = await this.writeStream(
+                    path,
+                    stream,
+                    onProgress
+                        ? bytesWritten => onProgress({
+                            path,
+                            index,
+                            count,
+                            bytesWritten,
+                            bytesTotal,
+                            totalBytesWritten: base + bytesWritten,
+                            totalBytes,
+                        })
+                        : undefined
+                );
+
+                totalBytesWritten += written;
             }
+
+            return {
+                paths,
+                count,
+                bytesWritten: totalBytesWritten,
+            };
         }
         catch (error) {
             if (error instanceof OPFSError) {
@@ -937,6 +1011,14 @@ export abstract class BaseOPFS {
         }
     }
 
+    /**
+     * @deprecated Use {@link importFiles} instead.
+     */
+    async createIndex(entries: ImportFilesEntries): Promise<void> {
+        warnCreateIndexDeprecated();
+        await this.importFiles(entries);
+    }
+
     /**
      * Dispose of resources and clean up the file system instance
      */
@@ -949,3 +1031,44 @@ export abstract class BaseOPFS {
         this.watchers.clear();
     }
 }
+
+function importEntryByteLength(data: ImportFileData): number {
+    if (typeof data === 'string') {
+        return new TextEncoder().encode(data).byteLength;
+    }
+
+    if (data instanceof Blob) {
+        return data.size;
+    }
+
+    return data.byteLength;
+}
+
+function toImportStream(data: ImportFileData): { stream: ReadableStream<Uint8Array>; size: number } {
+    if (data instanceof Blob) {
+        return { stream: data.stream(), size: data.size };
+    }
+
+    const bytes = typeof data === 'string' ? new TextEncoder().encode(data) : data;
+
+    return {
+        size: bytes.byteLength,
+        stream: new ReadableStream({
+            start(controller) {
+                controller.enqueue(bytes);
+                controller.close();
+            },
+        }),
+    };
+}
+
+let createIndexWarned = false;
+
+function warnCreateIndexDeprecated(): void {
+    if (createIndexWarned) {
+        return;
+    }
+
+    createIndexWarned = true;
+    console.warn('[opfs-worker] createIndex() is deprecated; use importFiles() instead');
+}

package/src/facade/OPFSFacade.ts

@@ -8,6 +8,9 @@ import type {
     Encoding,
     FileOpenOptions,
     FileStat,
+    ImportFileData,
+    ImportFilesProgress,
+    ImportFilesResult,
     OPFSApi,
     OPFSOptions,
     PathLike,
@@ -28,6 +31,17 @@ function normalizePath(path: PathLike): string {
     return path;
 }
 
+let createIndexWarned = false;
+
+function warnCreateIndexDeprecated(): void {
+    if (createIndexWarned) {
+        return;
+    }
+
+    createIndexWarned = true;
+    console.warn('[opfs-worker] createIndex() is deprecated; use importFiles() instead');
+}
+
 /** Backend the facade talks to: an fs implementation plus its cleanup. */
 export interface OPFSBackend {
     fs: OPFSApi;
@@ -442,12 +456,45 @@ export class OPFSFacade {
     }
 
     /**
-     * Synchronize the file system with external data
+     * Read a file as a lazy, disk-backed `Blob` without copying the data to memory.
+     *
+     * Ideal for `URL.createObjectURL()`: the browser streams `<video>` / `<audio>`
+     * on demand instead of loading the whole file first.
      */
-    async createIndex(entries: [PathLike, string | Uint8Array | Blob][]): Promise<void> {
-        const normalizedEntries = entries.map(([path, data]) => [normalizePath(path), data] as [string, string | Uint8Array | Blob]);
+    async readBlob(path: PathLike): Promise<Blob> {
+        return this.#fs.readBlob(normalizePath(path));
+    }
 
-        return this.#fs.createIndex(normalizedEntries);
+    /**
+     * Bulk-import files from `[path, data]` entries (strings, bytes, Blobs, or Files).
+     * Each entry is streamed via {@link importStream} / `writeStream` so large
+     * Blobs/Files are not fully buffered in memory.
+     *
+     * Accepts an array of tuples, a `Map`, or any iterable of `[path, data]` pairs.
+     * Returns written paths, count, and total bytes.
+     */
+    async importFiles(
+        entries: Iterable<[PathLike, ImportFileData]> | Map<string, ImportFileData>,
+        options?: { onProgress?: (progress: ImportFilesProgress) => void }
+    ): Promise<ImportFilesResult> {
+        const normalizedEntries = [...entries].map(([path, data]) => [
+            normalizePath(path),
+            data,
+        ] as [string, ImportFileData]);
+
+        const onProgress = options?.onProgress
+            ? proxy((progress: ImportFilesProgress) => options.onProgress!(progress))
+            : undefined;
+
+        return this.#fs.importFiles(normalizedEntries, onProgress);
+    }
+
+    /**
+     * @deprecated Use {@link importFiles} instead.
+     */
+    async createIndex(entries: Iterable<[PathLike, ImportFileData]> | Map<string, ImportFileData>): Promise<void> {
+        warnCreateIndexDeprecated();
+        await this.importFiles(entries);
     }
 
     /**

package/src/types.ts

@@ -76,6 +76,43 @@ export interface OPFSOptions {
     broadcastChannel?: string | BroadcastChannel | null;
 }
 
+/** Payload accepted by {@link importFiles} for a single entry. */
+export type ImportFileData = string | Uint8Array | Blob;
+
+/**
+ * Entries for {@link importFiles}: an array of `[path, data]` tuples, a `Map`,
+ * or any iterable that yields the same pairs.
+ */
+export type ImportFilesEntries = Iterable<[string, ImportFileData]> | Map<string, ImportFileData>;
+
+/** Progress event fired while {@link importFiles} writes entries. */
+export interface ImportFilesProgress {
+    /** Path of the file currently being written */
+    path: string;
+    /** 0-based index of the current file */
+    index: number;
+    /** Total number of entries in this import */
+    count: number;
+    /** Bytes written for the current file so far */
+    bytesWritten: number;
+    /** Size of the current file in bytes */
+    bytesTotal: number;
+    /** Bytes written across all files so far */
+    totalBytesWritten: number;
+    /** Sum of all entry sizes in bytes */
+    totalBytes: number;
+}
+
+/** Result of a finished {@link importFiles} call. */
+export interface ImportFilesResult {
+    /** Paths written, in import order */
+    paths: string[];
+    /** Number of files imported (`paths.length`) */
+    count: number;
+    /** Total bytes written across all files */
+    bytesWritten: number;
+}
+
 export interface RenameOptions {
     /** Whether to overwrite existing files (default: false) */
     overwrite?: boolean;