@atproto/lex-schema 0.1.4 → 0.1.6

package/src/core/schema.ts

@@ -1,412 +0,0 @@
-import { StandardSchemaV1 } from '@standard-schema/spec'
-import { lazyProperty } from '../util/lazy-property.js'
-import { StandardSchemaAdapter } from './standard-schema.js'
-import {
-  InferInput,
-  InferOutput,
-  ValidationContext,
-  ValidationOptions,
-  ValidationResult,
-  Validator,
-} from './validator.js'
-
-/**
- * Options for parsing operations.
- * Excludes the `mode` option as it is implicitly set to `"parse"`.
- */
-export type ParseOptions = Omit<ValidationOptions, 'mode'>
-
-/**
- * Options for validation operations.
- * Excludes the `mode` option as it is implicitly set to `"validate"`.
- */
-export type ValidateOptions = Omit<ValidationOptions, 'mode'>
-
-/**
- * Internal type structure for schema type inference.
- *
- * This interface defines the phantom types used for compile-time type inference
- * without affecting runtime behavior. The `input` and `output` properties
- * represent the expected input type during validation and the resulting output
- * type after parsing, respectively.
- *
- * @typeParam TInput - The type accepted as input during validation
- * @typeParam TOutput - The type returned after parsing (may differ from input due to coercion)
- */
-export interface SchemaInternals<out TInput = unknown, out TOutput = TInput> {
-  input: TInput
-  output: TOutput
-}
-
-/**
- * Abstract base class for all schema validators in the lexicon system.
- *
- * This class provides the standard validation interface that all schema types
- * implement. It offers multiple methods for validating and parsing data:
- *
- * - **Assertion methods**: `assert()`, `check()` - throw on invalid input
- * - **Type guard methods**: `matches()`, `ifMatches()` - return boolean or optional value
- * - **Parse methods**: `parse()`, `safeParse()` - allow value transformation/coercion
- * - **Validate methods**: `validate()`, `safeValidate()` - validation without coercion
- *
- * All methods are also available with a `$` prefix (e.g., `$parse()`, `$validate()`)
- * for consistent access in generated lexicon namespaces.
- *
- * @typeParam TInput - The type accepted as valid input during validation
- * @typeParam TOutput - The type returned after parsing (may include transformations)
- *
- * @example
- * ```typescript
- * class MySchema extends Schema<string> {
- *   validateInContext(input: unknown, ctx: ValidationContext): ValidationResult {
- *     if (typeof input !== 'string') {
- *       return ctx.issueUnexpectedType(input, 'string')
- *     }
- *     return ctx.success(input)
- *   }
- * }
- *
- * const schema = new MySchema()
- * schema.assert('hello')     // OK
- * schema.assert(123)         // Throws LexValidationError
- * schema.matches('hello')    // true
- * schema.matches(123)        // false
- * ```
- */
-export abstract class Schema<out TInput = unknown, out TOutput = TInput>
-  implements Validator<TInput, TOutput>, StandardSchemaV1<TInput, TOutput>
-{
-  /**
-   * Internal phantom property for type inference.
-   * This property does not exist at runtime.
-   *
-   * @internal
-   */
-  declare readonly ['__lex']: SchemaInternals<TInput, TOutput>
-
-  get '~standard'(): StandardSchemaV1.Props<TInput, TOutput> {
-    // Lazily create, and cache, the Standard Schema adapter for this schema
-    // instance.
-    return lazyProperty(this, '~standard', new StandardSchemaAdapter(this))
-  }
-
-  // Needed to discriminate multiple schema types when used in unions. Without
-  // this, Typescript could allow an EnumSchema<"foo" | "bar"> to be used where
-  // a StringSchema is expected, since they would both be structurally
-  // compatible.
-  abstract readonly type: string
-
-  /**
-   * Performs validation of the input value within a validation context.
-   *
-   * This method must be implemented by subclasses to define the actual
-   * validation logic. It should not be called directly; use
-   * {@link ValidationContext.validate} instead to ensure proper mode enforcement.
-   *
-   * @param input - The value to validate
-   * @param ctx - The validation context providing path tracking and issue reporting
-   * @returns A validation result indicating success with the validated value or failure with issues
-   *
-   * @internal
-   */
-  abstract validateInContext(
-    input: unknown,
-    ctx: ValidationContext,
-  ): ValidationResult
-
-  /**
-   * @note use {@link check}() instead of {@link assert}() if you encounter a
-   * `ts(2775)` error and you are not able to fully type the validator. This
-   * will typically arise in generic contexts, where the narrowed type is not
-   * needed.
-   */
-  assert(
-    input: unknown,
-    options?: ValidateOptions,
-  ): asserts input is InferInput<this> {
-    const result = this.safeValidate(input, options)
-    if (!result.success) throw result.reason
-  }
-
-  /**
-   * Alias for {@link assert}(). Most useful in generic contexts where the
-   * validator is not exactly typed, allowing to avoid "_Assertions require
-   * every name in the call target to be declared with an explicit type
-   * annotation. ts(2775)_" errors.
-   */
-  check(input: unknown, options?: ValidateOptions): void {
-    this.assert(input, options)
-  }
-
-  /**
-   * Casts the input (by validating it) to the output type if it matches the
-   * schema, otherwise throws. This is the same as calling {@link parse}() with
-   * `mode: "validate"`.
-   */
-  cast<I>(input: I, options?: ValidateOptions): I & InferInput<this> {
-    const result = this.safeValidate(input, options)
-    if (result.success) return result.value
-    throw result.reason
-  }
-
-  /**
-   * Type guard that checks if the input matches this schema.
-   *
-   * @example
-   * ```typescript
-   * if (schema.matches(data)) {
-   *   // data is narrowed to the schema's input type
-   *   console.log(data)
-   * }
-   * ```
-   */
-  matches<I>(
-    input: I,
-    options?: ValidateOptions,
-  ): input is I & InferInput<this> {
-    const result = this.safeValidate(input, options)
-    return result.success
-  }
-
-  /**
-   * Returns the input if it matches this schema, otherwise returns `undefined`.
-   *
-   * This is useful for optional filtering operations where you want to
-   * conditionally extract values that match a schema.
-   *
-   * @example
-   * ```typescript
-   * const validData = schema.ifMatches(data)
-   * if (validData !== undefined) {
-   *   // validData is the schema's input type
-   *   console.log(validData)
-   * }
-   * ```
-   */
-  ifMatches<I>(
-    input: I,
-    options?: ValidateOptions,
-  ): (I & InferInput<this>) | undefined {
-    return this.matches(input, options) ? input : undefined
-  }
-
-  /**
-   * Parses the input, allowing value transformations and coercion.
-   *
-   * Unlike {@link validate}, this method allows the schema to transform
-   * the input value (e.g., applying default values, type coercion).
-   * Throws a {@link LexValidationError} if the input is invalid.
-   *
-   * @param input - The value to parse
-   * @param options - Optional parsing configuration
-   * @returns The parsed and potentially transformed value
-   * @throws {LexValidationError} If the input fails validation
-   *
-   * @example
-   * ```typescript
-   * const result = schema.parse(rawData)
-   * // result has defaults applied and is fully typed
-   * ```
-   */
-  parse(input: unknown, options?: ParseOptions): InferOutput<this> {
-    const result = this.safeParse(input, options)
-    if (result.success) return result.value
-    throw result.reason
-  }
-
-  /**
-   * Safely parses the input without throwing, returning a result object.
-   *
-   * This method allows value transformations like {@link parse}, but
-   * returns a discriminated union result instead of throwing on error.
-   *
-   * @param input - The value to parse
-   * @param options - Optional parsing configuration
-   * @returns A {@link ValidationResult} with either the parsed value or validation errors
-   *
-   * @example
-   * ```typescript
-   * const result = schema.safeParse(data)
-   * if (result.success) {
-   *   console.log(result.value)
-   * } else {
-   *   console.error(result.reason.issues)
-   * }
-   * ```
-   */
-  safeParse(
-    input: unknown,
-    options?: ParseOptions,
-  ): ValidationResult<InferOutput<this>> {
-    return ValidationContext.validate(input, this, {
-      ...options,
-      mode: 'parse',
-    })
-  }
-
-  /**
-   * Validates the input strictly without allowing transformations.
-   *
-   * Unlike {@link parse}, this method requires the input to exactly match
-   * the schema without any transformations (no defaults applied, no coercion).
-   * Throws a {@link LexValidationError} if the input is invalid or would require transformation.
-   *
-   * @typeParam I - The input type (preserved in the return type)
-   * @param input - The value to validate
-   * @param options - Optional validation configuration
-   * @returns The validated input with narrowed type
-   * @throws {LexValidationError} If the input fails validation or requires transformation
-   *
-   * @example
-   * ```typescript
-   * const validated = schema.validate(data)
-   * // validated is typed as the intersection of input type and schema type
-   * ```
-   */
-  validate<I>(input: I, options?: ValidateOptions): I & InferInput<this> {
-    const result = this.safeValidate(input, options)
-    if (result.success) return result.value
-    throw result.reason
-  }
-
-  /**
-   * Safely validates the input without throwing, returning a result object.
-   *
-   * This method performs strict validation like {@link validate}, but
-   * returns a discriminated union result instead of throwing on error.
-   *
-   * @typeParam I - The input type (preserved in the result value type)
-   * @param input - The value to validate
-   * @param options - Optional validation configuration
-   * @returns A {@link ValidationResult} with either the validated value or validation errors
-   *
-   * @example
-   * ```typescript
-   * const result = schema.safeValidate(data)
-   * if (result.success) {
-   *   console.log(result.value)
-   * } else {
-   *   console.error(result.reason.issues)
-   * }
-   * ```
-   */
-  safeValidate<I>(
-    input: I,
-    options?: ValidateOptions,
-  ): ValidationResult<I & InferInput<this>> {
-    return ValidationContext.validate(input, this, {
-      ...options,
-      mode: 'validate',
-    })
-  }
-
-  // @NOTE Dollar-prefixed aliases
-  //
-  // The `lex-builder` lib generates namespaced utility functions that allow
-  // accessing the schema's methods without the need to specify the ".main."
-  // part of the namespace. This allows utilities for a particular record type
-  // to be called like "app.bsky.feed.post.<utility>()" instead of
-  // "app.bsky.feed.post.main.<utility>()".
-  //
-  // Because those utilities could conflict with other schemas (e.g. if there is
-  // a lexicon definition with the same name as the "<utility>"), those exported
-  // utilities will be prefixed with "$".
-  //
-  // Similarly, since those utilities are defined as simple "const", they are
-  // also bound (using JS's .bind) to the schema instance, so that they can be
-  // used without worrying about the context (e.g. "app.bsky.feed.post.$parse()"
-  // will work regardless of how it is imported or called).
-  //
-  // In order to provide the same functionalities for non-main definitions, we
-  // also define those aliases directly on the schema instance, so that they can
-  // be used in the same way as the utilities generated by "lex-builder". For
-  // example, if there is a non-main definition "app.bsky.feed.defs.postView",
-  // it will also be possible to call "app.bsky.feed.defs.postView.$parse()".
-  //
-  // These methods are also "bound" to the instance so that they can be used
-  // exactly like the utilities generated by "lex-builder", without worrying
-  // about the context.
-  //
-  // There are two ways we could "bind" those methods to the instance:
-  // 1. Define them as getters that return the bound method (e.g. get $parse() {
-  //    return this.parse.bind(this) })
-  // 2. Define them as properties that are initialized in the constructor (e.g.
-  //    this.$parse = this.parse.bind(this))
-  //
-  // Since a **lot** of those methods would end-up being created in systems that
-  // contains many schemas (e.g. the appview), we choose the first approach
-  // (getters) in order to avoid the overhead of creating all those bound
-  // functions upfront when instantiating the schemas.
-
-  /**
-   * Bound alias for {@link assert} for compatibility with generated utilities.
-   * @see {@link assert}
-   */
-  get $assert(): typeof this.assert {
-    return lazyProperty(this, '$assert', this.assert.bind(this))
-  }
-
-  /**
-   * Bound alias for {@link check} for compatibility with generated utilities.
-   * @see {@link check}
-   */
-  get $check(): typeof this.check {
-    return lazyProperty(this, '$check', this.check.bind(this))
-  }
-
-  /**
-   * Bound alias for {@link cast} for compatibility with generated utilities.
-   * @see {@link cast}
-   */
-  get $cast(): typeof this.cast {
-    return lazyProperty(this, '$cast', this.cast.bind(this))
-  }
-
-  /**
-   * Bound alias for {@link matches} for compatibility with generated utilities.
-   * @see {@link matches}
-   */
-  get $matches(): typeof this.matches {
-    return lazyProperty(this, '$matches', this.matches.bind(this))
-  }
-
-  /**
-   * Bound alias for {@link ifMatches} for compatibility with generated utilities.
-   * @see {@link ifMatches}
-   */
-  get $ifMatches(): typeof this.ifMatches {
-    return lazyProperty(this, '$ifMatches', this.ifMatches.bind(this))
-  }
-
-  /**
-   * Bound alias for {@link parse} for compatibility with generated utilities.
-   * @see {@link parse}
-   */
-  get $parse(): typeof this.parse {
-    return lazyProperty(this, '$parse', this.parse.bind(this))
-  }
-
-  /**
-   * Bound alias for {@link safeParse} for compatibility with generated utilities.
-   * @see {@link safeParse}
-   */
-  get $safeParse(): typeof this.safeParse {
-    return lazyProperty(this, '$safeParse', this.safeParse.bind(this))
-  }
-
-  /**
-   * Bound alias for {@link validate} for compatibility with generated utilities.
-   * @see {@link validate}
-   */
-  get $validate(): typeof this.validate {
-    return lazyProperty(this, '$validate', this.validate.bind(this))
-  }
-
-  /**
-   * Bound alias for {@link safeValidate} for compatibility with generated utilities.
-   * @see {@link safeValidate}
-   */
-  get $safeValidate(): typeof this.safeValidate {
-    return lazyProperty(this, '$safeValidate', this.safeValidate.bind(this))
-  }
-}

