@atproto/lex-schema 0.0.12 → 0.0.13

package/src/schema/params.ts

@@ -3,8 +3,13 @@ import {
   Infer,
   InferInput,
   InferOutput,
+  Issue,
+  IssueInvalidType,
+  IssueInvalidValue,
+  ParseOptions,
   Schema,
   ValidationContext,
+  ValidationError,
   Validator,
   WithOptionalProperties,
 } from '../core.js'
@@ -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,38 @@ 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) {
+      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 +252,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 ValidationError([issue])
+}
+
+function paramPath(key: string, options?: ParseOptions) {
+  return options?.path ? [...options.path, key] : [key]
+}
+
 /**
  * Creates a params schema for URL query parameters.
  *
@@ -258,17 +345,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

@@ -22,6 +22,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 +57,8 @@ export class RecordSchema<
   $Typed<InferInput<TShape>, TType>,
   $Typed<InferOutput<TShape>, TType>
 > {
+  readonly type = 'record' as const
+
   keySchema: RecordKeySchema<TKey>
 
   constructor(
@@ -61,11 +70,9 @@ 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> {
+  isTypeOf<TValue extends { $type?: unknown }>(
+    value: TValue,
+  ): value is TypedRecord<TType, TValue> {
     return value.$type === this.$type
   }
 
@@ -75,11 +82,15 @@ export class RecordSchema<
     return this.parse($typed(input, this.$type))
   }
 
-  $isTypeOf<X extends { $type?: unknown }>(value: X) {
-    return this.isTypeOf<X>(value)
+  $isTypeOf<TValue extends { $type?: unknown }>(
+    value: TValue,
+  ): value is TypedRecord<TType, TValue> {
+    return this.isTypeOf<TValue>(value)
   }
 
-  $build(input: Omit<InferInput<this>, '$type'>) {
+  $build(
+    input: Omit<InferInput<this>, '$type'>,
+  ): $Typed<InferOutput<this>, TType> {
     return this.build(input)
   }
 

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)) {

package/src/schema/string.test.ts

@@ -1,5 +1,6 @@
-import { describe, expect, it } from 'vitest'
-import { string } from './string.js'
+import { describe, expect, expectTypeOf, it } from 'vitest'
+import { Infer, UnknownString } from '../core.js'
+import { StringSchemaOptions, string } from './string.js'
 import { token } from './token.js'
 import { withDefault } from './with-default.js'
 
@@ -610,4 +611,100 @@ describe('StringSchema', () => {
       expect(result.success).toBe(true)
     })
   })
+
+  describe('knownValues option', () => {
+    it('allows omitting knownValues at runtime', () => {
+      string<{ knownValues: ['active', 'inactive'] }>()
+
+      // @ts-expect-error format requires options to be set
+      string<{ knownValues: ['active', 'inactive']; format: 'did' }>()
+
+      // @ts-expect-error any options, besides knownValues, must be provided
+      string<{ knownValues: ['active', 'inactive']; minLength: 5 }>()
+
+      string<{
+        knownValues: ['john.doe', 'someone.else']
+        format: 'handle'
+      }>({
+        format: 'handle',
+      })
+
+      string<{
+        knownValues: ['john.doe', 'someone.else']
+      }>({
+        // Being *more* precise than the generic if fine
+        format: 'handle',
+      })
+
+      string<{
+        knownValues: ['did', 'inactive']
+        format: 'did'
+      }>({
+        // @ts-expect-error does not match format form generic constraint
+        format: 'handle',
+      })
+
+      string<{
+        knownValues: ['active', 'inactive']
+        minLength: 10
+      }>({
+        minLength: 10,
+      })
+
+      string<{
+        knownValues: ['active', 'inactive']
+        minLength: 5
+      }>({
+        // @ts-expect-error mismatch
+        minLength: 10,
+      })
+    })
+  })
+
+  it('properly types knownValues in parameters', () => {
+    const schema = string({
+      knownValues: ['active', 'inactive'],
+    })
+    type SchemaType = Infer<typeof schema>
+    expectTypeOf<{
+      foo: SchemaType
+    }>().toMatchObjectType<{
+      foo: 'active' | 'inactive' | UnknownString
+    }>()
+    expectTypeOf<{
+      foo: SchemaType
+    }>().not.toMatchObjectType<{
+      foo: string
+    }>()
+    expectTypeOf<{
+      foo: SchemaType
+    }>().not.toMatchObjectType<{
+      foo: 'active' | 'inactive'
+    }>()
+    expectTypeOf<{
+      foo: SchemaType
+    }>().not.toMatchObjectType<{
+      foo: UnknownString
+    }>()
+  })
+
+  it('type string<any>() as string', () => {
+    const schema = string<any>()
+    type SchemaType = Infer<typeof schema>
+    expectTypeOf<{
+      foo: SchemaType
+    }>().toMatchObjectType<{
+      foo: string
+    }>()
+  })
+
+  it('type string<StringSchemaOptions>({}) as string', () => {
+    const schema = string<StringSchemaOptions>({})
+    type SchemaType = Infer<typeof schema>
+    expectTypeOf<{
+      foo: SchemaType
+    }>().toMatchObjectType<{
+      foo: string
+    }>()
+  })
 })

package/src/schema/string.ts

@@ -1,11 +1,14 @@
 import { graphemeLen, ifCid, utf8Len } from '@atproto/lex-data'
 import {
   InferStringFormat,
+  Restricted,
   Schema,
   StringFormat,
+  UnknownString,
   ValidationContext,
   isStringFormat,
 } from '../core.js'
+import { IfAny } from '../util/if-any.js'
 import { memoizedOptions } from '../util/memoize.js'
 import { TokenSchema } from './token.js'
 
@@ -13,6 +16,7 @@ import { TokenSchema } from './token.js'
  * Configuration options for string schema validation.
  *
  * @property format - Expected string format (e.g., 'datetime', 'uri', 'at-uri', 'did', 'handle', 'nsid', 'cid', 'tid', 'record-key', 'at-identifier', 'language')
+ * @property knownValues - Known string literal values for type narrowing
  * @property minLength - Minimum length in UTF-8 bytes
  * @property maxLength - Maximum length in UTF-8 bytes
  * @property minGraphemes - Minimum number of grapheme clusters
@@ -20,6 +24,7 @@ import { TokenSchema } from './token.js'
  */
 export type StringSchemaOptions = {
   format?: StringFormat
+  knownValues?: readonly string[]
   minLength?: number
   maxLength?: number
   minGraphemes?: number
@@ -43,30 +48,46 @@ export type StringSchemaOptions = {
 export class StringSchema<
   const TOptions extends StringSchemaOptions = StringSchemaOptions,
 > extends Schema<
-  TOptions extends { format: infer F extends StringFormat }
-    ? InferStringFormat<F>
-    : string
+  IfAny<
+    TOptions,
+    string,
+    TOptions extends { format: infer F extends StringFormat }
+      ? InferStringFormat<F>
+      : TOptions extends { knownValues: readonly (infer V extends string)[] }
+        ? V | UnknownString
+        : string
+  >
 > {
-  constructor(readonly options?: TOptions) {
+  readonly type = 'string' as const
+
+  // @NOTE since the _string utility allows omitting knownValues when TOptions
+  // *does* include it (since it's only used for typing), we cannot type options
+  // as TOptions directly since it may not actually include knownValues at
+  // runtime, making schema.options.knownValues potentially undefined even when
+  // TOptions includes it.
+  readonly options: StringSchemaOptions
+
+  constructor(options: TOptions) {
     super()
+    this.options = options
   }
 
   validateInContext(input: unknown, ctx: ValidationContext) {
     const str = coerceToString(input)
     if (str == null) {
-      return ctx.issueInvalidType(input, 'string')
+      return ctx.issueUnexpectedType(input, 'string')
     }
 
     let lazyUtf8Len: number
 
-    const minLength = this.options?.minLength
+    const minLength = this.options.minLength
     if (minLength != null) {
       if ((lazyUtf8Len ??= utf8Len(str)) < minLength) {
         return ctx.issueTooSmall(str, 'string', minLength, lazyUtf8Len)
       }
     }
 
-    const maxLength = this.options?.maxLength
+    const maxLength = this.options.maxLength
     if (maxLength != null) {
       // Optimization: we can avoid computing the UTF-8 length if the maximum
       // possible length, in bytes, of the input JS string is smaller than the
@@ -80,7 +101,7 @@ export class StringSchema<
 
     let lazyGraphLen: number
 
-    const minGraphemes = this.options?.minGraphemes
+    const minGraphemes = this.options.minGraphemes
     if (minGraphemes != null) {
       // Optimization: avoid counting graphemes if the length check already fails
       if (str.length < minGraphemes) {
@@ -90,14 +111,14 @@ export class StringSchema<
       }
     }
 
-    const maxGraphemes = this.options?.maxGraphemes
+    const maxGraphemes = this.options.maxGraphemes
     if (maxGraphemes != null) {
       if ((lazyGraphLen ??= graphemeLen(str)) > maxGraphemes) {
         return ctx.issueTooBig(str, 'grapheme', maxGraphemes, lazyGraphLen)
       }
     }
 
-    const format = this.options?.format
+    const format = this.options.format
     if (format != null && !isStringFormat(str, format)) {
       return ctx.issueInvalidFormat(str, format)
     }
@@ -146,6 +167,32 @@ export function coerceToString(input: unknown): string | null {
   }
 }
 
+function _string(): StringSchema<NonNullable<unknown>>
+function _string<
+  // Allow calling `string<{ knownValues: [...] }>()` without passing an options
+  // object, since knownValues is only used for typing and has no runtime
+  // effect, so it can be safely omitted at runtime.
+  const TOptions extends {
+    knownValues: StringSchemaOptions['knownValues']
+  } & {
+    [K in Exclude<
+      keyof StringSchemaOptions,
+      'knownValues'
+    >]?: Restricted<`An options argument is required when using the "${K}" option`>
+  },
+>(): StringSchema<
+  IfAny<TOptions, any, { knownValues: TOptions['knownValues'] }>
+>
+function _string<const TOptions extends StringSchemaOptions>(
+  // If TOptions is explicitly provided (e.g. `string<{ ... }>({ ... })`), we
+  // allow the actual options argument to omit the "knownValues" property since
+  // it's only used for inferring the type and has no runtime effect.
+  options: TOptions | Omit<TOptions, 'knownValues'>,
+): StringSchema<TOptions>
+function _string(options: StringSchemaOptions = {}) {
+  return new StringSchema(options)
+}
+
 /**
  * Creates a string schema with optional format and length constraints.
  *
@@ -173,8 +220,4 @@ export function coerceToString(input: unknown): string | null {
  * const handleSchema = l.string({ format: 'handle', minLength: 3, maxLength: 253 })
  * ```
  */
-export const string = /*#__PURE__*/ memoizedOptions(function <
-  const O extends StringSchemaOptions = NonNullable<unknown>,
->(options?: StringSchemaOptions & O) {
-  return new StringSchema<O>(options)
-})
+export const string = /*#__PURE__*/ memoizedOptions(_string)

package/src/schema/token.ts

@@ -18,6 +18,8 @@ import { $type, NsidString, Schema, ValidationContext } from '../core.js'
 export class TokenSchema<
   const TValue extends string = string,
 > extends Schema<TValue> {
+  readonly type = 'token' as const
+
   constructor(readonly value: TValue) {
     super()
   }
@@ -34,7 +36,7 @@ export class TokenSchema<
     }
 
     if (typeof input !== 'string') {
-      return ctx.issueInvalidType(input, 'token')
+      return ctx.issueUnexpectedType(input, 'token')
     }
 
     return ctx.issueInvalidValue(input, [this.value])