@atproto/lex-schema 0.0.11 → 0.0.13

package/src/schema/array.test.ts

@@ -5,103 +5,118 @@ import { object } from './object.js'
 import { string } from './string.js'
 
 describe('ArraySchema', () => {
-  it('validates arrays with string items', () => {
-    const schema = array(string())
-    const result = schema.safeParse(['hello', 'world'])
-    expect(result.success).toBe(true)
-  })
-
-  it('validates arrays with integer items', () => {
-    const schema = array(integer())
-    const result = schema.safeParse([1, 2, 3])
-    expect(result.success).toBe(true)
-  })
+  describe('validation', () => {
+    it('validates arrays with string items', () => {
+      const schema = array(string())
+      const result = schema.safeValidate(['hello', 'world'])
+      expect(result).toMatchObject({ success: true })
+    })
+
+    it('validates arrays with integer items', () => {
+      const schema = array(integer())
+      const result = schema.safeValidate([1, 2, 3])
+      expect(result).toMatchObject({ success: true })
+    })
+
+    it('validates arrays with object items', () => {
+      const schema = array(
+        object({
+          name: string(),
+          age: integer(),
+        }),
+      )
+      const result = schema.safeValidate([
+        { name: 'Alice', age: 30 },
+        { name: 'Bob', age: 25 },
+      ])
+      expect(result).toMatchObject({ success: true })
+    })
 
-  it('validates arrays with object items', () => {
-    const schema = array(
-      object({
-        name: string(),
-        age: integer(),
-      }),
-    )
-    const result = schema.safeParse([
-      { name: 'Alice', age: 30 },
-      { name: 'Bob', age: 25 },
-    ])
-    expect(result.success).toBe(true)
-  })
+    it('validates empty arrays', () => {
+      const schema = array(string())
+      const result = schema.safeValidate([])
+      expect(result).toMatchObject({ success: true })
+    })
 
-  it('validates empty arrays', () => {
-    const schema = array(string())
-    const result = schema.safeParse([])
-    expect(result.success).toBe(true)
-  })
+    it('rejects non-array values', () => {
+      const schema = array(string())
+      const result = schema.safeValidate('not an array')
+      expect(result).toMatchObject({ success: false })
+    })
 
-  it('rejects non-array values', () => {
-    const schema = array(string())
-    const result = schema.safeParse('not an array')
-    expect(result.success).toBe(false)
-  })
+    it('rejects null values', () => {
+      const schema = array(string())
+      const result = schema.safeValidate(null)
+      expect(result).toMatchObject({ success: false })
+    })
 
-  it('rejects null values', () => {
-    const schema = array(string())
-    const result = schema.safeParse(null)
-    expect(result.success).toBe(false)
-  })
+    it('rejects undefined values', () => {
+      const schema = array(string())
+      const result = schema.safeValidate(undefined)
+      expect(result).toMatchObject({ success: false })
+    })
 
-  it('rejects undefined values', () => {
-    const schema = array(string())
-    const result = schema.safeParse(undefined)
-    expect(result.success).toBe(false)
-  })
+    it('rejects objects that look like arrays', () => {
+      const schema = array(string())
+      const result = schema.safeValidate({ 0: 'a', 1: 'b', length: 2 })
+      expect(result).toMatchObject({ success: false })
+    })
 
-  it('rejects objects that look like arrays', () => {
-    const schema = array(string())
-    const result = schema.safeParse({ 0: 'a', 1: 'b', length: 2 })
-    expect(result.success).toBe(false)
-  })
+    it('rejects arrays with invalid items', () => {
+      const schema = array(integer())
+      const result = schema.safeValidate([1, 2, 'three'])
+      expect(result).toMatchObject({ success: false })
+    })
 
-  it('rejects arrays with invalid items', () => {
-    const schema = array(integer())
-    const result = schema.safeParse([1, 2, 'three'])
-    expect(result.success).toBe(false)
-  })
+    it('rejects arrays with some invalid items', () => {
+      const schema = array(string())
+      const result = schema.safeValidate(['valid', null, 'also valid'])
+      expect(result).toMatchObject({ success: false })
+    })
 
-  it('rejects arrays with some invalid items', () => {
-    const schema = array(string())
-    const result = schema.safeParse(['valid', null, 'also valid'])
-    expect(result.success).toBe(false)
+    it('rejects single values', () => {
+      const schema = array(string())
+      const result = schema.safeValidate(3)
+      expect(result).toEqual({
+        success: false,
+        reason: expect.objectContaining({
+          message: expect.stringContaining(
+            'Expected array value type at $ (got integer)',
+          ),
+        }),
+      })
+    })
   })
 
   describe('minLength constraint', () => {
     it('validates arrays meeting minLength', () => {
       const schema = array(string(), { minLength: 2 })
       const result = schema.safeParse(['a', 'b'])
-      expect(result.success).toBe(true)
+      expect(result).toMatchObject({ success: true })
     })
 
     it('validates arrays exceeding minLength', () => {
       const schema = array(string(), { minLength: 2 })
       const result = schema.safeParse(['a', 'b', 'c'])
-      expect(result.success).toBe(true)
+      expect(result).toMatchObject({ success: true })
     })
 
     it('rejects arrays below minLength', () => {
       const schema = array(string(), { minLength: 3 })
       const result = schema.safeParse(['a', 'b'])
-      expect(result.success).toBe(false)
+      expect(result).toMatchObject({ success: false })
     })
 
     it('rejects empty arrays when minLength is set', () => {
       const schema = array(string(), { minLength: 1 })
       const result = schema.safeParse([])
-      expect(result.success).toBe(false)
+      expect(result).toMatchObject({ success: false })
     })
 
     it('validates empty arrays when minLength is 0', () => {
       const schema = array(string(), { minLength: 0 })
       const result = schema.safeParse([])
-      expect(result.success).toBe(true)
+      expect(result).toMatchObject({ success: true })
     })
   })
 
@@ -109,37 +124,37 @@ describe('ArraySchema', () => {
     it('validates arrays meeting maxLength', () => {
       const schema = array(string(), { maxLength: 3 })
       const result = schema.safeParse(['a', 'b', 'c'])
-      expect(result.success).toBe(true)
+      expect(result).toMatchObject({ success: true })
     })
 
     it('validates arrays below maxLength', () => {
       const schema = array(string(), { maxLength: 3 })
       const result = schema.safeParse(['a', 'b'])
-      expect(result.success).toBe(true)
+      expect(result).toMatchObject({ success: true })
     })
 
     it('rejects arrays exceeding maxLength', () => {
       const schema = array(string(), { maxLength: 2 })
       const result = schema.safeParse(['a', 'b', 'c'])
-      expect(result.success).toBe(false)
+      expect(result).toMatchObject({ success: false })
     })
 
     it('validates empty arrays with maxLength', () => {
       const schema = array(string(), { maxLength: 5 })
       const result = schema.safeParse([])
-      expect(result.success).toBe(true)
+      expect(result).toMatchObject({ success: true })
     })
 
     it('rejects empty arrays when maxLength is 0', () => {
       const schema = array(string(), { maxLength: 0 })
       const result = schema.safeParse(['a'])
-      expect(result.success).toBe(false)
+      expect(result).toMatchObject({ success: false })
     })
 
     it('validates empty arrays when maxLength is 0', () => {
       const schema = array(string(), { maxLength: 0 })
       const result = schema.safeParse([])
-      expect(result.success).toBe(true)
+      expect(result).toMatchObject({ success: true })
     })
   })
 
@@ -150,7 +165,7 @@ describe('ArraySchema', () => {
         maxLength: 4,
       })
       const result = schema.safeParse(['a', 'b', 'c'])
-      expect(result.success).toBe(true)
+      expect(result).toMatchObject({ success: true })
     })
 
     it('validates arrays at min boundary', () => {
@@ -159,7 +174,7 @@ describe('ArraySchema', () => {
         maxLength: 4,
       })
       const result = schema.safeParse(['a', 'b'])
-      expect(result.success).toBe(true)
+      expect(result).toMatchObject({ success: true })
     })
 
     it('validates arrays at max boundary', () => {
@@ -168,7 +183,7 @@ describe('ArraySchema', () => {
         maxLength: 4,
       })
       const result = schema.safeParse(['a', 'b', 'c', 'd'])
-      expect(result.success).toBe(true)
+      expect(result).toMatchObject({ success: true })
     })
 
     it('rejects arrays below minLength', () => {
@@ -177,7 +192,7 @@ describe('ArraySchema', () => {
         maxLength: 4,
       })
       const result = schema.safeParse(['a'])
-      expect(result.success).toBe(false)
+      expect(result).toMatchObject({ success: false })
     })
 
     it('rejects arrays above maxLength', () => {
@@ -186,7 +201,7 @@ describe('ArraySchema', () => {
         maxLength: 4,
       })
       const result = schema.safeParse(['a', 'b', 'c', 'd', 'e'])
-      expect(result.success).toBe(false)
+      expect(result).toMatchObject({ success: false })
     })
 
     it('validates single-length range', () => {
@@ -195,7 +210,7 @@ describe('ArraySchema', () => {
         maxLength: 3,
       })
       const result = schema.safeParse(['a', 'b', 'c'])
-      expect(result.success).toBe(true)
+      expect(result).toMatchObject({ success: true })
     })
 
     it('rejects arrays not matching exact length', () => {
@@ -204,7 +219,7 @@ describe('ArraySchema', () => {
         maxLength: 3,
       })
       const result = schema.safeParse(['a', 'b'])
-      expect(result.success).toBe(false)
+      expect(result).toMatchObject({ success: false })
     })
   })
 
