@atproto/lex-schema 0.0.0

package/src/schema/bytes.ts

@@ -0,0 +1,38 @@
+import { asUint8Array } from '@atproto/lex-data'
+import { ValidationResult, Validator, ValidatorContext } from '../validation.js'
+
+export type BytesSchemaOptions = {
+  minLength?: number
+  maxLength?: number
+}
+
+export class BytesSchema extends Validator<Uint8Array> {
+  readonly lexiconType = 'bytes' as const
+
+  constructor(readonly options: BytesSchemaOptions) {
+    super()
+  }
+
+  override validateInContext(
+    input: unknown,
+    ctx: ValidatorContext,
+  ): ValidationResult<Uint8Array> {
+    // Coerce different binary formats into Uint8Array
+    const bytes = asUint8Array(input)
+    if (!bytes) {
+      return ctx.issueInvalidType(input, 'bytes')
+    }
+
+    const { minLength } = this.options
+    if (minLength != null && bytes.length < minLength) {
+      return ctx.issueTooSmall(bytes, 'bytes', minLength, bytes.length)
+    }
+
+    const { maxLength } = this.options
+    if (maxLength != null && bytes.length > maxLength) {
+      return ctx.issueTooBig(bytes, 'bytes', maxLength, bytes.length)
+    }
+
+    return ctx.success(bytes)
+  }
+}

package/src/schema/cid.ts

@@ -0,0 +1,27 @@
+import { CID, isCid } from '@atproto/lex-data'
+import { ValidationResult, Validator, ValidatorContext } from '../validation.js'
+
+export { CID }
+
+export type CidSchemaOptions = {
+  strict?: boolean
+}
+
+export class CidSchema extends Validator<CID> {
+  readonly lexiconType = 'cid-link' as const
+
+  constructor(readonly options: CidSchemaOptions = {}) {
+    super()
+  }
+
+  override validateInContext(
+    input: unknown,
+    ctx: ValidatorContext,
+  ): ValidationResult<CID> {
+    if (!isCid(input, this.options)) {
+      return ctx.issueInvalidType(input, 'cid')
+    }
+
+    return ctx.success(input)
+  }
+}

package/src/schema/custom.ts

@@ -0,0 +1,36 @@
+import { PropertyKey } from '../validation/property-key.js'
+import {
+  ContextualIssue,
+  ValidationResult,
+  Validator,
+  ValidatorContext,
+} from '../validation/validator.js'
+
+export type CustomAssertionContext = {
+  path: PropertyKey[]
+  addIssue(issue: ContextualIssue): void
+}
+
+export type CustomAssertion<T = any> = (
+  this: null,
+  input: unknown,
+  ctx: CustomAssertionContext,
+) => input is T
+
+export class CustomSchema<T = unknown> extends Validator<T> {
+  constructor(
+    private readonly assertion: CustomAssertion<T>,
+    private readonly message: string,
+    private readonly path?: PropertyKey | readonly PropertyKey[],
+  ) {
+    super()
+  }
+
+  override validateInContext(
+    input: unknown,
+    ctx: ValidatorContext,
+  ): ValidationResult<T> {
+    if (this.assertion.call(null, input, ctx)) return ctx.success(input as T)
+    return ctx.custom(input, this.message, this.path)
+  }
+}

package/src/schema/dict.ts

@@ -0,0 +1,69 @@
+import { isPlainObject } from '@atproto/lex-data'
+import {
+  Infer,
+  ValidationResult,
+  Validator,
+  ValidatorContext,
+} from '../validation.js'
+
+export type DictSchemaOutput<
+  KeySchema extends Validator,
+  ValueSchema extends Validator,
+> =
+  Infer<KeySchema> extends never
+    ? Record<string, never>
+    : Record<Infer<KeySchema> & string, Infer<ValueSchema>>
+
+/**
+ * @note There is no dictionary in Lexicon schemas. This is a custom extension
+ * to allow map-like objects when using the lex library programmatically (i.e.
+ * not code generated from a lexicon schema).
+ */
+export class DictSchema<
+  const KeySchema extends Validator = any,
+  const ValueSchema extends Validator = any,
+> extends Validator<DictSchemaOutput<KeySchema, ValueSchema>> {
+  constructor(
+    readonly keySchema: KeySchema,
+    readonly valueSchema: ValueSchema,
+  ) {
+    super()
+  }
+
+  override validateInContext(
+    input: unknown,
+    ctx: ValidatorContext,
+    options?: { ignoredKeys?: { has(k: string): boolean } },
+  ): ValidationResult<DictSchemaOutput<KeySchema, ValueSchema>> {
+    if (!isPlainObject(input)) {
+      return ctx.issueInvalidType(input, 'dict')
+    }
+
+    let copy: undefined | Record<string, unknown>
+
+    for (const key in input) {
+      if (options?.ignoredKeys?.has(key)) continue
+
+      const keyResult = ctx.validate(key, this.keySchema)
+      if (!keyResult.success) return keyResult
+      if (keyResult.value !== key) {
+        // We can't safely "move" the key to a different name in the output
+        // object (because there may already be something there), so we issue a
+        // "required key" error if the key validation changes the key
+        return ctx.issueRequiredKey(input, key)
+      }
+
+      const valueResult = ctx.validateChild(input, key, this.valueSchema)
+      if (!valueResult.success) return valueResult
+
+      if (valueResult.value !== input[key]) {
+        copy ??= { ...input }
+        copy[key] = valueResult.value
+      }
+    }
+
+    return ctx.success(
+      (copy ?? input) as DictSchemaOutput<KeySchema, ValueSchema>,
+    )
+  }
+}

