@atproto/lex-schema 0.0.11 → 0.0.13

package/src/schema/lex-value.test.ts

@@ -0,0 +1,81 @@
+import { describe, expect, test } from 'vitest'
+import { parseCid } from '@atproto/lex-data'
+import { lexValue } from './lex-value.js'
+
+const schema = lexValue()
+
+describe(lexValue, () => {
+  describe('valid values', () => {
+    for (const { note, value } of [
+      { note: 'string', value: 'hello' },
+      { note: 'boolean true', value: true },
+      { note: 'boolean false', value: false },
+      { note: 'null', value: null },
+      { note: 'integer', value: 42 },
+      { note: 'negative integer', value: -1 },
+      { note: 'zero', value: 0 },
+      { note: 'Uint8Array', value: new Uint8Array([1, 2, 3]) },
+      {
+        note: 'Cid',
+        value: parseCid(
+          'bafyreidfayvfuwqa7qlnopdjiqrxzs6blmoeu4rujcjtnci5beludirz2a',
+        ),
+      },
+      { note: 'empty plain object', value: {} },
+      {
+        note: 'object with Lex values',
+        value: {
+          a: 123,
+          b: 'blah',
+          c: true,
+          d: null,
+          e: new Uint8Array([1, 2, 3]),
+          f: { nested: 'value' },
+          g: [1, 2, 3],
+        },
+      },
+      { note: 'empty array', value: [] },
+      {
+        note: 'array with Lex values',
+        value: [
+          123,
+          'blah',
+          true,
+          null,
+          new Uint8Array([1, 2, 3]),
+          { nested: 'value' },
+          [1, 2, 3],
+        ],
+      },
+    ]) {
+      test(note, () => {
+        const result = schema.safeParse(value)
+        expect(result.success).toBe(true)
+      })
+    }
+  })
+
+  describe('invalid values', () => {
+    for (const { note, value } of [
+      { note: 'float', value: 42.5 },
+      { note: 'undefined', value: undefined },
+      { note: 'function', value: () => {} },
+      { note: 'Date object', value: new Date() },
+      { note: 'Map object', value: new Map() },
+      { note: 'Set object', value: new Set() },
+      { note: 'class instance', value: new (class A {})() },
+      { note: 'object with function value', value: { a: 123, b: () => {} } },
+      {
+        note: 'object with undefined value',
+        value: { a: 123, b: undefined },
+      },
+      { note: 'array with function', value: [123, 'blah', () => {}] },
+      { note: 'array with undefined', value: [123, 'blah', undefined] },
+    ]) {
+      test(note, () => {
+        const result = schema.safeParse(value)
+        expect(result.success).toBe(false)
+      })
+    }
+  })
+})

package/src/schema/lex-value.ts

