@atproto/lex-data 0.0.9 → 0.0.11

package/dist/uint8array.js

@@ -14,18 +14,45 @@ const uint8array_to_base64_js_1 = require("./uint8array-to-base64.js");
 /**
  * Encodes a Uint8Array into a base64 string.
  *
+ * Uses native Uint8Array.prototype.toBase64 when available (Node.js 24+, modern browsers),
+ * falling back to Node.js Buffer or a ponyfill implementation.
+ *
+ * @param bytes - The binary data to encode
+ * @param alphabet - The base64 alphabet to use ('base64' or 'base64url'), defaults to 'base64'
  * @returns The base64 encoded string
+ *
+ * @example
+ * ```typescript
+ * import { toBase64 } from '@atproto/lex-data'
+ *
+ * const bytes = new Uint8Array([72, 101, 108, 108, 111])
+ * toBase64(bytes)           // 'SGVsbG8='
+ * toBase64(bytes, 'base64url')  // 'SGVsbG8' (URL-safe, no padding)
+ * ```
  */
 exports.toBase64 = 
 /* v8 ignore next -- @preserve */ uint8array_to_base64_js_1.toBase64Native ??
     uint8array_to_base64_js_1.toBase64Node ??
     uint8array_to_base64_js_1.toBase64Ponyfill;
 /**
- * Decodes a base64 string into a Uint8Array. This function supports both padded
- * and unpadded base64 strings.
+ * Decodes a base64 string into a Uint8Array.
+ *
+ * Supports both padded and unpadded base64 strings. Uses native
+ * Uint8Array.fromBase64 when available, falling back to Node.js Buffer
+ * or a ponyfill implementation.
  *
- * @returns The decoded {@link Uint8Array}
+ * @param b64 - The base64 string to decode
+ * @param alphabet - The base64 alphabet to use ('base64' or 'base64url'), defaults to 'base64'
+ * @returns The decoded binary data
  * @throws If the input is not a valid base64 string
+ *
+ * @example
+ * ```typescript
+ * import { fromBase64 } from '@atproto/lex-data'
+ *
+ * fromBase64('SGVsbG8=')       // Uint8Array([72, 101, 108, 108, 111])
+ * fromBase64('SGVsbG8', 'base64url')  // Same, URL-safe alphabet
+ * ```
  */
 exports.fromBase64 = 
 /* v8 ignore next -- @preserve */ uint8array_from_base64_js_1.fromBase64Native ??
@@ -36,6 +63,21 @@ if (exports.toBase64 === uint8array_to_base64_js_1.toBase64Ponyfill || exports.f
     /*#__PURE__*/
     console.warn('[@atproto/lex-data]: Uint8Array.fromBase64 / Uint8Array.prototype.toBase64 not available in this environment. Falling back to ponyfill implementation.');
 }