package/src/schema/discriminated-union.ts

@@ -0,0 +1,144 @@
+import { isPlainObject } from '@atproto/lex-data'
+import { ArrayContaining } from '../core.js'
+import {
+  ValidationError,
+  ValidationFailure,
+  ValidationResult,
+  Validator,
+  ValidatorContext,
+} from '../validation.js'
+import { EnumSchema } from './enum.js'
+import { LiteralSchema } from './literal.js'
+import { ObjectSchema } from './object.js'
+
+export type DiscriminatedUnionSchemaVariant<Discriminator extends string> =
+  ObjectSchema<
+    { [_ in Discriminator]: Validator },
+    { required: ArrayContaining<Discriminator, string> }
+  >
+
+export type DiscriminatedUnionSchemaVariants<Discriminator extends string> =
+  readonly [
+    DiscriminatedUnionSchemaVariant<Discriminator>,
+    ...DiscriminatedUnionSchemaVariant<Discriminator>[],
+  ]
+
+export type DiscriminatedUnionSchemaOutput<
+  Options extends readonly Validator[],
+> = Options extends readonly [Validator<infer V>]
+  ? V
+  : Options extends readonly [
+        Validator<infer V>,
+        ...infer Rest extends Validator[],
+      ]
+    ? V | DiscriminatedUnionSchemaOutput<Rest>
+    : never
+
+/**
+ * @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).
+ */
+export class DiscriminatedUnionSchema<
+  const Discriminator extends string = any,
+  const Options extends DiscriminatedUnionSchemaVariants<Discriminator> = any,
+> extends Validator<DiscriminatedUnionSchemaOutput<Options>> {
+  constructor(
+    readonly discriminator: Discriminator,
+    readonly variants: Options,
+  ) {
+    super()
+  }
+
+  /**
+   * If all variants have a literal or enum for the discriminator property,
+   * and there are no overlapping values, returns a map of discriminator values
+   * to variants. Otherwise, returns null.
+   */
+  protected get variantsMap() {
+    const map = new Map<
+      unknown,
+      DiscriminatedUnionSchemaVariant<Discriminator>
+    >()
+    for (const variant of this.variants) {
+      const schema = variant.validators[this.discriminator]
+      if (schema instanceof LiteralSchema) {
+        if (map.has(schema.value)) return null // overlapping value
+        map.set(schema.value, variant)
+      } else if (schema instanceof EnumSchema) {
+        for (const val of schema.values) {
+          if (map.has(val)) return null // overlapping value
+          map.set(val, variant)
+        }
+      } else {
+        return null // not a literal or enum
+      }
+    }
+
+    // Cache the map on the instance (to avoid re-computing)
+    Object.defineProperty(this, 'variantsMap', {
+      value: map,
+      writable: false,
+      enumerable: false,
+      configurable: true,
+    })
+
+    return map
+  }
+
+  override validateInContext(
+    input: unknown,
+    ctx: ValidatorContext,
+  ): ValidationResult<DiscriminatedUnionSchemaOutput<Options>> {
+    if (!isPlainObject(input)) {
+      return ctx.issueInvalidType(input, 'object')
+    }
+
+    if (!Object.hasOwn(input, this.discriminator)) {
+      return ctx.issueRequiredKey(input, this.discriminator)
+    }
+
+    // Fast path: if we have a mapping of discriminator values to variants,
+    // we can directly select the correct variant to validate against. This also
+    // outputs a better error (with a single failure issue) when the discriminator.
+    if (this.variantsMap) {
+      const variant = this.variantsMap.get(input[this.discriminator])
+      if (!variant) {
+        return ctx.issueInvalidPropertyValue(input, this.discriminator, [
+          ...this.variantsMap.keys(),
+        ])
+      }
+
+      return ctx.validate(input, variant) as ValidationResult<
+        DiscriminatedUnionSchemaOutput<Options>
+      >
+    }
+
+    // Slow path: try validating against each variant and return the first
+    // successful one (or aggregate all failures if none match).
+    const failures: ValidationFailure[] = []
+
+    for (const variant of this.variants) {
+      const discSchema = variant.validators[this.discriminator]
+      const discResult = ctx.validateChild(
+        input,
+        this.discriminator,
+        discSchema,
+      )
+
+      if (!discResult.success) {
+        failures.push(discResult)
+        continue
+      }
+
+      return ctx.validate(input, variant) as ValidationResult<
+        DiscriminatedUnionSchemaOutput<Options>
+      >
+    }
+
+    return {
+      success: false,
+      error: ValidationError.fromFailures(failures),
+    }
+  }
+}

