@backblaze-labs/b2-sdk 0.1.0 → 0.3.0

package/dist/util/normalize.cjs

@@ -1,16 +1,75 @@
-"use strict";
-Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/util/normalize.ts
+/**
+* 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".
+*/
 function normalizeSha1(raw) {
-  if (raw === null || raw === void 0 || raw === "none") return null;
-  return raw;
+	if (raw === null || raw === void 0 || raw === "none") return null;
+	return raw;
 }
+/**
+* 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`.
+*/
 function normalizeFileVersionSha1(fv) {
-  return fv.contentSha1 === "none" ? { ...fv, contentSha1: null } : fv;
+	return fv.contentSha1 === "none" ? {
+		...fv,
+		contentSha1: null
+	} : fv;
 }
+/**
+* Returns a new list-response object with `normalizeFileVersionSha1`
+* applied to every entry in `files`. Used at file-version and unfinished
+* large-file list boundaries 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.
+*/
 function normalizeFileVersionListSha1(resp) {
-  return { ...resp, files: resp.files.map(normalizeFileVersionSha1) };
+	return {
+		...resp,
+		files: resp.files.map(normalizeFileVersionSha1)
+	};
 }
+//#endregion
 exports.normalizeFileVersionListSha1 = normalizeFileVersionListSha1;
 exports.normalizeFileVersionSha1 = normalizeFileVersionSha1;
 exports.normalizeSha1 = normalizeSha1;
-//# sourceMappingURL=normalize.cjs.map
+
+//# sourceMappingURL=normalize.cjs.map

package/dist/util/normalize.cjs.map

