@atproto/lex-schema 0.0.11 → 0.0.12

package/dist/core/result.js.map

@@ -1 +1 @@
-{"version":3,"file":"result.js","sourceRoot":"","sources":["../../src/core/result.ts"],"names":[],"mappings":";;AAMA,0BAEC;AAGD,0BAEC;AAGD,sCAEC;AAGD,oCAEC;AAsBD,4BAGC;AA0BD,sCAKC;AA1ED,wBAAwB;AACxB,SAAgB,OAAO,CAAI,KAAQ;IACjC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,CAAA;AACjC,CAAC;AAED,wBAAwB;AACxB,SAAgB,OAAO,CAAI,MAAS;IAClC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,CAAA;AACnC,CAAC;AAED,wBAAwB;AACxB,SAAgB,aAAa,CAAI,MAAwB;IACvD,OAAO,MAAM,CAAC,MAAM,CAAA;AACtB,CAAC;AAED,wBAAwB;AACxB,SAAgB,YAAY,CAAI,MAAwB;IACtD,OAAO,MAAM,CAAC,KAAK,CAAA;AACrB,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAwB;AACxB,SAAgB,QAAQ,CAAC,GAAY;IACnC,IAAI,GAAG,YAAY,KAAK;QAAE,OAAO,OAAO,CAAC,GAAG,CAAC,CAAA;IAC7C,OAAO,OAAO,CAAC,IAAI,KAAK,CAAC,eAAe,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC,CAAA;AAC5D,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAwB;AACxB,SAAgB,aAAa,CAAI,IAA+B;IAC9D,OAAO,CAAC,GAAY,EAAoB,EAAE;QACxC,IAAI,GAAG,YAAY,IAAI;YAAE,OAAO,OAAO,CAAC,GAAG,CAAC,CAAA;QAC5C,MAAM,GAAG,CAAA;IACX,CAAC,CAAA;AACH,CAAC","sourcesContent":["export type ResultSuccess<V = any> = { success: true; value: V }\nexport type ResultFailure<E = Error> = { success: false; reason: E }\n\nexport type Result<V = any, E = Error> = ResultSuccess<V> | ResultFailure<E>\n\n/*@__NO_SIDE_EFFECTS__*/\nexport function success<V>(value: V): ResultSuccess<V> {\n  return { success: true, value }\n}\n\n/*@__NO_SIDE_EFFECTS__*/\nexport function failure<E>(reason: E): ResultFailure<E> {\n  return { success: false, reason }\n}\n\n/*@__NO_SIDE_EFFECTS__*/\nexport function failureReason<T>(result: ResultFailure<T>): T {\n  return result.reason\n}\n\n/*@__NO_SIDE_EFFECTS__*/\nexport function successValue<T>(result: ResultSuccess<T>): T {\n  return result.value\n}\n\n/**\n * Catches any error and wraps it in a {@link ResultFailure<Error>}.\n *\n * @param err - The error to catch.\n * @returns A {@link ResultFailure<Error>} containing the caught error.\n * @example\n *\n * ```ts\n * declare function someFunction(): Promise<string>\n *\n * const result = await someFunction().then(success, catchall)\n * if (result.success) {\n *   console.log(result.value) // string\n * } else {\n *   console.error(result.error instanceof Error) // true\n *   console.error(result.error.message) // string\n * }\n * ```\n */\n/*@__NO_SIDE_EFFECTS__*/\nexport function catchall(err: unknown): ResultFailure<Error> {\n  if (err instanceof Error) return failure(err)\n  return failure(new Error('Unknown error', { cause: err }))\n}\n\n/**\n * Creates a catcher function for the given constructor that wraps caught errors\n * in a {@link ResultFailure}.\n *\n * @example\n *\n * ```ts\n * class FooError extends Error {}\n * class BarError extends Error {}\n *\n * declare function someFunction(): Promise<string>\n *\n * const result = await someFunction()\n *   .then(success)\n *   .catch(createCatcher(FooError))\n *   .catch(createCatcher(BarError))\n *\n * if (result.success) {\n *   console.log(result.value) // string\n * } else {\n *   console.error(result.error) // FooError | BarError\n * }\n */\n/*@__NO_SIDE_EFFECTS__*/\nexport function createCatcher<T>(Ctor: new (...args: any[]) => T) {\n  return (err: unknown): ResultFailure<T> => {\n    if (err instanceof Ctor) return failure(err)\n    throw err\n  }\n}\n"]}
+{"version":3,"file":"result.js","sourceRoot":"","sources":["../../src/core/result.ts"],"names":[],"mappings":";;AA8CA,0BAEC;AAiBD,0BAEC;AAiBD,sCAEC;AAiBD,oCAEC;AAsBD,4BAGC;AA0BD,sCAKC;AAlID;;;;;;;;;;;;;GAaG;AACH,wBAAwB;AACxB,SAAgB,OAAO,CAAI,KAAQ;IACjC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,CAAA;AACjC,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAwB;AACxB,SAAgB,OAAO,CAAI,MAAS;IAClC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,CAAA;AACnC,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAwB;AACxB,SAAgB,aAAa,CAAI,MAAwB;IACvD,OAAO,MAAM,CAAC,MAAM,CAAA;AACtB,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAwB;AACxB,SAAgB,YAAY,CAAI,MAAwB;IACtD,OAAO,MAAM,CAAC,KAAK,CAAA;AACrB,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAwB;AACxB,SAAgB,QAAQ,CAAC,GAAY;IACnC,IAAI,GAAG,YAAY,KAAK;QAAE,OAAO,OAAO,CAAC,GAAG,CAAC,CAAA;IAC7C,OAAO,OAAO,CAAC,IAAI,KAAK,CAAC,eAAe,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC,CAAA;AAC5D,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAwB;AACxB,SAAgB,aAAa,CAAI,IAA+B;IAC9D,OAAO,CAAC,GAAY,EAAoB,EAAE;QACxC,IAAI,GAAG,YAAY,IAAI;YAAE,OAAO,OAAO,CAAC,GAAG,CAAC,CAAA;QAC5C,MAAM,GAAG,CAAA;IACX,CAAC,CAAA;AACH,CAAC","sourcesContent":["export type ResultSuccess<V = any> = { success: true; value: V }\n\n/**\n * Represents a failed result containing an error reason.\n *\n * @typeParam E - The type of the error reason\n */\nexport type ResultFailure<E = Error> = { success: false; reason: E }\n\n/**\n * A discriminated union type representing either a success or failure outcome.\n *\n * Check the `success` property to determine the outcome and access the\n * appropriate property (`value` for success, `reason` for failure).\n *\n * @typeParam V - The type of the success value\n * @typeParam E - The type of the error reason\n *\n * @example\n * ```typescript\n * function parseJson(text: string): Result<unknown, SyntaxError> {\n *   try {\n *     return success(JSON.parse(text))\n *   } catch (e) {\n *     return failure(e as SyntaxError)\n *   }\n * }\n * ```\n */\nexport type Result<V = any, E = Error> = ResultSuccess<V> | ResultFailure<E>\n\n/**\n * Creates a successful result wrapping the given value.\n *\n * @typeParam V - The type of the value\n * @param value - The success value to wrap\n * @returns {ResultSuccess} A success result containing the value\n *\n * @example\n * ```typescript\n * const result = success(42)\n * console.log(result.success) // true\n * console.log(result.value)   // 42\n * ```\n */\n/*@__NO_SIDE_EFFECTS__*/\nexport function success<V>(value: V): ResultSuccess<V> {\n  return { success: true, value }\n}\n\n/**\n * Creates a failed result wrapping the given error reason.\n *\n * @typeParam E - The type of the error reason\n * @param reason - The error reason to wrap\n * @returns {ResultFailure} A failure result containing the error\n *\n * @example\n * ```typescript\n * const result = failure(new Error('Something went wrong'))\n * console.log(result.success) // false\n * console.log(result.reason.message) // \"Something went wrong\"\n * ```\n */\n/*@__NO_SIDE_EFFECTS__*/\nexport function failure<E>(reason: E): ResultFailure<E> {\n  return { success: false, reason }\n}\n\n/**\n * Extracts the error reason from a failure result.\n *\n * @typeParam T - The type of the error reason\n * @param result - A failure result\n * @returns {T} The error reason\n *\n * @example\n * ```typescript\n * const result = failure(new Error('oops'))\n * const error = failureReason(result)\n * console.log(error.message) // \"oops\"\n * ```\n */\n/*@__NO_SIDE_EFFECTS__*/\nexport function failureReason<T>(result: ResultFailure<T>): T {\n  return result.reason\n}\n\n/**\n * Extracts the value from a success result.\n *\n * @typeParam T - The type of the success value\n * @param result - A success result\n * @returns {T} The success value\n *\n * @example\n * ```typescript\n * const result = success(42)\n * const value = successValue(result)\n * console.log(value) // 42\n * ```\n */\n/*@__NO_SIDE_EFFECTS__*/\nexport function successValue<T>(result: ResultSuccess<T>): T {\n  return result.value\n}\n\n/**\n * Catches any error and wraps it in a {@link ResultFailure<Error>}.\n *\n * @param err - The error to catch.\n * @returns {ResultFailure} A failure result containing the error.\n * @example\n *\n * ```ts\n * declare function someFunction(): Promise<string>\n *\n * const result = await someFunction().then(success, catchall)\n * if (result.success) {\n *   console.log(result.value) // string\n * } else {\n *   console.error(result.reason instanceof Error) // true\n *   console.error(result.reason.message) // string\n * }\n * ```\n */\n/*@__NO_SIDE_EFFECTS__*/\nexport function catchall(err: unknown): ResultFailure<Error> {\n  if (err instanceof Error) return failure(err)\n  return failure(new Error('Unknown error', { cause: err }))\n}\n\n/**\n * Creates a catcher function for the given constructor that wraps caught errors\n * in a {@link ResultFailure}.\n *\n * @example\n *\n * ```ts\n * class FooError extends Error {}\n * class BarError extends Error {}\n *\n * declare function someFunction(): Promise<string>\n *\n * const result = await someFunction()\n *   .then(success)\n *   .catch(createCatcher(FooError))\n *   .catch(createCatcher(BarError))\n *\n * if (result.success) {\n *   console.log(result.value) // string\n * } else {\n *   console.error(result.reason) // FooError | BarError\n * }\n */\n/*@__NO_SIDE_EFFECTS__*/\nexport function createCatcher<T>(Ctor: new (...args: any[]) => T) {\n  return (err: unknown): ResultFailure<T> => {\n    if (err instanceof Ctor) return failure(err)\n    throw err\n  }\n}\n"]}

