@atproto/lex-schema 0.0.11 → 0.0.13

package/src/core/schema.ts

@@ -7,17 +7,70 @@ import {
   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 abstract class Schema<
   out TInput = unknown,
   out TOutput = TInput,
@@ -27,8 +80,33 @@ export abstract class Schema<
   >,
 > implements Validator<TInternals['input'], TInternals['output']>
 {
+  /**
+   * Internal phantom property for type inference.
+   * This property does not exist at runtime.
+   *
+   * @internal
+   */
   declare readonly ['__lex']: TInternals
 
+  // Needed to discriminate multiple schema types when used in unions. Without
+  // this, Typescript could allow an EnumSchema<"foo" | "bar"> to be used where
+  // a StringSchema is expected, since they would both be structurally
+  // compatible.
+  abstract readonly type: string
+
+  /**
+   * Performs validation of the input value within a validation context.
+   *
+   * This method must be implemented by subclasses to define the actual
+   * validation logic. It should not be called directly; use
+   * {@link ValidationContext.validate} instead to ensure proper mode enforcement.
+   *
+   * @param input - The value to validate
+   * @param ctx - The validation context providing path tracking and issue reporting
+   * @returns A validation result indicating success with the validated value or failure with issues
+   *
+   * @internal
+   */
   abstract validateInContext(
     input: unknown,
     ctx: ValidationContext,
@@ -66,21 +144,91 @@ export abstract class Schema<
     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<I>(input: I): input is I & InferInput<this> {
     const result = 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<I>(input: I): (I & InferInput<this>) | undefined {
     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: unknown, options?: ParseOptions): InferOutput<this> {
     const result = this.safeParse(input, options)
     if (result.success) return result.value
     throw result.reason
   }
 
+  /**
+   * Safely parses the input without throwing, returning a result object.
+   *
+   * This method allows value transformations like {@link parse}, but
+   * returns a discriminated union result instead of throwing on error.
+   *
+   * @param input - The value to parse
+   * @param options - Optional parsing configuration
+   * @returns A {@link ValidationResult} with either the parsed value or validation errors
+   *
+   * @example
+   * ```typescript
+   * const result = schema.safeParse(data)
+   * if (result.success) {
+   *   console.log(result.value)
+   * } else {
+   *   console.error(result.reason.issues)
+   * }
+   * ```
+   */
   safeParse(
     input: unknown,
     options?: ParseOptions,
@@ -91,12 +239,52 @@ export abstract class Schema<
     })
   }
 
+  /**
+   * 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> {
     const result = this.safeValidate(input, options)
     if (result.success) return result.value
     throw result.reason
   }
 
+  /**
+   * Safely validates the input without throwing, returning a result object.
+   *
+   * This method performs strict validation like {@link validate}, but
+   * returns a discriminated union result instead of throwing on error.
+   *
+   * @typeParam I - The input type (preserved in the result value type)
+   * @param input - The value to validate
+   * @param options - Optional validation configuration
+   * @returns A {@link ValidationResult} with either the validated value or validation errors
+   *
+   * @example
+   * ```typescript
+   * const result = schema.safeValidate(data)
+   * if (result.success) {
+   *   console.log(result.value)
+   * } else {
+   *   console.error(result.reason.issues)
+   * }
+   * ```
+   */
   safeValidate<I>(
     input: I,
     options?: ValidateOptions,
@@ -107,10 +295,12 @@ export abstract class Schema<
     })
   }
 
-  // @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
@@ -121,30 +311,65 @@ export abstract 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: unknown): asserts input is InferInput<this> {
     return this.assert(input)
   }
 
+  /**
+   * Alias for {@link check} with `$` prefix for namespace compatibility.
+   *
+   * @see {@link check}
+   */
   $check(input: unknown): void {
     return this.check(input)
   }
 
+  /**
+   * Alias for {@link cast} with `$` prefix for namespace compatibility.
+   *
+   * @see {@link cast}
+   */
   $cast<I>(input: I): I & InferInput<this> {
     return this.cast(input)
   }
 
+  /**
+   * Alias for {@link matches} with `$` prefix for namespace compatibility.
+   *
+   * @see {@link matches}
+   */
   $matches(input: unknown): input is InferInput<this> {
     return this.matches(input)
   }
 
+  /**
+   * Alias for {@link ifMatches} with `$` prefix for namespace compatibility.
+   *
+   * @see {@link ifMatches}
+   */
   $ifMatches<I>(input: I): (I & InferInput<this>) | undefined {
     return this.ifMatches(input)
   }
 
+  /**
+   * Alias for {@link parse} with `$` prefix for namespace compatibility.
+   *
+   * @see {@link parse}
+   */
   $parse(input: unknown, options?: ValidateOptions): InferOutput<this> {
     return this.parse(input, options)
   }
 
+  /**
+   * Alias for {@link safeParse} with `$` prefix for namespace compatibility.
+   *
+   * @see {@link safeParse}
+   */
   $safeParse(
     input: unknown,
     options?: ValidateOptions,
@@ -152,10 +377,20 @@ export abstract class Schema<
     return this.safeParse(input, options)
   }
 
