@atproto/lex-schema 0.1.4 → 0.1.6

package/src/schema/discriminated-union.ts

@@ -1,196 +0,0 @@
-import { isPlainObject } from '@atproto/lex-data'
-import {
-  InferInput,
-  InferOutput,
-  Schema,
-  ValidationContext,
-  ValidationResult,
-  Validator,
-} from '../core.js'
-import { EnumSchema } from './enum.js'
-import { LiteralSchema } from './literal.js'
-import { ObjectSchema } from './object.js'
-
-/**
- * Type representing a single variant in a discriminated union.
- *
- * Must be an ObjectSchema with the discriminator property using either
- * a LiteralSchema or EnumSchema.
- *
- * @template Discriminator - The discriminator property name
- */
-export type DiscriminatedUnionVariant<Discriminator extends string = string> =
-  ObjectSchema<Record<Discriminator, EnumSchema<any> | LiteralSchema<any>>>
-
-/**
- * Type representing a non-empty tuple of discriminated union variants.
- *
- * @template TDiscriminator - The discriminator property name
- */
-export type DiscriminatedUnionVariants<TDiscriminator extends string> =
-  readonly [
-    DiscriminatedUnionVariant<TDiscriminator>,
-    ...DiscriminatedUnionVariant<TDiscriminator>[],
-  ]
-
-type DiscriminatedUnionSchemaInput<TVariants extends readonly Validator[]> =
-  TVariants extends readonly [
-    infer TValidator extends Validator,
-    ...infer TRest extends readonly Validator[],
-  ]
-    ? InferInput<TValidator> | DiscriminatedUnionSchemaInput<TRest>
-    : never
-
-type DiscriminatedUnionSchemaOutput<TVariants extends readonly Validator[]> =
-  TVariants extends readonly [
-    infer TValidator extends Validator,
-    ...infer TRest extends readonly Validator[],
-  ]
-    ? InferOutput<TValidator> | DiscriminatedUnionSchemaOutput<TRest>
-    : never
-
-/**
- * Schema for validating discriminated unions of objects.
- *
- * More efficient than regular union schemas when discriminating on a known
- * property. Looks up the correct variant schema directly based on the
- * discriminator value instead of trying each variant in sequence.
- *
- * @note There is no discriminated union in Lexicon schemas. This is a custom
- * extension to allow optimized validation of union of objects when using the
- * lex library programmatically (i.e. not code generated from a lexicon schema).
- *
- * @template TDiscriminator - The discriminator property name
- * @template TVariants - Tuple type of the variant schemas
- *
- * @example
- * ```ts
- * const schema = new DiscriminatedUnionSchema('type', [
- *   l.object({ type: l.literal('text'), content: l.string() }),
- *   l.object({ type: l.literal('image'), url: l.string() }),
- * ])
- * ```
- */
-export class DiscriminatedUnionSchema<
-  const TDiscriminator extends string,
-  const TVariants extends DiscriminatedUnionVariants<TDiscriminator>,
-> extends Schema<
-  DiscriminatedUnionSchemaInput<TVariants>,
-  DiscriminatedUnionSchemaOutput<TVariants>
-> {
-  readonly type = 'discriminatedUnion' as const
-
-  readonly variantsMap: Map<unknown, DiscriminatedUnionVariant<TDiscriminator>>
-
-  constructor(
-    readonly discriminator: TDiscriminator,
-    readonly variants: TVariants,
-  ) {
-    super()
-
-    // Although we usually try to avoid initialization work in constructors,
-    // here it is necessary to ensure that invalid discriminated throw from the
-    // place of construction, rather than later during validation.
-    this.variantsMap = buildVariantsMap(discriminator, variants)
-  }
-
-  validateInContext(input: unknown, ctx: ValidationContext) {
-    if (!isPlainObject(input)) {
-      return ctx.issueUnexpectedType(input, 'object')
-    }
-
-    const { discriminator } = this
-
-    if (!Object.hasOwn(input, discriminator)) {
-      return ctx.issueRequiredKey(input, discriminator)
-    }
-
-    const discriminatorValue = input[discriminator]
-
-    const variant = this.variantsMap.get(discriminatorValue)
-    if (variant) {
-      return ctx.validate(input, variant) as ValidationResult<
-        DiscriminatedUnionSchemaInput<TVariants>
-      >
-    }
-
-    return ctx.issueInvalidPropertyValue(input, discriminator, [
-      ...this.variantsMap.keys(),
-    ])
-  }
-}
-
-function buildVariantsMap<Discriminator extends string>(
-  discriminator: Discriminator,
-  variants: DiscriminatedUnionVariants<Discriminator>,
-) {
-  const variantsMap = new Map<
-    unknown,
-    DiscriminatedUnionVariant<Discriminator>
-  >()
-
-  for (const variant of variants) {
-    const schema = variant.shape[discriminator]
-    if (schema instanceof LiteralSchema) {
-      if (variantsMap.has(schema.value)) {
-        throw new TypeError(`Overlapping discriminator value: ${schema.value}`)
-      }
-      variantsMap.set(schema.value, variant)
-    } else if (schema instanceof EnumSchema) {
-      for (const val of schema.values) {
-        if (variantsMap.has(val)) {
-          throw new TypeError(`Overlapping discriminator value: ${val}`)
-        }
-        variantsMap.set(val, variant)
-      }
-    } else {
-      // Only enumerable discriminator schemas are supported
-
-      // Should never happen if types are used correctly
-      throw new TypeError(
-        `Discriminator schema must be a LiteralSchema or EnumSchema`,
-      )
-    }
-  }
-
-  return variantsMap
-}
-
-/**
- * Creates a discriminated union schema for efficient object type switching.
- *
- * Unlike regular `union()`, this schema uses a discriminator property to
- * directly look up the correct variant, providing O(1) validation instead
- * of trying each variant sequentially.
- *
- * @param discriminator - Property name to discriminate on
- * @param variants - Non-empty array of object schemas with the discriminator property
- * @returns A new {@link DiscriminatedUnionSchema} instance
- *
- * @example
- * ```ts
- * // Message types discriminated by 'kind'
- * const messageSchema = l.discriminatedUnion('kind', [
- *   l.object({ kind: l.literal('text'), text: l.string() }),
- *   l.object({ kind: l.literal('image'), url: l.string(), alt: l.optional(l.string()) }),
- *   l.object({ kind: l.literal('video'), url: l.string(), duration: l.integer() }),
- * ])
- *
- * // Using enums for multiple values mapping to same variant
- * const statusSchema = l.discriminatedUnion('status', [
- *   l.object({ status: l.enum(['pending', 'processing']), startedAt: l.string() }),
- *   l.object({ status: l.literal('completed'), completedAt: l.string() }),
- *   l.object({ status: l.literal('failed'), error: l.string() }),
- * ])
- * ```
- */
-/*@__NO_SIDE_EFFECTS__*/
-export function discriminatedUnion<
-  const Discriminator extends string,
-  const Options extends DiscriminatedUnionVariants<Discriminator>,
->(discriminator: Discriminator, variants: Options) {
-  return new DiscriminatedUnionSchema<Discriminator, Options>(
-    discriminator,
-    variants,
-  )
-}