package/dist/core/schema.d.ts

@@ -1,14 +1,86 @@
 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"`.
+ */
 type ParseOptions = Omit<ValidationOptions, 'mode'>;
+/**
+ * Options for validation operations.
+ * Excludes the `mode` option as it is implicitly set to `"validate"`.
+ */
 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> {
-    /** @internal The inferred validation type */
     input: TInput;
-    /** @internal The inferred parse type */
     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()` - strict 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)
+ * @typeParam TInternals - Internal type structure for type inference
+ *
+ * @example
+ * ```typescript
+ * class MySchema extends Schema<string> {
+ *   validateInContext(input: unknown, ctx: ValidationContext): ValidationResult {
+ *     if (typeof input !== 'string') {
+ *       return ctx.issueInvalidType(input, 'string')
+ *     }
+ *     return ctx.success(input)
+ *   }
+ * }
+ *
+ * const schema = new MySchema()
+ * schema.assert('hello')     // OK
+ * schema.assert(123)         // Throws ValidationError
+ * schema.matches('hello')    // true
+ * schema.matches(123)        // false
+ * ```
+ */
 export declare abstract class Schema<out TInput = unknown, out TOutput = TInput, out TInternals extends SchemaInternals<TInput, TOutput> = SchemaInternals<TInput, TOutput>> implements Validator<TInternals['input'], TInternals['output']> {
+    /**
+     * Internal phantom property for type inference.
+     * This property does not exist at runtime.
+     *
+     * @internal
+     */
     readonly ['__lex']: TInternals;
+    /**
+     * 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
@@ -30,20 +102,175 @@ export declare abstract class Schema<out TInput = unknown, out TOutput = TInput,
      * `mode: "validate"`.
      */
     cast<I>(input: I): I & InferInput<this>;
+    /**
+     * Type guard that checks if the input matches this schema.
+     *
+     * @param input - The value to check
+     * @returns `true` if the input is valid according to this schema
+     *
+     * @example
+     * ```typescript
+     * if (schema.matches(data)) {
+     *   // data is narrowed to the schema's input type
+     *   console.log(data)
+     * }
+     * ```
+     */
     matches<I>(input: I): input is I & InferInput<this>;
+    /**
+     * 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.
+     *
+     * @param input - The value to check
+     * @returns The input value with narrowed type if valid, otherwise `undefined`
+     *
+     * @example
+     * ```typescript
+     * const validData = schema.ifMatches(data)
+     * if (validData !== undefined) {
+     *   // validData is the schema's input type
+     *   console.log(validData)
+     * }
+     * ```
+     */
     ifMatches<I>(input: I): (I & InferInput<this>) | 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 ValidationError} 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
+     *
+     * @example
+     * ```typescript
+     * const result = schema.parse(rawData)
+     * // result has defaults applied and is fully typed
+     * ```
+     */
     parse(input: unknown, options?: ParseOptions): InferOutput<this>;
+    /**
+     * 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>>;
+    /**
+     * 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 ValidationError} 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
+     *
+     * @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>;
+    /**
+     * 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>>;
+    /**
+     * Alias for {@link assert} with `$` prefix for namespace compatibility.
+     *
+     * @see {@link assert}
+     */
     $assert(input: unknown): asserts input is InferInput<this>;
+    /**
+     * Alias for {@link check} with `$` prefix for namespace compatibility.
+     *
+     * @see {@link check}
+     */
     $check(input: unknown): void;
+    /**
+     * Alias for {@link cast} with `$` prefix for namespace compatibility.
+     *
+     * @see {@link cast}
+     */
     $cast<I>(input: I): I & InferInput<this>;
+    /**
+     * Alias for {@link matches} with `$` prefix for namespace compatibility.
+     *
+     * @see {@link matches}
+     */
     $matches(input: unknown): input is InferInput<this>;
+    /**
+     * Alias for {@link ifMatches} with `$` prefix for namespace compatibility.
+     *
+     * @see {@link ifMatches}
+     */
     $ifMatches<I>(input: I): (I & InferInput<this>) | undefined;
+    /**
+     * Alias for {@link parse} with `$` prefix for namespace compatibility.
+     *
+     * @see {@link parse}
+     */
     $parse(input: unknown, options?: ValidateOptions): InferOutput<this>;
+    /**
+     * Alias for {@link safeParse} with `$` prefix for namespace compatibility.
+     *
+     * @see {@link safeParse}
+     */
     $safeParse(input: unknown, options?: ValidateOptions): ValidationResult<InferOutput<this>>;
+    /**
+     * Alias for {@link validate} with `$` prefix for namespace compatibility.
+     *
+     * @see {@link validate}
+     */
     $validate<I>(input: I, options?: ValidateOptions): I & InferInput<this>;
+    /**
+     * Alias for {@link safeValidate} with `$` prefix for namespace compatibility.
+     *
+     * @see {@link safeValidate}
+     */
     $safeValidate<I>(input: I, options?: ValidateOptions): ValidationResult<I & InferInput<this>>;
 }
 export {};

package/dist/core/schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/core/schema.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,UAAU,EACV,WAAW,EACX,iBAAiB,EACjB,iBAAiB,EACjB,gBAAgB,EAChB,SAAS,EACV,MAAM,gBAAgB,CAAA;AAEvB,KAAK,YAAY,GAAG,IAAI,CAAC,iBAAiB,EAAE,MAAM,CAAC,CAAA;AACnD,KAAK,eAAe,GAAG,IAAI,CAAC,iBAAiB,EAAE,MAAM,CAAC,CAAA;AAEtD,MAAM,WAAW,eAAe,CAAC,GAAG,CAAC,MAAM,GAAG,OAAO,EAAE,GAAG,CAAC,OAAO,GAAG,MAAM;IACzE,6CAA6C;IAC7C,KAAK,EAAE,MAAM,CAAA;IAEb,wCAAwC;IACxC,MAAM,EAAE,OAAO,CAAA;CAChB;AAED,8BAAsB,MAAM,CAC1B,GAAG,CAAC,MAAM,GAAG,OAAO,EACpB,GAAG,CAAC,OAAO,GAAG,MAAM,EACpB,GAAG,CAAC,UAAU,SAAS,eAAe,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,eAAe,CACvE,MAAM,EACN,OAAO,CACR,CACD,YAAW,SAAS,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,UAAU,CAAC,QAAQ,CAAC,CAAC;IAE/D,SAAiB,CAAC,OAAO,CAAC,EAAE,UAAU,CAAA;IAEtC,QAAQ,CAAC,iBAAiB,CACxB,KAAK,EAAE,OAAO,EACd,GAAG,EAAE,iBAAiB,GACrB,gBAAgB;IAEnB;;;;;OAKG;IACH,MAAM,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,KAAK,IAAI,UAAU,CAAC,IAAI,CAAC;IAKzD;;;;;OAKG;IACH,KAAK,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI;IAI3B;;;;OAIG;IACH,IAAI,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,GAAG,UAAU,CAAC,IAAI,CAAC;IAMvC,OAAO,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,KAAK,IAAI,CAAC,GAAG,UAAU,CAAC,IAAI,CAAC;IAKnD,SAAS,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CAAC,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC,GAAG,SAAS;IAI1D,KAAK,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,WAAW,CAAC,IAAI,CAAC;IAMhE,SAAS,CACP,KAAK,EAAE,OAAO,EACd,OAAO,CAAC,EAAE,YAAY,GACrB,gBAAgB,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;IAOtC,QAAQ,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,CAAC,GAAG,UAAU,CAAC,IAAI,CAAC;IAMtE,YAAY,CAAC,CAAC,EACZ,KAAK,EAAE,CAAC,EACR,OAAO,CAAC,EAAE,eAAe,GACxB,gBAAgB,CAAC,CAAC,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC;IAqBzC,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,KAAK,IAAI,UAAU,CAAC,IAAI,CAAC;IAI1D,MAAM,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI;IAI5B,KAAK,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,GAAG,UAAU,CAAC,IAAI,CAAC;IAIxC,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,UAAU,CAAC,IAAI,CAAC;IAInD,UAAU,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CAAC,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC,GAAG,SAAS;IAI3D,MAAM,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,WAAW,CAAC,IAAI,CAAC;IAIpE,UAAU,CACR,KAAK,EAAE,OAAO,EACd,OAAO,CAAC,EAAE,eAAe,GACxB,gBAAgB,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;IAItC,SAAS,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,eAAe,GAAG,CAAC,GAAG,UAAU,CAAC,IAAI,CAAC;IAIvE,aAAa,CAAC,CAAC,EACb,KAAK,EAAE,CAAC,EACR,OAAO,CAAC,EAAE,eAAe,GACxB,gBAAgB,CAAC,CAAC,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC;CAG1C"}
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/core/schema.ts"],"names":[],"mappings":"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"}

package/dist/core/schema.js

@@ -2,6 +2,42 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Schema = void 0;
 const validator_js_1 = require("./validator.js");
+/**
+ * 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()` - strict 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)
+ * @typeParam TInternals - Internal type structure for type inference
+ *
+ * @example
+ * ```typescript
+ * class MySchema extends Schema<string> {
+ *   validateInContext(input: unknown, ctx: ValidationContext): ValidationResult {
+ *     if (typeof input !== 'string') {
+ *       return ctx.issueInvalidType(input, 'string')
+ *     }
+ *     return ctx.success(input)
+ *   }
+ * }
+ *
+ * const schema = new MySchema()
+ * schema.assert('hello')     // OK
+ * schema.assert(123)         // Throws ValidationError
+ * schema.matches('hello')    // true
+ * schema.matches(123)        // false
+ * ```
+ */
 class Schema {
     /**
      * @note use {@link check}() instead of {@link assert}() if you encounter a
@@ -34,41 +70,153 @@ class Schema {
             return result.value;
         throw result.reason;
     }
+    /**
+     * Type guard that checks if the input matches this schema.
+     *
+     * @param input - The value to check
+     * @returns `true` if the input is valid according to this schema
+     *
+     * @example
+     * ```typescript
+     * if (schema.matches(data)) {
+     *   // data is narrowed to the schema's input type
+     *   console.log(data)
+     * }
+     * ```
+     */
     matches(input) {
         const result = validator_js_1.ValidationContext.validate(input, this);
         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.
+     *
+     * @param input - The value to check
+     * @returns The input value with narrowed type if valid, otherwise `undefined`
+     *
+     * @example
+     * ```typescript
+     * const validData = schema.ifMatches(data)
+     * if (validData !== undefined) {
+     *   // validData is the schema's input type
+     *   console.log(validData)
+     * }
+     * ```
+     */
     ifMatches(input) {
         return this.matches(input) ? 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 ValidationError} 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
+     *
+     * @example
+     * ```typescript
+     * const result = schema.parse(rawData)
+     * // result has defaults applied and is fully typed
+     * ```
+     */
     parse(input, options) {
         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, options) {
         return validator_js_1.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 ValidationError} 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
+     *
+     * @example
+     * ```typescript
+     * const validated = schema.validate(data)
+     * // validated is typed as the intersection of input type and schema type
+     * ```
+     */
     validate(input, options) {
         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(input, options) {
         return validator_js_1.ValidationContext.validate(input, this, {
             ...options,
             mode: 'validate',
         });
     }
-    // @NOTE The built lexicons namespaces will 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
+    // @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
@@ -78,30 +226,75 @@ class Schema {
     //
     // - "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
+    /**
+     * Alias for {@link assert} with `$` prefix for namespace compatibility.
+     *
+     * @see {@link assert}
+     */
     $assert(input) {
         return this.assert(input);
     }
+    /**
+     * Alias for {@link check} with `$` prefix for namespace compatibility.
+     *
+     * @see {@link check}
+     */
     $check(input) {
         return this.check(input);
     }
+    /**
+     * Alias for {@link cast} with `$` prefix for namespace compatibility.
+     *
+     * @see {@link cast}
+     */
     $cast(input) {
         return this.cast(input);
     }
+    /**
+     * Alias for {@link matches} with `$` prefix for namespace compatibility.
+     *
+     * @see {@link matches}
+     */
     $matches(input) {
         return this.matches(input);
     }
+    /**
+     * Alias for {@link ifMatches} with `$` prefix for namespace compatibility.
+     *
+     * @see {@link ifMatches}
+     */
     $ifMatches(input) {
         return this.ifMatches(input);
     }
+    /**
+     * Alias for {@link parse} with `$` prefix for namespace compatibility.
+     *
+     * @see {@link parse}
+     */
     $parse(input, options) {
         return this.parse(input, options);
     }
+    /**
+     * Alias for {@link safeParse} with `$` prefix for namespace compatibility.
+     *
+     * @see {@link safeParse}
+     */
     $safeParse(input, options) {
         return this.safeParse(input, options);
     }
+    /**
+     * Alias for {@link validate} with `$` prefix for namespace compatibility.
+     *
+     * @see {@link validate}
+     */
     $validate(input, options) {
         return this.validate(input, options);
     }
+    /**
+     * Alias for {@link safeValidate} with `$` prefix for namespace compatibility.
+     *
+     * @see {@link safeValidate}
+     */
     $safeValidate(input, options) {
         return this.safeValidate(input, options);
     }

package/dist/core/schema.js.map

@@ -1 +1 @@
-{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/core/schema.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  InferInput,\n  InferOutput,\n  ValidationContext,\n  ValidationOptions,\n  ValidationResult,\n  Validator,\n} from './validator.js'\n\ntype ParseOptions = Omit<ValidationOptions, 'mode'>\ntype ValidateOptions = Omit<ValidationOptions, 'mode'>\n\nexport interface SchemaInternals<out TInput = unknown, out TOutput = TInput> {\n  /** @internal The inferred validation type */\n  input: TInput\n\n  /** @internal The inferred parse type */\n  output: TOutput\n}\n\nexport abstract class Schema<\n  out TInput = unknown,\n  out TOutput = TInput,\n  out TInternals extends SchemaInternals<TInput, TOutput> = SchemaInternals<\n    TInput,\n    TOutput\n  >,\n> implements Validator<TInternals['input'], TInternals['output']>\n{\n  declare readonly ['__lex']: TInternals\n\n  abstract validateInContext(\n    input: unknown,\n    ctx: ValidationContext,\n  ): ValidationResult\n\n  /**\n   * @note use {@link check}() instead of {@link assert}() if you encounter a\n   * `ts(2775)` error and you are not able to fully type the validator. This\n   * will typically arise in generic contexts, where the narrowed type is not\n   * needed.\n   */\n  assert(input: unknown): asserts input is InferInput<this> {\n    const result = ValidationContext.validate(input, this)\n    if (!result.success) throw result.reason\n  }\n\n  /**\n   * Alias for {@link assert}(). Most useful in generic contexts where the\n   * validator is not exactly typed, allowing to avoid \"_Assertions require\n   * every name in the call target to be declared with an explicit type\n   * annotation. ts(2775)_\" errors.\n   */\n  check(input: unknown): void {\n    this.assert(input)\n  }\n\n  /**\n   * Casts the input (by validating it) to the output type if it matches the\n   * schema, otherwise throws. This is the same as calling {@link parse}() with\n   * `mode: \"validate\"`.\n   */\n  cast<I>(input: I): I & InferInput<this> {\n    const result = ValidationContext.validate(input, this)\n    if (result.success) return result.value\n    throw result.reason\n  }\n\n  matches<I>(input: I): input is I & InferInput<this> {\n    const result = ValidationContext.validate(input, this)\n    return result.success\n  }\n\n  ifMatches<I>(input: I): (I & InferInput<this>) | undefined {\n    return this.matches(input) ? input : undefined\n  }\n\n  parse(input: unknown, options?: ParseOptions): InferOutput<this> {\n    const result = this.safeParse(input, options)\n    if (result.success) return result.value\n    throw result.reason\n  }\n\n  safeParse(\n    input: unknown,\n    options?: ParseOptions,\n  ): ValidationResult<InferOutput<this>> {\n    return ValidationContext.validate(input, this, {\n      ...options,\n      mode: 'parse',\n    })\n  }\n\n  validate<I>(input: I, options?: ValidateOptions): I & InferInput<this> {\n    const result = this.safeValidate(input, options)\n    if (result.success) return result.value\n    throw result.reason\n  }\n\n  safeValidate<I>(\n    input: I,\n    options?: ValidateOptions,\n  ): ValidationResult<I & InferInput<this>> {\n    return ValidationContext.validate(input, this, {\n      ...options,\n      mode: 'validate',\n    })\n  }\n\n  // @NOTE The built lexicons namespaces will export utility functions that\n  // allow accessing the schema's methods without the need to specify \".main.\"\n  // as part of the namespace. This way, a utility for a particular record type\n  // can be called like \"app.bsky.feed.post.<utility>()\" instead of\n  // \"app.bsky.feed.post.main.<utility>()\". Because those utilities could\n  // conflict with other schemas (e.g. if there is a lexicon definition at\n  // \"#<utility>\"), those exported utilities will be prefixed with \"$\". In order\n  // to be able to consistently call the utilities, when using the \"main\" and\n  // non \"main\" definitions, we also expose the same methods with a \"$\" prefix.\n  // Thanks to this, both of the following call will be possible:\n  //\n  // - \"app.bsky.feed.post.$parse(...)\" // calls a utility function created by \"lex build\"\n  // - \"app.bsky.feed.defs.postView.$parse(...)\" // uses the alias defined below on the schema instance\n\n  $assert(input: unknown): asserts input is InferInput<this> {\n    return this.assert(input)\n  }\n\n  $check(input: unknown): void {\n    return this.check(input)\n  }\n\n  $cast<I>(input: I): I & InferInput<this> {\n    return this.cast(input)\n  }\n\n  $matches(input: unknown): input is InferInput<this> {\n    return this.matches(input)\n  }\n\n  $ifMatches<I>(input: I): (I & InferInput<this>) | undefined {\n    return this.ifMatches(input)\n  }\n\n  $parse(input: unknown, options?: ValidateOptions): InferOutput<this> {\n    return this.parse(input, options)\n  }\n\n  $safeParse(\n    input: unknown,\n    options?: ValidateOptions,\n  ): ValidationResult<InferOutput<this>> {\n    return this.safeParse(input, options)\n  }\n\n  $validate<I>(input: I, options?: ValidateOptions): I & InferInput<this> {\n    return this.validate(input, options)\n  }\n\n  $safeValidate<I>(\n    input: I,\n    options?: ValidateOptions,\n  ): ValidationResult<I & InferInput<this>> {\n    return this.safeValidate(input, options)\n  }\n}\n"]}
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/core/schema.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  InferInput,\n  InferOutput,\n  ValidationContext,\n  ValidationOptions,\n  ValidationResult,\n  Validator,\n} from './validator.js'\n\n/**\n * Options for parsing operations.\n * Excludes the `mode` option as it is implicitly set to `\"parse\"`.\n */\ntype ParseOptions = Omit<ValidationOptions, 'mode'>\n\n/**\n * Options for validation operations.\n * Excludes the `mode` option as it is implicitly set to `\"validate\"`.\n */\ntype ValidateOptions = Omit<ValidationOptions, 'mode'>\n\n/**\n * Internal type structure for schema type inference.\n *\n * This interface defines the phantom types used for compile-time type inference\n * without affecting runtime behavior. The `input` and `output` properties\n * represent the expected input type during validation and the resulting output\n * type after parsing, respectively.\n *\n * @typeParam TInput - The type accepted as input during validation\n * @typeParam TOutput - The type returned after parsing (may differ from input due to coercion)\n */\nexport interface SchemaInternals<out TInput = unknown, out TOutput = TInput> {\n  input: TInput\n  output: TOutput\n}\n\n/**\n * Abstract base class for all schema validators in the lexicon system.\n *\n * This class provides the standard validation interface that all schema types\n * implement. It offers multiple methods for validating and parsing data:\n *\n * - **Assertion methods**: `assert()`, `check()` - throw on invalid input\n * - **Type guard methods**: `matches()`, `ifMatches()` - return boolean or optional value\n * - **Parse methods**: `parse()`, `safeParse()` - allow value transformation/coercion\n * - **Validate methods**: `validate()`, `safeValidate()` - strict validation without coercion\n *\n * All methods are also available with a `$` prefix (e.g., `$parse()`, `$validate()`)\n * for consistent access in generated lexicon namespaces.\n *\n * @typeParam TInput - The type accepted as valid input during validation\n * @typeParam TOutput - The type returned after parsing (may include transformations)\n * @typeParam TInternals - Internal type structure for type inference\n *\n * @example\n * ```typescript\n * class MySchema extends Schema<string> {\n *   validateInContext(input: unknown, ctx: ValidationContext): ValidationResult {\n *     if (typeof input !== 'string') {\n *       return ctx.issueInvalidType(input, 'string')\n *     }\n *     return ctx.success(input)\n *   }\n * }\n *\n * const schema = new MySchema()\n * schema.assert('hello')     // OK\n * schema.assert(123)         // Throws ValidationError\n * schema.matches('hello')    // true\n * schema.matches(123)        // false\n * ```\n */\nexport abstract class Schema<\n  out TInput = unknown,\n  out TOutput = TInput,\n  out TInternals extends SchemaInternals<TInput, TOutput> = SchemaInternals<\n    TInput,\n    TOutput\n  >,\n> implements Validator<TInternals['input'], TInternals['output']>\n{\n  /**\n   * Internal phantom property for type inference.\n   * This property does not exist at runtime.\n   *\n   * @internal\n   */\n  declare readonly ['__lex']: TInternals\n\n  /**\n   * Performs validation of the input value within a validation context.\n   *\n   * This method must be implemented by subclasses to define the actual\n   * validation logic. It should not be called directly; use\n   * {@link ValidationContext.validate} instead to ensure proper mode enforcement.\n   *\n   * @param input - The value to validate\n   * @param ctx - The validation context providing path tracking and issue reporting\n   * @returns A validation result indicating success with the validated value or failure with issues\n   *\n   * @internal\n   */\n  abstract validateInContext(\n    input: unknown,\n    ctx: ValidationContext,\n  ): ValidationResult\n\n  /**\n   * @note use {@link check}() instead of {@link assert}() if you encounter a\n   * `ts(2775)` error and you are not able to fully type the validator. This\n   * will typically arise in generic contexts, where the narrowed type is not\n   * needed.\n   */\n  assert(input: unknown): asserts input is InferInput<this> {\n    const result = ValidationContext.validate(input, this)\n    if (!result.success) throw result.reason\n  }\n\n  /**\n   * Alias for {@link assert}(). Most useful in generic contexts where the\n   * validator is not exactly typed, allowing to avoid \"_Assertions require\n   * every name in the call target to be declared with an explicit type\n   * annotation. ts(2775)_\" errors.\n   */\n  check(input: unknown): void {\n    this.assert(input)\n  }\n\n  /**\n   * Casts the input (by validating it) to the output type if it matches the\n   * schema, otherwise throws. This is the same as calling {@link parse}() with\n   * `mode: \"validate\"`.\n   */\n  cast<I>(input: I): I & InferInput<this> {\n    const result = ValidationContext.validate(input, this)\n    if (result.success) return result.value\n    throw result.reason\n  }\n\n  /**\n   * Type guard that checks if the input matches this schema.\n   *\n   * @param input - The value to check\n   * @returns `true` if the input is valid according to this schema\n   *\n   * @example\n   * ```typescript\n   * if (schema.matches(data)) {\n   *   // data is narrowed to the schema's input type\n   *   console.log(data)\n   * }\n   * ```\n   */\n  matches<I>(input: I): input is I & InferInput<this> {\n    const result = ValidationContext.validate(input, this)\n    return result.success\n  }\n\n  /**\n   * Returns the input if it matches this schema, otherwise returns `undefined`.\n   *\n   * This is useful for optional filtering operations where you want to\n   * conditionally extract values that match a schema.\n   *\n   * @param input - The value to check\n   * @returns The input value with narrowed type if valid, otherwise `undefined`\n   *\n   * @example\n   * ```typescript\n   * const validData = schema.ifMatches(data)\n   * if (validData !== undefined) {\n   *   // validData is the schema's input type\n   *   console.log(validData)\n   * }\n   * ```\n   */\n  ifMatches<I>(input: I): (I & InferInput<this>) | undefined {\n    return this.matches(input) ? input : undefined\n  }\n\n  /**\n   * Parses the input, allowing value transformations and coercion.\n   *\n   * Unlike {@link validate}, this method allows the schema to transform\n   * the input value (e.g., applying default values, type coercion).\n   * Throws a {@link ValidationError} if the input is invalid.\n   *\n   * @param input - The value to parse\n   * @param options - Optional parsing configuration\n   * @returns The parsed and potentially transformed value\n   * @throws {ValidationError} If the input fails validation\n   *\n   * @example\n   * ```typescript\n   * const result = schema.parse(rawData)\n   * // result has defaults applied and is fully typed\n   * ```\n   */\n  parse(input: unknown, options?: ParseOptions): InferOutput<this> {\n    const result = this.safeParse(input, options)\n    if (result.success) return result.value\n    throw result.reason\n  }\n\n  /**\n   * Safely parses the input without throwing, returning a result object.\n   *\n   * This method allows value transformations like {@link parse}, but\n   * returns a discriminated union result instead of throwing on error.\n   *\n   * @param input - The value to parse\n   * @param options - Optional parsing configuration\n   * @returns A {@link ValidationResult} with either the parsed value or validation errors\n   *\n   * @example\n   * ```typescript\n   * const result = schema.safeParse(data)\n   * if (result.success) {\n   *   console.log(result.value)\n   * } else {\n   *   console.error(result.reason.issues)\n   * }\n   * ```\n   */\n  safeParse(\n    input: unknown,\n    options?: ParseOptions,\n  ): ValidationResult<InferOutput<this>> {\n    return ValidationContext.validate(input, this, {\n      ...options,\n      mode: 'parse',\n    })\n  }\n\n  /**\n   * Validates the input strictly without allowing transformations.\n   *\n   * Unlike {@link parse}, this method requires the input to exactly match\n   * the schema without any transformations (no defaults applied, no coercion).\n   * Throws a {@link ValidationError} if the input is invalid or would require transformation.\n   *\n   * @typeParam I - The input type (preserved in the return type)\n   * @param input - The value to validate\n   * @param options - Optional validation configuration\n   * @returns The validated input with narrowed type\n   * @throws {ValidationError} If the input fails validation or requires transformation\n   *\n   * @example\n   * ```typescript\n   * const validated = schema.validate(data)\n   * // validated is typed as the intersection of input type and schema type\n   * ```\n   */\n  validate<I>(input: I, options?: ValidateOptions): I & InferInput<this> {\n    const result = this.safeValidate(input, options)\n    if (result.success) return result.value\n    throw result.reason\n  }\n\n  /**\n   * Safely validates the input without throwing, returning a result object.\n   *\n   * This method performs strict validation like {@link validate}, but\n   * returns a discriminated union result instead of throwing on error.\n   *\n   * @typeParam I - The input type (preserved in the result value type)\n   * @param input - The value to validate\n   * @param options - Optional validation configuration\n   * @returns A {@link ValidationResult} with either the validated value or validation errors\n   *\n   * @example\n   * ```typescript\n   * const result = schema.safeValidate(data)\n   * if (result.success) {\n   *   console.log(result.value)\n   * } else {\n   *   console.error(result.reason.issues)\n   * }\n   * ```\n   */\n  safeValidate<I>(\n    input: I,\n    options?: ValidateOptions,\n  ): ValidationResult<I & InferInput<this>> {\n    return ValidationContext.validate(input, this, {\n      ...options,\n      mode: 'validate',\n    })\n  }\n\n  // @NOTE Dollar-prefixed aliases\n  //\n  // The built lexicons namespaces export utility functions that allow accessing\n  // the schema's methods without the need to specify \".main.\" as part of the\n  // namespace. This way, a utility for a particular record type can be called\n  // like \"app.bsky.feed.post.<utility>()\" instead of\n  // \"app.bsky.feed.post.main.<utility>()\". Because those utilities could\n  // conflict with other schemas (e.g. if there is a lexicon definition at\n  // \"#<utility>\"), those exported utilities will be prefixed with \"$\". In order\n  // to be able to consistently call the utilities, when using the \"main\" and\n  // non \"main\" definitions, we also expose the same methods with a \"$\" prefix.\n  // Thanks to this, both of the following call will be possible:\n  //\n  // - \"app.bsky.feed.post.$parse(...)\" // calls a utility function created by \"lex build\"\n  // - \"app.bsky.feed.defs.postView.$parse(...)\" // uses the alias defined below on the schema instance\n\n  /**\n   * Alias for {@link assert} with `$` prefix for namespace compatibility.\n   *\n   * @see {@link assert}\n   */\n  $assert(input: unknown): asserts input is InferInput<this> {\n    return this.assert(input)\n  }\n\n  /**\n   * Alias for {@link check} with `$` prefix for namespace compatibility.\n   *\n   * @see {@link check}\n   */\n  $check(input: unknown): void {\n    return this.check(input)\n  }\n\n  /**\n   * Alias for {@link cast} with `$` prefix for namespace compatibility.\n   *\n   * @see {@link cast}\n   */\n  $cast<I>(input: I): I & InferInput<this> {\n    return this.cast(input)\n  }\n\n  /**\n   * Alias for {@link matches} with `$` prefix for namespace compatibility.\n   *\n   * @see {@link matches}\n   */\n  $matches(input: unknown): input is InferInput<this> {\n    return this.matches(input)\n  }\n\n  /**\n   * Alias for {@link ifMatches} with `$` prefix for namespace compatibility.\n   *\n   * @see {@link ifMatches}\n   */\n  $ifMatches<I>(input: I): (I & InferInput<this>) | undefined {\n    return this.ifMatches(input)\n  }\n\n  /**\n   * Alias for {@link parse} with `$` prefix for namespace compatibility.\n   *\n   * @see {@link parse}\n   */\n  $parse(input: unknown, options?: ValidateOptions): InferOutput<this> {\n    return this.parse(input, options)\n  }\n\n  /**\n   * Alias for {@link safeParse} with `$` prefix for namespace compatibility.\n   *\n   * @see {@link safeParse}\n   */\n  $safeParse(\n    input: unknown,\n    options?: ValidateOptions,\n  ): ValidationResult<InferOutput<this>> {\n    return this.safeParse(input, options)\n  }\n\n  /**\n   * Alias for {@link validate} with `$` prefix for namespace compatibility.\n   *\n   * @see {@link validate}\n   */\n  $validate<I>(input: I, options?: ValidateOptions): I & InferInput<this> {\n    return this.validate(input, options)\n  }\n\n  /**\n   * Alias for {@link safeValidate} with `$` prefix for namespace compatibility.\n   *\n   * @see {@link safeValidate}\n   */\n  $safeValidate<I>(\n    input: I,\n    options?: ValidateOptions,\n  ): ValidationResult<I & InferInput<this>> {\n    return this.safeValidate(input, options)\n  }\n}\n"]}