+  /**
+   * Alias for {@link validate} with `$` prefix for namespace compatibility.
+   *
+   * @see {@link validate}
+   */
   $validate<I>(input: I, options?: ValidateOptions): I & InferInput<this> {
     return this.validate(input, options)
   }
 
+  /**
+   * Alias for {@link safeValidate} with `$` prefix for namespace compatibility.
+   *
+   * @see {@link safeValidate}
+   */
   $safeValidate<I>(
     input: I,
     options?: ValidateOptions,

package/src/core/string-format.ts

@@ -22,42 +22,193 @@ import {
 } from '@atproto/syntax'
 import { CheckFn } from '../util/assertion-util.js'
 
-// Expose all individual string format types and type guards
+// -----------------------------------------------------------------------------
+// Individual string format types and type guards
+// -----------------------------------------------------------------------------
 
-export type { AtIdentifierString }
+/**
+ * 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,
+}
 
-export type { AtUriString }
+/**
+ * Type guard that checks if a value is a valid AT URI.
+ *
+ * @param value - The value to check
+ * @returns `true` if the value is a valid AT URI
+ */
 export const isAtUriString: CheckFn<AtUriString> = isValidAtUri
+export type {
+  /**
+   * An AT URI string pointing to a resource in the AT Protocol network.
+   *
+   * @example `"at://did:plc:1234.../app.bsky.feed.post/3k2..."`
+   */
+  AtUriString,
+}
 
-export type CidString = string
+/**
+ * Type guard that checks if a value is a valid CID string.
+ *
+ * @param value - The value to check
+ * @returns `true` if the value is a valid CID string
+ */
 export const isCidString = ((v) => validateCidString(v)) as CheckFn<CidString>
+/**
+ * A Content Identifier (CID) string.
+ *
+ * CIDs are self-describing content addresses used to identify data by its hash.
+ *
+ * @example `"bafyreig..."`
+ */
+export type CidString = string
 
-export type { DatetimeString }
+/**
+ * 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,
+}
 
-export type { DidString }
+/**
+ * Type guard that checks if a value is a valid DID string.
+ *
+ * @param value - The value to check
+ * @returns `true` if the value is a valid DID string
+ */
 export const isDidString: CheckFn<DidString> = isValidDid
+export type {
+  /**
+   * A Decentralized Identifier (DID) string.
+   *
+   * DIDs are globally unique identifiers that don't require a central authority.
+   *
+   * @example `"did:plc:1234abcd..."` or `"did:web:example.com"`
+   */
+  DidString,
+}
 
-export type { HandleString }
+/**
+ * Type guard that checks if a value is a valid handle string.
+ *
+ * @param value - The value to check
+ * @returns `true` if the value is a valid handle string
+ */
 export const isHandleString: CheckFn<HandleString> = isValidHandle
+export type {
+  /**
+   * A handle string - a human-readable identifier for users.
+   *
+   * @example `"alice.bsky.social"` or `"bob.example.com"`
+   */
+  HandleString,
+}
 
-export type LanguageString = string
+/**
+ * Type guard that checks if a value is a valid BCP-47 language tag.
+ *
+ * @param value - The value to check
+ * @returns `true` if the value is a valid language string
+ */
 export const isLanguageString = isValidLanguage as CheckFn<LanguageString>
+/**
+ * A BCP-47 language tag string.
+ *
+ * @example `"en"`, `"en-US"`, `"zh-Hans"`
+ */
+export type LanguageString = string
 
-export type { NsidString }
+/**
+ * Type guard that checks if a value is a valid NSID string.
+ *
+ * @param value - The value to check
+ * @returns `true` if the value is a valid NSID string
+ */
 export const isNsidString: CheckFn<NsidString> = isValidNsid
+export type {
+  /**
+   * A Namespaced Identifier (NSID) string identifying a lexicon.
+   *
+   * NSIDs use reverse-domain notation to identify schemas.
+   *
+   * @example `"app.bsky.feed.post"`, `"com.atproto.repo.createRecord"`
+   */
+  NsidString,
+}
 
-export type { RecordKeyString }
+/**
+ * Type guard that checks if a value is a valid record key string.
+ *
+ * @param value - The value to check
+ * @returns `true` if the value is a valid record key string
+ */
 export const isRecordKeyString: CheckFn<RecordKeyString> = isValidRecordKey
+export type {
+  /**
+   * A record key string identifying a record within a collection.
+   *
+   * @example `"3k2..."` (TID format) or `"self"` (literal key)
+   */
+  RecordKeyString,
+}
 
-export type { TidString }
+/**
+ * Type guard that checks if a value is a valid TID string.
+ *
+ * @param value - The value to check
+ * @returns `true` if the value is a valid TID string
+ */
 export const isTidString: CheckFn<TidString> = isValidTid
+export type {
+  /**
+   * A Timestamp Identifier (TID) string.
+   *
+   * TIDs are time-based identifiers used for record keys.
+   *
+   * @example `"3k2..."`
+   */
+  TidString,
+}
 
-export type { UriString }
+/**
+ * Type guard that checks if a value is a valid URI string.
+ *
+ * @param value - The value to check
+ * @returns `true` if the value is a valid URI string
+ */
 export const isUriString: CheckFn<UriString> = isValidUri
+export type {
+  /**
+   * A standard URI string.
+   *
+   * @example `"https://example.com/path"`
+   */
+  UriString,
+}
 
-// String format registry (maps format names to their types and type guards)
+// -----------------------------------------------------------------------------
+// String format registry
+// -----------------------------------------------------------------------------
 
 type StringFormats = {
   'at-identifier': AtIdentifierString
@@ -73,6 +224,9 @@ type StringFormats = {
   uri: UriString
 }
 
+/**
+ * Union type of all valid string format names.
+ */
 export type StringFormat = Extract<keyof StringFormats, string>
 
 const stringFormatVerifiers: {
@@ -93,10 +247,39 @@ const stringFormatVerifiers: {
   uri: isUriString,
 })
 
+/**
+ * Infers the string type for a given format name.
+ *
+ * @typeParam F - The format name
+ *
+ * @example
+ * ```typescript
+ * type Did = InferStringFormat<'did'>
+ * // Result: DidString
+ * ```
+ */
 export type InferStringFormat<F extends StringFormat> = F extends StringFormat
   ? StringFormats[F]
   : never
 
+/**
+ * Type guard that checks if a string matches a specific format.
+ *
+ * @typeParam I - The input string type
+ * @typeParam F - The format to check
+ * @param input - The string to validate
+ * @param format - The format name to validate against
+ * @returns `true` if the string matches the format
+ *
+ * @example
+ * ```typescript
+ * const value: string = 'did:plc:1234...'
+ * if (isStringFormat(value, 'did')) {
+ *   // value is typed as DidString
+ *   console.log('Valid DID:', value)
+ * }
+ * ```
+ */
 /*@__NO_SIDE_EFFECTS__*/
 export function isStringFormat<I extends string, F extends StringFormat>(
   input: I,
@@ -109,6 +292,21 @@ export function isStringFormat<I extends string, F extends StringFormat>(
   return formatVerifier(input)
 }
 
+/**
+ * Asserts that a string matches a specific format, throwing if invalid.
+ *
+ * @typeParam I - The input string type
+ * @typeParam F - The format to check
+ * @param input - The string to validate
+ * @param format - The format name to validate against
+ * @throws {TypeError} If the string doesn't match the format
+ *
+ * @example
+ * ```typescript
+ * assertStringFormat(value, 'handle')
+ * // value is now typed as HandleString
+ * ```
+ */
 /*@__NO_SIDE_EFFECTS__*/
 export function assertStringFormat<I extends string, F extends StringFormat>(
   input: I,
@@ -119,6 +317,24 @@ export function assertStringFormat<I extends string, F extends StringFormat>(
   }
 }
 
+/**
+ * Validates and returns a string as the specified format type, throwing if invalid.
+ *
+ * This is useful when you need to convert a string to a format type in an expression.
+ *
+ * @typeParam I - The input string type
+ * @typeParam F - The format to validate against
+ * @param input - The string to validate
+ * @param format - The format name to validate against
+ * @returns The input typed as the format type
+ * @throws {TypeError} If the string doesn't match the format
+ *
+ * @example
+ * ```typescript
+ * const did = asStringFormat(userInput, 'did')
+ * // did is typed as DidString
+ * ```
+ */
 /*@__NO_SIDE_EFFECTS__*/
 export function asStringFormat<I extends string, F extends StringFormat>(
   input: I,
@@ -128,6 +344,26 @@ export function asStringFormat<I extends string, F extends StringFormat>(
   return input
 }
 
+/**
+ * Returns the string as the format type if valid, otherwise returns `undefined`.
+ *
+ * This is useful for optional validation where you want to handle invalid values
+ * without throwing.
+ *
+ * @typeParam I - The input string type
+ * @typeParam F - The format to validate against
+ * @param input - The string to validate
+ * @param format - The format name to validate against
+ * @returns The typed string if valid, otherwise `undefined`
+ *
+ * @example
+ * ```typescript
+ * const did = ifStringFormat(maybeInvalid, 'did')
+ * if (did) {
+ *   // did is typed as DidString
+ * }
+ * ```
+ */
 /*@__NO_SIDE_EFFECTS__*/
 export function ifStringFormat<I extends string, F extends StringFormat>(
   input: I,
@@ -136,6 +372,16 @@ export function ifStringFormat<I extends string, F extends StringFormat>(
   return isStringFormat(input, format) ? input : undefined
 }
 
+/**
+ * Array of all valid string format names.
+ *
+ * @example
+ * ```typescript
+ * for (const format of STRING_FORMATS) {
+ *   console.log(format) // 'at-identifier', 'at-uri', 'cid', ...
+ * }
+ * ```
+ */
 export const STRING_FORMATS = /*#__PURE__*/ Object.freeze(
   /*#__PURE__*/ Object.keys(stringFormatVerifiers),
 ) as readonly StringFormat[]