@@ -1 +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;;;;"}
+{"version":3,"file":"normalize.cjs","names":[],"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 file-version and unfinished\n * large-file list boundaries so list output shares the same SHA-1 semantics\n * 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"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;AA2BA,SAAgB,cAAc,KAA+C;CAC3E,IAAI,QAAQ,QAAQ,QAAQ,KAAA,KAAa,QAAQ,QAAQ,OAAO;CAChE,OAAO;AACT;;;;;;;;;;;;;;AAeA,SAAgB,yBACd,IACG;CACH,OAAO,GAAG,gBAAgB,SAAS;EAAE,GAAG;EAAI,aAAa;CAAK,IAAI;AACpE;;;;;;;;;;;;;;AAeA,SAAgB,6BAGd,MAAY;CACZ,OAAO;EAAE,GAAG;EAAM,OAAO,KAAK,MAAM,IAAI,wBAAwB;CAAE;AACpE"}

package/dist/util/normalize.d.cts

@@ -32,22 +32,22 @@ export declare function normalizeSha1(raw: string | null | undefined): string |
  * 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.
+ * @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;
+    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.
+ * applied to every entry in `files`. Used at file-version and unfinished
+ * large-file list boundaries so list output shares the same SHA-1 semantics
+ * as the singular endpoints.
  *
- * @typeParam F - Any object with a `contentSha1: string | null` field.
+ * @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.
@@ -55,7 +55,7 @@ export declare function normalizeFileVersionSha1<T extends {
  * @returns A response with normalized `files`. `resp.files` is a new array.
  */
 export declare function normalizeFileVersionListSha1<F extends {
-    readonly contentSha1: string | null;
+    readonly contentSha1?: string | null;
 }, R extends {
     readonly files: readonly F[];
 }>(resp: R): R;

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

@@ -1 +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"}
+{"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,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,EACzF,EAAE,EAAE,CAAC,GACJ,CAAC,CAEH;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,4BAA4B,CAC1C,CAAC,SAAS;IAAE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,EAClD,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

@@ -32,22 +32,22 @@ export declare function normalizeSha1(raw: string | null | undefined): string |
  * 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.
+ * @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;
+    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.
+ * applied to every entry in `files`. Used at file-version and unfinished
+ * large-file list boundaries so list output shares the same SHA-1 semantics
+ * as the singular endpoints.
  *
- * @typeParam F - Any object with a `contentSha1: string | null` field.
+ * @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.
@@ -55,7 +55,7 @@ export declare function normalizeFileVersionSha1<T extends {
  * @returns A response with normalized `files`. `resp.files` is a new array.
  */
 export declare function normalizeFileVersionListSha1<F extends {
-    readonly contentSha1: string | null;
+    readonly contentSha1?: string | null;
 }, R extends {
     readonly files: readonly F[];
 }>(resp: R): R;

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

@@ -1 +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"}
+{"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,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,EACzF,EAAE,EAAE,CAAC,GACJ,CAAC,CAEH;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,4BAA4B,CAC1C,CAAC,SAAS;IAAE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,EAClD,CAAC,SAAS;IAAE,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC,EAAE,CAAA;CAAE,EAC1C,IAAI,EAAE,CAAC,GAAG,CAAC,CAEZ"}

package/dist/util/normalize.js

@@ -1,16 +1,73 @@
+//#region src/util/normalize.ts
+/**
+* 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".
+*/
 function normalizeSha1(raw) {
-  if (raw === null || raw === void 0 || raw === "none") return null;
-  return raw;
+	if (raw === null || raw === void 0 || raw === "none") return null;
+	return raw;
 }
+/**
+* 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`.
+*/
 function normalizeFileVersionSha1(fv) {
-  return fv.contentSha1 === "none" ? { ...fv, contentSha1: null } : fv;
+	return fv.contentSha1 === "none" ? {
+		...fv,
+		contentSha1: null
+	} : fv;
 }
+/**
+* Returns a new list-response object with `normalizeFileVersionSha1`
+* applied to every entry in `files`. Used at file-version and unfinished
+* large-file list boundaries 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.
+*/
 function normalizeFileVersionListSha1(resp) {
-  return { ...resp, files: resp.files.map(normalizeFileVersionSha1) };
+	return {
+		...resp,
+		files: resp.files.map(normalizeFileVersionSha1)
+	};
 }
-export {
-  normalizeFileVersionListSha1,
-  normalizeFileVersionSha1,
-  normalizeSha1
-};
-//# sourceMappingURL=normalize.js.map
+//#endregion
+export { normalizeFileVersionListSha1, normalizeFileVersionSha1, normalizeSha1 };
+
+//# sourceMappingURL=normalize.js.map

package/dist/util/normalize.js.map

@@ -1 +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;"}
+{"version":3,"file":"normalize.js","names":[],"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 file-version and unfinished\n * large-file list boundaries so list output shares the same SHA-1 semantics\n * 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"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;AA2BA,SAAgB,cAAc,KAA+C;CAC3E,IAAI,QAAQ,QAAQ,QAAQ,KAAA,KAAa,QAAQ,QAAQ,OAAO;CAChE,OAAO;AACT;;;;;;;;;;;;;;AAeA,SAAgB,yBACd,IACG;CACH,OAAO,GAAG,gBAAgB,SAAS;EAAE,GAAG;EAAI,aAAa;CAAK,IAAI;AACpE;;;;;;;;;;;;;;AAeA,SAAgB,6BAGd,MAAY;CACZ,OAAO;EAAE,GAAG;EAAM,OAAO,KAAK,MAAM,IAAI,wBAAwB;CAAE;AACpE"}

package/dist/util/paginator.cjs

@@ -1,20 +1,75 @@
-"use strict";
-Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/util/paginator.ts
+function isPrimitiveCursor(cursor) {
+	return cursor === null || typeof cursor !== "object" && typeof cursor !== "function";
+}
+/**
+* Async-iterates one page at a time. Stops when `fetcher` returns
+* `nextCursor: undefined` or a primitive cursor that is identical to the
+* cursor just used, which prevents non-advancing server cursors from looping
+* forever.
+*
+* @typeParam Page - The per-page response shape.
+* @typeParam Cursor - The cursor type used to request the next page.
+*
+* @param fetcher - Function that fetches one page given the current cursor.
+* @param signal - Optional abort signal. Checked before each fetch.
+*
+* @returns An async iterable of pages.
+*
+* @throws DOMException When `signal` is aborted between fetches.
+*
+* @example
+* ```ts
+* for await (const page of paginatePages(
+*   async (cursor) => {
+*     const resp = await bucket.listFileNames({ startFileName: cursor })
+*     return { page: resp, nextCursor: resp.nextFileName ?? undefined }
+*   },
+*   abortSignal,
+* )) {
+*   for (const file of page.files) { ... }
+* }
+* ```
+*/
 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;
-  }
+	let cursor;
+	while (true) {
+		signal?.throwIfAborted();
+		const { page, nextCursor } = await fetcher(cursor);
+		yield page;
+		if (nextCursor === void 0) return;
+		if (cursor !== void 0 && isPrimitiveCursor(cursor) && isPrimitiveCursor(nextCursor) && Object.is(nextCursor, cursor)) return;
+		cursor = nextCursor;
+	}
 }
+/**
+* Async-iterates items by flattening pages. The `extractItems` function
+* pulls the relevant array out of each page (e.g. `page.files`,
+* `page.keys`, `page.parts`). Each item is yielded individually so the
+* caller can `for await (const item of paginator)` rather than nest loops.
+*
+* Aborts between **pages**, not between items: if `signal` is aborted while
+* the caller is processing the items of page N, the iterator will still
+* yield all of page N's remaining items before checking the signal before
+* fetching page N+1.
+*
+* @typeParam Page - The per-page response shape.
+* @typeParam Cursor - The cursor type used to request the next page.
+* @typeParam Item - The item type the caller wants to iterate.
+*
+* @param fetcher - Function that fetches one page given the current cursor.
+* @param extractItems - Pulls the iterable items out of a page.
+* @param signal - Optional abort signal. Checked before each fetch.
+*
+* @returns An async iterable of individual items.
+*
+* @throws DOMException When `signal` is aborted between fetches.
+*/
 async function* paginateItems(fetcher, extractItems, signal) {
-  for await (const page of paginatePages(fetcher, signal)) {
-    yield* extractItems(page);
-  }
+	for await (const page of paginatePages(fetcher, signal)) yield* extractItems(page);
 }
+//#endregion
 exports.paginateItems = paginateItems;
 exports.paginatePages = paginatePages;
-//# sourceMappingURL=paginator.cjs.map
+
+//# sourceMappingURL=paginator.cjs.map

package/dist/util/paginator.cjs.map

@@ -1 +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;;;"}
+{"version":3,"file":"paginator.cjs","names":[],"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\nfunction isPrimitiveCursor(cursor: unknown): boolean {\n  return cursor === null || (typeof cursor !== 'object' && typeof cursor !== 'function')\n}\n\n/**\n * Async-iterates one page at a time. Stops when `fetcher` returns\n * `nextCursor: undefined` or a primitive cursor that is identical to the\n * cursor just used, which prevents non-advancing server cursors from looping\n * forever.\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    if (\n      cursor !== undefined &&\n      isPrimitiveCursor(cursor) &&\n      isPrimitiveCursor(nextCursor) &&\n      Object.is(nextCursor, cursor)\n    ) {\n      return\n    }\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"],"mappings":";AAsEA,SAAS,kBAAkB,QAA0B;CACnD,OAAO,WAAW,QAAS,OAAO,WAAW,YAAY,OAAO,WAAW;AAC7E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+BA,gBAAuB,cACrB,SACA,QAC6B;CAC7B,IAAI;CACJ,OAAO,MAAM;EACX,QAAQ,eAAe;EACvB,MAAM,EAAE,MAAM,eAAe,MAAM,QAAQ,MAAM;EACjD,MAAM;EACN,IAAI,eAAe,KAAA,GAAW;EAC9B,IACE,WAAW,KAAA,KACX,kBAAkB,MAAM,KACxB,kBAAkB,UAAU,KAC5B,OAAO,GAAG,YAAY,MAAM,GAE5B;EAEF,SAAS;CACX;AACF;;;;;;;;;;;;;;;;;;;;;;;;AAyBA,gBAAuB,cACrB,SACA,cACA,QAC6B;CAC7B,WAAW,MAAM,QAAQ,cAAc,SAAS,MAAM,GACpD,OAAO,aAAa,IAAI;AAE5B"}

package/dist/util/paginator.d.cts

@@ -67,7 +67,9 @@ export type PageFetcher<Page, Cursor> = (cursor: Cursor | undefined) => Promise<
 }>;
 /**
  * Async-iterates one page at a time. Stops when `fetcher` returns
- * `nextCursor: undefined`.
+ * `nextCursor: undefined` or a primitive cursor that is identical to the
+ * cursor just used, which prevents non-advancing server cursors from looping
+ * forever.
  *
  * @typeParam Page - The per-page response shape.
  * @typeParam Cursor - The cursor type used to request the next page.

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

@@ -1 +1 @@
-{"version":3,"file":"paginator.d.ts","sourceRoot":"","sources":["../../src/util/paginator.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,WAAW,CAAA;CACrB;AAED;;;;;;;;;;GAUG;AACH,MAAM,MAAM,WAAW,CAAC,IAAI,EAAE,MAAM,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,KAAK,OAAO,CAAC;IAC9E,6BAA6B;IAC7B,IAAI,EAAE,IAAI,CAAA;IACV,2EAA2E;IAC3E,UAAU,EAAE,MAAM,GAAG,SAAS,CAAA;CAC/B,CAAC,CAAA;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAuB,aAAa,CAAC,IAAI,EAAE,MAAM,EAC/C,OAAO,EAAE,WAAW,CAAC,IAAI,EAAE,MAAM,CAAC,EAClC,MAAM,EAAE,WAAW,GAAG,SAAS,GAC9B,qBAAqB,CAAC,IAAI,CAAC,CAS7B;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAuB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EACrD,OAAO,EAAE,WAAW,CAAC,IAAI,EAAE,MAAM,CAAC,EAClC,YAAY,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,QAAQ,CAAC,IAAI,CAAC,EAC5C,MAAM,EAAE,WAAW,GAAG,SAAS,GAC9B,qBAAqB,CAAC,IAAI,CAAC,CAI7B"}
+{"version":3,"file":"paginator.d.ts","sourceRoot":"","sources":["../../src/util/paginator.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,WAAW,CAAA;CACrB;AAED;;;;;;;;;;GAUG;AACH,MAAM,MAAM,WAAW,CAAC,IAAI,EAAE,MAAM,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,KAAK,OAAO,CAAC;IAC9E,6BAA6B;IAC7B,IAAI,EAAE,IAAI,CAAA;IACV,2EAA2E;IAC3E,UAAU,EAAE,MAAM,GAAG,SAAS,CAAA;CAC/B,CAAC,CAAA;AAMF;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAuB,aAAa,CAAC,IAAI,EAAE,MAAM,EAC/C,OAAO,EAAE,WAAW,CAAC,IAAI,EAAE,MAAM,CAAC,EAClC,MAAM,EAAE,WAAW,GAAG,SAAS,GAC9B,qBAAqB,CAAC,IAAI,CAAC,CAiB7B;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAuB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EACrD,OAAO,EAAE,WAAW,CAAC,IAAI,EAAE,MAAM,CAAC,EAClC,YAAY,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,QAAQ,CAAC,IAAI,CAAC,EAC5C,MAAM,EAAE,WAAW,GAAG,SAAS,GAC9B,qBAAqB,CAAC,IAAI,CAAC,CAI7B"}

package/dist/util/paginator.d.ts

@@ -67,7 +67,9 @@ export type PageFetcher<Page, Cursor> = (cursor: Cursor | undefined) => Promise<
 }>;
 /**
  * Async-iterates one page at a time. Stops when `fetcher` returns
- * `nextCursor: undefined`.
+ * `nextCursor: undefined` or a primitive cursor that is identical to the
+ * cursor just used, which prevents non-advancing server cursors from looping
+ * forever.
  *
  * @typeParam Page - The per-page response shape.
  * @typeParam Cursor - The cursor type used to request the next page.

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

@@ -1 +1 @@
-{"version":3,"file":"paginator.d.ts","sourceRoot":"","sources":["../../src/util/paginator.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,WAAW,CAAA;CACrB;AAED;;;;;;;;;;GAUG;AACH,MAAM,MAAM,WAAW,CAAC,IAAI,EAAE,MAAM,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,KAAK,OAAO,CAAC;IAC9E,6BAA6B;IAC7B,IAAI,EAAE,IAAI,CAAA;IACV,2EAA2E;IAC3E,UAAU,EAAE,MAAM,GAAG,SAAS,CAAA;CAC/B,CAAC,CAAA;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAuB,aAAa,CAAC,IAAI,EAAE,MAAM,EAC/C,OAAO,EAAE,WAAW,CAAC,IAAI,EAAE,MAAM,CAAC,EAClC,MAAM,EAAE,WAAW,GAAG,SAAS,GAC9B,qBAAqB,CAAC,IAAI,CAAC,CAS7B;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAuB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EACrD,OAAO,EAAE,WAAW,CAAC,IAAI,EAAE,MAAM,CAAC,EAClC,YAAY,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,QAAQ,CAAC,IAAI,CAAC,EAC5C,MAAM,EAAE,WAAW,GAAG,SAAS,GAC9B,qBAAqB,CAAC,IAAI,CAAC,CAI7B"}
+{"version":3,"file":"paginator.d.ts","sourceRoot":"","sources":["../../src/util/paginator.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,WAAW,CAAA;CACrB;AAED;;;;;;;;;;GAUG;AACH,MAAM,MAAM,WAAW,CAAC,IAAI,EAAE,MAAM,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,KAAK,OAAO,CAAC;IAC9E,6BAA6B;IAC7B,IAAI,EAAE,IAAI,CAAA;IACV,2EAA2E;IAC3E,UAAU,EAAE,MAAM,GAAG,SAAS,CAAA;CAC/B,CAAC,CAAA;AAMF;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAuB,aAAa,CAAC,IAAI,EAAE,MAAM,EAC/C,OAAO,EAAE,WAAW,CAAC,IAAI,EAAE,MAAM,CAAC,EAClC,MAAM,EAAE,WAAW,GAAG,SAAS,GAC9B,qBAAqB,CAAC,IAAI,CAAC,CAiB7B;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAuB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EACrD,OAAO,EAAE,WAAW,CAAC,IAAI,EAAE,MAAM,CAAC,EAClC,YAAY,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,QAAQ,CAAC,IAAI,CAAC,EAC5C,MAAM,EAAE,WAAW,GAAG,SAAS,GAC9B,qBAAqB,CAAC,IAAI,CAAC,CAI7B"}

package/dist/util/paginator.js

@@ -1,20 +1,74 @@
+//#region src/util/paginator.ts
+function isPrimitiveCursor(cursor) {
+	return cursor === null || typeof cursor !== "object" && typeof cursor !== "function";
+}
+/**
+* Async-iterates one page at a time. Stops when `fetcher` returns
+* `nextCursor: undefined` or a primitive cursor that is identical to the
+* cursor just used, which prevents non-advancing server cursors from looping
+* forever.
+*
+* @typeParam Page - The per-page response shape.
+* @typeParam Cursor - The cursor type used to request the next page.
+*
+* @param fetcher - Function that fetches one page given the current cursor.
+* @param signal - Optional abort signal. Checked before each fetch.
+*
+* @returns An async iterable of pages.
+*
+* @throws DOMException When `signal` is aborted between fetches.
+*
+* @example
+* ```ts
+* for await (const page of paginatePages(
+*   async (cursor) => {
+*     const resp = await bucket.listFileNames({ startFileName: cursor })
+*     return { page: resp, nextCursor: resp.nextFileName ?? undefined }
+*   },
+*   abortSignal,
+* )) {
+*   for (const file of page.files) { ... }
+* }
+* ```
+*/
 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;
-  }
+	let cursor;
+	while (true) {
+		signal?.throwIfAborted();
+		const { page, nextCursor } = await fetcher(cursor);
+		yield page;
+		if (nextCursor === void 0) return;
+		if (cursor !== void 0 && isPrimitiveCursor(cursor) && isPrimitiveCursor(nextCursor) && Object.is(nextCursor, cursor)) return;
+		cursor = nextCursor;
+	}
 }
