@atproto/lex-schema 0.0.11 → 0.0.13

package/src/schema/custom.ts

@@ -6,18 +6,48 @@ 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> {
+  readonly type = 'custom' as const
+
   constructor(
     private readonly assertion: CustomAssertion<TValue>,
     private readonly message: string,
@@ -35,6 +65,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,
@@ -19,6 +34,8 @@ export class DictSchema<
   Record<InferInput<TKey>, InferInput<TValue>>,
   Record<InferInput<TKey>, InferOutput<TValue>>
 > {
+  readonly type = 'dict' as const
+
   constructor(
     readonly keySchema: TKey,
     readonly valueSchema: TValue,
@@ -32,7 +49,7 @@ export class DictSchema<
     options?: { ignoredKeys?: { has(k: string): boolean } },
   ) {
     if (!isPlainObject(input)) {
-      return ctx.issueInvalidType(input, 'dict')
+      return ctx.issueUnexpectedType(input, 'dict')
     }
 
     let copy: undefined | Record<string, unknown>
@@ -67,6 +84,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,
@@ -48,6 +78,8 @@ export class DiscriminatedUnionSchema<
   DiscriminatedUnionSchemaInput<TVariants>,
   DiscriminatedUnionSchemaOutput<TVariants>
 > {
+  readonly type = 'discriminatedUnion' as const
+
   readonly variantsMap: Map<unknown, DiscriminatedUnionVariant<TDiscriminator>>
 
   constructor(
@@ -64,7 +96,7 @@ export class DiscriminatedUnionSchema<
 
   validateInContext(input: unknown, ctx: ValidationContext) {
     if (!isPlainObject(input)) {
-      return ctx.issueInvalidType(input, 'object')
+      return ctx.issueUnexpectedType(input, 'object')
     }
 
     const { discriminator } = this
@@ -124,6 +156,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,8 +1,25 @@
 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> {
+  readonly type = 'enum' as const
+
   constructor(readonly values: readonly TValue[]) {
     super()
   }
@@ -16,6 +33,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,19 +1,39 @@
 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> {
+  readonly type = 'integer' as const
+
   constructor(readonly options?: IntegerSchemaOptions) {
     super()
   }
 
   validateInContext(input: unknown, ctx: ValidationContext) {
     if (!isInteger(input)) {
-      return ctx.issueInvalidType(input, 'integer')
+      return ctx.issueUnexpectedType(input, 'integer')
     }
 
     if (this.options?.minimum != null && input < this.options.minimum) {
@@ -35,6 +55,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,
 ) {

package/src/schema/intersection.ts

@@ -9,10 +9,15 @@ import { DictSchema } from './dict.js'
 import { ObjectSchema } from './object.js'
 
 /**
+ * Type utility for computing the intersection of two object types.
+ *
  * Allows to more accurately represent the intersection of two object types
  * where both types may share some keys, and one of them uses an index
  * signature.
  *
+ * @template A - First object type (typically from ObjectSchema)
+ * @template B - Second object type (typically from DictSchema)
+ *
  * @see {@link https://www.typescriptlang.org/play/?#code/C4TwDgpgBAglC8UDeUBmB7dAuKByARgIYBOuUAvlAGTJQDaA+lAJYB2UAzsMWwOYC6OVgFcAtvgjEKAKGkATCAGMANiWiL0rLlEI4YsjVuBQA1hBA4uPVrwRQARBnT2Dm7QDdCy4dESE6ZiD8UAD0IVAi4pJQABQcABbowspyUBIORMT2AJSyEAAeYOjExqCQUACSrMCSHErAzJoAPNJQsFAFNaxyHFAASkrFck1WfAA0UMKsJqzoAO6sAHxjrVAAQh35XT39g8TDozYTUzPzSyuLdqtwVKttMYHoqO00j88bnRDdvawQ7pJ3NpQAD860BbRwSHBQLadAA0ix2G91oJ1vDggAfWABcxPF5QOH8aFtci5aRlaAwVDMfIQVKIKo1Yh1RQNZq0Jw4AgkMjkCYoRiIzjcPioyISKTkRayBQqNRQQzaQgAMRpdL01NpclcRignm8EFVWrsKrVchxQVC4XF0SxmSAA Playground link}
  */
 export type Intersect<A, B> = B[keyof B] extends never
@@ -24,6 +29,26 @@ export type Intersect<A, B> = B[keyof B] extends never
       // index signature could return a value from either A or B
       A & { [K in keyof B]: B[K] | A[keyof A & K] }
 
+/**
+ * Schema for combining an object schema with a dictionary schema.
+ *
+ * Validates that the input matches both the fixed object shape and allows
+ * additional properties that match the dictionary schema. Properties defined
+ * in the object schema are validated by the object, and remaining properties
+ * are validated by the dictionary.
+ *
+ * @template Left - The ObjectSchema type for fixed properties
+ * @template Right - The DictSchema type for additional properties
+ *
+ * @example
+ * ```ts
+ * const schema = new IntersectionSchema(
+ *   l.object({ name: l.string() }),
+ *   l.dict(l.string(), l.integer())
+ * )
+ * // Validates: { name: 'test', score: 100, count: 5 }
+ * ```
+ */
 export class IntersectionSchema<
   const Left extends ObjectSchema = any,
   const Right extends DictSchema = any,
@@ -31,6 +56,8 @@ export class IntersectionSchema<
   Simplify<Intersect<InferInput<Left>, InferInput<Right>>>,
   Simplify<Intersect<InferOutput<Left>, InferOutput<Right>>>
 > {
+  readonly type = 'intersection' as const
+
   constructor(
     protected readonly left: Left,
     protected readonly right: Right,
@@ -48,6 +75,35 @@ export class IntersectionSchema<
   }
 }
 
+/**
+ * Creates an intersection schema combining fixed object properties with dynamic dictionary properties.
+ *
+ * Useful for objects that have a known set of properties plus additional
+ * arbitrary properties that follow a pattern.
+ *
+ * @param left - Object schema defining the fixed, known properties
+ * @param right - Dictionary schema for validating additional properties
+ * @returns A new {@link IntersectionSchema} instance
+ *
+ * @example
+ * ```ts
+ * // Object with fixed and dynamic properties
+ * const configSchema = l.intersection(
+ *   l.object({
+ *     version: l.integer(),
+ *     name: l.string(),
+ *   }),
+ *   l.dict(l.string(), l.string()) // Additional string properties
+ * )
+ *
+ * configSchema.parse({
+ *   version: 1,
+ *   name: 'my-config',
+ *   customField: 'value',
+ *   anotherField: 'another',
+ * })
+ * ```
+ */
 /*@__NO_SIDE_EFFECTS__*/
 export function intersection<
   const Left extends ObjectSchema,

package/src/schema/{unknown-object.test.ts → lex-map.test.ts}

@@ -1,9 +1,9 @@
 import { describe, expect, it } from 'vitest'
-import { unknownObject } from './unknown-object.js'
+import { lexMap } from './lex-map.js'
 
-describe('UnknownObjectSchema', () => {
+describe(lexMap, () => {
   describe('basic validation', () => {
-    const schema = unknownObject()
+    const schema = lexMap()
 
     it('accepts empty plain objects', () => {
       const result = schema.safeParse({})
@@ -106,7 +106,7 @@ describe('UnknownObjectSchema', () => {
   })
 
   describe('rejects non-plain-objects', () => {
-    const schema = unknownObject()
+    const schema = lexMap()
 
     it('rejects strings', () => {
       const result = schema.safeParse('not an object')
@@ -208,7 +208,7 @@ describe('UnknownObjectSchema', () => {
   })
 
   describe('rejects invalid value types', () => {
-    const schema = unknownObject()
+    const schema = lexMap()
 
     it('rejects objects with floating point numbers', () => {
       const result = schema.safeParse({ value: 3.14 })
@@ -288,7 +288,7 @@ describe('UnknownObjectSchema', () => {
   })
 
   describe('rejects invalid nested values', () => {
-    const schema = unknownObject()
+    const schema = lexMap()
 
     it('rejects deeply nested invalid values', () => {
       const result = schema.safeParse({
@@ -335,7 +335,7 @@ describe('UnknownObjectSchema', () => {
   })
 
   describe('edge cases', () => {
-    const schema = unknownObject()
+    const schema = lexMap()
 
     it('accepts objects with numeric string keys', () => {
       const obj = { '0': 'zero', '1': 'one', '2': 'two' }
@@ -500,7 +500,7 @@ describe('UnknownObjectSchema', () => {
   })
 
   describe('large objects', () => {
-    const schema = unknownObject()
+    const schema = lexMap()
 
     it('accepts objects with many keys', () => {
       const obj: Record<string, number> = {}
@@ -538,7 +538,7 @@ describe('UnknownObjectSchema', () => {
   })
 
   describe('preservation of input', () => {
-    const schema = unknownObject()
+    const schema = lexMap()
 
     it('preserves the original object reference', () => {
       const input = { key: 'value', count: 42 }

package/src/schema/lex-map.ts

@@ -0,0 +1,63 @@
+import { LexMap, isPlainObject } from '@atproto/lex-data'
+import { Schema, ValidationContext } from '../core.js'
+import { memoizedOptions } from '../util/memoize.js'
+import { lexValue } from './lex-value.js'
+
+const propertyValueSchema = /*#__PURE__*/ lexValue()
+
+export type { LexMap }
+
+/**
+ * AT Protocol lexicon schema definitions with "type": "unknown" are represented
+ * as plain objects with string keys and values that are valid AT Protocol data
+ * types (string, integer, boolean, null, bytes, cid, array, or object). This
+ * type alias corresponds to the expected structure of such "unknown" schema
+ * values.
+ */
+export class LexMapSchema extends Schema<LexMap> {
+  readonly type = 'lexMap' as const
+
+  validateInContext(input: unknown, ctx: ValidationContext) {
+    if (!isPlainObject(input)) {
+      return ctx.issueUnexpectedType(input, 'object')
+    }
+
+    for (const key of Object.keys(input)) {
+      // @NOTE We use a lexValue() schema here to recursively validate all
+      // nested values, which ensures that the error reporting includes the
+      // correct path and type information for any invalid nested values. This
+      // allows for more informative error descriptions than a simple "isLexMap"
+      // check.
+      const r = ctx.validateChild(input, key, propertyValueSchema) // recursively validate all properties
+      if (!r.success) return r
+    }
+
+    return ctx.success(input)
+  }
+}
+
+/**
+ * Creates a schema that accepts any plain object with string keys and values
+ * that are valid AT Protocol data types (string, integer, boolean, null, bytes,
+ * cid, array, or object).
+ *
+ * @see {@link LexMap} from `@atproto/lex-data` for the type definition of valid AT Protocol data types
+ * @returns A new {@link LexMapSchema} instance
+ *
+ * @example
+ * ```ts
+ * // Accept any object shape
+ * const schema = l.lexMap()
+ *
+ * schema.validate({ any: 'props' })    // success
+ * schema.validate([1, 2, 3])           // fails - only plain objects are accepted
+ * schema.validate({ foo: new Date() }) // fails - Date is not a valid LexValue
+ * schema.validate({ foo: 1.2 })        // fails - 1.2 is not a valid LexValue (not an integer)
+ * ```
+ */
+export const lexMap = /*#__PURE__*/ memoizedOptions(function () {
+  return new LexMapSchema()
+})
+
+/** @deprecated Use {@link lexMap} instead */
+export const unknownObject = lexMap