package/src/schema/enum.test.ts

@@ -1,398 +0,0 @@
-import { describe, expect, it } from 'vitest'
-import { enumSchema } from './enum.js'
-import { withDefault } from './with-default.js'
-
-describe('EnumSchema', () => {
-  describe('with string values', () => {
-    const schema = enumSchema(['male', 'female', 'other'])
-
-    it('validates matching string values', () => {
-      const result = schema.safeParse('male')
-      expect(result.success).toBe(true)
-    })
-
-    it('validates all enum values', () => {
-      expect(schema.safeParse('male').success).toBe(true)
-      expect(schema.safeParse('female').success).toBe(true)
-      expect(schema.safeParse('other').success).toBe(true)
-    })
-
-    it('rejects non-matching string values', () => {
-      const result = schema.safeParse('unknown')
-      expect(result.success).toBe(false)
-    })
-
-    it('rejects null', () => {
-      const result = schema.safeParse(null)
-      expect(result.success).toBe(false)
-    })
-
-    it('rejects undefined', () => {
-      const result = schema.safeParse(undefined)
-      expect(result.success).toBe(false)
-    })
-
-    it('rejects numbers', () => {
-      const result = schema.safeParse(123)
-      expect(result.success).toBe(false)
-    })
-
-    it('rejects booleans', () => {
-      const result = schema.safeParse(true)
-      expect(result.success).toBe(false)
-    })
-
-    it('rejects objects', () => {
-      const result = schema.safeParse({ value: 'male' })
-      expect(result.success).toBe(false)
-    })
-
-    it('rejects arrays', () => {
-      const result = schema.safeParse(['male'])
-      expect(result.success).toBe(false)
-    })
-
-    it('rejects empty string when not in enum', () => {
-      const result = schema.safeParse('')
-      expect(result.success).toBe(false)
-    })
-  })
-
-  describe('with number values', () => {
-    const schema = enumSchema([1, 2, 3])
-
-    it('validates matching number values', () => {
-      const result = schema.safeParse(1)
-      expect(result.success).toBe(true)
-    })
-
-    it('validates all enum values', () => {
-      expect(schema.safeParse(1).success).toBe(true)
-      expect(schema.safeParse(2).success).toBe(true)
-      expect(schema.safeParse(3).success).toBe(true)
-    })
-
-    it('rejects non-matching number values', () => {
-      const result = schema.safeParse(4)
-      expect(result.success).toBe(false)
-    })
-
-    it('rejects string numbers', () => {
-      const result = schema.safeParse('1')
-      expect(result.success).toBe(false)
-    })
-
-    it('rejects zero when not in enum', () => {
-      const result = schema.safeParse(0)
-      expect(result.success).toBe(false)
-    })
-
-    it('rejects negative numbers when not in enum', () => {
-      const result = schema.safeParse(-1)
-      expect(result.success).toBe(false)
-    })
-  })
-
-  describe('with boolean values', () => {
-    const schema = enumSchema([true, false])
-
-    it('validates true', () => {
-      const result = schema.safeParse(true)
-      expect(result.success).toBe(true)
-    })
-
-    it('validates false', () => {
-      const result = schema.safeParse(false)
-      expect(result.success).toBe(true)
-    })
-
-    it('rejects string booleans', () => {
-      expect(schema.safeParse('true').success).toBe(false)
-      expect(schema.safeParse('false').success).toBe(false)
-    })
-
-    it('rejects number booleans', () => {
-      expect(schema.safeParse(1).success).toBe(false)
-      expect(schema.safeParse(0).success).toBe(false)
-    })
-  })
-
-  describe('with single boolean value', () => {
-    const schema = enumSchema([true])
-
-    it('validates true', () => {
-      const result = schema.safeParse(true)
-      expect(result.success).toBe(true)
-    })
-
-    it('rejects false when not in enum', () => {
-      const result = schema.safeParse(false)
-      expect(result.success).toBe(false)
-    })
-  })
-
-  describe('with null value', () => {
-    const schema = enumSchema([null, 'value'])
-
-    it('validates null', () => {
-      const result = schema.safeParse(null)
-      expect(result.success).toBe(true)
-    })
-
-    it('validates other enum values', () => {
-      const result = schema.safeParse('value')
-      expect(result.success).toBe(true)
-    })
-
-    it('rejects undefined', () => {
-      const result = schema.safeParse(undefined)
-      expect(result.success).toBe(false)
-    })
-  })
-
-  describe('with mixed type values', () => {
-    const schema = enumSchema(['string', 123, true, null])
-
-    it('validates string value', () => {
-      const result = schema.safeParse('string')
-      expect(result.success).toBe(true)
-    })
-
-    it('validates number value', () => {
-      const result = schema.safeParse(123)
-      expect(result.success).toBe(true)
-    })
-
-    it('validates boolean value', () => {
-      const result = schema.safeParse(true)
-      expect(result.success).toBe(true)
-    })
-
-    it('validates null value', () => {
-      const result = schema.safeParse(null)
-      expect(result.success).toBe(true)
-    })
-
-    it('rejects non-matching values', () => {
-      expect(schema.safeParse('other').success).toBe(false)
-      expect(schema.safeParse(456).success).toBe(false)
-      expect(schema.safeParse(false).success).toBe(false)
-      expect(schema.safeParse(undefined).success).toBe(false)
-    })
-  })
-
-  describe('with default option', () => {
-    const schema = withDefault(enumSchema(['red', 'green', 'blue']), 'red')
-
-    it('validates matching values', () => {
-      const result = schema.safeParse('green')
-      expect(result.success).toBe(true)
-    })
-
-    it('uses default when input is undefined', () => {
-      const result = schema.safeParse(undefined)
-      expect(result.success).toBe(true)
-      if (result.success) {
-        expect(result.value).toBe('red')
-      }
-    })
-
-    it('uses default when no argument is passed', () => {
-      const result = schema.safeParse(undefined)
-      expect(result.success).toBe(true)
-      if (result.success) {
-        expect(result.value).toBe('red')
-      }
-    })
-
-    it('does not use default for null', () => {
-      const result = schema.safeParse(null)
-      expect(result.success).toBe(false)
-    })
-
-    it('does not use default for invalid values', () => {
-      const result = schema.safeParse('yellow')
-      expect(result.success).toBe(false)
-    })
-
-    it('does not use default for empty string', () => {
-      const result = schema.safeParse('')
-      expect(result.success).toBe(false)
-    })
-  })
-
-  describe('with default option as number', () => {
-    const schema = withDefault(enumSchema([1, 2, 3]), 1)
-
-    it('uses default when input is undefined', () => {
-      const result = schema.safeParse(undefined)
-      expect(result.success).toBe(true)
-      if (result.success) {
-        expect(result.value).toBe(1)
-      }
-    })
-
-    it('does not use default for zero', () => {
-      const result = schema.safeParse(0)
-      expect(result.success).toBe(false)
-    })
-  })
-
-  describe('with default option as boolean', () => {
-    const schema = withDefault(enumSchema([true, false]), false)
-
-    it('uses default when input is undefined', () => {
-      const result = schema.safeParse(undefined)
-      expect(result.success).toBe(true)
-      if (result.success) {
-        expect(result.value).toBe(false)
-      }
-    })
-
-    it('validates true even when default is false', () => {
-      const result = schema.safeParse(true)
-      expect(result.success).toBe(true)
-      if (result.success) {
-        expect(result.value).toBe(true)
-      }
-    })
-  })
-
-  describe('with default option as null', () => {
-    const schema = withDefault(enumSchema([null, 'value']), null)
-
-    it('uses default when input is undefined', () => {
-      const result = schema.safeParse(undefined)
-      expect(result.success).toBe(true)
-      if (result.success) {
-        expect(result.value).toBe(null)
-      }
-    })
-
-    it('validates explicit null', () => {
-      const result = schema.safeParse(null)
-      expect(result.success).toBe(true)
-      if (result.success) {
-        expect(result.value).toBe(null)
-      }
-    })
-  })
-
-  describe('with single value', () => {
-    const schema = enumSchema(['only'])
-
-    it('validates the single value', () => {
-      const result = schema.safeParse('only')
-      expect(result.success).toBe(true)
-    })
-
-    it('rejects any other value', () => {
-      expect(schema.safeParse('other').success).toBe(false)
-      expect(schema.safeParse('').success).toBe(false)
-      expect(schema.safeParse(null).success).toBe(false)
-      expect(schema.safeParse(undefined).success).toBe(false)
-    })
-  })
-
-  describe('with empty string value', () => {
-    const schema = enumSchema(['', 'value'])
-
-    it('validates empty string', () => {
-      const result = schema.safeParse('')
-      expect(result.success).toBe(true)
-    })
-
-    it('validates other values', () => {
-      const result = schema.safeParse('value')
-      expect(result.success).toBe(true)
-    })
-
-    it('rejects non-matching values', () => {
-      const result = schema.safeParse('other')
-      expect(result.success).toBe(false)
-    })
-  })
-
-  describe('with zero value', () => {
-    const schema = enumSchema([0, 1, 2])
-
-    it('validates zero', () => {
-      const result = schema.safeParse(0)
-      expect(result.success).toBe(true)
-    })
-
-    it('validates other values', () => {
-      expect(schema.safeParse(1).success).toBe(true)
-      expect(schema.safeParse(2).success).toBe(true)
-    })
-
-    it('rejects false even though zero is in enum', () => {
-      const result = schema.safeParse(false)
-      expect(result.success).toBe(false)
-    })
-  })
-
-  describe('case sensitivity', () => {
-    const schema = enumSchema(['Value', 'VALUE', 'value'])
-
-    it('validates exact case matches', () => {
-      expect(schema.safeParse('Value').success).toBe(true)
-      expect(schema.safeParse('VALUE').success).toBe(true)
-      expect(schema.safeParse('value').success).toBe(true)
-    })
-
-    it('rejects case mismatches', () => {
-      expect(schema.safeParse('vaLue').success).toBe(false)
-      expect(schema.safeParse('VaLuE').success).toBe(false)
-    })
-  })
-
-  describe('with special string values', () => {
-    const schema = enumSchema([
-      'with space',
-      'with\ttab',
-      'with\nnewline',
-      '123',
-      'true',
-      'null',
-      'undefined',
-    ])
-
-    it('validates strings with spaces', () => {
-      const result = schema.safeParse('with space')
-      expect(result.success).toBe(true)
-    })
-
-    it('validates strings with tabs', () => {
-      const result = schema.safeParse('with\ttab')
-      expect(result.success).toBe(true)
-    })
-
-    it('validates strings with newlines', () => {
-      const result = schema.safeParse('with\nnewline')
-      expect(result.success).toBe(true)
-    })
-
-    it('validates number-like strings', () => {
-      const result = schema.safeParse('123')
-      expect(result.success).toBe(true)
-    })
-
-    it('rejects actual numbers for number-like strings', () => {
-      const result = schema.safeParse(123)
-      expect(result.success).toBe(false)
-    })
-
-    it('validates keyword strings', () => {
-      expect(schema.safeParse('true').success).toBe(true)
-      expect(schema.safeParse('null').success).toBe(true)
-      expect(schema.safeParse('undefined').success).toBe(true)
-    })
-
-    it('rejects actual boolean/null/undefined for keyword strings', () => {
-      expect(schema.safeParse(true).success).toBe(false)
-      expect(schema.safeParse(null).success).toBe(false)
-      expect(schema.safeParse(undefined).success).toBe(false)
-    })
-  })
-})

