@backblaze-labs/b2-sdk 0.1.0

package/dist/upload/stream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream.js","sources":["../../src/upload/stream.ts"],"sourcesContent":["import type { AccountInfo } from '../auth/account-info.ts'\nimport type { RawClient } from '../raw/index.ts'\nimport { IncrementalSha1 } from '../streams/hash.ts'\nimport type { ProgressListener } from '../streams/progress.ts'\nimport { ProgressTracker } from '../streams/progress.ts'\nimport type { EncryptionSetting } from '../types/encryption.ts'\nimport type { FileVersion } from '../types/file.ts'\nimport type { BucketId, LargeFileId } from '../types/ids.ts'\nimport { DEFAULT_CONTENT_TYPE, DEFAULT_TRANSFER_CONCURRENCY } from '../util/defaults.ts'\nimport { toError } from '../util/to-error.ts'\nimport { cancelLargeFileBestEffort } from './cancel.ts'\nimport { Semaphore } from './concurrency.ts'\n\n/** Options for creating a streaming multipart upload sink. */\nexport interface CreateWriteStreamOptions {\n  /** Target bucket for the upload. */\n  readonly bucketId: BucketId\n  /** Destination file name in the bucket. */\n  readonly fileName: string\n  /** MIME type. Defaults to `b2/x-auto`. */\n  readonly contentType?: string\n  /** Custom file info stored with the file. */\n  readonly fileInfo?: Record<string, string>\n  /** Server-side encryption applied to each part. */\n  readonly serverSideEncryption?: EncryptionSetting\n  /**\n   * Target part size in bytes. The stream buffers writes until this many bytes\n   * are accumulated, then ships a part. Must be at least the account's\n   * absolute minimum part size; the implementation will raise it if too small.\n   */\n  readonly partSize?: number\n  /** Maximum number of parts uploaded in parallel. Defaults to 4. */\n  readonly concurrency?: number\n  /** Callback invoked with upload progress events. `totalBytes` is `null` (size unknown). */\n  readonly onProgress?: ProgressListener\n  /** Aborts the upload and cancels the unfinished large file. */\n  readonly signal?: AbortSignal\n}\n\n/**\n * Handle returned by `B2Object.createWriteStream`: the Web `WritableStream` to\n * pipe data into, plus a promise that resolves with the finished\n * {@link FileVersion} once the stream is closed and all parts have been\n * uploaded.\n */\nexport interface UploadWriteHandle {\n  /** Web `WritableStream` sink to pipe data into. */\n  readonly writable: WritableStream<Uint8Array>\n  /** Resolves with the finalized file version when the stream closes successfully. */\n  readonly done: Promise<FileVersion>\n}\n\n/**\n * Creates a {@link WritableStream} that streams data into a B2 multipart upload.\n *\n * Buffers incoming chunks until `partSize` bytes are accumulated, ships each\n * complete part through the standard multipart engine, and finalizes the file\n * once the stream is closed. Honours backpressure via the queue's bounded\n * concurrency. Streaming uploads do not support resume because the total size\n * and per-part hashes aren't known in advance; use {@link uploadLargeFile} with\n * a buffered source when resume is required.\n *\n * @param raw - Low-level B2 API client.\n * @param accountInfo - Authorized account state (tokens, URLs, part URL pool).\n * @param options - Streaming upload parameters.\n *\n * @returns A {@link UploadWriteHandle} with the writable sink and a completion promise.\n */\nexport function createWriteStream(\n  raw: RawClient,\n  accountInfo: AccountInfo,\n  options: CreateWriteStreamOptions,\n): UploadWriteHandle {\n  const minPartSize = accountInfo.getAbsoluteMinimumPartSize()\n  const recommendedPartSize = accountInfo.getRecommendedPartSize()\n  const partSize = Math.max(options.partSize ?? recommendedPartSize, minPartSize)\n  const concurrency = options.concurrency ?? DEFAULT_TRANSFER_CONCURRENCY\n  const tracker = new ProgressTracker(options.onProgress, null, null)\n  const sem = new Semaphore(concurrency)\n\n  let largeFileId: LargeFileId | null = null\n  let startPromise: Promise<LargeFileId> | null = null\n  let nextPartNumber = 1\n  let pendingBytes = 0\n  const pending: Uint8Array[] = []\n  const partSha1s: string[] = []\n  const inflight: Promise<void>[] = []\n  let errored: Error | null = null\n\n  // ES2024 `Promise.withResolvers()` exposes the resolve/reject pair as\n  // properties of the returned object, avoiding the `let resolve!:` /\n  // `let reject!:` non-null-assertion pattern needed before this API\n  // existed. Available in Node 22 (our minimum), Bun, Deno, modern\n  // browsers, and Cloudflare Workers.\n  const {\n    promise: done,\n    resolve: resolveDone,\n    reject: rejectDone,\n  } = Promise.withResolvers<FileVersion>()\n  // Attach a no-op rejection handler so a `done` that rejects before the\n  // caller observes it never surfaces as a process-level unhandled rejection.\n  // The error is not swallowed: `close()`/`abort()` also reject the writable\n  // (so `pipeTo`/`getWriter().close()` throw), and any later `await done` /\n  // `done.then(onRejected)` the caller attaches still sees the rejection —\n  // extra handlers on the same promise all fire. Mirrors the\n  // `task.catch(() => {})` pattern used for inflight part uploads below, and\n  // keeps the engine well-behaved under Bun and Node's strict\n  // unhandled-rejection mode.\n  done.catch(() => {})\n\n  function ensureStarted(): Promise<LargeFileId> {\n    if (largeFileId !== null) return Promise.resolve(largeFileId)\n    if (startPromise !== null) return startPromise\n    startPromise = (async () => {\n      const resp = await raw.startLargeFile(accountInfo.getApiUrl(), accountInfo.getAuthToken(), {\n        bucketId: options.bucketId,\n        fileName: options.fileName,\n        contentType: options.contentType ?? DEFAULT_CONTENT_TYPE,\n        fileInfo: options.fileInfo ?? {},\n        ...(options.serverSideEncryption !== undefined\n          ? { serverSideEncryption: options.serverSideEncryption }\n          : {}),\n      })\n      largeFileId = resp.fileId\n      return largeFileId\n    })()\n    return startPromise\n  }\n\n  async function shipPart(data: Uint8Array, partNumber: number): Promise<void> {\n    const fileId = await ensureStarted()\n\n    const sha1 = new IncrementalSha1()\n    await sha1.update(data)\n    const sha1Hex = await sha1.digest()\n\n    let uploadEntry = accountInfo.checkoutPartUploadUrl(fileId)\n    if (!uploadEntry) {\n      const resp = await raw.getUploadPartUrl(accountInfo.getApiUrl(), accountInfo.getAuthToken(), {\n        fileId,\n      })\n      uploadEntry = { uploadUrl: resp.uploadUrl, authorizationToken: resp.authorizationToken }\n    }\n\n    try {\n      const result = await raw.uploadPart(\n        uploadEntry.uploadUrl,\n        {\n          authorization: uploadEntry.authorizationToken,\n          partNumber,\n          contentLength: data.byteLength,\n          contentSha1: sha1Hex,\n          ...(options.serverSideEncryption !== undefined\n            ? { serverSideEncryption: options.serverSideEncryption }\n            : {}),\n        },\n        data as BodyInit,\n        options.signal,\n      )\n      accountInfo.returnPartUploadUrl(fileId, uploadEntry)\n      partSha1s[partNumber - 1] = result.contentSha1\n      tracker.addBytes(data.byteLength)\n      tracker.completePart()\n    } catch (err) {\n      accountInfo.evictPartUploadUrl(fileId, uploadEntry)\n      throw err\n    }\n  }\n\n  function dispatchPart(): void {\n    if (pending.length === 0) return\n    let data: Uint8Array\n    if (pending.length === 1) {\n      const head = pending[0]\n      if (!head) return\n      data = head\n    } else {\n      const total = pending.reduce((sum, chunk) => sum + chunk.byteLength, 0)\n      data = new Uint8Array(total)\n      let offset = 0\n      for (const chunk of pending) {\n        data.set(chunk, offset)\n        offset += chunk.byteLength\n      }\n    }\n    pending.length = 0\n    pendingBytes = 0\n    const partNumber = nextPartNumber++\n    const task = (async () => {\n      await sem.acquire()\n      try {\n        await shipPart(data, partNumber)\n      } catch (err) {\n        errored = toError(err)\n        throw err\n      } finally {\n        sem.release()\n      }\n    })()\n    inflight.push(task)\n    // Swallow rejection here; we check `errored` later.\n    task.catch(() => {})\n  }\n\n  const writable = new WritableStream<Uint8Array>({\n    async write(chunk: Uint8Array): Promise<void> {\n      if (errored) throw errored\n      options.signal?.throwIfAborted()\n\n      pending.push(chunk)\n      pendingBytes += chunk.byteLength\n      while (pendingBytes >= partSize) {\n        // Pull exactly partSize bytes off the front\n        const carved = carveExact(pending, partSize)\n        const partNumber = nextPartNumber++\n        pendingBytes -= partSize\n        const task = (async () => {\n          await sem.acquire()\n          try {\n            await shipPart(carved, partNumber)\n          } catch (err) {\n            errored = toError(err)\n            throw err\n          } finally {\n            sem.release()\n          }\n        })()\n        inflight.push(task)\n        task.catch(() => {})\n      }\n    },\n\n    async close(): Promise<void> {\n      try {\n        if (errored) throw errored\n        options.signal?.throwIfAborted()\n\n        // Ship any remaining bytes as the last part. If the total fit in one\n        // single buffered batch (no parts shipped yet), we have to use the\n        // multipart path anyway since we already called startLargeFile lazily.\n        if (pendingBytes > 0) {\n          dispatchPart()\n        }\n\n        await Promise.all(inflight)\n        if (errored) throw errored\n\n        if (largeFileId === null) {\n          // Stream closed before any data was written. Start an empty large\n          // file? B2 requires at least 2 parts. Reject — callers shouldn't\n          // close an empty stream.\n          throw new Error('createWriteStream closed without any data written.')\n        }\n\n        const result = await raw.finishLargeFile(\n          accountInfo.getApiUrl(),\n          accountInfo.getAuthToken(),\n          { fileId: largeFileId, partSha1Array: partSha1s },\n        )\n        resolveDone(result)\n      } catch (err) {\n        // Capture into a const so the cancel closure sees a non-null\n        // `fileId`; closures don't observe the outer `!== null` narrowing\n        // because the variable is mutable across the lambda boundary.\n        const fileIdToCancel = largeFileId\n        if (fileIdToCancel !== null) {\n          await cancelLargeFileBestEffort(raw, accountInfo, fileIdToCancel)\n        }\n        rejectDone(err)\n        throw err\n      }\n    },\n\n    async abort(reason: unknown): Promise<void> {\n      const fileIdToCancel = largeFileId\n      if (fileIdToCancel !== null) {\n        await cancelLargeFileBestEffort(raw, accountInfo, fileIdToCancel)\n      }\n      rejectDone(toError(reason))\n    },\n  })\n\n  return { writable, done }\n}\n\n/**\n * Removes exactly `size` bytes from the front of `chunks` (mutates) and returns\n * them as a contiguous Uint8Array. Any trailing remainder of the last chunk\n * stays at the front of `chunks` for the next part.\n *\n * @param chunks - Queue of pending chunks. Modified in place.\n * @param size - Number of bytes to carve off the front.\n *\n * @returns A new Uint8Array containing exactly `size` bytes.\n */\nfunction carveExact(chunks: Uint8Array[], size: number): Uint8Array {\n  const out = new Uint8Array(size)\n  let written = 0\n  while (written < size && chunks.length > 0) {\n    const head = chunks[0]\n    if (!head) break\n    const need = size - written\n    if (head.byteLength <= need) {\n      out.set(head, written)\n      written += head.byteLength\n      chunks.shift()\n    } else {\n      out.set(head.subarray(0, need), written)\n      chunks[0] = head.subarray(need)\n      written += need\n    }\n  }\n  return out\n}\n"],"names":[],"mappings":"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"}

package/dist/util/best-effort.cjs

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+async function bestEffort(fn) {
+  try {
+    await fn();
+  } catch {
+  }
+}
+exports.bestEffort = bestEffort;
+//# sourceMappingURL=best-effort.cjs.map

package/dist/util/best-effort.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"best-effort.cjs","sources":["../../src/util/best-effort.ts"],"sourcesContent":["/**\n * Runs an async cleanup operation and swallows any rejection.\n *\n * Used at error-handling boundaries (e.g. after a multipart upload fails,\n * when trying to `cancelLargeFile` on the orphaned upload). The primary\n * error is what the caller wants to see; a secondary failure during\n * cleanup must not shadow it.\n *\n * Naming the pattern instead of inlining a try/catch with an empty catch\n * makes the intent explicit at the call site: this is best-effort cleanup,\n * not a silent error swallow.\n *\n * @param fn - Cleanup async function. Its return value is ignored; any\n *   thrown error or rejected promise is caught and discarded.\n *\n * @returns A promise that always resolves, regardless of `fn`'s outcome.\n *\n * @example\n * ```ts\n * try {\n *   await uploadParts(...)\n * } catch (err) {\n *   await bestEffort(() =>\n *     raw.cancelLargeFile(apiUrl, authToken, { fileId: largeFileId }),\n *   )\n *   throw err\n * }\n * ```\n */\nexport async function bestEffort(fn: () => Promise<unknown>): Promise<void> {\n  try {\n    await fn()\n  } catch {\n    // Intentional swallow: this helper exists for cleanup paths where a\n    // secondary failure must not shadow the primary error.\n  }\n}\n"],"names":[],"mappings":";;AA6BA,eAAsB,WAAW,IAA2C;AAC1E,MAAI;AACF,UAAM,GAAA;AAAA,EACR,QAAQ;AAAA,EAGR;AACF;;"}

