@atproto/lex-schema 0.0.10 → 0.0.12

package/src/schema/refine.ts

@@ -8,18 +8,40 @@ import {
 } from '../core.js'
 import { CustomAssertionContext } from './custom.js'
 
+/**
+ * Configuration for a refinement check that validates a condition.
+ *
+ * @template T - The type being validated
+ * @property check - Function that returns true if the value passes the check
+ * @property message - Error message when the check fails
+ * @property path - Optional path to associate with the error
+ */
 export type RefinementCheck<T> = {
   check: (value: T, ctx: CustomAssertionContext) => boolean
   message: string
   path?: PropertyKey | readonly PropertyKey[]
 }
 
+/**
+ * Configuration for a refinement assertion that narrows the type.
+ *
+ * @template T - The input type being validated
+ * @template Out - The narrowed output type
+ * @property check - Type guard function that narrows the type
+ * @property message - Error message when the assertion fails
+ * @property path - Optional path to associate with the error
+ */
 export type RefinementAssertion<T, Out extends T> = {
   check: (this: null, value: T, ctx: CustomAssertionContext) => value is Out
   message: string
   path?: PropertyKey | readonly PropertyKey[]
 }
 
+/**
+ * Infers the input type from a refinement configuration.
+ *
+ * @template R - The refinement type
+ */
 export type InferRefinement<R> =
   R extends RefinementCheck<infer T>
     ? T
@@ -27,25 +49,52 @@ export type InferRefinement<R> =
       ? T
       : never
 
+/**
+ * Union type of refinement check or assertion.
+ *
+ * @template T - The input type being validated
+ * @template Out - The output type (same as T for checks, narrowed for assertions)
+ */
 export type Refinement<T = any, Out extends T = T> =
   | RefinementCheck<T>
   | RefinementAssertion<T, Out>
 
 /**
- * Create a refined schema based on an existing schema and a refinement check.
+ * Creates a refined schema by adding additional validation constraints.
  *
- * @param schema - The base schema to refine.
- * @param refinement - The refinement check to apply.
- * @returns A new schema that includes the refinement.
- * @example
+ * Wraps an existing schema with an additional check function. The base schema
+ * is validated first, then the refinement check is applied to the result.
  *
+ * @param schema - The base schema to refine
+ * @param refinement - The refinement check or assertion to apply
+ * @returns A new schema that includes the refinement
+ *
+ * @example
  * ```ts
- * const PositiveInt = refine(l.integer(), {
+ * // Simple check refinement
+ * const positiveInt = l.refine(l.integer(), {
  *   check: (value) => value > 0,
- *   message: 'Value must be a positive integer',
+ *   message: 'Value must be positive',
  * })
- * const result = PositiveInt.validate(-5)
- * // result.success === false
+ *
+ * positiveInt.parse(5)  // 5
+ * positiveInt.parse(-1) // throws
+ *
+ * // Type-narrowing assertion
+ * const nonEmptyString = l.refine(l.string(), {
+ *   check: (value): value is string & { length: number } => value.length > 0,
+ *   message: 'String must not be empty',
+ * })
+ *
+ * // With custom path for nested errors
+ * const validDateRange = l.refine(
+ *   l.object({ start: l.string(), end: l.string() }),
+ *   {
+ *     check: (v) => new Date(v.start) < new Date(v.end),
+ *     message: 'Start date must be before end date',
+ *     path: ['end'],
+ *   }
+ * )
  * ```
  */
 export function refine<

package/src/schema/regexp.ts

@@ -1,5 +1,20 @@
 import { Schema, ValidationContext } from '../core.js'
 
+/**
+ * Schema for validating strings against a regular expression pattern.
+ *
+ * Validates that the input is a string and matches the provided pattern.
+ * The pattern is tested using RegExp.test().
+ *
+ * @template TValue - The string type (can be narrowed with branded types)
+ *
+ * @example
+ * ```ts
+ * const schema = new RegexpSchema(/^[a-z]+$/)
+ * schema.validate('hello') // success
+ * schema.validate('Hello') // fails - uppercase not allowed
+ * ```
+ */
 export class RegexpSchema<
   TValue extends string = string,
 > extends Schema<TValue> {
@@ -20,6 +35,35 @@ export class RegexpSchema<
   }
 }
 
