@atproto/lex-schema 0.0.10 → 0.0.12

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,
@@ -48,6 +73,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/literal.ts

@@ -1,5 +1,20 @@
 import { Schema, ValidationContext } from '../core.js'
 
+/**
+ * Schema that only accepts a specific literal value.
+ *
+ * Validates that the input is exactly equal to the specified value using
+ * strict equality (===).
+ *
+ * @template TValue - The literal type (null, string, number, or boolean)
+ *
+ * @example
+ * ```ts
+ * const schema = new LiteralSchema('admin')
+ * schema.validate('admin') // success
+ * schema.validate('user')  // fails
+ * ```
+ */
 export class LiteralSchema<
   const TValue extends null | string | number | boolean,
 > extends Schema<TValue> {
@@ -16,6 +31,35 @@ export class LiteralSchema<
   }
 }
 
+/**
+ * Creates a literal schema that only accepts the exact specified value.
+ *
+ * Useful for discriminator fields in unions, constant values, or type narrowing.
+ *
+ * @param value - The exact value that must be matched
+ * @returns A new {@link LiteralSchema} instance
+ *
+ * @example
+ * ```ts
+ * // String literal
+ * const roleSchema = l.literal('admin')
+ *
+ * // Number literal
+ * const versionSchema = l.literal(1)
+ *
+ * // Boolean literal
+ * const enabledSchema = l.literal(true)
+ *
+ * // Null literal
+ * const nullSchema = l.literal(null)
+ *
+ * // In discriminated unions
+ * const actionSchema = l.discriminatedUnion('type', [
+ *   l.object({ type: l.literal('create'), data: l.unknown() }),
+ *   l.object({ type: l.literal('delete'), id: l.string() }),
+ * ])
+ * ```
+ */
 /*@__NO_SIDE_EFFECTS__*/
 export function literal<const V extends null | string | number | boolean>(
   value: V,

package/src/schema/never.ts

@@ -1,12 +1,54 @@
 import { Schema, ValidationContext } from '../core.js'
 import { memoizedOptions } from '../util/memoize.js'
 
+/**
+ * Schema that always fails validation.
+ *
+ * Represents an impossible type - no value can satisfy this schema.
+ * Useful for exhaustiveness checking or marking impossible branches.
+ *
+ * @example
+ * ```ts
+ * const schema = new NeverSchema()
+ * schema.validate(anything) // always fails
+ * ```
+ */
 export class NeverSchema extends Schema<never> {
   validateInContext(input: unknown, ctx: ValidationContext) {
     return ctx.issueInvalidType(input, 'never')
   }
 }
 
+/**
+ * Creates a never schema that always fails validation.
+ *
+ * Useful for exhaustiveness checking in TypeScript or marking impossible
+ * code paths.
+ *
+ * @returns A new {@link NeverSchema} instance
+ *
+ * @example
+ * ```ts
+ * // Exhaustiveness checking
+ * type Status = 'active' | 'inactive'
+ *
+ * function handleStatus(status: Status) {
+ *   switch (status) {
+ *     case 'active': return 'Active'
+ *     case 'inactive': return 'Inactive'
+ *     default:
+ *       // TypeScript will error if we miss a case
+ *       l.never().parse(status)
+ *   }
+ * }
+ *
+ * // In impossible union branches
+ * const schema = l.object({
+ *   type: l.literal('fixed'),
+ *   dynamic: l.never(), // This property can never exist
+ * })
+ * ```
+ */
 export const never = /*#__PURE__*/ memoizedOptions(function () {
   return new NeverSchema()
 })

package/src/schema/null.ts

@@ -1,6 +1,19 @@
 import { Schema, ValidationContext } from '../core.js'
 import { memoizedOptions } from '../util/memoize.js'
 
+/**
+ * Schema for validating null values.
+ *
+ * Only accepts the JavaScript `null` value. Rejects `undefined` and all
+ * other values.
+ *
+ * @example
+ * ```ts
+ * const schema = new NullSchema()
+ * schema.validate(null)      // success
+ * schema.validate(undefined) // fails
+ * ```
+ */
 export class NullSchema extends Schema<null> {
   validateInContext(input: unknown, ctx: ValidationContext) {
     if (input !== null) {
@@ -11,6 +24,22 @@ export class NullSchema extends Schema<null> {
   }
 }
 
+/**
+ * Creates a null schema that only accepts the null value.
+ *
+ * Useful for explicitly representing null in union types or optional fields.
+ *
+ * @returns A new {@link NullSchema} instance
+ *
+ * @example
+ * ```ts
+ * // Explicit null
+ * const nullOnlySchema = l.null()
+ *
+ * // Nullable string (string or null)
+ * const nullableStringSchema = l.union([l.string(), l.null()])
+ * ```
+ */
 export const nullSchema = /*#__PURE__*/ memoizedOptions(function () {
   return new NullSchema()
 })

package/src/schema/nullable.ts

@@ -7,6 +7,21 @@ import {
 } from '../core.js'
 import { memoizedTransformer } from '../util/memoize.js'
 
+/**
+ * Schema wrapper that allows null values in addition to the wrapped schema.
+ *
+ * When the input is `null`, validation succeeds immediately. Otherwise,
+ * the input is validated against the wrapped schema.
+ *
+ * @template TValidator - The wrapped validator type
+ *
+ * @example
+ * ```ts
+ * const schema = new NullableSchema(l.string())
+ * schema.validate(null)    // success
+ * schema.validate('hello') // success
+ * ```
+ */
 export class NullableSchema<const TValidator extends Validator> extends Schema<
   InferInput<TValidator> | null,
   InferOutput<TValidator> | null
@@ -24,6 +39,32 @@ export class NullableSchema<const TValidator extends Validator> extends Schema<
   }
 }
 
+/**
+ * Creates a nullable schema that accepts null in addition to the wrapped type.
+ *
+ * Wraps another schema to allow null values. Different from `optional()` which
+ * allows undefined.
+ *
+ * @param validator - The validator to make nullable
+ * @returns A new {@link NullableSchema} instance
+ *
+ * @example
+ * ```ts
+ * // Nullable string
+ * const nullableString = l.nullable(l.string())
+ * nullableString.parse(null)    // null
+ * nullableString.parse('hello') // 'hello'
+ *
+ * // In an object
+ * const userSchema = l.object({
+ *   name: l.string(),
+ *   deletedAt: l.nullable(l.string({ format: 'datetime' })),
+ * })
+ *
+ * // Combine with optional for null or undefined
+ * const maybeString = l.optional(l.nullable(l.string()))
+ * ```
+ */
 export const nullable = /*#__PURE__*/ memoizedTransformer(function <
   const TValidator extends Validator,
 >(validator: TValidator) {

package/src/schema/object.ts

@@ -9,8 +9,30 @@ import {
 } from '../core.js'
 import { lazyProperty } from '../util/lazy-property.js'
 
+/**
+ * Type representing the shape of an object schema.
+ *
+ * Maps property names to their corresponding validators.
+ */
 export type ObjectSchemaShape = Record<string, Validator>
 
+/**
+ * Schema for validating objects with a defined shape.
+ *
+ * Each property in the shape is validated against its corresponding schema.
+ * Properties wrapped in `optional()` are not required.
+ *
+ * @template TShape - The object shape type mapping property names to validators
+ *
+ * @example
+ * ```ts
+ * const schema = new ObjectSchema({
+ *   name: l.string(),
+ *   age: l.optional(l.integer()),
+ * })
+ * const result = schema.validate({ name: 'Alice' })
+ * ```
+ */
 export class ObjectSchema<
   const TShape extends ObjectSchemaShape = any,
 > extends Schema<
@@ -70,6 +92,40 @@ export class ObjectSchema<
   }
 }
 
+/**
+ * Creates an object schema with the specified property validators.
+ *
+ * Validates that the input is a plain object and each property matches
+ * its corresponding schema. Properties wrapped in `optional()` are not required.
+ *
+ * @param properties - Object mapping property names to their validators
+ * @returns A new {@link ObjectSchema} instance
+ *
+ * @example
+ * ```ts
+ * // Basic object
+ * const userSchema = l.object({
+ *   name: l.string(),
+ *   email: l.string({ format: 'uri' }),
+ * })
+ *
+ * // With optional properties
+ * const profileSchema = l.object({
+ *   displayName: l.string(),
+ *   bio: l.optional(l.string({ maxLength: 256 })),
+ *   avatar: l.optional(l.blob({ accept: ['image/*'] })),
+ * })
+ *
+ * // Nested objects
+ * const postSchema = l.object({
+ *   text: l.string(),
+ *   author: l.object({
+ *     did: l.string({ format: 'did' }),
+ *     handle: l.string({ format: 'handle' }),
+ *   }),
+ * })
+ * ```
+ */
 /*@__NO_SIDE_EFFECTS__*/
 export function object<const TShape extends ObjectSchemaShape>(
   properties: TShape,

package/src/schema/optional.ts

@@ -9,6 +9,22 @@ import {
 import { memoizedTransformer } from '../util/memoize.js'
 import { WithDefaultSchema } from './with-default.js'
 
+/**
+ * Schema wrapper that makes a value optional (allows undefined).
+ *
+ * When the input is `undefined`, validation succeeds without running the
+ * inner validator. If the inner validator has a default value (via `withDefault`),
+ * that default will be applied in parse mode.
+ *
+ * @template TValidator - The wrapped validator type
+ *
+ * @example
+ * ```ts
+ * const schema = new OptionalSchema(l.string())
+ * schema.validate(undefined) // success
+ * schema.validate('hello')   // success
+ * ```
+ */
 export class OptionalSchema<TValidator extends Validator> extends Schema<
   InferInput<TValidator> | undefined,
   UnwrapValidator<TValidator> extends WithDefaultSchema<infer TValidator>
@@ -41,6 +57,32 @@ export class OptionalSchema<TValidator extends Validator> extends Schema<
   }
 }
 
+/**
+ * Creates an optional schema that allows undefined values.
+ *
+ * Wraps another schema to make it optional. When used in an object schema,
+ * properties with optional schemas are not required.
+ *
+ * @param validator - The validator to make optional
+ * @returns A new {@link OptionalSchema} instance
+ *
+ * @example
+ * ```ts
+ * // Optional string
+ * const optionalBio = l.optional(l.string())
+ *
+ * // In an object - property is not required
+ * const userSchema = l.object({
+ *   name: l.string(),
+ *   bio: l.optional(l.string()),
+ * })
+ * userSchema.parse({ name: 'Alice' }) // Valid, bio is undefined
+ *
+ * // With default value
+ * const countSchema = l.optional(l.withDefault(l.integer(), 0))
+ * countSchema.parse(undefined) // Returns 0
+ * ```
+ */
 export const optional = /*#__PURE__*/ memoizedTransformer(function <
   const TValidator extends Validator,
 >(validator: TValidator) {

package/src/schema/params.test.ts

@@ -265,6 +265,9 @@ describe('ParamsSchema', () => {
       name: string(),
       age: optional(integer()),
       active: optional(boolean()),
+      tags: optional(array(string())),
+      ids: optional(array(integer())),
+      bools: optional(array(boolean())),
     })
 
     it('parses string parameters', () => {
@@ -310,9 +313,9 @@ describe('ParamsSchema', () => {
     })
 
     it('parses multiple values as array', () => {
-      const urlParams = new URLSearchParams('name=Alice&tag=one&tag=two')
+      const urlParams = new URLSearchParams('name=Alice&tags=one&tags=two')
       const result = schema.fromURLSearchParams(urlParams)
-      expect(result).toEqual({ name: 'Alice', tag: ['one', 'two'] })
+      expect(result).toEqual({ name: 'Alice', tags: ['one', 'two'] })
     })
 
     it('coerces array values correctly', () => {
@@ -346,6 +349,59 @@ describe('ParamsSchema', () => {
         extra: 'value',
       })
     })
+
+    it('coerces single values into arrays in parse mode', () => {
+      expect(
+        schema.fromURLSearchParams([
+          ['name', 'Alice'],
+          ['tags', 'tag1'],
+        ]),
+      ).toEqual({ name: 'Alice', tags: ['tag1'] })
+
+      expect(
+        schema.fromURLSearchParams([
+          ['name', 'Alice'],
+          ['tags', 'true'],
+        ]),
+      ).toEqual({ name: 'Alice', tags: ['true'] })
+
+      expect(
+        schema.fromURLSearchParams([
+          ['name', 'Alice'],
+          ['tags', '1'],
+        ]),
+      ).toEqual({ name: 'Alice', tags: ['1'] })
+    })
+
+    it('coerces single boolean values into arrays in parse mode', () => {
+      expect(
+        schema.fromURLSearchParams([
+          ['name', 'Alice'],
+          ['bools', 'true'],
+        ]),
+      ).toEqual({ name: 'Alice', bools: [true] })
+
+      expect(
+        schema.fromURLSearchParams([
+          ['name', 'Alice'],
+          ['bools', 'false'],
+        ]),
+      ).toEqual({ name: 'Alice', bools: [false] })
+
+      expect(() =>
+        schema.fromURLSearchParams([
+          ['name', 'Alice'],
+          ['bools', 'notabool'],
+        ]),
+      ).toThrow('Expected boolean value type at $.bools[0] (got string)')
+
+      expect(() =>
+        schema.fromURLSearchParams([
+          ['name', 'Alice'],
+          ['bools', '2'],
+        ]),
+      ).toThrow('Expected boolean value type at $.bools[0] (got integer)')
+    })
   })
 
   describe('toURLSearchParams', () => {

package/src/schema/params.ts

@@ -10,27 +10,82 @@ import {
 } from '../core.js'
 import { lazyProperty } from '../util/lazy-property.js'
 import { memoizedOptions } from '../util/memoize.js'
-import { array } from './array.js'
-import { boolean } from './boolean.js'
+import { ArraySchema, array } from './array.js'
+import { BooleanSchema, boolean } from './boolean.js'
 import { dict } from './dict.js'
-import { integer } from './integer.js'
-import { optional } from './optional.js'
+import { IntegerSchema, integer } from './integer.js'
+import { OptionalSchema, optional } from './optional.js'
 import { StringSchema, string } from './string.js'
 import { union } from './union.js'
+import { WithDefaultSchema } from './with-default.js'
 
+/**
+ * Scalar types allowed in URL parameters: boolean, integer, or string.
+ */
 export type ParamScalar = Infer<typeof paramScalarSchema>
 const paramScalarSchema = union([boolean(), integer(), string()])
 
+/**
+ * A single parameter value: scalar or array of scalars.
+ */
 export type Param = Infer<typeof paramSchema>
+
+/**
+ * Schema for validating individual parameter values.
+ */
 export const paramSchema = union([paramScalarSchema, array(paramScalarSchema)])
 
+/**
+ * Type for a params object with string keys and optional param values.
+ */
 export type Params = Infer<typeof paramsSchema>
+
+/**
+ * Schema for validating arbitrary params objects.
+ */
 export const paramsSchema = dict(string(), optional(paramSchema))
 
+// @NOTE In order to properly coerce URLSearchParams, we need to distinguish
+// between scalar and array validators, requiring to be able to detect which
+// schema types are being used, restricting the allowed param validators here.
+type ParamScalarValidator = StringSchema | BooleanSchema | IntegerSchema
+type ParamValueValidator =
+  | ParamScalarValidator
+  | ArraySchema<ParamScalarValidator>
+type ParamValidator =
+  | ParamValueValidator
+  | OptionalSchema<ParamValueValidator>
+  | OptionalSchema<WithDefaultSchema<ParamValueValidator>>
+  | WithDefaultSchema<ParamValueValidator>
+
+/**
+ * Type representing the shape of a params schema definition.
+ *
+ * Maps parameter names to their validators (must be Param or undefined).
+ */
 export type ParamsSchemaShape = {
-  [x: string]: Validator<Param | undefined>
+  [x: string]: ParamValidator
 }
 
+/**
+ * Schema for validating URL query parameters in Lexicon endpoints.
+ *
+ * Params are the query string parameters passed to queries, procedures,
+ * and subscriptions. Values must be scalars (boolean, integer, string)
+ * or arrays of scalars, as they need to be serializable to URL format.
+ *
+ * Provides methods for converting to/from URLSearchParams.
+ *
+ * @template TShape - The params shape type mapping names to validators
+ *
+ * @example
+ * ```ts
+ * const schema = new ParamsSchema({
+ *   limit: l.optional(l.integer({ minimum: 1, maximum: 100 })),
+ *   cursor: l.optional(l.string()),
+ * })
+ * ```
+ */
 export class ParamsSchema<
   const TShape extends ParamsSchemaShape = ParamsSchemaShape,
 > extends Schema<
@@ -45,14 +100,13 @@ export class ParamsSchema<
     super()
   }
 
-  get shapeValidators(): Map<string, Validator<Param | undefined>> {
+  get shapeValidators(): Map<string, ParamValidator> {
     const map = new Map(Object.entries(this.shape))
 
     return lazyProperty(this, 'shapeValidators', map)
   }
 
   validateInContext(input: unknown, ctx: ValidationContext) {
-    // @TODO BETTER SUPPORT Input/Output
     if (!isPlainObject(input)) {
       return ctx.issueInvalidType(input, 'object')
     }
@@ -109,14 +163,22 @@ export class ParamsSchema<
     return ctx.success(copy ?? input)
   }
 
-  fromURLSearchParams(urlSearchParams: URLSearchParams): InferOutput<this> {
+  fromURLSearchParams(iterable: Iterable<[string, string]>): InferOutput<this> {
     const params: Record<string, Param> = {}
 
-    for (const [key, value] of urlSearchParams.entries()) {
-      const validator = this.shapeValidators.get(key)
+    // Compatibility with URLSearchParams not being iterable in some environments
+    const entries =
+      iterable instanceof URLSearchParams ? iterable.entries() : iterable
+
+    for (const [key, value] of entries) {
+      const validator = unwrapValidator(this.shapeValidators.get(key))
+      const expectsArray = validator instanceof ArraySchema
+      const scalarValidator = expectsArray
+        ? unwrapValidator(validator.validator)
+        : validator
 
       const coerced: ParamScalar =
-        validator instanceof StringSchema
+        scalarValidator instanceof StringSchema
           ? value
           : value === 'true'
             ? true
@@ -126,12 +188,13 @@ export class ParamsSchema<
                 ? Number(value)
                 : value
 
-      if (params[key] === undefined) {
-        params[key] = coerced
-      } else if (Array.isArray(params[key])) {
-        params[key].push(coerced)
+      const currentParam = params[key]
+      if (currentParam === undefined) {
+        params[key] = expectsArray ? [coerced] : coerced
+      } else if (Array.isArray(currentParam)) {
+        currentParam.push(coerced)
       } else {
-        params[key] = [params[key] as ParamScalar, coerced]
+        params[key] = [currentParam, coerced]
       }
     }
 
@@ -159,8 +222,53 @@ export class ParamsSchema<
   }
 }
 
+/**
+ * Creates a params schema for URL query parameters.
+ *
+ * Params schemas validate query string parameters for Lexicon endpoints.
+ * Values must be boolean, integer, string, or arrays of those types.
+ *
+ * @param properties - Object mapping parameter names to their validators
+ * @returns A new {@link ParamsSchema} instance
+ *
+ * @example
+ * ```ts
+ * // Simple pagination params
+ * const paginationParams = l.params({
+ *   limit: l.optional(l.withDefault(l.integer({ minimum: 1, maximum: 100 }), 50)),
+ *   cursor: l.optional(l.string()),
+ * })
+ *
+ * // Required parameter
+ * const actorParams = l.params({
+ *   actor: l.string({ format: 'at-identifier' }),
+ * })
+ *
+ * // Array parameter (multiple values)
+ * const filterParams = l.params({
+ *   tags: l.optional(l.array(l.string())),
+ * })
+ *
+ * // Convert from URL
+ * const urlParams = new URLSearchParams('limit=25&cursor=abc')
+ * const validated = paginationParams.fromURLSearchParams(urlParams)
+ *
+ * // Convert to URL
+ * const searchParams = paginationParams.toURLSearchParams({ limit: 25 })
+ * ```
+ */
 export const params = /*#__PURE__*/ memoizedOptions(function params<
   const TShape extends ParamsSchemaShape = NonNullable<unknown>,
 >(properties: TShape = {} as TShape) {
   return new ParamsSchema<TShape>(properties)
 })
+
+function unwrapValidator(schema?: Validator): Validator | undefined {
+  while (
+    schema instanceof OptionalSchema ||
+    schema instanceof WithDefaultSchema
+  ) {
+    schema = schema.validator
+  }
+  return schema
+}