package/dist/util/best-effort.d.cts

@@ -0,0 +1,31 @@
+/**
+ * Runs an async cleanup operation and swallows any rejection.
+ *
+ * Used at error-handling boundaries (e.g. after a multipart upload fails,
+ * when trying to `cancelLargeFile` on the orphaned upload). The primary
+ * error is what the caller wants to see; a secondary failure during
+ * cleanup must not shadow it.
+ *
+ * Naming the pattern instead of inlining a try/catch with an empty catch
+ * makes the intent explicit at the call site: this is best-effort cleanup,
+ * not a silent error swallow.
+ *
+ * @param fn - Cleanup async function. Its return value is ignored; any
+ *   thrown error or rejected promise is caught and discarded.
+ *
+ * @returns A promise that always resolves, regardless of `fn`'s outcome.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await uploadParts(...)
+ * } catch (err) {
+ *   await bestEffort(() =>
+ *     raw.cancelLargeFile(apiUrl, authToken, { fileId: largeFileId }),
+ *   )
+ *   throw err
+ * }
+ * ```
+ */
+export declare function bestEffort(fn: () => Promise<unknown>): Promise<void>;
+//# sourceMappingURL=best-effort.d.ts.map

package/dist/util/best-effort.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"best-effort.d.ts","sourceRoot":"","sources":["../../src/util/best-effort.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAsB,UAAU,CAAC,EAAE,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAO1E"}

