@backblaze-labs/b2-sdk 0.1.0 → 0.2.0

package/dist/util/error-reason.cjs

@@ -0,0 +1,41 @@
+const require_to_error = require("./to-error.cjs");
+//#region src/util/error-reason.ts
+/**
+* Formats an unknown error for public diagnostics without leaking filesystem paths.
+*
+* @param err - Unknown thrown value.
+*
+* @returns A stable, sanitized reason.
+*/
+function sanitizeErrorReason(err) {
+	const error = require_to_error.toError(err);
+	const code = error.code;
+	if (typeof code === "string" && code.length > 0) {
+		const reason = cleanReason(code);
+		if (reason.length > 0) return reason;
+	}
+	const message = cleanReason(error.message);
+	if (message.length > 0 && !/[\\/]/.test(message)) return message;
+	const name = cleanReason(error.name);
+	if (name.length > 0) return name;
+	return "Error";
+}
+function cleanReason(value) {
+	let cleaned = "";
+	let sawNonWhitespace = false;
+	for (const char of value) {
+		const code = char.charCodeAt(0);
+		if (code < 32 || code === 127) continue;
+		if (!sawNonWhitespace) {
+			if (char.trim().length === 0) continue;
+			sawNonWhitespace = true;
+		}
+		cleaned += char;
+		if (cleaned.length >= 200) break;
+	}
+	return cleaned.trimEnd();
+}
+//#endregion
+exports.sanitizeErrorReason = sanitizeErrorReason;
+
+//# sourceMappingURL=error-reason.cjs.map

package/dist/util/error-reason.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-reason.cjs","names":[],"sources":["../../src/util/error-reason.ts"],"sourcesContent":["import { toError } from './to-error.ts'\n\n/**\n * Formats an unknown error for public diagnostics without leaking filesystem paths.\n *\n * @param err - Unknown thrown value.\n *\n * @returns A stable, sanitized reason.\n */\nexport function sanitizeErrorReason(err: unknown): string {\n  const error = toError(err)\n  const code = (error as { readonly code?: unknown }).code\n  if (typeof code === 'string' && code.length > 0) {\n    const reason = cleanReason(code)\n    if (reason.length > 0) return reason\n  }\n  const message = cleanReason(error.message)\n  if (message.length > 0 && !/[\\\\/]/.test(message)) return message\n  const name = cleanReason(error.name)\n  if (name.length > 0) return name\n  return 'Error'\n}\n\nfunction cleanReason(value: string): string {\n  let cleaned = ''\n  let sawNonWhitespace = false\n  for (const char of value) {\n    const code = char.charCodeAt(0)\n    if (code < 0x20 || code === 0x7f) continue\n    if (!sawNonWhitespace) {\n      if (char.trim().length === 0) continue\n      sawNonWhitespace = true\n    }\n    cleaned += char\n    if (cleaned.length >= 200) break\n  }\n  return cleaned.trimEnd()\n}\n"],"mappings":";;;;;;;;;AASA,SAAgB,oBAAoB,KAAsB;CACxD,MAAM,QAAQ,iBAAA,QAAQ,GAAG;CACzB,MAAM,OAAQ,MAAsC;CACpD,IAAI,OAAO,SAAS,YAAY,KAAK,SAAS,GAAG;EAC/C,MAAM,SAAS,YAAY,IAAI;EAC/B,IAAI,OAAO,SAAS,GAAG,OAAO;CAChC;CACA,MAAM,UAAU,YAAY,MAAM,OAAO;CACzC,IAAI,QAAQ,SAAS,KAAK,CAAC,QAAQ,KAAK,OAAO,GAAG,OAAO;CACzD,MAAM,OAAO,YAAY,MAAM,IAAI;CACnC,IAAI,KAAK,SAAS,GAAG,OAAO;CAC5B,OAAO;AACT;AAEA,SAAS,YAAY,OAAuB;CAC1C,IAAI,UAAU;CACd,IAAI,mBAAmB;CACvB,KAAK,MAAM,QAAQ,OAAO;EACxB,MAAM,OAAO,KAAK,WAAW,CAAC;EAC9B,IAAI,OAAO,MAAQ,SAAS,KAAM;EAClC,IAAI,CAAC,kBAAkB;GACrB,IAAI,KAAK,KAAK,CAAC,CAAC,WAAW,GAAG;GAC9B,mBAAmB;EACrB;EACA,WAAW;EACX,IAAI,QAAQ,UAAU,KAAK;CAC7B;CACA,OAAO,QAAQ,QAAQ;AACzB"}

