@atproto/lex-schema 0.0.11 → 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', () => {