@atproto/lex-schema 0.0.12 → 0.0.13

package/src/schema/{unknown-object.test.ts → lex-map.test.ts}

@@ -1,9 +1,9 @@
 import { describe, expect, it } from 'vitest'
-import { unknownObject } from './unknown-object.js'
+import { lexMap } from './lex-map.js'
 
-describe('UnknownObjectSchema', () => {
+describe(lexMap, () => {
   describe('basic validation', () => {
-    const schema = unknownObject()
+    const schema = lexMap()
 
     it('accepts empty plain objects', () => {
       const result = schema.safeParse({})
@@ -106,7 +106,7 @@ describe('UnknownObjectSchema', () => {
   })
 
   describe('rejects non-plain-objects', () => {
-    const schema = unknownObject()
+    const schema = lexMap()
 
     it('rejects strings', () => {
       const result = schema.safeParse('not an object')
@@ -208,7 +208,7 @@ describe('UnknownObjectSchema', () => {
   })
 
   describe('rejects invalid value types', () => {
-    const schema = unknownObject()
+    const schema = lexMap()
 
     it('rejects objects with floating point numbers', () => {
       const result = schema.safeParse({ value: 3.14 })
@@ -288,7 +288,7 @@ describe('UnknownObjectSchema', () => {
   })
 
   describe('rejects invalid nested values', () => {
-    const schema = unknownObject()
+    const schema = lexMap()
 
     it('rejects deeply nested invalid values', () => {
       const result = schema.safeParse({
@@ -335,7 +335,7 @@ describe('UnknownObjectSchema', () => {
   })
 
   describe('edge cases', () => {
-    const schema = unknownObject()
+    const schema = lexMap()
 
     it('accepts objects with numeric string keys', () => {
       const obj = { '0': 'zero', '1': 'one', '2': 'two' }
@@ -500,7 +500,7 @@ describe('UnknownObjectSchema', () => {
   })
 
   describe('large objects', () => {
-    const schema = unknownObject()
+    const schema = lexMap()
 
     it('accepts objects with many keys', () => {
       const obj: Record<string, number> = {}
@@ -538,7 +538,7 @@ describe('UnknownObjectSchema', () => {
   })
 
   describe('preservation of input', () => {
-    const schema = unknownObject()
+    const schema = lexMap()
 
     it('preserves the original object reference', () => {
       const input = { key: 'value', count: 42 }

package/src/schema/lex-map.ts

@@ -0,0 +1,63 @@
+import { LexMap, isPlainObject } from '@atproto/lex-data'
+import { Schema, ValidationContext } from '../core.js'
+import { memoizedOptions } from '../util/memoize.js'
+import { lexValue } from './lex-value.js'
+
+const propertyValueSchema = /*#__PURE__*/ lexValue()
+
+export type { LexMap }
+
+/**
+ * AT Protocol lexicon schema definitions with "type": "unknown" are represented
+ * as plain objects with string keys and values that are valid AT Protocol data
+ * types (string, integer, boolean, null, bytes, cid, array, or object). This
+ * type alias corresponds to the expected structure of such "unknown" schema
+ * values.
+ */
+export class LexMapSchema extends Schema<LexMap> {
+  readonly type = 'lexMap' as const
+
+  validateInContext(input: unknown, ctx: ValidationContext) {
+    if (!isPlainObject(input)) {
+      return ctx.issueUnexpectedType(input, 'object')
+    }
+
+    for (const key of Object.keys(input)) {
+      // @NOTE We use a lexValue() schema here to recursively validate all
+      // nested values, which ensures that the error reporting includes the
+      // correct path and type information for any invalid nested values. This
+      // allows for more informative error descriptions than a simple "isLexMap"
+      // check.
+      const r = ctx.validateChild(input, key, propertyValueSchema) // recursively validate all properties
+      if (!r.success) return r
+    }
+
+    return ctx.success(input)
+  }
+}
+
+/**
+ * Creates a schema that accepts any plain object with string keys and values
+ * that are valid AT Protocol data types (string, integer, boolean, null, bytes,
+ * cid, array, or object).
+ *
+ * @see {@link LexMap} from `@atproto/lex-data` for the type definition of valid AT Protocol data types
+ * @returns A new {@link LexMapSchema} instance
+ *
+ * @example
+ * ```ts
+ * // Accept any object shape
+ * const schema = l.lexMap()
+ *
+ * schema.validate({ any: 'props' })    // success
+ * schema.validate([1, 2, 3])           // fails - only plain objects are accepted
+ * schema.validate({ foo: 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 lexMap = /*#__PURE__*/ memoizedOptions(function () {
+  return new LexMapSchema()
+})
+
+/** @deprecated Use {@link lexMap} instead */
+export const unknownObject = lexMap

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

@@ -18,6 +18,8 @@ import { Schema, ValidationContext } from '../core.js'
 export class LiteralSchema<
   const TValue extends null | string | number | boolean,
 > extends Schema<TValue> {
+  readonly type = 'literal' as const
+
   constructor(readonly value: TValue) {
     super()
   }

package/src/schema/never.ts

@@ -14,8 +14,10 @@ import { memoizedOptions } from '../util/memoize.js'
  * ```
  */
 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')
   }
 }
 

package/src/schema/null.ts

@@ -15,9 +15,11 @@ import { memoizedOptions } from '../util/memoize.js'
  * ```
  */
 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)

package/src/schema/nullable.ts

@@ -26,6 +26,8 @@ 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()
   }

package/src/schema/object.ts

@@ -43,6 +43,8 @@ export class ObjectSchema<
     [K in keyof TShape]: InferOutput<TShape[K]>
   }>
 > {
+  readonly type = 'object' as const
+
   constructor(readonly shape: TShape) {
     super()
   }
@@ -55,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

package/src/schema/optional.ts

@@ -31,6 +31,8 @@ export class OptionalSchema<TValidator extends Validator> extends Schema<
     ? InferOutput<TValidator>
     : InferOutput<TValidator> | undefined
 > {
+  readonly type = 'optional' as const
+
   constructor(readonly validator: TValidator) {
     super()
   }

package/src/schema/params.test.ts

@@ -1,7 +1,9 @@
 import { describe, expect, it } from 'vitest'
 import { array } from './array.js'
 import { boolean } from './boolean.js'
+import { enumSchema } from './enum.js'
 import { integer } from './integer.js'
+import { literal } from './literal.js'
 import { optional } from './optional.js'
 import { paramSchema, params, paramsSchema } from './params.js'
 import { string } from './string.js'
@@ -260,6 +262,42 @@ describe('ParamsSchema', () => {
     })
   })
 
+  describe('coercion', () => {
+    it('throws for invalid enum values', () => {
+      const schema = params({
+        status: enumSchema(['active', 'inactive']),
+      })
+      expect(() => schema.fromURLSearchParams('status=unknown')).toThrow(
+        'Expected one of "active" or "inactive"',
+      )
+    })
+
+    it('throws for invalid const values', () => {
+      const schema = params({
+        version: literal(42),
+      })
+      expect(() => schema.fromURLSearchParams('version=99')).toThrow(
+        'Expected 42',
+      )
+    })
+
+    it('handles negative integer enum values', () => {
+      const schema = params({
+        offset: enumSchema([-10, 0, 10]),
+      })
+      const result = schema.fromURLSearchParams('offset=-10')
+      expect(result).toEqual({ offset: -10 })
+    })
+
+    it('handles boolean const false', () => {
+      const schema = params({
+        disabled: literal(false),
+      })
+      const result = schema.fromURLSearchParams('disabled=false')
+      expect(result).toEqual({ disabled: false })
+    })
+  })
+
   describe('fromURLSearchParams', () => {
     const schema = params({
       name: string(),
@@ -271,70 +309,58 @@ describe('ParamsSchema', () => {
     })
 
     it('parses string parameters', () => {
-      const urlParams = new URLSearchParams('name=Alice')
-      const result = schema.fromURLSearchParams(urlParams)
+      const result = schema.fromURLSearchParams('name=Alice')
       expect(result).toEqual({ name: 'Alice' })
     })
 
     it('parses and coerces boolean true', () => {
-      const urlParams = new URLSearchParams('name=Alice&active=true')
-      const result = schema.fromURLSearchParams(urlParams)
+      const result = schema.fromURLSearchParams('name=Alice&active=true')
       expect(result).toEqual({ name: 'Alice', active: true })
     })
 
     it('parses and coerces boolean false', () => {
-      const urlParams = new URLSearchParams('name=Alice&active=false')
-      const result = schema.fromURLSearchParams(urlParams)
+      const result = schema.fromURLSearchParams('name=Alice&active=false')
       expect(result).toEqual({ name: 'Alice', active: false })
     })
 
     it('parses and coerces integer values', () => {
-      const urlParams = new URLSearchParams('name=Alice&age=30')
-      const result = schema.fromURLSearchParams(urlParams)
+      const result = schema.fromURLSearchParams('name=Alice&age=30')
       expect(result).toEqual({ name: 'Alice', age: 30 })
     })
 
     it('parses and coerces negative integers', () => {
-      const urlParams = new URLSearchParams('name=Alice&age=-5')
-      const result = schema.fromURLSearchParams(urlParams)
+      const result = schema.fromURLSearchParams('name=Alice&age=-5')
       expect(result).toEqual({ name: 'Alice', age: -5 })
     })
 
     it('does not coerce non-integer numbers', () => {
-      const urlParams = new URLSearchParams('name=Alice&extra=3.14')
-      const result = schema.fromURLSearchParams(urlParams)
+      const result = schema.fromURLSearchParams('name=Alice&extra=3.14')
       expect(result).toEqual({ name: 'Alice', extra: '3.14' })
     })
 
     it('keeps string values for string schema even if they look like numbers', () => {
-      const urlParams = new URLSearchParams('name=123')
-      const result = schema.fromURLSearchParams(urlParams)
+      const result = schema.fromURLSearchParams('name=123')
       expect(result).toEqual({ name: '123' })
     })
 
     it('parses multiple values as array', () => {
-      const urlParams = new URLSearchParams('name=Alice&tags=one&tags=two')
-      const result = schema.fromURLSearchParams(urlParams)
+      const result = schema.fromURLSearchParams('name=Alice&tags=one&tags=two')
       expect(result).toEqual({ name: 'Alice', tags: ['one', 'two'] })
     })
 
-    it('coerces array values correctly', () => {
-      const urlParams = new URLSearchParams('name=Alice&num=1&num=2&num=3')
-      const result = schema.fromURLSearchParams(urlParams)
-      expect(result).toEqual({ name: 'Alice', num: [1, 2, 3] })
-    })
+    it('does not coerce numeric values of unknown params', () => {
+      expect(
+        schema.fromURLSearchParams('name=Alice&num=1&num=2&num=3&foo=3'),
+      ).toEqual({ name: 'Alice', num: ['1', '2', '3'], foo: '3' })
 
-    it('handles mixed types in arrays', () => {
-      const urlParams = new URLSearchParams(
-        'name=Alice&val=true&val=123&val=text',
-      )
-      const result = schema.fromURLSearchParams(urlParams)
-      expect(result).toEqual({ name: 'Alice', val: [true, 123, 'text'] })
+      expect(
+        schema.fromURLSearchParams('name=Alice&val=true&val=123&val=text'),
+      ).toEqual({ name: 'Alice', val: ['true', '123', 'text'] })
     })
 
     it('handles empty URLSearchParams', () => {
-      const urlParams = new URLSearchParams()
-      expect(() => schema.fromURLSearchParams(urlParams)).toThrow()
+      expect(() => schema.fromURLSearchParams(new URLSearchParams())).toThrow()
+      expect(() => schema.fromURLSearchParams('')).toThrow()
     })
 
     it('handles multiple parameters', () => {
@@ -393,14 +419,19 @@ describe('ParamsSchema', () => {
           ['name', 'Alice'],
           ['bools', 'notabool'],
         ]),
-      ).toThrow('Expected boolean value type at $.bools[0] (got string)')
+      ).toThrow('Expected boolean value type at $.bools (got string)')
 
       expect(() =>
-        schema.fromURLSearchParams([
-          ['name', 'Alice'],
-          ['bools', '2'],
-        ]),
-      ).toThrow('Expected boolean value type at $.bools[0] (got integer)')
+        schema.fromURLSearchParams(
+          [
+            ['name', 'Alice'],
+            ['bools', '2'],
+          ],
+          {
+            path: ['foo', 'bar'],
+          },
+        ),
+      ).toThrow('Expected boolean value type at $.foo.bar.bools (got string)')
     })
   })
 
@@ -461,15 +492,23 @@ describe('ParamsSchema', () => {
       expect(result.toString()).toBe('name=Alice')
     })
 
+    it('rejects arrays with multiple types', () => {
+      expect(() => {
+        schema.toURLSearchParams({
+          name: 'Alice',
+          // @ts-expect-error
+          values: [1, true, 'text'],
+        })
+      }).toThrow()
+    })
+
     it('handles arrays with multiple types', () => {
       const result = schema.toURLSearchParams({
         name: 'Alice',
         // @ts-expect-error
-        values: [1, true, 'text'],
+        values: ['foo', 'bar'],
       })
-      expect(result.toString()).toBe(
-        'name=Alice&values=1&values=true&values=text',
-      )
+      expect(result.toString()).toBe('name=Alice&values=foo&values=bar')
     })
 
     it('handles undefined input', () => {
@@ -711,9 +750,9 @@ describe('paramSchema', () => {
       expect(result.success).toBe(true)
     })
 
-    it('validates arrays with mixed scalar types', () => {
+    it('rejects arrays with mixed scalar types', () => {
       const result = paramSchema.safeParse([true, 42, 'text'])
-      expect(result.success).toBe(true)
+      expect(result.success).toBe(false)
     })
 
     it('validates arrays with negative integers', () => {
@@ -884,11 +923,11 @@ describe('paramsSchema', () => {
     expect(result.success).toBe(true)
   })
 
-  it('validates object with arrays of mixed scalar types', () => {
+  it('rejects object with arrays of mixed scalar types', () => {
     const result = paramsSchema.safeParse({
       values: [true, 42, 'text'],
     })
-    expect(result.success).toBe(true)
+    expect(result.success).toBe(false)
   })
 
   it('validates object with numeric string keys', () => {