@atproto/lex-data 0.0.14 → 0.0.15

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @atproto/lex-data
 
+## 0.0.15
+
+### Patch Changes
+
+- [#4828](https://github.com/bluesky-social/atproto/pull/4828) [`c62651d`](https://github.com/bluesky-social/atproto/commit/c62651dd69f1e18bd854b66e499b91fee9eaa856) Thanks [@matthieusieben](https://github.com/matthieusieben)! - Export new utility functions for working with `BlobRef`: `getBlobCid`, `getBlobCidString`, `getBlobMime`, and `getBlobSize`.
+
+- [#4835](https://github.com/bluesky-social/atproto/pull/4835) [`f6f100c`](https://github.com/bluesky-social/atproto/commit/f6f100c33700a7ff58a1458109cc7420131feed0) Thanks [@matthieusieben](https://github.com/matthieusieben)! - Add `utf8FromBytes` that decodes a byte array containing a utf-8 string
+
+- [#4828](https://github.com/bluesky-social/atproto/pull/4828) [`c62651d`](https://github.com/bluesky-social/atproto/commit/c62651dd69f1e18bd854b66e499b91fee9eaa856) Thanks [@matthieusieben](https://github.com/matthieusieben)! - Defines `BlobRef` as a union of `TypedBlobRef` and `LegacyBlobRef` to allow for seamless handling of both types of blob references.
+
+- [#4828](https://github.com/bluesky-social/atproto/pull/4828) [`c62651d`](https://github.com/bluesky-social/atproto/commit/c62651dd69f1e18bd854b66e499b91fee9eaa856) Thanks [@matthieusieben](https://github.com/matthieusieben)! - Accept legacy blob references in non-strict mode. Legacy blob references (objects with `cid` and `mimeType` properties) are now accepted when `strict: false`, which is the default behavior when `strictResponseProcessing` is disabled on the Client.
+
+  BREAKING: The `allowLegacy` option has been removed from the blob schema builder, and legacy blobs are now handled automatically based on the strictness mode: in strict mode they are rejected, and in non-strict mode they are accepted. Consumers should stop passing `allowLegacy` and rely on strictness configuration instead. Likewise, CLI consumers should stop using the removed `--allowLegacyBlobs` flag and use the default strict/non-strict behavior.
+
 ## 0.0.14
 
 ### Patch Changes

package/dist/blob.d.ts

@@ -1,19 +1,114 @@
 import { Cid, RawCid } from './cid.js';
 import { LexValue } from './lex.js';
+/**
+ * Reference to binary data (like images, videos, etc.) in the AT Protocol data
+ * model.
+ *
+ * This type represents a reference to a blob of binary data, identified by its
+ * content hash (CID) and accompanied by metadata such as MIME type and size.
+ *
+ * The {@link BlobRef} type is a union of the current {@link TypedBlobRef}
+ * format and the legacy {@link LegacyBlobRef} format.
+ */
+export type BlobRef<Ref extends Cid = Cid> = TypedBlobRef<Ref> | LegacyBlobRef;
+/**
+ * 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.
+     *
+     * @default true
+     */
+    strict?: boolean;
+};
+/**
+ * Type guard to check if a value is a valid {@link BlobRef}, which can be
+ * either a {@link TypedBlobRef} or a {@link LegacyBlobRef}. By default, strict
+ * CID validation is applied to ensure that the CID in the blob reference is in
+ * the expected format for the AT Protocol, but this can be relaxed with the
+ * `strict: false` option.
+ */
+export declare function isBlobRef(input: unknown): input is BlobRef<RawCid>;
+export declare function isBlobRef<TOptions extends BlobRefCheckOptions>(input: unknown, options: TOptions): input is LegacyBlobRef | InferTypedBlobRef<TOptions>;
+export declare function isBlobRef(input: unknown, options?: BlobRefCheckOptions): input is BlobRef<RawCid>;
+/**
+ * Extracts the MIME type from a {@link BlobRef}.
+ *
+ * @example
+ * ```ts
+ * const mimeType = getBlobMime(blobRef)
+ * console.log(mimeType)  // e.g., 'image/jpeg'
+ * ```
+ */
+export declare function getBlobMime(blob: BlobRef): string;
+export declare function getBlobMime(blob?: BlobRef): string | undefined;
+/**
+ * Extracts the size (in bytes) from a {@link TypedBlobRef}. For
+ * {@link LegacyBlobRef}, size information is not available, so this function
+ * returns `undefined` for legacy refs.
+ *
+ * @note The size property, in blob refs, cannot be 100% trusted since the PDS
+ * might not have a local copy of the blob (to check the size against) and might
+ * just be passing through the blob ref from the client without validating it.
+ * So, while this function can be useful for getting size information when
+ * available, it should not be solely relied upon for critical functionality
+ * without additional validation.
+ *
+ * @example
+ * ```ts
+ * const size = getBlobSize(blobRef)
+ * if (size !== undefined) {
+ *   console.log(`Blob size: ${size} bytes`)
+ * } else {
+ *   console.log('Size information not available for legacy blob ref')
+ * }
+ * ```
+ */
+export declare function getBlobSize(blob: BlobRef): number | undefined;
+/**
+ * Extracts the {@link Cid} from a {@link BlobRef}.
+ *
+ * @throws If the input input is a {@link LegacyBlobRef} with an invalid CID string
+ * @example
+ * ```ts
+ * const cid = getBlobCid(blobRef)
+ * console.log(cid.bytes)
+ * ```
+ */
+export declare function getBlobCid(blob: BlobRef): Cid;
+export declare function getBlobCid(blob?: BlobRef): Cid | undefined;
+/**
+ * Extracts the CID string from a {@link BlobRef}.
+ *
+ * This is similar to `getBlobCid(blob).toString()` but is more optimized since
+ * the CID string is already available in the legacy format and we can avoid
+ * parsing it into a CID object just to convert it back to a string.
+ *
+ * @example
+ * ```ts
+ * const cidString = getBlobCidString(blobRef)
+ * console.log(cidString)
+ * ```
+ */
+export declare function getBlobCidString(blob: BlobRef): string;
+export declare function getBlobCidString(blob?: BlobRef): string | undefined;
 /**
  * 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.
+ * A {@link TypedBlobRef} 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'
+ * import type { TypedBlobRef } from '@atproto/lex-data'
  *
- * const imageRef: BlobRef = {
+ * const imageRef: TypedBlobRef = {
  *   $type: 'blob',
  *   mimeType: 'image/jpeg',
  *   ref: cid,  // CID of the blob content
@@ -21,38 +116,25 @@ import { LexValue } from './lex.js';
  * }
  * ```
  *
- * @see {@link isBlobRef} to check if a value is a valid BlobRef
+ * @see {@link isTypedBlobRef} to check if a value is a valid {@link TypedBlobRef}
  * @see {@link LegacyBlobRef} for the older blob reference format
  */
-export type BlobRef<Ref extends Cid = Cid> = {
+export type TypedBlobRef<Ref extends Cid = Cid> = {
     $type: 'blob';
     mimeType: string;
     ref: Ref;
     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.
-     *
-     * @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 {
+export type InferTypedBlobRef<TOptions extends BlobRefCheckOptions> = TOptions extends {
     strict: false;
-} ? BlobRef : {
+} ? TypedBlobRef : {
     strict: boolean;
-} extends TOptions ? BlobRef : BlobRef<RawCid>;
+} extends TOptions ? TypedBlobRef : TypedBlobRef<RawCid>;
 /**
  * Type guard to check if a value is a valid {@link BlobRef}.
  *
@@ -68,22 +150,22 @@ export type InferCheckedBlobRef<TOptions extends BlobRefCheckOptions> = TOptions
  *
  * @example
  * ```typescript
- * import { isBlobRef } from '@atproto/lex-data'
+ * import { isTypedBlobRef } from '@atproto/lex-data'
  *
- * if (isBlobRef(data)) {
+ * if (isTypedBlobRef(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 })) {
+ * if (isTypedBlobRef(data, { strict: false })) {
  *   // ...
  * }
  * ```
  */
-export declare function isBlobRef(input: unknown): input is BlobRef<RawCid>;
-export declare function isBlobRef<TOptions extends BlobRefCheckOptions>(input: unknown, options: TOptions): input is InferCheckedBlobRef<TOptions>;
-export declare function isBlobRef(input: unknown, options?: BlobRefCheckOptions): input is BlobRef;
+export declare function isTypedBlobRef(input: unknown): input is TypedBlobRef<RawCid>;
+export declare function isTypedBlobRef<TOptions extends BlobRefCheckOptions>(input: unknown, options: TOptions): input is InferTypedBlobRef<TOptions>;
+export declare function isTypedBlobRef(input: unknown, options?: BlobRefCheckOptions): input is TypedBlobRef<RawCid>;
 /**
  * Legacy format for blob references used in older AT Protocol data.
  *
@@ -116,9 +198,6 @@ export type LegacyBlobRef = {
  * - `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'
@@ -129,9 +208,9 @@ export type LegacyBlobRef = {
  * }
  * ```
  *
- * @see {@link isBlobRef} for checking the current blob reference format
+ * @see {@link isTypedBlobRef} for checking the current blob reference format
  */
-export declare function isLegacyBlobRef(input: unknown): input is LegacyBlobRef;
+export declare function isLegacyBlobRef(input: unknown, options?: BlobRefCheckOptions): input is LegacyBlobRef;
 /**
  * Options for enumerating blob references within a {@link LexValue}.
  */
@@ -151,9 +230,9 @@ export type EnumBlobRefsOptions = BlobRefCheckOptions & {
  */
 export type InferEnumBlobRefs<TOptions extends EnumBlobRefsOptions> = TOptions extends {
     allowLegacy: true;
-} ? InferCheckedBlobRef<TOptions> | LegacyBlobRef : {
+} ? InferTypedBlobRef<TOptions> | LegacyBlobRef : {
     allowLegacy: boolean;
-} extends TOptions ? InferCheckedBlobRef<TOptions> | LegacyBlobRef : InferCheckedBlobRef<TOptions>;
+} extends TOptions ? InferTypedBlobRef<TOptions> | LegacyBlobRef : InferTypedBlobRef<TOptions>;
 /**
  * Generator that enumerates all {@link BlobRef}s (and, optionally,
  * {@link LegacyBlobRef}s) found within a {@link LexValue}.
@@ -182,12 +261,12 @@ export type InferEnumBlobRefs<TOptions extends EnumBlobRefsOptions> = TOptions e
  * }
  *
  * // Include legacy blob references
- * for (const ref of enumBlobRefs(record, { allowLegacy: true })) {
- *   // ref may be BlobRef or LegacyBlobRef
+ * for (const ref of enumBlobRefs(record, { allowLegacy: true, strict: false })) {
+ *   // ref may be BlobRef or LegacyBlobRef, with relaxed CID validation
  * }
  * ```
  */
 export declare function enumBlobRefs(input: LexValue): Generator<BlobRef<RawCid>, void, unknown>;
 export declare function enumBlobRefs<TOptions extends EnumBlobRefsOptions>(input: LexValue, options: TOptions): Generator<InferEnumBlobRefs<TOptions>, void, unknown>;
-export declare function enumBlobRefs(input: LexValue, options?: EnumBlobRefsOptions): Generator<BlobRef | LegacyBlobRef, void, unknown>;
+export declare function enumBlobRefs(input: LexValue, options?: EnumBlobRefsOptions): Generator<BlobRef, void, unknown>;
 //# sourceMappingURL=blob.d.ts.map

package/dist/blob.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"blob.d.ts","sourceRoot":"","sources":["../src/blob.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,EAA4B,MAAM,UAAU,CAAA;AAChE,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAA;AAOnC;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,MAAM,OAAO,CAAC,GAAG,SAAS,GAAG,GAAG,GAAG,IAAI;IAC3C,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,MAAM,CAAA;IAChB,GAAG,EAAE,GAAG,CAAA;IACR,IAAI,EAAE,MAAM,CAAA;CACb,CAAA;AAED;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAChC;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,OAAO,CAAA;CACjB,CAAA;AAED;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,CAAC,QAAQ,SAAS,mBAAmB,IAClE,QAAQ,SAAS;IAAE,MAAM,EAAE,KAAK,CAAA;CAAE,GAC9B,OAAO,GACP;IAAE,MAAM,EAAE,OAAO,CAAA;CAAE,SAAS,QAAQ,GAClC,OAAO,GACP,OAAO,CAAC,MAAM,CAAC,CAAA;AAEvB;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC,CAAA;AACnE,wBAAgB,SAAS,CAAC,QAAQ,SAAS,mBAAmB,EAC5D,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,QAAQ,GAChB,KAAK,IAAI,mBAAmB,CAAC,QAAQ,CAAC,CAAA;AACzC,wBAAgB,SAAS,CACvB,KAAK,EAAE,OAAO,EACd,OAAO,CAAC,EAAE,mBAAmB,GAC5B,KAAK,IAAI,OAAO,CAAA;AAqDnB;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,GAAG,EAAE,MAAM,CAAA;IACX,QAAQ,EAAE,MAAM,CAAA;CACjB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,aAAa,CAyBtE;AAED;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG,mBAAmB,GAAG;IACtD;;;;;OAKG;IACH,WAAW,CAAC,EAAE,OAAO,CAAA;CACtB,CAAA;AAED;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,CAAC,QAAQ,SAAS,mBAAmB,IAChE,QAAQ,SAAS;IAAE,WAAW,EAAE,IAAI,CAAA;CAAE,GAClC,mBAAmB,CAAC,QAAQ,CAAC,GAAG,aAAa,GAC7C;IAAE,WAAW,EAAE,OAAO,CAAA;CAAE,SAAS,QAAQ,GACvC,mBAAmB,CAAC,QAAQ,CAAC,GAAG,aAAa,GAC7C,mBAAmB,CAAC,QAAQ,CAAC,CAAA;AAErC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,QAAQ,GACd,SAAS,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,CAAA;AAC5C,wBAAgB,YAAY,CAAC,QAAQ,SAAS,mBAAmB,EAC/D,KAAK,EAAE,QAAQ,EACf,OAAO,EAAE,QAAQ,GAChB,SAAS,CAAC,iBAAiB,CAAC,QAAQ,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,CAAA;AACxD,wBAAgB,YAAY,CAC1B,KAAK,EAAE,QAAQ,EACf,OAAO,CAAC,EAAE,mBAAmB,GAC5B,SAAS,CAAC,OAAO,GAAG,aAAa,EAAE,IAAI,EAAE,OAAO,CAAC,CAAA"}
+{"version":3,"file":"blob.d.ts","sourceRoot":"","sources":["../src/blob.ts"],"names":[],"mappings":"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"}

package/dist/blob.js

@@ -1,14 +1,73 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isBlobRef = isBlobRef;
+exports.getBlobMime = getBlobMime;
+exports.getBlobSize = getBlobSize;
+exports.getBlobCid = getBlobCid;
+exports.getBlobCidString = getBlobCidString;
+exports.isTypedBlobRef = isTypedBlobRef;
 exports.isLegacyBlobRef = isLegacyBlobRef;
 exports.enumBlobRefs = enumBlobRefs;
 const cid_js_1 = require("./cid.js");
 const object_js_1 = require("./object.js");
+/**
+ * Options to use with {@link ifCid}, {@link validateCidString}, and related CID
+ * validation functions when validating CIDs in BlobRefs, in strict mode. This
+ * ensures that the CID is a {@link RawCid} (CID v1, raw multicodec, sha256
+ * multihash), which is the expected format for blob references in the AT
+ * Protocol data model.
+ */
+const STRICT_CID_CHECK_OPTIONS = { flavor: 'raw' };
 // Number.isSafeInteger is actually safe to use with non-number values, so we
 // can use it as a type guard.
 const isSafeInteger = Number.isSafeInteger;
 function isBlobRef(input, options) {
+    return input?.$type === 'blob'
+        ? isTypedBlobRef(input, options)
+        : isLegacyBlobRef(input, options);
+}
+function getBlobMime(blob) {
+    return blob?.mimeType;
+}
+/**
+ * Extracts the size (in bytes) from a {@link TypedBlobRef}. For
+ * {@link LegacyBlobRef}, size information is not available, so this function
+ * returns `undefined` for legacy refs.
+ *
+ * @note The size property, in blob refs, cannot be 100% trusted since the PDS
+ * might not have a local copy of the blob (to check the size against) and might
+ * just be passing through the blob ref from the client without validating it.
+ * So, while this function can be useful for getting size information when
+ * available, it should not be solely relied upon for critical functionality
+ * without additional validation.
+ *
+ * @example
+ * ```ts
+ * const size = getBlobSize(blobRef)
+ * if (size !== undefined) {
+ *   console.log(`Blob size: ${size} bytes`)
+ * } else {
+ *   console.log('Size information not available for legacy blob ref')
+ * }
+ * ```
+ */
+function getBlobSize(blob) {
+    if ('$type' in blob && blob.size >= 0)
+        return blob.size;
+    // LegacyBlobRef doesn't have size information
+    return undefined;
+}
+function getBlobCid(blob) {
+    if (!blob)
+        return undefined;
+    return '$type' in blob ? blob.ref : (0, cid_js_1.parseCid)(blob.cid);
+}
+function getBlobCidString(blob) {
+    if (!blob)
+        return undefined;
+    return '$type' in blob ? blob.ref.toString() : blob.cid;
+}
+function isTypedBlobRef(input, options) {
     if (!(0, object_js_1.isPlainObject)(input)) {
         return false;
     }
@@ -40,7 +99,7 @@ function isBlobRef(input, options) {
     }
     const cid = (0, cid_js_1.ifCid)(ref, 
     // Strict unless explicitly disabled
-    options?.strict === false ? undefined : { flavor: 'raw' });
+    options?.strict === false ? undefined : STRICT_CID_CHECK_OPTIONS);
     if (!cid) {
         return false;
     }
@@ -54,9 +113,6 @@ function isBlobRef(input, options) {
  * - `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'
@@ -67,9 +123,9 @@ function isBlobRef(input, options) {
  * }
  * ```
  *
- * @see {@link isBlobRef} for checking the current blob reference format
+ * @see {@link isTypedBlobRef} for checking the current blob reference format
  */
-function isLegacyBlobRef(input) {
+function isLegacyBlobRef(input, options) {
     if (!(0, object_js_1.isPlainObject)(input)) {
         return false;
     }
@@ -85,7 +141,7 @@ function isLegacyBlobRef(input) {
             return false;
         }
     }
-    if (!(0, cid_js_1.validateCidString)(cid)) {
+    if (!(0, cid_js_1.validateCidString)(cid, options?.strict === false ? undefined : STRICT_CID_CHECK_OPTIONS)) {
         return false;
     }
     return true;
@@ -112,10 +168,10 @@ function* enumBlobRefs(input, options) {
                 if (visited.has(value))
                     continue;
                 visited.add(value);
-                if (isBlobRef(value, options)) {
+                if (isTypedBlobRef(value, options)) {
                     yield value;
                 }
-                else if (includeLegacy && isLegacyBlobRef(value)) {
+                else if (includeLegacy && isLegacyBlobRef(value, options)) {
                     yield value;
                 }
                 else {

package/dist/blob.js.map

@@ -1 +1 @@
-{"version":3,"file":"blob.js","sourceRoot":"","sources":["../src/blob.ts"],"names":[],"mappings":"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","sourcesContent":["import { Cid, RawCid, ifCid, validateCidString } from './cid.js'\nimport { LexValue } from './lex.js'\nimport { isPlainObject, isPlainProto } from './object.js'\n\n// Number.isSafeInteger is actually safe to use with non-number values, so we\n// can use it as a type guard.\nconst isSafeInteger = Number.isSafeInteger as (v: unknown) => v is number\n\n/**\n * Reference to binary data (like images, videos, etc.) in the AT Protocol data model.\n *\n * A BlobRef is a {@link LexMap} with a specific structure that identifies binary\n * content by its content hash (CID), along with metadata about the content type\n * and size.\n *\n * @typeParam Ref - The type of CID reference, defaults to any {@link Cid}\n *\n * @example\n * ```typescript\n * import type { BlobRef } from '@atproto/lex-data'\n *\n * const imageRef: BlobRef = {\n *   $type: 'blob',\n *   mimeType: 'image/jpeg',\n *   ref: cid,  // CID of the blob content\n *   size: 12345\n * }\n * ```\n *\n * @see {@link isBlobRef} to check if a value is a valid BlobRef\n * @see {@link LegacyBlobRef} for the older blob reference format\n */\nexport type BlobRef<Ref extends Cid = Cid> = {\n  $type: 'blob'\n  mimeType: string\n  ref: Ref\n  size: number\n}\n\n/**\n * Options for validating a {@link BlobRef}.\n */\nexport type BlobRefCheckOptions = {\n  /**\n   * If `false`, skips strict CID validation of {@link BlobRef.ref}, allowing\n   * any valid CID. Otherwise, validates that the CID is v1, uses the raw\n   * multicodec, and has a sha256 multihash.\n   *\n   * @default true\n   */\n  strict?: boolean\n}\n\n/**\n * Infers the BlobRef type based on the check options.\n *\n * @typeParam TOptions - The options used for checking\n */\nexport type InferCheckedBlobRef<TOptions extends BlobRefCheckOptions> =\n  TOptions extends { strict: false }\n    ? BlobRef\n    : { strict: boolean } extends TOptions\n      ? BlobRef\n      : BlobRef<RawCid>\n\n/**\n * Type guard to check if a value is a valid {@link BlobRef}.\n *\n * Validates the structure of the input including:\n * - `$type` must be `'blob'`\n * - `mimeType` must be a valid MIME type string (containing '/')\n * - `size` must be a non-negative safe integer\n * - `ref` must be a valid CID (strict validation by default)\n *\n * @param input - The value to check\n * @param options - Optional validation options\n * @returns `true` if the input is a valid BlobRef\n *\n * @example\n * ```typescript\n * import { isBlobRef } from '@atproto/lex-data'\n *\n * if (isBlobRef(data)) {\n *   console.log(data.mimeType)  // e.g., 'image/jpeg'\n *   console.log(data.size)      // e.g., 12345\n * }\n *\n * // Allow any valid CID (not just raw CIDs)\n * if (isBlobRef(data, { strict: false })) {\n *   // ...\n * }\n * ```\n */\nexport function isBlobRef(input: unknown): input is BlobRef<RawCid>\nexport function isBlobRef<TOptions extends BlobRefCheckOptions>(\n  input: unknown,\n  options: TOptions,\n): input is InferCheckedBlobRef<TOptions>\nexport function isBlobRef(\n  input: unknown,\n  options?: BlobRefCheckOptions,\n): input is BlobRef\nexport function isBlobRef(\n  input: unknown,\n  options?: BlobRefCheckOptions,\n): input is BlobRef {\n  if (!isPlainObject(input)) {\n    return false\n  }\n\n  if (input?.$type !== 'blob') {\n    return false\n  }\n\n  const { mimeType, size, ref } = input\n  // @NOTE Very basic mime validation\n  if (typeof mimeType !== 'string' || !mimeType.includes('/')) {\n    return false\n  }\n\n  if (size === -1 && options?.strict === false) {\n    // In non-strict mode, allow size to be -1 to accommodate legacy blob refs\n    // that don't include size information.\n  } else if (!isSafeInteger(size) || size < 0) {\n    return false\n  }\n\n  if (typeof ref !== 'object' || ref === null) {\n    return false\n  }\n\n  for (const key in input) {\n    if (\n      key !== '$type' &&\n      key !== 'mimeType' &&\n      key !== 'ref' &&\n      key !== 'size'\n    ) {\n      return false\n    }\n  }\n\n  const cid = ifCid(\n    ref,\n    // Strict unless explicitly disabled\n    options?.strict === false ? undefined : { flavor: 'raw' },\n  )\n  if (!cid) {\n    return false\n  }\n\n  return true\n}\n\n/**\n * Legacy format for blob references used in older AT Protocol data.\n *\n * This is the older format that stores the CID as a string rather than\n * as a structured CID object. New code should use {@link BlobRef} instead.\n *\n * @example\n * ```typescript\n * import type { LegacyBlobRef } from '@atproto/lex-data'\n *\n * const legacyRef: LegacyBlobRef = {\n *   cid: 'bafyreib...',\n *   mimeType: 'image/jpeg'\n * }\n * ```\n *\n * @see {@link isLegacyBlobRef} to check if a value is a LegacyBlobRef\n * @see {@link BlobRef} for the current blob reference format\n * @deprecated Use {@link BlobRef} for new code\n */\nexport type LegacyBlobRef = {\n  cid: string\n  mimeType: string\n}\n\n/**\n * Type guard to check if a value is a valid {@link LegacyBlobRef}.\n *\n * Validates the structure of the input:\n * - `cid` must be a valid CID string\n * - `mimeType` must be a non-empty string\n * - No additional properties allowed\n *\n * @param input - The value to check\n * @returns `true` if the input is a valid LegacyBlobRef\n *\n * @example\n * ```typescript\n * import { isLegacyBlobRef } from '@atproto/lex-data'\n *\n * if (isLegacyBlobRef(data)) {\n *   console.log(data.cid)       // CID as string\n *   console.log(data.mimeType)  // e.g., 'image/jpeg'\n * }\n * ```\n *\n * @see {@link isBlobRef} for checking the current blob reference format\n */\nexport function isLegacyBlobRef(input: unknown): input is LegacyBlobRef {\n  if (!isPlainObject(input)) {\n    return false\n  }\n\n  const { cid, mimeType } = input\n  if (typeof cid !== 'string') {\n    return false\n  }\n\n  if (typeof mimeType !== 'string' || mimeType.length === 0) {\n    return false\n  }\n\n  for (const key in input) {\n    if (key !== 'cid' && key !== 'mimeType') {\n      return false\n    }\n  }\n\n  if (!validateCidString(cid)) {\n    return false\n  }\n\n  return true\n}\n\n/**\n * Options for enumerating blob references within a {@link LexValue}.\n */\nexport type EnumBlobRefsOptions = BlobRefCheckOptions & {\n  /**\n   * If `true`, also yields {@link LegacyBlobRef} objects in addition to\n   * {@link BlobRef} objects.\n   *\n   * @default false\n   */\n  allowLegacy?: boolean\n}\n\n/**\n * Infers the yielded type of {@link enumBlobRefs} based on options.\n *\n * @typeParam TOptions - The options used for enumeration\n */\nexport type InferEnumBlobRefs<TOptions extends EnumBlobRefsOptions> =\n  TOptions extends { allowLegacy: true }\n    ? InferCheckedBlobRef<TOptions> | LegacyBlobRef\n    : { allowLegacy: boolean } extends TOptions\n      ? InferCheckedBlobRef<TOptions> | LegacyBlobRef\n      : InferCheckedBlobRef<TOptions>\n\n/**\n * Generator that enumerates all {@link BlobRef}s (and, optionally,\n * {@link LegacyBlobRef}s) found within a {@link LexValue}.\n *\n * Performs a deep traversal of the input value, yielding any blob references\n * found. This is useful for extracting all media references from a record.\n *\n * @param input - The LexValue to search for blob references\n * @param options - Optional configuration for the enumeration\n * @yields Each blob reference found in the input\n *\n * @example\n * ```typescript\n * import { enumBlobRefs } from '@atproto/lex-data'\n *\n * const record = {\n *   text: 'Hello',\n *   images: [\n *     { $type: 'blob', mimeType: 'image/jpeg', ref: cid1, size: 1000 },\n *     { $type: 'blob', mimeType: 'image/png', ref: cid2, size: 2000 }\n *   ]\n * }\n *\n * for (const blobRef of enumBlobRefs(record)) {\n *   console.log(blobRef.mimeType, blobRef.size)\n * }\n *\n * // Include legacy blob references\n * for (const ref of enumBlobRefs(record, { allowLegacy: true })) {\n *   // ref may be BlobRef or LegacyBlobRef\n * }\n * ```\n */\nexport function enumBlobRefs(\n  input: LexValue,\n): Generator<BlobRef<RawCid>, void, unknown>\nexport function enumBlobRefs<TOptions extends EnumBlobRefsOptions>(\n  input: LexValue,\n  options: TOptions,\n): Generator<InferEnumBlobRefs<TOptions>, void, unknown>\nexport function enumBlobRefs(\n  input: LexValue,\n  options?: EnumBlobRefsOptions,\n): Generator<BlobRef | LegacyBlobRef, void, unknown>\nexport function* enumBlobRefs(\n  input: LexValue,\n  options?: EnumBlobRefsOptions,\n): Generator<BlobRef | LegacyBlobRef, void, unknown> {\n  // LegacyBlobRef not included by default\n  const includeLegacy = options?.allowLegacy === true\n\n  // Using a stack to avoid recursion depth issues.\n  const stack: LexValue[] = [input]\n\n  // Since we are using a stack, we could end-up in an infinite loop with cyclic\n  // structures. Cyclic structures are not valid LexValues and should, thus,\n  // never occur, but let's be safe.\n  const visited = new Set<object>()\n\n  do {\n    const value = stack.pop()!\n\n    if (value != null && typeof value === 'object') {\n      if (Array.isArray(value)) {\n        if (visited.has(value)) continue\n        visited.add(value)\n        stack.push(...value)\n      } else if (isPlainProto(value)) {\n        if (visited.has(value)) continue\n        visited.add(value)\n        if (isBlobRef(value, options)) {\n          yield value\n        } else if (includeLegacy && isLegacyBlobRef(value)) {\n          yield value\n        } else {\n          for (const v of Object.values(value)) {\n            if (v != null) stack.push(v)\n          }\n        }\n      }\n    }\n  } while (stack.length > 0)\n\n  // Optimization: ease GC's work\n  visited.clear()\n}\n"]}
+{"version":3,"file":"blob.js","sourceRoot":"","sources":["../src/blob.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  CheckCidOptions,\n  Cid,\n  RawCid,\n  ifCid,\n  parseCid,\n  validateCidString,\n} from './cid.js'\nimport { LexValue } from './lex.js'\nimport { isPlainObject, isPlainProto } from './object.js'\n\n/**\n * Options to use with {@link ifCid}, {@link validateCidString}, and related CID\n * validation functions when validating CIDs in BlobRefs, in strict mode. This\n * ensures that the CID is a {@link RawCid} (CID v1, raw multicodec, sha256\n * multihash), which is the expected format for blob references in the AT\n * Protocol data model.\n */\nconst STRICT_CID_CHECK_OPTIONS: CheckCidOptions = { flavor: 'raw' }\n\n// Number.isSafeInteger is actually safe to use with non-number values, so we\n// can use it as a type guard.\nconst isSafeInteger = Number.isSafeInteger as (v: unknown) => v is number\n\n/**\n * Reference to binary data (like images, videos, etc.) in the AT Protocol data\n * model.\n *\n * This type represents a reference to a blob of binary data, identified by its\n * content hash (CID) and accompanied by metadata such as MIME type and size.\n *\n * The {@link BlobRef} type is a union of the current {@link TypedBlobRef}\n * format and the legacy {@link LegacyBlobRef} format.\n */\nexport type BlobRef<Ref extends Cid = Cid> = TypedBlobRef<Ref> | LegacyBlobRef\n\n/**\n * Options for validating a {@link BlobRef}.\n */\nexport type BlobRefCheckOptions = {\n  /**\n   * If `false`, skips strict CID validation of {@link BlobRef.ref}, allowing\n   * any valid CID. Otherwise, validates that the CID is v1, uses the raw\n   * multicodec, and has a sha256 multihash.\n   *\n   * @default true\n   */\n  strict?: boolean\n}\n\n/**\n * Type guard to check if a value is a valid {@link BlobRef}, which can be\n * either a {@link TypedBlobRef} or a {@link LegacyBlobRef}. By default, strict\n * CID validation is applied to ensure that the CID in the blob reference is in\n * the expected format for the AT Protocol, but this can be relaxed with the\n * `strict: false` option.\n */\nexport function isBlobRef(input: unknown): input is BlobRef<RawCid>\nexport function isBlobRef<TOptions extends BlobRefCheckOptions>(\n  input: unknown,\n  options: TOptions,\n): input is LegacyBlobRef | InferTypedBlobRef<TOptions>\nexport function isBlobRef(\n  input: unknown,\n  options?: BlobRefCheckOptions,\n): input is BlobRef<RawCid>\nexport function isBlobRef(\n  input: unknown,\n  options?: BlobRefCheckOptions,\n): input is BlobRef {\n  return (input as any)?.$type === 'blob'\n    ? isTypedBlobRef(input, options)\n    : isLegacyBlobRef(input, options)\n}\n\n/**\n * Extracts the MIME type from a {@link BlobRef}.\n *\n * @example\n * ```ts\n * const mimeType = getBlobMime(blobRef)\n * console.log(mimeType)  // e.g., 'image/jpeg'\n * ```\n */\nexport function getBlobMime(blob: BlobRef): string\nexport function getBlobMime(blob?: BlobRef): string | undefined\nexport function getBlobMime(blob?: BlobRef): string | undefined {\n  return blob?.mimeType\n}\n\n/**\n * Extracts the size (in bytes) from a {@link TypedBlobRef}. For\n * {@link LegacyBlobRef}, size information is not available, so this function\n * returns `undefined` for legacy refs.\n *\n * @note The size property, in blob refs, cannot be 100% trusted since the PDS\n * might not have a local copy of the blob (to check the size against) and might\n * just be passing through the blob ref from the client without validating it.\n * So, while this function can be useful for getting size information when\n * available, it should not be solely relied upon for critical functionality\n * without additional validation.\n *\n * @example\n * ```ts\n * const size = getBlobSize(blobRef)\n * if (size !== undefined) {\n *   console.log(`Blob size: ${size} bytes`)\n * } else {\n *   console.log('Size information not available for legacy blob ref')\n * }\n * ```\n */\nexport function getBlobSize(blob: BlobRef): number | undefined {\n  if ('$type' in blob && blob.size >= 0) return blob.size\n  // LegacyBlobRef doesn't have size information\n  return undefined\n}\n\n/**\n * Extracts the {@link Cid} from a {@link BlobRef}.\n *\n * @throws If the input input is a {@link LegacyBlobRef} with an invalid CID string\n * @example\n * ```ts\n * const cid = getBlobCid(blobRef)\n * console.log(cid.bytes)\n * ```\n */\nexport function getBlobCid(blob: BlobRef): Cid\nexport function getBlobCid(blob?: BlobRef): Cid | undefined\nexport function getBlobCid(blob?: BlobRef): Cid | undefined {\n  if (!blob) return undefined\n  return '$type' in blob ? blob.ref : parseCid(blob.cid)\n}\n\n/**\n * Extracts the CID string from a {@link BlobRef}.\n *\n * This is similar to `getBlobCid(blob).toString()` but is more optimized since\n * the CID string is already available in the legacy format and we can avoid\n * parsing it into a CID object just to convert it back to a string.\n *\n * @example\n * ```ts\n * const cidString = getBlobCidString(blobRef)\n * console.log(cidString)\n * ```\n */\nexport function getBlobCidString(blob: BlobRef): string\nexport function getBlobCidString(blob?: BlobRef): string | undefined\nexport function getBlobCidString(blob?: BlobRef): string | undefined {\n  if (!blob) return undefined\n  return '$type' in blob ? blob.ref.toString() : blob.cid\n}\n\n/**\n * Reference to binary data (like images, videos, etc.) in the AT Protocol data model.\n *\n * A {@link TypedBlobRef} is a {@link LexMap} with a specific structure that\n * identifies binary content by its content hash (CID), along with metadata\n * about the content type and size.\n *\n * @typeParam Ref - The type of CID reference, defaults to any {@link Cid}\n *\n * @example\n * ```typescript\n * import type { TypedBlobRef } from '@atproto/lex-data'\n *\n * const imageRef: TypedBlobRef = {\n *   $type: 'blob',\n *   mimeType: 'image/jpeg',\n *   ref: cid,  // CID of the blob content\n *   size: 12345\n * }\n * ```\n *\n * @see {@link isTypedBlobRef} to check if a value is a valid {@link TypedBlobRef}\n * @see {@link LegacyBlobRef} for the older blob reference format\n */\nexport type TypedBlobRef<Ref extends Cid = Cid> = {\n  $type: 'blob'\n  mimeType: string\n  ref: Ref\n  size: number\n}\n\n/**\n * Infers the BlobRef type based on the check options.\n *\n * @typeParam TOptions - The options used for checking\n */\nexport type InferTypedBlobRef<TOptions extends BlobRefCheckOptions> =\n  TOptions extends { strict: false }\n    ? TypedBlobRef\n    : { strict: boolean } extends TOptions\n      ? TypedBlobRef\n      : TypedBlobRef<RawCid>\n\n/**\n * Type guard to check if a value is a valid {@link BlobRef}.\n *\n * Validates the structure of the input including:\n * - `$type` must be `'blob'`\n * - `mimeType` must be a valid MIME type string (containing '/')\n * - `size` must be a non-negative safe integer\n * - `ref` must be a valid CID (strict validation by default)\n *\n * @param input - The value to check\n * @param options - Optional validation options\n * @returns `true` if the input is a valid BlobRef\n *\n * @example\n * ```typescript\n * import { isTypedBlobRef } from '@atproto/lex-data'\n *\n * if (isTypedBlobRef(data)) {\n *   console.log(data.mimeType)  // e.g., 'image/jpeg'\n *   console.log(data.size)      // e.g., 12345\n * }\n *\n * // Allow any valid CID (not just raw CIDs)\n * if (isTypedBlobRef(data, { strict: false })) {\n *   // ...\n * }\n * ```\n */\nexport function isTypedBlobRef(input: unknown): input is TypedBlobRef<RawCid>\nexport function isTypedBlobRef<TOptions extends BlobRefCheckOptions>(\n  input: unknown,\n  options: TOptions,\n): input is InferTypedBlobRef<TOptions>\nexport function isTypedBlobRef(\n  input: unknown,\n  options?: BlobRefCheckOptions,\n): input is TypedBlobRef<RawCid>\nexport function isTypedBlobRef(\n  input: unknown,\n  options?: BlobRefCheckOptions,\n): input is TypedBlobRef {\n  if (!isPlainObject(input)) {\n    return false\n  }\n\n  if (input?.$type !== 'blob') {\n    return false\n  }\n\n  const { mimeType, size, ref } = input\n  // @NOTE Very basic mime validation\n  if (typeof mimeType !== 'string' || !mimeType.includes('/')) {\n    return false\n  }\n\n  if (size === -1 && options?.strict === false) {\n    // In non-strict mode, allow size to be -1 to accommodate legacy blob refs\n    // that don't include size information.\n  } else if (!isSafeInteger(size) || size < 0) {\n    return false\n  }\n\n  if (typeof ref !== 'object' || ref === null) {\n    return false\n  }\n\n  for (const key in input) {\n    if (\n      key !== '$type' &&\n      key !== 'mimeType' &&\n      key !== 'ref' &&\n      key !== 'size'\n    ) {\n      return false\n    }\n  }\n\n  const cid = ifCid(\n    ref,\n    // Strict unless explicitly disabled\n    options?.strict === false ? undefined : STRICT_CID_CHECK_OPTIONS,\n  )\n  if (!cid) {\n    return false\n  }\n\n  return true\n}\n\n/**\n * Legacy format for blob references used in older AT Protocol data.\n *\n * This is the older format that stores the CID as a string rather than\n * as a structured CID object. New code should use {@link BlobRef} instead.\n *\n * @example\n * ```typescript\n * import type { LegacyBlobRef } from '@atproto/lex-data'\n *\n * const legacyRef: LegacyBlobRef = {\n *   cid: 'bafyreib...',\n *   mimeType: 'image/jpeg'\n * }\n * ```\n *\n * @see {@link isLegacyBlobRef} to check if a value is a LegacyBlobRef\n * @see {@link BlobRef} for the current blob reference format\n * @deprecated Use {@link BlobRef} for new code\n */\nexport type LegacyBlobRef = {\n  cid: string\n  mimeType: string\n}\n\n/**\n * Type guard to check if a value is a valid {@link LegacyBlobRef}.\n *\n * Validates the structure of the input:\n * - `cid` must be a valid CID string\n * - `mimeType` must be a non-empty string\n * - No additional properties allowed\n *\n * @example\n * ```typescript\n * import { isLegacyBlobRef } from '@atproto/lex-data'\n *\n * if (isLegacyBlobRef(data)) {\n *   console.log(data.cid)       // CID as string\n *   console.log(data.mimeType)  // e.g., 'image/jpeg'\n * }\n * ```\n *\n * @see {@link isTypedBlobRef} for checking the current blob reference format\n */\nexport function isLegacyBlobRef(\n  input: unknown,\n  options?: BlobRefCheckOptions,\n): input is LegacyBlobRef {\n  if (!isPlainObject(input)) {\n    return false\n  }\n\n  const { cid, mimeType } = input\n  if (typeof cid !== 'string') {\n    return false\n  }\n\n  if (typeof mimeType !== 'string' || mimeType.length === 0) {\n    return false\n  }\n\n  for (const key in input) {\n    if (key !== 'cid' && key !== 'mimeType') {\n      return false\n    }\n  }\n\n  if (\n    !validateCidString(\n      cid,\n      options?.strict === false ? undefined : STRICT_CID_CHECK_OPTIONS,\n    )\n  ) {\n    return false\n  }\n\n  return true\n}\n\n/**\n * Options for enumerating blob references within a {@link LexValue}.\n */\nexport type EnumBlobRefsOptions = BlobRefCheckOptions & {\n  /**\n   * If `true`, also yields {@link LegacyBlobRef} objects in addition to\n   * {@link BlobRef} objects.\n   *\n   * @default false\n   */\n  allowLegacy?: boolean\n}\n\n/**\n * Infers the yielded type of {@link enumBlobRefs} based on options.\n *\n * @typeParam TOptions - The options used for enumeration\n */\nexport type InferEnumBlobRefs<TOptions extends EnumBlobRefsOptions> =\n  TOptions extends { allowLegacy: true }\n    ? InferTypedBlobRef<TOptions> | LegacyBlobRef\n    : { allowLegacy: boolean } extends TOptions\n      ? InferTypedBlobRef<TOptions> | LegacyBlobRef\n      : InferTypedBlobRef<TOptions>\n\n/**\n * Generator that enumerates all {@link BlobRef}s (and, optionally,\n * {@link LegacyBlobRef}s) found within a {@link LexValue}.\n *\n * Performs a deep traversal of the input value, yielding any blob references\n * found. This is useful for extracting all media references from a record.\n *\n * @param input - The LexValue to search for blob references\n * @param options - Optional configuration for the enumeration\n * @yields Each blob reference found in the input\n *\n * @example\n * ```typescript\n * import { enumBlobRefs } from '@atproto/lex-data'\n *\n * const record = {\n *   text: 'Hello',\n *   images: [\n *     { $type: 'blob', mimeType: 'image/jpeg', ref: cid1, size: 1000 },\n *     { $type: 'blob', mimeType: 'image/png', ref: cid2, size: 2000 }\n *   ]\n * }\n *\n * for (const blobRef of enumBlobRefs(record)) {\n *   console.log(blobRef.mimeType, blobRef.size)\n * }\n *\n * // Include legacy blob references\n * for (const ref of enumBlobRefs(record, { allowLegacy: true, strict: false })) {\n *   // ref may be BlobRef or LegacyBlobRef, with relaxed CID validation\n * }\n * ```\n */\nexport function enumBlobRefs(\n  input: LexValue,\n): Generator<BlobRef<RawCid>, void, unknown>\nexport function enumBlobRefs<TOptions extends EnumBlobRefsOptions>(\n  input: LexValue,\n  options: TOptions,\n): Generator<InferEnumBlobRefs<TOptions>, void, unknown>\nexport function enumBlobRefs(\n  input: LexValue,\n  options?: EnumBlobRefsOptions,\n): Generator<BlobRef, void, unknown>\nexport function* enumBlobRefs(\n  input: LexValue,\n  options?: EnumBlobRefsOptions,\n): Generator<BlobRef, void, unknown> {\n  // LegacyBlobRef not included by default\n  const includeLegacy = options?.allowLegacy === true\n\n  // Using a stack to avoid recursion depth issues.\n  const stack: LexValue[] = [input]\n\n  // Since we are using a stack, we could end-up in an infinite loop with cyclic\n  // structures. Cyclic structures are not valid LexValues and should, thus,\n  // never occur, but let's be safe.\n  const visited = new Set<object>()\n\n  do {\n    const value = stack.pop()!\n\n    if (value != null && typeof value === 'object') {\n      if (Array.isArray(value)) {\n        if (visited.has(value)) continue\n        visited.add(value)\n        stack.push(...value)\n      } else if (isPlainProto(value)) {\n        if (visited.has(value)) continue\n        visited.add(value)\n        if (isTypedBlobRef(value, options)) {\n          yield value\n        } else if (includeLegacy && isLegacyBlobRef(value, options)) {\n          yield value\n        } else {\n          for (const v of Object.values(value)) {\n            if (v != null) stack.push(v)\n          }\n        }\n      }\n    }\n  } while (stack.length > 0)\n\n  // Optimization: ease GC's work\n  visited.clear()\n}\n"]}

package/dist/lib/nodejs-buffer.d.ts

@@ -7,6 +7,7 @@ interface NodeJSBufferConstructor {
     new (input: string, encoding?: Encoding): NodeJSBuffer;
     from(input: Uint8Array | ArrayBuffer | ArrayBufferView): NodeJSBuffer<ArrayBuffer>;
     from(input: string, encoding?: Encoding): NodeJSBuffer<ArrayBuffer>;
+    from<TArrayBuffer extends ArrayBufferLike>(arrayBuffer: WithImplicitCoercion<TArrayBuffer>, byteOffset?: number, length?: number): Buffer<TArrayBuffer>;
     concat(list: readonly Uint8Array[], totalLength?: number): NodeJSBuffer;
     byteLength(input: string, encoding?: Encoding): number;
     prototype: NodeJSBuffer;

package/dist/lib/nodejs-buffer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"nodejs-buffer.d.ts","sourceRoot":"","sources":["../../src/lib/nodejs-buffer.ts"],"names":[],"mappings":"AAAA,KAAK,QAAQ,GAAG,MAAM,GAAG,QAAQ,GAAG,WAAW,CAAA;AAE/C,UAAU,YAAY,CAAC,YAAY,SAAS,eAAe,GAAG,eAAe,CAC3E,SAAQ,UAAU,CAAC,YAAY,CAAC;IAChC,UAAU,EAAE,MAAM,CAAA;IAClB,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,GAAG,MAAM,CAAA;CACtC;AAED,UAAU,uBAAuB;IAC/B,KAAK,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,QAAQ,GAAG,YAAY,CAAA;IACtD,IAAI,CACF,KAAK,EAAE,UAAU,GAAG,WAAW,GAAG,eAAe,GAChD,YAAY,CAAC,WAAW,CAAC,CAAA;IAC5B,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,QAAQ,GAAG,YAAY,CAAC,WAAW,CAAC,CAAA;IACnE,MAAM,CAAC,IAAI,EAAE,SAAS,UAAU,EAAE,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,YAAY,CAAA;IACvE,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,QAAQ,GAAG,MAAM,CAAA;IACtD,SAAS,EAAE,YAAY,CAAA;CACxB;AAMD,eAAO,MAAM,YAAY,EAAE,uBAAuB,GAAG,IAIT,CAAA"}
+{"version":3,"file":"nodejs-buffer.d.ts","sourceRoot":"","sources":["../../src/lib/nodejs-buffer.ts"],"names":[],"mappings":"AAAA,KAAK,QAAQ,GAAG,MAAM,GAAG,QAAQ,GAAG,WAAW,CAAA;AAE/C,UAAU,YAAY,CAAC,YAAY,SAAS,eAAe,GAAG,eAAe,CAC3E,SAAQ,UAAU,CAAC,YAAY,CAAC;IAChC,UAAU,EAAE,MAAM,CAAA;IAClB,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,GAAG,MAAM,CAAA;CACtC;AAED,UAAU,uBAAuB;IAC/B,KAAK,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,QAAQ,GAAG,YAAY,CAAA;IACtD,IAAI,CACF,KAAK,EAAE,UAAU,GAAG,WAAW,GAAG,eAAe,GAChD,YAAY,CAAC,WAAW,CAAC,CAAA;IAC5B,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,QAAQ,GAAG,YAAY,CAAC,WAAW,CAAC,CAAA;IACnE,IAAI,CAAC,YAAY,SAAS,eAAe,EACvC,WAAW,EAAE,oBAAoB,CAAC,YAAY,CAAC,EAC/C,UAAU,CAAC,EAAE,MAAM,EACnB,MAAM,CAAC,EAAE,MAAM,GACd,MAAM,CAAC,YAAY,CAAC,CAAA;IACvB,MAAM,CAAC,IAAI,EAAE,SAAS,UAAU,EAAE,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,YAAY,CAAA;IACvE,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,QAAQ,GAAG,MAAM,CAAA;IACtD,SAAS,EAAE,YAAY,CAAA;CACxB;AAMD,eAAO,MAAM,YAAY,EAAE,uBAAuB,GAAG,IAIT,CAAA"}

package/dist/lib/nodejs-buffer.js.map

@@ -1 +1 @@
-{"version":3,"file":"nodejs-buffer.js","sourceRoot":"","sources":["../../src/lib/nodejs-buffer.ts"],"names":[],"mappings":";;;AAmBA,6EAA6E;AAC7E,6EAA6E;AAC7E,qBAAqB;AACrB,MAAM,MAAM,GAAG,aAAa,CAAC,CAAC,GAAG,EAAE,CAAC,IAAI,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,EAAc,CAAA;AACjE,QAAA,YAAY,GACtB,UAAkB,EAAE,CAAC,MAAM,CAAC,EAAE,SAAS,YAAY,UAAU;IAC9D,YAAY,IAAK,UAAkB,CAAC,MAAM,CAAC;IACzC,CAAC,CAAG,UAAkB,CAAC,MAAM,CAA6B;IAC1D,CAAC,CAAC,iCAAiC,CAAC,IAAI,CAAA","sourcesContent":["type Encoding = 'utf8' | 'base64' | 'base64url'\n\ninterface NodeJSBuffer<TArrayBuffer extends ArrayBufferLike = ArrayBufferLike>\n  extends Uint8Array<TArrayBuffer> {\n  byteLength: number\n  toString(encoding?: Encoding): string\n}\n\ninterface NodeJSBufferConstructor {\n  new (input: string, encoding?: Encoding): NodeJSBuffer\n  from(\n    input: Uint8Array | ArrayBuffer | ArrayBufferView,\n  ): NodeJSBuffer<ArrayBuffer>\n  from(input: string, encoding?: Encoding): NodeJSBuffer<ArrayBuffer>\n  concat(list: readonly Uint8Array[], totalLength?: number): NodeJSBuffer\n  byteLength(input: string, encoding?: Encoding): number\n  prototype: NodeJSBuffer\n}\n\n// Avoids a direct reference to Node.js Buffer, which might not exist in some\n// environments (e.g. browsers, Deno, Bun) to prevent bundlers from trying to\n// include polyfills.\nconst BUFFER = /*#__PURE__*/ (() => 'Bu' + 'f'.repeat(2) + 'er')() as 'Buffer'\nexport const NodeJSBuffer: NodeJSBufferConstructor | null =\n  (globalThis as any)?.[BUFFER]?.prototype instanceof Uint8Array &&\n  'byteLength' in (globalThis as any)[BUFFER]\n    ? ((globalThis as any)[BUFFER] as NodeJSBufferConstructor)\n    : /* v8 ignore next -- @preserve */ null\n"]}
+{"version":3,"file":"nodejs-buffer.js","sourceRoot":"","sources":["../../src/lib/nodejs-buffer.ts"],"names":[],"mappings":";;;AAwBA,6EAA6E;AAC7E,6EAA6E;AAC7E,qBAAqB;AACrB,MAAM,MAAM,GAAG,aAAa,CAAC,CAAC,GAAG,EAAE,CAAC,IAAI,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,EAAc,CAAA;AACjE,QAAA,YAAY,GACtB,UAAkB,EAAE,CAAC,MAAM,CAAC,EAAE,SAAS,YAAY,UAAU;IAC9D,YAAY,IAAK,UAAkB,CAAC,MAAM,CAAC;IACzC,CAAC,CAAG,UAAkB,CAAC,MAAM,CAA6B;IAC1D,CAAC,CAAC,iCAAiC,CAAC,IAAI,CAAA","sourcesContent":["type Encoding = 'utf8' | 'base64' | 'base64url'\n\ninterface NodeJSBuffer<TArrayBuffer extends ArrayBufferLike = ArrayBufferLike>\n  extends Uint8Array<TArrayBuffer> {\n  byteLength: number\n  toString(encoding?: Encoding): string\n}\n\ninterface NodeJSBufferConstructor {\n  new (input: string, encoding?: Encoding): NodeJSBuffer\n  from(\n    input: Uint8Array | ArrayBuffer | ArrayBufferView,\n  ): NodeJSBuffer<ArrayBuffer>\n  from(input: string, encoding?: Encoding): NodeJSBuffer<ArrayBuffer>\n  from<TArrayBuffer extends ArrayBufferLike>(\n    arrayBuffer: WithImplicitCoercion<TArrayBuffer>,\n    byteOffset?: number,\n    length?: number,\n  ): Buffer<TArrayBuffer>\n  concat(list: readonly Uint8Array[], totalLength?: number): NodeJSBuffer\n  byteLength(input: string, encoding?: Encoding): number\n  prototype: NodeJSBuffer\n}\n\n// Avoids a direct reference to Node.js Buffer, which might not exist in some\n// environments (e.g. browsers, Deno, Bun) to prevent bundlers from trying to\n// include polyfills.\nconst BUFFER = /*#__PURE__*/ (() => 'Bu' + 'f'.repeat(2) + 'er')() as 'Buffer'\nexport const NodeJSBuffer: NodeJSBufferConstructor | null =\n  (globalThis as any)?.[BUFFER]?.prototype instanceof Uint8Array &&\n  'byteLength' in (globalThis as any)[BUFFER]\n    ? ((globalThis as any)[BUFFER] as NodeJSBufferConstructor)\n    : /* v8 ignore next -- @preserve */ null\n"]}

package/dist/utf8-from-bytes.d.ts

@@ -0,0 +1,3 @@
+export declare const utf8FromBytesNode: ((bytes: Uint8Array) => string) | null;
+export declare function utf8FromBytesNative(bytes: Uint8Array): string;
+//# sourceMappingURL=utf8-from-bytes.d.ts.map

package/dist/utf8-from-bytes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utf8-from-bytes.d.ts","sourceRoot":"","sources":["../src/utf8-from-bytes.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,iBAAiB,WACQ,UAAU,KAAG,MAAM,QAWf,CAAA;AAE1C,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAE7D"}

package/dist/utf8-from-bytes.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.utf8FromBytesNode = void 0;
+exports.utf8FromBytesNative = utf8FromBytesNative;
+const nodejs_buffer_js_1 = require("./lib/nodejs-buffer.js");
+const Buffer = nodejs_buffer_js_1.NodeJSBuffer;
+exports.utf8FromBytesNode = Buffer
+    ? function utf8FromBytesNode(bytes) {
+        // @NOTE Buffer.from(bytes) creates a copy of the ArrayBuffer. The following
+        // allows us to avoid the copy by creating a Buffer that shares the same
+        // memory as the input Uint8Array.
+        const buffer = Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+        return buffer.toString('utf8');
+    }
+    : /* v8 ignore next -- @preserve */ null;
+function utf8FromBytesNative(bytes) {
+    return new TextDecoder('utf-8').decode(bytes);
+}
+//# sourceMappingURL=utf8-from-bytes.js.map

package/dist/utf8-from-bytes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utf8-from-bytes.js","sourceRoot":"","sources":["../src/utf8-from-bytes.ts"],"names":[],"mappings":";;;AAkBA,kDAEC;AApBD,6DAAqD;AAErD,MAAM,MAAM,GAAG,+BAAY,CAAA;AAEd,QAAA,iBAAiB,GAAG,MAAM;IACrC,CAAC,CAAC,SAAS,iBAAiB,CAAC,KAAiB;QAC1C,4EAA4E;QAC5E,wEAAwE;QACxE,kCAAkC;QAClC,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CACxB,KAAK,CAAC,MAAM,EACZ,KAAK,CAAC,UAAU,EAChB,KAAK,CAAC,UAAU,CACjB,CAAA;QACD,OAAO,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAA;IAChC,CAAC;IACH,CAAC,CAAC,iCAAiC,CAAC,IAAI,CAAA;AAE1C,SAAgB,mBAAmB,CAAC,KAAiB;IACnD,OAAO,IAAI,WAAW,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;AAC/C,CAAC","sourcesContent":["import { NodeJSBuffer } from './lib/nodejs-buffer.js'\n\nconst Buffer = NodeJSBuffer\n\nexport const utf8FromBytesNode = Buffer\n  ? function utf8FromBytesNode(bytes: Uint8Array): string {\n      // @NOTE Buffer.from(bytes) creates a copy of the ArrayBuffer. The following\n      // allows us to avoid the copy by creating a Buffer that shares the same\n      // memory as the input Uint8Array.\n      const buffer = Buffer.from(\n        bytes.buffer,\n        bytes.byteOffset,\n        bytes.byteLength,\n      )\n      return buffer.toString('utf8')\n    }\n  : /* v8 ignore next -- @preserve */ null\n\nexport function utf8FromBytesNative(bytes: Uint8Array): string {\n  return new TextDecoder('utf-8').decode(bytes)\n}\n"]}

package/dist/utf8.d.ts

@@ -1,4 +1,22 @@
 import { Base64Alphabet } from './uint8array.js';
+/**
+ * Converts a Uint8Array to a UTF-8 string.
+ *
+ * Uses Node.js Buffer when available for performance, falling back to
+ * TextDecoder in environments without Buffer support.
+ *
+ * @param bytes - The binary data to decode
+ * @returns The decoded string (as UTF-16 JavaScript string)
+ *
+ * @example
+ * ```typescript
+ * import { utf8FromBytes } from '@atproto/lex-data'
+ *
+ * const bytes = new Uint8Array([72, 101, 108, 108, 111])
+ * utf8FromBytes(bytes)  // 'Hello'
+ * ```
+ */
+export declare const utf8FromBytes: (bytes: Uint8Array) => string;
 /**
  * Counts the number of grapheme clusters (user-perceived characters) in a string.
  *

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;;;;;;;;;;;;;;;;;;;;;;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"}
+{"version":3,"file":"utf8.d.ts","sourceRoot":"","sources":["../src/utf8.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAUhD;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,aAAa,+BAA2C,CAAA;AAErE;;;;;;;;;;;;;;;;;;;;;;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

@@ -1,10 +1,29 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.utf8FromBase64 = exports.utf8ToBase64 = exports.utf8Len = exports.graphemeLen = void 0;
+exports.utf8FromBase64 = exports.utf8ToBase64 = exports.utf8Len = exports.graphemeLen = exports.utf8FromBytes = void 0;
 const utf8_from_base64_js_1 = require("./utf8-from-base64.js");
+const utf8_from_bytes_js_1 = require("./utf8-from-bytes.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");
+/**
+ * Converts a Uint8Array to a UTF-8 string.
+ *
+ * Uses Node.js Buffer when available for performance, falling back to
+ * TextDecoder in environments without Buffer support.
+ *
+ * @param bytes - The binary data to decode
+ * @returns The decoded string (as UTF-16 JavaScript string)
+ *
+ * @example
+ * ```typescript
+ * import { utf8FromBytes } from '@atproto/lex-data'
+ *
+ * const bytes = new Uint8Array([72, 101, 108, 108, 111])
+ * utf8FromBytes(bytes)  // 'Hello'
+ * ```
+ */
+exports.utf8FromBytes = utf8_from_bytes_js_1.utf8FromBytesNode ?? utf8_from_bytes_js_1.utf8FromBytesNative;
 /**
  * Counts the number of grapheme clusters (user-perceived characters) in a string.
  *

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;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"]}
+{"version":3,"file":"utf8.js","sourceRoot":"","sources":["../src/utf8.ts"],"names":[],"mappings":";;;AACA,+DAG8B;AAC9B,6DAA6E;AAC7E,iEAA+E;AAC/E,+CAA2D;AAC3D,2DAA4E;AAE5E;;;;;;;;;;;;;;;;GAgBG;AACU,QAAA,aAAa,GAAG,sCAAiB,IAAI,wCAAmB,CAAA;AAErE;;;;;;;;;;;;;;;;;;;;;;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 { utf8FromBytesNative, utf8FromBytesNode } from './utf8-from-bytes.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 * Converts a Uint8Array to a UTF-8 string.\n *\n * Uses Node.js Buffer when available for performance, falling back to\n * TextDecoder in environments without Buffer support.\n *\n * @param bytes - The binary data to decode\n * @returns The decoded string (as UTF-16 JavaScript string)\n *\n * @example\n * ```typescript\n * import { utf8FromBytes } from '@atproto/lex-data'\n *\n * const bytes = new Uint8Array([72, 101, 108, 108, 111])\n * utf8FromBytes(bytes)  // 'Hello'\n * ```\n */\nexport const utf8FromBytes = utf8FromBytesNode ?? utf8FromBytesNative\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"]}