package/src/schema/enum.ts

@@ -0,0 +1,20 @@
+import { ValidationResult, Validator, ValidatorContext } from '../validation.js'
+
+export class EnumSchema<
+  Output extends null | string | number | boolean = any,
+> extends Validator<Output> {
+  constructor(readonly values: readonly Output[]) {
+    super()
+  }
+
+  override validateInContext(
+    input: unknown,
+    ctx: ValidatorContext,
+  ): ValidationResult<Output> {
+    if (!(this.values as readonly unknown[]).includes(input)) {
+      return ctx.issueInvalidValue(input, this.values)
+    }
+
+    return ctx.success(input as Output)
+  }
+}

package/src/schema/integer.ts

@@ -0,0 +1,41 @@
+import { ValidationResult, Validator, ValidatorContext } from '../validation.js'
+
+export type IntegerSchemaOptions = {
+  default?: number
+  minimum?: number
+  maximum?: number
+}
+
+export class IntegerSchema extends Validator<number> {
+  readonly lexiconType = 'integer' as const
+
+  constructor(readonly options: IntegerSchemaOptions) {
+    super()
+  }
+
+  override validateInContext(
+    input: unknown = this.options.default,
+    ctx: ValidatorContext,
+  ): ValidationResult<number> {
+    if (!isInteger(input)) {
+      return ctx.issueInvalidType(input, 'integer')
+    }
+
+    if (this.options.minimum !== undefined && input < this.options.minimum) {
+      return ctx.issueTooSmall(input, 'integer', this.options.minimum, input)
+    }
+
+    if (this.options.maximum !== undefined && input > this.options.maximum) {
+      return ctx.issueTooBig(input, 'integer', this.options.maximum, input)
+    }
+
+    return ctx.success(input)
+  }
+}
+
+/**
+ * Simple wrapper around {@link Number.isInteger} that acts as a type guard.
+ */
+function isInteger(input: unknown): input is number {
+  return Number.isInteger(input)
+}

package/src/schema/intersection.ts

@@ -0,0 +1,57 @@
+import {
+  Infer,
+  ValidationResult,
+  Validator,
+  ValidatorContext,
+} from '../validation.js'
+
+export type IntersectionSchemaValidators = readonly [
+  Validator,
+  Validator,
+  ...Validator[],
+]
+export type IntersectionSchemaOutput<
+  V extends readonly Validator[],
+  Base = unknown,
+> = V extends readonly [
+  infer First extends Validator,
+  ...infer Rest extends Validator[],
+]
+  ? IntersectionSchemaOutput<Rest, Base & Infer<First>>
+  : Base
+
+export class IntersectionSchema<
+  V extends IntersectionSchemaValidators = any,
+> extends Validator<IntersectionSchemaOutput<V>> {
+  constructor(protected readonly validators: V) {
+    super()
+  }
+
+  override validateInContext(
+    input: unknown,
+    ctx: ValidatorContext,
+  ): ValidationResult<IntersectionSchemaOutput<V>> {
+    for (let i = 0; i < this.validators.length; i++) {
+      const result = ctx.validate(input, this.validators[i])
+
+      if (!result.success) {
+        return result
+      }
+
+      // @NOTE because transforming the value could make it invalid for previous
+      // validators, we need to ensure the input remains unchanged only gets
+      // transformed by the first validator.
+      if (i !== 0 && input !== result.value) {
+        // The alternative would be to allow transforms on a first pass
+        // (ignoring errors) and then re-validate the final value against all
+        // validators (without allowing further transforms). This would be way
+        // less efficient (we could make this optional).
+        return ctx.issueInvalidValue(input, [result.value])
+      }
+
+      input = result.value
+    }
+
+    return ctx.success(input as IntersectionSchemaOutput<V>)
+  }
+}

package/src/schema/literal.ts

@@ -0,0 +1,20 @@
+import { ValidationResult, Validator, ValidatorContext } from '../validation.js'
+
+export class LiteralSchema<
+  Output extends null | string | number | boolean = any,
+> extends Validator<Output> {
+  constructor(readonly value: Output) {
+    super()
+  }
+
+  override validateInContext(
+    input: unknown,
+    ctx: ValidatorContext,
+  ): ValidationResult<Output> {
+    if (input !== this.value) {
+      return ctx.issueInvalidValue(input, [this.value])
+    }
+
+    return ctx.success(this.value)
+  }
+}

