@es-labs/jslib 0.0.1

package/iso/fetch.js

@@ -0,0 +1,129 @@
+// TODO add retry - https://dev.to/ycmjason/javascript-fetch-retry-upon-failure-3p6g
+class Fetch {
+  /**
+   * 
+   * @param {*} options 
+   * @param {*} tokens 
+   */
+  constructor(options = {}, tokens = {}) {
+    this.options = {
+      baseUrl: '',
+      credentials: 'same-origin',
+      forceLogoutFn: () => {}, // function to call when forcing a logout
+      refreshUrl: '',
+      timeoutMs: 0,
+      maxRetry: 0
+    }
+    Object.assign(this.options, options)
+    this.tokens = { access: '', refresh: '' }
+    Object.assign(this.tokens, tokens)
+  }
+
+  /**
+   * 
+   * @param {string} url 
+   * @param {string} baseUrl 
+   * @returns {object} { urlOrigin, urlPath, urlFull, urlSearch }
+   * @throws {Error} if URL is invalid
+   */
+  static parseUrl (url, baseUrl = '') {
+    let urlPath = url
+    let urlOrigin = baseUrl
+    let urlFull = baseUrl + urlPath
+    let urlSearch = ''
+    try {
+      urlSearch = (url.lastIndexOf('?') !== -1) ? url.split('?').pop() : '' // handle /abc/def?aa=1&bb=2
+      if (urlSearch) urlSearch = '?' + urlSearch // prepend ?
+      const { origin = '', pathname = '', search = '' } = new URL(url) // http://example.com:3001/abc/ees?aa=1&bb=2
+      urlOrigin = origin
+      urlPath = pathname
+      urlFull = origin + pathname
+      urlSearch = search
+    } catch (e) {
+    }
+    return { urlOrigin, urlPath, urlFull, urlSearch }
+  }
+  
+  setOptions (options) { Object.assign(this.options, options) }
+  getOptions () { return this.options }
+
+  setTokens (tokens) { Object.assign(this.tokens, tokens) }
+  getTokens () { return this.tokens }
+
+  async http (method, url, body = null, query = null, headers = null) {
+    const { urlOrigin, urlPath, urlFull, urlSearch } = Fetch.parseUrl(url, this.options.baseUrl)
+    try {
+      const controller = new AbortController()
+      const signal = controller.signal
+      if (this.options.timeoutMs > 0) setTimeout(() => controller.abort(), this.options.timeoutMs) // err.name === 'AbortError'
+  
+      let qs = (query && typeof query === 'object') // null is also an object
+        ? '?' +
+          Object.keys(query).map((key) => encodeURIComponent(key) + '=' + encodeURIComponent(query[key])).join('&')
+        : (query || '')
+      qs = qs ? qs + urlSearch.substring(1) // remove the question mark
+        : urlSearch
+  
+      if (!headers) {
+        headers = {
+          Accept: 'application/json'
+        }
+      }
+      const options = { method, headers }
+      if (this.options.timeoutMs > 0) options.signal = signal
+      if (this.options.credentials !== 'include') { // include === HTTPONLY_TOKEN
+        if (this.tokens.access) options.headers.Authorization = `Bearer ${this.tokens.access}`
+      }
+      options.credentials = this.options.credentials
+  
+      if (['POST', 'PATCH', 'PUT'].includes(method)) { // check if HTTP method has req body (DELETE is maybe)
+        if (body && body instanceof FormData) {
+          options.body = body // options.headers['Content-Type'] = 'multipart/form-data' // NOT NEEDED!!!
+        } else if (options.headers['Content-Type'] && options.headers['Content-Type'] === 'application/x-www-form-urlencoded') {
+          options.body = new URLSearchParams(body) // body should be JSON
+        } else if (options.headers['Content-Type'] && options.headers['Content-Type'] === 'application/octet-stream') {
+          options.body = body // handling stream...
+        } else {
+          options.headers['Content-Type'] = 'application/json' // NEEDED!!!
+          options.body = JSON.stringify(body)
+        }  
+      }
+  
+      const rv0 = await fetch(urlFull + qs, options)
+      const txt0 = await rv0.text() // handle empty body as xxx.json() cannot
+      rv0.data = txt0.length ? JSON.parse(txt0) : {}
+      if (rv0.status >= 200 && rv0.status < 400) return rv0
+      else if (rv0.status === 401) { // no longer needed urlPath !== '/api/auth/refresh'
+        if (rv0.data.message === 'Token Expired Error' && this.options.refreshUrl) {
+          try {
+            const rv1 = await this.http('POST', urlOrigin + this.options.refreshUrl, { refresh_token: this.tokens.refresh }) // rv1 JSON already processed
+            // status code should be < 400 here
+            this.tokens.access = rv1.data.access_token
+            this.tokens.refresh = rv1.data.refresh_token
+            if (options.credentials !== 'include') { // include === HTTPONLY_TOKEN
+              if (this.tokens.access) options.headers.Authorization = `Bearer ${this.tokens.access}`
+            }
+            const rv2 = await fetch(urlFull + qs, options)
+            const txt2 = await rv2.text()
+            rv2.data = txt2.length ? JSON.parse(txt2) : {}
+            return rv2
+          } catch (e) {
+            throw e
+          }
+        }
+      }
+      throw rv0 // error
+    } catch (e) {
+      if (e?.data?.message !== 'Token Expired Error' && (e.status === 401 || e.status === 403)) this.options.forceLogoutFn()
+      throw e // some other error
+    }
+  }
+  
+  async post (url, body = null, query = null, headers = null) { return this.http('POST', url, body, query, headers) }
+  async put (url, body = null, query = null, headers = null) { return this.http('PUT', url, body, query, headers) }
+  async patch (url, body = null, query = null, headers = null) { return this.http('PATCH', url, body, query, headers) }
+  async del (url, query = null, headers = null) { return this.http('DELETE', url, null, query, headers) }
+  async get (url, query = null, headers = null) { return this.http('GET', url, null, query, headers) }
+}
+
+export default Fetch

