@atproto/lex-schema 0.0.12 → 0.0.14

package/src/schema/boolean.ts

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

package/src/schema/bytes.ts

@@ -26,6 +26,8 @@ export type BytesSchemaOptions = {
  * ```
  */
 export class BytesSchema extends Schema<Uint8Array> {
+  readonly type = 'bytes' as const
+
   constructor(readonly options: BytesSchemaOptions = {}) {
     super()
   }
@@ -35,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

package/src/schema/cid.ts

@@ -29,13 +29,15 @@ export type CidSchemaOptions = CheckCidOptions
 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)

package/src/schema/custom.ts

@@ -46,6 +46,8 @@ export type CustomAssertion<TValue> = (
  * ```
  */
 export class CustomSchema<out TValue = unknown> extends Schema<TValue> {
+  readonly type = 'custom' as const
+
   constructor(
     private readonly assertion: CustomAssertion<TValue>,
     private readonly message: string,

package/src/schema/dict.ts

@@ -34,6 +34,8 @@ export class DictSchema<
   Record<InferInput<TKey>, InferInput<TValue>>,
   Record<InferInput<TKey>, InferOutput<TValue>>
 > {
+  readonly type = 'dict' as const
+
   constructor(
     readonly keySchema: TKey,
     readonly valueSchema: TValue,
@@ -47,7 +49,7 @@ export class DictSchema<
     options?: { ignoredKeys?: { has(k: string): boolean } },
   ) {
     if (!isPlainObject(input)) {
-      return ctx.issueInvalidType(input, 'dict')
+      return ctx.issueUnexpectedType(input, 'dict')
     }
 
     let copy: undefined | Record<string, unknown>

package/src/schema/discriminated-union.ts

@@ -78,6 +78,8 @@ export class DiscriminatedUnionSchema<
   DiscriminatedUnionSchemaInput<TVariants>,
   DiscriminatedUnionSchemaOutput<TVariants>
 > {
+  readonly type = 'discriminatedUnion' as const
+
   readonly variantsMap: Map<unknown, DiscriminatedUnionVariant<TDiscriminator>>
 
   constructor(
@@ -94,7 +96,7 @@ export class DiscriminatedUnionSchema<
 
   validateInContext(input: unknown, ctx: ValidationContext) {
     if (!isPlainObject(input)) {
-      return ctx.issueInvalidType(input, 'object')
+      return ctx.issueUnexpectedType(input, 'object')
     }
 
     const { discriminator } = this

package/src/schema/enum.ts

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

package/src/schema/integer.ts

@@ -25,13 +25,15 @@ export type IntegerSchemaOptions = {
  * ```
  */
 export class IntegerSchema extends Schema<number> {
+  readonly type = 'integer' as const
+
   constructor(readonly options?: IntegerSchemaOptions) {
     super()
   }
 
   validateInContext(input: unknown, ctx: ValidationContext) {
     if (!isInteger(input)) {
-      return ctx.issueInvalidType(input, 'integer')
+      return ctx.issueUnexpectedType(input, 'integer')
     }
 
     if (this.options?.minimum != null && input < this.options.minimum) {

package/src/schema/intersection.ts

@@ -56,6 +56,8 @@ export class IntersectionSchema<
   Simplify<Intersect<InferInput<Left>, InferInput<Right>>>,
   Simplify<Intersect<InferOutput<Left>, InferOutput<Right>>>
 > {
+  readonly type = 'intersection' as const
+
   constructor(
     protected readonly left: Left,
     protected readonly right: Right,

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()
   }