package/src/core/standard-schema.test.ts

@@ -1,124 +0,0 @@
-import { assert, describe, expect, it } from 'vitest'
-import { array } from '../schema/array.js'
-import { integer } from '../schema/integer.js'
-import { object } from '../schema/object.js'
-import { optional } from '../schema/optional.js'
-import { string } from '../schema/string.js'
-import { withDefault } from '../schema/with-default.js'
-import { LexValidationError } from './validation-error.js'
-
-describe('StandardSchemaAdapter', () => {
-  describe('metadata', () => {
-    const schema = integer()
-
-    it('has version 1', () => {
-      expect(schema['~standard'].version).toBe(1)
-    })
-
-    it('has vendor @atproto/lex-schema', () => {
-      expect(schema['~standard'].vendor).toBe('@atproto/lex-schema')
-    })
-  })
-
-  describe('lazy caching', () => {
-    it('returns the same adapter instance on repeated accesses', () => {
-      const schema = integer()
-      const first = schema['~standard']
-      const second = schema['~standard']
-      expect(first).toBe(second)
-    })
-  })
-
-  describe('validate() result shape on success', () => {
-    it('returns a value property for a valid integer', () => {
-      const result = integer()['~standard'].validate(42)
-      expect(result).toMatchObject({ value: 42 })
-    })
-
-    it('returns a value property for a valid string', () => {
-      const result = string()['~standard'].validate('hello')
-      expect(result).toMatchObject({ value: 'hello' })
-    })
-
-    it('does not include an issues property on success', () => {
-      const result = integer()['~standard'].validate(1)
-      expect(result).not.toHaveProperty('issues')
-    })
-  })
-
-  describe('validate() result shape on failure', () => {
-    it('returns a LexValidationError with issues for an invalid value', () => {
-      const result = integer()['~standard'].validate('not-a-number')
-      assert(result instanceof LexValidationError)
-      expect(Array.isArray(result.issues)).toBe(true)
-      expect(result.issues.length).toBeGreaterThan(0)
-    })
-
-    it('does not include a value property on failure', () => {
-      const result = integer()['~standard'].validate('not-a-number')
-      expect(result).not.toHaveProperty('value')
-    })
-
-    describe('issues[].message', () => {
-      it('is a non-empty string', () => {
-        const result = integer()['~standard'].validate('not-a-number')
-        assert(result instanceof LexValidationError)
-        for (const issue of result.issues) {
-          expect(typeof issue.message).toBe('string')
-          expect(issue.message.length).toBeGreaterThan(0)
-        }
-      })
-
-      it('describes the type mismatch', () => {
-        const result = integer()['~standard'].validate('not-a-number')
-        assert(result instanceof LexValidationError)
-        expect(result.issues[0].message).toContain('integer')
-      })
-    })
-
-    describe('issues[].path', () => {
-      it('is an empty array for a root-level failure', () => {
-        const result = integer()['~standard'].validate('not-a-number')
-        assert(result instanceof LexValidationError)
-        expect(result.issues[0].path).toEqual([])
-      })
-
-      it('reflects the property key for a nested object failure', () => {
-        const schema = object({ age: integer() })
-        const result = schema['~standard'].validate({ age: 'not-a-number' })
-        assert(result instanceof LexValidationError)
-        expect(result.issues[0].path).toContain('age')
-      })
-
-      it('reflects the index for an array element failure', () => {
-        const schema = array(integer())
-        const result = schema['~standard'].validate([1, 'bad', 3])
-        assert(result instanceof LexValidationError)
-        expect(result.issues[0].path).toContain(1)
-      })
-    })
-  })
-
-  describe('parse mode (default value application)', () => {
-    it('applies default values when input is undefined', () => {
-      const schema = withDefault(integer(), 10)
-      const result = schema['~standard'].validate(undefined)
-      expect(result).toMatchObject({ value: 10 })
-    })
-
-    it('uses the provided value instead of default when input is present', () => {
-      const schema = withDefault(integer(), 10)
-      const result = schema['~standard'].validate(42)
-      expect(result).toMatchObject({ value: 42 })
-    })
-
-    it('applies defaults for optional object properties in parse mode', () => {
-      const schema = object({
-        name: string(),
-        count: optional(withDefault(integer(), 0)),
-      })
-      const result = schema['~standard'].validate({ name: 'Alice' })
-      expect(result).toMatchObject({ value: { name: 'Alice', count: 0 } })
-    })
-  })
-})

package/src/core/standard-schema.ts

@@ -1,31 +0,0 @@
-import { StandardSchemaV1 } from '@standard-schema/spec'
-import { ValidationContext, Validator } from './validator.js'
-
-/**
- * The Standard Schema adapter for {@link Validator} instances.
- */
-export class StandardSchemaAdapter<TInput, TOutput>
-  implements StandardSchemaV1.Props<TInput, TOutput>
-{
-  readonly version = 1
-
-  readonly vendor = '@atproto/lex-schema'
-
-  declare readonly types: StandardSchemaV1.Types<TInput, TOutput>
-
-  constructor(private readonly validator: Validator<TInput, TOutput>) {}
-
-  validate(
-    value: unknown,
-    options?: StandardSchemaV1.Options,
-  ): StandardSchemaV1.Result<TOutput> {
-    // Perform validation in "parse" mode to ensure transformations (defaults,
-    // coercions, etc.) are applied. Also ensures that the output type is
-    // returned. Note that ValidationResult is compatible with
-    // StandardSchemaV1.Result :-)
-    return ValidationContext.validate(value, this.validator, {
-      ...options?.libraryOptions,
-      mode: 'parse',
-    })
-  }
-}