package/iso/fetch2.js

@@ -0,0 +1,180 @@
+/**
+ * Fetch with AbortController timeout + retry mechanism
+ *
+ * Features:
+ *  - Per-attempt timeout via AbortController
+ *  - Exponential backoff with jitter between retries
+ *  - Retries on network errors and configurable HTTP status codes
+ *  - External abort signal support (cancel from outside)
+ *  - Retry lifecycle hooks (onRetry)
+ */
+
+// ─── Default Config ───────────────────────────────────────────────────────────
+
+const DEFAULTS = {
+  timeout: 10_000,          // ms per attempt before aborting
+  retries: 3,               // max retry attempts (0 = no retries)
+  baseDelay: 300,           // ms — base for exponential backoff
+  maxDelay: 10_000,         // ms — cap on backoff delay
+  backoffFactor: 2,         // exponential multiplier
+  jitter: true,             // randomise delay to avoid thundering herd
+  retryOn: [408, 429, 500, 502, 503, 504], // HTTP codes to retry on
+  onRetry: null,            // ({ attempt, error, delay }) => void
+};
+
+// ─── Core ─────────────────────────────────────────────────────────────────────
+
+/**
+ * fetch() with per-attempt timeout and automatic retry on failure.
+ *
+ * @param {string}  url
+ * @param {object}  [options]                - All standard fetch options, plus:
+ * @param {number}  [options.timeout]        - Ms before each attempt times out
+ * @param {number}  [options.retries]        - Max number of retries after first failure
+ * @param {number}  [options.baseDelay]      - Initial backoff delay in ms
+ * @param {number}  [options.maxDelay]       - Max backoff delay in ms
+ * @param {number}  [options.backoffFactor]  - Exponential backoff multiplier
+ * @param {boolean} [options.jitter]         - Add randomness to delay
+ * @param {number[]} [options.retryOn]       - HTTP status codes that trigger a retry
+ * @param {Function} [options.onRetry]       - Called before each retry attempt
+ * @param {AbortSignal} [options.signal]     - External signal to cancel all attempts
+ * @returns {Promise<Response>}
+ */
+async function fetchWithRetry(url, options = {}) {
+  const {
+    timeout,
+    retries,
+    baseDelay,
+    maxDelay,
+    backoffFactor,
+    jitter,
+    retryOn,
+    onRetry,
+    signal: externalSignal, // caller-supplied cancel signal
+    ...fetchOptions          // remaining standard fetch options
+  } = { ...DEFAULTS, ...options };
+
+  let attempt = 0;
+
+  while (true) {
+    // Honour external cancellation before starting each attempt
+    if (externalSignal?.aborted) {
+      throw new DOMException('Fetch aborted by caller', 'AbortError');
+    }
+
+    // Create a per-attempt AbortController for the timeout
+    const timeoutController = new AbortController();
+    const timeoutId = setTimeout(() => timeoutController.abort(), timeout);
+
+    // Merge the timeout signal with any external signal
+    const signal = externalSignal
+      ? mergeSignals([timeoutController.signal, externalSignal])
+      : timeoutController.signal;
+
+    let response;
+    let error;
+
+    try {
+      response = await fetch(url, { ...fetchOptions, signal });
+    } catch (err) {
+      error = err;
+    } finally {
+      clearTimeout(timeoutId);
+    }
+
+    // ── Determine if we should retry ────────────────────────────────────────
+
+    const isTimeout    = error?.name === 'AbortError' && timeoutController.signal.aborted;
+    const isNetworkErr = error && !isTimeout;
+    const isExternalAbort = externalSignal?.aborted;
+
+    // Never retry if the caller explicitly cancelled
+    if (isExternalAbort) {
+      throw new DOMException('Fetch aborted by caller', 'AbortError');
+    }
+
+    const shouldRetry =
+      attempt < retries &&
+      (isTimeout || isNetworkErr || (response && retryOn.includes(response.status)));
+
+    if (!shouldRetry) {
+      // No more retries — resolve or throw
+      if (error) throw error;
+      return response;
+    }
+
+    // ── Backoff before next attempt ──────────────────────────────────────────
+
+    const delay = calcDelay({ attempt, baseDelay, maxDelay, backoffFactor, jitter });
+
+    // Check Retry-After header on 429/503 and honour it if present
+    const retryAfterMs = parseRetryAfter(response?.headers?.get('Retry-After'));
+    const waitMs = retryAfterMs ? Math.min(retryAfterMs, maxDelay) : delay;
+
+    const retryReason = isTimeout
+      ? `Timeout after ${timeout}ms`
+      : isNetworkErr
+        ? error.message
+        : `HTTP ${response.status}`;
+
+    if (typeof onRetry === 'function') {
+      onRetry({ attempt: attempt + 1, total: retries, reason: retryReason, delay: waitMs });
+    }
+
+    await sleep(waitMs, externalSignal); // sleep is also cancellable
+    attempt++;
+  }
+}
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+/** Exponential backoff with optional jitter */
+function calcDelay({ attempt, baseDelay, maxDelay, backoffFactor, jitter }) {
+  const exponential = baseDelay * Math.pow(backoffFactor, attempt);
+  const capped = Math.min(exponential, maxDelay);
+  return jitter
+    ? capped * (0.5 + Math.random() * 0.5) // jitter: 50%–100% of capped
+    : capped;
+}
+
+/**
+ * Merge multiple AbortSignals into one.
+ * Aborts as soon as ANY of the signals fires.
+ * (Native AbortSignal.any() is available in Node 20+ / Chrome 116+)
+ */
+function mergeSignals(signals) {
+  if (typeof AbortSignal.any === 'function') {
+    return AbortSignal.any(signals);
+  }
+  // Polyfill for older environments
+  const controller = new AbortController();
+  for (const signal of signals) {
+    if (signal.aborted) { controller.abort(signal.reason); break; }
+    signal.addEventListener('abort', () => controller.abort(signal.reason), { once: true });
+  }
+  return controller.signal;
+}
+
+/** Sleep for ms, but cancel early if signal fires */
+function sleep(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) return reject(new DOMException('Aborted', 'AbortError'));
+    const id = setTimeout(resolve, ms);
+    signal?.addEventListener('abort', () => {
+      clearTimeout(id);
+      reject(new DOMException('Aborted', 'AbortError'));
+    }, { once: true });
+  });
+}
+
+/** Parse Retry-After header into milliseconds (supports seconds int and HTTP date) */
+function parseRetryAfter(header) {
+  if (!header) return null;
+  const seconds = parseInt(header, 10);
+  if (!isNaN(seconds)) return seconds * 1000;
+  const date = new Date(header).getTime();
+  if (!isNaN(date)) return Math.max(0, date - Date.now());
+  return null;
+}
+
+export { fetchWithRetry };

