@atproto/lex-schema 0.1.5 → 0.1.6

package/src/schema/params.ts

@@ -1,371 +0,0 @@
-import { isPlainObject } from '@atproto/lex-data'
-import {
-  Infer,
-  InferInput,
-  InferOutput,
-  Issue,
-  IssueInvalidType,
-  IssueInvalidValue,
-  LexValidationError,
-  ParseOptions,
-  Schema,
-  ValidationContext,
-  Validator,
-  WithOptionalProperties,
-} from '../core.js'
-import { lazyProperty } from '../util/lazy-property.js'
-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'
-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>
-
-/**
- * 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 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 ParamsShape = ParamsShape,
-> extends Schema<
-  WithOptionalProperties<{
-    [K in keyof TShape]: InferInput<TShape[K]>
-  }>,
-  WithOptionalProperties<{
-    [K in keyof TShape]: InferOutput<TShape[K]>
-  }>
-> {
-  readonly type = 'params' as const
-
-  constructor(readonly shape: TShape) {
-    super()
-  }
-
-  get shapeValidators(): Map<string, ParamValidator> {
-    const map = new Map(Object.entries(this.shape))
-
-    return lazyProperty(this, 'shapeValidators', map)
-  }
-
-  validateInContext(input: unknown, ctx: ValidationContext) {
-    if (!isPlainObject(input)) {
-      return ctx.issueUnexpectedType(input, 'object')
-    }
-
-    // Lazily copy value
-    let copy: undefined | Record<string, unknown>
-
-    // Ensure that non-specified params conform to param schema
-    for (const key in input) {
-      if (this.shapeValidators.has(key)) continue
-
-      const result = ctx.validateChild(input, key, paramSchema)
-      if (!result.success) return result
-
-      if (result.value !== input[key]) {
-        if (ctx.options.mode === 'validate') {
-          // In "validate" mode, we can't modify the input, so we issue an error
-          return ctx.issueInvalidPropertyValue(input, key, [result.value])
-        }
-
-        copy ??= { ...input }
-        copy[key] = result.value
-      }
-    }
-
-    for (const [key, propDef] of this.shapeValidators) {
-      const result = ctx.validateChild(input, key, propDef)
-      if (!result.success) {
-        if (!(key in input)) {
-          // Transform into "required key" issue
-          return ctx.issueRequiredKey(input, key)
-        }
-
-        return result
-      }
-
-      // Skip copying if key is not present in input (and value is undefined)
-      if (result.value === undefined && !(key in input)) {
-        continue
-      }
-
-      if (!Object.is(result.value, input[key])) {
-        if (ctx.options.mode === 'validate') {
-          // In "validate" mode, we can't modify the input, so we issue an error
-          return ctx.issueInvalidPropertyValue(input, key, [result.value])
-        }
-
-        // Copy on write
-        copy ??= { ...input }
-        copy[key] = result.value
-      }
-    }
-
-    return ctx.success(copy ?? input)
-  }
-
-  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) {
-      // 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
-        ? 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[name] = [currentParam, coerced]
-      }
-    }
-
-    return this.parse(params, options)
-  }
-
-  toURLSearchParams(input: InferInput<this>): URLSearchParams {
-    const urlSearchParams = new URLSearchParams()
-
-    // @NOTE We apply defaults here to ensure that server with different
-    // defaults still receive all expected parameters.
-    const params = this.parse(input)
-
-    for (const [key, value] of Object.entries(params)) {
-      if (Array.isArray(value)) {
-        for (const v of value) {
-          urlSearchParams.append(key, String(v))
-        }
-      } else if (value !== undefined) {
-        urlSearchParams.append(key, String(value))
-      }
-    }
-
-    return urlSearchParams
-  }
-}
-
-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.
- *
- * 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 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,340 +0,0 @@
-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'
-
-describe('Payload', () => {
-  describe('basic construction', () => {
-    it('creates payload with encoding and no schema', () => {
-      const def = payload('application/json', undefined)
-      expect(def.encoding).toBe('application/json')
-      expect(def.schema).toBeUndefined()
-    })
-
-    it('creates payload with encoding and schema', () => {
-      const schema = object({
-        name: string(),
-      })
-      const def = payload('application/json', schema)
-      expect(def.encoding).toBe('application/json')
-      expect(def.schema).toBe(schema)
-    })
-
-    it('creates payload with undefined encoding and undefined schema', () => {
-      const def = payload(undefined, undefined)
-      expect(def.encoding).toBeUndefined()
-      expect(def.schema).toBeUndefined()
-    })
-
-    it('creates payload with text encoding', () => {
-      const def = payload('text/plain', undefined)
-      expect(def.encoding).toBe('text/plain')
-      expect(def.schema).toBeUndefined()
-    })
-
-    it('creates payload with text/html encoding', () => {
-      const def = payload('text/html', undefined)
-      expect(def.encoding).toBe('text/html')
-      expect(def.schema).toBeUndefined()
-    })
-
-    it('creates payload with application/octet-stream encoding', () => {
-      const def = payload('application/octet-stream', undefined)
-      expect(def.encoding).toBe('application/octet-stream')
-      expect(def.schema).toBeUndefined()
-    })
-
-    it('creates payload with image encoding', () => {
-      const def = payload('image/png', undefined)
-      expect(def.encoding).toBe('image/png')
-      expect(def.schema).toBeUndefined()
-    })
-  })
-
-  describe('encoding types', () => {
-    it('handles application/json encoding', () => {
-      const def = payload('application/json', undefined)
-      expect(def.encoding).toBe('application/json')
-    })
-
-    it('handles text/* encodings', () => {
-      const textPlain = payload('text/plain', undefined)
-      expect(textPlain.encoding).toBe('text/plain')
-
-      const textHtml = payload('text/html', undefined)
-      expect(textHtml.encoding).toBe('text/html')
-
-      const textCss = payload('text/css', undefined)
-      expect(textCss.encoding).toBe('text/css')
-    })
-
-    it('handles binary encodings', () => {
-      const octetStream = payload('application/octet-stream', undefined)
-      expect(octetStream.encoding).toBe('application/octet-stream')
-
-      const imagePng = payload('image/png', undefined)
-      expect(imagePng.encoding).toBe('image/png')
-
-      const imageJpeg = payload('image/jpeg', undefined)
-      expect(imageJpeg.encoding).toBe('image/jpeg')
-    })
-
-    it('handles custom mime types', () => {
-      const def = payload('application/vnd.custom+json', undefined)
-      expect(def.encoding).toBe('application/vnd.custom+json')
-    })
-  })
-
-  describe('with schemas', () => {
-    it('creates payload with object schema', () => {
-      const schema = object({
-        id: integer(),
-        name: string(),
-      })
-      const def = payload('application/json', schema)
-      expect(def.encoding).toBe('application/json')
-      expect(def.schema).toBe(schema)
-    })
-
-    it('creates payload with string schema', () => {
-      const schema = string()
-      const def = payload('application/json', schema)
-      expect(def.encoding).toBe('application/json')
-      expect(def.schema).toBe(schema)
-    })
-
-    it('creates payload with integer schema', () => {
-      const schema = integer()
-      const def = payload('application/json', schema)
-      expect(def.encoding).toBe('application/json')
-      expect(def.schema).toBe(schema)
-    })
-
-    it('creates payload with unknown schema', () => {
-      const schema = object({})
-      const def = payload('application/json', schema)
-      expect(def.encoding).toBe('application/json')
-      expect(def.schema).toBe(schema)
-    })
-
-    it('creates payload with complex nested schema', () => {
-      const schema = object({
-        user: object({
-          id: integer(),
-          name: string(),
-          email: string({ format: 'uri' }),
-        }),
-        metadata: object({
-          createdAt: string({ format: 'datetime' }),
-          updatedAt: string({ format: 'datetime' }),
-        }),
-      })
-      const def = payload('application/json', schema)
-      expect(def.encoding).toBe('application/json')
-      expect(def.schema).toBe(schema)
-    })
-  })
-
-  describe('validation constraints', () => {
-    it('throws error when schema is defined but encoding is undefined', () => {
-      const schema = string()
-      expect(() => {
-        // @ts-expect-error
-        payload(undefined, schema)
-      }).toThrow(TypeError)
-      expect(() => {
-        // @ts-expect-error
-        payload(undefined, schema)
-      }).toThrow('schema cannot be defined when encoding is undefined')
-    })
-
-    it('throws error when object schema is defined but encoding is undefined', () => {
-      const schema = object({
-        name: string(),
-      })
-      expect(() => {
-        // @ts-expect-error
-        payload(undefined, schema)
-      }).toThrow(TypeError)
-      expect(() => {
-        // @ts-expect-error
-        payload(undefined, schema)
-      }).toThrow('schema cannot be defined when encoding is undefined')
-    })
-
-    it('throws error when integer schema is defined but encoding is undefined', () => {
-      const schema = integer()
-      expect(() => {
-        // @ts-expect-error
-        payload(undefined, schema)
-      }).toThrow(TypeError)
-    })
-
-    it('allows undefined encoding with undefined schema', () => {
-      expect(() => {
-        payload(undefined, undefined)
-      }).not.toThrow()
-    })
-
-    it('allows defined encoding with undefined schema', () => {
-      expect(() => {
-        payload('application/json', undefined)
-      }).not.toThrow()
-    })
-
-    it('allows defined encoding with defined schema', () => {
-      const schema = string()
-      expect(() => {
-        payload('application/json', schema)
-      }).not.toThrow()
-    })
-  })
-
-  describe('property access', () => {
-    it('has accessible encoding property', () => {
-      const def = payload('application/json', undefined)
-      expect(def.encoding).toBe('application/json')
-    })
-
-    it('has accessible schema property', () => {
-      const schema = string()
-      const def = payload('application/json', schema)
-      expect(def.schema).toBe(schema)
-    })
-
-    it('encoding property is immutable in TypeScript', () => {
-      const def = payload('application/json', undefined)
-      // TypeScript enforces readonly at compile time
-      expect(def.encoding).toBe('application/json')
-    })
-
-    it('schema property is immutable in TypeScript', () => {
-      const schema = string()
-      const def = payload('application/json', schema)
-      // TypeScript enforces readonly at compile time
-      expect(def.schema).toBe(schema)
-    })
-  })
-
-  describe('usage scenarios', () => {
-    it('creates payload for JSON API response', () => {
-      const def = payload(
-        'application/json',
-        object({
-          success: string(),
-          data: lexMap(),
-        }),
-      )
-      expect(def.encoding).toBe('application/json')
-      expect(def.schema).toBeDefined()
-    })
-
-    it('creates payload for plain text response', () => {
-      const def = payload('text/plain', undefined)
-      expect(def.encoding).toBe('text/plain')
-      expect(def.schema).toBeUndefined()
-    })
-
-    it('creates payload for binary data', () => {
-      const def = payload('application/octet-stream', undefined)
-      expect(def.encoding).toBe('application/octet-stream')
-      expect(def.schema).toBeUndefined()
-    })
-
-    it('creates payload for image upload', () => {
-      const def = payload('image/jpeg', undefined)
-      expect(def.encoding).toBe('image/jpeg')
-      expect(def.schema).toBeUndefined()
-    })
-
-    it('creates payload for multipart form data', () => {
-      const def = payload('multipart/form-data', undefined)
-      expect(def.encoding).toBe('multipart/form-data')
-      expect(def.schema).toBeUndefined()
-    })
-
-    it('creates payload for URL encoded form', () => {
-      const def = payload('application/x-www-form-urlencoded', undefined)
-      expect(def.encoding).toBe('application/x-www-form-urlencoded')
-      expect(def.schema).toBeUndefined()
-    })
-
-    it('creates empty payload (no encoding, no schema)', () => {
-      const def = payload(undefined, undefined)
-      expect(def.encoding).toBeUndefined()
-      expect(def.schema).toBeUndefined()
-    })
-  })
-
-  describe('edge cases', () => {
-    it('handles encoding with charset parameter', () => {
-      const def = payload('application/json; charset=utf-8', undefined)
-      expect(def.encoding).toBe('application/json; charset=utf-8')
-    })
-
-    it('handles encoding with multiple parameters', () => {
-      const def = payload('multipart/form-data; boundary=something', undefined)
-      expect(def.encoding).toBe('multipart/form-data; boundary=something')
-    })
-
-    it('handles empty string encoding', () => {
-      const def = payload('', undefined)
-      expect(def.encoding).toBe('')
-    })
-
-    it('creates multiple payloads with same schema reference', () => {
-      const sharedSchema = object({
-        id: integer(),
-      })
-      const def1 = payload('application/json', sharedSchema)
-      const def2 = payload('application/json', sharedSchema)
-
-      expect(def1.schema).toBe(def2.schema)
-      expect(def1.schema).toBe(sharedSchema)
-    })
-
-    it('creates multiple payloads with different schemas', () => {
-      const schema1 = string()
-      const schema2 = integer()
-      const def1 = payload('application/json', schema1)
-      const def2 = payload('application/json', schema2)
-
-      expect(def1.schema).not.toBe(def2.schema)
-      expect(def1.schema).toBe(schema1)
-      expect(def2.schema).toBe(schema2)
-    })
-  })
-
-  describe('type inference scenarios', () => {
-    it('works with application/json and object schema', () => {
-      const schema = object({
-        message: string(),
-      })
-      const def = payload('application/json', schema)
-      expect(def.encoding).toBe('application/json')
-      expect(def.schema).toBe(schema)
-    })
-
-    it('works with text/* encodings expecting string bodies', () => {
-      const def1 = payload('text/plain', undefined)
-      const def2 = payload('text/html', undefined)
-      const def3 = payload('text/csv', undefined)
-
-      expect(def1.encoding).toBe('text/plain')
-      expect(def2.encoding).toBe('text/html')
-      expect(def3.encoding).toBe('text/csv')
-    })
-
-    it('works with binary encodings expecting Uint8Array bodies', () => {
-      const def1 = payload('image/png', undefined)
-      const def2 = payload('application/octet-stream', undefined)
-      const def3 = payload('video/mp4', undefined)
-
-      expect(def1.encoding).toBe('image/png')
-      expect(def2.encoding).toBe('application/octet-stream')
-      expect(def3.encoding).toBe('video/mp4')
-    })
-  })
-})