@atproto/lex-json 0.0.10 → 0.0.11

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # @atproto/lex-json
 
+## 0.0.11
+
+### Patch Changes
+
+- [#4601](https://github.com/bluesky-social/atproto/pull/4601) [`ed61c62`](https://github.com/bluesky-social/atproto/commit/ed61c62f3161fcde85ee9a93f8ed339c7e06c015) Thanks [@matthieusieben](https://github.com/matthieusieben)! - Prevent `jsonToLex` from throwing in non-strict mode
+
+- [#4601](https://github.com/bluesky-social/atproto/pull/4601) [`ed61c62`](https://github.com/bluesky-social/atproto/commit/ed61c62f3161fcde85ee9a93f8ed339c7e06c015) Thanks [@matthieusieben](https://github.com/matthieusieben)! - Fix `exports` field in package.json
+
+- [#4601](https://github.com/bluesky-social/atproto/pull/4601) [`ed61c62`](https://github.com/bluesky-social/atproto/commit/ed61c62f3161fcde85ee9a93f8ed339c7e06c015) Thanks [@matthieusieben](https://github.com/matthieusieben)! - Add JSDoc
+
+- Updated dependencies [[`ed61c62`](https://github.com/bluesky-social/atproto/commit/ed61c62f3161fcde85ee9a93f8ed339c7e06c015), [`ed61c62`](https://github.com/bluesky-social/atproto/commit/ed61c62f3161fcde85ee9a93f8ed339c7e06c015)]:
+  - @atproto/lex-data@0.0.11
+
 ## 0.0.10
 
 ### Patch Changes

package/dist/blob.d.ts

@@ -1,3 +1,37 @@
 import { BlobRef, BlobRefCheckOptions, LexMap } from '@atproto/lex-data';
+/**
+ * Parses a blob reference from a JSON object.
+ *
+ * In the AT Protocol, blobs are referenced using a specific object structure
+ * with `$type: 'blob'`, a `ref` property containing a CID link, and metadata
+ * like `mimeType` and `size`. This function validates and parses such objects
+ * into `BlobRef` instances.
+ *
+ * The function handles both cases where the `ref` property is:
+ * - A `{$link: string}` object (when parsing from JSON)
+ * - Already a `Cid` instance (when the parent object has been partially converted)
+ *
+ * @param input - A Lex map potentially representing a blob reference
+ * @param options - Optional blob reference validation options
+ * @returns The parsed `BlobRef` if the input is a valid blob reference,
+ *          or `undefined` if the input is not a valid blob representation
+ *
+ * @example
+ * ```typescript
+ * // Parse a blob reference from JSON
+ * const blobRef = parseBlobRef({
+ *   $type: 'blob',
+ *   ref: { $link: 'bafyreib2rxk3rybloqtqwbo' },
+ *   mimeType: 'image/png',
+ *   size: 12345
+ * })
+ *
+ * // blobRef.ref is a Cid instance
+ *
+ * // Returns undefined for non-blob objects
+ * const result = parseBlobRef({ foo: 'bar' })
+ * // result is undefined
+ * ```
+ */
 export declare function parseBlobRef(input: LexMap, options?: BlobRefCheckOptions): BlobRef | undefined;
 //# 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,EACL,OAAO,EACP,mBAAmB,EACnB,MAAM,EAEP,MAAM,mBAAmB,CAAA;AAG1B,wBAAgB,YAAY,CAC1B,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,mBAAmB,GAC5B,OAAO,GAAG,SAAS,CAwBrB"}
+{"version":3,"file":"blob.d.ts","sourceRoot":"","sources":["../src/blob.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,OAAO,EACP,mBAAmB,EACnB,MAAM,EAEP,MAAM,mBAAmB,CAAA;AAG1B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,mBAAmB,GAC5B,OAAO,GAAG,SAAS,CAwBrB"}

package/dist/blob.js

@@ -3,6 +3,40 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.parseBlobRef = parseBlobRef;
 const lex_data_1 = require("@atproto/lex-data");
 const link_js_1 = require("./link.js");
+/**
+ * Parses a blob reference from a JSON object.
+ *
+ * In the AT Protocol, blobs are referenced using a specific object structure
+ * with `$type: 'blob'`, a `ref` property containing a CID link, and metadata
+ * like `mimeType` and `size`. This function validates and parses such objects
+ * into `BlobRef` instances.
+ *
+ * The function handles both cases where the `ref` property is:
+ * - A `{$link: string}` object (when parsing from JSON)
+ * - Already a `Cid` instance (when the parent object has been partially converted)
+ *
+ * @param input - A Lex map potentially representing a blob reference
+ * @param options - Optional blob reference validation options
+ * @returns The parsed `BlobRef` if the input is a valid blob reference,
+ *          or `undefined` if the input is not a valid blob representation
+ *
+ * @example
+ * ```typescript
+ * // Parse a blob reference from JSON
+ * const blobRef = parseBlobRef({
+ *   $type: 'blob',
+ *   ref: { $link: 'bafyreib2rxk3rybloqtqwbo' },
+ *   mimeType: 'image/png',
+ *   size: 12345
+ * })
+ *
+ * // blobRef.ref is a Cid instance
+ *
+ * // Returns undefined for non-blob objects
+ * const result = parseBlobRef({ foo: 'bar' })
+ * // result is undefined
+ * ```
+ */
 function parseBlobRef(input, options) {
     if (input.$type !== 'blob')
         return undefined;

package/dist/blob.js.map

@@ -1 +1 @@
-{"version":3,"file":"blob.js","sourceRoot":"","sources":["../src/blob.ts"],"names":[],"mappings":";;AAQA,oCA2BC;AAnCD,gDAK0B;AAC1B,uCAAwC;AAExC,SAAgB,YAAY,CAC1B,KAAa,EACb,OAA6B;IAE7B,IAAI,KAAK,CAAC,KAAK,KAAK,MAAM;QAAE,OAAO,SAAS,CAAA;IAE5C,MAAM,GAAG,GAAG,KAAK,EAAE,GAAG,CAAA;IACtB,IAAI,CAAC,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAA;IAErD,8EAA8E;IAC9E,oEAAoE;IACpE,qEAAqE;IACrE,iDAAiD;IAEjD,IAAI,OAAO,IAAI,GAAG,EAAE,CAAC;QACnB,MAAM,GAAG,GAAG,IAAA,sBAAY,EAAC,GAAG,CAAC,CAAA;QAC7B,IAAI,CAAC,GAAG;YAAE,OAAO,SAAS,CAAA;QAE1B,MAAM,IAAI,GAAG,EAAE,GAAG,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,CAAA;QACnC,IAAI,IAAA,oBAAS,EAAC,IAAI,EAAE,OAAO,CAAC;YAAE,OAAO,IAAI,CAAA;IAC3C,CAAC;IAED,IAAI,IAAA,oBAAS,EAAC,KAAK,CAAC,EAAE,CAAC;QACrB,OAAO,KAAK,CAAA;IACd,CAAC;IAED,OAAO,SAAS,CAAA;AAClB,CAAC","sourcesContent":["import {\n  BlobRef,\n  BlobRefCheckOptions,\n  LexMap,\n  isBlobRef,\n} from '@atproto/lex-data'\nimport { parseLexLink } from './link.js'\n\nexport function parseBlobRef(\n  input: LexMap,\n  options?: BlobRefCheckOptions,\n): BlobRef | undefined {\n  if (input.$type !== 'blob') return undefined\n\n  const ref = input?.ref\n  if (!ref || typeof ref !== 'object') return undefined\n\n  // @NOTE Because json to lex conversion can be performed both in a depth-first\n  // manner (e.g. via lexParse) or in a breadth-first manner (e.g. via\n  // jsonToLex), the `ref` property may either be a LexMap with a $link\n  // property, or it may already be a CID instance.\n\n  if ('$link' in ref) {\n    const cid = parseLexLink(ref)\n    if (!cid) return undefined\n\n    const blob = { ...input, ref: cid }\n    if (isBlobRef(blob, options)) return blob\n  }\n\n  if (isBlobRef(input)) {\n    return input\n  }\n\n  return undefined\n}\n"]}
+{"version":3,"file":"blob.js","sourceRoot":"","sources":["../src/blob.ts"],"names":[],"mappings":";;AA0CA,oCA2BC;AArED,gDAK0B;AAC1B,uCAAwC;AAExC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,SAAgB,YAAY,CAC1B,KAAa,EACb,OAA6B;IAE7B,IAAI,KAAK,CAAC,KAAK,KAAK,MAAM;QAAE,OAAO,SAAS,CAAA;IAE5C,MAAM,GAAG,GAAG,KAAK,EAAE,GAAG,CAAA;IACtB,IAAI,CAAC,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAA;IAErD,8EAA8E;IAC9E,oEAAoE;IACpE,qEAAqE;IACrE,iDAAiD;IAEjD,IAAI,OAAO,IAAI,GAAG,EAAE,CAAC;QACnB,MAAM,GAAG,GAAG,IAAA,sBAAY,EAAC,GAAG,CAAC,CAAA;QAC7B,IAAI,CAAC,GAAG;YAAE,OAAO,SAAS,CAAA;QAE1B,MAAM,IAAI,GAAG,EAAE,GAAG,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,CAAA;QACnC,IAAI,IAAA,oBAAS,EAAC,IAAI,EAAE,OAAO,CAAC;YAAE,OAAO,IAAI,CAAA;IAC3C,CAAC;IAED,IAAI,IAAA,oBAAS,EAAC,KAAK,CAAC,EAAE,CAAC;QACrB,OAAO,KAAK,CAAA;IACd,CAAC;IAED,OAAO,SAAS,CAAA;AAClB,CAAC","sourcesContent":["import {\n  BlobRef,\n  BlobRefCheckOptions,\n  LexMap,\n  isBlobRef,\n} from '@atproto/lex-data'\nimport { parseLexLink } from './link.js'\n\n/**\n * Parses a blob reference from a JSON object.\n *\n * In the AT Protocol, blobs are referenced using a specific object structure\n * with `$type: 'blob'`, a `ref` property containing a CID link, and metadata\n * like `mimeType` and `size`. This function validates and parses such objects\n * into `BlobRef` instances.\n *\n * The function handles both cases where the `ref` property is:\n * - A `{$link: string}` object (when parsing from JSON)\n * - Already a `Cid` instance (when the parent object has been partially converted)\n *\n * @param input - A Lex map potentially representing a blob reference\n * @param options - Optional blob reference validation options\n * @returns The parsed `BlobRef` if the input is a valid blob reference,\n *          or `undefined` if the input is not a valid blob representation\n *\n * @example\n * ```typescript\n * // Parse a blob reference from JSON\n * const blobRef = parseBlobRef({\n *   $type: 'blob',\n *   ref: { $link: 'bafyreib2rxk3rybloqtqwbo' },\n *   mimeType: 'image/png',\n *   size: 12345\n * })\n *\n * // blobRef.ref is a Cid instance\n *\n * // Returns undefined for non-blob objects\n * const result = parseBlobRef({ foo: 'bar' })\n * // result is undefined\n * ```\n */\nexport function parseBlobRef(\n  input: LexMap,\n  options?: BlobRefCheckOptions,\n): BlobRef | undefined {\n  if (input.$type !== 'blob') return undefined\n\n  const ref = input?.ref\n  if (!ref || typeof ref !== 'object') return undefined\n\n  // @NOTE Because json to lex conversion can be performed both in a depth-first\n  // manner (e.g. via lexParse) or in a breadth-first manner (e.g. via\n  // jsonToLex), the `ref` property may either be a LexMap with a $link\n  // property, or it may already be a CID instance.\n\n  if ('$link' in ref) {\n    const cid = parseLexLink(ref)\n    if (!cid) return undefined\n\n    const blob = { ...input, ref: cid }\n    if (isBlobRef(blob, options)) return blob\n  }\n\n  if (isBlobRef(input)) {\n    return input\n  }\n\n  return undefined\n}\n"]}

package/dist/bytes.d.ts

@@ -1,6 +1,47 @@
 import { JsonValue } from './json.js';
-export declare function parseLexBytes(input?: {
-    $bytes?: unknown;
-}): Uint8Array | undefined;
+/**
+ * Parses a `{$bytes: string}` JSON object into a `Uint8Array`.
+ *
+ * In the AT Protocol data model, binary data is represented in JSON as an object
+ * with a single `$bytes` property containing a base64-encoded string. This function
+ * decodes that representation back into raw bytes.
+ *
+ * @param input - An object potentially containing a `$bytes` property
+ * @returns The decoded `Uint8Array` if the input is a valid `$bytes` object,
+ *          or `undefined` if the input is not a valid `$bytes` representation
+ *
+ * @example
+ * ```typescript
+ * // Parse a $bytes object to Uint8Array
+ * const bytes = parseLexBytes({ $bytes: 'SGVsbG8sIHdvcmxkIQ==' })
+ * // bytes is Uint8Array containing "Hello, world!"
+ *
+ * // Returns undefined for non-$bytes objects
+ * const result = parseLexBytes({ foo: 'bar' })
+ * // result is undefined
+ *
+ * // Returns undefined for objects with extra properties
+ * const invalid = parseLexBytes({ $bytes: 'SGVsbG8=', extra: true })
+ * // invalid is undefined
+ * ```
+ */
+export declare function parseLexBytes(input?: Record<string, unknown>): Uint8Array | undefined;
+/**
+ * Encodes a `Uint8Array` into a `{$bytes: string}` JSON representation.
+ *
+ * In the AT Protocol data model, binary data is represented in JSON as an object
+ * with a single `$bytes` property containing a base64-encoded string. This function
+ * performs that encoding.
+ *
+ * @param bytes - The binary data to encode
+ * @returns An object with a `$bytes` property containing the base64-encoded data
+ *
+ * @example
+ * ```typescript
+ * const bytes = new TextEncoder().encode('Hello, world!')
+ * const encoded = encodeLexBytes(bytes)
+ * // encoded is { $bytes: 'SGVsbG8sIHdvcmxkIQ==' }
+ * ```
+ */
 export declare function encodeLexBytes(bytes: Uint8Array): JsonValue;
 //# sourceMappingURL=bytes.d.ts.map

package/dist/bytes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bytes.d.ts","sourceRoot":"","sources":["../src/bytes.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAA;AAErC,wBAAgB,aAAa,CAAC,KAAK,CAAC,EAAE;IACpC,MAAM,CAAC,EAAE,OAAO,CAAA;CACjB,GAAG,UAAU,GAAG,SAAS,CAgBzB;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,UAAU,GAAG,SAAS,CAE3D"}
+{"version":3,"file":"bytes.d.ts","sourceRoot":"","sources":["../src/bytes.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAA;AAErC;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,aAAa,CAC3B,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,UAAU,GAAG,SAAS,CAoBxB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,UAAU,GAAG,SAAS,CAE3D"}

package/dist/bytes.js

@@ -3,6 +3,32 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.parseLexBytes = parseLexBytes;
 exports.encodeLexBytes = encodeLexBytes;
 const lex_data_1 = require("@atproto/lex-data");
+/**
+ * Parses a `{$bytes: string}` JSON object into a `Uint8Array`.
+ *
+ * In the AT Protocol data model, binary data is represented in JSON as an object
+ * with a single `$bytes` property containing a base64-encoded string. This function
+ * decodes that representation back into raw bytes.
+ *
+ * @param input - An object potentially containing a `$bytes` property
+ * @returns The decoded `Uint8Array` if the input is a valid `$bytes` object,
+ *          or `undefined` if the input is not a valid `$bytes` representation
+ *
+ * @example
+ * ```typescript
+ * // Parse a $bytes object to Uint8Array
+ * const bytes = parseLexBytes({ $bytes: 'SGVsbG8sIHdvcmxkIQ==' })
+ * // bytes is Uint8Array containing "Hello, world!"
+ *
+ * // Returns undefined for non-$bytes objects
+ * const result = parseLexBytes({ foo: 'bar' })
+ * // result is undefined
+ *
+ * // Returns undefined for objects with extra properties
+ * const invalid = parseLexBytes({ $bytes: 'SGVsbG8=', extra: true })
+ * // invalid is undefined
+ * ```
+ */
 function parseLexBytes(input) {
     if (!input || !('$bytes' in input)) {
         return undefined;
@@ -13,10 +39,32 @@ function parseLexBytes(input) {
         }
     }
     if (typeof input.$bytes !== 'string') {
-        throw new TypeError('$bytes must be a base64-encoded string');
+        return undefined;
+    }
+    try {
+        return (0, lex_data_1.fromBase64)(input.$bytes);
+    }
+    catch {
+        return undefined;
     }
-    return (0, lex_data_1.fromBase64)(input.$bytes);
 }
+/**
+ * Encodes a `Uint8Array` into a `{$bytes: string}` JSON representation.
+ *
+ * In the AT Protocol data model, binary data is represented in JSON as an object
+ * with a single `$bytes` property containing a base64-encoded string. This function
+ * performs that encoding.
+ *
+ * @param bytes - The binary data to encode
+ * @returns An object with a `$bytes` property containing the base64-encoded data
+ *
+ * @example
+ * ```typescript
+ * const bytes = new TextEncoder().encode('Hello, world!')
+ * const encoded = encodeLexBytes(bytes)
+ * // encoded is { $bytes: 'SGVsbG8sIHdvcmxkIQ==' }
+ * ```
+ */
 function encodeLexBytes(bytes) {
     return { $bytes: (0, lex_data_1.toBase64)(bytes) };
 }

package/dist/bytes.js.map

@@ -1 +1 @@
-{"version":3,"file":"bytes.js","sourceRoot":"","sources":["../src/bytes.ts"],"names":[],"mappings":";;AAGA,sCAkBC;AAED,wCAEC;AAzBD,gDAAwD;AAGxD,SAAgB,aAAa,CAAC,KAE7B;IACC,IAAI,CAAC,KAAK,IAAI,CAAC,CAAC,QAAQ,IAAI,KAAK,CAAC,EAAE,CAAC;QACnC,OAAO,SAAS,CAAA;IAClB,CAAC;IAED,KAAK,MAAM,GAAG,IAAI,KAAK,EAAE,CAAC;QACxB,IAAI,GAAG,KAAK,QAAQ,EAAE,CAAC;YACrB,OAAO,SAAS,CAAA;QAClB,CAAC;IACH,CAAC;IAED,IAAI,OAAO,KAAK,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;QACrC,MAAM,IAAI,SAAS,CAAC,wCAAwC,CAAC,CAAA;IAC/D,CAAC;IAED,OAAO,IAAA,qBAAU,EAAC,KAAK,CAAC,MAAM,CAAC,CAAA;AACjC,CAAC;AAED,SAAgB,cAAc,CAAC,KAAiB;IAC9C,OAAO,EAAE,MAAM,EAAE,IAAA,mBAAQ,EAAC,KAAK,CAAC,EAAE,CAAA;AACpC,CAAC","sourcesContent":["import { fromBase64, toBase64 } from '@atproto/lex-data'\nimport { JsonValue } from './json.js'\n\nexport function parseLexBytes(input?: {\n  $bytes?: unknown\n}): Uint8Array | undefined {\n  if (!input || !('$bytes' in input)) {\n    return undefined\n  }\n\n  for (const key in input) {\n    if (key !== '$bytes') {\n      return undefined\n    }\n  }\n\n  if (typeof input.$bytes !== 'string') {\n    throw new TypeError('$bytes must be a base64-encoded string')\n  }\n\n  return fromBase64(input.$bytes)\n}\n\nexport function encodeLexBytes(bytes: Uint8Array): JsonValue {\n  return { $bytes: toBase64(bytes) }\n}\n"]}
+{"version":3,"file":"bytes.js","sourceRoot":"","sources":["../src/bytes.ts"],"names":[],"mappings":";;AA6BA,sCAsBC;AAmBD,wCAEC;AAxED,gDAAwD;AAGxD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,SAAgB,aAAa,CAC3B,KAA+B;IAE/B,IAAI,CAAC,KAAK,IAAI,CAAC,CAAC,QAAQ,IAAI,KAAK,CAAC,EAAE,CAAC;QACnC,OAAO,SAAS,CAAA;IAClB,CAAC;IAED,KAAK,MAAM,GAAG,IAAI,KAAK,EAAE,CAAC;QACxB,IAAI,GAAG,KAAK,QAAQ,EAAE,CAAC;YACrB,OAAO,SAAS,CAAA;QAClB,CAAC;IACH,CAAC;IAED,IAAI,OAAO,KAAK,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;QACrC,OAAO,SAAS,CAAA;IAClB,CAAC;IAED,IAAI,CAAC;QACH,OAAO,IAAA,qBAAU,EAAC,KAAK,CAAC,MAAM,CAAC,CAAA;IACjC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAA;IAClB,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,SAAgB,cAAc,CAAC,KAAiB;IAC9C,OAAO,EAAE,MAAM,EAAE,IAAA,mBAAQ,EAAC,KAAK,CAAC,EAAE,CAAA;AACpC,CAAC","sourcesContent":["import { fromBase64, toBase64 } from '@atproto/lex-data'\nimport { JsonValue } from './json.js'\n\n/**\n * Parses a `{$bytes: string}` JSON object into a `Uint8Array`.\n *\n * In the AT Protocol data model, binary data is represented in JSON as an object\n * with a single `$bytes` property containing a base64-encoded string. This function\n * decodes that representation back into raw bytes.\n *\n * @param input - An object potentially containing a `$bytes` property\n * @returns The decoded `Uint8Array` if the input is a valid `$bytes` object,\n *          or `undefined` if the input is not a valid `$bytes` representation\n *\n * @example\n * ```typescript\n * // Parse a $bytes object to Uint8Array\n * const bytes = parseLexBytes({ $bytes: 'SGVsbG8sIHdvcmxkIQ==' })\n * // bytes is Uint8Array containing \"Hello, world!\"\n *\n * // Returns undefined for non-$bytes objects\n * const result = parseLexBytes({ foo: 'bar' })\n * // result is undefined\n *\n * // Returns undefined for objects with extra properties\n * const invalid = parseLexBytes({ $bytes: 'SGVsbG8=', extra: true })\n * // invalid is undefined\n * ```\n */\nexport function parseLexBytes(\n  input?: Record<string, unknown>,\n): Uint8Array | undefined {\n  if (!input || !('$bytes' in input)) {\n    return undefined\n  }\n\n  for (const key in input) {\n    if (key !== '$bytes') {\n      return undefined\n    }\n  }\n\n  if (typeof input.$bytes !== 'string') {\n    return undefined\n  }\n\n  try {\n    return fromBase64(input.$bytes)\n  } catch {\n    return undefined\n  }\n}\n\n/**\n * Encodes a `Uint8Array` into a `{$bytes: string}` JSON representation.\n *\n * In the AT Protocol data model, binary data is represented in JSON as an object\n * with a single `$bytes` property containing a base64-encoded string. This function\n * performs that encoding.\n *\n * @param bytes - The binary data to encode\n * @returns An object with a `$bytes` property containing the base64-encoded data\n *\n * @example\n * ```typescript\n * const bytes = new TextEncoder().encode('Hello, world!')\n * const encoded = encodeLexBytes(bytes)\n * // encoded is { $bytes: 'SGVsbG8sIHdvcmxkIQ==' }\n * ```\n */\nexport function encodeLexBytes(bytes: Uint8Array): JsonValue {\n  return { $bytes: toBase64(bytes) }\n}\n"]}

package/dist/json.d.ts

@@ -1,7 +1,50 @@
+/**
+ * Primitive JSON values: string, number, boolean, or null.
+ *
+ * These are the scalar (non-composite) types that can appear in JSON data.
+ * In the context of the AT Protocol:
+ * - `string` - Text values, including special encoded types like `$link` and `$bytes`
+ * - `number` - Numeric values (note: Lex only supports safe integers)
+ * - `boolean` - True/false values
+ * - `null` - Explicit null values
+ *
+ * @see {@link JsonValue} for the complete JSON type including arrays and objects
+ */
 export type JsonScalar = number | string | boolean | null;
+/**
+ * Any valid JSON value.
+ *
+ * This is a recursive type that represents the full JSON data model:
+ * - Scalars: string, number, boolean, null
+ * - Arrays: ordered lists of JSON values
+ * - Objects: string-keyed maps of JSON values
+ *
+ * @example
+ * ```typescript
+ * const scalar: JsonValue = "hello"
+ * const array: JsonValue = [1, 2, 3]
+ * const object: JsonValue = { name: "Alice", age: 30 }
+ * const nested: JsonValue = { users: [{ name: "Bob" }] }
+ * ```
+ */
 export type JsonValue = JsonScalar | JsonValue[] | {
     [_ in string]?: JsonValue;
 };
+/**
+ * A JSON object with string keys and JSON values.
+ *
+ * This type represents a plain JavaScript object that is valid JSON,
+ * where all keys are strings and all values are valid JSON values.
+ *
+ * @example
+ * ```typescript
+ * const obj: JsonObject = {
+ *   name: "Alice",
+ *   tags: ["admin", "user"],
+ *   metadata: { created: "2024-01-01" }
+ * }
+ * ```
+ */
 export type JsonObject = {
     [_ in string]?: JsonValue;
 };

package/dist/json.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"json.d.ts","sourceRoot":"","sources":["../src/json.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAA;AACzD,MAAM,MAAM,SAAS,GAAG,UAAU,GAAG,SAAS,EAAE,GAAG;KAAG,CAAC,IAAI,MAAM,CAAC,CAAC,EAAE,SAAS;CAAE,CAAA;AAChF,MAAM,MAAM,UAAU,GAAG;KAAG,CAAC,IAAI,MAAM,CAAC,CAAC,EAAE,SAAS;CAAE,CAAA"}
+{"version":3,"file":"json.d.ts","sourceRoot":"","sources":["../src/json.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAA;AAEzD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,SAAS,GAAG,UAAU,GAAG,SAAS,EAAE,GAAG;KAAG,CAAC,IAAI,MAAM,CAAC,CAAC,EAAE,SAAS;CAAE,CAAA;AAEhF;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,UAAU,GAAG;KAAG,CAAC,IAAI,MAAM,CAAC,CAAC,EAAE,SAAS;CAAE,CAAA"}

package/dist/json.js.map

@@ -1 +1 @@
-{"version":3,"file":"json.js","sourceRoot":"","sources":["../src/json.ts"],"names":[],"mappings":"","sourcesContent":["export type JsonScalar = number | string | boolean | null\nexport type JsonValue = JsonScalar | JsonValue[] | { [_ in string]?: JsonValue }\nexport type JsonObject = { [_ in string]?: JsonValue }\n"]}
+{"version":3,"file":"json.js","sourceRoot":"","sources":["../src/json.ts"],"names":[],"mappings":"","sourcesContent":["/**\n * Primitive JSON values: string, number, boolean, or null.\n *\n * These are the scalar (non-composite) types that can appear in JSON data.\n * In the context of the AT Protocol:\n * - `string` - Text values, including special encoded types like `$link` and `$bytes`\n * - `number` - Numeric values (note: Lex only supports safe integers)\n * - `boolean` - True/false values\n * - `null` - Explicit null values\n *\n * @see {@link JsonValue} for the complete JSON type including arrays and objects\n */\nexport type JsonScalar = number | string | boolean | null\n\n/**\n * Any valid JSON value.\n *\n * This is a recursive type that represents the full JSON data model:\n * - Scalars: string, number, boolean, null\n * - Arrays: ordered lists of JSON values\n * - Objects: string-keyed maps of JSON values\n *\n * @example\n * ```typescript\n * const scalar: JsonValue = \"hello\"\n * const array: JsonValue = [1, 2, 3]\n * const object: JsonValue = { name: \"Alice\", age: 30 }\n * const nested: JsonValue = { users: [{ name: \"Bob\" }] }\n * ```\n */\nexport type JsonValue = JsonScalar | JsonValue[] | { [_ in string]?: JsonValue }\n\n/**\n * A JSON object with string keys and JSON values.\n *\n * This type represents a plain JavaScript object that is valid JSON,\n * where all keys are strings and all values are valid JSON values.\n *\n * @example\n * ```typescript\n * const obj: JsonObject = {\n *   name: \"Alice\",\n *   tags: [\"admin\", \"user\"],\n *   metadata: { created: \"2024-01-01\" }\n * }\n * ```\n */\nexport type JsonObject = { [_ in string]?: JsonValue }\n"]}

package/dist/lex-json.d.ts

@@ -1,14 +1,139 @@
 import { LexValue } from '@atproto/lex-data';
 import { JsonValue } from './json.js';
+/**
+ * Serialize a Lex value to a JSON string.
+ *
+ * This function serializes AT Protocol data model values to JSON, automatically
+ * encoding special types:
+ * - `Cid` instances are encoded as `{$link: string}`
+ * - `Uint8Array` instances are encoded as `{$bytes: string}` (base64)
+ *
+ * @param input - The Lex value to stringify
+ * @returns A JSON string representation of the value
+ *
+ * @example
+ * ```typescript
+ * import { lexStringify } from '@atproto/lex'
+ *
+ * // Stringify with CID and bytes encoding
+ * const json = lexStringify({
+ *   ref: someCid,
+ *   data: new Uint8Array([72, 101, 108, 108, 111])
+ * })
+ * // json is '{"ref":{"$link":"bafyrei..."},"data":{"$bytes":"SGVsbG8="}}'
+ * ```
+ */
 export declare function lexStringify(input: LexValue): string;
+/**
+ * Options for parsing JSON to Lex values.
+ */
 export type LexParseOptions = {
     /**
-     * Forbids the presence of invalid Lex values (e.g. non-integer numbers,
-     * malformed $link, $bytes, blob objects, etc.)
+     * When enabled, forbids the presence of invalid Lex values such as:
+     * - Non-integer numbers (only safe integers are valid in the Lex data model)
+     * - Malformed `$link` objects
+     * - Malformed `$bytes` objects
+     * - Objects with invalid or empty `$type` properties
+     * - Invalid {@link BlobRef} (`$type: 'blob'`) objects
+     *
+     * When disabled (default), invalid special objects are left as plain objects.
+     *
+     * @default false
      */
     strict?: boolean;
 };
+/**
+ * Parses a JSON string into Lex values.
+ *
+ * This function parses JSON and automatically decodes AT Protocol special types:
+ * - `{$link: string}` objects are decoded to `Cid` instances
+ * - `{$bytes: string}` objects are decoded to `Uint8Array` instances
+ * - `{$type: 'blob'}` objects are validated
+ *
+ * @typeParam T - Type cast for the resulting Lex value. Use when you want to specify the expected structure of the parsed data.
+ * @param input - The JSON string to parse
+ * @param options - Parsing options (e.g., strict mode)
+ * @returns The parsed Lex value
+ * @throws {SyntaxError} If the input is not valid JSON
+ * @throws {TypeError} If strict mode is enabled and invalid Lex values are found
+ *
+ * @example
+ * ```typescript
+ * import { lexParse } from '@atproto/lex'
+ *
+ * // Parse JSON with $link and $bytes decoding
+ * const parsed = lexParse<{
+ *   ref: Cid
+ *   data: Uint8Array
+ * }>(`{
+ *   "ref": { "$link": "bafyrei..." },
+ *   "data": { "$bytes": "SGVsbG8sIHdvcmxkIQ==" }
+ * }`)
+ *
+ * // Parse a single CID
+ * const someCid = lexParse<Cid>('{"$link": "bafyrei..."}')
+ *
+ * // Parse binary data
+ * const someBytes = lexParse<Uint8Array>('{"$bytes": "SGVsbG8sIHdvcmxkIQ=="}')
+ * ```
+ */
 export declare function lexParse<T extends LexValue = LexValue>(input: string, options?: LexParseOptions): T;
+/**
+ * Converts a parsed JSON representation of Lexicon value to a {@link LexValue}.
+ *
+ * This function transforms already-parsed JSON objects into Lex values by
+ * decoding AT Protocol special types:
+ * - `{$link: string}` objects are converted to `Cid` instances
+ * - `{$bytes: string}` objects are converted to `Uint8Array` instances
+ *
+ * Use this when you have a JavaScript object (e.g., from `JSON.parse()`) and
+ * need to convert it to the Lex data model. For parsing JSON strings directly,
+ * use {@link lexParse} instead.
+ *
+ * @param value - The JSON value to convert
+ * @param options - Parsing options (e.g., strict mode)
+ * @returns The converted Lex value
+ * @throws {TypeError} If strict mode is enabled and invalid Lex values are found
+ * @throws {TypeError} If the value contains unsupported types (e.g., undefined at top level)
+ *
+ * @example
+ * ```typescript
+ * import { jsonToLex } from '@atproto/lex'
+ *
+ * // Convert parsed JSON to Lex values
+ * const lex = jsonToLex({
+ *   ref: { $link: 'bafyrei...' },  // Converted to Cid
+ *   data: { $bytes: 'SGVsbG8sIHdvcmxkIQ==' }  // Converted to Uint8Array
+ * })
+ * ```
+ */
 export declare function jsonToLex(value: JsonValue, options?: LexParseOptions): LexValue;
+/**
+ * Converts a Lex value to a JSON-compatible value.
+ *
+ * This function transforms Lex data model values into plain JavaScript objects
+ * suitable for JSON serialization:
+ * - `Cid` instances are converted to `{$link: string}` objects
+ * - `Uint8Array` instances are converted to `{$bytes: string}` objects (base64)
+ *
+ * Use this when you need to convert Lex values to plain objects (e.g., for
+ * custom serialization or inspection). For direct JSON string output, use
+ * {@link lexStringify} instead.
+ *
+ * @param value - The Lex value to convert
+ * @returns The JSON-compatible value
+ * @throws {TypeError} If the value contains unsupported types
+ *
+ * @example
+ * ```typescript
+ * import { lexToJson } from '@atproto/lex'
+ *
+ * // Convert Lex values to JSON-compatible objects
+ * const obj = lexToJson({
+ *   ref: someCid,      // Converted to { $link: string }
+ *   data: someBytes    // Converted to { $bytes: string }
+ * })
+ * ```
+ */
 export declare function lexToJson(value: LexValue): JsonValue;
 //# sourceMappingURL=lex-json.d.ts.map

package/dist/lex-json.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lex-json.d.ts","sourceRoot":"","sources":["../src/lex-json.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,QAAQ,EAET,MAAM,mBAAmB,CAAA;AAG1B,OAAO,EAAc,SAAS,EAAE,MAAM,WAAW,CAAA;AAGjD,wBAAgB,YAAY,CAAC,KAAK,EAAE,QAAQ,GAAG,MAAM,CAKpD;AAED,MAAM,MAAM,eAAe,GAAG;IAC5B;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAA;CACjB,CAAA;AAED,wBAAgB,QAAQ,CAAC,CAAC,SAAS,QAAQ,GAAG,QAAQ,EACpD,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,eAAmC,GAC3C,CAAC,CAiBH;AAED,wBAAgB,SAAS,CACvB,KAAK,EAAE,SAAS,EAChB,OAAO,GAAE,eAAmC,GAC3C,QAAQ,CAsBV;AA+CD,wBAAgB,SAAS,CAAC,KAAK,EAAE,QAAQ,GAAG,SAAS,CAqBpD"}
+{"version":3,"file":"lex-json.d.ts","sourceRoot":"","sources":["../src/lex-json.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,QAAQ,EAET,MAAM,mBAAmB,CAAA;AAG1B,OAAO,EAAc,SAAS,EAAE,MAAM,WAAW,CAAA;AAGjD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,QAAQ,GAAG,MAAM,CAKpD;AAED;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,EAAE,OAAO,CAAA;CACjB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,QAAQ,GAAG,QAAQ,EACpD,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,eAAmC,GAC3C,CAAC,CAiBH;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,SAAS,CACvB,KAAK,EAAE,SAAS,EAChB,OAAO,GAAE,eAAmC,GAC3C,QAAQ,CAsBV;AA+CD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,QAAQ,GAAG,SAAS,CAqBpD"}

package/dist/lex-json.js

@@ -8,12 +8,70 @@ const lex_data_1 = require("@atproto/lex-data");
 const blob_js_1 = require("./blob.js");
 const bytes_js_1 = require("./bytes.js");
 const link_js_1 = require("./link.js");
+/**
+ * Serialize a Lex value to a JSON string.
+ *
+ * This function serializes AT Protocol data model values to JSON, automatically
+ * encoding special types:
+ * - `Cid` instances are encoded as `{$link: string}`
+ * - `Uint8Array` instances are encoded as `{$bytes: string}` (base64)
+ *
+ * @param input - The Lex value to stringify
+ * @returns A JSON string representation of the value
+ *
+ * @example
+ * ```typescript
+ * import { lexStringify } from '@atproto/lex'
+ *
+ * // Stringify with CID and bytes encoding
+ * const json = lexStringify({
+ *   ref: someCid,
+ *   data: new Uint8Array([72, 101, 108, 108, 111])
+ * })
+ * // json is '{"ref":{"$link":"bafyrei..."},"data":{"$bytes":"SGVsbG8="}}'
+ * ```
+ */
 function lexStringify(input) {
     // @NOTE Because of the way the "replacer" works in JSON.stringify, it's
     // simpler to convert Lex to JSON first rather than trying to do it
     // on-the-fly.
     return JSON.stringify(lexToJson(input));
 }
+/**
+ * Parses a JSON string into Lex values.
+ *
+ * This function parses JSON and automatically decodes AT Protocol special types:
+ * - `{$link: string}` objects are decoded to `Cid` instances
+ * - `{$bytes: string}` objects are decoded to `Uint8Array` instances
+ * - `{$type: 'blob'}` objects are validated
+ *
+ * @typeParam T - Type cast for the resulting Lex value. Use when you want to specify the expected structure of the parsed data.
+ * @param input - The JSON string to parse
+ * @param options - Parsing options (e.g., strict mode)
+ * @returns The parsed Lex value
+ * @throws {SyntaxError} If the input is not valid JSON
+ * @throws {TypeError} If strict mode is enabled and invalid Lex values are found
+ *
+ * @example
+ * ```typescript
+ * import { lexParse } from '@atproto/lex'
+ *
+ * // Parse JSON with $link and $bytes decoding
+ * const parsed = lexParse<{
+ *   ref: Cid
+ *   data: Uint8Array
+ * }>(`{
+ *   "ref": { "$link": "bafyrei..." },
+ *   "data": { "$bytes": "SGVsbG8sIHdvcmxkIQ==" }
+ * }`)
+ *
+ * // Parse a single CID
+ * const someCid = lexParse<Cid>('{"$link": "bafyrei..."}')
+ *
+ * // Parse binary data
+ * const someBytes = lexParse<Uint8Array>('{"$bytes": "SGVsbG8sIHdvcmxkIQ=="}')
+ * ```
+ */
 function lexParse(input, options = { strict: false }) {
     return JSON.parse(input, function (key, value) {
         switch (typeof value) {
@@ -35,6 +93,35 @@ function lexParse(input, options = { strict: false }) {
         }
     });
 }
+/**
+ * Converts a parsed JSON representation of Lexicon value to a {@link LexValue}.
+ *
+ * This function transforms already-parsed JSON objects into Lex values by
+ * decoding AT Protocol special types:
+ * - `{$link: string}` objects are converted to `Cid` instances
+ * - `{$bytes: string}` objects are converted to `Uint8Array` instances
+ *
+ * Use this when you have a JavaScript object (e.g., from `JSON.parse()`) and
+ * need to convert it to the Lex data model. For parsing JSON strings directly,
+ * use {@link lexParse} instead.
+ *
+ * @param value - The JSON value to convert
+ * @param options - Parsing options (e.g., strict mode)
+ * @returns The converted Lex value
+ * @throws {TypeError} If strict mode is enabled and invalid Lex values are found
+ * @throws {TypeError} If the value contains unsupported types (e.g., undefined at top level)
+ *
+ * @example
+ * ```typescript
+ * import { jsonToLex } from '@atproto/lex'
+ *
+ * // Convert parsed JSON to Lex values
+ * const lex = jsonToLex({
+ *   ref: { $link: 'bafyrei...' },  // Converted to Cid
+ *   data: { $bytes: 'SGVsbG8sIHdvcmxkIQ==' }  // Converted to Uint8Array
+ * })
+ * ```
+ */
 function jsonToLex(value, options = { strict: false }) {
     switch (typeof value) {
         case 'object': {
@@ -94,6 +181,33 @@ function jsonObjectToLexMap(input, options) {
     }
     return copy ?? input;
 }
+/**
+ * Converts a Lex value to a JSON-compatible value.
+ *
+ * This function transforms Lex data model values into plain JavaScript objects
+ * suitable for JSON serialization:
+ * - `Cid` instances are converted to `{$link: string}` objects
+ * - `Uint8Array` instances are converted to `{$bytes: string}` objects (base64)
+ *
+ * Use this when you need to convert Lex values to plain objects (e.g., for
+ * custom serialization or inspection). For direct JSON string output, use
+ * {@link lexStringify} instead.
+ *
+ * @param value - The Lex value to convert
+ * @returns The JSON-compatible value
+ * @throws {TypeError} If the value contains unsupported types
+ *
+ * @example
+ * ```typescript
+ * import { lexToJson } from '@atproto/lex'
+ *
+ * // Convert Lex values to JSON-compatible objects
+ * const obj = lexToJson({
+ *   ref: someCid,      // Converted to { $link: string }
+ *   data: someBytes    // Converted to { $bytes: string }
+ * })
+ * ```
+ */
 function lexToJson(value) {
     switch (typeof value) {
         case 'object':