package/iso/log-filter.js

@@ -0,0 +1,17 @@
+//NOSONAR const type = 'error'
+// const orig = console[type]
+// console[type] = function logError() {
+//   orig.apply(console, [`[${new Date().toISOString().replace("T", " ").replace(/\..+/, "")}]`, ...arguments])
+// }
+//
+// Usage (filter out console.log): LogFilter(['log'])
+
+const LogFilter = (function () {
+  return function (list) {
+    if (list && list.length) {
+      list.forEach(item => {
+        console[item] = function () { }
+      })
+    }
+  }
+})()

package/iso/sleep.js

@@ -0,0 +1,6 @@
+/**
+ * wait asynchronously for ms milliseconds
+ * @param {number} ms - milliseconds to sleep
+ * @returns 
+ */
+export const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms))

package/iso/ws.js

@@ -0,0 +1,63 @@
+// Using options instead of class, only below commented code is use to replace "class Ws {", and the constructor 
+// const ws = { // similar except need comma after eachb option
+//   instance: null, // web socket instance
+//   options: {
+//     onmessage: null, // attach message handler
+//     endpoint: null,
+//     reconnectMS: 0, // number of retries? not implemented
+//   },
+class Ws {
+  constructor(options = {}, tokens = {}) {
+    this.instance = null // web socket instance
+    this.options = {
+      onmessage: null, // attach message handler
+      endpoint: null,
+      reconnectMS: 0, // number of retries? not implemented
+    }
+    Object.assign(this.options, options)
+  }
+  setOptions (options) { Object.assign(this.options, options) }
+  getOptions () { return this.options }
+
+  setMessage(onmessage) {
+    this.options.onmessage = onmessage
+    if (this.instance) this.instance.onmessage = this.options.onmessage
+  }
+  send(message) {
+    if (this.instance) this.instance.send(message)
+  }
+  close() {
+    if (this.instance) {
+      this.instance.close()
+      this.instance = null
+    }
+  }
+  connect() {
+    console.log(`ws connecting... endpoint=${this.options.endpoint} reconnectMs=${this.options.reconnectMS}`)
+    if (!this.options.endpoint) return console.log('ws connect failed - no endpoint')
+    if (this.instance) return console.log('ws connect failed - already connected')
+
+    try {
+      this.instance = new WebSocket(this.options.endpoint)
+      this.instance.onopen = () => console.log('ws open - connected')
+      this.instance.onerror = (err) => console.log(err)
+      this.instance.onmessage = this.options.onmessage
+      this.instance.onclose = (e) => {
+        if (!e.wasClean && this.options.reconnectMs) {
+          setTimeout(
+            () => {
+              this.connect()
+            },
+            this.options.reconnectMs > 1000 ? this.options.reconnectMs : 1000
+          )
+        } else {
+          console.log(`ws connection closed cleanly, code=${e.code} reason=${e.reason}`)
+        }
+      }
+    } catch (e) {
+      console.log('ws connect error', e.toString())
+    }
+  }
+}
+
+export default Ws