+/**
+* Async-iterates items by flattening pages. The `extractItems` function
+* pulls the relevant array out of each page (e.g. `page.files`,
+* `page.keys`, `page.parts`). Each item is yielded individually so the
+* caller can `for await (const item of paginator)` rather than nest loops.
+*
+* Aborts between **pages**, not between items: if `signal` is aborted while
+* the caller is processing the items of page N, the iterator will still
+* yield all of page N's remaining items before checking the signal before
+* fetching page N+1.
+*
+* @typeParam Page - The per-page response shape.
+* @typeParam Cursor - The cursor type used to request the next page.
+* @typeParam Item - The item type the caller wants to iterate.
+*
+* @param fetcher - Function that fetches one page given the current cursor.
+* @param extractItems - Pulls the iterable items out of a page.
+* @param signal - Optional abort signal. Checked before each fetch.
+*
+* @returns An async iterable of individual items.
+*
+* @throws DOMException When `signal` is aborted between fetches.
+*/
 async function* paginateItems(fetcher, extractItems, signal) {
-  for await (const page of paginatePages(fetcher, signal)) {
-    yield* extractItems(page);
-  }
+	for await (const page of paginatePages(fetcher, signal)) yield* extractItems(page);
 }
-export {
-  paginateItems,
-  paginatePages
-};
-//# sourceMappingURL=paginator.js.map
+//#endregion
+export { paginateItems, paginatePages };
+
+//# sourceMappingURL=paginator.js.map