package/dist/util/error-reason.d.cts

@@ -0,0 +1,9 @@
+/**
+ * Formats an unknown error for public diagnostics without leaking filesystem paths.
+ *
+ * @param err - Unknown thrown value.
+ *
+ * @returns A stable, sanitized reason.
+ */
+export declare function sanitizeErrorReason(err: unknown): string;
+//# sourceMappingURL=error-reason.d.ts.map

package/dist/util/error-reason.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-reason.d.ts","sourceRoot":"","sources":["../../src/util/error-reason.js"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAYxD"}

package/dist/util/error-reason.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Formats an unknown error for public diagnostics without leaking filesystem paths.
+ *
+ * @param err - Unknown thrown value.
+ *
+ * @returns A stable, sanitized reason.
+ */
+export declare function sanitizeErrorReason(err: unknown): string;
+//# sourceMappingURL=error-reason.d.ts.map

package/dist/util/error-reason.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-reason.d.ts","sourceRoot":"","sources":["../../src/util/error-reason.js"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAYxD"}

package/dist/util/error-reason.js

@@ -0,0 +1,41 @@
+import { toError } from "./to-error.js";
+//#region src/util/error-reason.ts
+/**
+* Formats an unknown error for public diagnostics without leaking filesystem paths.
+*
+* @param err - Unknown thrown value.
+*
+* @returns A stable, sanitized reason.
+*/
+function sanitizeErrorReason(err) {
+	const error = toError(err);
+	const code = error.code;
+	if (typeof code === "string" && code.length > 0) {
+		const reason = cleanReason(code);
+		if (reason.length > 0) return reason;
+	}
+	const message = cleanReason(error.message);
+	if (message.length > 0 && !/[\\/]/.test(message)) return message;
+	const name = cleanReason(error.name);
+	if (name.length > 0) return name;
+	return "Error";
+}
+function cleanReason(value) {
+	let cleaned = "";
+	let sawNonWhitespace = false;
+	for (const char of value) {
+		const code = char.charCodeAt(0);
+		if (code < 32 || code === 127) continue;
+		if (!sawNonWhitespace) {
+			if (char.trim().length === 0) continue;
+			sawNonWhitespace = true;
+		}
+		cleaned += char;
+		if (cleaned.length >= 200) break;
+	}
+	return cleaned.trimEnd();
+}
+//#endregion
+export { sanitizeErrorReason };
+
+//# sourceMappingURL=error-reason.js.map

