libfw-client 0.1.1 → 0.1.2

package/index.d.ts

@@ -94,6 +94,16 @@ export declare class LibfwClient {
    */
   downloadFolder(token: string, dirPath?: string): Promise<number>;
 
+  /**
+   * Download a single file from the server at `filePath` into a user-selected
+   * local directory.
+   *
+   * @param token bearer token
+   * @param filePath virtual server path of the file to download
+   * @returns total bytes written
+   */
+  downloadFile(token: string, filePath: string): Promise<number>;
+
   /**
    * Upload files to the server.
    *

package/index.js

@@ -158,7 +158,7 @@ export class LibfwClient {
     this._dirHandle = null;
     /** @type {Map<string, FileSystemFileHandle>} path → file handle */
     this._fileHandles = new Map();
-    /** @type {Map<string, FileSystemWritableFileStream>} path → writable stream */
+    /** @type {Map<string, FileSystemWritableFileStream>} path → open writable stream */
     this._writables = new Map();
     /** @type {Map<string, File>} path → File (upload) */
     this._uploadFiles = new Map();
@@ -205,7 +205,7 @@ export class LibfwClient {
     return {
       onFileStart: (path, size) => this._emit({ type: 'fileStart', path, done: 0, total: size }),
       onWriteChunk: (path, offset, data) => this._onWriteChunk(path, offset, data),
-      onFileCompleted: (path) => this._emit({ type: 'fileCompleted', path }),
+      onFileCompleted: (path) => this._onFileCompleted(path),
       onProgress: (done, total) => this._emit({ type: 'progress', done, total }),
       loadState: (direction, path) => Idb.loadState(`${direction}:${path}`),
       saveState: (direction, path, state) => Idb.saveState(`${direction}:${path}`, state),
@@ -259,6 +259,36 @@ export class LibfwClient {
   }
 
   /**
+   * Download a single file from the server at `filePath` into a local
+   * directory chosen via `showDirectoryPicker()`.
+   *
+   * @param {string} token bearer token
+   * @param {string} filePath virtual server path of the file to download
+   * @returns {Promise<number>} total bytes written
+   * @throws {LibfwError}
+   */
+  async downloadFile(token, filePath) {
+    const engine = await this._ready();
+    if (typeof window === 'undefined' || typeof window.showDirectoryPicker !== 'function') {
+      throw new LibfwError('File System Access API is not available in this browser', 'unsupported');
+    }
+    if (!filePath) throw new LibfwError('downloadFile requires a file path', 'path');
+    this._dirHandle = await window.showDirectoryPicker();
+    this._fileHandles.clear();
+    try {
+      return await engine.download_file(this._options.baseUrl, token, filePath);
+    } catch (err) {
+      throw toLibfwError(err);
+    } finally {
+      await this._flushWritables();
+    }
+  }
+
+  /**
+   * Stream a decompressed chunk straight to disk at its absolute byte
+   * offset, keeping memory bounded regardless of file size (no whole-file
+   * buffering). The engine awaits this callback, so writes for a file are
+   * applied strictly in order.
    * @param {string} path virtual path
    * @param {number} offset byte offset
    * @param {Uint8Array} data decompressed chunk
@@ -268,15 +298,13 @@ export class LibfwClient {
   async _onWriteChunk(path, offset, data) {
     let writable = this._writables.get(path);
     if (!writable) {
+      // Open the destination once per file. A true resume (first chunk at
+      // offset > 0) keeps the existing prefix on disk; a fresh download opens
+      // a truncating writable. Always close the writable on completion/abort
+      // so no orphaned `.crswap` swap files are left behind.
+      const isResume = offset > 0;
       const handle = await this._ensureFileHandle(path);
       this._fileHandles.set(path, handle);
-      // Only a true resume (first chunk arrives at offset > 0) needs to
-      // keep the existing file's prefix. For a fresh download we open the
-      // writable WITHOUT keepExistingData, which truncates and lets us
-      // write sequentially. In real Chromium the keepExistingData +
-      // position-write path can leave empty target files behind a trail of
-      // orphaned `.crswap` swap files, so we avoid it unless required.
-      const isResume = offset > 0;
       writable = await handle.createWritable(
         isResume ? { keepExistingData: true } : undefined
       );
@@ -285,6 +313,35 @@ export class LibfwClient {
     await writable.write({ type: 'write', position: offset, data });
   }
 
+  /**
+   * Close the destination writable once a file's transfer completes.
+   * @param {string} path virtual path
+   * @returns {Promise<void>}
+   * @private
+   */
+  async _onFileCompleted(path) {
+    await this._closeWritable(path);
+    this._emit({ type: 'fileCompleted', path });
+  }
+
+  /**
+   * Close (and forget) a file's writable, flushing buffered bytes to disk.
+   * @param {string} path virtual path
+   * @returns {Promise<void>}
+   * @private
+   */
+  async _closeWritable(path) {
+    const writable = this._writables.get(path);
+    if (writable) {
+      this._writables.delete(path);
+      try {
+        await writable.close();
+      } catch {
+        /* best-effort flush on failure/abort */
+      }
+    }
+  }
+
   /**
    * Resolve (and create, if needed) the file handle for a virtual path,
    * creating any parent directories along the way.
@@ -305,13 +362,20 @@ export class LibfwClient {
   }
 
   /**
-   * Close all open writable streams (flush to disk).
+   * Close all still-open writable streams (flush to disk). Called on
+   * success, failure or cancellation of a transfer.
    * @returns {Promise<void>}
    * @private
    */
   async _flushWritables() {
-    const pending = [...this._writables.values()].map((w) => w.close().catch(() => {}));
-    this._writables.clear();
+    const pending = [...this._writables.entries()].map(async ([path, writable]) => {
+      this._writables.delete(path);
+      try {
+        await writable.close();
+      } catch {
+        /* best-effort flush */
+      }
+    });
     await Promise.allSettled(pending);
   }
 

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "libfw-client",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "High-performance streaming file & folder transfer SDK for the browser (libfw WASM engine + File System Access API + IndexedDB resume).",
-  "license": "MIT OR Apache-2.0",
+  "license": "MIT",
   "type": "module",
   "main": "index.js",
   "module": "index.js",

package/pkg/libfw_client.d.ts

@@ -15,6 +15,12 @@ export class LibfwClient {
      * Bytes transferred so far.
      */
     done_bytes(): number;
+    /**
+     * Download a single file at `file_path` into the chosen local directory.
+     *
+     * Resolves with the number of bytes written.
+     */
+    download_file(base_url: string, token: string, file_path: string): Promise<any>;
     /**
      * Download every file under the virtual `dirPath` (empty = root).
      *
@@ -77,6 +83,7 @@ export interface InitOutput {
     readonly js_option_string: (a: any, b: number, c: number) => [number, number];
     readonly libfwclient_cancel: (a: number) => void;
     readonly libfwclient_done_bytes: (a: number) => number;
+    readonly libfwclient_download_file: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => any;
     readonly libfwclient_download_folder: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => any;
     readonly libfwclient_has_callbacks: (a: number) => number;
     readonly libfwclient_new: (a: any) => number;

package/pkg/libfw_client.js

@@ -28,6 +28,25 @@ export class LibfwClient {
         const ret = wasm.libfwclient_done_bytes(this.__wbg_ptr);
         return ret;
     }
+    /**
+     * Download a single file at `file_path` into the chosen local directory.
+     *
+     * Resolves with the number of bytes written.
+     * @param {string} base_url
+     * @param {string} token
+     * @param {string} file_path
+     * @returns {Promise<any>}
+     */
+    download_file(base_url, token, file_path) {
+        const ptr0 = passStringToWasm0(base_url, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ptr1 = passStringToWasm0(token, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len1 = WASM_VECTOR_LEN;
+        const ptr2 = passStringToWasm0(file_path, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len2 = WASM_VECTOR_LEN;
+        const ret = wasm.libfwclient_download_file(this.__wbg_ptr, ptr0, len0, ptr1, len1, ptr2, len2);
+        return ret;
+    }
     /**
      * Download every file under the virtual `dirPath` (empty = root).
      *
@@ -431,7 +450,7 @@ function __wbg_get_imports() {
             return ret;
         },
         __wbindgen_cast_0000000000000001: function(arg0, arg1) {
-            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [Externref], shim_idx: 128, ret: Result(Unit), inner_ret: Some(Result(Unit)) }, mutable: true }) -> Externref`.
+            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [Externref], shim_idx: 133, ret: Result(Unit), inner_ret: Some(Result(Unit)) }, mutable: true }) -> Externref`.
             const ret = makeMutClosure(arg0, arg1, wasm_bindgen_1e05ddb24c0b7df4___convert__closures_____invoke___wasm_bindgen_1e05ddb24c0b7df4___JsValue__core_9b3796e30d99ddb7___result__Result_____wasm_bindgen_1e05ddb24c0b7df4___JsError___true_);
             return ret;
         },

package/pkg/libfw_client_bg.wasm.d.ts

@@ -5,6 +5,7 @@ export const __wbg_libfwclient_free: (a: number, b: number) => void;
 export const js_option_string: (a: any, b: number, c: number) => [number, number];
 export const libfwclient_cancel: (a: number) => void;
 export const libfwclient_done_bytes: (a: number) => number;
+export const libfwclient_download_file: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => any;
 export const libfwclient_download_folder: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => any;
 export const libfwclient_has_callbacks: (a: number) => number;
 export const libfwclient_new: (a: any) => number;

package/pkg/package.json

@@ -2,7 +2,7 @@
   "name": "libfw-client",
   "type": "module",
   "description": "WASM engine + JS SDK for libfw browser clients",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "license": "MIT",
   "repository": {
     "type": "git",