@atproto/lex-schema 0.0.10 → 0.0.12

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[]

package/src/core/types.ts

@@ -1,23 +1,95 @@
 /**
- * Same as {@link string} but prevents TypeScript allowing union types to
+ * Same as `string` but prevents TypeScript from allowing union types to
  * be widened to `string` in IDEs.
+ *
+ * This is useful when you want autocompletion for known string values
+ * while still allowing arbitrary strings.
+ *
+ * @example
+ * ```typescript
+ * // With plain string, union is widened:
+ * type Status1 = 'active' | 'inactive' | string // just becomes "string"
+ *
+ * // With UnknownString, union is preserved:
+ * type Status2 = 'active' | 'inactive' | UnknownString
+ * // Autocomplete will suggest 'active' and 'inactive'
+ * ```
  */
 export type UnknownString = string & NonNullable<unknown>
 
+/**
+ * Simplifies a type by expanding intersections and mapped types.
+ *
+ * This improves IDE tooltips by showing the actual shape of a type
+ * rather than complex intersections.
+ *
+ * @typeParam T - The type to simplify
+ *
+ * @example
+ * ```typescript
+ * type Complex = { a: string } & { b: number }
+ * type Simple = Simplify<Complex>
+ * // Hover shows: { a: string; b: number }
+ * ```
+ */
 export type Simplify<T> = { [K in keyof T]: T[K] } & NonNullable<unknown>
 
+/**
+ * Internal symbol for branding restricted types.
+ * @internal
+ */
 declare const __restricted: unique symbol
+
 /**
  * A type that represents a value that cannot be used, with a custom
  * message explaining the restriction.
+ *
+ * This is useful for creating "never use this" types that provide
+ * helpful error messages when someone tries to use them.
+ *
+ * @typeParam Message - A string literal type containing the error message
+ *
+ * @example
+ * ```typescript
+ * type DeprecatedField = Restricted<'This field has been deprecated. Use newField instead.'>
+ *
+ * interface MyType {
+ *   oldField?: DeprecatedField
+ *   newField: string
+ * }
+ *
+ * const obj: MyType = {
+ *   oldField: 'value', // Error: Type 'string' is not assignable to type 'Restricted<...>'
+ *   newField: 'value'
+ * }
+ * ```
  */
 export type Restricted<Message extends string> = typeof __restricted & {
   [__restricted]: Message
 }
 
 /**
- * Converts all properties of `P` that are optional (i.e. may be `undefined`)
- * into actual optional properties on the resulting type.
+ * Converts all properties of `P` that may be `undefined` into actual
+ * optional properties on the resulting type.
+ *
+ * This is useful when working with types where some properties are typed as
+ * `T | undefined` but should really be optional (`T?`).
+ *
+ * @typeParam P - The object type to transform
+ *
+ * @example
+ * ```typescript
+ * type Input = {
+ *   required: string
+ *   optional: string | undefined
+ * }
+ *
+ * type Output = WithOptionalProperties<Input>
+ * // Result: {
+ * //   required: string
+ * //   optional?: string | undefined
+ * // }
+ * ```
  */
 export type WithOptionalProperties<P> = Simplify<
   {
@@ -27,6 +99,22 @@ export type WithOptionalProperties<P> = Simplify<
   }
 >
 
+/**
+ * Creates a type by omitting a specific key from an object type.
+ *
+ * Similar to TypeScript's built-in `Omit`, but preserves the type structure
+ * more accurately in some edge cases.
+ *
+ * @typeParam T - The object type to transform
+ * @typeParam K - The key to omit (must be a key of T)
+ *
+ * @example
+ * ```typescript
+ * type Person = { name: string; age: number; email: string }
+ * type PersonWithoutEmail = OmitKey<Person, 'email'>
+ * // Result: { name: string; age: number }
+ * ```
+ */
 export type OmitKey<T, K extends keyof T> = {
   [K2 in keyof T as K2 extends K ? never : K2]: T[K2]
 }

package/src/core/validation-error.ts

@@ -7,17 +7,60 @@ import {
   IssueInvalidValue,
 } from './validation-issue.js'
 