package/src/schema/enum.ts

@@ -1,77 +0,0 @@
-import { Schema, ValidationContext } from '../core.js'
-
-/**
- * Schema that accepts one of several specific literal values.
- *
- * Validates that the input matches one of the allowed values using strict
- * equality. Similar to TypeScript union of literals.
- *
- * @template TValue - The union of literal types
- *
- * @example
- * ```ts
- * const schema = new EnumSchema(['pending', 'active', 'completed'])
- * schema.validate('active')  // success
- * schema.validate('invalid') // fails
- * ```
- */
-export class EnumSchema<
-  const TValue extends null | string | number | boolean,
-> extends Schema<TValue> {
-  readonly type = 'enum' as const
-
-  constructor(readonly values: readonly TValue[]) {
-    super()
-  }
-
-  validateInContext(input: unknown, ctx: ValidationContext) {
-    if (!(this.values as readonly unknown[]).includes(input)) {
-      return ctx.issueInvalidValue(input, this.values)
-    }
-
-    return ctx.success(input as TValue)
-  }
-}
-
-/**
- * Creates an enum schema that accepts one of the specified values.
- *
- * Similar to TypeScript's union of string literals. Use `l.enum()` for
- * the namespace-friendly alias.
- *
- * @param value - Array of allowed values
- * @returns A new {@link EnumSchema} instance
- *
- * @example
- * ```ts
- * // String enum
- * const statusSchema = l.enum(['pending', 'active', 'completed', 'failed'])
- *
- * // Number enum
- * const prioritySchema = l.enum([1, 2, 3, 4, 5])
- *
- * // Mixed types
- * const mixedSchema = l.enum(['auto', 0, 1, true])
- *
- * // Use in objects
- * const taskSchema = l.object({
- *   title: l.string(),
- *   status: l.enum(['todo', 'in-progress', 'done']),
- * })
- *
- * // In discriminated unions
- * const resultSchema = l.discriminatedUnion('status', [
- *   l.object({ status: l.enum(['pending', 'processing']), progress: l.integer() }),
- *   l.object({ status: l.literal('completed'), result: l.unknown() }),
- * ])
- * ```
- */
-/*@__NO_SIDE_EFFECTS__*/
-export function enumSchema<const V extends null | string | number | boolean>(
-  value: readonly V[],
-) {
-  return new EnumSchema<V>(value)
-}
-
-// @NOTE "enum" is a reserved keyword in JS/TS
-export { enumSchema as enum }