+/**
+ * Creates a regexp schema that validates strings against a pattern.
+ *
+ * Useful for custom string formats not covered by the built-in format
+ * validators.
+ *
+ * @param pattern - Regular expression pattern to match against
+ * @returns A new {@link RegexpSchema} instance
+ *
+ * @example
+ * ```ts
+ * // Simple pattern
+ * const slugSchema = l.regexp(/^[a-z0-9-]+$/)
+ *
+ * // With anchors for exact match
+ * const uuidSchema = l.regexp(
+ *   /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i
+ * )
+ *
+ * // Semantic versioning
+ * const semverSchema = l.regexp(/^\d+\.\d+\.\d+(-[\w.]+)?(\+[\w.]+)?$/)
+ *
+ * // Use in object
+ * const configSchema = l.object({
+ *   name: l.regexp(/^[a-z][a-z0-9-]*$/), // kebab-case identifier
+ *   version: semverSchema,
+ * })
+ * ```
+ */
 /*@__NO_SIDE_EFFECTS__*/
 export function regexp<TInput extends string = string>(pattern: RegExp) {
   return new RegexpSchema<TInput>(pattern)

package/src/schema/string.ts

@@ -9,6 +9,15 @@ import {
 import { memoizedOptions } from '../util/memoize.js'
 import { TokenSchema } from './token.js'
 
+/**
+ * Configuration options for string schema validation.
+ *
+ * @property format - Expected string format (e.g., 'datetime', 'uri', 'at-uri', 'did', 'handle', 'nsid', 'cid', 'tid', 'record-key', 'at-identifier', 'language')
+ * @property minLength - Minimum length in UTF-8 bytes
+ * @property maxLength - Maximum length in UTF-8 bytes
+ * @property minGraphemes - Minimum number of grapheme clusters
+ * @property maxGraphemes - Maximum number of grapheme clusters
+ */
 export type StringSchemaOptions = {
   format?: StringFormat
   minLength?: number
@@ -17,6 +26,20 @@ export type StringSchemaOptions = {
   maxGraphemes?: number
 }
 
+/**
+ * Schema for validating string values with optional format and length constraints.
+ *
+ * Supports various string formats defined in the Lexicon specification, as well as
+ * length constraints measured in UTF-8 bytes or grapheme clusters.
+ *
+ * @template TOptions - The configuration options type
+ *
+ * @example
+ * ```ts
+ * const schema = new StringSchema({ format: 'datetime', maxLength: 64 })
+ * const result = schema.validate('2024-01-15T10:30:00Z')
+ * ```
+ */
 export class StringSchema<
   const TOptions extends StringSchemaOptions = StringSchemaOptions,
 > extends Schema<
@@ -123,6 +146,33 @@ export function coerceToString(input: unknown): string | null {
   }
 }
 
+/**
+ * Creates a string schema with optional format and length constraints.
+ *
+ * Strings can be validated against various formats (datetime, uri, did, handle, etc.)
+ * and constrained by length in UTF-8 bytes or grapheme clusters.
+ *
+ * @param options - Optional configuration for format and length constraints
+ * @returns A new {@link StringSchema} instance
+ *
+ * @example
+ * ```ts
+ * // Basic string
+ * const nameSchema = l.string()
+ *
+ * // With format validation
+ * const dateSchema = l.string({ format: 'datetime' })
+ *
+ * // With length constraints (UTF-8 bytes)
+ * const bioSchema = l.string({ maxLength: 256 })
+ *
+ * // With grapheme constraints (user-perceived characters)
+ * const displayNameSchema = l.string({ maxGraphemes: 64 })
+ *
+ * // Combining constraints
+ * const handleSchema = l.string({ format: 'handle', minLength: 3, maxLength: 253 })
+ * ```
+ */
 export const string = /*#__PURE__*/ memoizedOptions(function <
   const O extends StringSchemaOptions = NonNullable<unknown>,
 >(options?: StringSchemaOptions & O) {

package/src/schema/subscription.ts

@@ -1,18 +1,51 @@
+import { LexValue } from '@atproto/lex-data'
 import { Infer, NsidString, Schema } from '../core.js'
 import { ParamsSchema } from './params.js'
 
+/**
+ * Infers the parameters type from a Subscription definition.
+ *
+ * @template S - The Subscription type
+ */
 export type InferSubscriptionParameters<S extends Subscription> = Infer<
   S['parameters']
 >
 
+/**
+ * Infers the message type from a Subscription definition.
+ *
+ * @template S - The Subscription type
+ */
 export type InferSubscriptionMessage<S extends Subscription> = Infer<
   S['message']
 >
 
+/**
+ * Represents a Lexicon subscription (WebSocket) endpoint definition.
+ *
+ * Subscriptions are real-time event streams delivered over WebSocket.
+ * They have parameters for initializing the connection and a message
+ * schema for validating incoming events.
+ *
+ * @template TNsid - The NSID identifying this subscription
+ * @template TParameters - The connection parameters schema type
+ * @template TMessage - The message schema type
+ * @template TErrors - Array of error type strings, or undefined
+ *
+ * @example
+ * ```ts
+ * const firehose = new Subscription(
+ *   'com.atproto.sync.subscribeRepos',
+ *   l.params({ cursor: l.optional(l.integer()) }),
+ *   repoEventSchema,
+ *   ['FutureCursor']
+ * )
+ * ```
+ */
 export class Subscription<
   const TNsid extends NsidString = NsidString,
   const TParameters extends ParamsSchema = ParamsSchema,
-  const TMessage extends Schema = Schema,
+  const TMessage extends Schema<LexValue> = Schema<LexValue>,
   const TErrors extends undefined | readonly string[] =
     | undefined
     | readonly string[],
@@ -27,11 +60,48 @@ export class Subscription<
   ) {}
 }
 
+/**
+ * Creates a subscription definition for a Lexicon WebSocket endpoint.
+ *
+ * Subscriptions enable real-time event streaming. The connection is
+ * initialized with parameters, and the server sends messages matching
+ * the message schema.
+ *
+ * @param nsid - The NSID identifying this subscription endpoint
+ * @param parameters - Schema for connection parameters
+ * @param message - Schema for validating incoming messages
+ * @param errors - Optional array of error type strings
+ * @returns A new {@link Subscription} instance
+ *
+ * @example
+ * ```ts
+ * // Repository event stream
+ * const subscribeRepos = l.subscription(
+ *   'com.atproto.sync.subscribeRepos',
+ *   l.params({
+ *     cursor: l.optional(l.integer()),
+ *   }),
+ *   l.typedUnion([
+ *     l.typedRef(() => commitEventSchema),
+ *     l.typedRef(() => handleEventSchema),
+ *     l.typedRef(() => identityEventSchema),
+ *   ], false),
+ *   ['FutureCursor', 'ConsumerTooSlow'],
+ * )
+ *
+ * // Label stream
+ * const subscribeLabels = l.subscription(
+ *   'com.atproto.label.subscribeLabels',
+ *   l.params({ cursor: l.optional(l.integer()) }),
+ *   labelEventSchema,
+ * )
+ * ```
+ */
 /*@__NO_SIDE_EFFECTS__*/
 export function subscription<
   const N extends NsidString,
   const P extends ParamsSchema,
-  const M extends Schema,
+  const M extends Schema<LexValue>,
   const E extends undefined | readonly string[] = undefined,
 >(nsid: N, parameters: P, message: M, errors: E = undefined as E) {
   return new Subscription<N, P, M, E>(nsid, parameters, message, errors)

package/src/schema/token.ts

@@ -1,5 +1,20 @@
 import { $type, NsidString, Schema, ValidationContext } from '../core.js'
 
+/**
+ * Schema for Lexicon token values.
+ *
+ * Tokens are named constants in Lexicon, identified by their NSID and hash.
+ * They validate to their string value (e.g., 'app.bsky.feed.defs#requestLess').
+ * TokenSchema instances can also be used as values themselves.
+ *
+ * @template TValue - The token string literal type
+ *
+ * @example
+ * ```ts
+ * const schema = new TokenSchema('app.bsky.feed.defs#requestLess')
+ * schema.validate('app.bsky.feed.defs#requestLess') // success
+ * ```
+ */
 export class TokenSchema<
   const TValue extends string = string,
 > extends Schema<TValue> {
@@ -37,6 +52,38 @@ export class TokenSchema<
   }
 }
 
+/**
+ * Creates a token schema for Lexicon named constants.
+ *
+ * Tokens are used in Lexicon as named constants or enum-like values.
+ * The token instance can be used both as a schema validator and as
+ * the token value itself (it serializes to its string value).
+ *
+ * @param nsid - The NSID part of the token
+ * @param hash - The hash part of the token (defaults to 'main')
+ * @returns A new {@link TokenSchema} instance
+ *
+ * @example
+ * ```ts
+ * // Define tokens
+ * const requestLess = l.token('app.bsky.feed.defs', 'requestLess')
+ * const requestMore = l.token('app.bsky.feed.defs', 'requestMore')
+ *
+ * // Use as a value
+ * console.log(requestLess.toString()) // 'app.bsky.feed.defs#requestLess'
+ *
+ * // Use in union for validation
+ * const feedbackSchema = l.union([requestLess, requestMore])
+ *
+ * // Validate
+ * feedbackSchema.parse('app.bsky.feed.defs#requestLess') // success
+ *
+ * // Token instances can be used as values in other schemas
+ * const feedbackRequest = l.object({
+ *   feedback: requestLess, // Accepts the token value
+ * })
+ * ```
+ */
 /*@__NO_SIDE_EFFECTS__*/
 export function token<
   const N extends NsidString,

package/src/schema/typed-object.ts

@@ -15,6 +15,24 @@ import {
   Validator,
 } from '../core.js'
 
+/**
+ * Schema for typed objects in Lexicon unions.
+ *
+ * Typed objects have a `$type` field that identifies which variant they are
+ * in a union. The `$type` can be omitted in input (it's implicit), but if
+ * present, it must match the expected value.
+ *
+ * @template TType - The $type string literal type
+ * @template TShape - The validator type for the object's shape
+ *
+ * @example
+ * ```ts
+ * const schema = new TypedObjectSchema(
+ *   'app.bsky.embed.images#view',
+ *   l.object({ images: l.array(imageSchema) })
+ * )
+ * ```
+ */
 export class TypedObjectSchema<
   const TType extends $Type = $Type,
   const TShape extends Validator<{ [k: string]: unknown }> = any,
@@ -72,15 +90,51 @@ export class TypedObjectSchema<
 }
 
 /**
+ * Creates a typed object schema for use in Lexicon unions.
+ *
+ * Typed objects are identified by their `$type` field, which combines an NSID
+ * and a hash (e.g., 'app.bsky.embed.images#view'). Used for union variants.
+ *
  * This function offers two overloads:
- * - One that allows creating a {@link TypedObjectSchema}, and infer the output
- *   type from the provided arguments, without requiring to specify any of the
- *   generics. This is useful when you want to define a record without
- *   explicitly defining its interface. This version does not support circular
- *   references, as TypeScript cannot infer types in such cases.
- * - One allows creating a {@link TypedObjectSchema} with an explicitly defined
- *   interface. This will typically be used by codegen (`lex build`) to generate
- *   schemas that work even if they contain circular references.
+ * - One that infers the type from arguments (no circular reference support)
+ * - One with explicit interface for codegen with circular references
+ *
+ * @param nsid - The NSID part of the type (e.g., 'app.bsky.embed.images')
+ * @param hash - The hash part of the type (e.g., 'view'), defaults to 'main'
+ * @param validator - Schema for validating the object properties
+ * @returns A new {@link TypedObjectSchema} instance
+ *
+ * @example
+ * ```ts
+ * // Image embed view
+ * const imageViewSchema = l.typedObject(
+ *   'app.bsky.embed.images',
+ *   'view',
+ *   l.object({
+ *     images: l.array(l.object({
+ *       thumb: l.string(),
+ *       fullsize: l.string(),
+ *       alt: l.string(),
+ *     })),
+ *   })
+ * )
+ *
+ * // Main type (hash defaults to 'main')
+ * const postViewSchema = l.typedObject(
+ *   'app.bsky.feed.defs',
+ *   'postView',
+ *   l.object({ uri: l.string(), cid: l.string(), author: authorSchema })
+ * )
+ *
+ * // Use $isTypeOf to narrow union types
+ * if (imageViewSchema.$isTypeOf(embed)) {
+ *   // embed is narrowed to image view type
+ * }
+ *
+ * // Use $build to construct typed objects
+ * const view = imageViewSchema.$build({ images: [...] })
+ * // view.$type === 'app.bsky.embed.images#view'
+ * ```
  */
 export function typedObject<
   const N extends NsidString,

package/src/schema/typed-ref.ts

@@ -7,6 +7,14 @@ import {
   Validator,
 } from '../core.js'
 
+/**
+ * Interface for validators that have a $type property.
+ *
+ * Used by typed objects and records to identify their type in unions.
+ *
+ * @template TInput - The input type (with optional $type)
+ * @template TOutput - The output type (with non-optional $type)
+ */
 export interface TypedObjectValidator<
   TInput extends { $type?: string } = { $type?: string },
   TOutput extends TInput = TInput,
@@ -14,9 +22,29 @@ export interface TypedObjectValidator<
   $type: NonNullable<TOutput['$type']>
 }
 
