@atproto/lex-schema 0.0.11 → 0.0.12

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,

package/src/schema/unknown-object.ts

@@ -2,8 +2,24 @@ import { LexMap, isLexMap } from '@atproto/lex-data'
 import { Schema, ValidationContext } from '../core.js'
 import { memoizedOptions } from '../util/memoize.js'
 
+/**
+ * Type alias for a plain object with unknown values.
+ */
 export type UnknownObject = LexMap
 
+/**
+ * Schema that accepts any plain object without validating its properties.
+ *
+ * Validates that the input is a plain object (not an array, Date, or other
+ * special object type), but does not validate the object's properties.
+ *
+ * @example
+ * ```ts
+ * const schema = new UnknownObjectSchema()
+ * schema.validate({ any: 'props' }) // success
+ * schema.validate([1, 2, 3])        // fails - arrays not accepted
+ * ```
+ */
 export class UnknownObjectSchema extends Schema<UnknownObject> {
   validateInContext(input: unknown, ctx: ValidationContext) {
     if (isLexMap(input)) {
@@ -14,6 +30,24 @@ export class UnknownObjectSchema extends Schema<UnknownObject> {
   }
 }
 
+/**
+ * Creates a schema that accepts any plain object.
+ *
+ * Unlike `l.unknown()` which accepts any value, this validates that the input
+ * is specifically a plain object (not an array, null, or primitive).
+ *
+ * @returns A new {@link UnknownObjectSchema} instance
+ *
+ * @example
+ * ```ts
+ * // Accept any object shape
+ * const metadataSchema = l.unknownObject()
+ *
+ * metadataSchema.parse({ foo: 1, bar: 'baz' }) // success
+ * metadataSchema.parse([1, 2, 3])              // throws - not a plain object
+ * metadataSchema.parse(null)                   // throws
+ * ```
+ */
 export const unknownObject = /*#__PURE__*/ memoizedOptions(function () {
   return new UnknownObjectSchema()
 })

package/src/schema/unknown.ts

@@ -1,12 +1,45 @@
 import { Schema, ValidationContext } from '../core.js'
 import { memoizedOptions } from '../util/memoize.js'
 
+/**
+ * Schema that accepts any value without validation.
+ *
+ * Passes through any input unchanged. Use sparingly as it bypasses
+ * type safety. Useful for dynamic data or when the schema is not
+ * known at compile time.
+ *
+ * @example
+ * ```ts
+ * const schema = new UnknownSchema()
+ * schema.validate(anything) // always succeeds
+ * ```
+ */
 export class UnknownSchema extends Schema<unknown> {
   validateInContext(input: unknown, ctx: ValidationContext) {
     return ctx.success(input)
   }
 }
 
+/**
+ * Creates an unknown schema that accepts any value.
+ *
+ * The value passes through without any validation or transformation.
+ * Use this when you need to accept arbitrary data.
+ *
+ * @returns A new {@link UnknownSchema} instance
+ *
+ * @example
+ * ```ts
+ * // Accept any value
+ * const anyDataSchema = l.unknown()
+ *
+ * // In an object with a dynamic field
+ * const flexibleSchema = l.object({
+ *   type: l.string(),
+ *   data: l.unknown(),
+ * })
+ * ```
+ */
 export const unknown = /*#__PURE__*/ memoizedOptions(function () {
   return new UnknownSchema()
 })

package/src/schema/with-default.ts

@@ -6,6 +6,22 @@ import {
   Validator,
 } from '../core.js'
 
+/**
+ * Schema wrapper that provides a default value when the input is undefined.
+ *
+ * In parse mode, when the input is `undefined`, the default value is used
+ * instead. In validate mode, undefined values pass through unchanged (the
+ * default is not applied).
+ *
+ * @template TValidator - The wrapped validator type
+ *
+ * @example
+ * ```ts
+ * const schema = new WithDefaultSchema(l.integer(), 0)
+ * schema.parse(undefined) // 0
+ * schema.parse(42)        // 42
+ * ```
+ */
 export class WithDefaultSchema<
   const TValidator extends Validator,
 > extends Schema<InferInput<TValidator>, InferOutput<TValidator>> {
@@ -27,6 +43,34 @@ export class WithDefaultSchema<
   }
 }
 
+/**
+ * Creates a schema that applies a default value when the input is undefined.
+ *
+ * Commonly used with `optional()` to provide fallback values for missing
+ * properties. The default value is validated against the schema.
+ *
+ * @param validator - The validator for the value
+ * @param defaultValue - The default value to use when input is undefined
+ * @returns A new {@link WithDefaultSchema} instance
+ *
+ * @example
+ * ```ts
+ * // Integer with default
+ * const countSchema = l.withDefault(l.integer(), 0)
+ * countSchema.parse(undefined) // 0
+ * countSchema.parse(5)         // 5
+ *
+ * // Commonly combined with optional in objects
+ * const settingsSchema = l.object({
+ *   theme: l.optional(l.withDefault(l.string(), 'light')),
+ *   pageSize: l.optional(l.withDefault(l.integer(), 25)),
+ * })
+ * settingsSchema.parse({}) // { theme: 'light', pageSize: 25 }
+ *
+ * // Boolean with default
+ * const enabledSchema = l.withDefault(l.boolean(), false)
+ * ```
+ */
 export function withDefault<const TValidator extends Validator>(
   validator: TValidator,
   defaultValue: InferInput<TValidator>,