+/**
+ * Error thrown when validation fails.
+ *
+ * Contains detailed information about all validation issues encountered,
+ * including the path to each invalid value and descriptions of what was
+ * expected vs what was received.
+ *
+ * Extends {@link LexError} with the error name "InvalidRequest" for
+ * consistency with the AT Protocol error handling conventions.
+ *
+ * @example
+ * ```typescript
+ * const error = new ValidationError([
+ *   new IssueInvalidType(['user', 'age'], 'hello', ['number'])
+ * ])
+ * console.log(error.message)
+ * // "Expected number value type at $.user.age (got string)"
+ *
+ * console.log(error.issues.length) // 1
+ * console.log(error.toJSON())
+ * // { error: 'InvalidRequest', message: '...', issues: [...] }
+ * ```
+ */
 export class ValidationError extends LexError {
   name = 'ValidationError'
 
+  /**
+   * The list of validation issues that caused this error.
+   *
+   * Issues are aggregated when possible (e.g., multiple invalid type issues
+   * at the same path are combined into a single issue listing all expected types).
+   */
   readonly issues: Issue[]
 
+  /**
+   * Creates a new validation error from a list of issues.
+   *
+   * Issues are automatically aggregated to combine related issues at the same
+   * path (e.g., multiple type expectations from a union schema).
+   *
+   * @param issues - The validation issues that caused this error
+   * @param options - Standard Error options (e.g., `cause`)
+   */
   constructor(issues: Issue[], options?: ErrorOptions) {
     const issuesAgg = aggregateIssues(issues)
     super('InvalidRequest', issuesAgg.join(', '), options)
     this.issues = issuesAgg
   }
 
+  /**
+   * Converts the error to a JSON-serializable object.
+   *
+   * @returns An object containing the error details and all issues in JSON format
+   */
   toJSON() {
     return {
       ...super.toJSON(),
@@ -25,6 +68,23 @@ export class ValidationError extends LexError {
     }
   }
 
+  /**
+   * Creates a validation error by combining multiple validation failures.
+   *
+   * This is useful when validating against multiple possible schemas (e.g., unions)
+   * and all branches fail. The resulting error contains issues from all failures.
+   *
+   * @param failures - The validation failures to combine
+   * @returns A single validation error containing all issues from the failures
+   *
+   * @example
+   * ```typescript
+   * const failures = schemas.map(s => s.safeValidate(data)).filter(r => !r.success)
+   * if (failures.length === schemas.length) {
+   *   throw ValidationError.fromFailures(failures)
+   * }
+   * ```
+   */
   static fromFailures(
     failures: ResultFailure<ValidationError>[],
   ): ValidationError {

package/src/core/validation-issue.ts

@@ -1,6 +1,17 @@
 import { ifCid, isPlainObject } from '@atproto/lex-data'
 import { PropertyKey } from './property-key.js'
 
+/**
+ * Abstract base class for all validation issues.
+ *
+ * An issue represents a single validation failure, containing:
+ * - A code identifying the type of issue
+ * - The path to the invalid value in the data structure
+ * - The actual input value that failed validation
+ *
+ * Subclasses add specific properties relevant to each issue type and
+ * implement the {@link toString} method for human-readable error messages.
+ */
 export abstract class Issue {
   constructor(
     readonly code: string,
@@ -8,8 +19,16 @@ export abstract class Issue {
     readonly input: unknown,
   ) {}
 
+  /**
+   * Returns a human-readable description of the validation issue.
+   */
   abstract toString(): string
 
+  /**
+   * Converts the issue to a JSON-serializable object.
+   *
+   * @returns An object containing the issue code, path, and message
+   */
   toJSON() {
     return {
       code: this.code,
@@ -19,6 +38,11 @@ export abstract class Issue {
   }
 }
 
+/**
+ * A custom validation issue with a user-defined message.
+ *
+ * Use this for validation rules that don't fit into the standard issue categories.
+ */
 export class IssueCustom extends Issue {
   constructor(
     readonly path: readonly PropertyKey[],
@@ -33,6 +57,11 @@ export class IssueCustom extends Issue {
   }
 }
 
+/**
+ * Issue for string values that don't match an expected format.
+ *
+ * Used for AT Protocol specific formats like DID, handle, NSID, AT-URI, etc.
+ */
 export class IssueInvalidFormat extends Issue {
   constructor(
     path: readonly PropertyKey[],
@@ -54,6 +83,7 @@ export class IssueInvalidFormat extends Issue {
     }
   }
 
+  /** Returns a human-readable description of the expected format. */
   get formatDescription(): string {
     switch (this.format) {
       case 'at-identifier':
@@ -74,6 +104,12 @@ export class IssueInvalidFormat extends Issue {
   }
 }
 
+/**
+ * Issue for values that have an unexpected type.
+ *
+ * This is one of the most common validation issues, occurring when the
+ * runtime type of a value doesn't match the expected schema type.
+ */
 export class IssueInvalidType extends Issue {
   constructor(
     path: readonly PropertyKey[],
@@ -95,6 +131,12 @@ export class IssueInvalidType extends Issue {
   }
 }
 
+/**
+ * Issue for values that don't match any of the expected literal values.
+ *
+ * Used when a value must be one of a specific set of allowed values
+ * (e.g., enum-like constraints).
+ */
 export class IssueInvalidValue extends Issue {
   constructor(
     path: readonly PropertyKey[],
@@ -116,6 +158,9 @@ export class IssueInvalidValue extends Issue {
   }
 }
 
+/**
+ * Issue for missing required object properties.
+ */
 export class IssueRequiredKey extends Issue {
   constructor(
     path: readonly PropertyKey[],
@@ -137,6 +182,16 @@ export class IssueRequiredKey extends Issue {
   }
 }
 
+/**
+ * The type of measurement for size constraint issues.
+ *
+ * - `'array'` - Array length
+ * - `'string'` - String length in characters
+ * - `'integer'` - Numeric value
+ * - `'grapheme'` - String length in grapheme clusters
+ * - `'bytes'` - Byte length
+ * - `'blob'` - Blob size
+ */
 export type MeasurableType =
   | 'array'
   | 'string'
@@ -145,6 +200,9 @@ export type MeasurableType =
   | 'bytes'
   | 'blob'
 
+/**
+ * Issue for values that exceed a maximum constraint.
+ */
 export class IssueTooBig extends Issue {
   constructor(
     path: readonly PropertyKey[],
@@ -169,6 +227,9 @@ export class IssueTooBig extends Issue {
   }
 }
 
+/**
+ * Issue for values that are below a minimum constraint.
+ */
 export class IssueTooSmall extends Issue {
   constructor(
     path: readonly PropertyKey[],
@@ -193,6 +254,10 @@ export class IssueTooSmall extends Issue {
   }
 }
 
+// -----------------------------------------------------------------------------
+// Helper functions for formatting error messages
+// -----------------------------------------------------------------------------
+
 function stringifyExpectedType(expected: string): string {
   if (expected === '$typed') {
     return 'an object or record which includes a "$type" property'