package/dist/util/paginator.js.map

@@ -1 +1 @@
-{"version":3,"file":"paginator.js","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;"}
+{"version":3,"file":"paginator.js","names":[],"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\nfunction isPrimitiveCursor(cursor: unknown): boolean {\n  return cursor === null || (typeof cursor !== 'object' && typeof cursor !== 'function')\n}\n\n/**\n * Async-iterates one page at a time. Stops when `fetcher` returns\n * `nextCursor: undefined` or a primitive cursor that is identical to the\n * cursor just used, which prevents non-advancing server cursors from looping\n * forever.\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    if (\n      cursor !== undefined &&\n      isPrimitiveCursor(cursor) &&\n      isPrimitiveCursor(nextCursor) &&\n      Object.is(nextCursor, cursor)\n    ) {\n      return\n    }\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"],"mappings":";AAsEA,SAAS,kBAAkB,QAA0B;CACnD,OAAO,WAAW,QAAS,OAAO,WAAW,YAAY,OAAO,WAAW;AAC7E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+BA,gBAAuB,cACrB,SACA,QAC6B;CAC7B,IAAI;CACJ,OAAO,MAAM;EACX,QAAQ,eAAe;EACvB,MAAM,EAAE,MAAM,eAAe,MAAM,QAAQ,MAAM;EACjD,MAAM;EACN,IAAI,eAAe,KAAA,GAAW;EAC9B,IACE,WAAW,KAAA,KACX,kBAAkB,MAAM,KACxB,kBAAkB,UAAU,KAC5B,OAAO,GAAG,YAAY,MAAM,GAE5B;EAEF,SAAS;CACX;AACF;;;;;;;;;;;;;;;;;;;;;;;;AAyBA,gBAAuB,cACrB,SACA,cACA,QAC6B;CAC7B,WAAW,MAAM,QAAQ,cAAc,SAAS,MAAM,GACpD,OAAO,aAAa,IAAI;AAE5B"}