@atproto/lex-schema 0.0.11 → 0.0.13

package/dist/core/result.js

@@ -6,18 +6,74 @@ exports.failureReason = failureReason;
 exports.successValue = successValue;
 exports.catchall = catchall;
 exports.createCatcher = createCatcher;
+/**
+ * Creates a successful result wrapping the given value.
+ *
+ * @typeParam V - The type of the value
+ * @param value - The success value to wrap
+ * @returns {ResultSuccess} A success result containing the value
+ *
+ * @example
+ * ```typescript
+ * const result = success(42)
+ * console.log(result.success) // true
+ * console.log(result.value)   // 42
+ * ```
+ */
 /*@__NO_SIDE_EFFECTS__*/
 function success(value) {
     return { success: true, value };
 }
+/**
+ * Creates a failed result wrapping the given error reason.
+ *
+ * @typeParam E - The type of the error reason
+ * @param reason - The error reason to wrap
+ * @returns {ResultFailure} A failure result containing the error
+ *
+ * @example
+ * ```typescript
+ * const result = failure(new Error('Something went wrong'))
+ * console.log(result.success) // false
+ * console.log(result.reason.message) // "Something went wrong"
+ * ```
+ */
 /*@__NO_SIDE_EFFECTS__*/
 function failure(reason) {
     return { success: false, reason };
 }
+/**
+ * Extracts the error reason from a failure result.
+ *
+ * @typeParam T - The type of the error reason
+ * @param result - A failure result
+ * @returns {T} The error reason
+ *
+ * @example
+ * ```typescript
+ * const result = failure(new Error('oops'))
+ * const error = failureReason(result)
+ * console.log(error.message) // "oops"
+ * ```
+ */
 /*@__NO_SIDE_EFFECTS__*/
 function failureReason(result) {
     return result.reason;
 }
+/**
+ * Extracts the value from a success result.
+ *
+ * @typeParam T - The type of the success value
+ * @param result - A success result
+ * @returns {T} The success value
+ *
+ * @example
+ * ```typescript
+ * const result = success(42)
+ * const value = successValue(result)
+ * console.log(value) // 42
+ * ```
+ */
 /*@__NO_SIDE_EFFECTS__*/
 function successValue(result) {
     return result.value;
@@ -26,7 +82,7 @@ function successValue(result) {
  * Catches any error and wraps it in a {@link ResultFailure<Error>}.
  *
  * @param err - The error to catch.
- * @returns A {@link ResultFailure<Error>} containing the caught error.
+ * @returns {ResultFailure} A failure result containing the error.
  * @example
  *
  * ```ts
@@ -36,8 +92,8 @@ function successValue(result) {
  * if (result.success) {
  *   console.log(result.value) // string
  * } else {
- *   console.error(result.error instanceof Error) // true
- *   console.error(result.error.message) // string
+ *   console.error(result.reason instanceof Error) // true
+ *   console.error(result.reason.message) // string
  * }
  * ```
  */
@@ -67,7 +123,7 @@ function catchall(err) {
  * if (result.success) {
  *   console.log(result.value) // string
  * } else {
- *   console.error(result.error) // FooError | BarError
+ *   console.error(result.reason) // FooError | BarError
  * }
  */
 /*@__NO_SIDE_EFFECTS__*/

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,87 @@
 import { InferInput, InferOutput, ValidationContext, ValidationOptions, ValidationResult, Validator } from './validator.js';
-type ParseOptions = Omit<ValidationOptions, 'mode'>;
-type ValidateOptions = Omit<ValidationOptions, 'mode'>;
+/**
+ * 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> {
-    /** @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.issueUnexpectedType(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;
+    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
@@ -30,21 +103,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 {};
 //# sourceMappingURL=schema.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/core/schema.ts"],"names":[],"mappings":"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"}
+{"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.issueUnexpectedType(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);
     }