@atproto/lex-schema 0.0.11 → 0.0.13

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,78 +262,105 @@ 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(),
       age: optional(integer()),
       active: optional(boolean()),
+      tags: optional(array(string())),
+      ids: optional(array(integer())),
+      bools: optional(array(boolean())),
     })
 
     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&tag=one&tag=two')
-      const result = schema.fromURLSearchParams(urlParams)
-      expect(result).toEqual({ name: 'Alice', tag: ['one', 'two'] })
+      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', () => {
@@ -346,6 +375,64 @@ describe('ParamsSchema', () => {
         extra: 'value',
       })
     })
+
+    it('coerces single values into arrays in parse mode', () => {
+      expect(
+        schema.fromURLSearchParams([
+          ['name', 'Alice'],
+          ['tags', 'tag1'],
+        ]),
+      ).toEqual({ name: 'Alice', tags: ['tag1'] })
+
+      expect(
+        schema.fromURLSearchParams([
+          ['name', 'Alice'],
+          ['tags', 'true'],
+        ]),
+      ).toEqual({ name: 'Alice', tags: ['true'] })
+
+      expect(
+        schema.fromURLSearchParams([
+          ['name', 'Alice'],
+          ['tags', '1'],
+        ]),
+      ).toEqual({ name: 'Alice', tags: ['1'] })
+    })
+
+    it('coerces single boolean values into arrays in parse mode', () => {
+      expect(
+        schema.fromURLSearchParams([
+          ['name', 'Alice'],
+          ['bools', 'true'],
+        ]),
+      ).toEqual({ name: 'Alice', bools: [true] })
+
+      expect(
+        schema.fromURLSearchParams([
+          ['name', 'Alice'],
+          ['bools', 'false'],
+        ]),
+      ).toEqual({ name: 'Alice', bools: [false] })
+
+      expect(() =>
+        schema.fromURLSearchParams([
+          ['name', 'Alice'],
+          ['bools', 'notabool'],
+        ]),
+      ).toThrow('Expected boolean value type at $.bools (got string)')
+
+      expect(() =>
+        schema.fromURLSearchParams(
+          [
+            ['name', 'Alice'],
+            ['bools', '2'],
+          ],
+          {
+            path: ['foo', 'bar'],
+          },
+        ),
+      ).toThrow('Expected boolean value type at $.foo.bar.bools (got string)')
+    })
   })
 
   describe('toURLSearchParams', () => {
@@ -405,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', () => {
@@ -655,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', () => {
@@ -828,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', () => {

package/src/schema/params.ts

@@ -3,38 +3,123 @@ import {
   Infer,
   InferInput,
   InferOutput,
+  Issue,
+  IssueInvalidType,
+  IssueInvalidValue,
+  ParseOptions,
   Schema,
   ValidationContext,
+  ValidationError,
   Validator,
   WithOptionalProperties,
 } from '../core.js'
 import { lazyProperty } from '../util/lazy-property.js'
 import { memoizedOptions } from '../util/memoize.js'
-import { array } from './array.js'
-import { boolean } from './boolean.js'
+import { ArraySchema, array } from './array.js'
+import { BooleanSchema, boolean } from './boolean.js'
 import { dict } from './dict.js'
-import { integer } from './integer.js'
-import { optional } from './optional.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'
+import { WithDefaultSchema } from './with-default.js'
 
+/**
+ * Scalar types allowed in URL parameters: boolean, integer, or string.
+ */
 export type ParamScalar = Infer<typeof paramScalarSchema>
 const paramScalarSchema = union([boolean(), integer(), string()])
 
+/**
+ * A single parameter value: scalar or array of scalars.
+ */
 export type Param = Infer<typeof paramSchema>
-export const paramSchema = union([paramScalarSchema, array(paramScalarSchema)])
 
+/**
+ * Schema for validating individual parameter values.
+ */
+export const paramSchema = union([
+  paramScalarSchema,
+  array(boolean()),
+  array(integer()),
+  array(string()),
+])
+
+/**
+ * Type for a params object with string keys and optional param values.
+ */
 export type Params = Infer<typeof paramsSchema>
+
+/**
+ * Schema for validating arbitrary params objects.
+ */
 export const paramsSchema = dict(string(), optional(paramSchema))
 
-export type ParamsSchemaShape = {
-  [x: string]: Validator<Param | undefined>
+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
+  | AsArrayParamSchema<ParamScalarValidator>
+
+export type ParamValidator =
+  | ParamValueValidator
+  | OptionalSchema<ParamValueValidator>
+  | OptionalSchema<WithDefaultSchema<ParamValueValidator>>
+  | WithDefaultSchema<ParamValueValidator>
+
+/**
+ * Type representing the shape of a params schema definition.
+ *
+ * Maps parameter names to their validators (must be Param or undefined).
+ */
+export type ParamsShape = {
+  [x: string]: ParamValidator
 }
 
+/**
+ * Schema for validating URL query parameters in Lexicon endpoints.
+ *
+ * Params are the query string parameters passed to queries, procedures,
+ * and subscriptions. Values must be scalars (boolean, integer, string)
+ * or arrays of scalars, as they need to be serializable to URL format.
+ *
+ * Provides methods for converting to/from URLSearchParams.
+ *
+ * @template TShape - The params shape type mapping names to validators
+ *
+ * @example
+ * ```ts
+ * const schema = new ParamsSchema({
+ *   limit: l.optional(l.integer({ minimum: 1, maximum: 100 })),
+ *   cursor: l.optional(l.string()),
+ * })
+ * ```
+ */
 export class ParamsSchema<
-  const TShape extends ParamsSchemaShape = {
-    [x: string]: Validator<Param | undefined>
-  },
+  const TShape extends ParamsShape = ParamsShape,
 > extends Schema<
   WithOptionalProperties<{
     [K in keyof TShape]: InferInput<TShape[K]>
@@ -43,20 +128,21 @@ export class ParamsSchema<
     [K in keyof TShape]: InferOutput<TShape[K]>
   }>
 > {
+  readonly type = 'params' as const
+
   constructor(readonly shape: TShape) {
     super()
   }
 
-  get shapeValidators(): Map<string, Validator<Param | undefined>> {
+  get shapeValidators(): Map<string, ParamValidator> {
     const map = new Map(Object.entries(this.shape))
 
     return lazyProperty(this, 'shapeValidators', map)
   }
 
   validateInContext(input: unknown, ctx: ValidationContext) {
-    // @TODO BETTER SUPPORT Input/Output
     if (!isPlainObject(input)) {
-      return ctx.issueInvalidType(input, 'object')
+      return ctx.issueUnexpectedType(input, 'object')
     }
 
     // Lazily copy value
@@ -111,33 +197,38 @@ export class ParamsSchema<
     return ctx.success(copy ?? input)
   }
 
-  fromURLSearchParams(urlSearchParams: URLSearchParams): InferOutput<this> {
-    const params: Record<string, Param> = {}
-
-    for (const [key, value] of urlSearchParams.entries()) {
-      const validator = this.shapeValidators.get(key)
-
-      const coerced: ParamScalar =
-        validator instanceof StringSchema
-          ? value
-          : value === 'true'
-            ? true
-            : value === 'false'
-              ? false
-              : /^-?\d+$/.test(value)
-                ? Number(value)
-                : value
-
-      if (params[key] === undefined) {
-        params[key] = coerced
-      } else if (Array.isArray(params[key])) {
-        params[key].push(coerced)
+  fromURLSearchParams(
+    input: string | Iterable<[string, string]>,
+    options?: ParseOptions,
+  ): InferOutput<this> {
+    const params: Record<string, unknown> = {}
+
+    const iterable =
+      typeof input === 'string' ? new URLSearchParams(input) : input
+    const entries =
+      iterable instanceof URLSearchParams ? iterable.entries() : iterable
+
+    for (const [name, value] of entries) {
+      const validator = this.shapeValidators.get(name)
+      const innerValidator = validator ? unwrapSchema(validator) : undefined
+      const expectsArray = innerValidator instanceof ArraySchema
+      const scalarValidator = expectsArray
+        ? unwrapSchema(innerValidator.validator)
+        : innerValidator
+
+      const coerced = coerceParam(name, value, scalarValidator, options)
+
+      const currentParam = params[name]
+      if (currentParam === undefined) {
+        params[name] = expectsArray ? [coerced] : coerced
+      } else if (Array.isArray(currentParam)) {
+        currentParam.push(coerced)
       } else {
-        params[key] = [params[key] as ParamScalar, coerced]
+        params[name] = [currentParam, coerced]
       }
     }
 
-    return this.parse(params)
+    return this.parse(params, options)
   }
 
   toURLSearchParams(input: InferInput<this>): URLSearchParams {
@@ -161,8 +252,117 @@ 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 ValidationError([issue])
+}
+
+function paramPath(key: string, options?: ParseOptions) {
+  return options?.path ? [...options.path, key] : [key]
+}
+
+/**
+ * Creates a params schema for URL query parameters.
+ *
+ * Params schemas validate query string parameters for Lexicon endpoints.
+ * Values must be boolean, integer, string, or arrays of those types.
+ *
+ * @param properties - Object mapping parameter names to their validators
+ * @returns A new {@link ParamsSchema} instance
+ *
+ * @example
+ * ```ts
+ * // Simple pagination params
+ * const paginationParams = l.params({
+ *   limit: l.optional(l.withDefault(l.integer({ minimum: 1, maximum: 100 }), 50)),
+ *   cursor: l.optional(l.string()),
+ * })
+ *
+ * // Required parameter
+ * const actorParams = l.params({
+ *   actor: l.string({ format: 'at-identifier' }),
+ * })
+ *
+ * // Array parameter (multiple values)
+ * const filterParams = l.params({
+ *   tags: l.optional(l.array(l.string())),
+ * })
+ *
+ * // Convert from URL
+ * const urlParams = new URLSearchParams('limit=25&cursor=abc')
+ * const validated = paginationParams.fromURLSearchParams(urlParams)
+ *
+ * // Convert to URL
+ * const searchParams = paginationParams.toURLSearchParams({ limit: 25 })
+ * ```
+ */
 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)
 })
+
+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
+  ) {
+    return unwrapSchema(schema.validator)
+  }
+  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 { unknown } from './unknown.js'
 
 describe('Payload', () => {
   describe('basic construction', () => {
@@ -113,7 +113,7 @@ describe('Payload', () => {
     })
 
     it('creates payload with unknown schema', () => {
-      const schema = unknown()
+      const schema = object({})
       const def = payload('application/json', schema)
       expect(def.encoding).toBe('application/json')
       expect(def.schema).toBe(schema)
@@ -224,7 +224,7 @@ describe('Payload', () => {
         'application/json',
         object({
           success: string(),
-          data: unknown(),
+          data: lexMap(),
         }),
       )
       expect(def.encoding).toBe('application/json')