@@ -0,0 +1,86 @@
+import { LexValue, isLexScalar, isPlainObject } from '@atproto/lex-data'
+import { Schema, ValidationContext } from '../core.js'
+import { memoizedOptions } from '../util/memoize.js'
+
+export type { LexValue }
+
+const EXPECTED_TYPES = Object.freeze([
+  // Scalar types
+  'null',
+  'boolean',
+  'integer',
+  'string',
+  'cid',
+  'bytes',
+  // Recursive types
+  'array',
+  'object',
+] as const)
+
+/**
+ * AT Protocol lexicon values are any valid AT Protocol data types: string,
+ * integer, boolean, null, bytes, cid, array, or object.
+ */
+export class LexValueSchema extends Schema<LexValue> {
+  readonly type = 'lexValue' as const
+
+  validateInContext(input: unknown, ctx: ValidationContext) {
+    // @NOTE We are *not* using "isLexValue" here to allow for more specific
+    // error messages about the path and type of the invalid value. The
+    // "isLexValue" check is effectively performed by the recursive validation
+    // of child properties below.
+
+    // @NOTE There are two limitations to the fact that we are not using
+    // "isLexValue" here:
+    // 1. We cannot detect circular references in objects or arrays, which would
+    //    cause infinite recursion. However, circular references are not valid
+    //    AT Protocol data types, so this is not a concern for valid input. This
+    //    could easily be addressed in the "validateChild" method by keeping
+    //    track of "parent" objects.
+    // 2. We are limited in the recursion depth we can validate due to potential
+    //    recursion depth limits in JavaScript. However, this is also not a
+    //    concern for most valid input, as extremely deep nesting is unlikely in
+    //    typical use cases.
+    if (isPlainObject(input)) {
+      for (const key of Object.keys(input)) {
+        const r = ctx.validateChild(input, key, this) // recursively validate all properties
+        if (!r.success) return r
+      }
+    } else if (Array.isArray(input)) {
+      for (let i = 0; i < input.length; i++) {
+        const r = ctx.validateChild(input, i, this) // recursively validate all array items
+        if (!r.success) return r
+      }
+    } else if (!isLexScalar(input)) {
+      return ctx.issueInvalidType(input, EXPECTED_TYPES)
+    }
+
+    return ctx.success(input)
+  }
+}
+
+/**
+ * Creates a schema that accepts any valid AT Protocol data type: string,
+ * integer, boolean, null, bytes, cid, array, or plain object. Arrays and
+ * objects are recursively validated to ensure all nested values are also valid
+ * AT Protocol data types.
+ *
+ * @see {@link LexValue} from `@atproto/lex-data` for the type definition of valid AT Protocol data types
+ * @returns A new {@link LexValueSchema} instance
+ *
+ * @example
+ * ```ts
+ * const schema = l.lexValue()
+ *
+ * schema.validate('hello')              // success
+ * schema.validate(42)                   // success
+ * schema.validate(null)                 // success
+ * schema.validate([1, 'two', null])     // success
+ * schema.validate({ any: 'props' })     // success
+ * schema.validate(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 lexValue = /*#__PURE__*/ memoizedOptions(function () {
+  return new LexValueSchema()
+})

package/src/schema/literal.ts

@@ -1,8 +1,25 @@
 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> {
+  readonly type = 'literal' as const
+
   constructor(readonly value: TValue) {
     super()
   }
@@ -16,6 +33,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,56 @@
 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> {
+  readonly type = 'never' as const
+
   validateInContext(input: unknown, ctx: ValidationContext) {
-    return ctx.issueInvalidType(input, 'never')
+    return ctx.issueUnexpectedType(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,16 +1,47 @@
 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> {
+  readonly type = 'null' as const
+
   validateInContext(input: unknown, ctx: ValidationContext) {
     if (input !== null) {
-      return ctx.issueInvalidType(input, 'null')
+      return ctx.issueUnexpectedType(input, 'null')
     }
 
     return ctx.success(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,10 +7,27 @@ 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
 > {
+  readonly type = 'nullable' as const
+
   constructor(readonly validator: TValidator) {
     super()
   }
@@ -24,6 +41,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<
@@ -21,6 +43,8 @@ export class ObjectSchema<
     [K in keyof TShape]: InferOutput<TShape[K]>
   }>
 > {
+  readonly type = 'object' as const
+
   constructor(readonly shape: TShape) {
     super()
   }
@@ -33,7 +57,7 @@ export class ObjectSchema<
 
   validateInContext(input: unknown, ctx: ValidationContext) {
     if (!isPlainObject(input)) {
-      return ctx.issueInvalidType(input, 'object')
+      return ctx.issueUnexpectedType(input, 'object')
     }
 
     // Lazily copy value
@@ -70,6 +94,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,12 +9,30 @@ 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>
     ? InferOutput<TValidator>
     : InferOutput<TValidator> | undefined
 > {
+  readonly type = 'optional' as const
+
   constructor(readonly validator: TValidator) {
     super()
   }
@@ -41,6 +59,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) {