package/dist/util/error-reason.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-reason.js","names":[],"sources":["../../src/util/error-reason.ts"],"sourcesContent":["import { toError } from './to-error.ts'\n\n/**\n * Formats an unknown error for public diagnostics without leaking filesystem paths.\n *\n * @param err - Unknown thrown value.\n *\n * @returns A stable, sanitized reason.\n */\nexport function sanitizeErrorReason(err: unknown): string {\n  const error = toError(err)\n  const code = (error as { readonly code?: unknown }).code\n  if (typeof code === 'string' && code.length > 0) {\n    const reason = cleanReason(code)\n    if (reason.length > 0) return reason\n  }\n  const message = cleanReason(error.message)\n  if (message.length > 0 && !/[\\\\/]/.test(message)) return message\n  const name = cleanReason(error.name)\n  if (name.length > 0) return name\n  return 'Error'\n}\n\nfunction cleanReason(value: string): string {\n  let cleaned = ''\n  let sawNonWhitespace = false\n  for (const char of value) {\n    const code = char.charCodeAt(0)\n    if (code < 0x20 || code === 0x7f) continue\n    if (!sawNonWhitespace) {\n      if (char.trim().length === 0) continue\n      sawNonWhitespace = true\n    }\n    cleaned += char\n    if (cleaned.length >= 200) break\n  }\n  return cleaned.trimEnd()\n}\n"],"mappings":";;;;;;;;;AASA,SAAgB,oBAAoB,KAAsB;CACxD,MAAM,QAAQ,QAAQ,GAAG;CACzB,MAAM,OAAQ,MAAsC;CACpD,IAAI,OAAO,SAAS,YAAY,KAAK,SAAS,GAAG;EAC/C,MAAM,SAAS,YAAY,IAAI;EAC/B,IAAI,OAAO,SAAS,GAAG,OAAO;CAChC;CACA,MAAM,UAAU,YAAY,MAAM,OAAO;CACzC,IAAI,QAAQ,SAAS,KAAK,CAAC,QAAQ,KAAK,OAAO,GAAG,OAAO;CACzD,MAAM,OAAO,YAAY,MAAM,IAAI;CACnC,IAAI,KAAK,SAAS,GAAG,OAAO;CAC5B,OAAO;AACT;AAEA,SAAS,YAAY,OAAuB;CAC1C,IAAI,UAAU;CACd,IAAI,mBAAmB;CACvB,KAAK,MAAM,QAAQ,OAAO;EACxB,MAAM,OAAO,KAAK,WAAW,CAAC;EAC9B,IAAI,OAAO,MAAQ,SAAS,KAAM;EAClC,IAAI,CAAC,kBAAkB;GACrB,IAAI,KAAK,KAAK,CAAC,CAAC,WAAW,GAAG;GAC9B,mBAAmB;EACrB;EACA,WAAW;EACX,IAAI,QAAQ,UAAU,KAAK;CAC7B;CACA,OAAO,QAAQ,QAAQ;AACzB"}

package/dist/util/http.cjs

@@ -0,0 +1,23 @@
+//#region src/util/http.ts
+/**
+* Detect HTTP header value control characters.
+*
+* Header values used by this SDK must not contain C0 controls or DEL. Rejecting
+* them before signing avoids relying on later whitespace normalization to
+* neutralize CR/LF header injection.
+*
+* @param value - Header value to inspect.
+*
+* @returns `true` when the value contains a disallowed control character.
+*/
+function hasHttpHeaderControlCharacter(value) {
+	for (let i = 0; i < value.length; i++) {
+		const code = value.charCodeAt(i);
+		if (code <= 31 || code === 127) return true;
+	}
+	return false;
+}
+//#endregion
+exports.hasHttpHeaderControlCharacter = hasHttpHeaderControlCharacter;
+
+//# sourceMappingURL=http.cjs.map

package/dist/util/http.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.cjs","names":[],"sources":["../../src/util/http.ts"],"sourcesContent":["/**\n * Detect HTTP header value control characters.\n *\n * Header values used by this SDK must not contain C0 controls or DEL. Rejecting\n * them before signing avoids relying on later whitespace normalization to\n * neutralize CR/LF header injection.\n *\n * @param value - Header value to inspect.\n *\n * @returns `true` when the value contains a disallowed control character.\n */\nexport function hasHttpHeaderControlCharacter(value: string): boolean {\n  for (let i = 0; i < value.length; i++) {\n    const code = value.charCodeAt(i)\n    if (code <= 0x1f || code === 0x7f) return true\n  }\n\n  return false\n}\n"],"mappings":";;;;;;;;;;;;AAWA,SAAgB,8BAA8B,OAAwB;CACpE,KAAK,IAAI,IAAI,GAAG,IAAI,MAAM,QAAQ,KAAK;EACrC,MAAM,OAAO,MAAM,WAAW,CAAC;EAC/B,IAAI,QAAQ,MAAQ,SAAS,KAAM,OAAO;CAC5C;CAEA,OAAO;AACT"}