+/**
+ * Function type that returns a typed object validator, used for lazy resolution.
+ *
+ * @template TValidator - The typed object validator type
+ */
 export type TypedRefGetter<out TValidator extends TypedObjectValidator> =
   () => TValidator
 
+/**
+ * Schema for referencing typed objects with lazy resolution.
+ *
+ * Used in typed unions to reference typed object schemas. Requires the
+ * `$type` field to be present and match the referenced schema's type.
+ * The referenced schema is resolved lazily to support circular references.
+ *
+ * @template TValidator - The referenced typed object validator type
+ *
+ * @example
+ * ```ts
+ * const ref = new TypedRefSchema(() => imageViewSchema)
+ * // ref.$type === 'app.bsky.embed.images#view'
+ * ```
+ */
 export class TypedRefSchema<
   const TValidator extends TypedObjectValidator = TypedObjectValidator,
 > extends Schema<
@@ -54,6 +82,31 @@ export class TypedRefSchema<
   }
 }
 
+/**
+ * Creates a reference to a typed object schema for use in typed unions.
+ *
+ * Unlike regular `ref()`, this requires the referenced schema to have a
+ * `$type` property, and validates that the input's `$type` matches.
+ *
+ * @param get - Function that returns the typed object validator
+ * @returns A new {@link TypedRefSchema} instance
+ *
+ * @example
+ * ```ts
+ * // Reference to image embed view
+ * const imageRef = l.typedRef(() => imageViewSchema)
+ *
+ * // Use in a typed union
+ * const embedUnion = l.typedUnion([
+ *   l.typedRef(() => imageViewSchema),
+ *   l.typedRef(() => videoViewSchema),
+ *   l.typedRef(() => externalViewSchema),
+ * ], true) // closed union
+ *
+ * // The $type is accessible on the ref
+ * console.log(imageRef.$type) // 'app.bsky.embed.images#view'
+ * ```
+ */
 /*@__NO_SIDE_EFFECTS__*/
 export function typedRef<const TValidator extends TypedObjectValidator>(
   get: TypedRefGetter<TValidator>,

package/src/schema/typed-union.ts

@@ -7,10 +7,32 @@ import {
   ValidationContext,
 } from '../core.js'
 import { lazyProperty } from '../util/lazy-property.js'
+import { TypedObjectSchema } from './typed-object.js'
 import { TypedRefSchema } from './typed-ref.js'
 
+/**
+ * Schema for Lexicon typed unions (unions discriminated by $type).
+ *
+ * Typed unions are collections of typed objects identified by their `$type`
+ * field. Can be "open" (accept unknown types) or "closed" (only accept
+ * known types).
+ *
+ * @template TValidators - Tuple of {@link TypedRefSchema} or {@link TypedObjectSchema} instances
+ * @template TClosed - Whether the union is closed (rejects unknown $types)
+ *
+ * @example
+ * ```ts
+ * const embedUnion = new TypedUnionSchema([
+ *   l.typedRef(() => imageSchema),
+ *   l.typedRef(() => videoSchema),
+ * ], true) // closed - only accepts images and videos
+ * ```
+ */
 export class TypedUnionSchema<
-  const TValidators extends readonly TypedRefSchema[] = [],
+  const TValidators extends readonly (
+    | TypedRefSchema
+    | TypedObjectSchema
+  )[] = [],
   const TClosed extends boolean = boolean,
 > extends Schema<
   TClosed extends true
@@ -26,7 +48,8 @@ export class TypedUnionSchema<
   ) {
     // @NOTE In order to avoid circular dependency issues, we don't access the
     // refs's schema (or $type) here. Instead, we access them lazily when first
-    // needed.
+    // needed. The biggest issue with this strategy is that we can't throw
+    // early if the refs contain multiple refs with the same $type.
 
     super()
   }
