libfw-client 0.1.3 → 0.1.4

package/README.md

@@ -11,6 +11,11 @@ import { LibfwClient } from 'libfw-client';
 const client = new LibfwClient({
   baseUrl: '/api',      // where libfw-server routes are mounted
   concurrency: 4,       // max parallel file transfers
+  uploadWindow: 8,      // in-flight chunks per single file upload (raise to
+                        // reduce upload stutter on high-latency links)
+  downloadWindow: 4,    // in-flight byte-range GETs per single file download
+                        // (tus-style parallel download: one file's throughput
+                        // isn't bounded by a single connection's RTT)
   compress: true,       // zrip streaming compression
   onEvent: (e) => console.log(e), // { type: 'progress', done, total }
 });
@@ -38,14 +43,25 @@ client.cancel();
 - `downloadFolder(token, dirPath?)` / `downloadFile(token, filePath)` — the
   engine lists (for folders) and downloads each file with `Range`/`If-Range`
   resume, decompresses the zrip stream, and pushes `Uint8Array` chunks to the
-  SDK. With the File System Access API the SDK streams them to disk via
-  `fileHandle.createWritable()`; without it (or with `downloadMode: 'browser'`)
-  the SDK buffers the chunks and saves the result through a traditional
-  browser download — a single file as-is, a folder packed into a `.zip`.
+  SDK. Large files use the **tus-style parallel path**: `downloadWindow`
+  concurrent byte-range GETs, reordered in memory so the SDK still receives
+  bytes strictly in order (append-mode `createWritable()`, no `.crswap`
+  churn), with per-chunk independent retries. With the File System Access API
+  the SDK streams them to disk via `fileHandle.createWritable()`; without it
+  (or with `downloadMode: 'browser'`) the SDK buffers the chunks and saves the
+  result through a traditional browser download — a single file as-is, a
+  folder packed into a `.zip`.
 - `upload(token, files?)` — the engine slices each file into fixed-size
   chunks, reads them via `readFile`, compresses each chunk into one zstd
-  frame, and POSTs them with `x-libfw-offset` for server-side resume
-  validation.
+  frame, and POSTs them with an absolute `x-libfw-offset` into a shared
+  per-session temp file. Up to `uploadWindow` chunks of one file are kept in
+  flight concurrently (independent of the cross-file `concurrency`), so a
+  high-latency link stays saturated. Uploads are **tus-style
+  verify-then-complete**: the server is the source of truth — the client
+  probes the byte ranges the server actually persisted and re-sends only the
+  still-missing blocks, filling gaps a lost response may have left (and
+  re-probing + refilling if a commit fails) before the final `x-libfw-final`
+  request merges the temp into place.
 - Resume state (`etag`, `offset`, `size`) is persisted per path in
   IndexedDB and re-validated on every retry.
 - Pause/resume/cancel drive the WASM state machine
@@ -74,6 +90,12 @@ dist/libfw-client.umd.js   UMD bundle (after build:umd)
 ## API
 
 - `new LibfwClient(options?)`
+  - `downloadWindow: number` (default `4`) — in-flight byte-range GETs per
+    single file download; `1` disables parallelism.
+  - `downloadChunkSize: number` (default `262144`, 256 KiB) — byte range size
+    for parallel downloads; the engine reorders in-flight chunks in memory
+    (worst case ≈ `downloadWindow * downloadChunkSize` bytes) so the SDK
+    still receives data in order.
   - `downloadMode: 'auto' | 'fs' | 'browser'` (default `'auto'`) — `'fs'`
     streams downloads through the File System Access API; `'browser'` buffers
     and triggers a traditional browser download (folders become `.zip`);

package/index.d.ts

