@backblaze-labs/b2-sdk 0.3.0 → 0.4.0

package/dist/streams/progress.cjs

@@ -1,4 +1,3 @@
-//#region src/streams/progress.ts
 /**
 * Accumulates byte and part counts and emits {@link ProgressEvent}s to a listener.
 *
@@ -19,31 +18,91 @@ var ProgressTracker = class {
 	partsCompleted = 0;
 	/** Timestamp when tracking began. */
 	startTime;
+	/** Minimum milliseconds between byte-only emissions. */
+	minIntervalMs;
+	/** Timestamp of the most recent emitted snapshot. */
+	lastEmitTime = null;
+	/** Timer scheduled for a coalesced byte-only emission. */
+	pendingEmitTimer;
+	/** Listener error captured from a detached timer callback. */
+	listenerError;
 	/**
 	* Creates a new ProgressTracker.
 	* @param listener - Callback to receive progress events, or undefined to disable.
 	* @param totalBytes - Expected total bytes, or null if unknown.
 	* @param totalParts - Expected total parts, or null if not a multipart transfer.
+	* @param options - Optional emission controls.
 	*/
-	constructor(listener, totalBytes, totalParts) {
+	constructor(listener, totalBytes, totalParts, options = {}) {
 		this.listener = listener;
 		this.totalBytes = totalBytes;
 		this.totalParts = totalParts;
 		this.startTime = Date.now();
+		this.minIntervalMs = Math.max(0, options.minIntervalMs ?? 100);
 	}
 	/**
-	* Record that additional bytes have been transferred and notify the listener.
+	* Record that additional bytes have been transferred and schedule listener notification.
 	* @param count - The number of additional bytes that were transferred.
 	*/
 	addBytes(count) {
+		this.throwPendingListenerError();
 		this.bytesTransferred += count;
-		this.emit();
+		this.emitThrottled();
 	}
 	/** Record that a multipart part has completed and notify the listener. */
 	completePart() {
+		this.throwPendingListenerError();
+		this.flushPendingEmit();
 		this.partsCompleted++;
+		this.emitNow();
+	}
+	/** Cancel any pending coalesced progress emission. */
+	dispose() {
+		this.clearPendingEmit();
+		this.listenerError = void 0;
+	}
+	emitThrottled() {
+		if (this.listener === void 0) return;
+		if (this.minIntervalMs === 0) {
+			this.emitNow();
+			return;
+		}
+		const now = Date.now();
+		if (this.lastEmitTime === null || now - this.lastEmitTime >= this.minIntervalMs) {
+			this.emitNow(now);
+			return;
+		}
+		if (this.pendingEmitTimer !== void 0) return;
+		const delay = Math.max(0, this.minIntervalMs - (now - this.lastEmitTime));
+		this.pendingEmitTimer = setTimeout(() => {
+			this.pendingEmitTimer = void 0;
+			try {
+				this.emitNow();
+			} catch (err) {
+				this.listenerError = err;
+			}
+		}, delay);
+		this.pendingEmitTimer.unref?.();
+	}
+	flushPendingEmit() {
+		if (this.pendingEmitTimer !== void 0) this.emitNow();
+	}
+	clearPendingEmit() {
+		if (this.pendingEmitTimer === void 0) return;
+		clearTimeout(this.pendingEmitTimer);
+		this.pendingEmitTimer = void 0;
+	}
+	emitNow(now = Date.now()) {
+		this.clearPendingEmit();
+		this.lastEmitTime = now;
 		this.emit();
 	}
+	throwPendingListenerError() {
+		if (this.listenerError === void 0) return;
+		const err = this.listenerError;
+		this.listenerError = void 0;
+		throw err;
+	}
 	/** Emit the current progress snapshot to the listener, if one is registered. */
 	emit() {
 		this.listener?.({

package/dist/streams/progress.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"progress.cjs","names":[],"sources":["../../src/streams/progress.ts"],"sourcesContent":["/** Snapshot of upload or download progress at a point in time. */\nexport interface ProgressEvent {\n  /** Number of bytes transferred so far. */\n  readonly bytesTransferred: number\n  /** Total bytes expected, or null if unknown. */\n  readonly totalBytes: number | null\n  /** Number of multipart parts completed so far. */\n  readonly partsCompleted: number\n  /** Total number of parts expected, or null if unknown. */\n  readonly totalParts: number | null\n  /** Milliseconds elapsed since the operation started. */\n  readonly elapsedMs: number\n}\n\n/** Callback invoked each time transfer progress changes. */\nexport type ProgressListener = (event: ProgressEvent) => void\n\n/**\n * Accumulates byte and part counts and emits {@link ProgressEvent}s to a listener.\n *\n * Internal building block. The SDK wires one of these inside every\n * transfer that accepts an `onProgress` option; users supply the\n * listener callback, not the tracker. Exported only so SDK source\n * modules can import it; not re-exported through any subpath.\n *\n * @internal\n */\nexport class ProgressTracker {\n  /** Running total of bytes transferred. */\n  private bytesTransferred = 0\n  /** Running count of completed parts. */\n  private partsCompleted = 0\n  /** Timestamp when tracking began. */\n  private readonly startTime: number\n\n  /**\n   * Creates a new ProgressTracker.\n   * @param listener - Callback to receive progress events, or undefined to disable.\n   * @param totalBytes - Expected total bytes, or null if unknown.\n   * @param totalParts - Expected total parts, or null if not a multipart transfer.\n   */\n  constructor(\n    private readonly listener: ProgressListener | undefined,\n    private readonly totalBytes: number | null,\n    private readonly totalParts: number | null,\n  ) {\n    this.startTime = Date.now()\n  }\n\n  /**\n   * Record that additional bytes have been transferred and notify the listener.\n   * @param count - The number of additional bytes that were transferred.\n   */\n  addBytes(count: number): void {\n    this.bytesTransferred += count\n    this.emit()\n  }\n\n  /** Record that a multipart part has completed and notify the listener. */\n  completePart(): void {\n    this.partsCompleted++\n    this.emit()\n  }\n\n  /** Emit the current progress snapshot to the listener, if one is registered. */\n  private emit(): void {\n    this.listener?.({\n      bytesTransferred: this.bytesTransferred,\n      totalBytes: this.totalBytes,\n      partsCompleted: this.partsCompleted,\n      totalParts: this.totalParts,\n      elapsedMs: Date.now() - this.startTime,\n    })\n  }\n}\n"],"mappings":";;;;;;;;;;;AA2BA,IAAa,kBAAb,MAA6B;CAeR;CACA;CACA;;CAfnB,mBAA2B;;CAE3B,iBAAyB;;CAEzB;;;;;;;CAQA,YACE,UACA,YACA,YACA;EAHiB,KAAA,WAAA;EACA,KAAA,aAAA;EACA,KAAA,aAAA;EAEjB,KAAK,YAAY,KAAK,IAAI;CAC5B;;;;;CAMA,SAAS,OAAqB;EAC5B,KAAK,oBAAoB;EACzB,KAAK,KAAK;CACZ;;CAGA,eAAqB;EACnB,KAAK;EACL,KAAK,KAAK;CACZ;;CAGA,OAAqB;EACnB,KAAK,WAAW;GACd,kBAAkB,KAAK;GACvB,YAAY,KAAK;GACjB,gBAAgB,KAAK;GACrB,YAAY,KAAK;GACjB,WAAW,KAAK,IAAI,IAAI,KAAK;EAC/B,CAAC;CACH;AACF"}
+{"version":3,"file":"progress.cjs","names":[],"sources":["../../src/streams/progress.ts"],"sourcesContent":["/** Snapshot of upload or download progress at a point in time. */\nexport interface ProgressEvent {\n  /** Number of bytes transferred so far. */\n  readonly bytesTransferred: number\n  /** Total bytes expected, or null if unknown. */\n  readonly totalBytes: number | null\n  /** Number of multipart parts completed so far. */\n  readonly partsCompleted: number\n  /** Total number of parts expected, or null if unknown. */\n  readonly totalParts: number | null\n  /** Milliseconds elapsed since the operation started. */\n  readonly elapsedMs: number\n}\n\n/** Callback invoked each time transfer progress changes. */\nexport type ProgressListener = (event: ProgressEvent) => void\n\n/** Default minimum time between byte-progress emissions. */\nexport const DEFAULT_PROGRESS_EMIT_INTERVAL_MS = 100\n\n/** Internal controls for ProgressTracker emission behavior. */\nexport interface ProgressTrackerOptions {\n  /**\n   * Minimum milliseconds between byte-only progress emissions.\n   * Set to 0 to emit every change.\n   */\n  readonly minIntervalMs?: number\n}\n\n/**\n * Accumulates byte and part counts and emits {@link ProgressEvent}s to a listener.\n *\n * Internal building block. The SDK wires one of these inside every\n * transfer that accepts an `onProgress` option; users supply the\n * listener callback, not the tracker. Exported only so SDK source\n * modules can import it; not re-exported through any subpath.\n *\n * @internal\n */\nexport class ProgressTracker {\n  /** Running total of bytes transferred. */\n  private bytesTransferred = 0\n  /** Running count of completed parts. */\n  private partsCompleted = 0\n  /** Timestamp when tracking began. */\n  private readonly startTime: number\n  /** Minimum milliseconds between byte-only emissions. */\n  private readonly minIntervalMs: number\n  /** Timestamp of the most recent emitted snapshot. */\n  private lastEmitTime: number | null = null\n  /** Timer scheduled for a coalesced byte-only emission. */\n  private pendingEmitTimer: ReturnType<typeof setTimeout> | undefined\n  /** Listener error captured from a detached timer callback. */\n  private listenerError: unknown\n\n  /**\n   * Creates a new ProgressTracker.\n   * @param listener - Callback to receive progress events, or undefined to disable.\n   * @param totalBytes - Expected total bytes, or null if unknown.\n   * @param totalParts - Expected total parts, or null if not a multipart transfer.\n   * @param options - Optional emission controls.\n   */\n  constructor(\n    private readonly listener: ProgressListener | undefined,\n    private readonly totalBytes: number | null,\n    private readonly totalParts: number | null,\n    options: ProgressTrackerOptions = {},\n  ) {\n    this.startTime = Date.now()\n    this.minIntervalMs = Math.max(0, options.minIntervalMs ?? DEFAULT_PROGRESS_EMIT_INTERVAL_MS)\n  }\n\n  /**\n   * Record that additional bytes have been transferred and schedule listener notification.\n   * @param count - The number of additional bytes that were transferred.\n   */\n  addBytes(count: number): void {\n    this.throwPendingListenerError()\n    this.bytesTransferred += count\n    this.emitThrottled()\n  }\n\n  /** Record that a multipart part has completed and notify the listener. */\n  completePart(): void {\n    this.throwPendingListenerError()\n    this.flushPendingEmit()\n    this.partsCompleted++\n    this.emitNow()\n  }\n\n  /** Cancel any pending coalesced progress emission. */\n  dispose(): void {\n    this.clearPendingEmit()\n    this.listenerError = undefined\n  }\n\n  private emitThrottled(): void {\n    if (this.listener === undefined) return\n    if (this.minIntervalMs === 0) {\n      this.emitNow()\n      return\n    }\n\n    const now = Date.now()\n    if (this.lastEmitTime === null || now - this.lastEmitTime >= this.minIntervalMs) {\n      this.emitNow(now)\n      return\n    }\n\n    if (this.pendingEmitTimer !== undefined) return\n\n    const delay = Math.max(0, this.minIntervalMs - (now - this.lastEmitTime))\n    this.pendingEmitTimer = setTimeout(() => {\n      this.pendingEmitTimer = undefined\n      try {\n        this.emitNow()\n      } catch (err) {\n        this.listenerError = err\n      }\n    }, delay)\n    ;(this.pendingEmitTimer as { unref?: () => void }).unref?.()\n  }\n\n  private flushPendingEmit(): void {\n    if (this.pendingEmitTimer !== undefined) {\n      this.emitNow()\n    }\n  }\n\n  private clearPendingEmit(): void {\n    if (this.pendingEmitTimer === undefined) return\n    clearTimeout(this.pendingEmitTimer)\n    this.pendingEmitTimer = undefined\n  }\n\n  private emitNow(now = Date.now()): void {\n    this.clearPendingEmit()\n    this.lastEmitTime = now\n    this.emit()\n  }\n\n  private throwPendingListenerError(): void {\n    if (this.listenerError === undefined) return\n    const err = this.listenerError\n    this.listenerError = undefined\n    throw err\n  }\n\n  /** Emit the current progress snapshot to the listener, if one is registered. */\n  private emit(): void {\n    this.listener?.({\n      bytesTransferred: this.bytesTransferred,\n      totalBytes: this.totalBytes,\n      partsCompleted: this.partsCompleted,\n      totalParts: this.totalParts,\n      elapsedMs: Date.now() - this.startTime,\n    })\n  }\n}\n"],"mappings":";;;;;;;;;;AAuCA,IAAa,kBAAb,MAA6B;CAwBR;CACA;CACA;;CAxBnB,mBAA2B;;CAE3B,iBAAyB;;CAEzB;;CAEA;;CAEA,eAAsC;;CAEtC;;CAEA;;;;;;;;CASA,YACE,UACA,YACA,YACA,UAAkC,CAAC,GACnC;EAJiB,KAAA,WAAA;EACA,KAAA,aAAA;EACA,KAAA,aAAA;EAGjB,KAAK,YAAY,KAAK,IAAI;EAC1B,KAAK,gBAAgB,KAAK,IAAI,GAAG,QAAQ,iBAAA,GAAkD;CAC7F;;;;;CAMA,SAAS,OAAqB;EAC5B,KAAK,0BAA0B;EAC/B,KAAK,oBAAoB;EACzB,KAAK,cAAc;CACrB;;CAGA,eAAqB;EACnB,KAAK,0BAA0B;EAC/B,KAAK,iBAAiB;EACtB,KAAK;EACL,KAAK,QAAQ;CACf;;CAGA,UAAgB;EACd,KAAK,iBAAiB;EACtB,KAAK,gBAAgB,KAAA;CACvB;CAEA,gBAA8B;EAC5B,IAAI,KAAK,aAAa,KAAA,GAAW;EACjC,IAAI,KAAK,kBAAkB,GAAG;GAC5B,KAAK,QAAQ;GACb;EACF;EAEA,MAAM,MAAM,KAAK,IAAI;EACrB,IAAI,KAAK,iBAAiB,QAAQ,MAAM,KAAK,gBAAgB,KAAK,eAAe;GAC/E,KAAK,QAAQ,GAAG;GAChB;EACF;EAEA,IAAI,KAAK,qBAAqB,KAAA,GAAW;EAEzC,MAAM,QAAQ,KAAK,IAAI,GAAG,KAAK,iBAAiB,MAAM,KAAK,aAAa;EACxE,KAAK,mBAAmB,iBAAiB;GACvC,KAAK,mBAAmB,KAAA;GACxB,IAAI;IACF,KAAK,QAAQ;GACf,SAAS,KAAK;IACZ,KAAK,gBAAgB;GACvB;EACF,GAAG,KAAK;EACP,KAAM,iBAA4C,QAAQ;CAC7D;CAEA,mBAAiC;EAC/B,IAAI,KAAK,qBAAqB,KAAA,GAC5B,KAAK,QAAQ;CAEjB;CAEA,mBAAiC;EAC/B,IAAI,KAAK,qBAAqB,KAAA,GAAW;EACzC,aAAa,KAAK,gBAAgB;EAClC,KAAK,mBAAmB,KAAA;CAC1B;CAEA,QAAgB,MAAM,KAAK,IAAI,GAAS;EACtC,KAAK,iBAAiB;EACtB,KAAK,eAAe;EACpB,KAAK,KAAK;CACZ;CAEA,4BAA0C;EACxC,IAAI,KAAK,kBAAkB,KAAA,GAAW;EACtC,MAAM,MAAM,KAAK;EACjB,KAAK,gBAAgB,KAAA;EACrB,MAAM;CACR;;CAGA,OAAqB;EACnB,KAAK,WAAW;GACd,kBAAkB,KAAK;GACvB,YAAY,KAAK;GACjB,gBAAgB,KAAK;GACrB,YAAY,KAAK;GACjB,WAAW,KAAK,IAAI,IAAI,KAAK;EAC/B,CAAC;CACH;AACF"}

package/dist/streams/progress.d.cts

@@ -13,6 +13,16 @@ export interface ProgressEvent {
 }
 /** Callback invoked each time transfer progress changes. */
 export type ProgressListener = (event: ProgressEvent) => void;
+/** Default minimum time between byte-progress emissions. */
+export declare const DEFAULT_PROGRESS_EMIT_INTERVAL_MS = 100;
+/** Internal controls for ProgressTracker emission behavior. */
+export interface ProgressTrackerOptions {
+    /**
+     * Minimum milliseconds between byte-only progress emissions.
+     * Set to 0 to emit every change.
+     */
+    readonly minIntervalMs?: number;
+}
 /**
  * Accumulates byte and part counts and emits {@link ProgressEvent}s to a listener.
  *
@@ -33,20 +43,36 @@ export declare class ProgressTracker {
     private partsCompleted;
     /** Timestamp when tracking began. */
     private readonly startTime;
+    /** Minimum milliseconds between byte-only emissions. */
+    private readonly minIntervalMs;
+    /** Timestamp of the most recent emitted snapshot. */
+    private lastEmitTime;
+    /** Timer scheduled for a coalesced byte-only emission. */
+    private pendingEmitTimer;
+    /** Listener error captured from a detached timer callback. */
+    private listenerError;
     /**
      * Creates a new ProgressTracker.
      * @param listener - Callback to receive progress events, or undefined to disable.
      * @param totalBytes - Expected total bytes, or null if unknown.
      * @param totalParts - Expected total parts, or null if not a multipart transfer.
+     * @param options - Optional emission controls.
      */
-    constructor(listener: ProgressListener | undefined, totalBytes: number | null, totalParts: number | null);
+    constructor(listener: ProgressListener | undefined, totalBytes: number | null, totalParts: number | null, options?: ProgressTrackerOptions);
     /**
-     * Record that additional bytes have been transferred and notify the listener.
+     * Record that additional bytes have been transferred and schedule listener notification.
      * @param count - The number of additional bytes that were transferred.
      */
     addBytes(count: number): void;
     /** Record that a multipart part has completed and notify the listener. */
     completePart(): void;
+    /** Cancel any pending coalesced progress emission. */
+    dispose(): void;
+    private emitThrottled;
+    private flushPendingEmit;
+    private clearPendingEmit;
+    private emitNow;
+    private throwPendingListenerError;
     /** Emit the current progress snapshot to the listener, if one is registered. */
     private emit;
 }

package/dist/streams/progress.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"progress.d.ts","sourceRoot":"","sources":["../../src/streams/progress.js"],"names":[],"mappings":"AAAA,kEAAkE;AAClE,MAAM,WAAW,aAAa;IAC5B,0CAA0C;IAC1C,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAA;IACjC,gDAAgD;IAChD,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;IAClC,kDAAkD;IAClD,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;IAC/B,0DAA0D;IAC1D,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;IAClC,wDAAwD;IACxD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAC3B;AAED,4DAA4D;AAC5D,MAAM,MAAM,gBAAgB,GAAG,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAA;AAE7D;;;;;;;;;GASG;AACH,qBAAa,eAAe;IAexB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,UAAU;IAhB7B,0CAA0C;IAC1C,OAAO,CAAC,gBAAgB,CAAI;IAC5B,wCAAwC;IACxC,OAAO,CAAC,cAAc,CAAI;IAC1B,qCAAqC;IACrC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAQ;IAElC;;;;;OAKG;gBAEgB,QAAQ,EAAE,gBAAgB,GAAG,SAAS,EACtC,UAAU,EAAE,MAAM,GAAG,IAAI,EACzB,UAAU,EAAE,MAAM,GAAG,IAAI;IAK5C;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAK7B,0EAA0E;IAC1E,YAAY,IAAI,IAAI;IAKpB,gFAAgF;IAChF,OAAO,CAAC,IAAI;CASb"}
+{"version":3,"file":"progress.d.ts","sourceRoot":"","sources":["../../src/streams/progress.js"],"names":[],"mappings":"AAAA,kEAAkE;AAClE,MAAM,WAAW,aAAa;IAC5B,0CAA0C;IAC1C,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAA;IACjC,gDAAgD;IAChD,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;IAClC,kDAAkD;IAClD,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;IAC/B,0DAA0D;IAC1D,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;IAClC,wDAAwD;IACxD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAC3B;AAED,4DAA4D;AAC5D,MAAM,MAAM,gBAAgB,GAAG,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAA;AAE7D,4DAA4D;AAC5D,eAAO,MAAM,iCAAiC,MAAM,CAAA;AAEpD,+DAA+D;AAC/D,MAAM,WAAW,sBAAsB;IACrC;;;OAGG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAA;CAChC;AAED;;;;;;;;;GASG;AACH,qBAAa,eAAe;IAwBxB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,UAAU;IAzB7B,0CAA0C;IAC1C,OAAO,CAAC,gBAAgB,CAAI;IAC5B,wCAAwC;IACxC,OAAO,CAAC,cAAc,CAAI;IAC1B,qCAAqC;IACrC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAQ;IAClC,wDAAwD;IACxD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAQ;IACtC,qDAAqD;IACrD,OAAO,CAAC,YAAY,CAAsB;IAC1C,0DAA0D;IAC1D,OAAO,CAAC,gBAAgB,CAA2C;IACnE,8DAA8D;IAC9D,OAAO,CAAC,aAAa,CAAS;IAE9B;;;;;;OAMG;gBAEgB,QAAQ,EAAE,gBAAgB,GAAG,SAAS,EACtC,UAAU,EAAE,MAAM,GAAG,IAAI,EACzB,UAAU,EAAE,MAAM,GAAG,IAAI,EAC1C,OAAO,GAAE,sBAA2B;IAMtC;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAM7B,0EAA0E;IAC1E,YAAY,IAAI,IAAI;IAOpB,sDAAsD;IACtD,OAAO,IAAI,IAAI;IAKf,OAAO,CAAC,aAAa;IA2BrB,OAAO,CAAC,gBAAgB;IAMxB,OAAO,CAAC,gBAAgB;IAMxB,OAAO,CAAC,OAAO;IAMf,OAAO,CAAC,yBAAyB;IAOjC,gFAAgF;IAChF,OAAO,CAAC,IAAI;CASb"}

package/dist/streams/progress.d.ts

@@ -13,6 +13,16 @@ export interface ProgressEvent {
 }
 /** Callback invoked each time transfer progress changes. */
 export type ProgressListener = (event: ProgressEvent) => void;
+/** Default minimum time between byte-progress emissions. */
+export declare const DEFAULT_PROGRESS_EMIT_INTERVAL_MS = 100;
+/** Internal controls for ProgressTracker emission behavior. */
+export interface ProgressTrackerOptions {
+    /**
+     * Minimum milliseconds between byte-only progress emissions.
+     * Set to 0 to emit every change.
+     */
+    readonly minIntervalMs?: number;
+}
 /**
  * Accumulates byte and part counts and emits {@link ProgressEvent}s to a listener.
  *
@@ -33,20 +43,36 @@ export declare class ProgressTracker {
     private partsCompleted;
     /** Timestamp when tracking began. */
     private readonly startTime;
+    /** Minimum milliseconds between byte-only emissions. */
+    private readonly minIntervalMs;
+    /** Timestamp of the most recent emitted snapshot. */
+    private lastEmitTime;
+    /** Timer scheduled for a coalesced byte-only emission. */
+    private pendingEmitTimer;
+    /** Listener error captured from a detached timer callback. */
+    private listenerError;
     /**
      * Creates a new ProgressTracker.
      * @param listener - Callback to receive progress events, or undefined to disable.
      * @param totalBytes - Expected total bytes, or null if unknown.
      * @param totalParts - Expected total parts, or null if not a multipart transfer.
+     * @param options - Optional emission controls.
      */
-    constructor(listener: ProgressListener | undefined, totalBytes: number | null, totalParts: number | null);
+    constructor(listener: ProgressListener | undefined, totalBytes: number | null, totalParts: number | null, options?: ProgressTrackerOptions);
     /**
-     * Record that additional bytes have been transferred and notify the listener.
+     * Record that additional bytes have been transferred and schedule listener notification.
      * @param count - The number of additional bytes that were transferred.
      */
     addBytes(count: number): void;
     /** Record that a multipart part has completed and notify the listener. */
     completePart(): void;
+    /** Cancel any pending coalesced progress emission. */
+    dispose(): void;
+    private emitThrottled;
+    private flushPendingEmit;
+    private clearPendingEmit;
+    private emitNow;
+    private throwPendingListenerError;
     /** Emit the current progress snapshot to the listener, if one is registered. */
     private emit;
 }