@@ -66,6 +89,36 @@ export class TypedUnionSchema<
   }
 }
 
+/**
+ * Creates a typed union schema for Lexicon unions.
+ *
+ * Typed unions discriminate variants by their `$type` field. Can be open
+ * (accepts unknown types, useful for extensibility) or closed (strict).
+ *
+ * @param refs - Array of typed refs for the union variants
+ * @param closed - Whether to reject unknown $type values
+ * @returns A new {@link TypedUnionSchema} instance
+ *
+ * @example
+ * ```ts
+ * // Closed union - only accepts known types
+ * const embedSchema = l.typedUnion([
+ *   l.typedRef(() => imageViewSchema),
+ *   l.typedRef(() => videoViewSchema),
+ *   l.typedRef(() => externalViewSchema),
+ * ], true)
+ *
+ * // Open union - accepts unknown types for forward compatibility
+ * const feedItemSchema = l.typedUnion([
+ *   l.typedRef(() => postSchema),
+ *   l.typedRef(() => repostSchema),
+ * ], false) // unknown types pass through
+ *
+ * // Get all known $types
+ * console.log(embedSchema.$types)
+ * // ['app.bsky.embed.images#view', 'app.bsky.embed.video#view', ...]
+ * ```
+ */
 /*@__NO_SIDE_EFFECTS__*/
 export function typedUnion<
   const R extends readonly TypedRefSchema[],

