@atproto/lex-schema 0.0.11 → 0.0.12

package/src/schema/array.ts

@@ -7,11 +7,31 @@ import {
 } from '../core.js'
 import { memoizedTransformer } from '../util/memoize.js'
 
+/**
+ * Configuration options for array schema validation.
+ *
+ * @property minLength - Minimum number of items in the array
+ * @property maxLength - Maximum number of items in the array
+ */
 export type ArraySchemaOptions = {
   minLength?: number
   maxLength?: number
 }
 
+/**
+ * Schema for validating arrays where all items match a given schema.
+ *
+ * Validates that the input is an array, checks length constraints, and
+ * validates each item against the provided item schema.
+ *
+ * @template TItem - The validator type for array items
+ *
+ * @example
+ * ```ts
+ * const schema = new ArraySchema(l.string(), { maxLength: 10 })
+ * const result = schema.validate(['a', 'b', 'c'])
+ * ```
+ */
 export class ArraySchema<const TItem extends Validator> extends Schema<
   Array<InferInput<TItem>>,
   Array<InferOutput<TItem>>
@@ -60,6 +80,31 @@ export class ArraySchema<const TItem extends Validator> extends Schema<
   }
 }
 
+/**
+ * Creates an array schema that validates each item against the provided schema.
+ *
+ * @param items - Schema to validate each array item against
+ * @param options - Optional length constraints
+ * @returns A new {@link ArraySchema} instance
+ *
+ * @example
+ * ```ts
+ * // Array of strings
+ * const tagsSchema = l.array(l.string())
+ *
+ * // Array with length constraints
+ * const limitedSchema = l.array(l.integer(), { maxLength: 100 })
+ *
+ * // Array of objects
+ * const usersSchema = l.array(l.object({
+ *   name: l.string(),
+ *   age: l.integer(),
+ * }))
+ *
+ * // Non-empty array
+ * const nonEmptySchema = l.array(l.string(), { minLength: 1 })
+ * ```
+ */
 /*@__NO_SIDE_EFFECTS__*/
 function arraySchema<const TValidator extends Validator>(
   items: TValidator,

package/src/schema/blob.ts

@@ -8,6 +8,13 @@ import {
 import { Schema, ValidationContext } from '../core.js'
 import { memoizedOptions } from '../util/memoize.js'
 
+/**
+ * Configuration options for blob schema validation.
+ *
+ * @property allowLegacy - Whether to allow legacy blob references format
+ * @property accept - List of accepted MIME types (supports wildcards like 'image/*' or '*\/*')
+ * @property maxSize - Maximum blob size in bytes
+ */
 export type BlobSchemaOptions = BlobRefCheckOptions & {
   /**
    * Whether to allow legacy blob references format
@@ -26,6 +33,21 @@ export type BlobSchemaOptions = BlobRefCheckOptions & {
 
 export type { BlobRef, LegacyBlobRef }
 
+/**
+ * Schema for validating blob references in AT Protocol.
+ *
+ * Validates BlobRef objects which contain a CID reference to binary data,
+ * along with metadata like MIME type and size. Can optionally accept
+ * legacy blob reference format.
+ *
+ * @template TOptions - The configuration options type
+ *
+ * @example
+ * ```ts
+ * const schema = new BlobSchema({ accept: ['image/*'], maxSize: 1000000 })
+ * const result = schema.validate(blobRef)
+ * ```
+ */
 export class BlobSchema<
   const TOptions extends BlobSchemaOptions = NonNullable<unknown>,
 > extends Schema<
@@ -80,6 +102,30 @@ function matchesMime(mime: string, accepted: string[]): boolean {
   return false
 }
 
+/**
+ * Creates a blob schema for validating blob references with optional constraints.
+ *
+ * Blob references are used in AT Protocol to reference binary data stored
+ * separately from records. They contain a CID, MIME type, and size information.
+ *
+ * @param options - Optional configuration for MIME type filtering and size limits
+ * @returns A new {@link BlobSchema} instance
+ *
+ * @example
+ * ```ts
+ * // Basic blob reference
+ * const fileSchema = l.blob()
+ *
+ * // Image files only
+ * const imageSchema = l.blob({ accept: ['image/png', 'image/jpeg', 'image/gif'] })
+ *
+ * // Any image type with size limit
+ * const avatarSchema = l.blob({ accept: ['image/*'], maxSize: 1000000 })
+ *
+ * // Allow legacy format
+ * const legacySchema = l.blob({ allowLegacy: true })
+ * ```
+ */
 export const blob = /*#__PURE__*/ memoizedOptions(function <
   O extends BlobSchemaOptions = { allowLegacy?: false },
 >(options?: O) {

package/src/schema/boolean.ts

@@ -1,6 +1,20 @@
 import { Schema, ValidationContext } from '../core.js'
 import { memoizedOptions } from '../util/memoize.js'
 
+/**
+ * Schema for validating boolean values.
+ *
+ * Only accepts JavaScript `true` or `false` values. Does not perform
+ * any coercion from strings or numbers.
+ *
+ * @example
+ * ```ts
+ * const schema = new BooleanSchema()
+ * schema.validate(true)  // success
+ * schema.validate(false) // success
+ * schema.validate('true') // fails - no string coercion
+ * ```
+ */
 export class BooleanSchema extends Schema<boolean> {
   validateInContext(input: unknown, ctx: ValidationContext) {
     if (typeof input === 'boolean') {
@@ -11,6 +25,20 @@ export class BooleanSchema extends Schema<boolean> {
   }
 }
 
+/**
+ * Creates a boolean schema that validates true/false values.
+ *
+ * @returns A new {@link BooleanSchema} instance
+ *
+ * @example
+ * ```ts
+ * const enabledSchema = l.boolean()
+ *
+ * enabledSchema.parse(true)   // true
+ * enabledSchema.parse(false)  // false
+ * enabledSchema.parse('true') // throws - strings not accepted
+ * ```
+ */
 export const boolean = /*#__PURE__*/ memoizedOptions(function () {
   return new BooleanSchema()
 })

package/src/schema/bytes.ts

@@ -2,11 +2,29 @@ import { asUint8Array, ifUint8Array } from '@atproto/lex-data'
 import { Schema, ValidationContext } from '../core.js'
 import { memoizedOptions } from '../util/memoize.js'
 
+/**
+ * Configuration options for bytes schema validation.
+ *
+ * @property minLength - Minimum length in bytes
+ * @property maxLength - Maximum length in bytes
+ */
 export type BytesSchemaOptions = {
   minLength?: number
   maxLength?: number
 }
 
+/**
+ * Schema for validating binary data as Uint8Array with optional length constraints.
+ *
+ * In "parse" mode, coerces various binary formats (Buffer, ArrayBuffer, etc.)
+ * into Uint8Array. In "validate" mode, only accepts Uint8Array directly.
+ *
+ * @example
+ * ```ts
+ * const schema = new BytesSchema({ maxLength: 1024 })
+ * const result = schema.validate(new Uint8Array([1, 2, 3]))
+ * ```
+ */
 export class BytesSchema extends Schema<Uint8Array> {
   constructor(readonly options: BytesSchemaOptions = {}) {
     super()
@@ -34,6 +52,26 @@ export class BytesSchema extends Schema<Uint8Array> {
   }
 }
 
+/**
+ * Creates a bytes schema for validating binary data with optional length constraints.
+ *
+ * Validates Uint8Array values and can coerce other binary formats in parse mode.
+ *
+ * @param options - Optional configuration for minimum and maximum byte length
+ * @returns A new {@link BytesSchema} instance
+ *
+ * @example
+ * ```ts
+ * // Basic bytes schema
+ * const dataSchema = l.bytes()
+ *
+ * // With size constraints
+ * const avatarSchema = l.bytes({ maxLength: 1000000 }) // 1MB max
+ *
+ * // With minimum size
+ * const hashSchema = l.bytes({ minLength: 32, maxLength: 32 }) // Exactly 32 bytes
+ * ```
+ */
 export const bytes = /*#__PURE__*/ memoizedOptions(function (
   options?: BytesSchemaOptions,
 ) {

package/src/schema/cid.ts

@@ -4,8 +4,28 @@ import { memoizedOptions } from '../util/memoize.js'
 
 export type { Cid }
 
+/**
+ * Configuration options for CID schema validation.
+ *
+ * @see CheckCidOptions from @atproto/lex-data for available options
+ */
 export type CidSchemaOptions = CheckCidOptions
 
+/**
+ * Schema for validating Content Identifiers (CIDs).
+ *
+ * CIDs are self-describing content-addressed identifiers used in AT Protocol
+ * to reference data by its cryptographic hash. This schema validates that
+ * the input is a valid CID object.
+ *
+ * @template TOptions - The configuration options type
+ *
+ * @example
+ * ```ts
+ * const schema = new CidSchema()
+ * const result = schema.validate(someCid)
+ * ```
+ */
 export class CidSchema<
   const TOptions extends CidSchemaOptions = { flavor: undefined },
 > extends Schema<InferCheckedCid<TOptions>> {
@@ -22,6 +42,24 @@ export class CidSchema<
   }
 }
 
+/**
+ * Creates a CID schema for validating Content Identifiers.
+ *
+ * CIDs are used throughout AT Protocol to reference content by its hash.
+ * This is commonly used for referencing blobs, commits, and other data.
+ *
+ * @param options - Optional configuration for CID validation
+ * @returns A new {@link CidSchema} instance
+ *
+ * @example
+ * ```ts
+ * // Basic CID validation
+ * const cidSchema = l.cid()
+ *
+ * // Validate a CID from a blob reference
+ * const result = cidSchema.validate(blobRef.ref)
+ * ```
+ */
 export const cid = /*#__PURE__*/ memoizedOptions(function <
   O extends CidSchemaOptions = NonNullable<unknown>,
 >(options?: O) {

package/src/schema/custom.ts

@@ -6,18 +6,46 @@ import {
   ValidationContext,
 } from '../core.js'
 
+/**
+ * Context object provided to custom assertion functions.
+ *
+ * @property path - Current validation path as an array of property keys
+ * @property addIssue - Function to add additional validation issues
+ */
 export type CustomAssertionContext = {
   path: PropertyKey[]
   addIssue(issue: Issue): void
 }
 
+/**
+ * Type guard function for custom schema validation.
+ *
+ * @template TValue - The type to validate/narrow to
+ */
 export type CustomAssertion<TValue> = (
   this: null,
   input: unknown,
   ctx: CustomAssertionContext,
 ) => input is TValue
 
-export class CustomSchema<const TValue = unknown> extends Schema<TValue> {
+/**
+ * Schema with a custom validation function.
+ *
+ * Allows defining completely custom validation logic using a type guard
+ * assertion function. The function receives the input and validation context,
+ * and must return whether the input is valid.
+ *
+ * @template TValue - The validated output type
+ *
+ * @example
+ * ```ts
+ * const schema = new CustomSchema(
+ *   (input): input is Date => input instanceof Date,
+ *   'Expected a Date instance'
+ * )
+ * ```
+ */
+export class CustomSchema<out TValue = unknown> extends Schema<TValue> {
   constructor(
     private readonly assertion: CustomAssertion<TValue>,
     private readonly message: string,
@@ -35,6 +63,43 @@ export class CustomSchema<const TValue = unknown> extends Schema<TValue> {
   }
 }
 
+/**
+ * Creates a custom schema with a user-defined validation function.
+ *
+ * Use this when the built-in schemas don't cover your validation needs.
+ * The assertion function must be a type guard that narrows the input type.
+ *
+ * @param assertion - Type guard function that validates the input
+ * @param message - Error message when validation fails
+ * @param path - Optional path to associate with validation errors
+ * @returns A new {@link CustomSchema} instance
+ *
+ * @example
+ * ```ts
+ * // Validate Date instances
+ * const dateSchema = l.custom(
+ *   (input): input is Date => input instanceof Date && !isNaN(input.getTime()),
+ *   'Expected a valid Date'
+ * )
+ *
+ * // Validate specific object shape
+ * const pointSchema = l.custom(
+ *   (input): input is { x: number; y: number } =>
+ *     typeof input === 'object' &&
+ *     input !== null &&
+ *     typeof (input as any).x === 'number' &&
+ *     typeof (input as any).y === 'number',
+ *   'Expected a point with x and y coordinates'
+ * )
+ *
+ * // With custom path
+ * const validConfig = l.custom(
+ *   (input): input is Config => validateConfig(input),
+ *   'Invalid configuration',
+ *   ['config']
+ * )
+ * ```
+ */
 /*@__NO_SIDE_EFFECTS__*/
 export function custom<TValue>(
   assertion: CustomAssertion<TValue>,

package/src/schema/dict.ts

@@ -8,9 +8,24 @@ import {
 } from '../core.js'
 
 /**
+ * Schema for validating dictionary/map-like objects with dynamic keys.
+ *
+ * Unlike `ObjectSchema` which validates a fixed set of properties, `DictSchema`
+ * validates objects where any string key is allowed, with both keys and values
+ * validated against their respective schemas.
+ *
  * @note There is no dictionary in Lexicon schemas. This is a custom extension
  * to allow map-like objects when using the lex library programmatically (i.e.
  * not code generated from a lexicon schema).
+ *
+ * @template TKey - The validator type for dictionary keys (must validate strings)
+ * @template TValue - The validator type for dictionary values
+ *
+ * @example
+ * ```ts
+ * const schema = new DictSchema(l.string(), l.integer())
+ * const result = schema.validate({ a: 1, b: 2, c: 3 })
+ * ```
  */
 export class DictSchema<
   const TKey extends Validator<string> = any,
@@ -67,6 +82,35 @@ export class DictSchema<
   }
 }
 
+/**
+ * Creates a dictionary schema for validating map-like objects.
+ *
+ * Validates objects where all keys match the key schema and all values
+ * match the value schema. Useful for dynamic key-value mappings.
+ *
+ * @param key - Schema to validate each key (must be a string validator)
+ * @param value - Schema to validate each value
+ * @returns A new {@link DictSchema} instance
+ *
+ * @example
+ * ```ts
+ * // String to number mapping
+ * const scoresSchema = l.dict(l.string(), l.integer())
+ * scoresSchema.parse({ alice: 100, bob: 85 })
+ *
+ * // Constrained keys
+ * const langSchema = l.dict(
+ *   l.string({ minLength: 2, maxLength: 5 }), // Language codes
+ *   l.string() // Translations
+ * )
+ *
+ * // Complex values
+ * const usersById = l.dict(
+ *   l.string({ format: 'did' }),
+ *   l.object({ name: l.string(), age: l.integer() })
+ * )
+ * ```
+ */
 /*@__NO_SIDE_EFFECTS__*/
 export function dict<
   const TKey extends Validator<string>,

package/src/schema/discriminated-union.ts

@@ -11,9 +11,22 @@ import { EnumSchema } from './enum.js'
 import { LiteralSchema } from './literal.js'
 import { ObjectSchema } from './object.js'
 
+/**
+ * Type representing a single variant in a discriminated union.
+ *
+ * Must be an ObjectSchema with the discriminator property using either
+ * a LiteralSchema or EnumSchema.
+ *
+ * @template Discriminator - The discriminator property name
+ */
 export type DiscriminatedUnionVariant<Discriminator extends string = string> =
   ObjectSchema<Record<Discriminator, EnumSchema<any> | LiteralSchema<any>>>
 
+/**
+ * Type representing a non-empty tuple of discriminated union variants.
+ *
+ * @template TDiscriminator - The discriminator property name
+ */
 export type DiscriminatedUnionVariants<TDiscriminator extends string> =
   readonly [
     DiscriminatedUnionVariant<TDiscriminator>,
@@ -37,9 +50,26 @@ type DiscriminatedUnionSchemaOutput<TVariants extends readonly Validator[]> =
     : never
 
 /**
+ * Schema for validating discriminated unions of objects.
+ *
+ * More efficient than regular union schemas when discriminating on a known
+ * property. Looks up the correct variant schema directly based on the
+ * discriminator value instead of trying each variant in sequence.
+ *
  * @note There is no discriminated union in Lexicon schemas. This is a custom
  * extension to allow optimized validation of union of objects when using the
  * lex library programmatically (i.e. not code generated from a lexicon schema).
+ *
+ * @template TDiscriminator - The discriminator property name
+ * @template TVariants - Tuple type of the variant schemas
+ *
+ * @example
+ * ```ts
+ * const schema = new DiscriminatedUnionSchema('type', [
+ *   l.object({ type: l.literal('text'), content: l.string() }),
+ *   l.object({ type: l.literal('image'), url: l.string() }),
+ * ])
+ * ```
  */
 export class DiscriminatedUnionSchema<
   const TDiscriminator extends string,
@@ -124,6 +154,34 @@ function buildVariantsMap<Discriminator extends string>(
   return variantsMap
 }
 
+/**
+ * Creates a discriminated union schema for efficient object type switching.
+ *
+ * Unlike regular `union()`, this schema uses a discriminator property to
+ * directly look up the correct variant, providing O(1) validation instead
+ * of trying each variant sequentially.
+ *
+ * @param discriminator - Property name to discriminate on
+ * @param variants - Non-empty array of object schemas with the discriminator property
+ * @returns A new {@link DiscriminatedUnionSchema} instance
+ *
+ * @example
+ * ```ts
+ * // Message types discriminated by 'kind'
+ * const messageSchema = l.discriminatedUnion('kind', [
+ *   l.object({ kind: l.literal('text'), text: l.string() }),
+ *   l.object({ kind: l.literal('image'), url: l.string(), alt: l.optional(l.string()) }),
+ *   l.object({ kind: l.literal('video'), url: l.string(), duration: l.integer() }),
+ * ])
+ *
+ * // Using enums for multiple values mapping to same variant
+ * const statusSchema = l.discriminatedUnion('status', [
+ *   l.object({ status: l.enum(['pending', 'processing']), startedAt: l.string() }),
+ *   l.object({ status: l.literal('completed'), completedAt: l.string() }),
+ *   l.object({ status: l.literal('failed'), error: l.string() }),
+ * ])
+ * ```
+ */
 /*@__NO_SIDE_EFFECTS__*/
 export function discriminatedUnion<
   const Discriminator extends string,

package/src/schema/enum.ts

@@ -1,5 +1,20 @@
 import { Schema, ValidationContext } from '../core.js'
 
+/**
+ * Schema that accepts one of several specific literal values.
+ *
+ * Validates that the input matches one of the allowed values using strict
+ * equality. Similar to TypeScript union of literals.
+ *
+ * @template TValue - The union of literal types
+ *
+ * @example
+ * ```ts
+ * const schema = new EnumSchema(['pending', 'active', 'completed'])
+ * schema.validate('active')  // success
+ * schema.validate('invalid') // fails
+ * ```
+ */
 export class EnumSchema<
   const TValue extends null | string | number | boolean,
 > extends Schema<TValue> {
@@ -16,6 +31,39 @@ export class EnumSchema<
   }
 }
 
+/**
+ * Creates an enum schema that accepts one of the specified values.
+ *
+ * Similar to TypeScript's union of string literals. Use `l.enum()` for
+ * the namespace-friendly alias.
+ *
+ * @param value - Array of allowed values
+ * @returns A new {@link EnumSchema} instance
+ *
+ * @example
+ * ```ts
+ * // String enum
+ * const statusSchema = l.enum(['pending', 'active', 'completed', 'failed'])
+ *
+ * // Number enum
+ * const prioritySchema = l.enum([1, 2, 3, 4, 5])
+ *
+ * // Mixed types
+ * const mixedSchema = l.enum(['auto', 0, 1, true])
+ *
+ * // Use in objects
+ * const taskSchema = l.object({
+ *   title: l.string(),
+ *   status: l.enum(['todo', 'in-progress', 'done']),
+ * })
+ *
+ * // In discriminated unions
+ * const resultSchema = l.discriminatedUnion('status', [
+ *   l.object({ status: l.enum(['pending', 'processing']), progress: l.integer() }),
+ *   l.object({ status: l.literal('completed'), result: l.unknown() }),
+ * ])
+ * ```
+ */
 /*@__NO_SIDE_EFFECTS__*/
 export function enumSchema<const V extends null | string | number | boolean>(
   value: readonly V[],

package/src/schema/integer.ts

@@ -1,11 +1,29 @@
 import { Schema, ValidationContext } from '../core.js'
 import { memoizedOptions } from '../util/memoize.js'
 
+/**
+ * Configuration options for integer schema validation.
+ *
+ * @property minimum - Minimum allowed value (inclusive)
+ * @property maximum - Maximum allowed value (inclusive)
+ */
 export type IntegerSchemaOptions = {
   minimum?: number
   maximum?: number
 }
 
+/**
+ * Schema for validating integer values with optional range constraints.
+ *
+ * Only accepts safe integers (values that can be exactly represented in JavaScript).
+ * Use {@link IntegerSchemaOptions} to constrain the allowed range.
+ *
+ * @example
+ * ```ts
+ * const schema = new IntegerSchema({ minimum: 0, maximum: 100 })
+ * const result = schema.validate(42)
+ * ```
+ */
 export class IntegerSchema extends Schema<number> {
   constructor(readonly options?: IntegerSchemaOptions) {
     super()
@@ -35,6 +53,30 @@ function isInteger(input: unknown): input is number {
   return Number.isSafeInteger(input)
 }
 
+/**
+ * Creates an integer schema with optional minimum and maximum constraints.
+ *
+ * Validates that the input is a safe integer (can be exactly represented in JavaScript)
+ * and optionally falls within a specified range.
+ *
+ * @param options - Optional configuration for minimum and maximum values
+ * @returns A new {@link IntegerSchema} instance
+ *
+ * @example
+ * ```ts
+ * // Basic integer
+ * const countSchema = l.integer()
+ *
+ * // With minimum value
+ * const positiveSchema = l.integer({ minimum: 1 })
+ *
+ * // With range constraints
+ * const percentSchema = l.integer({ minimum: 0, maximum: 100 })
+ *
+ * // Age validation
+ * const ageSchema = l.integer({ minimum: 0, maximum: 150 })
+ * ```
+ */
 export const integer = /*#__PURE__*/ memoizedOptions(function (
   options?: IntegerSchemaOptions,
 ) {