@atproto/lex-data 0.0.10 → 0.0.11

package/src/lex.ts

@@ -1,19 +1,142 @@
 import { Cid, isCid } from './cid.js'
 import { isPlainObject, isPlainProto } from './object.js'
 
+/**
+ * Primitive values in the Lexicon data model.
+ *
+ * Represents the basic scalar types that can appear in AT Protocol data:
+ * - `number` - Integer values only (no floats)
+ * - `string` - UTF-8 text
+ * - `boolean` - true or false
+ * - `null` - Explicit null value
+ * - `Cid` - Content Identifier (link by hash)
+ * - `Uint8Array` - Binary data (bytes)
+ *
+ * @see {@link LexValue} for the complete recursive value type
+ */
 export type LexScalar = number | string | boolean | null | Cid | Uint8Array
+
+/**
+ * Any valid Lexicon value (recursive type).
+ *
+ * This is the union of all types that can appear in AT Protocol Lexicon data:
+ * - {@link LexScalar} - Primitive values (number, string, boolean, null, Cid, Uint8Array)
+ * - `LexValue[]` - Arrays of LexValues
+ * - `{ [key: string]?: LexValue }` - Objects with string keys and LexValue values
+ *
+ * @example
+ * ```typescript
+ * import type { LexValue } from '@atproto/lex'
+ *
+ * const scalar: LexValue = 'hello'
+ * const array: LexValue = [1, 2, 3]
+ * const object: LexValue = { name: 'Alice', age: 30 }
+ * ```
+ *
+ * @see {@link LexScalar} for primitive value types
+ * @see {@link LexMap} for object types
+ * @see {@link LexArray} for array types
+ */
 export type LexValue = LexScalar | LexValue[] | { [_ in string]?: LexValue }
+
+/**
+ * Object with string keys and LexValue values.
+ *
+ * Represents a plain object in the Lexicon data model where all values
+ * must be valid {@link LexValue} types.
+ *
+ * @example
+ * ```typescript
+ * import type { LexMap } from '@atproto/lex'
+ *
+ * const user: LexMap = {
+ *   name: 'Alice',
+ *   age: 30,
+ *   tags: ['admin', 'user']
+ * }
+ * ```
+ *
+ * @see {@link TypedLexMap} for objects with a required `$type` property
+ */
 export type LexMap = { [_ in string]?: LexValue }
+
+/**
+ * Array of {@link LexValue} elements.
+ *
+ * @example
+ * ```typescript
+ * import type { LexArray } from '@atproto/lex'
+ *
+ * const items: LexArray = [1, 'two', { three: 3 }]
+ * ```
+ */
 export type LexArray = LexValue[]
 
+/**
+ * Type guard to check if a value is a valid {@link LexMap}.
+ *
+ * Returns true if the value is a plain object where all values are valid
+ * {@link LexValue} types.
+ *
+ * @param value - The value to check
+ * @returns `true` if the value is a valid LexMap
+ *
+ * @example
+ * ```typescript
+ * import { isLexMap } from '@atproto/lex'
+ *
+ * if (isLexMap(data)) {
+ *   // data is narrowed to LexMap
+ *   console.log(Object.keys(data))
+ * }
+ * ```
+ */
 export function isLexMap(value: unknown): value is LexMap {
   return isPlainObject(value) && Object.values(value).every(isLexValue)
 }
 
+/**
+ * Type guard to check if a value is a valid {@link LexArray}.
+ *
+ * Returns true if the value is an array where all elements are valid
+ * {@link LexValue} types.
+ *
+ * @param value - The value to check
+ * @returns `true` if the value is a valid LexArray
+ *
+ * @example
+ * ```typescript
+ * import { isLexArray } from '@atproto/lex'
+ *
+ * if (isLexArray(data)) {
+ *   // data is narrowed to LexArray
+ *   data.forEach(item => console.log(item))
+ * }
+ * ```
+ */
 export function isLexArray(value: unknown): value is LexArray {
   return Array.isArray(value) && value.every(isLexValue)
 }
 
