@atproto/lex-schema 0.0.12 → 0.0.14

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,35 @@ 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)')
+    })
+
+    it('ignores empty string values', () => {
+      const result = schema.fromURLSearchParams([
+        ['name', 'Alice'],
+        ['extra', ''],
+      ])
+      expect(result).toEqual({ name: 'Alice' })
+    })
+
+    it('ignores empty string values for known parameters', () => {
+      const result = schema.fromURLSearchParams([
+        ['name', 'Alice'],
+        ['age', ''],
+      ])
+      expect(result).toEqual({ name: 'Alice' })
     })
   })
 
@@ -461,15 +508,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 +766,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 +939,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', () => {

package/src/schema/params.ts

@@ -3,6 +3,11 @@ import {
   Infer,
   InferInput,
   InferOutput,
+  Issue,
+  IssueInvalidType,
+  IssueInvalidValue,
+  LexValidationError,
+  ParseOptions,
   Schema,
   ValidationContext,
   Validator,
@@ -13,7 +18,9 @@ import { memoizedOptions } from '../util/memoize.js'
 import { ArraySchema, array } from './array.js'
 import { BooleanSchema, boolean } from './boolean.js'
 import { dict } from './dict.js'
+import { EnumSchema } from './enum.js'
 import { IntegerSchema, integer } from './integer.js'
+import { LiteralSchema } from './literal.js'
 import { OptionalSchema, optional } from './optional.js'
 import { StringSchema, string } from './string.js'
 import { union } from './union.js'
@@ -33,7 +40,12 @@ export type Param = Infer<typeof paramSchema>
 /**
  * Schema for validating individual parameter values.
  */
-export const paramSchema = union([paramScalarSchema, array(paramScalarSchema)])
+export const paramSchema = union([
+  paramScalarSchema,
+  array(boolean()),
+  array(integer()),
+  array(string()),
+])
 
 /**
  * Type for a params object with string keys and optional param values.
@@ -45,14 +57,34 @@ export type Params = Infer<typeof paramsSchema>
  */
 export const paramsSchema = dict(string(), optional(paramSchema))
 
-// @NOTE In order to properly coerce URLSearchParams, we need to distinguish
-// between scalar and array validators, requiring to be able to detect which
-// schema types are being used, restricting the allowed param validators here.
-type ParamScalarValidator = StringSchema | BooleanSchema | IntegerSchema
-type ParamValueValidator =
+export type ParamScalarValidator =
+  // @NOTE In order to properly coerce URLSearchParams, we need to distinguish
+  // between scalar and array validators, requiring to be able to detect which
+  // schema types are being used, restricting the allowed param validators here.
+  | LiteralSchema<string>
+  | LiteralSchema<number>
+  | LiteralSchema<boolean>
+  | EnumSchema<string>
+  | EnumSchema<number>
+  // | EnumSchema<boolean> // Boolean lexicon definitions don't allow "enum"
+  | StringSchema<any>
+  | BooleanSchema
+  | IntegerSchema
+
+type AsArrayParamSchema<TSchema extends Validator> =
+  // This allows to "distribute" any union of scalar validators into a union of
+  // arrays of those validators, instead of an array of union. If TSchema is
+  // BooleanSchema | IntegerSchema, we want the result to be
+  // ArraySchema<BooleanSchema> | ArraySchema<IntegerSchema>, not
+  // ArraySchema<BooleanSchema | IntegerSchema>, since the latter would allow
+  // arrays with mixed types (e.g. [true, 42]), which we don't want.
+  TSchema extends any ? ArraySchema<TSchema> : never
+
+export type ParamValueValidator =
   | ParamScalarValidator
-  | ArraySchema<ParamScalarValidator>
-type ParamValidator =
+  | AsArrayParamSchema<ParamScalarValidator>
+
+export type ParamValidator =
   | ParamValueValidator
   | OptionalSchema<ParamValueValidator>
   | OptionalSchema<WithDefaultSchema<ParamValueValidator>>
@@ -63,7 +95,7 @@ type ParamValidator =
  *
  * Maps parameter names to their validators (must be Param or undefined).
  */
-export type ParamsSchemaShape = {
+export type ParamsShape = {
   [x: string]: ParamValidator
 }
 
@@ -87,7 +119,7 @@ export type ParamsSchemaShape = {
  * ```
  */
 export class ParamsSchema<
-  const TShape extends ParamsSchemaShape = ParamsSchemaShape,
+  const TShape extends ParamsShape = ParamsShape,
 > extends Schema<
   WithOptionalProperties<{
     [K in keyof TShape]: InferInput<TShape[K]>
@@ -96,6 +128,8 @@ export class ParamsSchema<
     [K in keyof TShape]: InferOutput<TShape[K]>
   }>
 > {
+  readonly type = 'params' as const
+
   constructor(readonly shape: TShape) {
     super()
   }
@@ -108,7 +142,7 @@ export class ParamsSchema<
 
   validateInContext(input: unknown, ctx: ValidationContext) {
     if (!isPlainObject(input)) {
-      return ctx.issueInvalidType(input, 'object')
+      return ctx.issueUnexpectedType(input, 'object')
     }
 
     // Lazily copy value
@@ -163,42 +197,41 @@ export class ParamsSchema<
     return ctx.success(copy ?? input)
   }
 
-  fromURLSearchParams(iterable: Iterable<[string, string]>): InferOutput<this> {
-    const params: Record<string, Param> = {}
+  fromURLSearchParams(
+    input: string | Iterable<[string, string]>,
+    options?: ParseOptions,
+  ): InferOutput<this> {
+    const params: Record<string, unknown> = {}
 
-    // Compatibility with URLSearchParams not being iterable in some environments
+    const iterable =
+      typeof input === 'string' ? new URLSearchParams(input) : input
     const entries =
       iterable instanceof URLSearchParams ? iterable.entries() : iterable
 
-    for (const [key, value] of entries) {
-      const validator = unwrapValidator(this.shapeValidators.get(key))
-      const expectsArray = validator instanceof ArraySchema
+    for (const [name, value] of entries) {
+      // Ignore empty strings
+      if (!value) continue
+
+      const validator = this.shapeValidators.get(name)
+      const innerValidator = validator ? unwrapSchema(validator) : undefined
+      const expectsArray = innerValidator instanceof ArraySchema
       const scalarValidator = expectsArray
-        ? unwrapValidator(validator.validator)
-        : validator
-
-      const coerced: ParamScalar =
-        scalarValidator instanceof StringSchema
-          ? value
-          : value === 'true'
-            ? true
-            : value === 'false'
-              ? false
-              : /^-?\d+$/.test(value)
-                ? Number(value)
-                : value
-
-      const currentParam = params[key]
+        ? unwrapSchema(innerValidator.validator)
+        : innerValidator
+
+      const coerced = coerceParam(name, value, scalarValidator, options)
+
+      const currentParam = params[name]
       if (currentParam === undefined) {
-        params[key] = expectsArray ? [coerced] : coerced
+        params[name] = expectsArray ? [coerced] : coerced
       } else if (Array.isArray(currentParam)) {
         currentParam.push(coerced)
       } else {
-        params[key] = [currentParam, coerced]
+        params[name] = [currentParam, coerced]
       }
     }
 
-    return this.parse(params)
+    return this.parse(params, options)
   }
 
   toURLSearchParams(input: InferInput<this>): URLSearchParams {
@@ -222,6 +255,63 @@ export class ParamsSchema<
   }
 }
 
+function coerceParam(
+  name: string,
+  param: string,
+  schema?: ParamScalarValidator,
+  options?: ParseOptions,
+): ParamScalar {
+  let issue: Issue
+
+  if (!schema) {
+    // The param is unknown (not defined in schema), so we don't apply any
+    // coercion and just return the string value.
+    return param
+  } else if (schema instanceof StringSchema) {
+    return param
+  } else if (schema instanceof IntegerSchema) {
+    if (/^-?\d+$/.test(param)) return Number(param)
+    issue = new IssueInvalidType(paramPath(name, options), param, ['integer'])
+  } else if (schema instanceof BooleanSchema) {
+    if (param === 'true') return true
+    if (param === 'false') return false
+    issue = new IssueInvalidType(paramPath(name, options), param, ['boolean'])
+  } else if (schema instanceof LiteralSchema) {
+    const { value } = schema
+    if (String(value) === param) return value
+    issue = new IssueInvalidValue(paramPath(name, options), param, [value])
+  } else if (schema instanceof EnumSchema) {
+    const { values } = schema
+    for (const value of values) {
+      if (String(value) === param) return value
+    }
+    issue = new IssueInvalidValue(paramPath(name, options), param, values)
+  } else {
+    // This should never happen. If it *does*, it means that the user of
+    // lex-schema is mixing different versions of the lib, which is not
+    // supported. Throwing an error here is better than silently accepting
+    // invalid params and causing unexpected behavior down the line (ie. error
+    // message returning the string value instead of the expected
+    // boolean/number/string value).
+    throw new Error(`Unsupported schema type for param coercion: ${schema}`)
+  }
+
+  // We were not able to coerce the param to the expected type. There is no
+  // point in returning the original string value since it doesn't conform to
+  // the expected schema, so we throw a validation error instead. We could
+  // return the "param" here, which would cause the validation to fail later on
+  // (see fromURLSearchParams()'s return statement). The main benefit of
+  // returning the original "param" value is that the error path would include
+  // the index of the param in case of array params (e.g. "tags[1]"), which
+  // could be helpful for debugging. The cost overhead is not worth it though
+  // (IMO).
+  throw new LexValidationError([issue])
+}
+
+function paramPath(key: string, options?: ParseOptions) {
+  return options?.path ? [...options.path, key] : [key]
+}
+
 /**
  * Creates a params schema for URL query parameters.
  *
@@ -258,17 +348,24 @@ export class ParamsSchema<
  * ```
  */
 export const params = /*#__PURE__*/ memoizedOptions(function params<
-  const TShape extends ParamsSchemaShape = NonNullable<unknown>,
+  const TShape extends ParamsShape = NonNullable<unknown>,
 >(properties: TShape = {} as TShape) {
   return new ParamsSchema<TShape>(properties)
 })
 
-function unwrapValidator(schema?: Validator): Validator | undefined {
+type UnwrapSchema<S extends Validator> =
+  S extends OptionalSchema<infer U>
+    ? UnwrapSchema<U>
+    : S extends WithDefaultSchema<infer U>
+      ? UnwrapSchema<U>
+      : S
+
+function unwrapSchema<S extends Validator>(schema: S): UnwrapSchema<S> {
   while (
     schema instanceof OptionalSchema ||
     schema instanceof WithDefaultSchema
   ) {
-    schema = schema.validator
+    return unwrapSchema(schema.validator)
   }
-  return schema
+  return schema as UnwrapSchema<S>
 }

package/src/schema/payload.test.ts

@@ -1,9 +1,9 @@
 import { describe, expect, it } from 'vitest'
 import { integer } from './integer.js'
+import { lexMap } from './lex-map.js'
 import { object } from './object.js'
 import { payload } from './payload.js'
 import { string } from './string.js'
-import { unknownObject } from './unknown-object.js'
 
 describe('Payload', () => {
   describe('basic construction', () => {
@@ -224,7 +224,7 @@ describe('Payload', () => {
         'application/json',
         object({
           success: string(),
-          data: unknownObject(),
+          data: lexMap(),
         }),
       )
       expect(def.encoding).toBe('application/json')

package/src/schema/payload.ts

@@ -107,15 +107,13 @@ export class Payload<
    * encoding.
    */
   matchesEncoding(contentType: string | undefined): boolean {
-    const mime = contentType?.split(';', 1)[0].trim()
-
     const { encoding } = this
 
     // Handle undefined cases
     if (encoding === undefined) {
       // Expecting no body
-      return mime === undefined
-    } else if (mime === undefined) {
+      return contentType == null
+    } else if (contentType == null) {
       // Expecting a body, but got no content-type
       return false
     }
@@ -124,6 +122,7 @@ export class Payload<
       return true
     }
 
+    const mime = contentType?.split(';', 1)[0].trim()
     if (encoding.endsWith('/*')) {
       return mime.startsWith(encoding.slice(0, -1))
     }

package/src/schema/record.ts

@@ -11,6 +11,7 @@ import {
   ValidationContext,
   Validator,
 } from '../core.js'
+import { lazyProperty } from '../util/lazy-property.js'
 import { literal } from './literal.js'
 import { string } from './string.js'
 
@@ -22,6 +23,13 @@ import { string } from './string.js'
 export type InferRecordKey<R extends RecordSchema> =
   R extends RecordSchema<infer TKey> ? RecordKeySchemaOutput<TKey> : never
 
+export type TypedRecord<
+  TType extends NsidString,
+  TValue extends { $type?: unknown } = { $type?: unknown },
+> = TValue extends { $type: TType }
+  ? TValue
+  : $Typed<Exclude<TValue, Unknown$TypedObject>, TType>
+
 /**
  * Schema for AT Protocol records with a type identifier and key constraints.
  *
@@ -50,6 +58,8 @@ export class RecordSchema<
   $Typed<InferInput<TShape>, TType>,
   $Typed<InferOutput<TShape>, TType>
 > {
+  readonly type = 'record' as const
+
   keySchema: RecordKeySchema<TKey>
 
   constructor(
@@ -61,28 +71,6 @@ export class RecordSchema<
     this.keySchema = recordKey(key)
   }
 
-  isTypeOf<X extends { $type?: unknown }>(
-    value: X,
-  ): value is X extends { $type: TType }
-    ? X
-    : $Typed<Exclude<X, Unknown$TypedObject>, TType> {
-    return value.$type === this.$type
-  }
-
-  build(
-    input: Omit<InferInput<this>, '$type'>,
-  ): $Typed<InferOutput<this>, TType> {
-    return this.parse($typed(input, this.$type))
-  }
-
-  $isTypeOf<X extends { $type?: unknown }>(value: X) {
-    return this.isTypeOf<X>(value)
-  }
-
-  $build(input: Omit<InferInput<this>, '$type'>) {
-    return this.build(input)
-  }
-
   validateInContext(input: unknown, ctx: ValidationContext) {
     const result = ctx.validate(input, this.schema)
 
@@ -96,6 +84,34 @@ export class RecordSchema<
 
     return result
   }
+
+  build(
+    input: Omit<InferInput<this>, '$type'>,
+  ): $Typed<InferOutput<this>, TType> {
+    return this.parse($typed(input, this.$type))
+  }
+
+  isTypeOf<TValue extends { $type?: unknown }>(
+    value: TValue,
+  ): value is TypedRecord<TType, TValue> {
+    return value.$type === this.$type
+  }
+
+  /**
+   * Bound alias for {@link build} for compatibility with generated utilities.
+   * @see {@link build}
+   */
+  get $build(): typeof this.build {
+    return lazyProperty(this, '$build', this.build.bind(this))
+  }
+
+  /**
+   * Bound alias for {@link isTypeOf} for compatibility with generated utilities.
+   * @see {@link isTypeOf}
+   */
+  get $isTypeOf(): typeof this.isTypeOf {
+    return lazyProperty(this, '$isTypeOf', this.isTypeOf.bind(this))
+  }
 }
 
 export type RecordKeySchemaOutput<Key extends LexiconRecordKey> =

package/src/schema/ref.ts

@@ -39,6 +39,8 @@ export class RefSchema<const TValidator extends Validator>
   >
   implements WrappedValidator<TValidator>
 {
+  readonly type = 'ref' as const
+
   #getter: RefSchemaGetter<TValidator>
 
   constructor(getter: RefSchemaGetter<TValidator>) {

package/src/schema/regexp.ts

@@ -18,13 +18,15 @@ import { Schema, ValidationContext } from '../core.js'
 export class RegexpSchema<
   TValue extends string = string,
 > extends Schema<TValue> {
+  readonly type = 'regexp' as const
+
   constructor(public readonly pattern: RegExp) {
     super()
   }
 
   validateInContext(input: unknown, ctx: ValidationContext) {
     if (typeof input !== 'string') {
-      return ctx.issueInvalidType(input, 'string')
+      return ctx.issueUnexpectedType(input, 'string')
     }
 
     if (!this.pattern.test(input)) {