package/src/schema/union.ts

@@ -8,8 +8,29 @@ import {
   Validator,
 } from '../core.js'
 
+/**
+ * Type representing a non-empty tuple of validators for union schemas.
+ *
+ * Requires at least one validator in the tuple.
+ */
 export type UnionSchemaValidators = readonly [Validator, ...Validator[]]
 
+/**
+ * Schema for validating values that match one of several possible schemas.
+ *
+ * Tries each validator in order until one succeeds. If all validators fail,
+ * returns a combined error from all attempts.
+ *
+ * @template TValidators - Tuple type of the validators in the union
+ *
+ * @example
+ * ```ts
+ * const schema = new UnionSchema([l.string(), l.integer()])
+ * schema.validate('hello') // success
+ * schema.validate(42)      // success
+ * schema.validate(true)    // fails
+ * ```
+ */
 export class UnionSchema<
   const TValidators extends UnionSchemaValidators = any,
 > extends Schema<
@@ -34,6 +55,30 @@ export class UnionSchema<
   }
 }
 
+/**
+ * Creates a union schema that accepts values matching any of the provided schemas.
+ *
+ * Validators are tried in order. Use `discriminatedUnion()` for better
+ * performance when discriminating on a known property.
+ *
+ * @param validators - Non-empty array of validators to try
+ * @returns A new {@link UnionSchema} instance
+ *
+ * @example
+ * ```ts
+ * // String or number
+ * const stringOrNumber = l.union([l.string(), l.integer()])
+ *
+ * // Nullable value
+ * const nullableString = l.union([l.string(), l.null()])
+ *
+ * // Multiple object types
+ * const mediaSchema = l.union([
+ *   l.object({ type: l.literal('image'), url: l.string() }),
+ *   l.object({ type: l.literal('video'), url: l.string(), duration: l.integer() }),
+ * ])
+ * ```
+ */
 /*@__NO_SIDE_EFFECTS__*/
 export function union<const TValidators extends UnionSchemaValidators>(
   validators: TValidators,