@atproto/lex-schema 0.0.11 → 0.0.13

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 { ifCid, isLegacyBlobRef, 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,9 +254,13 @@ 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'
+    return 'an object which includes the "$type" property'
   }
   return expected
 }
@@ -230,6 +295,7 @@ function stringifyType(value: unknown): string {
       if (value === null) return 'null'
       if (Array.isArray(value)) return 'array'
       if (ifCid(value)) return 'cid'
+      if (isLegacyBlobRef(value)) return 'legacy-blob'
       if (value instanceof Date) return 'date'
       if (value instanceof RegExp) return 'regexp'
       if (value instanceof Map) return 'map'