package/dist/util/best-effort.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Runs an async cleanup operation and swallows any rejection.
+ *
+ * Used at error-handling boundaries (e.g. after a multipart upload fails,
+ * when trying to `cancelLargeFile` on the orphaned upload). The primary
+ * error is what the caller wants to see; a secondary failure during
+ * cleanup must not shadow it.
+ *
+ * Naming the pattern instead of inlining a try/catch with an empty catch
+ * makes the intent explicit at the call site: this is best-effort cleanup,
+ * not a silent error swallow.
+ *
+ * @param fn - Cleanup async function. Its return value is ignored; any
+ *   thrown error or rejected promise is caught and discarded.
+ *
+ * @returns A promise that always resolves, regardless of `fn`'s outcome.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await uploadParts(...)
+ * } catch (err) {
+ *   await bestEffort(() =>
+ *     raw.cancelLargeFile(apiUrl, authToken, { fileId: largeFileId }),
+ *   )
+ *   throw err
+ * }
+ * ```
+ */
+export declare function bestEffort(fn: () => Promise<unknown>): Promise<void>;
+//# sourceMappingURL=best-effort.d.ts.map

package/dist/util/best-effort.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"best-effort.d.ts","sourceRoot":"","sources":["../../src/util/best-effort.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAsB,UAAU,CAAC,EAAE,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAO1E"}

package/dist/util/best-effort.js

@@ -0,0 +1,10 @@
+async function bestEffort(fn) {
+  try {
+    await fn();
+  } catch {
+  }
+}
+export {
+  bestEffort
+};
+//# sourceMappingURL=best-effort.js.map

package/dist/util/best-effort.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"best-effort.js","sources":["../../src/util/best-effort.ts"],"sourcesContent":["/**\n * Runs an async cleanup operation and swallows any rejection.\n *\n * Used at error-handling boundaries (e.g. after a multipart upload fails,\n * when trying to `cancelLargeFile` on the orphaned upload). The primary\n * error is what the caller wants to see; a secondary failure during\n * cleanup must not shadow it.\n *\n * Naming the pattern instead of inlining a try/catch with an empty catch\n * makes the intent explicit at the call site: this is best-effort cleanup,\n * not a silent error swallow.\n *\n * @param fn - Cleanup async function. Its return value is ignored; any\n *   thrown error or rejected promise is caught and discarded.\n *\n * @returns A promise that always resolves, regardless of `fn`'s outcome.\n *\n * @example\n * ```ts\n * try {\n *   await uploadParts(...)\n * } catch (err) {\n *   await bestEffort(() =>\n *     raw.cancelLargeFile(apiUrl, authToken, { fileId: largeFileId }),\n *   )\n *   throw err\n * }\n * ```\n */\nexport async function bestEffort(fn: () => Promise<unknown>): Promise<void> {\n  try {\n    await fn()\n  } catch {\n    // Intentional swallow: this helper exists for cleanup paths where a\n    // secondary failure must not shadow the primary error.\n  }\n}\n"],"names":[],"mappings":"AA6BA,eAAsB,WAAW,IAA2C;AAC1E,MAAI;AACF,UAAM,GAAA;AAAA,EACR,QAAQ;AAAA,EAGR;AACF;"}

package/dist/util/defaults.cjs

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const DEFAULT_TRANSFER_CONCURRENCY = 4;
+const DEFAULT_BULK_CONCURRENCY = 10;
+const DEFAULT_PAGE_SIZE = 1e3;
+const DEFAULT_CONTENT_TYPE = "b2/x-auto";
+exports.DEFAULT_BULK_CONCURRENCY = DEFAULT_BULK_CONCURRENCY;
+exports.DEFAULT_CONTENT_TYPE = DEFAULT_CONTENT_TYPE;
+exports.DEFAULT_PAGE_SIZE = DEFAULT_PAGE_SIZE;
+exports.DEFAULT_TRANSFER_CONCURRENCY = DEFAULT_TRANSFER_CONCURRENCY;
+//# sourceMappingURL=defaults.cjs.map

package/dist/util/defaults.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"defaults.cjs","sources":["../../src/util/defaults.ts"],"sourcesContent":["/**\n * Shared SDK-wide default values.\n *\n * Centralising defaults here makes the trade-offs visible and prevents the\n * drift that creeps in when each module hard-codes its own magic number.\n *\n * @packageDocumentation\n */\n\n/**\n * Default parallel-task count for **data-transfer** operations: uploads\n * (multipart parts), downloads (byte ranges), server-side copies (parts),\n * and sync (file-by-file). Each in-flight task occupies one transport\n * slot and at least one part-worth of memory, so we keep this\n * conservative.\n *\n * Empirically `4` saturates a typical home / office uplink without\n * starving the event loop or risking B2's per-account upload-URL\n * rate-limit. Callers that have measured their environment can override\n * via the `concurrency` option on every transfer method.\n */\nexport const DEFAULT_TRANSFER_CONCURRENCY = 4\n\n/**\n * Default parallel-task count for **bulk metadata** operations:\n * `Bucket.deleteMany` (per-version delete calls), and the action loop in\n * `synchronize` when it dispatches mixed actions in batches.\n *\n * Higher than the transfer default because each task is a tiny API\n * round-trip (no payload), so concurrency is bound by API latency rather\n * than bandwidth or local memory. `10` keeps a delete-of-thousands\n * snappy without overwhelming a single account's request budget.\n */\nexport const DEFAULT_BULK_CONCURRENCY = 10\n\n/**\n * Default `maxFileCount` for list-style endpoints\n * (`b2_list_file_names`, `b2_list_file_versions`, `b2_list_parts`). B2\n * caps `maxFileCount` at `10000` for these endpoints; the SDK requests\n * `1000` per page so a single network blip doesn't lose 10× the work and\n * so callers see results sooner.\n *\n * `b2_list_unfinished_large_files` is capped at `100` server-side and is\n * not affected by this constant.\n */\nexport const DEFAULT_PAGE_SIZE = 1000\n\n/**\n * Default MIME type for uploads when the caller omits `contentType`.\n * B2 documents `b2/x-auto` as the magic value that asks the service to\n * sniff the file's content and pick a sensible `Content-Type` itself.\n * Centralising the literal here keeps the upload, copy, and create-write\n * paths in sync.\n *\n * @see https://www.backblaze.com/apidocs/b2-upload-file\n */\nexport const DEFAULT_CONTENT_TYPE = 'b2/x-auto'\n"],"names":[],"mappings":";;AAqBO,MAAM,+BAA+B;AAYrC,MAAM,2BAA2B;AAYjC,MAAM,oBAAoB;AAW1B,MAAM,uBAAuB;;;;;"}

package/dist/util/defaults.d.cts

@@ -0,0 +1,54 @@
+/**
+ * Shared SDK-wide default values.
+ *
+ * Centralising defaults here makes the trade-offs visible and prevents the
+ * drift that creeps in when each module hard-codes its own magic number.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Default parallel-task count for **data-transfer** operations: uploads
+ * (multipart parts), downloads (byte ranges), server-side copies (parts),
+ * and sync (file-by-file). Each in-flight task occupies one transport
+ * slot and at least one part-worth of memory, so we keep this
+ * conservative.
+ *
+ * Empirically `4` saturates a typical home / office uplink without
+ * starving the event loop or risking B2's per-account upload-URL
+ * rate-limit. Callers that have measured their environment can override
+ * via the `concurrency` option on every transfer method.
+ */
+export declare const DEFAULT_TRANSFER_CONCURRENCY = 4;
+/**
+ * Default parallel-task count for **bulk metadata** operations:
+ * `Bucket.deleteMany` (per-version delete calls), and the action loop in
+ * `synchronize` when it dispatches mixed actions in batches.
+ *
+ * Higher than the transfer default because each task is a tiny API
+ * round-trip (no payload), so concurrency is bound by API latency rather
+ * than bandwidth or local memory. `10` keeps a delete-of-thousands
+ * snappy without overwhelming a single account's request budget.
+ */
+export declare const DEFAULT_BULK_CONCURRENCY = 10;
+/**
+ * Default `maxFileCount` for list-style endpoints
+ * (`b2_list_file_names`, `b2_list_file_versions`, `b2_list_parts`). B2
+ * caps `maxFileCount` at `10000` for these endpoints; the SDK requests
+ * `1000` per page so a single network blip doesn't lose 10× the work and
+ * so callers see results sooner.
+ *
+ * `b2_list_unfinished_large_files` is capped at `100` server-side and is
+ * not affected by this constant.
+ */
+export declare const DEFAULT_PAGE_SIZE = 1000;
+/**
+ * Default MIME type for uploads when the caller omits `contentType`.
+ * B2 documents `b2/x-auto` as the magic value that asks the service to
+ * sniff the file's content and pick a sensible `Content-Type` itself.
+ * Centralising the literal here keeps the upload, copy, and create-write
+ * paths in sync.
+ *
+ * @see https://www.backblaze.com/apidocs/b2-upload-file
+ */
+export declare const DEFAULT_CONTENT_TYPE = "b2/x-auto";
+//# sourceMappingURL=defaults.d.ts.map

package/dist/util/defaults.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"defaults.d.ts","sourceRoot":"","sources":["../../src/util/defaults.js"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,4BAA4B,IAAI,CAAA;AAE7C;;;;;;;;;GASG;AACH,eAAO,MAAM,wBAAwB,KAAK,CAAA;AAE1C;;;;;;;;;GASG;AACH,eAAO,MAAM,iBAAiB,OAAO,CAAA;AAErC;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,cAAc,CAAA"}

package/dist/util/defaults.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Shared SDK-wide default values.
+ *
+ * Centralising defaults here makes the trade-offs visible and prevents the
+ * drift that creeps in when each module hard-codes its own magic number.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Default parallel-task count for **data-transfer** operations: uploads
+ * (multipart parts), downloads (byte ranges), server-side copies (parts),
+ * and sync (file-by-file). Each in-flight task occupies one transport
+ * slot and at least one part-worth of memory, so we keep this
+ * conservative.
+ *
+ * Empirically `4` saturates a typical home / office uplink without
+ * starving the event loop or risking B2's per-account upload-URL
+ * rate-limit. Callers that have measured their environment can override
+ * via the `concurrency` option on every transfer method.
+ */
+export declare const DEFAULT_TRANSFER_CONCURRENCY = 4;
+/**
+ * Default parallel-task count for **bulk metadata** operations:
+ * `Bucket.deleteMany` (per-version delete calls), and the action loop in
+ * `synchronize` when it dispatches mixed actions in batches.
+ *
+ * Higher than the transfer default because each task is a tiny API
+ * round-trip (no payload), so concurrency is bound by API latency rather
+ * than bandwidth or local memory. `10` keeps a delete-of-thousands
+ * snappy without overwhelming a single account's request budget.
+ */
+export declare const DEFAULT_BULK_CONCURRENCY = 10;
+/**
+ * Default `maxFileCount` for list-style endpoints
+ * (`b2_list_file_names`, `b2_list_file_versions`, `b2_list_parts`). B2
+ * caps `maxFileCount` at `10000` for these endpoints; the SDK requests
+ * `1000` per page so a single network blip doesn't lose 10× the work and
+ * so callers see results sooner.
+ *
+ * `b2_list_unfinished_large_files` is capped at `100` server-side and is
+ * not affected by this constant.
+ */
+export declare const DEFAULT_PAGE_SIZE = 1000;
+/**
+ * Default MIME type for uploads when the caller omits `contentType`.
+ * B2 documents `b2/x-auto` as the magic value that asks the service to
+ * sniff the file's content and pick a sensible `Content-Type` itself.
+ * Centralising the literal here keeps the upload, copy, and create-write
+ * paths in sync.
+ *
+ * @see https://www.backblaze.com/apidocs/b2-upload-file
+ */
+export declare const DEFAULT_CONTENT_TYPE = "b2/x-auto";
+//# sourceMappingURL=defaults.d.ts.map

package/dist/util/defaults.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"defaults.d.ts","sourceRoot":"","sources":["../../src/util/defaults.js"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,4BAA4B,IAAI,CAAA;AAE7C;;;;;;;;;GASG;AACH,eAAO,MAAM,wBAAwB,KAAK,CAAA;AAE1C;;;;;;;;;GASG;AACH,eAAO,MAAM,iBAAiB,OAAO,CAAA;AAErC;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,cAAc,CAAA"}

package/dist/util/defaults.js

@@ -0,0 +1,11 @@
+const DEFAULT_TRANSFER_CONCURRENCY = 4;
+const DEFAULT_BULK_CONCURRENCY = 10;
+const DEFAULT_PAGE_SIZE = 1e3;
+const DEFAULT_CONTENT_TYPE = "b2/x-auto";
+export {
+  DEFAULT_BULK_CONCURRENCY,
+  DEFAULT_CONTENT_TYPE,
+  DEFAULT_PAGE_SIZE,
+  DEFAULT_TRANSFER_CONCURRENCY
+};
+//# sourceMappingURL=defaults.js.map

package/dist/util/defaults.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"defaults.js","sources":["../../src/util/defaults.ts"],"sourcesContent":["/**\n * Shared SDK-wide default values.\n *\n * Centralising defaults here makes the trade-offs visible and prevents the\n * drift that creeps in when each module hard-codes its own magic number.\n *\n * @packageDocumentation\n */\n\n/**\n * Default parallel-task count for **data-transfer** operations: uploads\n * (multipart parts), downloads (byte ranges), server-side copies (parts),\n * and sync (file-by-file). Each in-flight task occupies one transport\n * slot and at least one part-worth of memory, so we keep this\n * conservative.\n *\n * Empirically `4` saturates a typical home / office uplink without\n * starving the event loop or risking B2's per-account upload-URL\n * rate-limit. Callers that have measured their environment can override\n * via the `concurrency` option on every transfer method.\n */\nexport const DEFAULT_TRANSFER_CONCURRENCY = 4\n\n/**\n * Default parallel-task count for **bulk metadata** operations:\n * `Bucket.deleteMany` (per-version delete calls), and the action loop in\n * `synchronize` when it dispatches mixed actions in batches.\n *\n * Higher than the transfer default because each task is a tiny API\n * round-trip (no payload), so concurrency is bound by API latency rather\n * than bandwidth or local memory. `10` keeps a delete-of-thousands\n * snappy without overwhelming a single account's request budget.\n */\nexport const DEFAULT_BULK_CONCURRENCY = 10\n\n/**\n * Default `maxFileCount` for list-style endpoints\n * (`b2_list_file_names`, `b2_list_file_versions`, `b2_list_parts`). B2\n * caps `maxFileCount` at `10000` for these endpoints; the SDK requests\n * `1000` per page so a single network blip doesn't lose 10× the work and\n * so callers see results sooner.\n *\n * `b2_list_unfinished_large_files` is capped at `100` server-side and is\n * not affected by this constant.\n */\nexport const DEFAULT_PAGE_SIZE = 1000\n\n/**\n * Default MIME type for uploads when the caller omits `contentType`.\n * B2 documents `b2/x-auto` as the magic value that asks the service to\n * sniff the file's content and pick a sensible `Content-Type` itself.\n * Centralising the literal here keeps the upload, copy, and create-write\n * paths in sync.\n *\n * @see https://www.backblaze.com/apidocs/b2-upload-file\n */\nexport const DEFAULT_CONTENT_TYPE = 'b2/x-auto'\n"],"names":[],"mappings":"AAqBO,MAAM,+BAA+B;AAYrC,MAAM,2BAA2B;AAYjC,MAAM,oBAAoB;AAW1B,MAAM,uBAAuB;"}

package/dist/util/normalize.cjs

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+function normalizeSha1(raw) {
+  if (raw === null || raw === void 0 || raw === "none") return null;
+  return raw;
+}
+function normalizeFileVersionSha1(fv) {
+  return fv.contentSha1 === "none" ? { ...fv, contentSha1: null } : fv;
+}
+function normalizeFileVersionListSha1(resp) {
+  return { ...resp, files: resp.files.map(normalizeFileVersionSha1) };
+}
+exports.normalizeFileVersionListSha1 = normalizeFileVersionListSha1;
+exports.normalizeFileVersionSha1 = normalizeFileVersionSha1;
+exports.normalizeSha1 = normalizeSha1;
+//# sourceMappingURL=normalize.cjs.map

package/dist/util/normalize.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize.cjs","sources":["../../src/util/normalize.ts"],"sourcesContent":["/**\n * Wire-shape → SDK-shape normalization helpers.\n *\n * B2 occasionally uses sentinel strings on the wire where a missing\n * value would be more idiomatic in TypeScript. The biggest offender is\n * `contentSha1: 'none'` on files completed via `b2_finish_large_file`\n * (multipart-finished files don't have a whole-file SHA-1; B2 sends the\n * literal three-letter string). The SDK's `FileVersion.contentSha1` is\n * typed `string | null` to signal that absence — this module collapses\n * the wire sentinel to `null` so callers can write\n * `if (fv.contentSha1) { ... }` without an extra `=== 'none'` guard.\n *\n * Normalization happens at the RawClient boundary so every SDK consumer\n * (RawClient direct users, the high-level facade, the simulator-driven\n * tests, generated docs) sees the same `null` value.\n *\n * @packageDocumentation\n */\n\n/**\n * Collapses the B2 wire sentinel `'none'` (and `undefined`) to `null` for\n * SHA-1-shaped fields. Any other string passes through unchanged.\n *\n * @param raw - SHA-1 string from the wire, or `null`/`undefined`.\n *\n * @returns A hex SHA-1 string, or `null` when the wire said \"no hash\".\n */\nexport function normalizeSha1(raw: string | null | undefined): string | null {\n  if (raw === null || raw === undefined || raw === 'none') return null\n  return raw\n}\n\n/**\n * Returns a new file-version-shaped object with the `contentSha1: 'none'`\n * sentinel collapsed to `null`. Pass-through when the value is already\n * `null` or a real hash. The object reference is preserved if no\n * substitution was needed, so callers paying for change detection\n * (e.g. React memo) see referential stability.\n *\n * @typeParam T - Any object with a `contentSha1: string | null` field.\n *\n * @param fv - The wire-shape file-version object.\n *\n * @returns Either `fv` unchanged or a shallow copy with `contentSha1: null`.\n */\nexport function normalizeFileVersionSha1<T extends { readonly contentSha1: string | null }>(\n  fv: T,\n): T {\n  return fv.contentSha1 === 'none' ? { ...fv, contentSha1: null } : fv\n}\n\n/**\n * Returns a new list-response object with `normalizeFileVersionSha1`\n * applied to every entry in `files`. Used at the `b2_list_file_names` /\n * `b2_list_file_versions` boundary so list output shares the same\n * SHA-1 semantics as the singular endpoints.\n *\n * @typeParam F - Any object with a `contentSha1: string | null` field.\n * @typeParam R - The list-response shape (must have a `files` array of `F`).\n *\n * @param resp - The wire-shape list response.\n *\n * @returns A response with normalized `files`. `resp.files` is a new array.\n */\nexport function normalizeFileVersionListSha1<\n  F extends { readonly contentSha1: string | null },\n  R extends { readonly files: readonly F[] },\n>(resp: R): R {\n  return { ...resp, files: resp.files.map(normalizeFileVersionSha1) }\n}\n"],"names":[],"mappings":";;AA2BO,SAAS,cAAc,KAA+C;AAC3E,MAAI,QAAQ,QAAQ,QAAQ,UAAa,QAAQ,OAAQ,QAAO;AAChE,SAAO;AACT;AAeO,SAAS,yBACd,IACG;AACH,SAAO,GAAG,gBAAgB,SAAS,EAAE,GAAG,IAAI,aAAa,SAAS;AACpE;AAeO,SAAS,6BAGd,MAAY;AACZ,SAAO,EAAE,GAAG,MAAM,OAAO,KAAK,MAAM,IAAI,wBAAwB,EAAA;AAClE;;;;"}

package/dist/util/normalize.d.cts

@@ -0,0 +1,62 @@
+/**
+ * Wire-shape → SDK-shape normalization helpers.
+ *
+ * B2 occasionally uses sentinel strings on the wire where a missing
+ * value would be more idiomatic in TypeScript. The biggest offender is
+ * `contentSha1: 'none'` on files completed via `b2_finish_large_file`
+ * (multipart-finished files don't have a whole-file SHA-1; B2 sends the
+ * literal three-letter string). The SDK's `FileVersion.contentSha1` is
+ * typed `string | null` to signal that absence — this module collapses
+ * the wire sentinel to `null` so callers can write
+ * `if (fv.contentSha1) { ... }` without an extra `=== 'none'` guard.
+ *
+ * Normalization happens at the RawClient boundary so every SDK consumer
+ * (RawClient direct users, the high-level facade, the simulator-driven
+ * tests, generated docs) sees the same `null` value.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Collapses the B2 wire sentinel `'none'` (and `undefined`) to `null` for
+ * SHA-1-shaped fields. Any other string passes through unchanged.
+ *
+ * @param raw - SHA-1 string from the wire, or `null`/`undefined`.
+ *
+ * @returns A hex SHA-1 string, or `null` when the wire said "no hash".
+ */
+export declare function normalizeSha1(raw: string | null | undefined): string | null;
+/**
+ * Returns a new file-version-shaped object with the `contentSha1: 'none'`
+ * sentinel collapsed to `null`. Pass-through when the value is already
+ * `null` or a real hash. The object reference is preserved if no
+ * substitution was needed, so callers paying for change detection
+ * (e.g. React memo) see referential stability.
+ *
+ * @typeParam T - Any object with a `contentSha1: string | null` field.
+ *
+ * @param fv - The wire-shape file-version object.
+ *
+ * @returns Either `fv` unchanged or a shallow copy with `contentSha1: null`.
+ */
+export declare function normalizeFileVersionSha1<T extends {
+    readonly contentSha1: string | null;
+}>(fv: T): T;
+/**
+ * Returns a new list-response object with `normalizeFileVersionSha1`
+ * applied to every entry in `files`. Used at the `b2_list_file_names` /
+ * `b2_list_file_versions` boundary so list output shares the same
+ * SHA-1 semantics as the singular endpoints.
+ *
+ * @typeParam F - Any object with a `contentSha1: string | null` field.
+ * @typeParam R - The list-response shape (must have a `files` array of `F`).
+ *
+ * @param resp - The wire-shape list response.
+ *
+ * @returns A response with normalized `files`. `resp.files` is a new array.
+ */
+export declare function normalizeFileVersionListSha1<F extends {
+    readonly contentSha1: string | null;
+}, R extends {
+    readonly files: readonly F[];
+}>(resp: R): R;
+//# sourceMappingURL=normalize.d.ts.map

package/dist/util/normalize.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize.d.ts","sourceRoot":"","sources":["../../src/util/normalize.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAG3E;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,wBAAwB,CAAC,CAAC,SAAS;IAAE,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,EACxF,EAAE,EAAE,CAAC,GACJ,CAAC,CAEH;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,4BAA4B,CAC1C,CAAC,SAAS;IAAE,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,EACjD,CAAC,SAAS;IAAE,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC,EAAE,CAAA;CAAE,EAC1C,IAAI,EAAE,CAAC,GAAG,CAAC,CAEZ"}

package/dist/util/normalize.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Wire-shape → SDK-shape normalization helpers.
+ *
+ * B2 occasionally uses sentinel strings on the wire where a missing
+ * value would be more idiomatic in TypeScript. The biggest offender is
+ * `contentSha1: 'none'` on files completed via `b2_finish_large_file`
+ * (multipart-finished files don't have a whole-file SHA-1; B2 sends the
+ * literal three-letter string). The SDK's `FileVersion.contentSha1` is
+ * typed `string | null` to signal that absence — this module collapses
+ * the wire sentinel to `null` so callers can write
+ * `if (fv.contentSha1) { ... }` without an extra `=== 'none'` guard.
+ *
+ * Normalization happens at the RawClient boundary so every SDK consumer
+ * (RawClient direct users, the high-level facade, the simulator-driven
+ * tests, generated docs) sees the same `null` value.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Collapses the B2 wire sentinel `'none'` (and `undefined`) to `null` for
+ * SHA-1-shaped fields. Any other string passes through unchanged.
+ *
+ * @param raw - SHA-1 string from the wire, or `null`/`undefined`.
+ *
+ * @returns A hex SHA-1 string, or `null` when the wire said "no hash".
+ */
+export declare function normalizeSha1(raw: string | null | undefined): string | null;
+/**
+ * Returns a new file-version-shaped object with the `contentSha1: 'none'`
+ * sentinel collapsed to `null`. Pass-through when the value is already
+ * `null` or a real hash. The object reference is preserved if no
+ * substitution was needed, so callers paying for change detection
+ * (e.g. React memo) see referential stability.
+ *
+ * @typeParam T - Any object with a `contentSha1: string | null` field.
+ *
+ * @param fv - The wire-shape file-version object.
+ *
+ * @returns Either `fv` unchanged or a shallow copy with `contentSha1: null`.
+ */
+export declare function normalizeFileVersionSha1<T extends {
+    readonly contentSha1: string | null;
+}>(fv: T): T;
+/**
+ * Returns a new list-response object with `normalizeFileVersionSha1`
+ * applied to every entry in `files`. Used at the `b2_list_file_names` /
+ * `b2_list_file_versions` boundary so list output shares the same
+ * SHA-1 semantics as the singular endpoints.
+ *
+ * @typeParam F - Any object with a `contentSha1: string | null` field.
+ * @typeParam R - The list-response shape (must have a `files` array of `F`).
+ *
+ * @param resp - The wire-shape list response.
+ *
+ * @returns A response with normalized `files`. `resp.files` is a new array.
+ */
+export declare function normalizeFileVersionListSha1<F extends {
+    readonly contentSha1: string | null;
+}, R extends {
+    readonly files: readonly F[];
+}>(resp: R): R;
+//# sourceMappingURL=normalize.d.ts.map

package/dist/util/normalize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize.d.ts","sourceRoot":"","sources":["../../src/util/normalize.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAG3E;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,wBAAwB,CAAC,CAAC,SAAS;IAAE,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,EACxF,EAAE,EAAE,CAAC,GACJ,CAAC,CAEH;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,4BAA4B,CAC1C,CAAC,SAAS;IAAE,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,EACjD,CAAC,SAAS;IAAE,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC,EAAE,CAAA;CAAE,EAC1C,IAAI,EAAE,CAAC,GAAG,CAAC,CAEZ"}

package/dist/util/normalize.js

@@ -0,0 +1,16 @@
+function normalizeSha1(raw) {
+  if (raw === null || raw === void 0 || raw === "none") return null;
+  return raw;
+}
+function normalizeFileVersionSha1(fv) {
+  return fv.contentSha1 === "none" ? { ...fv, contentSha1: null } : fv;
+}
+function normalizeFileVersionListSha1(resp) {
+  return { ...resp, files: resp.files.map(normalizeFileVersionSha1) };
+}
+export {
+  normalizeFileVersionListSha1,
+  normalizeFileVersionSha1,
+  normalizeSha1
+};
+//# sourceMappingURL=normalize.js.map

package/dist/util/normalize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize.js","sources":["../../src/util/normalize.ts"],"sourcesContent":["/**\n * Wire-shape → SDK-shape normalization helpers.\n *\n * B2 occasionally uses sentinel strings on the wire where a missing\n * value would be more idiomatic in TypeScript. The biggest offender is\n * `contentSha1: 'none'` on files completed via `b2_finish_large_file`\n * (multipart-finished files don't have a whole-file SHA-1; B2 sends the\n * literal three-letter string). The SDK's `FileVersion.contentSha1` is\n * typed `string | null` to signal that absence — this module collapses\n * the wire sentinel to `null` so callers can write\n * `if (fv.contentSha1) { ... }` without an extra `=== 'none'` guard.\n *\n * Normalization happens at the RawClient boundary so every SDK consumer\n * (RawClient direct users, the high-level facade, the simulator-driven\n * tests, generated docs) sees the same `null` value.\n *\n * @packageDocumentation\n */\n\n/**\n * Collapses the B2 wire sentinel `'none'` (and `undefined`) to `null` for\n * SHA-1-shaped fields. Any other string passes through unchanged.\n *\n * @param raw - SHA-1 string from the wire, or `null`/`undefined`.\n *\n * @returns A hex SHA-1 string, or `null` when the wire said \"no hash\".\n */\nexport function normalizeSha1(raw: string | null | undefined): string | null {\n  if (raw === null || raw === undefined || raw === 'none') return null\n  return raw\n}\n\n/**\n * Returns a new file-version-shaped object with the `contentSha1: 'none'`\n * sentinel collapsed to `null`. Pass-through when the value is already\n * `null` or a real hash. The object reference is preserved if no\n * substitution was needed, so callers paying for change detection\n * (e.g. React memo) see referential stability.\n *\n * @typeParam T - Any object with a `contentSha1: string | null` field.\n *\n * @param fv - The wire-shape file-version object.\n *\n * @returns Either `fv` unchanged or a shallow copy with `contentSha1: null`.\n */\nexport function normalizeFileVersionSha1<T extends { readonly contentSha1: string | null }>(\n  fv: T,\n): T {\n  return fv.contentSha1 === 'none' ? { ...fv, contentSha1: null } : fv\n}\n\n/**\n * Returns a new list-response object with `normalizeFileVersionSha1`\n * applied to every entry in `files`. Used at the `b2_list_file_names` /\n * `b2_list_file_versions` boundary so list output shares the same\n * SHA-1 semantics as the singular endpoints.\n *\n * @typeParam F - Any object with a `contentSha1: string | null` field.\n * @typeParam R - The list-response shape (must have a `files` array of `F`).\n *\n * @param resp - The wire-shape list response.\n *\n * @returns A response with normalized `files`. `resp.files` is a new array.\n */\nexport function normalizeFileVersionListSha1<\n  F extends { readonly contentSha1: string | null },\n  R extends { readonly files: readonly F[] },\n>(resp: R): R {\n  return { ...resp, files: resp.files.map(normalizeFileVersionSha1) }\n}\n"],"names":[],"mappings":"AA2BO,SAAS,cAAc,KAA+C;AAC3E,MAAI,QAAQ,QAAQ,QAAQ,UAAa,QAAQ,OAAQ,QAAO;AAChE,SAAO;AACT;AAeO,SAAS,yBACd,IACG;AACH,SAAO,GAAG,gBAAgB,SAAS,EAAE,GAAG,IAAI,aAAa,SAAS;AACpE;AAeO,SAAS,6BAGd,MAAY;AACZ,SAAO,EAAE,GAAG,MAAM,OAAO,KAAK,MAAM,IAAI,wBAAwB,EAAA;AAClE;"}

package/dist/util/paginator.cjs

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+async function* paginatePages(fetcher, signal) {
+  let cursor;
+  while (true) {
+    signal?.throwIfAborted();
+    const { page, nextCursor } = await fetcher(cursor);
+    yield page;
+    if (nextCursor === void 0) return;
+    cursor = nextCursor;
+  }
+}
+async function* paginateItems(fetcher, extractItems, signal) {
+  for await (const page of paginatePages(fetcher, signal)) {
+    yield* extractItems(page);
+  }
+}
+exports.paginateItems = paginateItems;
+exports.paginatePages = paginatePages;
+//# sourceMappingURL=paginator.cjs.map

package/dist/util/paginator.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"paginator.cjs","sources":["../../src/util/paginator.ts"],"sourcesContent":["/**\n * Generic pagination helpers for B2 list endpoints.\n *\n * B2 returns paginated results as `{ items, nextCursor }` shapes that differ\n * per endpoint (`nextFileName`, `nextFileId`, `nextPartNumber`,\n * `nextApplicationKeyId`, etc.). These helpers let callers iterate without\n * threading the cursor by hand.\n *\n * Two flavours:\n *   - {@link paginatePages} yields each page as the server returned it.\n *     Useful when the caller wants the per-page response object (e.g. for\n *     access to per-page metadata or to control item-iteration order).\n *   - {@link paginateItems} flattens pages and yields individual items.\n *     Useful for the common \"iterate everything\" case.\n *\n * Both helpers honour an optional {@link AbortSignal} that aborts the\n * iteration **between fetches**. They do NOT abort an in-flight network\n * request: the underlying list call has its own `signal` parameter and\n * each consumer must wire that through if mid-flight cancellation is\n * required.\n *\n * @packageDocumentation\n *\n * @example\n * ```ts\n * for await (const file of bucket.paginateFileNames({ prefix: 'photos/' })) {\n *   console.log(file.fileName, file.contentLength)\n * }\n * ```\n *\n */\n\n/**\n * Options accepted by every `paginateX` method on `Bucket` and `B2Client`.\n */\nexport interface PaginatorOptions {\n  /**\n   * Maximum items per page. Forwarded to the underlying list call's\n   * `maxFileCount` / `maxKeyCount` / `maxPartCount` parameter. B2 caps this\n   * at endpoint-specific limits (typically 10000 for files, 100 for parts).\n   */\n  pageSize?: number\n  /**\n   * Aborts the iteration between fetches. When already aborted at call time,\n   * the iterator throws immediately on its first `next()` call.\n   *\n   * Note: this does NOT abort an in-flight HTTP request mid-page. The\n   * iterator checks `signal.throwIfAborted()` only between fetches.\n   */\n  signal?: AbortSignal\n}\n\n/**\n * Function that fetches a single page given a cursor.\n *\n * The cursor is `undefined` for the first page, then takes the value of the\n * previous page's `nextCursor` on subsequent calls. Iteration stops when\n * `nextCursor` is `undefined` (or any other falsy value the caller maps to\n * `undefined`).\n *\n * @typeParam Page - The per-page response shape returned by the B2 endpoint.\n * @typeParam Cursor - The cursor type (typically `string` or a `{name, id}` pair).\n */\nexport type PageFetcher<Page, Cursor> = (cursor: Cursor | undefined) => Promise<{\n  /** The page just fetched. */\n  page: Page\n  /** Cursor for the next page, or `undefined` if there are no more pages. */\n  nextCursor: Cursor | undefined\n}>\n\n/**\n * Async-iterates one page at a time. Stops when `fetcher` returns\n * `nextCursor: undefined`.\n *\n * @typeParam Page - The per-page response shape.\n * @typeParam Cursor - The cursor type used to request the next page.\n *\n * @param fetcher - Function that fetches one page given the current cursor.\n * @param signal - Optional abort signal. Checked before each fetch.\n *\n * @returns An async iterable of pages.\n *\n * @throws DOMException When `signal` is aborted between fetches.\n *\n * @example\n * ```ts\n * for await (const page of paginatePages(\n *   async (cursor) => {\n *     const resp = await bucket.listFileNames({ startFileName: cursor })\n *     return { page: resp, nextCursor: resp.nextFileName ?? undefined }\n *   },\n *   abortSignal,\n * )) {\n *   for (const file of page.files) { ... }\n * }\n * ```\n */\nexport async function* paginatePages<Page, Cursor>(\n  fetcher: PageFetcher<Page, Cursor>,\n  signal: AbortSignal | undefined,\n): AsyncIterableIterator<Page> {\n  let cursor: Cursor | undefined\n  while (true) {\n    signal?.throwIfAborted()\n    const { page, nextCursor } = await fetcher(cursor)\n    yield page\n    if (nextCursor === undefined) return\n    cursor = nextCursor\n  }\n}\n\n/**\n * Async-iterates items by flattening pages. The `extractItems` function\n * pulls the relevant array out of each page (e.g. `page.files`,\n * `page.keys`, `page.parts`). Each item is yielded individually so the\n * caller can `for await (const item of paginator)` rather than nest loops.\n *\n * Aborts between **pages**, not between items: if `signal` is aborted while\n * the caller is processing the items of page N, the iterator will still\n * yield all of page N's remaining items before checking the signal before\n * fetching page N+1.\n *\n * @typeParam Page - The per-page response shape.\n * @typeParam Cursor - The cursor type used to request the next page.\n * @typeParam Item - The item type the caller wants to iterate.\n *\n * @param fetcher - Function that fetches one page given the current cursor.\n * @param extractItems - Pulls the iterable items out of a page.\n * @param signal - Optional abort signal. Checked before each fetch.\n *\n * @returns An async iterable of individual items.\n *\n * @throws DOMException When `signal` is aborted between fetches.\n */\nexport async function* paginateItems<Page, Cursor, Item>(\n  fetcher: PageFetcher<Page, Cursor>,\n  extractItems: (page: Page) => Iterable<Item>,\n  signal: AbortSignal | undefined,\n): AsyncIterableIterator<Item> {\n  for await (const page of paginatePages(fetcher, signal)) {\n    yield* extractItems(page)\n  }\n}\n"],"names":[],"mappings":";;AAiGA,gBAAuB,cACrB,SACA,QAC6B;AAC7B,MAAI;AACJ,SAAO,MAAM;AACX,YAAQ,eAAA;AACR,UAAM,EAAE,MAAM,WAAA,IAAe,MAAM,QAAQ,MAAM;AACjD,UAAM;AACN,QAAI,eAAe,OAAW;AAC9B,aAAS;AAAA,EACX;AACF;AAyBA,gBAAuB,cACrB,SACA,cACA,QAC6B;AAC7B,mBAAiB,QAAQ,cAAc,SAAS,MAAM,GAAG;AACvD,WAAO,aAAa,IAAI;AAAA,EAC1B;AACF;;;"}