@atproto/lex-json 0.0.10 → 0.0.11

package/src/lex-json.ts

@@ -11,6 +11,29 @@ import { encodeLexBytes, parseLexBytes } from './bytes.js'
 import { JsonObject, JsonValue } from './json.js'
 import { encodeLexLink, parseLexLink } from './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="}}'
+ * ```
+ */
 export function lexStringify(input: LexValue): string {
   // @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
@@ -18,14 +41,60 @@ export function lexStringify(input: LexValue): string {
   return JSON.stringify(lexToJson(input))
 }
 
+/**
+ * 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 function lexParse<T extends LexValue = LexValue>(
   input: string,
   options: LexParseOptions = { strict: false },
@@ -48,6 +117,35 @@ export function lexParse<T extends LexValue = LexValue>(
   })
 }
 
+/**
+ * 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 function jsonToLex(
   value: JsonValue,
   options: LexParseOptions = { strict: false },
@@ -120,6 +218,33 @@ function jsonObjectToLexMap(
   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 }
+ * })
+ * ```
+ */
 export function lexToJson(value: LexValue): JsonValue {
   switch (typeof value) {
     case 'object':

package/src/link.ts

@@ -6,6 +6,35 @@ import {
 } from '@atproto/lex-data'
 import { JsonValue } from './json.js'
 
+/**
+ * Parses a `{$link: string}` JSON object into a {@link Cid} instance.
+ *
+ * In the AT Protocol data model, CID references are represented in JSON as an
+ * object with a single `$link` property containing a base32-encoded CID string,
+ * prefixed with "b". This function decodes that representation into a `Cid`
+ * object.
+ *
+ * @param input - An object potentially containing a `{$link: string}` property
+ * @param options - Optional CID validation options
+ * @returns The parsed {@link Cid} if the input is a valid `$link` object,
+ *          or `undefined` if the input is not a valid `$link` representation
+ * @throws {TypeError} If `$link` is present but is not a valid CID string
+ *
+ * @example
+ * ```typescript
+ * // Parse a $link object to Cid
+ * const cid = parseLexLink({ $link: 'bafyreib2rxk3rybloqtqwbo' })
+ * // cid is a Cid instance
+ *
+ * // Returns undefined for non-$link objects
+ * const result = parseLexLink({ foo: 'bar' })
+ * // result is undefined
+ *
+ * // Returns undefined for objects with extra properties
+ * const invalid = parseLexLink({ $link: 'bafyrei...', extra: true })
+ * // invalid is undefined
+ * ```
+ */
 export function parseLexLink<TOptions extends CheckCidOptions>(
   input: undefined | Record<string, unknown>,
   options: TOptions,
@@ -31,25 +60,42 @@ export function parseLexLink(
   const { $link } = input
 
   if (typeof $link !== 'string') {
-    throw new TypeError('$link must be a base32-encoded CID string')
+    return undefined
   }
 
   if ($link.length === 0) {
-    throw new TypeError('CID string in $link cannot be empty')
+    return undefined
   }
 
   // Arbitrary limit to prevent DoS via extremely long CIDs
   if ($link.length > 2048) {
-    throw new TypeError('CID string in $link is too long')
+    return undefined
   }
 
   try {
     return parseCid($link, options)
   } catch (cause) {
-    throw new TypeError('Invalid CID string in $link', { cause })
+    return undefined
   }
 }
 
+/**
+ * Encodes a {@link Cid} instance into a `{$link: string}` JSON representation.
+ *
+ * In the AT Protocol data model, CID references are represented in JSON as an
+ * object with a single `$link` property containing a base32-encoded CID string,
+ * prefixed with "b". This function performs that encoding.
+ *
+ * @param cid - The CID to encode
+ * @returns An object with a `$link` property containing the string representation of the CID
+ *
+ * @example
+ * ```typescript
+ * const cid = CID.parse('bafyreib2rxk3rybloqtqwbo')
+ * const encoded = encodeLexLink(cid)
+ * // encoded is { $link: 'bafyreib2rxk3rybloqtqwbo' }
+ * ```
+ */
 export function encodeLexLink(cid: Cid): JsonValue {
   return { $link: cid.toString() }
 }