@@ -52,8 +52,30 @@ export interface LibfwEvent {
 export interface LibfwClientOptions {
   /** Base URL the libfw server routes are mounted under. Default `''`. */
   baseUrl?: string;
-  /** Max concurrent file transfers. Default `4`. */
+  /** Max concurrently-transferring files. Default `4`. */
   concurrency?: number;
+  /**
+   * In-flight chunk window for a single file's upload, independent of
+   * `concurrency`. A higher value keeps high-latency links saturated and
+   * reduces upload stutter; keep it within your server's connection limit
+   * (~6 for HTTP/1.1). Default `8`.
+   */
+  uploadWindow?: number;
+  /**
+   * In-flight byte-range window for a single file's download. Large files
+   * are fetched as `downloadWindow` concurrent `Range` GETs (tus-style
+   * parallel transfer), so a single file's throughput is bounded by
+   * bandwidth instead of one connection's `chunkSize / RTT` on high-latency
+   * links. `1` disables parallelism. Default `4`.
+   */
+  downloadWindow?: number;
+  /**
+   * Byte range size for parallel downloads. Smaller than the upload chunk
+   * on purpose: the engine reorders in-flight chunks in memory (worst case
+   * ≈ `downloadWindow * downloadChunkSize` bytes) so the SDK still receives
+   * data strictly in order. Default `262144` (256 KiB).
+   */
+  downloadChunkSize?: number;
   /** Negotiate zrip compression. Default `true`. */
   compress?: boolean;
   /** Upload chunk size in bytes. Default 2 MiB. */

package/index.js

@@ -188,7 +188,22 @@ export class LibfwClient {
   /**
    * @param {object} [options]
    * @param {string} [options.baseUrl=''] base URL the server routes are mounted under
-   * @param {number} [options.concurrency=4] max concurrent file transfers
+   * @param {number} [options.concurrency=4] max concurrently-transferring files
+   * @param {number} [options.uploadWindow=8] in-flight chunk window for a
+   *        single file's upload; independent of `concurrency`, keeps a
+   *        high-latency link saturated (raise it to reduce upload stutter;
+   *        keep within your server's connection limit, ~6 for HTTP/1.1)
+   * @param {number} [options.downloadWindow=4] in-flight byte-range window
+   *        for a single file's download. Large files are fetched as
+   *        `downloadWindow` concurrent `Range` GETs (tus-style parallel
+   *        transfer), so a single file's throughput is bounded by bandwidth
+   *        instead of one connection's `chunkSize / RTT` on high-latency
+   *        links. `1` disables parallelism (sequential downloads).
+   * @param {number} [options.downloadChunkSize=262144] byte range size for
+   *        parallel downloads (256 KiB default). Smaller than the upload
+   *        chunk on purpose: the engine reorders in-flight chunks in memory
+   *        (worst case ≈ `downloadWindow * downloadChunkSize` bytes) so the
+   *        SDK still receives data strictly in order.
    * @param {boolean} [options.compress=true] negotiate zrip compression
    * @param {number} [options.chunkSize=2097152] upload chunk size in bytes
    * @param {number} [options.maxRetries=3] retries per chunk/file before failing
@@ -216,6 +231,9 @@ export class LibfwClient {
     this._options = {
       baseUrl: '',
       concurrency: 4,
+      uploadWindow: 8,
+      downloadWindow: 4,
+      downloadChunkSize: 256 * 1024,
       compress: true,
       chunkSize: 2 * 1024 * 1024,
       maxRetries: 3,
@@ -272,6 +290,9 @@ export class LibfwClient {
     await this._initPromise;
     const engine = new WasmEngine({
       concurrency: this._options.concurrency,
+      uploadWindow: this._options.uploadWindow,
+      downloadWindow: this._options.downloadWindow,
+      downloadChunkSize: this._options.downloadChunkSize,
       compress: this._options.compress,
       chunkSize: this._options.chunkSize,
       maxRetries: this._options.maxRetries,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "libfw-client",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "High-performance streaming file & folder transfer SDK for the browser (libfw WASM engine + File System Access API + IndexedDB resume).",
   "license": "MIT",
   "type": "module",

package/pkg/libfw_client.d.ts

@@ -33,8 +33,9 @@ export class LibfwClient {
     has_callbacks(): boolean;
     /**
      * Create an engine. `options` may include:
-     * `{ concurrency, compress, chunkSize, maxRetries, baseRetryDelayMs,
-     * maxRetryDelayMs, timeoutMs }`.
+     * `{ concurrency, uploadWindow, downloadWindow, downloadChunkSize,
+     * compress, chunkSize, maxRetries, baseRetryDelayMs, maxRetryDelayMs,
+     * timeoutMs }`.
      */
     constructor(opts: any);
     /**

package/pkg/libfw_client.js

@@ -76,8 +76,9 @@ export class LibfwClient {
     }
     /**
      * Create an engine. `options` may include:
-     * `{ concurrency, compress, chunkSize, maxRetries, baseRetryDelayMs,
-     * maxRetryDelayMs, timeoutMs }`.
+     * `{ concurrency, uploadWindow, downloadWindow, downloadChunkSize,
+     * compress, chunkSize, maxRetries, baseRetryDelayMs, maxRetryDelayMs,
+     * timeoutMs }`.
      * @param {any} opts
      */
     constructor(opts) {
@@ -462,7 +463,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: 135, ret: Result(Unit), inner_ret: Some(Result(Unit)) }, mutable: true }) -> Externref`.
+            // Cast intrinsic for `Closure(Closure { owned: true, function: Function { arguments: [Externref], shim_idx: 145, 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/package.json

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