package/node/oss-files/oss-uploader-client-fetch.js

@@ -0,0 +1,258 @@
+/**
+ * Alibaba Cloud OSS Large File Uploader (Client-Side)
+ * Uses the S3-compatible API via pre-signed URLs generated by your backend.
+ *
+ * OSS S3-compatibility docs:
+ *   https://www.alibabacloud.com/help/en/oss/developer-reference/compatibility-with-amazon-s3
+ *
+ * Key OSS-specific differences from AWS S3:
+ *  - Endpoint format: https://<bucket>.<region>.aliyuncs.com  (path-style not needed)
+ *  - Minimum multipart part size: 100KB (S3 is 5MB) — we still use 10MB for reliability
+ *  - Max parts: 10,000 (same as S3)
+ *  - ETag is returned without quotes in some OSS responses — we normalize this below
+ *  - CORS must expose the ETag header explicitly on the OSS bucket
+ *
+ * Usage:
+ *   const uploader = new OSSUploader({ signEndpoint: '/api/oss/sign' });
+ *   const result = await uploader.upload(file, { onProgress: pct => console.log(pct + '%') });
+ *
+ * Note on progress reporting with fetch:
+ *   The fetch API does not natively expose upload progress (only download progress via
+ *   Response.body.getReader()). To track upload progress we wrap the Blob in a
+ *   ReadableStream that counts bytes as they are consumed by fetch.
+ */
+
+const CHUNK_SIZE = 10 * 1024 * 1024;        // 10MB per part
+const MULTIPART_THRESHOLD = 5 * 1024 * 1024; // Use multipart above 5MB
+
+class OSSUploader {
+  /**
+   * @param {object} options
+   * @param {string} options.signEndpoint    - Your backend endpoint for signed URL generation
+   * @param {number} [options.chunkSize]     - Bytes per part (default 10MB, min 100KB for OSS)
+   * @param {number} [options.maxConcurrent] - Parallel part uploads (default 3)
+   */
+  constructor(options = {}) {
+    if (!options.signEndpoint) throw new Error('signEndpoint is required');
+    this.signEndpoint = options.signEndpoint;
+    this.chunkSize = options.chunkSize || CHUNK_SIZE;
+    this.maxConcurrent = options.maxConcurrent || 3;
+  }
+
+  // ─── Public API ──────────────────────────────────────────────────────────────
+
+  /**
+   * Upload a File or Blob to Alibaba OSS.
+   *
+   * @param {File|Blob} file
+   * @param {object}    [opts]
+   * @param {string}    [opts.key]          - OSS object key (defaults to file.name)
+   * @param {Function}  [opts.onProgress]   - Callback with integer 0–100
+   * @param {AbortSignal} [opts.signal]     - AbortController signal to cancel
+   * @returns {Promise<{ key: string, location: string }>}
+   */
+  async upload(file, opts = {}) {
+    const key = opts.key || file.name;
+    const onProgress = opts.onProgress || (() => {});
+    const signal = opts.signal || null;
+
+    if (file.size <= MULTIPART_THRESHOLD) {
+      return this._singleUpload(file, key, onProgress, signal);
+    }
+    return this._multipartUpload(file, key, onProgress, signal);
+  }
+
+  // ─── Single-Part Upload (≤5MB) ───────────────────────────────────────────────
+
+  async _singleUpload(file, key, onProgress, signal) {
+    onProgress(0);
+
+    const { signedUrl, location } = await this._callBackend({
+      type: 'single',
+      key,
+      contentType: file.type || 'application/octet-stream',
+      size: file.size,
+    });
+
+    await this._putBlob(signedUrl, file, file.type, (loaded) => {
+      onProgress(Math.round((loaded / file.size) * 100));
+    }, signal);
+
+    onProgress(100);
+    return { key, location };
+  }
+
+  // ─── Multipart Upload (>5MB) ─────────────────────────────────────────────────
+
+  async _multipartUpload(file, key, onProgress, signal) {
+    // Step 1 — Initiate: backend calls CreateMultipartUpload, returns uploadId
+    const { uploadId } = await this._callBackend({
+      type: 'initiate',
+      key,
+      contentType: file.type || 'application/octet-stream',
+    });
+
+    const chunks = this._splitFile(file);
+    const partProgress = new Array(chunks.length).fill(0);
+
+    const reportProgress = () => {
+      const uploaded = partProgress.reduce((s, v) => s + v, 0);
+      onProgress(Math.round((uploaded / file.size) * 100));
+    };
+
+    // Step 2 — Upload parts concurrently
+    const completedParts = [];
+    const queue = chunks.map((chunk, i) => ({ chunk, partNumber: i + 1, index: i }));
+
+    const worker = async () => {
+      while (queue.length > 0) {
+        const { chunk, partNumber, index } = queue.shift();
+
+        if (signal?.aborted) throw new DOMException('Upload aborted', 'AbortError');
+
+        // Get a signed URL for this specific part
+        const { signedUrl } = await this._callBackend({
+          type: 'part',
+          key,
+          uploadId,
+          partNumber,
+        });
+
+        // PUT the chunk; OSS returns ETag in response header
+        const rawETag = await this._putBlob(
+          signedUrl,
+          chunk,
+          file.type || 'application/octet-stream',
+          (loaded) => { partProgress[index] = loaded; reportProgress(); },
+          signal,
+          /* returnETag= */ true,
+        );
+
+        // OSS sometimes returns ETag without surrounding quotes — normalise
+        const etag = rawETag?.replace(/"/g, '') ? `"${rawETag.replace(/"/g, '')}"` : rawETag;
+
+        completedParts.push({ PartNumber: partNumber, ETag: etag });
+      }
+    };
+
+    const workers = Array.from({ length: this.maxConcurrent }, worker);
+    try {
+      await Promise.all(workers);
+    } catch (err) {
+      // Best-effort abort to avoid orphaned multipart uploads costing storage
+      await this._callBackend({ type: 'abort', key, uploadId }).catch(() => {});
+      throw err;
+    }
+
+    // Step 3 — Complete: parts must be sorted by PartNumber
+    completedParts.sort((a, b) => a.PartNumber - b.PartNumber);
+
+    const { location } = await this._callBackend({
+      type: 'complete',
+      key,
+      uploadId,
+      parts: completedParts,
+    });
+
+    onProgress(100);
+    return { key, location };
+  }
+
+  // ─── Helpers ─────────────────────────────────────────────────────────────────
+
+  _splitFile(file) {
+    const chunks = [];
+    for (let offset = 0; offset < file.size; offset += this.chunkSize) {
+      chunks.push(file.slice(offset, offset + this.chunkSize));
+    }
+    return chunks;
+  }
+
+  async _callBackend(payload) {
+    const res = await fetch(this.signEndpoint, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(payload),
+    });
+    if (!res.ok) {
+      const text = await res.text();
+      throw new Error(`Backend error (${res.status}): ${text}`);
+    }
+    return res.json();
+  }
+
+  /**
+   * PUT a Blob to a pre-signed OSS URL using the fetch API.
+   *
+   * Upload progress is tracked by wrapping the Blob in a ReadableStream that
+   * counts bytes as they pass through, since fetch does not expose an upload
+   * progress event like XHR does.
+   *
+   * OSS S3-compatible PUT requires:
+   *   - Content-Type header must match the value used when signing
+   *   - Do NOT send Content-MD5 unless you included it in the signed headers
+   *
+   * @param {string}      signedUrl
+   * @param {Blob}        blob
+   * @param {string}      contentType
+   * @param {Function}    onProgress   - Called with bytes uploaded so far
+   * @param {AbortSignal|null} signal
+   * @param {boolean}     returnETag   - If true, resolves with the ETag header value
+   * @returns {Promise<string|undefined>}
+   */
+  async _putBlob(signedUrl, blob, contentType, onProgress, signal, returnETag = false) {
+    const totalBytes = blob.size;
+    let uploadedBytes = 0;
+
+    // Wrap the blob's byte stream so we can intercept each chunk and report progress.
+    // fetch() cannot report upload progress on its own — this is the standard workaround.
+    const progressStream = new ReadableStream({
+      async start(controller) {
+        const reader = blob.stream().getReader();
+        try {
+          while (true) {
+            const { done, value } = await reader.read();
+            if (done) { controller.close(); break; }
+            uploadedBytes += value.byteLength;
+            onProgress(uploadedBytes);
+            controller.enqueue(value);
+          }
+        } catch (err) {
+          controller.error(err);
+        }
+      },
+    });
+
+    const headers = {};
+    if (contentType) headers['Content-Type'] = contentType;
+
+    // Content-Length must be set explicitly — fetch cannot infer it from a
+    // ReadableStream, and OSS requires it for multipart PUT requests.
+    headers['Content-Length'] = String(totalBytes);
+
+    let response;
+    try {
+      response = await fetch(signedUrl, {
+        method: 'PUT',
+        headers,
+        body: progressStream,
+        signal,
+        // Required for streaming request bodies in the fetch API (Chrome 105+, Firefox 112+)
+        duplex: 'half',
+      });
+    } catch (err) {
+      if (err.name === 'AbortError') throw new DOMException('Upload aborted', 'AbortError');
+      throw new Error(`Network error during OSS upload: ${err.message}`);
+    }
+
+    if (!response.ok) {
+      // OSS returns XML error bodies — surface them for easier debugging
+      const text = await response.text().catch(() => '');
+      throw new Error(`OSS PUT failed (HTTP ${response.status}): ${text}`);
+    }
+
+    return returnETag ? response.headers.get('ETag') : undefined;
+  }
+}
+
+export default OSSUploader;

package/node/oss-files/oss-uploader-client-fetch.md

@@ -0,0 +1,31 @@
+The only meaningful change was replacing `_putBlob` — everything else stayed identical. Here's what changed and why:
+
+**The core swap — `XMLHttpRequest` → `fetch`**
+
+The old `xhr.send(blob)` becomes `fetch(url, { method: 'PUT', body: progressStream, duplex: 'half' })`.
+
+**The progress tracking problem**
+
+`fetch` has no `upload.onprogress` event like XHR does. The workaround is wrapping the blob in a `ReadableStream` that increments a counter as bytes flow through it:
+
+```js
+const progressStream = new ReadableStream({
+  async start(controller) {
+    const reader = blob.stream().getReader();
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) { controller.close(); break; }
+      uploadedBytes += value.byteLength;  // ← count bytes here
+      onProgress(uploadedBytes);
+      controller.enqueue(value);          // ← pass them along unchanged
+    }
+  }
+});
+```
+
+**Two things required for streaming bodies in fetch:**
+
+1. `duplex: 'half'` — required by the spec when passing a `ReadableStream` as the body (Chrome 105+, Firefox 112+). Without it, some browsers throw a `TypeError`.
+2. `Content-Length` set explicitly — fetch can't infer the size from a stream, and OSS requires it for part uploads.
+
+**Error handling** is cleaner with fetch since `response.ok` + `response.text()` replaces checking `xhr.status` and reading `xhr.responseText`.