package/dist/streams/progress.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"progress.d.ts","sourceRoot":"","sources":["../../src/streams/progress.js"],"names":[],"mappings":"AAAA,kEAAkE;AAClE,MAAM,WAAW,aAAa;IAC5B,0CAA0C;IAC1C,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAA;IACjC,gDAAgD;IAChD,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;IAClC,kDAAkD;IAClD,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;IAC/B,0DAA0D;IAC1D,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;IAClC,wDAAwD;IACxD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAC3B;AAED,4DAA4D;AAC5D,MAAM,MAAM,gBAAgB,GAAG,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAA;AAE7D;;;;;;;;;GASG;AACH,qBAAa,eAAe;IAexB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,UAAU;IAhB7B,0CAA0C;IAC1C,OAAO,CAAC,gBAAgB,CAAI;IAC5B,wCAAwC;IACxC,OAAO,CAAC,cAAc,CAAI;IAC1B,qCAAqC;IACrC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAQ;IAElC;;;;;OAKG;gBAEgB,QAAQ,EAAE,gBAAgB,GAAG,SAAS,EACtC,UAAU,EAAE,MAAM,GAAG,IAAI,EACzB,UAAU,EAAE,MAAM,GAAG,IAAI;IAK5C;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAK7B,0EAA0E;IAC1E,YAAY,IAAI,IAAI;IAKpB,gFAAgF;IAChF,OAAO,CAAC,IAAI;CASb"}
+{"version":3,"file":"progress.d.ts","sourceRoot":"","sources":["../../src/streams/progress.js"],"names":[],"mappings":"AAAA,kEAAkE;AAClE,MAAM,WAAW,aAAa;IAC5B,0CAA0C;IAC1C,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAA;IACjC,gDAAgD;IAChD,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;IAClC,kDAAkD;IAClD,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;IAC/B,0DAA0D;IAC1D,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;IAClC,wDAAwD;IACxD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAC3B;AAED,4DAA4D;AAC5D,MAAM,MAAM,gBAAgB,GAAG,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAA;AAE7D,4DAA4D;AAC5D,eAAO,MAAM,iCAAiC,MAAM,CAAA;AAEpD,+DAA+D;AAC/D,MAAM,WAAW,sBAAsB;IACrC;;;OAGG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAA;CAChC;AAED;;;;;;;;;GASG;AACH,qBAAa,eAAe;IAwBxB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,UAAU;IAzB7B,0CAA0C;IAC1C,OAAO,CAAC,gBAAgB,CAAI;IAC5B,wCAAwC;IACxC,OAAO,CAAC,cAAc,CAAI;IAC1B,qCAAqC;IACrC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAQ;IAClC,wDAAwD;IACxD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAQ;IACtC,qDAAqD;IACrD,OAAO,CAAC,YAAY,CAAsB;IAC1C,0DAA0D;IAC1D,OAAO,CAAC,gBAAgB,CAA2C;IACnE,8DAA8D;IAC9D,OAAO,CAAC,aAAa,CAAS;IAE9B;;;;;;OAMG;gBAEgB,QAAQ,EAAE,gBAAgB,GAAG,SAAS,EACtC,UAAU,EAAE,MAAM,GAAG,IAAI,EACzB,UAAU,EAAE,MAAM,GAAG,IAAI,EAC1C,OAAO,GAAE,sBAA2B;IAMtC;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAM7B,0EAA0E;IAC1E,YAAY,IAAI,IAAI;IAOpB,sDAAsD;IACtD,OAAO,IAAI,IAAI;IAKf,OAAO,CAAC,aAAa;IA2BrB,OAAO,CAAC,gBAAgB;IAMxB,OAAO,CAAC,gBAAgB;IAMxB,OAAO,CAAC,OAAO;IAMf,OAAO,CAAC,yBAAyB;IAOjC,gFAAgF;IAChF,OAAO,CAAC,IAAI;CASb"}