@@ -215,7 +230,7 @@ describe('ArraySchema', () => {
         ['a', 'b'],
         ['c', 'd'],
       ])
-      expect(result.success).toBe(true)
+      expect(result).toMatchObject({ success: true })
     })
 
     it('rejects invalid nested arrays', () => {
@@ -224,13 +239,13 @@ describe('ArraySchema', () => {
         [1, 2],
         [3, 'four'],
       ])
-      expect(result.success).toBe(false)
+      expect(result).toMatchObject({ success: false })
     })
 
     it('validates deeply nested arrays', () => {
       const schema = array(array(array(integer())))
       const result = schema.safeParse([[[1, 2], [3]], [[4, 5, 6]]])
-      expect(result.success).toBe(true)
+      expect(result).toMatchObject({ success: true })
     })
   })
 })

package/src/schema/array.ts

@@ -7,15 +7,37 @@ import {
 } from '../core.js'
 import { memoizedTransformer } from '../util/memoize.js'
 
+/**
+ * Configuration options for array schema validation.
+ *
+ * @property minLength - Minimum number of items in the array
+ * @property maxLength - Maximum number of items in the array
+ */
 export type ArraySchemaOptions = {
   minLength?: number
   maxLength?: number
 }
 
+/**
+ * Schema for validating arrays where all items match a given schema.
+ *
+ * Validates that the input is an array, checks length constraints, and
+ * validates each item against the provided item schema.
+ *
+ * @template TItem - The validator type for array items
+ *
+ * @example
+ * ```ts
+ * const schema = new ArraySchema(l.string(), { maxLength: 10 })
+ * const result = schema.validate(['a', 'b', 'c'])
+ * ```
+ */
 export class ArraySchema<const TItem extends Validator> extends Schema<
   Array<InferInput<TItem>>,
   Array<InferOutput<TItem>>
 > {
+  readonly type = 'array' as const
+
   constructor(
     readonly validator: TItem,
     readonly options: ArraySchemaOptions = {},
@@ -25,7 +47,7 @@ export class ArraySchema<const TItem extends Validator> extends Schema<
 
   validateInContext(input: unknown, ctx: ValidationContext) {
     if (!Array.isArray(input)) {
-      return ctx.issueInvalidType(input, 'array')
+      return ctx.issueUnexpectedType(input, 'array')
     }
 
     const { minLength, maxLength } = this.options
@@ -60,6 +82,31 @@ export class ArraySchema<const TItem extends Validator> extends Schema<
   }
 }
 
+/**
+ * Creates an array schema that validates each item against the provided schema.
+ *
+ * @param items - Schema to validate each array item against
+ * @param options - Optional length constraints
+ * @returns A new {@link ArraySchema} instance
+ *
+ * @example
+ * ```ts
+ * // Array of strings
+ * const tagsSchema = l.array(l.string())
+ *
+ * // Array with length constraints
+ * const limitedSchema = l.array(l.integer(), { maxLength: 100 })
+ *
+ * // Array of objects
+ * const usersSchema = l.array(l.object({
+ *   name: l.string(),
+ *   age: l.integer(),
+ * }))
+ *
+ * // Non-empty array
+ * const nonEmptySchema = l.array(l.string(), { minLength: 1 })
+ * ```
+ */
 /*@__NO_SIDE_EFFECTS__*/
 function arraySchema<const TValidator extends Validator>(
   items: TValidator,

package/src/schema/blob.ts

@@ -8,6 +8,13 @@ import {
 import { Schema, ValidationContext } from '../core.js'
 import { memoizedOptions } from '../util/memoize.js'
 
+/**
+ * Configuration options for blob schema validation.
+ *
+ * @property allowLegacy - Whether to allow legacy blob references format
+ * @property accept - List of accepted MIME types (supports wildcards like 'image/*' or '*\/*')
+ * @property maxSize - Maximum blob size in bytes
+ */
 export type BlobSchemaOptions = BlobRefCheckOptions & {
   /**
    * Whether to allow legacy blob references format
@@ -25,12 +32,30 @@ export type BlobSchemaOptions = BlobRefCheckOptions & {
 }
 
 export type { BlobRef, LegacyBlobRef }
+export { isBlobRef, isLegacyBlobRef }
 
+/**
+ * Schema for validating blob references in AT Protocol.
+ *
+ * Validates BlobRef objects which contain a CID reference to binary data,
+ * along with metadata like MIME type and size. Can optionally accept
+ * legacy blob reference format.
+ *
+ * @template TOptions - The configuration options type
+ *
+ * @example
+ * ```ts
+ * const schema = new BlobSchema({ accept: ['image/*'], maxSize: 1000000 })
+ * const result = schema.validate(blobRef)
+ * ```
+ */
 export class BlobSchema<
   const TOptions extends BlobSchemaOptions = NonNullable<unknown>,
 > extends Schema<
   TOptions extends { allowLegacy: true } ? BlobRef | LegacyBlobRef : BlobRef
 > {
+  readonly type = 'blob' as const
+
   constructor(readonly options?: TOptions) {
     super()
   }
@@ -46,7 +71,7 @@ export class BlobSchema<
           : null
 
     if (!blob) {
-      return ctx.issueInvalidType(input, 'blob')
+      return ctx.issueUnexpectedType(input, 'blob')
     }
 
     const accept = this.options?.accept
@@ -80,6 +105,30 @@ function matchesMime(mime: string, accepted: string[]): boolean {
   return false
 }
 
+/**
+ * Creates a blob schema for validating blob references with optional constraints.
+ *
+ * Blob references are used in AT Protocol to reference binary data stored
+ * separately from records. They contain a CID, MIME type, and size information.
+ *
+ * @param options - Optional configuration for MIME type filtering and size limits
+ * @returns A new {@link BlobSchema} instance
+ *
+ * @example
+ * ```ts
+ * // Basic blob reference
+ * const fileSchema = l.blob()
+ *
+ * // Image files only
+ * const imageSchema = l.blob({ accept: ['image/png', 'image/jpeg', 'image/gif'] })
+ *
+ * // Any image type with size limit
+ * const avatarSchema = l.blob({ accept: ['image/*'], maxSize: 1000000 })
+ *
+ * // Allow legacy format
+ * const legacySchema = l.blob({ allowLegacy: true })
+ * ```
+ */
 export const blob = /*#__PURE__*/ memoizedOptions(function <
   O extends BlobSchemaOptions = { allowLegacy?: false },
 >(options?: O) {

package/src/schema/boolean.ts

@@ -1,16 +1,46 @@
 import { Schema, ValidationContext } from '../core.js'
 import { memoizedOptions } from '../util/memoize.js'
 
+/**
+ * Schema for validating boolean values.
+ *
+ * Only accepts JavaScript `true` or `false` values. Does not perform
+ * any coercion from strings or numbers.
+ *
+ * @example
+ * ```ts
+ * const schema = new BooleanSchema()
+ * schema.validate(true)  // success
+ * schema.validate(false) // success
+ * schema.validate('true') // fails - no string coercion
+ * ```
+ */
 export class BooleanSchema extends Schema<boolean> {
+  readonly type = 'boolean' as const
+
   validateInContext(input: unknown, ctx: ValidationContext) {
     if (typeof input === 'boolean') {
       return ctx.success(input)
     }
 
-    return ctx.issueInvalidType(input, 'boolean')
+    return ctx.issueUnexpectedType(input, 'boolean')
   }
 }
 
+/**
+ * Creates a boolean schema that validates true/false values.
+ *
+ * @returns A new {@link BooleanSchema} instance
+ *
+ * @example
+ * ```ts
+ * const enabledSchema = l.boolean()
+ *
+ * enabledSchema.parse(true)   // true
+ * enabledSchema.parse(false)  // false
+ * enabledSchema.parse('true') // throws - strings not accepted
+ * ```
+ */
 export const boolean = /*#__PURE__*/ memoizedOptions(function () {
   return new BooleanSchema()
 })

package/src/schema/bytes.ts

@@ -2,12 +2,32 @@ import { asUint8Array, ifUint8Array } from '@atproto/lex-data'
 import { Schema, ValidationContext } from '../core.js'
 import { memoizedOptions } from '../util/memoize.js'
 
+/**
+ * Configuration options for bytes schema validation.
+ *
+ * @property minLength - Minimum length in bytes
+ * @property maxLength - Maximum length in bytes
+ */
 export type BytesSchemaOptions = {
   minLength?: number
   maxLength?: number
 }
 
+/**
+ * Schema for validating binary data as Uint8Array with optional length constraints.
+ *
+ * In "parse" mode, coerces various binary formats (Buffer, ArrayBuffer, etc.)
+ * into Uint8Array. In "validate" mode, only accepts Uint8Array directly.
+ *
+ * @example
+ * ```ts
+ * const schema = new BytesSchema({ maxLength: 1024 })
+ * const result = schema.validate(new Uint8Array([1, 2, 3]))
+ * ```
+ */
 export class BytesSchema extends Schema<Uint8Array> {
+  readonly type = 'bytes' as const
+
   constructor(readonly options: BytesSchemaOptions = {}) {
     super()
   }
@@ -17,7 +37,7 @@ export class BytesSchema extends Schema<Uint8Array> {
     const bytes =
       ctx.options.mode === 'parse' ? asUint8Array(input) : ifUint8Array(input)
     if (!bytes) {
-      return ctx.issueInvalidType(input, 'bytes')
+      return ctx.issueUnexpectedType(input, 'bytes')
     }
 
     const { minLength } = this.options
@@ -34,6 +54,26 @@ export class BytesSchema extends Schema<Uint8Array> {
   }
 }
 
+/**
+ * Creates a bytes schema for validating binary data with optional length constraints.
+ *
+ * Validates Uint8Array values and can coerce other binary formats in parse mode.
+ *
+ * @param options - Optional configuration for minimum and maximum byte length
+ * @returns A new {@link BytesSchema} instance
+ *
+ * @example
+ * ```ts
+ * // Basic bytes schema
+ * const dataSchema = l.bytes()
+ *
+ * // With size constraints
+ * const avatarSchema = l.bytes({ maxLength: 1000000 }) // 1MB max
+ *
+ * // With minimum size
+ * const hashSchema = l.bytes({ minLength: 32, maxLength: 32 }) // Exactly 32 bytes
+ * ```
+ */
 export const bytes = /*#__PURE__*/ memoizedOptions(function (
   options?: BytesSchemaOptions,
 ) {

package/src/schema/cid.ts

@@ -4,24 +4,64 @@ import { memoizedOptions } from '../util/memoize.js'
 
 export type { Cid }
 
+/**
+ * Configuration options for CID schema validation.
+ *
+ * @see CheckCidOptions from @atproto/lex-data for available options
+ */
 export type CidSchemaOptions = CheckCidOptions
 
+/**
+ * Schema for validating Content Identifiers (CIDs).
+ *
+ * CIDs are self-describing content-addressed identifiers used in AT Protocol
+ * to reference data by its cryptographic hash. This schema validates that
+ * the input is a valid CID object.
+ *
+ * @template TOptions - The configuration options type
+ *
+ * @example
+ * ```ts
+ * const schema = new CidSchema()
+ * const result = schema.validate(someCid)
+ * ```
+ */
 export class CidSchema<
   const TOptions extends CidSchemaOptions = { flavor: undefined },
 > extends Schema<InferCheckedCid<TOptions>> {
+  readonly type = 'cid' as const
+
   constructor(readonly options?: TOptions) {
     super()
   }
 
   validateInContext(input: unknown, ctx: ValidationContext) {
     if (!isCid(input, this.options)) {
-      return ctx.issueInvalidType(input, 'cid')
+      return ctx.issueUnexpectedType(input, 'cid')
     }
 
     return ctx.success(input)
   }
 }
 
+/**
+ * Creates a CID schema for validating Content Identifiers.
+ *
+ * CIDs are used throughout AT Protocol to reference content by its hash.
+ * This is commonly used for referencing blobs, commits, and other data.
+ *
+ * @param options - Optional configuration for CID validation
+ * @returns A new {@link CidSchema} instance
+ *
+ * @example
+ * ```ts
+ * // Basic CID validation
+ * const cidSchema = l.cid()
+ *
+ * // Validate a CID from a blob reference
+ * const result = cidSchema.validate(blobRef.ref)
+ * ```
+ */
 export const cid = /*#__PURE__*/ memoizedOptions(function <
   O extends CidSchemaOptions = NonNullable<unknown>,
 >(options?: O) {