package/dist/util/http.d.cts

@@ -0,0 +1,13 @@
+/**
+ * Detect HTTP header value control characters.
+ *
+ * Header values used by this SDK must not contain C0 controls or DEL. Rejecting
+ * them before signing avoids relying on later whitespace normalization to
+ * neutralize CR/LF header injection.
+ *
+ * @param value - Header value to inspect.
+ *
+ * @returns `true` when the value contains a disallowed control character.
+ */
+export declare function hasHttpHeaderControlCharacter(value: string): boolean;
+//# sourceMappingURL=http.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../src/util/http.js"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAOpE"}

package/dist/util/http.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Detect HTTP header value control characters.
+ *
+ * Header values used by this SDK must not contain C0 controls or DEL. Rejecting
+ * them before signing avoids relying on later whitespace normalization to
+ * neutralize CR/LF header injection.
+ *
+ * @param value - Header value to inspect.
+ *
+ * @returns `true` when the value contains a disallowed control character.
+ */
+export declare function hasHttpHeaderControlCharacter(value: string): boolean;
+//# sourceMappingURL=http.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../src/util/http.js"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAOpE"}

package/dist/util/http.js

@@ -0,0 +1,23 @@
+//#region src/util/http.ts
+/**
+* Detect HTTP header value control characters.
+*
+* Header values used by this SDK must not contain C0 controls or DEL. Rejecting
+* them before signing avoids relying on later whitespace normalization to
+* neutralize CR/LF header injection.
+*
+* @param value - Header value to inspect.
+*
+* @returns `true` when the value contains a disallowed control character.
+*/
+function hasHttpHeaderControlCharacter(value) {
+	for (let i = 0; i < value.length; i++) {
+		const code = value.charCodeAt(i);
+		if (code <= 31 || code === 127) return true;
+	}
+	return false;
+}
+//#endregion
+export { hasHttpHeaderControlCharacter };
+
+//# sourceMappingURL=http.js.map

package/dist/util/http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.js","names":[],"sources":["../../src/util/http.ts"],"sourcesContent":["/**\n * Detect HTTP header value control characters.\n *\n * Header values used by this SDK must not contain C0 controls or DEL. Rejecting\n * them before signing avoids relying on later whitespace normalization to\n * neutralize CR/LF header injection.\n *\n * @param value - Header value to inspect.\n *\n * @returns `true` when the value contains a disallowed control character.\n */\nexport function hasHttpHeaderControlCharacter(value: string): boolean {\n  for (let i = 0; i < value.length; i++) {\n    const code = value.charCodeAt(i)\n    if (code <= 0x1f || code === 0x7f) return true\n  }\n\n  return false\n}\n"],"mappings":";;;;;;;;;;;;AAWA,SAAgB,8BAA8B,OAAwB;CACpE,KAAK,IAAI,IAAI,GAAG,IAAI,MAAM,QAAQ,KAAK;EACrC,MAAM,OAAO,MAAM,WAAW,CAAC;EAC/B,IAAI,QAAQ,MAAQ,SAAS,KAAM,OAAO;CAC5C;CAEA,OAAO;AACT"}

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 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.
+*/
 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 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"],"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.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 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.
+*/
 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 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"],"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,69 @@
-"use strict";
-Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/util/paginator.ts
+/**
+* Async-iterates one page at a time. Stops when `fetcher` returns
+* `nextCursor: undefined`.
+*
+* @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;
+		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\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"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiGA,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,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.js

@@ -1,20 +1,68 @@
+//#region src/util/paginator.ts
+/**
+* Async-iterates one page at a time. Stops when `fetcher` returns
+* `nextCursor: undefined`.
+*
+* @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;
+		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