package/dist/streams/progress.js

@@ -1,4 +1,3 @@
-//#region src/streams/progress.ts
 /**
 * Accumulates byte and part counts and emits {@link ProgressEvent}s to a listener.
 *
@@ -19,31 +18,91 @@ var ProgressTracker = class {
 	partsCompleted = 0;
 	/** Timestamp when tracking began. */
 	startTime;
+	/** Minimum milliseconds between byte-only emissions. */
+	minIntervalMs;
+	/** Timestamp of the most recent emitted snapshot. */
+	lastEmitTime = null;
+	/** Timer scheduled for a coalesced byte-only emission. */
+	pendingEmitTimer;
+	/** Listener error captured from a detached timer callback. */
+	listenerError;
 	/**
 	* Creates a new ProgressTracker.
 	* @param listener - Callback to receive progress events, or undefined to disable.
 	* @param totalBytes - Expected total bytes, or null if unknown.
 	* @param totalParts - Expected total parts, or null if not a multipart transfer.
+	* @param options - Optional emission controls.
 	*/
-	constructor(listener, totalBytes, totalParts) {
+	constructor(listener, totalBytes, totalParts, options = {}) {
 		this.listener = listener;
 		this.totalBytes = totalBytes;
 		this.totalParts = totalParts;
 		this.startTime = Date.now();
+		this.minIntervalMs = Math.max(0, options.minIntervalMs ?? 100);
 	}
 	/**
-	* Record that additional bytes have been transferred and notify the listener.
+	* Record that additional bytes have been transferred and schedule listener notification.
 	* @param count - The number of additional bytes that were transferred.
 	*/
 	addBytes(count) {
+		this.throwPendingListenerError();
 		this.bytesTransferred += count;
-		this.emit();
+		this.emitThrottled();
 	}
 	/** Record that a multipart part has completed and notify the listener. */
 	completePart() {
+		this.throwPendingListenerError();
+		this.flushPendingEmit();
 		this.partsCompleted++;
+		this.emitNow();
+	}
+	/** Cancel any pending coalesced progress emission. */
+	dispose() {
+		this.clearPendingEmit();
+		this.listenerError = void 0;
+	}
+	emitThrottled() {
+		if (this.listener === void 0) return;
+		if (this.minIntervalMs === 0) {
+			this.emitNow();
+			return;
+		}
+		const now = Date.now();
+		if (this.lastEmitTime === null || now - this.lastEmitTime >= this.minIntervalMs) {
+			this.emitNow(now);
+			return;
+		}
+		if (this.pendingEmitTimer !== void 0) return;
+		const delay = Math.max(0, this.minIntervalMs - (now - this.lastEmitTime));
+		this.pendingEmitTimer = setTimeout(() => {
+			this.pendingEmitTimer = void 0;
+			try {
+				this.emitNow();
+			} catch (err) {
+				this.listenerError = err;
+			}
+		}, delay);
+		this.pendingEmitTimer.unref?.();
+	}
+	flushPendingEmit() {
+		if (this.pendingEmitTimer !== void 0) this.emitNow();
+	}
+	clearPendingEmit() {
+		if (this.pendingEmitTimer === void 0) return;
+		clearTimeout(this.pendingEmitTimer);
+		this.pendingEmitTimer = void 0;
+	}
+	emitNow(now = Date.now()) {
+		this.clearPendingEmit();
+		this.lastEmitTime = now;
 		this.emit();
 	}
+	throwPendingListenerError() {
+		if (this.listenerError === void 0) return;
+		const err = this.listenerError;
+		this.listenerError = void 0;
+		throw err;
+	}
 	/** Emit the current progress snapshot to the listener, if one is registered. */
 	emit() {
 		this.listener?.({

package/dist/streams/progress.js.map

@@ -1 +1 @@
-{"version":3,"file":"progress.js","names":[],"sources":["../../src/streams/progress.ts"],"sourcesContent":["/** Snapshot of upload or download progress at a point in time. */\nexport interface ProgressEvent {\n  /** Number of bytes transferred so far. */\n  readonly bytesTransferred: number\n  /** Total bytes expected, or null if unknown. */\n  readonly totalBytes: number | null\n  /** Number of multipart parts completed so far. */\n  readonly partsCompleted: number\n  /** Total number of parts expected, or null if unknown. */\n  readonly totalParts: number | null\n  /** Milliseconds elapsed since the operation started. */\n  readonly elapsedMs: number\n}\n\n/** Callback invoked each time transfer progress changes. */\nexport type ProgressListener = (event: ProgressEvent) => void\n\n/**\n * Accumulates byte and part counts and emits {@link ProgressEvent}s to a listener.\n *\n * Internal building block. The SDK wires one of these inside every\n * transfer that accepts an `onProgress` option; users supply the\n * listener callback, not the tracker. Exported only so SDK source\n * modules can import it; not re-exported through any subpath.\n *\n * @internal\n */\nexport class ProgressTracker {\n  /** Running total of bytes transferred. */\n  private bytesTransferred = 0\n  /** Running count of completed parts. */\n  private partsCompleted = 0\n  /** Timestamp when tracking began. */\n  private readonly startTime: number\n\n  /**\n   * Creates a new ProgressTracker.\n   * @param listener - Callback to receive progress events, or undefined to disable.\n   * @param totalBytes - Expected total bytes, or null if unknown.\n   * @param totalParts - Expected total parts, or null if not a multipart transfer.\n   */\n  constructor(\n    private readonly listener: ProgressListener | undefined,\n    private readonly totalBytes: number | null,\n    private readonly totalParts: number | null,\n  ) {\n    this.startTime = Date.now()\n  }\n\n  /**\n   * Record that additional bytes have been transferred and notify the listener.\n   * @param count - The number of additional bytes that were transferred.\n   */\n  addBytes(count: number): void {\n    this.bytesTransferred += count\n    this.emit()\n  }\n\n  /** Record that a multipart part has completed and notify the listener. */\n  completePart(): void {\n    this.partsCompleted++\n    this.emit()\n  }\n\n  /** Emit the current progress snapshot to the listener, if one is registered. */\n  private emit(): void {\n    this.listener?.({\n      bytesTransferred: this.bytesTransferred,\n      totalBytes: this.totalBytes,\n      partsCompleted: this.partsCompleted,\n      totalParts: this.totalParts,\n      elapsedMs: Date.now() - this.startTime,\n    })\n  }\n}\n"],"mappings":";;;;;;;;;;;AA2BA,IAAa,kBAAb,MAA6B;CAeR;CACA;CACA;;CAfnB,mBAA2B;;CAE3B,iBAAyB;;CAEzB;;;;;;;CAQA,YACE,UACA,YACA,YACA;EAHiB,KAAA,WAAA;EACA,KAAA,aAAA;EACA,KAAA,aAAA;EAEjB,KAAK,YAAY,KAAK,IAAI;CAC5B;;;;;CAMA,SAAS,OAAqB;EAC5B,KAAK,oBAAoB;EACzB,KAAK,KAAK;CACZ;;CAGA,eAAqB;EACnB,KAAK;EACL,KAAK,KAAK;CACZ;;CAGA,OAAqB;EACnB,KAAK,WAAW;GACd,kBAAkB,KAAK;GACvB,YAAY,KAAK;GACjB,gBAAgB,KAAK;GACrB,YAAY,KAAK;GACjB,WAAW,KAAK,IAAI,IAAI,KAAK;EAC/B,CAAC;CACH;AACF"}
+{"version":3,"file":"progress.js","names":[],"sources":["../../src/streams/progress.ts"],"sourcesContent":["/** Snapshot of upload or download progress at a point in time. */\nexport interface ProgressEvent {\n  /** Number of bytes transferred so far. */\n  readonly bytesTransferred: number\n  /** Total bytes expected, or null if unknown. */\n  readonly totalBytes: number | null\n  /** Number of multipart parts completed so far. */\n  readonly partsCompleted: number\n  /** Total number of parts expected, or null if unknown. */\n  readonly totalParts: number | null\n  /** Milliseconds elapsed since the operation started. */\n  readonly elapsedMs: number\n}\n\n/** Callback invoked each time transfer progress changes. */\nexport type ProgressListener = (event: ProgressEvent) => void\n\n/** Default minimum time between byte-progress emissions. */\nexport const DEFAULT_PROGRESS_EMIT_INTERVAL_MS = 100\n\n/** Internal controls for ProgressTracker emission behavior. */\nexport interface ProgressTrackerOptions {\n  /**\n   * Minimum milliseconds between byte-only progress emissions.\n   * Set to 0 to emit every change.\n   */\n  readonly minIntervalMs?: number\n}\n\n/**\n * Accumulates byte and part counts and emits {@link ProgressEvent}s to a listener.\n *\n * Internal building block. The SDK wires one of these inside every\n * transfer that accepts an `onProgress` option; users supply the\n * listener callback, not the tracker. Exported only so SDK source\n * modules can import it; not re-exported through any subpath.\n *\n * @internal\n */\nexport class ProgressTracker {\n  /** Running total of bytes transferred. */\n  private bytesTransferred = 0\n  /** Running count of completed parts. */\n  private partsCompleted = 0\n  /** Timestamp when tracking began. */\n  private readonly startTime: number\n  /** Minimum milliseconds between byte-only emissions. */\n  private readonly minIntervalMs: number\n  /** Timestamp of the most recent emitted snapshot. */\n  private lastEmitTime: number | null = null\n  /** Timer scheduled for a coalesced byte-only emission. */\n  private pendingEmitTimer: ReturnType<typeof setTimeout> | undefined\n  /** Listener error captured from a detached timer callback. */\n  private listenerError: unknown\n\n  /**\n   * Creates a new ProgressTracker.\n   * @param listener - Callback to receive progress events, or undefined to disable.\n   * @param totalBytes - Expected total bytes, or null if unknown.\n   * @param totalParts - Expected total parts, or null if not a multipart transfer.\n   * @param options - Optional emission controls.\n   */\n  constructor(\n    private readonly listener: ProgressListener | undefined,\n    private readonly totalBytes: number | null,\n    private readonly totalParts: number | null,\n    options: ProgressTrackerOptions = {},\n  ) {\n    this.startTime = Date.now()\n    this.minIntervalMs = Math.max(0, options.minIntervalMs ?? DEFAULT_PROGRESS_EMIT_INTERVAL_MS)\n  }\n\n  /**\n   * Record that additional bytes have been transferred and schedule listener notification.\n   * @param count - The number of additional bytes that were transferred.\n   */\n  addBytes(count: number): void {\n    this.throwPendingListenerError()\n    this.bytesTransferred += count\n    this.emitThrottled()\n  }\n\n  /** Record that a multipart part has completed and notify the listener. */\n  completePart(): void {\n    this.throwPendingListenerError()\n    this.flushPendingEmit()\n    this.partsCompleted++\n    this.emitNow()\n  }\n\n  /** Cancel any pending coalesced progress emission. */\n  dispose(): void {\n    this.clearPendingEmit()\n    this.listenerError = undefined\n  }\n\n  private emitThrottled(): void {\n    if (this.listener === undefined) return\n    if (this.minIntervalMs === 0) {\n      this.emitNow()\n      return\n    }\n\n    const now = Date.now()\n    if (this.lastEmitTime === null || now - this.lastEmitTime >= this.minIntervalMs) {\n      this.emitNow(now)\n      return\n    }\n\n    if (this.pendingEmitTimer !== undefined) return\n\n    const delay = Math.max(0, this.minIntervalMs - (now - this.lastEmitTime))\n    this.pendingEmitTimer = setTimeout(() => {\n      this.pendingEmitTimer = undefined\n      try {\n        this.emitNow()\n      } catch (err) {\n        this.listenerError = err\n      }\n    }, delay)\n    ;(this.pendingEmitTimer as { unref?: () => void }).unref?.()\n  }\n\n  private flushPendingEmit(): void {\n    if (this.pendingEmitTimer !== undefined) {\n      this.emitNow()\n    }\n  }\n\n  private clearPendingEmit(): void {\n    if (this.pendingEmitTimer === undefined) return\n    clearTimeout(this.pendingEmitTimer)\n    this.pendingEmitTimer = undefined\n  }\n\n  private emitNow(now = Date.now()): void {\n    this.clearPendingEmit()\n    this.lastEmitTime = now\n    this.emit()\n  }\n\n  private throwPendingListenerError(): void {\n    if (this.listenerError === undefined) return\n    const err = this.listenerError\n    this.listenerError = undefined\n    throw err\n  }\n\n  /** Emit the current progress snapshot to the listener, if one is registered. */\n  private emit(): void {\n    this.listener?.({\n      bytesTransferred: this.bytesTransferred,\n      totalBytes: this.totalBytes,\n      partsCompleted: this.partsCompleted,\n      totalParts: this.totalParts,\n      elapsedMs: Date.now() - this.startTime,\n    })\n  }\n}\n"],"mappings":";;;;;;;;;;AAuCA,IAAa,kBAAb,MAA6B;CAwBR;CACA;CACA;;CAxBnB,mBAA2B;;CAE3B,iBAAyB;;CAEzB;;CAEA;;CAEA,eAAsC;;CAEtC;;CAEA;;;;;;;;CASA,YACE,UACA,YACA,YACA,UAAkC,CAAC,GACnC;EAJiB,KAAA,WAAA;EACA,KAAA,aAAA;EACA,KAAA,aAAA;EAGjB,KAAK,YAAY,KAAK,IAAI;EAC1B,KAAK,gBAAgB,KAAK,IAAI,GAAG,QAAQ,iBAAA,GAAkD;CAC7F;;;;;CAMA,SAAS,OAAqB;EAC5B,KAAK,0BAA0B;EAC/B,KAAK,oBAAoB;EACzB,KAAK,cAAc;CACrB;;CAGA,eAAqB;EACnB,KAAK,0BAA0B;EAC/B,KAAK,iBAAiB;EACtB,KAAK;EACL,KAAK,QAAQ;CACf;;CAGA,UAAgB;EACd,KAAK,iBAAiB;EACtB,KAAK,gBAAgB,KAAA;CACvB;CAEA,gBAA8B;EAC5B,IAAI,KAAK,aAAa,KAAA,GAAW;EACjC,IAAI,KAAK,kBAAkB,GAAG;GAC5B,KAAK,QAAQ;GACb;EACF;EAEA,MAAM,MAAM,KAAK,IAAI;EACrB,IAAI,KAAK,iBAAiB,QAAQ,MAAM,KAAK,gBAAgB,KAAK,eAAe;GAC/E,KAAK,QAAQ,GAAG;GAChB;EACF;EAEA,IAAI,KAAK,qBAAqB,KAAA,GAAW;EAEzC,MAAM,QAAQ,KAAK,IAAI,GAAG,KAAK,iBAAiB,MAAM,KAAK,aAAa;EACxE,KAAK,mBAAmB,iBAAiB;GACvC,KAAK,mBAAmB,KAAA;GACxB,IAAI;IACF,KAAK,QAAQ;GACf,SAAS,KAAK;IACZ,KAAK,gBAAgB;GACvB;EACF,GAAG,KAAK;EACP,KAAM,iBAA4C,QAAQ;CAC7D;CAEA,mBAAiC;EAC/B,IAAI,KAAK,qBAAqB,KAAA,GAC5B,KAAK,QAAQ;CAEjB;CAEA,mBAAiC;EAC/B,IAAI,KAAK,qBAAqB,KAAA,GAAW;EACzC,aAAa,KAAK,gBAAgB;EAClC,KAAK,mBAAmB,KAAA;CAC1B;CAEA,QAAgB,MAAM,KAAK,IAAI,GAAS;EACtC,KAAK,iBAAiB;EACtB,KAAK,eAAe;EACpB,KAAK,KAAK;CACZ;CAEA,4BAA0C;EACxC,IAAI,KAAK,kBAAkB,KAAA,GAAW;EACtC,MAAM,MAAM,KAAK;EACjB,KAAK,gBAAgB,KAAA;EACrB,MAAM;CACR;;CAGA,OAAqB;EACnB,KAAK,WAAW;GACd,kBAAkB,KAAK;GACvB,YAAY,KAAK;GACjB,gBAAgB,KAAK;GACrB,YAAY,KAAK;GACjB,WAAW,KAAK,IAAI,IAAI,KAAK;EAC/B,CAAC;CACH;AACF"}