@atproto/lex-schema 0.0.11 → 0.0.13

package/dist/core/types.d.ts

@@ -1,28 +1,115 @@
 /**
- * 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<{
     -readonly [K in keyof P as undefined extends P[K] ? never : K]-?: P[K];
 } & {
     -readonly [K in keyof P as undefined extends P[K] ? K : never]?: P[K];
 }>;
+/**
+ * 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/dist/core/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,WAAW,CAAC,OAAO,CAAC,CAAA;AAEzD,MAAM,MAAM,QAAQ,CAAC,CAAC,IAAI;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;CAAE,GAAG,WAAW,CAAC,OAAO,CAAC,CAAA;AAEzE,OAAO,CAAC,MAAM,YAAY,EAAE,OAAO,MAAM,CAAA;AACzC;;;GAGG;AACH,MAAM,MAAM,UAAU,CAAC,OAAO,SAAS,MAAM,IAAI,OAAO,YAAY,GAAG;IACrE,CAAC,YAAY,CAAC,EAAE,OAAO,CAAA;CACxB,CAAA;AAED;;;GAGG;AACH,MAAM,MAAM,sBAAsB,CAAC,CAAC,IAAI,QAAQ,CAC9C;IACE,CAAC,UAAU,CAAC,IAAI,MAAM,CAAC,IAAI,SAAS,SAAS,CAAC,CAAC,CAAC,CAAC,GAAG,KAAK,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;CACvE,GAAG;IACF,CAAC,UAAU,CAAC,IAAI,MAAM,CAAC,IAAI,SAAS,SAAS,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;CACtE,CACF,CAAA;AAED,MAAM,MAAM,OAAO,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,CAAC,IAAI;KACzC,EAAE,IAAI,MAAM,CAAC,IAAI,EAAE,SAAS,CAAC,GAAG,KAAK,GAAG,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC;CACpD,CAAA"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,WAAW,CAAC,OAAO,CAAC,CAAA;AAEzD;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,QAAQ,CAAC,CAAC,IAAI;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;CAAE,GAAG,WAAW,CAAC,OAAO,CAAC,CAAA;AAEzE;;;GAGG;AACH,OAAO,CAAC,MAAM,YAAY,EAAE,OAAO,MAAM,CAAA;AAEzC;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,MAAM,UAAU,CAAC,OAAO,SAAS,MAAM,IAAI,OAAO,YAAY,GAAG;IACrE,CAAC,YAAY,CAAC,EAAE,OAAO,CAAA;CACxB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,MAAM,sBAAsB,CAAC,CAAC,IAAI,QAAQ,CAC9C;IACE,CAAC,UAAU,CAAC,IAAI,MAAM,CAAC,IAAI,SAAS,SAAS,CAAC,CAAC,CAAC,CAAC,GAAG,KAAK,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;CACvE,GAAG;IACF,CAAC,UAAU,CAAC,IAAI,MAAM,CAAC,IAAI,SAAS,SAAS,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;CACtE,CACF,CAAA;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,OAAO,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,CAAC,IAAI;KACzC,EAAE,IAAI,MAAM,CAAC,IAAI,EAAE,SAAS,CAAC,GAAG,KAAK,GAAG,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC;CACpD,CAAA"}

package/dist/core/types.js.map

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

package/dist/core/validation-error.d.ts

@@ -1,10 +1,53 @@
 import { LexError } from '@atproto/lex-data';
 import { ResultFailure } from './result.js';
 import { Issue } 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 declare class ValidationError extends LexError {
     name: string;
+    /**
+     * 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);
+    /**
+     * Converts the error to a JSON-serializable object.
+     *
+     * @returns An object containing the error details and all issues in JSON format
+     */
     toJSON(): {
         issues: {
             code: string;
@@ -14,6 +57,23 @@ export declare class ValidationError extends LexError {
         error: import("@atproto/lex-data").LexErrorCode;
         message?: string;
     };
+    /**
+     * 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;
 }
 //# sourceMappingURL=validation-error.d.ts.map

package/dist/core/validation-error.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validation-error.d.ts","sourceRoot":"","sources":["../../src/core/validation-error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAA;AAE5C,OAAO,EAAE,aAAa,EAAiB,MAAM,aAAa,CAAA;AAC1D,OAAO,EACL,KAAK,EAGN,MAAM,uBAAuB,CAAA;AAE9B,qBAAa,eAAgB,SAAQ,QAAQ;IAC3C,IAAI,SAAoB;IAExB,QAAQ,CAAC,MAAM,EAAE,KAAK,EAAE,CAAA;gBAEZ,MAAM,EAAE,KAAK,EAAE,EAAE,OAAO,CAAC,EAAE,YAAY;IAMnD,MAAM;;;;;;;;;IAON,MAAM,CAAC,YAAY,CACjB,QAAQ,EAAE,aAAa,CAAC,eAAe,CAAC,EAAE,GACzC,eAAe;CAQnB"}
+{"version":3,"file":"validation-error.d.ts","sourceRoot":"","sources":["../../src/core/validation-error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAA;AAE5C,OAAO,EAAE,aAAa,EAAiB,MAAM,aAAa,CAAA;AAC1D,OAAO,EACL,KAAK,EAGN,MAAM,uBAAuB,CAAA;AAE9B;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,eAAgB,SAAQ,QAAQ;IAC3C,IAAI,SAAoB;IAExB;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,EAAE,KAAK,EAAE,CAAA;IAExB;;;;;;;;OAQG;gBACS,MAAM,EAAE,KAAK,EAAE,EAAE,OAAO,CAAC,EAAE,YAAY;IAMnD;;;;OAIG;IACH,MAAM;;;;;;;;;IAON;;;;;;;;;;;;;;;;OAgBG;IACH,MAAM,CAAC,YAAY,CACjB,QAAQ,EAAE,aAAa,CAAC,eAAe,CAAC,EAAE,GACzC,eAAe;CAQnB"}

package/dist/core/validation-error.js

@@ -5,20 +5,80 @@ const lex_data_1 = require("@atproto/lex-data");
 const array_agg_js_1 = require("../util/array-agg.js");
 const result_js_1 = require("./result.js");
 const validation_issue_js_1 = require("./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: [...] }
+ * ```
+ */
 class ValidationError extends lex_data_1.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).
+     */
     issues;
+    /**
+     * 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, options) {
         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(),
             issues: this.issues.map((issue) => issue.toJSON()),
         };
     }
+    /**
+     * 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) {
         if (failures.length === 1)
             return (0, result_js_1.failureReason)(failures[0]);

package/dist/core/validation-error.js.map

@@ -1 +1 @@
-{"version":3,"file":"validation-error.js","sourceRoot":"","sources":["../../src/core/validation-error.ts"],"names":[],"mappings":"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","sourcesContent":["import { LexError } from '@atproto/lex-data'\nimport { arrayAgg } from '../util/array-agg.js'\nimport { ResultFailure, failureReason } from './result.js'\nimport {\n  Issue,\n  IssueInvalidType,\n  IssueInvalidValue,\n} from './validation-issue.js'\n\nexport class ValidationError extends LexError {\n  name = 'ValidationError'\n\n  readonly issues: Issue[]\n\n  constructor(issues: Issue[], options?: ErrorOptions) {\n    const issuesAgg = aggregateIssues(issues)\n    super('InvalidRequest', issuesAgg.join(', '), options)\n    this.issues = issuesAgg\n  }\n\n  toJSON() {\n    return {\n      ...super.toJSON(),\n      issues: this.issues.map((issue) => issue.toJSON()),\n    }\n  }\n\n  static fromFailures(\n    failures: ResultFailure<ValidationError>[],\n  ): ValidationError {\n    if (failures.length === 1) return failureReason(failures[0])\n    const issues = failures.flatMap(extractFailureIssues)\n    return new ValidationError(issues, {\n      // Keep the original errors as the cause chain\n      cause: failures.map(failureReason),\n    })\n  }\n}\n\nfunction extractFailureIssues(result: ResultFailure<ValidationError>) {\n  return result.reason.issues\n}\n\nfunction aggregateIssues(issues: Issue[]): Issue[] {\n  // Quick path for common cases\n  if (issues.length <= 1) return issues\n  if (issues.length === 2 && issues[0].code !== issues[1].code) return issues\n\n  return [\n    // Aggregate invalid_type with identical paths\n    ...arrayAgg(\n      issues.filter((issue) => issue instanceof IssueInvalidType),\n      (a, b) => comparePropertyPaths(a.path, b.path),\n      (issues) =>\n        new IssueInvalidType(\n          issues[0].path,\n          issues[0].input,\n          Array.from(new Set(issues.flatMap((iss) => iss.expected))),\n        ),\n    ),\n    // Aggregate invalid_value with identical paths\n    ...arrayAgg(\n      issues.filter((issue) => issue instanceof IssueInvalidValue),\n      (a, b) => comparePropertyPaths(a.path, b.path),\n      (issues) =>\n        new IssueInvalidValue(\n          issues[0].path,\n          issues[0].input,\n          Array.from(new Set(issues.flatMap((iss) => iss.values))),\n        ),\n    ),\n    // Pass through other issues\n    ...issues.filter(\n      (issue) =>\n        !(issue instanceof IssueInvalidType) &&\n        !(issue instanceof IssueInvalidValue),\n    ),\n  ]\n}\n\n/*@__NO_SIDE_EFFECTS__*/\nfunction comparePropertyPaths(\n  a: readonly PropertyKey[],\n  b: readonly PropertyKey[],\n) {\n  if (a.length !== b.length) return false\n  for (let i = 0; i < a.length; i++) {\n    if (a[i] !== b[i]) return false\n  }\n  return true\n}\n"]}
+{"version":3,"file":"validation-error.js","sourceRoot":"","sources":["../../src/core/validation-error.ts"],"names":[],"mappings":"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","sourcesContent":["import { LexError } from '@atproto/lex-data'\nimport { arrayAgg } from '../util/array-agg.js'\nimport { ResultFailure, failureReason } from './result.js'\nimport {\n  Issue,\n  IssueInvalidType,\n  IssueInvalidValue,\n} from './validation-issue.js'\n\n/**\n * Error thrown when validation fails.\n *\n * Contains detailed information about all validation issues encountered,\n * including the path to each invalid value and descriptions of what was\n * expected vs what was received.\n *\n * Extends {@link LexError} with the error name \"InvalidRequest\" for\n * consistency with the AT Protocol error handling conventions.\n *\n * @example\n * ```typescript\n * const error = new ValidationError([\n *   new IssueInvalidType(['user', 'age'], 'hello', ['number'])\n * ])\n * console.log(error.message)\n * // \"Expected number value type at $.user.age (got string)\"\n *\n * console.log(error.issues.length) // 1\n * console.log(error.toJSON())\n * // { error: 'InvalidRequest', message: '...', issues: [...] }\n * ```\n */\nexport class ValidationError extends LexError {\n  name = 'ValidationError'\n\n  /**\n   * The list of validation issues that caused this error.\n   *\n   * Issues are aggregated when possible (e.g., multiple invalid type issues\n   * at the same path are combined into a single issue listing all expected types).\n   */\n  readonly issues: Issue[]\n\n  /**\n   * Creates a new validation error from a list of issues.\n   *\n   * Issues are automatically aggregated to combine related issues at the same\n   * path (e.g., multiple type expectations from a union schema).\n   *\n   * @param issues - The validation issues that caused this error\n   * @param options - Standard Error options (e.g., `cause`)\n   */\n  constructor(issues: Issue[], options?: ErrorOptions) {\n    const issuesAgg = aggregateIssues(issues)\n    super('InvalidRequest', issuesAgg.join(', '), options)\n    this.issues = issuesAgg\n  }\n\n  /**\n   * Converts the error to a JSON-serializable object.\n   *\n   * @returns An object containing the error details and all issues in JSON format\n   */\n  toJSON() {\n    return {\n      ...super.toJSON(),\n      issues: this.issues.map((issue) => issue.toJSON()),\n    }\n  }\n\n  /**\n   * Creates a validation error by combining multiple validation failures.\n   *\n   * This is useful when validating against multiple possible schemas (e.g., unions)\n   * and all branches fail. The resulting error contains issues from all failures.\n   *\n   * @param failures - The validation failures to combine\n   * @returns A single validation error containing all issues from the failures\n   *\n   * @example\n   * ```typescript\n   * const failures = schemas.map(s => s.safeValidate(data)).filter(r => !r.success)\n   * if (failures.length === schemas.length) {\n   *   throw ValidationError.fromFailures(failures)\n   * }\n   * ```\n   */\n  static fromFailures(\n    failures: ResultFailure<ValidationError>[],\n  ): ValidationError {\n    if (failures.length === 1) return failureReason(failures[0])\n    const issues = failures.flatMap(extractFailureIssues)\n    return new ValidationError(issues, {\n      // Keep the original errors as the cause chain\n      cause: failures.map(failureReason),\n    })\n  }\n}\n\nfunction extractFailureIssues(result: ResultFailure<ValidationError>) {\n  return result.reason.issues\n}\n\nfunction aggregateIssues(issues: Issue[]): Issue[] {\n  // Quick path for common cases\n  if (issues.length <= 1) return issues\n  if (issues.length === 2 && issues[0].code !== issues[1].code) return issues\n\n  return [\n    // Aggregate invalid_type with identical paths\n    ...arrayAgg(\n      issues.filter((issue) => issue instanceof IssueInvalidType),\n      (a, b) => comparePropertyPaths(a.path, b.path),\n      (issues) =>\n        new IssueInvalidType(\n          issues[0].path,\n          issues[0].input,\n          Array.from(new Set(issues.flatMap((iss) => iss.expected))),\n        ),\n    ),\n    // Aggregate invalid_value with identical paths\n    ...arrayAgg(\n      issues.filter((issue) => issue instanceof IssueInvalidValue),\n      (a, b) => comparePropertyPaths(a.path, b.path),\n      (issues) =>\n        new IssueInvalidValue(\n          issues[0].path,\n          issues[0].input,\n          Array.from(new Set(issues.flatMap((iss) => iss.values))),\n        ),\n    ),\n    // Pass through other issues\n    ...issues.filter(\n      (issue) =>\n        !(issue instanceof IssueInvalidType) &&\n        !(issue instanceof IssueInvalidValue),\n    ),\n  ]\n}\n\n/*@__NO_SIDE_EFFECTS__*/\nfunction comparePropertyPaths(\n  a: readonly PropertyKey[],\n  b: readonly PropertyKey[],\n) {\n  if (a.length !== b.length) return false\n  for (let i = 0; i < a.length; i++) {\n    if (a[i] !== b[i]) return false\n  }\n  return true\n}\n"]}

package/dist/core/validation-issue.d.ts

@@ -1,16 +1,40 @@
 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 declare abstract class Issue {
     readonly code: string;
     readonly path: readonly PropertyKey[];
     readonly input: unknown;
     constructor(code: string, path: readonly PropertyKey[], 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(): {
         code: string;
         path: readonly PropertyKey[];
         message: string;
     };
 }
+/**
+ * A custom validation issue with a user-defined message.
+ *
+ * Use this for validation rules that don't fit into the standard issue categories.
+ */
 export declare class IssueCustom extends Issue {
     readonly path: readonly PropertyKey[];
     readonly input: unknown;
@@ -18,6 +42,11 @@ export declare class IssueCustom extends Issue {
     constructor(path: readonly PropertyKey[], input: unknown, message: string);
     toString(): string;
 }
+/**
+ * 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 declare class IssueInvalidFormat extends Issue {
     readonly format: string;
     readonly message?: string | undefined;
@@ -29,8 +58,15 @@ export declare class IssueInvalidFormat extends Issue {
         path: readonly PropertyKey[];
         message: string;
     };
+    /** Returns a human-readable description of the expected format. */
     get formatDescription(): string;
 }
+/**
+ * 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 declare class IssueInvalidType extends Issue {
     readonly expected: readonly string[];
     constructor(path: readonly PropertyKey[], input: unknown, expected: readonly string[]);
@@ -42,6 +78,12 @@ export declare class IssueInvalidType extends Issue {
         message: string;
     };
 }
+/**
+ * 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 declare class IssueInvalidValue extends Issue {
     readonly values: readonly unknown[];
     constructor(path: readonly PropertyKey[], input: unknown, values: readonly unknown[]);
@@ -53,6 +95,9 @@ export declare class IssueInvalidValue extends Issue {
         message: string;
     };
 }
+/**
+ * Issue for missing required object properties.
+ */
 export declare class IssueRequiredKey extends Issue {
     readonly key: PropertyKey;
     constructor(path: readonly PropertyKey[], input: unknown, key: PropertyKey);
@@ -64,7 +109,20 @@ export declare class IssueRequiredKey extends Issue {
         message: string;
     };
 }
+/**
+ * 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' | 'integer' | 'grapheme' | 'bytes' | 'blob';
+/**
+ * Issue for values that exceed a maximum constraint.
+ */
 export declare class IssueTooBig extends Issue {
     readonly maximum: number;
     readonly type: MeasurableType;
@@ -79,6 +137,9 @@ export declare class IssueTooBig extends Issue {
         message: string;
     };
 }
+/**
+ * Issue for values that are below a minimum constraint.
+ */
 export declare class IssueTooSmall extends Issue {
     readonly minimum: number;
     readonly type: MeasurableType;

package/dist/core/validation-issue.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validation-issue.d.ts","sourceRoot":"","sources":["../../src/core/validation-issue.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAE/C,8BAAsB,KAAK;IAEvB,QAAQ,CAAC,IAAI,EAAE,MAAM;IACrB,QAAQ,CAAC,IAAI,EAAE,SAAS,WAAW,EAAE;IACrC,QAAQ,CAAC,KAAK,EAAE,OAAO;gBAFd,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,SAAS,WAAW,EAAE,EAC5B,KAAK,EAAE,OAAO;IAGzB,QAAQ,CAAC,QAAQ,IAAI,MAAM;IAE3B,MAAM;;;;;CAOP;AAED,qBAAa,WAAY,SAAQ,KAAK;IAElC,QAAQ,CAAC,IAAI,EAAE,SAAS,WAAW,EAAE;IACrC,QAAQ,CAAC,KAAK,EAAE,OAAO;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM;gBAFf,IAAI,EAAE,SAAS,WAAW,EAAE,EAC5B,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,MAAM;IAK1B,QAAQ;CAGT;AAED,qBAAa,kBAAmB,SAAQ,KAAK;IAIzC,QAAQ,CAAC,MAAM,EAAE,MAAM;IACvB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM;gBAHzB,IAAI,EAAE,SAAS,WAAW,EAAE,EAC5B,KAAK,EAAE,OAAO,EACL,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,MAAM,YAAA;IAK3B,QAAQ;IAIR,MAAM;;;;;;IAON,IAAI,iBAAiB,IAAI,MAAM,CAiB9B;CACF;AAED,qBAAa,gBAAiB,SAAQ,KAAK;IAIvC,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE;gBAFpC,IAAI,EAAE,SAAS,WAAW,EAAE,EAC5B,KAAK,EAAE,OAAO,EACL,QAAQ,EAAE,SAAS,MAAM,EAAE;IAKtC,QAAQ;IAIR,MAAM;;;;;;CAMP;AAED,qBAAa,iBAAkB,SAAQ,KAAK;IAIxC,QAAQ,CAAC,MAAM,EAAE,SAAS,OAAO,EAAE;gBAFnC,IAAI,EAAE,SAAS,WAAW,EAAE,EAC5B,KAAK,EAAE,OAAO,EACL,MAAM,EAAE,SAAS,OAAO,EAAE;IAKrC,QAAQ;IAIR,MAAM;;;;;;CAMP;AAED,qBAAa,gBAAiB,SAAQ,KAAK;IAIvC,QAAQ,CAAC,GAAG,EAAE,WAAW;gBAFzB,IAAI,EAAE,SAAS,WAAW,EAAE,EAC5B,KAAK,EAAE,OAAO,EACL,GAAG,EAAE,WAAW;IAK3B,QAAQ;IAIR,MAAM;;;;;;CAMP;AAED,MAAM,MAAM,cAAc,GACtB,OAAO,GACP,QAAQ,GACR,SAAS,GACT,UAAU,GACV,OAAO,GACP,MAAM,CAAA;AAEV,qBAAa,WAAY,SAAQ,KAAK;IAIlC,QAAQ,CAAC,OAAO,EAAE,MAAM;IACxB,QAAQ,CAAC,IAAI,EAAE,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM;gBAJvB,IAAI,EAAE,SAAS,WAAW,EAAE,EAC5B,KAAK,EAAE,OAAO,EACL,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,cAAc,EACpB,MAAM,EAAE,MAAM;IAKzB,QAAQ;IAIR,MAAM;;;;;;;CAOP;AAED,qBAAa,aAAc,SAAQ,KAAK;IAIpC,QAAQ,CAAC,OAAO,EAAE,MAAM;IACxB,QAAQ,CAAC,IAAI,EAAE,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM;gBAJvB,IAAI,EAAE,SAAS,WAAW,EAAE,EAC5B,KAAK,EAAE,OAAO,EACL,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,cAAc,EACpB,MAAM,EAAE,MAAM;IAKzB,QAAQ;IAIR,MAAM;;;;;;;CAOP"}
+{"version":3,"file":"validation-issue.d.ts","sourceRoot":"","sources":["../../src/core/validation-issue.ts"],"names":[],"mappings":"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"}

package/dist/core/validation-issue.js

@@ -2,6 +2,17 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.IssueTooSmall = exports.IssueTooBig = exports.IssueRequiredKey = exports.IssueInvalidValue = exports.IssueInvalidType = exports.IssueInvalidFormat = exports.IssueCustom = exports.Issue = void 0;
 const lex_data_1 = require("@atproto/lex-data");
+/**
+ * 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.
+ */
 class Issue {
     code;
     path;
@@ -11,6 +22,11 @@ class Issue {
         this.path = path;
         this.input = input;
     }
+    /**
+     * Converts the issue to a JSON-serializable object.
+     *
+     * @returns An object containing the issue code, path, and message
+     */
     toJSON() {
         return {
             code: this.code,
@@ -20,6 +36,11 @@ class Issue {
     }
 }
 exports.Issue = Issue;
+/**
+ * A custom validation issue with a user-defined message.
+ *
+ * Use this for validation rules that don't fit into the standard issue categories.
+ */
 class IssueCustom extends Issue {
     path;
     input;
@@ -35,6 +56,11 @@ class IssueCustom extends Issue {
     }
 }
 exports.IssueCustom = IssueCustom;
+/**
+ * Issue for string values that don't match an expected format.
+ *
+ * Used for AT Protocol specific formats like DID, handle, NSID, AT-URI, etc.
+ */
 class IssueInvalidFormat extends Issue {
     format;
     message;
@@ -52,6 +78,7 @@ class IssueInvalidFormat extends Issue {
             format: this.format,
         };
     }
+    /** Returns a human-readable description of the expected format. */
     get formatDescription() {
         switch (this.format) {
             case 'at-identifier':
@@ -72,6 +99,12 @@ class IssueInvalidFormat extends Issue {
     }
 }
 exports.IssueInvalidFormat = IssueInvalidFormat;
+/**
+ * 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.
+ */
 class IssueInvalidType extends Issue {
     expected;
     constructor(path, input, expected) {
@@ -89,6 +122,12 @@ class IssueInvalidType extends Issue {
     }
 }
 exports.IssueInvalidType = IssueInvalidType;
+/**
+ * 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).
+ */
 class IssueInvalidValue extends Issue {
     values;
     constructor(path, input, values) {
@@ -106,6 +145,9 @@ class IssueInvalidValue extends Issue {
     }
 }
 exports.IssueInvalidValue = IssueInvalidValue;
+/**
+ * Issue for missing required object properties.
+ */
 class IssueRequiredKey extends Issue {
     key;
     constructor(path, input, key) {
@@ -123,6 +165,9 @@ class IssueRequiredKey extends Issue {
     }
 }
 exports.IssueRequiredKey = IssueRequiredKey;
+/**
+ * Issue for values that exceed a maximum constraint.
+ */
 class IssueTooBig extends Issue {
     maximum;
     type;
@@ -145,6 +190,9 @@ class IssueTooBig extends Issue {
     }
 }
 exports.IssueTooBig = IssueTooBig;
+/**
+ * Issue for values that are below a minimum constraint.
+ */
 class IssueTooSmall extends Issue {
     minimum;
     type;
@@ -167,9 +215,12 @@ class IssueTooSmall extends Issue {
     }
 }
 exports.IssueTooSmall = IssueTooSmall;
+// -----------------------------------------------------------------------------
+// Helper functions for formatting error messages
+// -----------------------------------------------------------------------------
 function stringifyExpectedType(expected) {
     if (expected === '$typed') {
-        return 'an object or record which includes a "$type" property';
+        return 'an object which includes the "$type" property';
     }
     return expected;
 }
@@ -206,6 +257,8 @@ function stringifyType(value) {
                 return 'array';
             if ((0, lex_data_1.ifCid)(value))
                 return 'cid';
+            if ((0, lex_data_1.isLegacyBlobRef)(value))
+                return 'legacy-blob';
             if (value instanceof Date)
                 return 'date';
             if (value instanceof RegExp)