package/src/schema/never.ts

@@ -0,0 +1,14 @@
+import {
+  ValidationFailure,
+  Validator,
+  ValidatorContext,
+} from '../validation.js'
+
+export class NeverSchema extends Validator<never> {
+  override validateInContext(
+    input: unknown,
+    ctx: ValidatorContext,
+  ): ValidationFailure {
+    return ctx.issueInvalidType(input, 'never')
+  }
+}

package/src/schema/null.ts

@@ -0,0 +1,20 @@
+import { ValidationResult, Validator, ValidatorContext } from '../validation.js'
+
+export class NullSchema extends Validator<null> {
+  readonly lexiconType = 'null' as const
+
+  constructor() {
+    super()
+  }
+
+  override validateInContext(
+    input: unknown,
+    ctx: ValidatorContext,
+  ): ValidationResult<null> {
+    if (input !== null) {
+      return ctx.issueInvalidType(input, 'null')
+    }
+
+    return ctx.success(null)
+  }
+}

package/src/schema/object.test.ts

@@ -0,0 +1,138 @@
+import { BooleanSchema } from './boolean.js'
+import { DictSchema } from './dict.js'
+import { EnumSchema } from './enum.js'
+import { IntegerSchema } from './integer.js'
+import { ObjectSchema } from './object.js'
+import { StringSchema } from './string.js'
+
+describe('ObjectSchema', () => {
+  describe('simple schema', () => {
+    const schema = new ObjectSchema(
+      {
+        name: new StringSchema({}),
+        age: new IntegerSchema({}),
+        gender: new EnumSchema(['male', 'female']),
+      },
+      {
+        required: ['name'],
+        nullable: ['gender'],
+      },
+    )
+
+    it('validates plain objects', () => {
+      const result = schema.validate({
+        name: 'Alice',
+        age: 30,
+        gender: 'female',
+      })
+      expect(result.success).toBe(true)
+    })
+
+    it('rejects non-objects', () => {
+      const result = schema.validate('not an object')
+      expect(result.success).toBe(false)
+    })
+
+    it('rejects missing properties', () => {
+      const result = schema.validate({
+        age: 30,
+        gender: 'female',
+      })
+      expect(result.success).toBe(false)
+    })
+
+    it('validates optional properties', () => {
+      const result = schema.validate({
+        name: 'Alice',
+      })
+      expect(result.success).toBe(true)
+    })
+
+    it('validates nullable properties', () => {
+      const result = schema.validate({
+        name: 'Alice',
+        gender: null,
+      })
+      expect(result.success).toBe(true)
+    })
+
+    it('rejects invalid property types', () => {
+      const result = schema.validate({
+        name: 'Alice',
+        age: 'thirty',
+      })
+      expect(result.success).toBe(false)
+    })
+
+    it('ignores extra properties', () => {
+      const result = schema.validate({
+        name: 'Alice',
+        age: 30,
+        extra: 'value',
+      })
+      expect(result.success).toBe(true)
+    })
+  })
+
+  describe('strict schema', () => {
+    const schema = new ObjectSchema(
+      {
+        id: new StringSchema({}),
+        score: new IntegerSchema({}),
+      },
+      {
+        required: ['id', 'score'],
+        unknownProperties: 'strict',
+      },
+    )
+
+    it('rejects extra properties in strict mode', () => {
+      const result = schema.validate({
+        id: 'item1',
+        score: 100,
+        extra: 'not allowed',
+      })
+      expect(result.success).toBe(false)
+    })
+
+    it('accepts only defined properties in strict mode', () => {
+      const result = schema.validate({
+        id: 'item1',
+        score: 100,
+      })
+      expect(result.success).toBe(true)
+    })
+  })
+
+  describe('schema with unknownProperties validator', () => {
+    const schema = new ObjectSchema(
+      {
+        title: new StringSchema({}),
+      },
+      {
+        required: ['title'],
+        unknownProperties: new DictSchema(
+          new EnumSchema(['tag1', 'tag2']),
+          new BooleanSchema({}),
+        ),
+      },
+    )
+
+    it('validates extra properties with the provided validator', () => {
+      const result = schema.validate({
+        title: 'My Post',
+        tag1: true,
+        tag2: false,
+      })
+      expect(result.success).toBe(true)
+    })
+
+    it('rejects extra properties that fail the provided validator', () => {
+      const result = schema.validate({
+        title: 'My Post',
+        tag1: 'not a boolean',
+      })
+      expect(result.success).toBe(false)
+    })
+  })
+})