@atproto/lex-schema 0.0.13 → 0.0.15

package/src/core/schema.ts

@@ -1,3 +1,6 @@
+import { StandardSchemaV1 } from '@standard-schema/spec'
+import { lazyProperty } from '../util/lazy-property.js'
+import { StandardSchemaAdapter } from './standard-schema.js'
 import {
   InferInput,
   InferOutput,
@@ -51,7 +54,6 @@ export interface SchemaInternals<out TInput = unknown, out TOutput = TInput> {
  *
  * @typeParam TInput - The type accepted as valid input during validation
  * @typeParam TOutput - The type returned after parsing (may include transformations)
- * @typeParam TInternals - Internal type structure for type inference
  *
  * @example
  * ```typescript
@@ -66,19 +68,13 @@ export interface SchemaInternals<out TInput = unknown, out TOutput = TInput> {
  *
  * const schema = new MySchema()
  * schema.assert('hello')     // OK
- * schema.assert(123)         // Throws ValidationError
+ * schema.assert(123)         // Throws LexValidationError
  * schema.matches('hello')    // true
  * schema.matches(123)        // false
  * ```
  */
-export abstract class Schema<
-  out TInput = unknown,
-  out TOutput = TInput,
-  out TInternals extends SchemaInternals<TInput, TOutput> = SchemaInternals<
-    TInput,
-    TOutput
-  >,
-> implements Validator<TInternals['input'], TInternals['output']>
+export abstract class Schema<out TInput = unknown, out TOutput = TInput>
+  implements Validator<TInput, TOutput>, StandardSchemaV1<TInput, TOutput>
 {
   /**
    * Internal phantom property for type inference.
@@ -86,7 +82,13 @@ export abstract class Schema<
    *
    * @internal
    */
-  declare readonly ['__lex']: TInternals
+  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
@@ -190,12 +192,12 @@ export abstract class Schema<
    *
    * Unlike {@link validate}, this method allows the schema to transform
    * the input value (e.g., applying default values, type coercion).
-   * Throws a {@link ValidationError} if the input is invalid.
+   * 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 {ValidationError} If the input fails validation
+   * @throws {LexValidationError} If the input fails validation
    *
    * @example
    * ```typescript
@@ -244,13 +246,13 @@ export abstract class Schema<
    *
    * Unlike {@link parse}, this method requires the input to exactly match
    * the schema without any transformations (no defaults applied, no coercion).
-   * Throws a {@link ValidationError} if the input is invalid or would require transformation.
+   * 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 {ValidationError} If the input fails validation or requires transformation
+   * @throws {LexValidationError} If the input fails validation or requires transformation
    *
    * @example
    * ```typescript
@@ -297,104 +299,111 @@ export abstract class Schema<
 
   // @NOTE Dollar-prefixed aliases
   //
-  // The built lexicons namespaces export utility functions that allow accessing
-  // the schema's methods without the need to specify ".main." as part of the
-  // namespace. This way, a utility for a particular record type can 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 at
-  // "#<utility>"), those exported utilities will be prefixed with "$". In order
-  // to be able to consistently call the utilities, when using the "main" and
-  // non "main" definitions, we also expose the same methods with a "$" prefix.
-  // Thanks to this, both of the following call will be possible:
+  // 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.
   //
-  // - "app.bsky.feed.post.$parse(...)" // calls a utility function created by "lex build"
-  // - "app.bsky.feed.defs.postView.$parse(...)" // uses the alias defined below on the schema instance
+  // 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.
 
   /**
-   * Alias for {@link assert} with `$` prefix for namespace compatibility.
-   *
+   * Bound alias for {@link assert} for compatibility with generated utilities.
    * @see {@link assert}
    */
-  $assert(input: unknown): asserts input is InferInput<this> {
-    return this.assert(input)
+  get $assert(): typeof this.assert {
+    return lazyProperty(this, '$assert', this.assert.bind(this))
   }
 
   /**
-   * Alias for {@link check} with `$` prefix for namespace compatibility.
-   *
+   * Bound alias for {@link check} for compatibility with generated utilities.
    * @see {@link check}
    */
-  $check(input: unknown): void {
-    return this.check(input)
+  get $check(): typeof this.check {
+    return lazyProperty(this, '$check', this.check.bind(this))
   }
 
   /**
-   * Alias for {@link cast} with `$` prefix for namespace compatibility.
-   *
+   * Bound alias for {@link cast} for compatibility with generated utilities.
    * @see {@link cast}
    */
-  $cast<I>(input: I): I & InferInput<this> {
-    return this.cast(input)
+  get $cast(): typeof this.cast {
+    return lazyProperty(this, '$cast', this.cast.bind(this))
   }
 
   /**
-   * Alias for {@link matches} with `$` prefix for namespace compatibility.
-   *
+   * Bound alias for {@link matches} for compatibility with generated utilities.
    * @see {@link matches}
    */
-  $matches(input: unknown): input is InferInput<this> {
-    return this.matches(input)
+  get $matches(): typeof this.matches {
+    return lazyProperty(this, '$matches', this.matches.bind(this))
   }
 
   /**
-   * Alias for {@link ifMatches} with `$` prefix for namespace compatibility.
-   *
+   * Bound alias for {@link ifMatches} for compatibility with generated utilities.
    * @see {@link ifMatches}
    */
-  $ifMatches<I>(input: I): (I & InferInput<this>) | undefined {
-    return this.ifMatches(input)
+  get $ifMatches(): typeof this.ifMatches {
+    return lazyProperty(this, '$ifMatches', this.ifMatches.bind(this))
   }
 
   /**
-   * Alias for {@link parse} with `$` prefix for namespace compatibility.
-   *
+   * Bound alias for {@link parse} for compatibility with generated utilities.
    * @see {@link parse}
    */
-  $parse(input: unknown, options?: ValidateOptions): InferOutput<this> {
-    return this.parse(input, options)
+  get $parse(): typeof this.parse {
+    return lazyProperty(this, '$parse', this.parse.bind(this))
   }
 
   /**
-   * Alias for {@link safeParse} with `$` prefix for namespace compatibility.
-   *
+   * Bound alias for {@link safeParse} for compatibility with generated utilities.
    * @see {@link safeParse}
    */
-  $safeParse(
-    input: unknown,
-    options?: ValidateOptions,
-  ): ValidationResult<InferOutput<this>> {
-    return this.safeParse(input, options)
+  get $safeParse(): typeof this.safeParse {
+    return lazyProperty(this, '$safeParse', this.safeParse.bind(this))
   }
 
   /**
-   * Alias for {@link validate} with `$` prefix for namespace compatibility.
-   *
+   * Bound alias for {@link validate} for compatibility with generated utilities.
    * @see {@link validate}
    */
-  $validate<I>(input: I, options?: ValidateOptions): I & InferInput<this> {
-    return this.validate(input, options)
+  get $validate(): typeof this.validate {
+    return lazyProperty(this, '$validate', this.validate.bind(this))
   }
 
   /**
-   * Alias for {@link safeValidate} with `$` prefix for namespace compatibility.
-   *
+   * Bound alias for {@link safeValidate} for compatibility with generated utilities.
    * @see {@link safeValidate}
    */
-  $safeValidate<I>(
-    input: I,
-    options?: ValidateOptions,
-  ): ValidationResult<I & InferInput<this>> {
-    return this.safeValidate(input, options)
+  get $safeValidate(): typeof this.safeValidate {
+    return lazyProperty(this, '$safeValidate', this.safeValidate.bind(this))
   }
 }

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

@@ -0,0 +1,124 @@
+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

@@ -0,0 +1,31 @@
+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',
+    })
+  }
+}

package/src/core/string-format.ts

@@ -9,9 +9,9 @@ import {
   RecordKeyString,
   TidString,
   UriString,
-  isValidAtIdentifier as isValidAtId,
+  isAtIdentifierString,
+  isDatetimeString,
   isValidAtUri,
-  isValidDatetime,
   isValidDid,
   isValidHandle,
   isValidLanguage,
@@ -26,21 +26,30 @@ import { CheckFn } from '../util/assertion-util.js'
 // Individual string format types and type guards
 // -----------------------------------------------------------------------------
 
-/**
- * Type guard that checks if a value is a valid AT identifier (DID or handle).
- *
- * @param value - The value to check
- * @returns `true` if the value is a valid AT identifier
- */
-export const isAtIdentifierString: CheckFn<AtIdentifierString> = isValidAtId
-export type {
-  /**
-   * An AT identifier string - either a DID or a handle.
-   *
-   * @example `"did:plc:1234..."` or `"alice.bsky.social"`
-   */
-  AtIdentifierString,
-}
+// Re-exporting from @atproto/syntax without modification to preserve types and
+// documentation for types and utilities that are already well-defined there.
+// @TODO rework other string formats in @atproto/syntax to follow this pattern
+// and re-export here, e.g. language tags, NSIDs, record keys, etc.
+
+export {
+  type AtIdentifierString,
+  asAtIdentifierString,
+  ifAtIdentifierString,
+  isAtIdentifierString,
+} from '@atproto/syntax'
+
+// AtIdentifierString utilities
+export { isDidIdentifier, isHandleIdentifier } from '@atproto/syntax'
+
+export {
+  type DatetimeString,
+  asDatetimeString,
+  ifDatetimeString,
+  isDatetimeString,
+} from '@atproto/syntax'
+
+// DatetimeString utilities
+export { currentDatetimeString, toDatetimeString } from '@atproto/syntax'
 
 /**
  * Type guard that checks if a value is a valid AT URI.
@@ -74,22 +83,6 @@ export const isCidString = ((v) => validateCidString(v)) as CheckFn<CidString>
  */
 export type CidString = string
 
-/**
- * Type guard that checks if a value is a valid datetime string.
- *
- * @param value - The value to check
- * @returns `true` if the value is a valid datetime string
- */
-export const isDatetimeString: CheckFn<DatetimeString> = isValidDatetime
-export type {
-  /**
-   * An ISO 8601 datetime string.
-   *
-   * @example `"2024-01-15T12:30:00.000Z"`
-   */
-  DatetimeString,
-}
-
 /**
  * Type guard that checks if a value is a valid DID string.
  *

package/src/core/validation-error.ts

@@ -19,7 +19,7 @@ import {
  *
  * @example
  * ```typescript
- * const error = new ValidationError([
+ * const error = new LexValidationError([
  *   new IssueInvalidType(['user', 'age'], 'hello', ['number'])
  * ])
  * console.log(error.message)
@@ -29,9 +29,16 @@ import {
  * console.log(error.toJSON())
  * // { error: 'InvalidRequest', message: '...', issues: [...] }
  * ```
+ *
+ * @note this class implements {@link ResultFailure} to allow it to be used
+ * directly as a failure reason in validation results, avoiding the need for
+ * wrapping it in an additional object.
  */
-export class ValidationError extends LexError {
-  name = 'ValidationError'
+export class LexValidationError
+  extends LexError<'InvalidRequest'>
+  implements ResultFailure<LexValidationError>
+{
+  name = 'LexValidationError'
 
   /**
    * The list of validation issues that caused this error.
@@ -56,12 +63,20 @@ export class ValidationError extends LexError {
     this.issues = issuesAgg
   }
 
+  /** @see {ResultFailure.success} */
+  readonly success = false as const
+
+  /** @see {ResultFailure.reason} */
+  get reason() {
+    return this
+  }
+
   /**
    * Converts the error to a JSON-serializable object.
    *
-   * @returns An object containing the error details and all issues in JSON format
+   * @returns An object containing the error details and issues details
    */
-  toJSON() {
+  override toJSON() {
     return {
       ...super.toJSON(),
       issues: this.issues.map((issue) => issue.toJSON()),
@@ -81,23 +96,23 @@ export class ValidationError extends LexError {
    * ```typescript
    * const failures = schemas.map(s => s.safeValidate(data)).filter(r => !r.success)
    * if (failures.length === schemas.length) {
-   *   throw ValidationError.fromFailures(failures)
+   *   throw LexValidationError.fromFailures(failures)
    * }
    * ```
    */
   static fromFailures(
-    failures: ResultFailure<ValidationError>[],
-  ): ValidationError {
+    failures: readonly ResultFailure<LexValidationError>[],
+  ): LexValidationError {
     if (failures.length === 1) return failureReason(failures[0])
     const issues = failures.flatMap(extractFailureIssues)
-    return new ValidationError(issues, {
+    return new LexValidationError(issues, {
       // Keep the original errors as the cause chain
       cause: failures.map(failureReason),
     })
   }
 }
 
-function extractFailureIssues(result: ResultFailure<ValidationError>) {
+function extractFailureIssues(result: ResultFailure<LexValidationError>) {
   return result.reason.issues
 }