+/**
+ * Returns the input if it is a Uint8Array, otherwise returns undefined.
+ *
+ * @param input - The value to check
+ * @returns The input if it's a Uint8Array, otherwise undefined
+ *
+ * @example
+ * ```typescript
+ * import { ifUint8Array } from '@atproto/lex-data'
+ *
+ * ifUint8Array(new Uint8Array([1, 2]))  // Uint8Array([1, 2])
+ * ifUint8Array('not binary')            // undefined
+ * ifUint8Array(new ArrayBuffer(4))      // undefined
+ * ```
+ */
 function ifUint8Array(input) {
     if (input instanceof Uint8Array) {
         return input;
@@ -45,7 +87,23 @@ function ifUint8Array(input) {
 /**
  * Coerces various binary data representations into a Uint8Array.
  *
- * @return `undefined` if the input could not be coerced into a {@link Uint8Array}.
+ * Handles the following input types:
+ * - `Uint8Array` - Returned as-is
+ * - `ArrayBufferView` (e.g., DataView, other TypedArrays) - Converted to Uint8Array
+ * - `ArrayBuffer` - Wrapped in a Uint8Array
+ *
+ * @param input - The value to convert
+ * @returns A Uint8Array, or `undefined` if the input could not be converted
+ *
+ * @example
+ * ```typescript
+ * import { asUint8Array } from '@atproto/lex-data'
+ *
+ * asUint8Array(new Uint8Array([1, 2]))     // Uint8Array([1, 2])
+ * asUint8Array(new ArrayBuffer(4))         // Uint8Array of length 4
+ * asUint8Array(new Int16Array([1, 2]))     // Uint8Array view of the buffer
+ * asUint8Array('string')                   // undefined
+ * ```
  */
 function asUint8Array(input) {
     if (input instanceof Uint8Array) {
@@ -59,6 +117,22 @@ function asUint8Array(input) {
     }
     return undefined;
 }
+/**
+ * Compares two Uint8Arrays for byte-by-byte equality.
+ *
+ * @param a - First Uint8Array to compare
+ * @param b - Second Uint8Array to compare
+ * @returns `true` if both arrays have the same length and identical bytes
+ *
+ * @example
+ * ```typescript
+ * import { ui8Equals } from '@atproto/lex-data'
+ *
+ * ui8Equals(new Uint8Array([1, 2]), new Uint8Array([1, 2]))  // true
+ * ui8Equals(new Uint8Array([1, 2]), new Uint8Array([1, 3]))  // false
+ * ui8Equals(new Uint8Array([1]), new Uint8Array([1, 2]))     // false
+ * ```
+ */
 function ui8Equals(a, b) {
     if (a.byteLength !== b.byteLength) {
         return false;
@@ -70,6 +144,24 @@ function ui8Equals(a, b) {
     }
     return true;
 }
+/**
+ * Concatenates multiple Uint8Arrays into a single Uint8Array.
+ *
+ * Uses Node.js Buffer.concat when available for performance,
+ * falling back to a ponyfill implementation.
+ *
+ * @param arrays - The Uint8Arrays to concatenate
+ * @returns A new Uint8Array containing all input bytes in order
+ *
+ * @example
+ * ```typescript
+ * import { ui8Concat } from '@atproto/lex-data'
+ *
+ * const a = new Uint8Array([1, 2])
+ * const b = new Uint8Array([3, 4])
+ * ui8Concat([a, b])  // Uint8Array([1, 2, 3, 4])
+ * ```
+ */
 exports.ui8Concat = 
 /* v8 ignore next -- @preserve */ uint8array_concat_js_1.ui8ConcatNode ?? uint8array_concat_js_1.ui8ConcatPonyfill;
 //# sourceMappingURL=uint8array.js.map

package/dist/uint8array.js.map

@@ -1 +1 @@
-{"version":3,"file":"uint8array.js","sourceRoot":"","sources":["../src/uint8array.ts"],"names":[],"mappings":";;;AAwDA,oCAMC;AAOD,oCAkBC;AAED,8BAYC;AApGD,iEAAyE;AACzE,2EAIoC;AACpC,uEAIkC;AAIlC,4EAA4E;AAC5E,2EAA2E;AAC3E,2EAA2E;AAC3E,0CAA0C;AAE1C;;;;GAIG;AACU,QAAA,QAAQ;AAInB,iCAAiC,CAAC,wCAAc;IAChD,sCAAY;IACZ,0CAAgB,CAAA;AAElB;;;;;;GAMG;AACU,QAAA,UAAU;AAIrB,iCAAiC,CAAC,4CAAgB;IAClD,0CAAc;IACd,8CAAkB,CAAA;AAEpB,iCAAiC;AACjC,IAAI,gBAAQ,KAAK,0CAAgB,IAAI,kBAAU,KAAK,8CAAkB,EAAE,CAAC;IACvE,aAAa;IACb,OAAO,CAAC,IAAI,CACV,wJAAwJ,CACzJ,CAAA;AACH,CAAC;AAED,SAAgB,YAAY,CAAC,KAAc;IACzC,IAAI,KAAK,YAAY,UAAU,EAAE,CAAC;QAChC,OAAO,KAAK,CAAA;IACd,CAAC;IAED,OAAO,SAAS,CAAA;AAClB,CAAC;AAED;;;;GAIG;AACH,SAAgB,YAAY,CAAC,KAAc;IACzC,IAAI,KAAK,YAAY,UAAU,EAAE,CAAC;QAChC,OAAO,KAAK,CAAA;IACd,CAAC;IAED,IAAI,WAAW,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;QAC9B,OAAO,IAAI,UAAU,CACnB,KAAK,CAAC,MAAM,EACZ,KAAK,CAAC,UAAU,EAChB,KAAK,CAAC,UAAU,GAAG,UAAU,CAAC,iBAAiB,CAChD,CAAA;IACH,CAAC;IAED,IAAI,KAAK,YAAY,WAAW,EAAE,CAAC;QACjC,OAAO,IAAI,UAAU,CAAC,KAAK,CAAC,CAAA;IAC9B,CAAC;IAED,OAAO,SAAS,CAAA;AAClB,CAAC;AAED,SAAgB,SAAS,CAAC,CAAa,EAAE,CAAa;IACpD,IAAI,CAAC,CAAC,UAAU,KAAK,CAAC,CAAC,UAAU,EAAE,CAAC;QAClC,OAAO,KAAK,CAAA;IACd,CAAC;IAED,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,UAAU,EAAE,CAAC,EAAE,EAAE,CAAC;QACtC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;YAClB,OAAO,KAAK,CAAA;QACd,CAAC;IACH,CAAC;IAED,OAAO,IAAI,CAAA;AACb,CAAC;AAEY,QAAA,SAAS;AACpB,iCAAiC,CAAC,oCAAa,IAAI,wCAAiB,CAAA","sourcesContent":["import { Base64Alphabet } from './uint8array-base64.js'\nimport { ui8ConcatNode, ui8ConcatPonyfill } from './uint8array-concat.js'\nimport {\n  fromBase64Native,\n  fromBase64Node,\n  fromBase64Ponyfill,\n} from './uint8array-from-base64.js'\nimport {\n  toBase64Native,\n  toBase64Node,\n  toBase64Ponyfill,\n} from './uint8array-to-base64.js'\n\nexport type { Base64Alphabet }\n\n// @TODO drop dependency on uint8arrays package once Uint8Array.fromBase64 /\n// Uint8Array.prototype.toBase64 is widely supported, and mark fromBase64 /\n// toBase64 as deprecated. We can also drop NodeJS specific implementations\n// once NodeJS <24 is no longer supported.\n\n/**\n * Encodes a Uint8Array into a base64 string.\n *\n * @returns The base64 encoded string\n */\nexport const toBase64: (\n  bytes: Uint8Array,\n  alphabet?: Base64Alphabet,\n) => string =\n  /* v8 ignore next -- @preserve */ toBase64Native ??\n  toBase64Node ??\n  toBase64Ponyfill\n\n/**\n * Decodes a base64 string into a Uint8Array. This function supports both padded\n * and unpadded base64 strings.\n *\n * @returns The decoded {@link Uint8Array}\n * @throws If the input is not a valid base64 string\n */\nexport const fromBase64: (\n  b64: string,\n  alphabet?: Base64Alphabet,\n) => Uint8Array =\n  /* v8 ignore next -- @preserve */ fromBase64Native ??\n  fromBase64Node ??\n  fromBase64Ponyfill\n\n/* v8 ignore next -- @preserve */\nif (toBase64 === toBase64Ponyfill || fromBase64 === fromBase64Ponyfill) {\n  /*#__PURE__*/\n  console.warn(\n    '[@atproto/lex-data]: Uint8Array.fromBase64 / Uint8Array.prototype.toBase64 not available in this environment. Falling back to ponyfill implementation.',\n  )\n}\n\nexport function ifUint8Array(input: unknown): Uint8Array | undefined {\n  if (input instanceof Uint8Array) {\n    return input\n  }\n\n  return undefined\n}\n\n/**\n * Coerces various binary data representations into a Uint8Array.\n *\n * @return `undefined` if the input could not be coerced into a {@link Uint8Array}.\n */\nexport function asUint8Array(input: unknown): Uint8Array | undefined {\n  if (input instanceof Uint8Array) {\n    return input\n  }\n\n  if (ArrayBuffer.isView(input)) {\n    return new Uint8Array(\n      input.buffer,\n      input.byteOffset,\n      input.byteLength / Uint8Array.BYTES_PER_ELEMENT,\n    )\n  }\n\n  if (input instanceof ArrayBuffer) {\n    return new Uint8Array(input)\n  }\n\n  return undefined\n}\n\nexport function ui8Equals(a: Uint8Array, b: Uint8Array): boolean {\n  if (a.byteLength !== b.byteLength) {\n    return false\n  }\n\n  for (let i = 0; i < a.byteLength; i++) {\n    if (a[i] !== b[i]) {\n      return false\n    }\n  }\n\n  return true\n}\n\nexport const ui8Concat =\n  /* v8 ignore next -- @preserve */ ui8ConcatNode ?? ui8ConcatPonyfill\n"]}
+{"version":3,"file":"uint8array.js","sourceRoot":"","sources":["../src/uint8array.ts"],"names":[],"mappings":";;;AAkGA,oCAMC;AAuBD,oCAkBC;AAkBD,8BAYC;AA9KD,iEAAyE;AACzE,2EAIoC;AACpC,uEAIkC;AAIlC,4EAA4E;AAC5E,2EAA2E;AAC3E,2EAA2E;AAC3E,0CAA0C;AAE1C;;;;;;;;;;;;;;;;;;GAkBG;AACU,QAAA,QAAQ;AAInB,iCAAiC,CAAC,wCAAc;IAChD,sCAAY;IACZ,0CAAgB,CAAA;AAElB;;;;;;;;;;;;;;;;;;;GAmBG;AACU,QAAA,UAAU;AAIrB,iCAAiC,CAAC,4CAAgB;IAClD,0CAAc;IACd,8CAAkB,CAAA;AAEpB,iCAAiC;AACjC,IAAI,gBAAQ,KAAK,0CAAgB,IAAI,kBAAU,KAAK,8CAAkB,EAAE,CAAC;IACvE,aAAa;IACb,OAAO,CAAC,IAAI,CACV,wJAAwJ,CACzJ,CAAA;AACH,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,SAAgB,YAAY,CAAC,KAAc;IACzC,IAAI,KAAK,YAAY,UAAU,EAAE,CAAC;QAChC,OAAO,KAAK,CAAA;IACd,CAAC;IAED,OAAO,SAAS,CAAA;AAClB,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,SAAgB,YAAY,CAAC,KAAc;IACzC,IAAI,KAAK,YAAY,UAAU,EAAE,CAAC;QAChC,OAAO,KAAK,CAAA;IACd,CAAC;IAED,IAAI,WAAW,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;QAC9B,OAAO,IAAI,UAAU,CACnB,KAAK,CAAC,MAAM,EACZ,KAAK,CAAC,UAAU,EAChB,KAAK,CAAC,UAAU,GAAG,UAAU,CAAC,iBAAiB,CAChD,CAAA;IACH,CAAC;IAED,IAAI,KAAK,YAAY,WAAW,EAAE,CAAC;QACjC,OAAO,IAAI,UAAU,CAAC,KAAK,CAAC,CAAA;IAC9B,CAAC;IAED,OAAO,SAAS,CAAA;AAClB,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,SAAgB,SAAS,CAAC,CAAa,EAAE,CAAa;IACpD,IAAI,CAAC,CAAC,UAAU,KAAK,CAAC,CAAC,UAAU,EAAE,CAAC;QAClC,OAAO,KAAK,CAAA;IACd,CAAC;IAED,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,UAAU,EAAE,CAAC,EAAE,EAAE,CAAC;QACtC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;YAClB,OAAO,KAAK,CAAA;QACd,CAAC;IACH,CAAC;IAED,OAAO,IAAI,CAAA;AACb,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACU,QAAA,SAAS;AACpB,iCAAiC,CAAC,oCAAa,IAAI,wCAAiB,CAAA","sourcesContent":["import { Base64Alphabet } from './uint8array-base64.js'\nimport { ui8ConcatNode, ui8ConcatPonyfill } from './uint8array-concat.js'\nimport {\n  fromBase64Native,\n  fromBase64Node,\n  fromBase64Ponyfill,\n} from './uint8array-from-base64.js'\nimport {\n  toBase64Native,\n  toBase64Node,\n  toBase64Ponyfill,\n} from './uint8array-to-base64.js'\n\nexport type { Base64Alphabet }\n\n// @TODO drop dependency on uint8arrays package once Uint8Array.fromBase64 /\n// Uint8Array.prototype.toBase64 is widely supported, and mark fromBase64 /\n// toBase64 as deprecated. We can also drop NodeJS specific implementations\n// once NodeJS <24 is no longer supported.\n\n/**\n * Encodes a Uint8Array into a base64 string.\n *\n * Uses native Uint8Array.prototype.toBase64 when available (Node.js 24+, modern browsers),\n * falling back to Node.js Buffer or a ponyfill implementation.\n *\n * @param bytes - The binary data to encode\n * @param alphabet - The base64 alphabet to use ('base64' or 'base64url'), defaults to 'base64'\n * @returns The base64 encoded string\n *\n * @example\n * ```typescript\n * import { toBase64 } from '@atproto/lex-data'\n *\n * const bytes = new Uint8Array([72, 101, 108, 108, 111])\n * toBase64(bytes)           // 'SGVsbG8='\n * toBase64(bytes, 'base64url')  // 'SGVsbG8' (URL-safe, no padding)\n * ```\n */\nexport const toBase64: (\n  bytes: Uint8Array,\n  alphabet?: Base64Alphabet,\n) => string =\n  /* v8 ignore next -- @preserve */ toBase64Native ??\n  toBase64Node ??\n  toBase64Ponyfill\n\n/**\n * Decodes a base64 string into a Uint8Array.\n *\n * Supports both padded and unpadded base64 strings. Uses native\n * Uint8Array.fromBase64 when available, falling back to Node.js Buffer\n * or a ponyfill implementation.\n *\n * @param b64 - The base64 string to decode\n * @param alphabet - The base64 alphabet to use ('base64' or 'base64url'), defaults to 'base64'\n * @returns The decoded binary data\n * @throws If the input is not a valid base64 string\n *\n * @example\n * ```typescript\n * import { fromBase64 } from '@atproto/lex-data'\n *\n * fromBase64('SGVsbG8=')       // Uint8Array([72, 101, 108, 108, 111])\n * fromBase64('SGVsbG8', 'base64url')  // Same, URL-safe alphabet\n * ```\n */\nexport const fromBase64: (\n  b64: string,\n  alphabet?: Base64Alphabet,\n) => Uint8Array =\n  /* v8 ignore next -- @preserve */ fromBase64Native ??\n  fromBase64Node ??\n  fromBase64Ponyfill\n\n/* v8 ignore next -- @preserve */\nif (toBase64 === toBase64Ponyfill || fromBase64 === fromBase64Ponyfill) {\n  /*#__PURE__*/\n  console.warn(\n    '[@atproto/lex-data]: Uint8Array.fromBase64 / Uint8Array.prototype.toBase64 not available in this environment. Falling back to ponyfill implementation.',\n  )\n}\n\n/**\n * Returns the input if it is a Uint8Array, otherwise returns undefined.\n *\n * @param input - The value to check\n * @returns The input if it's a Uint8Array, otherwise undefined\n *\n * @example\n * ```typescript\n * import { ifUint8Array } from '@atproto/lex-data'\n *\n * ifUint8Array(new Uint8Array([1, 2]))  // Uint8Array([1, 2])\n * ifUint8Array('not binary')            // undefined\n * ifUint8Array(new ArrayBuffer(4))      // undefined\n * ```\n */\nexport function ifUint8Array(input: unknown): Uint8Array | undefined {\n  if (input instanceof Uint8Array) {\n    return input\n  }\n\n  return undefined\n}\n\n/**\n * Coerces various binary data representations into a Uint8Array.\n *\n * Handles the following input types:\n * - `Uint8Array` - Returned as-is\n * - `ArrayBufferView` (e.g., DataView, other TypedArrays) - Converted to Uint8Array\n * - `ArrayBuffer` - Wrapped in a Uint8Array\n *\n * @param input - The value to convert\n * @returns A Uint8Array, or `undefined` if the input could not be converted\n *\n * @example\n * ```typescript\n * import { asUint8Array } from '@atproto/lex-data'\n *\n * asUint8Array(new Uint8Array([1, 2]))     // Uint8Array([1, 2])\n * asUint8Array(new ArrayBuffer(4))         // Uint8Array of length 4\n * asUint8Array(new Int16Array([1, 2]))     // Uint8Array view of the buffer\n * asUint8Array('string')                   // undefined\n * ```\n */\nexport function asUint8Array(input: unknown): Uint8Array | undefined {\n  if (input instanceof Uint8Array) {\n    return input\n  }\n\n  if (ArrayBuffer.isView(input)) {\n    return new Uint8Array(\n      input.buffer,\n      input.byteOffset,\n      input.byteLength / Uint8Array.BYTES_PER_ELEMENT,\n    )\n  }\n\n  if (input instanceof ArrayBuffer) {\n    return new Uint8Array(input)\n  }\n\n  return undefined\n}\n\n/**\n * Compares two Uint8Arrays for byte-by-byte equality.\n *\n * @param a - First Uint8Array to compare\n * @param b - Second Uint8Array to compare\n * @returns `true` if both arrays have the same length and identical bytes\n *\n * @example\n * ```typescript\n * import { ui8Equals } from '@atproto/lex-data'\n *\n * ui8Equals(new Uint8Array([1, 2]), new Uint8Array([1, 2]))  // true\n * ui8Equals(new Uint8Array([1, 2]), new Uint8Array([1, 3]))  // false\n * ui8Equals(new Uint8Array([1]), new Uint8Array([1, 2]))     // false\n * ```\n */\nexport function ui8Equals(a: Uint8Array, b: Uint8Array): boolean {\n  if (a.byteLength !== b.byteLength) {\n    return false\n  }\n\n  for (let i = 0; i < a.byteLength; i++) {\n    if (a[i] !== b[i]) {\n      return false\n    }\n  }\n\n  return true\n}\n\n/**\n * Concatenates multiple Uint8Arrays into a single Uint8Array.\n *\n * Uses Node.js Buffer.concat when available for performance,\n * falling back to a ponyfill implementation.\n *\n * @param arrays - The Uint8Arrays to concatenate\n * @returns A new Uint8Array containing all input bytes in order\n *\n * @example\n * ```typescript\n * import { ui8Concat } from '@atproto/lex-data'\n *\n * const a = new Uint8Array([1, 2])\n * const b = new Uint8Array([3, 4])\n * ui8Concat([a, b])  // Uint8Array([1, 2, 3, 4])\n * ```\n */\nexport const ui8Concat =\n  /* v8 ignore next -- @preserve */ ui8ConcatNode ?? ui8ConcatPonyfill\n"]}

package/dist/utf8.d.ts

@@ -1,6 +1,83 @@
 import { Base64Alphabet } from './uint8array.js';
+/**
+ * Counts the number of grapheme clusters (user-perceived characters) in a string.
+ *
+ * Grapheme clusters represent what users typically think of as "characters",
+ * handling complex cases like:
+ * - Emoji with skin tones and ZWJ sequences (e.g., family emoji)
+ * - Combined characters (e.g., 'e' + combining accent)
+ * - Regional indicator pairs (flag emoji)
+ *
+ * Uses native {@link Intl.Segmenter} when available, falling back to a ponyfill.
+ *
+ * @param str - The string to measure
+ * @returns The number of grapheme clusters
+ *
+ * @example
+ * ```typescript
+ * import { graphemeLen } from '@atproto/lex-data'
+ *
+ * graphemeLen('hello')        // 5
+ * graphemeLen('cafe\u0301')   // 4 (cafe with combining accent)
+ * graphemeLen('\u{1F468}\u{200D}\u{1F469}\u{200D}\u{1F467}\u{200D}\u{1F466}')  // 1 (family emoji)
+ * ```
+ */
 export declare const graphemeLen: (str: string) => number;
+/**
+ * Calculates the UTF-8 byte length of a string.
+ *
+ * Returns the number of bytes the string would occupy when encoded as UTF-8.
+ * This is important for Lexicon validation where schemas specify byte limits.
+ *
+ * Uses Node.js Buffer.byteLength when available for performance,
+ * falling back to a computed implementation.
+ *
+ * @param str - The string to measure
+ * @returns The UTF-8 byte length
+ *
+ * @example
+ * ```typescript
+ * import { utf8Len } from '@atproto/lex-data'
+ *
+ * utf8Len('hello')      // 5 (ASCII: 1 byte per char)
+ * utf8Len('\u00e9')     // 2 (e with accent: 2 bytes)
+ * utf8Len('\u{1F600}')  // 4 (emoji: 4 bytes)
+ * utf8Len('\u{1F468}\u{200D}\u{1F469}\u{200D}\u{1F467}\u{200D}\u{1F466}')  // 25 (family emoji)
+ * ```
+ */
 export declare const utf8Len: (string: string) => number;
+/**
+ * Encodes a UTF-8 string to base64.
+ *
+ * First encodes the string as UTF-8 bytes, then encodes those bytes as base64.
+ *
+ * @param str - The string to encode
+ * @param alphabet - The base64 alphabet to use ('base64' or 'base64url')
+ * @returns The base64-encoded string
+ *
+ * @example
+ * ```typescript
+ * import { utf8ToBase64 } from '@atproto/lex-data'
+ *
+ * utf8ToBase64('Hello')  // 'SGVsbG8='
+ * ```
+ */
 export declare const utf8ToBase64: (str: string, alphabet?: Base64Alphabet) => string;
+/**
+ * Decodes a base64 string to UTF-8.
+ *
+ * Decodes the base64 to bytes, then interprets those bytes as UTF-8 text.
+ *
+ * @param b64 - The base64 string to decode
+ * @param alphabet - The base64 alphabet to use ('base64' or 'base64url')
+ * @returns The decoded UTF-8 string
+ *
+ * @example
+ * ```typescript
+ * import { utf8FromBase64 } from '@atproto/lex-data'
+ *
+ * utf8FromBase64('SGVsbG8=')  // 'Hello'
+ * ```
+ */
 export declare const utf8FromBase64: (b64: string, alphabet?: Base64Alphabet) => string;
 //# sourceMappingURL=utf8.d.ts.map

package/dist/utf8.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utf8.d.ts","sourceRoot":"","sources":["../src/utf8.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAShD,eAAO,MAAM,WAAW,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MACiC,CAAA;AAU5E,eAAO,MAAM,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,MACuB,CAAA;AAEjE,eAAO,MAAM,YAAY,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,cAAc,KAAK,MACK,CAAA;AAE5E,eAAO,MAAM,cAAc,EAAE,CAC3B,GAAG,EAAE,MAAM,EACX,QAAQ,CAAC,EAAE,cAAc,KACtB,MAC2E,CAAA"}
+{"version":3,"file":"utf8.d.ts","sourceRoot":"","sources":["../src/utf8.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAShD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,WAAW,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MACiC,CAAA;AAU5E;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,MACuB,CAAA;AAEjE;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,YAAY,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,cAAc,KAAK,MACK,CAAA;AAE5E;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,cAAc,EAAE,CAC3B,GAAG,EAAE,MAAM,EACX,QAAQ,CAAC,EAAE,cAAc,KACtB,MAC2E,CAAA"}

package/dist/utf8.js

@@ -5,6 +5,29 @@ const utf8_from_base64_js_1 = require("./utf8-from-base64.js");
 const utf8_grapheme_len_js_1 = require("./utf8-grapheme-len.js");
 const utf8_len_js_1 = require("./utf8-len.js");
 const utf8_to_base64_js_1 = require("./utf8-to-base64.js");
+/**
+ * Counts the number of grapheme clusters (user-perceived characters) in a string.
+ *
+ * Grapheme clusters represent what users typically think of as "characters",
+ * handling complex cases like:
+ * - Emoji with skin tones and ZWJ sequences (e.g., family emoji)
+ * - Combined characters (e.g., 'e' + combining accent)
+ * - Regional indicator pairs (flag emoji)
+ *
+ * Uses native {@link Intl.Segmenter} when available, falling back to a ponyfill.
+ *
+ * @param str - The string to measure
+ * @returns The number of grapheme clusters
+ *
+ * @example
+ * ```typescript
+ * import { graphemeLen } from '@atproto/lex-data'
+ *
+ * graphemeLen('hello')        // 5
+ * graphemeLen('cafe\u0301')   // 4 (cafe with combining accent)
+ * graphemeLen('\u{1F468}\u{200D}\u{1F469}\u{200D}\u{1F467}\u{200D}\u{1F466}')  // 1 (family emoji)
+ * ```
+ */
 exports.graphemeLen = 
 /* v8 ignore next -- @preserve */ utf8_grapheme_len_js_1.graphemeLenNative ?? utf8_grapheme_len_js_1.graphemeLenPonyfill;
 /* v8 ignore next -- @preserve */
@@ -12,10 +35,64 @@ if (exports.graphemeLen === utf8_grapheme_len_js_1.graphemeLenPonyfill) {
     /*#__PURE__*/
     console.warn('[@atproto/lex-data]: Intl.Segmenter is not available in this environment. Falling back to ponyfill implementation.');
 }
+/**
+ * Calculates the UTF-8 byte length of a string.
+ *
+ * Returns the number of bytes the string would occupy when encoded as UTF-8.
+ * This is important for Lexicon validation where schemas specify byte limits.
+ *
+ * Uses Node.js Buffer.byteLength when available for performance,
+ * falling back to a computed implementation.
+ *
+ * @param str - The string to measure
+ * @returns The UTF-8 byte length
+ *
+ * @example
+ * ```typescript
+ * import { utf8Len } from '@atproto/lex-data'
+ *
+ * utf8Len('hello')      // 5 (ASCII: 1 byte per char)
+ * utf8Len('\u00e9')     // 2 (e with accent: 2 bytes)
+ * utf8Len('\u{1F600}')  // 4 (emoji: 4 bytes)
+ * utf8Len('\u{1F468}\u{200D}\u{1F469}\u{200D}\u{1F467}\u{200D}\u{1F466}')  // 25 (family emoji)
+ * ```
+ */
 exports.utf8Len = 
 /* v8 ignore next -- @preserve */ utf8_len_js_1.utf8LenNode ?? utf8_len_js_1.utf8LenCompute;
+/**
+ * Encodes a UTF-8 string to base64.
+ *
+ * First encodes the string as UTF-8 bytes, then encodes those bytes as base64.
+ *
+ * @param str - The string to encode
+ * @param alphabet - The base64 alphabet to use ('base64' or 'base64url')
+ * @returns The base64-encoded string
+ *
+ * @example
+ * ```typescript
+ * import { utf8ToBase64 } from '@atproto/lex-data'
+ *
+ * utf8ToBase64('Hello')  // 'SGVsbG8='
+ * ```
+ */
 exports.utf8ToBase64 = 
 /* v8 ignore next -- @preserve */ utf8_to_base64_js_1.utf8ToBase64Node ?? utf8_to_base64_js_1.utf8ToBase64Ponyfill;
+/**
+ * Decodes a base64 string to UTF-8.
+ *
+ * Decodes the base64 to bytes, then interprets those bytes as UTF-8 text.
+ *
+ * @param b64 - The base64 string to decode
+ * @param alphabet - The base64 alphabet to use ('base64' or 'base64url')
+ * @returns The decoded UTF-8 string
+ *
+ * @example
+ * ```typescript
+ * import { utf8FromBase64 } from '@atproto/lex-data'
+ *
+ * utf8FromBase64('SGVsbG8=')  // 'Hello'
+ * ```
+ */
 exports.utf8FromBase64 = 
 /* v8 ignore next -- @preserve */ utf8_from_base64_js_1.utf8FromBase64Node ?? utf8_from_base64_js_1.utf8FromBase64Ponyfill;
 //# sourceMappingURL=utf8.js.map

package/dist/utf8.js.map

@@ -1 +1 @@
-{"version":3,"file":"utf8.js","sourceRoot":"","sources":["../src/utf8.ts"],"names":[],"mappings":";;;AACA,+DAG8B;AAC9B,iEAA+E;AAC/E,+CAA2D;AAC3D,2DAA4E;AAE/D,QAAA,WAAW;AACtB,iCAAiC,CAAC,wCAAiB,IAAI,0CAAmB,CAAA;AAE5E,iCAAiC;AACjC,IAAI,mBAAW,KAAK,0CAAmB,EAAE,CAAC;IACxC,aAAa;IACb,OAAO,CAAC,IAAI,CACV,oHAAoH,CACrH,CAAA;AACH,CAAC;AAEY,QAAA,OAAO;AAClB,iCAAiC,CAAC,yBAAW,IAAI,4BAAc,CAAA;AAEpD,QAAA,YAAY;AACvB,iCAAiC,CAAC,oCAAgB,IAAI,wCAAoB,CAAA;AAE/D,QAAA,cAAc;AAIzB,iCAAiC,CAAC,wCAAkB,IAAI,4CAAsB,CAAA","sourcesContent":["import { Base64Alphabet } from './uint8array.js'\nimport {\n  utf8FromBase64Node,\n  utf8FromBase64Ponyfill,\n} from './utf8-from-base64.js'\nimport { graphemeLenNative, graphemeLenPonyfill } from './utf8-grapheme-len.js'\nimport { utf8LenCompute, utf8LenNode } from './utf8-len.js'\nimport { utf8ToBase64Node, utf8ToBase64Ponyfill } from './utf8-to-base64.js'\n\nexport const graphemeLen: (str: string) => number =\n  /* v8 ignore next -- @preserve */ graphemeLenNative ?? graphemeLenPonyfill\n\n/* v8 ignore next -- @preserve */\nif (graphemeLen === graphemeLenPonyfill) {\n  /*#__PURE__*/\n  console.warn(\n    '[@atproto/lex-data]: Intl.Segmenter is not available in this environment. Falling back to ponyfill implementation.',\n  )\n}\n\nexport const utf8Len: (string: string) => number =\n  /* v8 ignore next -- @preserve */ utf8LenNode ?? utf8LenCompute\n\nexport const utf8ToBase64: (str: string, alphabet?: Base64Alphabet) => string =\n  /* v8 ignore next -- @preserve */ utf8ToBase64Node ?? utf8ToBase64Ponyfill\n\nexport const utf8FromBase64: (\n  b64: string,\n  alphabet?: Base64Alphabet,\n) => string =\n  /* v8 ignore next -- @preserve */ utf8FromBase64Node ?? utf8FromBase64Ponyfill\n"]}
+{"version":3,"file":"utf8.js","sourceRoot":"","sources":["../src/utf8.ts"],"names":[],"mappings":";;;AACA,+DAG8B;AAC9B,iEAA+E;AAC/E,+CAA2D;AAC3D,2DAA4E;AAE5E;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACU,QAAA,WAAW;AACtB,iCAAiC,CAAC,wCAAiB,IAAI,0CAAmB,CAAA;AAE5E,iCAAiC;AACjC,IAAI,mBAAW,KAAK,0CAAmB,EAAE,CAAC;IACxC,aAAa;IACb,OAAO,CAAC,IAAI,CACV,oHAAoH,CACrH,CAAA;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACU,QAAA,OAAO;AAClB,iCAAiC,CAAC,yBAAW,IAAI,4BAAc,CAAA;AAEjE;;;;;;;;;;;;;;;GAeG;AACU,QAAA,YAAY;AACvB,iCAAiC,CAAC,oCAAgB,IAAI,wCAAoB,CAAA;AAE5E;;;;;;;;;;;;;;;GAeG;AACU,QAAA,cAAc;AAIzB,iCAAiC,CAAC,wCAAkB,IAAI,4CAAsB,CAAA","sourcesContent":["import { Base64Alphabet } from './uint8array.js'\nimport {\n  utf8FromBase64Node,\n  utf8FromBase64Ponyfill,\n} from './utf8-from-base64.js'\nimport { graphemeLenNative, graphemeLenPonyfill } from './utf8-grapheme-len.js'\nimport { utf8LenCompute, utf8LenNode } from './utf8-len.js'\nimport { utf8ToBase64Node, utf8ToBase64Ponyfill } from './utf8-to-base64.js'\n\n/**\n * Counts the number of grapheme clusters (user-perceived characters) in a string.\n *\n * Grapheme clusters represent what users typically think of as \"characters\",\n * handling complex cases like:\n * - Emoji with skin tones and ZWJ sequences (e.g., family emoji)\n * - Combined characters (e.g., 'e' + combining accent)\n * - Regional indicator pairs (flag emoji)\n *\n * Uses native {@link Intl.Segmenter} when available, falling back to a ponyfill.\n *\n * @param str - The string to measure\n * @returns The number of grapheme clusters\n *\n * @example\n * ```typescript\n * import { graphemeLen } from '@atproto/lex-data'\n *\n * graphemeLen('hello')        // 5\n * graphemeLen('cafe\\u0301')   // 4 (cafe with combining accent)\n * graphemeLen('\\u{1F468}\\u{200D}\\u{1F469}\\u{200D}\\u{1F467}\\u{200D}\\u{1F466}')  // 1 (family emoji)\n * ```\n */\nexport const graphemeLen: (str: string) => number =\n  /* v8 ignore next -- @preserve */ graphemeLenNative ?? graphemeLenPonyfill\n\n/* v8 ignore next -- @preserve */\nif (graphemeLen === graphemeLenPonyfill) {\n  /*#__PURE__*/\n  console.warn(\n    '[@atproto/lex-data]: Intl.Segmenter is not available in this environment. Falling back to ponyfill implementation.',\n  )\n}\n\n/**\n * Calculates the UTF-8 byte length of a string.\n *\n * Returns the number of bytes the string would occupy when encoded as UTF-8.\n * This is important for Lexicon validation where schemas specify byte limits.\n *\n * Uses Node.js Buffer.byteLength when available for performance,\n * falling back to a computed implementation.\n *\n * @param str - The string to measure\n * @returns The UTF-8 byte length\n *\n * @example\n * ```typescript\n * import { utf8Len } from '@atproto/lex-data'\n *\n * utf8Len('hello')      // 5 (ASCII: 1 byte per char)\n * utf8Len('\\u00e9')     // 2 (e with accent: 2 bytes)\n * utf8Len('\\u{1F600}')  // 4 (emoji: 4 bytes)\n * utf8Len('\\u{1F468}\\u{200D}\\u{1F469}\\u{200D}\\u{1F467}\\u{200D}\\u{1F466}')  // 25 (family emoji)\n * ```\n */\nexport const utf8Len: (string: string) => number =\n  /* v8 ignore next -- @preserve */ utf8LenNode ?? utf8LenCompute\n\n/**\n * Encodes a UTF-8 string to base64.\n *\n * First encodes the string as UTF-8 bytes, then encodes those bytes as base64.\n *\n * @param str - The string to encode\n * @param alphabet - The base64 alphabet to use ('base64' or 'base64url')\n * @returns The base64-encoded string\n *\n * @example\n * ```typescript\n * import { utf8ToBase64 } from '@atproto/lex-data'\n *\n * utf8ToBase64('Hello')  // 'SGVsbG8='\n * ```\n */\nexport const utf8ToBase64: (str: string, alphabet?: Base64Alphabet) => string =\n  /* v8 ignore next -- @preserve */ utf8ToBase64Node ?? utf8ToBase64Ponyfill\n\n/**\n * Decodes a base64 string to UTF-8.\n *\n * Decodes the base64 to bytes, then interprets those bytes as UTF-8 text.\n *\n * @param b64 - The base64 string to decode\n * @param alphabet - The base64 alphabet to use ('base64' or 'base64url')\n * @returns The decoded UTF-8 string\n *\n * @example\n * ```typescript\n * import { utf8FromBase64 } from '@atproto/lex-data'\n *\n * utf8FromBase64('SGVsbG8=')  // 'Hello'\n * ```\n */\nexport const utf8FromBase64: (\n  b64: string,\n  alphabet?: Base64Alphabet,\n) => string =\n  /* v8 ignore next -- @preserve */ utf8FromBase64Node ?? utf8FromBase64Ponyfill\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atproto/lex-data",
-  "version": "0.0.9",
+  "version": "0.0.11",
   "license": "MIT",
   "description": "Core utilities for AT Lexicons",
   "keywords": [
@@ -31,7 +31,7 @@
       "types": "./dist/index.d.ts",
       "browser": "./dist/index.js",
       "import": "./dist/index.js",
-      "require": "./dist/index.js"
+      "default": "./dist/index.js"
     }
   },
   "dependencies": {

package/src/blob.ts

@@ -3,7 +3,28 @@ import { LexValue } from './lex.js'
 import { isPlainObject, isPlainProto } from './object.js'
 
 /**
- * @note {@link BlobRef} is just a {@link LexMap} with a specific shape.
+ * Reference to binary data (like images, videos, etc.) in the AT Protocol data model.
+ *
+ * A BlobRef is a {@link LexMap} with a specific structure that identifies binary
+ * content by its content hash (CID), along with metadata about the content type
+ * and size.
+ *
+ * @typeParam Ref - The type of CID reference, defaults to any {@link Cid}
+ *
+ * @example
+ * ```typescript
+ * import type { BlobRef } from '@atproto/lex-data'
+ *
+ * const imageRef: BlobRef = {
+ *   $type: 'blob',
+ *   mimeType: 'image/jpeg',
+ *   ref: cid,  // CID of the blob content
+ *   size: 12345
+ * }
+ * ```
+ *
+ * @see {@link isBlobRef} to check if a value is a valid BlobRef
+ * @see {@link LegacyBlobRef} for the older blob reference format
  */
 export type BlobRef<Ref extends Cid = Cid> = {
   $type: 'blob'
@@ -12,17 +33,25 @@ export type BlobRef<Ref extends Cid = Cid> = {
   size: number
 }
 
+/**
+ * Options for validating a {@link BlobRef}.
+ */
 export type BlobRefCheckOptions = {
   /**
    * If `false`, skips strict CID validation of {@link BlobRef.ref}, allowing
    * any valid CID. Otherwise, validates that the CID is v1, uses the raw
    * multicodec, and has a sha256 multihash.
    *
-   * @defaults to `true`
+   * @default true
    */
   strict?: boolean
 }
 
+/**
+ * Infers the BlobRef type based on the check options.
+ *
+ * @typeParam TOptions - The options used for checking
+ */
 export type InferCheckedBlobRef<TOptions extends BlobRefCheckOptions> =
   TOptions extends { strict: false }
     ? BlobRef
@@ -30,6 +59,34 @@ export type InferCheckedBlobRef<TOptions extends BlobRefCheckOptions> =
       ? BlobRef
       : BlobRef<RawCid>
 
+/**
+ * Type guard to check if a value is a valid {@link BlobRef}.
+ *
+ * Validates the structure of the input including:
+ * - `$type` must be `'blob'`
+ * - `mimeType` must be a valid MIME type string (containing '/')
+ * - `size` must be a non-negative safe integer
+ * - `ref` must be a valid CID (strict validation by default)
+ *
+ * @param input - The value to check
+ * @param options - Optional validation options
+ * @returns `true` if the input is a valid BlobRef
+ *
+ * @example
+ * ```typescript
+ * import { isBlobRef } from '@atproto/lex-data'
+ *
+ * if (isBlobRef(data)) {
+ *   console.log(data.mimeType)  // e.g., 'image/jpeg'
+ *   console.log(data.size)      // e.g., 12345
+ * }
+ *
+ * // Allow any valid CID (not just raw CIDs)
+ * if (isBlobRef(data, { strict: false })) {
+ *   // ...
+ * }
+ * ```
+ */
 export function isBlobRef(input: unknown): input is BlobRef<RawCid>
 export function isBlobRef<TOptions extends BlobRefCheckOptions>(
   input: unknown,
@@ -89,13 +146,53 @@ export function isBlobRef(
 }
 
 /**
- * @note {@link LegacyBlobRef} is just a {@link LexMap} with a specific shape.
+ * Legacy format for blob references used in older AT Protocol data.
+ *
+ * This is the older format that stores the CID as a string rather than
+ * as a structured CID object. New code should use {@link BlobRef} instead.
+ *
+ * @example
+ * ```typescript
+ * import type { LegacyBlobRef } from '@atproto/lex-data'
+ *
+ * const legacyRef: LegacyBlobRef = {
+ *   cid: 'bafyreib...',
+ *   mimeType: 'image/jpeg'
+ * }
+ * ```
+ *
+ * @see {@link isLegacyBlobRef} to check if a value is a LegacyBlobRef
+ * @see {@link BlobRef} for the current blob reference format
+ * @deprecated Use {@link BlobRef} for new code
  */
 export type LegacyBlobRef = {
   cid: string
   mimeType: string
 }
 
+/**
+ * Type guard to check if a value is a valid {@link LegacyBlobRef}.
+ *
+ * Validates the structure of the input:
+ * - `cid` must be a valid CID string
+ * - `mimeType` must be a non-empty string
+ * - No additional properties allowed
+ *
+ * @param input - The value to check
+ * @returns `true` if the input is a valid LegacyBlobRef
+ *
+ * @example
+ * ```typescript
+ * import { isLegacyBlobRef } from '@atproto/lex-data'
+ *
+ * if (isLegacyBlobRef(data)) {
+ *   console.log(data.cid)       // CID as string
+ *   console.log(data.mimeType)  // e.g., 'image/jpeg'
+ * }
+ * ```
+ *
+ * @see {@link isBlobRef} for checking the current blob reference format
+ */
 export function isLegacyBlobRef(input: unknown): input is LegacyBlobRef {
   if (!isPlainObject(input)) {
     return false
@@ -123,13 +220,24 @@ export function isLegacyBlobRef(input: unknown): input is LegacyBlobRef {
   return true
 }
 
+/**
+ * Options for enumerating blob references within a {@link LexValue}.
+ */
 export type EnumBlobRefsOptions = BlobRefCheckOptions & {
   /**
-   * @defaults to `false`
+   * If `true`, also yields {@link LegacyBlobRef} objects in addition to
+   * {@link BlobRef} objects.
+   *
+   * @default false
    */
   allowLegacy?: boolean
 }
 
+/**
+ * Infers the yielded type of {@link enumBlobRefs} based on options.
+ *
+ * @typeParam TOptions - The options used for enumeration
+ */
 export type InferEnumBlobRefs<TOptions extends EnumBlobRefsOptions> =
   TOptions extends { allowLegacy: true }
     ? InferCheckedBlobRef<TOptions> | LegacyBlobRef
@@ -138,8 +246,37 @@ export type InferEnumBlobRefs<TOptions extends EnumBlobRefsOptions> =
       : InferCheckedBlobRef<TOptions>
 
 /**
- * Enumerates all {@link BlobRef}s (and, optionally, {@link LegacyBlobRef}s)
- * found within a {@link LexValue}.
+ * Generator that enumerates all {@link BlobRef}s (and, optionally,
+ * {@link LegacyBlobRef}s) found within a {@link LexValue}.
+ *
+ * Performs a deep traversal of the input value, yielding any blob references
+ * found. This is useful for extracting all media references from a record.
+ *
+ * @param input - The LexValue to search for blob references
+ * @param options - Optional configuration for the enumeration
+ * @yields Each blob reference found in the input
+ *
+ * @example
+ * ```typescript
+ * import { enumBlobRefs } from '@atproto/lex-data'
+ *
+ * const record = {
+ *   text: 'Hello',
+ *   images: [
+ *     { $type: 'blob', mimeType: 'image/jpeg', ref: cid1, size: 1000 },
+ *     { $type: 'blob', mimeType: 'image/png', ref: cid2, size: 2000 }
+ *   ]
+ * }
+ *
+ * for (const blobRef of enumBlobRefs(record)) {
+ *   console.log(blobRef.mimeType, blobRef.size)
+ * }
+ *
+ * // Include legacy blob references
+ * for (const ref of enumBlobRefs(record, { allowLegacy: true })) {
+ *   // ref may be BlobRef or LegacyBlobRef
+ * }
+ * ```
  */
 export function enumBlobRefs(
   input: LexValue,

package/src/cid-implementation.test.ts

@@ -1,5 +1,3 @@
-/* eslint-disable import/no-deprecated */
-
 import { base32 } from 'multiformats/bases/base32'
 import { CID } from 'multiformats/cid'
 import { create as createDigest } from 'multiformats/hashes/digest'
@@ -75,25 +73,19 @@ describe(BytesCid, () => {
  */
 export function createCustomCid<
   TVersion extends 0 | 1,
-  TCode extends number,
-  TMultihashCode extends number,
+  TCodec extends number,
+  THashCode extends number,
 >(
   version: TVersion,
-  code: TCode,
-  multihashCode: TMultihashCode,
+  code: TCodec,
+  hashCode: THashCode,
   digest: Uint8Array,
-): Cid<TVersion, TCode, TMultihashCode> {
+): Cid<TVersion, TCodec, THashCode> {
   return {
     version,
     code,
-    multihash: { code: multihashCode, digest },
-    bytes: new Uint8Array([
-      version,
-      code,
-      multihashCode,
-      digest.length,
-      ...digest,
-    ]),
+    multihash: { code: hashCode, digest },
+    bytes: new Uint8Array([version, code, hashCode, digest.length, ...digest]),
     toString,
     equals,
   }