+/**
+ * Type guard to check if a value is a valid {@link LexScalar}.
+ *
+ * Returns true if the value is one of the primitive Lexicon types:
+ * number (integer only), string, boolean, null, Cid, or Uint8Array.
+ *
+ * @param value - The value to check
+ * @returns `true` if the value is a valid LexScalar
+ *
+ * @example
+ * ```typescript
+ * import { isLexScalar } from '@atproto/lex'
+ *
+ * isLexScalar('hello')     // true
+ * isLexScalar(42)          // true
+ * isLexScalar(3.14)        // false (floats not allowed)
+ * isLexScalar([1, 2])      // false (arrays are not scalars)
+ * ```
+ */
 export function isLexScalar(value: unknown): value is LexScalar {
   switch (typeof value) {
     case 'object':
@@ -29,6 +152,28 @@ export function isLexScalar(value: unknown): value is LexScalar {
   }
 }
 
+/**
+ * Type guard to check if a value is a valid {@link LexValue}.
+ *
+ * Performs a deep check to validate that the value (and all nested values)
+ * conform to the Lexicon data model. This includes checking for:
+ * - Valid scalar types (number, string, boolean, null, Cid, Uint8Array)
+ * - Arrays containing only valid LexValues
+ * - Plain objects with string keys and valid LexValue values
+ * - No cyclic references (which cannot be serialized to JSON or CBOR)
+ *
+ * @param value - The value to check
+ * @returns `true` if the value is a valid LexValue
+ *
+ * @example
+ * ```typescript
+ * import { isLexValue } from '@atproto/lex'
+ *
+ * isLexValue({ name: 'Alice', tags: ['admin'] })  // true
+ * isLexValue(new Date())                           // false (not a plain object)
+ * isLexValue({ fn: () => {} })                     // false (functions not allowed)
+ * ```
+ */
 export function isLexValue(value: unknown): value is LexValue {
   // Using a stack to avoid recursion depth issues.
   const stack: unknown[] = [value]
@@ -77,7 +222,48 @@ export function isLexValue(value: unknown): value is LexValue {
   return true
 }
 
-export type TypedLexMap = LexMap & { $type: string }
+/**
+ * A {@link LexMap} with a required `$type` property.
+ *
+ * Used to represent typed objects in the Lexicon data model, where the
+ * `$type` property identifies the Lexicon schema that defines the object's
+ * structure.
+ *
+ * @example
+ * ```typescript
+ * import type { TypedLexMap } from '@atproto/lex'
+ *
+ * const post: TypedLexMap = {
+ *   $type: 'app.bsky.feed.post',
+ *   text: 'Hello world!',
+ *   createdAt: '2024-01-01T00:00:00Z'
+ * }
+ * ```
+ *
+ * @see {@link isTypedLexMap} to check if a value is a TypedLexMap
+ */
+export type TypedLexMap<T extends string = string> = LexMap & { $type: T }
+
+/**
+ * Type guard to check if a value is a {@link TypedLexMap}.
+ *
+ * Returns true if the value is a valid {@link LexMap} with a non-empty
+ * `$type` string property.
+ *
+ * @param value - The LexValue to check
+ * @returns `true` if the value is a TypedLexMap
+ *
+ * @example
+ * ```typescript
+ * import { isTypedLexMap } from '@atproto/lex'
+ *
+ * const data = { $type: 'app.bsky.feed.post', text: 'Hello' }
+ *
+ * if (isTypedLexMap(data)) {
+ *   console.log(data.$type)  // 'app.bsky.feed.post'
+ * }
+ * ```
+ */
 export function isTypedLexMap(value: LexValue): value is TypedLexMap {
   return (
     isLexMap(value) && typeof value.$type === 'string' && value.$type.length > 0

package/src/object.ts

@@ -1,5 +1,22 @@
 /**
  * Checks whether the input is an object (not null).
+ *
+ * Returns true for any non-null value with typeof 'object', including
+ * arrays, plain objects, class instances, etc.
+ *
+ * @param input - The value to check
+ * @returns `true` if the input is an object (not null)
+ *
+ * @example
+ * ```typescript
+ * import { isObject } from '@atproto/lex-data'
+ *
+ * isObject({})           // true
+ * isObject([1, 2, 3])    // true
+ * isObject(new Date())   // true
+ * isObject(null)         // false
+ * isObject('string')     // false
+ * ```
  */
 export function isObject(input: unknown): input is object {
   return input != null && typeof input === 'object'
@@ -9,16 +26,49 @@ const ObjectProto = Object.prototype
 const ObjectToString = Object.prototype.toString
 
 /**
- * Checks whether the input is an object (not null) whose prototype is either
- * null or `Object.prototype`.
+ * Checks whether the input is a plain object.
+ *
+ * A plain object is an object (not null) whose prototype is either null
+ * or `Object.prototype`. This excludes arrays, class instances, and other
+ * special objects.
+ *
+ * @param input - The value to check
+ * @returns `true` if the input is a plain object
+ *
+ * @example
+ * ```typescript
+ * import { isPlainObject } from '@atproto/lex-data'
+ *
+ * isPlainObject({})                    // true
+ * isPlainObject({ a: 1 })              // true
+ * isPlainObject(Object.create(null))   // true
+ * isPlainObject([1, 2, 3])             // false
+ * isPlainObject(new Date())            // false
+ * isPlainObject(null)                  // false
+ * ```
  */
 export function isPlainObject(input: unknown) {
   return isObject(input) && isPlainProto(input)
 }
 
 /**
- * Checks whether the prototype of the input object is either null or
- * `Object.prototype`.
+ * Checks whether the prototype of an object is plain (null or Object.prototype).
+ *
+ * This is useful for checking if an object is a plain object without
+ * checking that it's non-null first (the null check is already done).
+ *
+ * @param input - The object to check (must be non-null)
+ * @returns `true` if the object's prototype is plain
+ *
+ * @example
+ * ```typescript
+ * import { isPlainProto } from '@atproto/lex-data'
+ *
+ * isPlainProto({})                    // true
+ * isPlainProto(Object.create(null))   // true
+ * isPlainProto([1, 2, 3])             // false (Array.prototype)
+ * isPlainProto(new Date())            // false (Date.prototype)
+ * ```
  */
 export function isPlainProto(input: object): input is Record<string, unknown> {
   const proto = Object.getPrototypeOf(input)

package/src/uint8array.ts

@@ -21,7 +21,21 @@ export type { Base64Alphabet }
 /**
  * Encodes a Uint8Array into a base64 string.
  *
+ * Uses native Uint8Array.prototype.toBase64 when available (Node.js 24+, modern browsers),
+ * falling back to Node.js Buffer or a ponyfill implementation.
+ *
+ * @param bytes - The binary data to encode
+ * @param alphabet - The base64 alphabet to use ('base64' or 'base64url'), defaults to 'base64'
  * @returns The base64 encoded string
+ *
+ * @example
+ * ```typescript
+ * import { toBase64 } from '@atproto/lex-data'
+ *
+ * const bytes = new Uint8Array([72, 101, 108, 108, 111])
+ * toBase64(bytes)           // 'SGVsbG8='
+ * toBase64(bytes, 'base64url')  // 'SGVsbG8' (URL-safe, no padding)
+ * ```
  */
 export const toBase64: (
   bytes: Uint8Array,
@@ -32,11 +46,24 @@ export const toBase64: (
   toBase64Ponyfill
 
 /**
- * Decodes a base64 string into a Uint8Array. This function supports both padded
- * and unpadded base64 strings.
+ * Decodes a base64 string into a Uint8Array.
+ *
+ * Supports both padded and unpadded base64 strings. Uses native
+ * Uint8Array.fromBase64 when available, falling back to Node.js Buffer
+ * or a ponyfill implementation.
  *
- * @returns The decoded {@link Uint8Array}
+ * @param b64 - The base64 string to decode
+ * @param alphabet - The base64 alphabet to use ('base64' or 'base64url'), defaults to 'base64'
+ * @returns The decoded binary data
  * @throws If the input is not a valid base64 string
+ *
+ * @example
+ * ```typescript
+ * import { fromBase64 } from '@atproto/lex-data'
+ *
+ * fromBase64('SGVsbG8=')       // Uint8Array([72, 101, 108, 108, 111])
+ * fromBase64('SGVsbG8', 'base64url')  // Same, URL-safe alphabet
+ * ```
  */
 export const fromBase64: (
   b64: string,
@@ -54,6 +81,21 @@ if (toBase64 === toBase64Ponyfill || fromBase64 === fromBase64Ponyfill) {
   )
 }
 
+/**
+ * Returns the input if it is a Uint8Array, otherwise returns undefined.
+ *
+ * @param input - The value to check
+ * @returns The input if it's a Uint8Array, otherwise undefined
+ *
+ * @example
+ * ```typescript
+ * import { ifUint8Array } from '@atproto/lex-data'
+ *
+ * ifUint8Array(new Uint8Array([1, 2]))  // Uint8Array([1, 2])
+ * ifUint8Array('not binary')            // undefined
+ * ifUint8Array(new ArrayBuffer(4))      // undefined
+ * ```
+ */
 export function ifUint8Array(input: unknown): Uint8Array | undefined {
   if (input instanceof Uint8Array) {
     return input
@@ -65,7 +107,23 @@ export function ifUint8Array(input: unknown): Uint8Array | undefined {
 /**
  * Coerces various binary data representations into a Uint8Array.
  *
- * @return `undefined` if the input could not be coerced into a {@link Uint8Array}.
+ * Handles the following input types:
+ * - `Uint8Array` - Returned as-is
+ * - `ArrayBufferView` (e.g., DataView, other TypedArrays) - Converted to Uint8Array
+ * - `ArrayBuffer` - Wrapped in a Uint8Array
+ *
+ * @param input - The value to convert
+ * @returns A Uint8Array, or `undefined` if the input could not be converted
+ *
+ * @example
+ * ```typescript
+ * import { asUint8Array } from '@atproto/lex-data'
+ *
+ * asUint8Array(new Uint8Array([1, 2]))     // Uint8Array([1, 2])
+ * asUint8Array(new ArrayBuffer(4))         // Uint8Array of length 4
+ * asUint8Array(new Int16Array([1, 2]))     // Uint8Array view of the buffer
+ * asUint8Array('string')                   // undefined
+ * ```
  */
 export function asUint8Array(input: unknown): Uint8Array | undefined {
   if (input instanceof Uint8Array) {
@@ -87,6 +145,22 @@ export function asUint8Array(input: unknown): Uint8Array | undefined {
   return undefined
 }
 
+/**
+ * Compares two Uint8Arrays for byte-by-byte equality.
+ *
+ * @param a - First Uint8Array to compare
+ * @param b - Second Uint8Array to compare
+ * @returns `true` if both arrays have the same length and identical bytes
+ *
+ * @example
+ * ```typescript
+ * import { ui8Equals } from '@atproto/lex-data'
+ *
+ * ui8Equals(new Uint8Array([1, 2]), new Uint8Array([1, 2]))  // true
+ * ui8Equals(new Uint8Array([1, 2]), new Uint8Array([1, 3]))  // false
+ * ui8Equals(new Uint8Array([1]), new Uint8Array([1, 2]))     // false
+ * ```
+ */
 export function ui8Equals(a: Uint8Array, b: Uint8Array): boolean {
   if (a.byteLength !== b.byteLength) {
     return false
@@ -101,5 +175,23 @@ export function ui8Equals(a: Uint8Array, b: Uint8Array): boolean {
   return true
 }
 
+/**
+ * Concatenates multiple Uint8Arrays into a single Uint8Array.
+ *
+ * Uses Node.js Buffer.concat when available for performance,
+ * falling back to a ponyfill implementation.
+ *
+ * @param arrays - The Uint8Arrays to concatenate
+ * @returns A new Uint8Array containing all input bytes in order
+ *
+ * @example
+ * ```typescript
+ * import { ui8Concat } from '@atproto/lex-data'
+ *
+ * const a = new Uint8Array([1, 2])
+ * const b = new Uint8Array([3, 4])
+ * ui8Concat([a, b])  // Uint8Array([1, 2, 3, 4])
+ * ```
+ */
 export const ui8Concat =
   /* v8 ignore next -- @preserve */ ui8ConcatNode ?? ui8ConcatPonyfill

package/src/utf8.ts

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