@atproto/lex-schema 0.0.10 → 0.0.12

package/dist/schema/token.js.map

@@ -1 +1 @@
-{"version":3,"file":"token.js","sourceRoot":"","sources":["../../src/schema/token.ts"],"names":[],"mappings":";;;AAwCA,sBAKC;AA7CD,wCAAyE;AAEzE,MAAa,WAEX,SAAQ,gBAAc;IACD;IAArB,YAAqB,KAAa;QAChC,KAAK,EAAE,CAAA;QADY,UAAK,GAAL,KAAK,CAAQ;IAElC,CAAC;IAED,iBAAiB,CAAC,KAAc,EAAE,GAAsB;QACtD,IAAI,KAAK,KAAK,IAAI,CAAC,KAAK,EAAE,CAAC;YACzB,OAAO,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;QAChC,CAAC;QAED,0EAA0E;QAC1E,eAAe;QACf,IAAI,KAAK,YAAY,WAAW,IAAI,KAAK,CAAC,KAAK,KAAK,IAAI,CAAC,KAAK,EAAE,CAAC;YAC/D,OAAO,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;QAChC,CAAC;QAED,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YAC9B,OAAO,GAAG,CAAC,gBAAgB,CAAC,KAAK,EAAE,OAAO,CAAC,CAAA;QAC7C,CAAC;QAED,OAAO,GAAG,CAAC,iBAAiB,CAAC,KAAK,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAA;IACnD,CAAC;IAED,yEAAyE;IACzE,cAAc;IAEd,MAAM;QACJ,OAAO,IAAI,CAAC,KAAK,CAAA;IACnB,CAAC;IAED,QAAQ;QACN,OAAO,IAAI,CAAC,KAAK,CAAA;IACnB,CAAC;CACF;AAnCD,kCAmCC;AAED,wBAAwB;AACxB,SAAgB,KAAK,CAGnB,IAAO,EAAE,OAAU,MAAW;IAC9B,OAAO,IAAI,WAAW,CAAC,IAAA,eAAK,EAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAA;AAC3C,CAAC","sourcesContent":["import { $type, NsidString, Schema, ValidationContext } from '../core.js'\n\nexport class TokenSchema<\n  const TValue extends string = string,\n> extends Schema<TValue> {\n  constructor(readonly value: TValue) {\n    super()\n  }\n\n  validateInContext(input: unknown, ctx: ValidationContext) {\n    if (input === this.value) {\n      return ctx.success(this.value)\n    }\n\n    // @NOTE: allow using the token instance itself (but convert to the actual\n    // token value)\n    if (input instanceof TokenSchema && input.value === this.value) {\n      return ctx.success(this.value)\n    }\n\n    if (typeof input !== 'string') {\n      return ctx.issueInvalidType(input, 'token')\n    }\n\n    return ctx.issueInvalidValue(input, [this.value])\n  }\n\n  // When using the TokenSchema instance as data, let's serialize it to the\n  // token value\n\n  toJSON(): string {\n    return this.value\n  }\n\n  toString(): string {\n    return this.value\n  }\n}\n\n/*@__NO_SIDE_EFFECTS__*/\nexport function token<\n  const N extends NsidString,\n  const H extends string = 'main',\n>(nsid: N, hash: H = 'main' as H) {\n  return new TokenSchema($type(nsid, hash))\n}\n"]}
+{"version":3,"file":"token.js","sourceRoot":"","sources":["../../src/schema/token.ts"],"names":[],"mappings":";;;AAuFA,sBAKC;AA5FD,wCAAyE;AAEzE;;;;;;;;;;;;;;GAcG;AACH,MAAa,WAEX,SAAQ,gBAAc;IACD;IAArB,YAAqB,KAAa;QAChC,KAAK,EAAE,CAAA;QADY,UAAK,GAAL,KAAK,CAAQ;IAElC,CAAC;IAED,iBAAiB,CAAC,KAAc,EAAE,GAAsB;QACtD,IAAI,KAAK,KAAK,IAAI,CAAC,KAAK,EAAE,CAAC;YACzB,OAAO,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;QAChC,CAAC;QAED,0EAA0E;QAC1E,eAAe;QACf,IAAI,KAAK,YAAY,WAAW,IAAI,KAAK,CAAC,KAAK,KAAK,IAAI,CAAC,KAAK,EAAE,CAAC;YAC/D,OAAO,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;QAChC,CAAC;QAED,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YAC9B,OAAO,GAAG,CAAC,gBAAgB,CAAC,KAAK,EAAE,OAAO,CAAC,CAAA;QAC7C,CAAC;QAED,OAAO,GAAG,CAAC,iBAAiB,CAAC,KAAK,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAA;IACnD,CAAC;IAED,yEAAyE;IACzE,cAAc;IAEd,MAAM;QACJ,OAAO,IAAI,CAAC,KAAK,CAAA;IACnB,CAAC;IAED,QAAQ;QACN,OAAO,IAAI,CAAC,KAAK,CAAA;IACnB,CAAC;CACF;AAnCD,kCAmCC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAwB;AACxB,SAAgB,KAAK,CAGnB,IAAO,EAAE,OAAU,MAAW;IAC9B,OAAO,IAAI,WAAW,CAAC,IAAA,eAAK,EAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAA;AAC3C,CAAC","sourcesContent":["import { $type, NsidString, Schema, ValidationContext } from '../core.js'\n\n/**\n * Schema for Lexicon token values.\n *\n * Tokens are named constants in Lexicon, identified by their NSID and hash.\n * They validate to their string value (e.g., 'app.bsky.feed.defs#requestLess').\n * TokenSchema instances can also be used as values themselves.\n *\n * @template TValue - The token string literal type\n *\n * @example\n * ```ts\n * const schema = new TokenSchema('app.bsky.feed.defs#requestLess')\n * schema.validate('app.bsky.feed.defs#requestLess') // success\n * ```\n */\nexport class TokenSchema<\n  const TValue extends string = string,\n> extends Schema<TValue> {\n  constructor(readonly value: TValue) {\n    super()\n  }\n\n  validateInContext(input: unknown, ctx: ValidationContext) {\n    if (input === this.value) {\n      return ctx.success(this.value)\n    }\n\n    // @NOTE: allow using the token instance itself (but convert to the actual\n    // token value)\n    if (input instanceof TokenSchema && input.value === this.value) {\n      return ctx.success(this.value)\n    }\n\n    if (typeof input !== 'string') {\n      return ctx.issueInvalidType(input, 'token')\n    }\n\n    return ctx.issueInvalidValue(input, [this.value])\n  }\n\n  // When using the TokenSchema instance as data, let's serialize it to the\n  // token value\n\n  toJSON(): string {\n    return this.value\n  }\n\n  toString(): string {\n    return this.value\n  }\n}\n\n/**\n * Creates a token schema for Lexicon named constants.\n *\n * Tokens are used in Lexicon as named constants or enum-like values.\n * The token instance can be used both as a schema validator and as\n * the token value itself (it serializes to its string value).\n *\n * @param nsid - The NSID part of the token\n * @param hash - The hash part of the token (defaults to 'main')\n * @returns A new {@link TokenSchema} instance\n *\n * @example\n * ```ts\n * // Define tokens\n * const requestLess = l.token('app.bsky.feed.defs', 'requestLess')\n * const requestMore = l.token('app.bsky.feed.defs', 'requestMore')\n *\n * // Use as a value\n * console.log(requestLess.toString()) // 'app.bsky.feed.defs#requestLess'\n *\n * // Use in union for validation\n * const feedbackSchema = l.union([requestLess, requestMore])\n *\n * // Validate\n * feedbackSchema.parse('app.bsky.feed.defs#requestLess') // success\n *\n * // Token instances can be used as values in other schemas\n * const feedbackRequest = l.object({\n *   feedback: requestLess, // Accepts the token value\n * })\n * ```\n */\n/*@__NO_SIDE_EFFECTS__*/\nexport function token<\n  const N extends NsidString,\n  const H extends string = 'main',\n>(nsid: N, hash: H = 'main' as H) {\n  return new TokenSchema($type(nsid, hash))\n}\n"]}

package/dist/schema/typed-object.d.ts

@@ -1,4 +1,22 @@
 import { $Type, $TypeOf, $Typed, $TypedMaybe, InferInput, InferOutput, NsidString, Schema, Unknown$TypedObject, ValidationContext, Validator } from '../core.js';
+/**
+ * Schema for typed objects in Lexicon unions.
+ *
+ * Typed objects have a `$type` field that identifies which variant they are
+ * in a union. The `$type` can be omitted in input (it's implicit), but if
+ * present, it must match the expected value.
+ *
+ * @template TType - The $type string literal type
+ * @template TShape - The validator type for the object's shape
+ *
+ * @example
+ * ```ts
+ * const schema = new TypedObjectSchema(
+ *   'app.bsky.embed.images#view',
+ *   l.object({ images: l.array(imageSchema) })
+ * )
+ * ```
+ */
 export declare class TypedObjectSchema<const TType extends $Type = $Type, const TShape extends Validator<{
     [k: string]: unknown;
 }> = any> extends Schema<$TypedMaybe<InferInput<TShape>, TType>, $TypedMaybe<InferOutput<TShape>, TType>> {
@@ -24,15 +42,51 @@ export declare class TypedObjectSchema<const TType extends $Type = $Type, const
     validateInContext(input: unknown, ctx: ValidationContext): import("../core.js").ValidationResult<InferInput<TShape>>;
 }
 /**
+ * Creates a typed object schema for use in Lexicon unions.
+ *
+ * Typed objects are identified by their `$type` field, which combines an NSID
+ * and a hash (e.g., 'app.bsky.embed.images#view'). Used for union variants.
+ *
  * This function offers two overloads:
- * - One that allows creating a {@link TypedObjectSchema}, and infer the output
- *   type from the provided arguments, without requiring to specify any of the
- *   generics. This is useful when you want to define a record without
- *   explicitly defining its interface. This version does not support circular
- *   references, as TypeScript cannot infer types in such cases.
- * - One allows creating a {@link TypedObjectSchema} with an explicitly defined
- *   interface. This will typically be used by codegen (`lex build`) to generate
- *   schemas that work even if they contain circular references.
+ * - One that infers the type from arguments (no circular reference support)
+ * - One with explicit interface for codegen with circular references
+ *
+ * @param nsid - The NSID part of the type (e.g., 'app.bsky.embed.images')
+ * @param hash - The hash part of the type (e.g., 'view'), defaults to 'main'
+ * @param validator - Schema for validating the object properties
+ * @returns A new {@link TypedObjectSchema} instance
+ *
+ * @example
+ * ```ts
+ * // Image embed view
+ * const imageViewSchema = l.typedObject(
+ *   'app.bsky.embed.images',
+ *   'view',
+ *   l.object({
+ *     images: l.array(l.object({
+ *       thumb: l.string(),
+ *       fullsize: l.string(),
+ *       alt: l.string(),
+ *     })),
+ *   })
+ * )
+ *
+ * // Main type (hash defaults to 'main')
+ * const postViewSchema = l.typedObject(
+ *   'app.bsky.feed.defs',
+ *   'postView',
+ *   l.object({ uri: l.string(), cid: l.string(), author: authorSchema })
+ * )
+ *
+ * // Use $isTypeOf to narrow union types
+ * if (imageViewSchema.$isTypeOf(embed)) {
+ *   // embed is narrowed to image view type
+ * }
+ *
+ * // Use $build to construct typed objects
+ * const view = imageViewSchema.$build({ images: [...] })
+ * // view.$type === 'app.bsky.embed.images#view'
+ * ```
  */
 export declare function typedObject<const N extends NsidString, const H extends string, const S extends Validator<{
     [k: string]: unknown;

package/dist/schema/typed-object.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"typed-object.d.ts","sourceRoot":"","sources":["../../src/schema/typed-object.ts"],"names":[],"mappings":"AACA,OAAO,EACL,KAAK,EACL,OAAO,EACP,MAAM,EACN,WAAW,EAGX,UAAU,EACV,WAAW,EACX,UAAU,EACV,MAAM,EACN,mBAAmB,EACnB,iBAAiB,EACjB,SAAS,EACV,MAAM,YAAY,CAAA;AAEnB,qBAAa,iBAAiB,CAC5B,KAAK,CAAC,KAAK,SAAS,KAAK,GAAG,KAAK,EACjC,KAAK,CAAC,MAAM,SAAS,SAAS,CAAC;IAAE,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE,CAAC,GAAG,GAAG,CAC9D,SAAQ,MAAM,CACd,WAAW,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,KAAK,CAAC,EACtC,WAAW,CAAC,WAAW,CAAC,MAAM,CAAC,EAAE,KAAK,CAAC,CACxC;IAEG,QAAQ,CAAC,KAAK,EAAE,KAAK;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM;gBADd,KAAK,EAAE,KAAK,EACZ,MAAM,EAAE,MAAM;IAKzB,QAAQ,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACxC,KAAK,EAAE,CAAC,GACP,KAAK,IAAI,CAAC,SAAS;QAAE,KAAK,CAAC,EAAE,KAAK,CAAA;KAAE,GACnC,CAAC,GACD,WAAW,CAAC,OAAO,CAAC,CAAC,EAAE,mBAAmB,CAAC,EAAE,KAAK,CAAC;IAIvD,KAAK,CACH,KAAK,EAAE,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC,GACrC,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,EAAE,KAAK,CAAC;IAOnC,SAAS,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,KAAK,EAAE,CAAC;gBAfrB,KAAK;;;;;;IAmBrC,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;;;;;IAI7C,iBAAiB,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,iBAAiB;CAezD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CACzB,KAAK,CAAC,CAAC,SAAS,UAAU,EAC1B,KAAK,CAAC,CAAC,SAAS,MAAM,EACtB,KAAK,CAAC,CAAC,SAAS,SAAS,CAAC;IAAE,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE,CAAC,EACnD,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,GAAG,iBAAiB,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;AACpE,wBAAgB,WAAW,CAAC,CAAC,SAAS;IAAE,KAAK,CAAC,EAAE,KAAK,CAAA;CAAE,EACrD,IAAI,EAAE,CAAC,SAAS;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC,SAAS,MAAM,CAAA;CAAE,GAC9C,CAAC,SAAS,GAAG,MAAM,CAAC,IAAI,MAAM,EAAE,GAC9B,CAAC,GACD,CAAC,GACH,KAAK,EACT,IAAI,EAAE,CAAC,SAAS;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC,SAAS,MAAM,CAAA;CAAE,GAC9C,CAAC,SAAS,GAAG,MAAM,IAAI,MAAM,CAAC,EAAE,GAC9B,CAAC,GACD,MAAM,GACR,KAAK,EACT,SAAS,EAAE,SAAS,CAAC,IAAI,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,GACrC,iBAAiB,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,CAAA"}
+{"version":3,"file":"typed-object.d.ts","sourceRoot":"","sources":["../../src/schema/typed-object.ts"],"names":[],"mappings":"AACA,OAAO,EACL,KAAK,EACL,OAAO,EACP,MAAM,EACN,WAAW,EAGX,UAAU,EACV,WAAW,EACX,UAAU,EACV,MAAM,EACN,mBAAmB,EACnB,iBAAiB,EACjB,SAAS,EACV,MAAM,YAAY,CAAA;AAEnB;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,iBAAiB,CAC5B,KAAK,CAAC,KAAK,SAAS,KAAK,GAAG,KAAK,EACjC,KAAK,CAAC,MAAM,SAAS,SAAS,CAAC;IAAE,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE,CAAC,GAAG,GAAG,CAC9D,SAAQ,MAAM,CACd,WAAW,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,KAAK,CAAC,EACtC,WAAW,CAAC,WAAW,CAAC,MAAM,CAAC,EAAE,KAAK,CAAC,CACxC;IAEG,QAAQ,CAAC,KAAK,EAAE,KAAK;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM;gBADd,KAAK,EAAE,KAAK,EACZ,MAAM,EAAE,MAAM;IAKzB,QAAQ,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACxC,KAAK,EAAE,CAAC,GACP,KAAK,IAAI,CAAC,SAAS;QAAE,KAAK,CAAC,EAAE,KAAK,CAAA;KAAE,GACnC,CAAC,GACD,WAAW,CAAC,OAAO,CAAC,CAAC,EAAE,mBAAmB,CAAC,EAAE,KAAK,CAAC;IAIvD,KAAK,CACH,KAAK,EAAE,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC,GACrC,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,EAAE,KAAK,CAAC;IAOnC,SAAS,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,KAAK,EAAE,CAAC;gBAfrB,KAAK;;;;;;IAmBrC,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;;;;;IAI7C,iBAAiB,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,iBAAiB;CAezD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,wBAAgB,WAAW,CACzB,KAAK,CAAC,CAAC,SAAS,UAAU,EAC1B,KAAK,CAAC,CAAC,SAAS,MAAM,EACtB,KAAK,CAAC,CAAC,SAAS,SAAS,CAAC;IAAE,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE,CAAC,EACnD,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,GAAG,iBAAiB,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;AACpE,wBAAgB,WAAW,CAAC,CAAC,SAAS;IAAE,KAAK,CAAC,EAAE,KAAK,CAAA;CAAE,EACrD,IAAI,EAAE,CAAC,SAAS;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC,SAAS,MAAM,CAAA;CAAE,GAC9C,CAAC,SAAS,GAAG,MAAM,CAAC,IAAI,MAAM,EAAE,GAC9B,CAAC,GACD,CAAC,GACH,KAAK,EACT,IAAI,EAAE,CAAC,SAAS;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC,SAAS,MAAM,CAAA;CAAE,GAC9C,CAAC,SAAS,GAAG,MAAM,IAAI,MAAM,CAAC,EAAE,GAC9B,CAAC,GACD,MAAM,GACR,KAAK,EACT,SAAS,EAAE,SAAS,CAAC,IAAI,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,GACrC,iBAAiB,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,CAAA"}

package/dist/schema/typed-object.js

@@ -4,6 +4,24 @@ exports.TypedObjectSchema = void 0;
 exports.typedObject = typedObject;
 const lex_data_1 = require("@atproto/lex-data");
 const core_js_1 = require("../core.js");
+/**
+ * Schema for typed objects in Lexicon unions.
+ *
+ * Typed objects have a `$type` field that identifies which variant they are
+ * in a union. The `$type` can be omitted in input (it's implicit), but if
+ * present, it must match the expected value.
+ *
+ * @template TType - The $type string literal type
+ * @template TShape - The validator type for the object's shape
+ *
+ * @example
+ * ```ts
+ * const schema = new TypedObjectSchema(
+ *   'app.bsky.embed.images#view',
+ *   l.object({ images: l.array(imageSchema) })
+ * )
+ * ```
+ */
 class TypedObjectSchema extends core_js_1.Schema {
     $type;
     schema;

package/dist/schema/typed-object.js.map

@@ -1 +1 @@
-{"version":3,"file":"typed-object.js","sourceRoot":"","sources":["../../src/schema/typed-object.ts"],"names":[],"mappings":";;;AAuGA,kCAMC;AA7GD,gDAAiD;AACjD,wCAcmB;AAEnB,MAAa,iBAGX,SAAQ,gBAGT;IAEY;IACA;IAFX,YACW,KAAY,EACZ,MAAc;QAEvB,KAAK,EAAE,CAAA;QAHE,UAAK,GAAL,KAAK,CAAO;QACZ,WAAM,GAAN,MAAM,CAAQ;IAGzB,CAAC;IAED,QAAQ,CACN,KAAQ;QAIR,OAAO,KAAK,CAAC,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,KAAK,KAAK,IAAI,CAAC,KAAK,CAAA;IAChE,CAAC;IAED,KAAK,CACH,KAAsC;QAEtC,OAAO,IAAI,CAAC,KAAK,CAAC,IAAA,gBAAM,EAAC,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,CAG1C,CAAA;IACH,CAAC;IAED,SAAS,CAAoC,KAAQ;QACnD,OAAO,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAA;IAC7B,CAAC;IAED,MAAM,CAAC,KAAsC;QAC3C,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAA;IAC1B,CAAC;IAED,iBAAiB,CAAC,KAAc,EAAE,GAAsB;QACtD,IAAI,CAAC,IAAA,wBAAa,EAAC,KAAK,CAAC,EAAE,CAAC;YAC1B,OAAO,GAAG,CAAC,gBAAgB,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAA;QAC9C,CAAC;QAED,IACE,OAAO,IAAI,KAAK;YAChB,KAAK,CAAC,KAAK,KAAK,SAAS;YACzB,KAAK,CAAC,KAAK,KAAK,IAAI,CAAC,KAAK,EAC1B,CAAC;YACD,OAAO,GAAG,CAAC,yBAAyB,CAAC,KAAK,EAAE,OAAO,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAA;QACpE,CAAC;QAED,OAAO,GAAG,CAAC,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,CAAA;IACzC,CAAC;CACF;AAtDD,8CAsDC;AA+BD,wBAAwB;AACxB,SAAgB,WAAW,CAIzB,IAAO,EAAE,IAAO,EAAE,SAAY;IAC9B,OAAO,IAAI,iBAAiB,CAAiB,IAAA,eAAK,EAAC,IAAI,EAAE,IAAI,CAAC,EAAE,SAAS,CAAC,CAAA;AAC5E,CAAC","sourcesContent":["import { isPlainObject } from '@atproto/lex-data'\nimport {\n  $Type,\n  $TypeOf,\n  $Typed,\n  $TypedMaybe,\n  $type,\n  $typed,\n  InferInput,\n  InferOutput,\n  NsidString,\n  Schema,\n  Unknown$TypedObject,\n  ValidationContext,\n  Validator,\n} from '../core.js'\n\nexport class TypedObjectSchema<\n  const TType extends $Type = $Type,\n  const TShape extends Validator<{ [k: string]: unknown }> = any,\n> extends Schema<\n  $TypedMaybe<InferInput<TShape>, TType>,\n  $TypedMaybe<InferOutput<TShape>, TType>\n> {\n  constructor(\n    readonly $type: TType,\n    readonly schema: TShape,\n  ) {\n    super()\n  }\n\n  isTypeOf<X extends Record<string, unknown>>(\n    value: X,\n  ): value is X extends { $type?: TType }\n    ? X\n    : $TypedMaybe<Exclude<X, Unknown$TypedObject>, TType> {\n    return value.$type === undefined || value.$type === this.$type\n  }\n\n  build(\n    input: Omit<InferInput<this>, '$type'>,\n  ): $Typed<InferOutput<this>, TType> {\n    return this.parse($typed(input, this.$type)) as $Typed<\n      InferOutput<this>,\n      TType\n    >\n  }\n\n  $isTypeOf<X extends Record<string, unknown>>(value: X) {\n    return this.isTypeOf(value)\n  }\n\n  $build(input: Omit<InferInput<this>, '$type'>) {\n    return this.build(input)\n  }\n\n  validateInContext(input: unknown, ctx: ValidationContext) {\n    if (!isPlainObject(input)) {\n      return ctx.issueInvalidType(input, 'object')\n    }\n\n    if (\n      '$type' in input &&\n      input.$type !== undefined &&\n      input.$type !== this.$type\n    ) {\n      return ctx.issueInvalidPropertyValue(input, '$type', [this.$type])\n    }\n\n    return ctx.validate(input, this.schema)\n  }\n}\n\n/**\n * This function offers two overloads:\n * - One that allows creating a {@link TypedObjectSchema}, and infer the output\n *   type from the provided arguments, without requiring to specify any of the\n *   generics. This is useful when you want to define a record without\n *   explicitly defining its interface. This version does not support circular\n *   references, as TypeScript cannot infer types in such cases.\n * - One allows creating a {@link TypedObjectSchema} with an explicitly defined\n *   interface. This will typically be used by codegen (`lex build`) to generate\n *   schemas that work even if they contain circular references.\n */\nexport function typedObject<\n  const N extends NsidString,\n  const H extends string,\n  const S extends Validator<{ [k: string]: unknown }>,\n>(nsid: N, hash: H, validator: S): TypedObjectSchema<$Type<N, H>, S>\nexport function typedObject<V extends { $type?: $Type }>(\n  nsid: V extends { $type?: infer T extends string }\n    ? T extends `${infer N}#${string}`\n      ? N\n      : T // (T is a \"main\" type, so already an NSID)\n    : never,\n  hash: V extends { $type?: infer T extends string }\n    ? T extends `${string}#${infer H}`\n      ? H\n      : 'main'\n    : never,\n  validator: Validator<Omit<V, '$type'>>,\n): TypedObjectSchema<$TypeOf<V>, Validator<V>>\n/*@__NO_SIDE_EFFECTS__*/\nexport function typedObject<\n  const N extends NsidString,\n  const H extends string,\n  const S extends Validator<{ [k: string]: unknown }>,\n>(nsid: N, hash: H, validator: S) {\n  return new TypedObjectSchema<$Type<N, H>, S>($type(nsid, hash), validator)\n}\n"]}
+{"version":3,"file":"typed-object.js","sourceRoot":"","sources":["../../src/schema/typed-object.ts"],"names":[],"mappings":";;;AA6JA,kCAMC;AAnKD,gDAAiD;AACjD,wCAcmB;AAEnB;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAa,iBAGX,SAAQ,gBAGT;IAEY;IACA;IAFX,YACW,KAAY,EACZ,MAAc;QAEvB,KAAK,EAAE,CAAA;QAHE,UAAK,GAAL,KAAK,CAAO;QACZ,WAAM,GAAN,MAAM,CAAQ;IAGzB,CAAC;IAED,QAAQ,CACN,KAAQ;QAIR,OAAO,KAAK,CAAC,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,KAAK,KAAK,IAAI,CAAC,KAAK,CAAA;IAChE,CAAC;IAED,KAAK,CACH,KAAsC;QAEtC,OAAO,IAAI,CAAC,KAAK,CAAC,IAAA,gBAAM,EAAC,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,CAG1C,CAAA;IACH,CAAC;IAED,SAAS,CAAoC,KAAQ;QACnD,OAAO,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAA;IAC7B,CAAC;IAED,MAAM,CAAC,KAAsC;QAC3C,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAA;IAC1B,CAAC;IAED,iBAAiB,CAAC,KAAc,EAAE,GAAsB;QACtD,IAAI,CAAC,IAAA,wBAAa,EAAC,KAAK,CAAC,EAAE,CAAC;YAC1B,OAAO,GAAG,CAAC,gBAAgB,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAA;QAC9C,CAAC;QAED,IACE,OAAO,IAAI,KAAK;YAChB,KAAK,CAAC,KAAK,KAAK,SAAS;YACzB,KAAK,CAAC,KAAK,KAAK,IAAI,CAAC,KAAK,EAC1B,CAAC;YACD,OAAO,GAAG,CAAC,yBAAyB,CAAC,KAAK,EAAE,OAAO,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAA;QACpE,CAAC;QAED,OAAO,GAAG,CAAC,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,CAAA;IACzC,CAAC;CACF;AAtDD,8CAsDC;AAmED,wBAAwB;AACxB,SAAgB,WAAW,CAIzB,IAAO,EAAE,IAAO,EAAE,SAAY;IAC9B,OAAO,IAAI,iBAAiB,CAAiB,IAAA,eAAK,EAAC,IAAI,EAAE,IAAI,CAAC,EAAE,SAAS,CAAC,CAAA;AAC5E,CAAC","sourcesContent":["import { isPlainObject } from '@atproto/lex-data'\nimport {\n  $Type,\n  $TypeOf,\n  $Typed,\n  $TypedMaybe,\n  $type,\n  $typed,\n  InferInput,\n  InferOutput,\n  NsidString,\n  Schema,\n  Unknown$TypedObject,\n  ValidationContext,\n  Validator,\n} from '../core.js'\n\n/**\n * Schema for typed objects in Lexicon unions.\n *\n * Typed objects have a `$type` field that identifies which variant they are\n * in a union. The `$type` can be omitted in input (it's implicit), but if\n * present, it must match the expected value.\n *\n * @template TType - The $type string literal type\n * @template TShape - The validator type for the object's shape\n *\n * @example\n * ```ts\n * const schema = new TypedObjectSchema(\n *   'app.bsky.embed.images#view',\n *   l.object({ images: l.array(imageSchema) })\n * )\n * ```\n */\nexport class TypedObjectSchema<\n  const TType extends $Type = $Type,\n  const TShape extends Validator<{ [k: string]: unknown }> = any,\n> extends Schema<\n  $TypedMaybe<InferInput<TShape>, TType>,\n  $TypedMaybe<InferOutput<TShape>, TType>\n> {\n  constructor(\n    readonly $type: TType,\n    readonly schema: TShape,\n  ) {\n    super()\n  }\n\n  isTypeOf<X extends Record<string, unknown>>(\n    value: X,\n  ): value is X extends { $type?: TType }\n    ? X\n    : $TypedMaybe<Exclude<X, Unknown$TypedObject>, TType> {\n    return value.$type === undefined || value.$type === this.$type\n  }\n\n  build(\n    input: Omit<InferInput<this>, '$type'>,\n  ): $Typed<InferOutput<this>, TType> {\n    return this.parse($typed(input, this.$type)) as $Typed<\n      InferOutput<this>,\n      TType\n    >\n  }\n\n  $isTypeOf<X extends Record<string, unknown>>(value: X) {\n    return this.isTypeOf(value)\n  }\n\n  $build(input: Omit<InferInput<this>, '$type'>) {\n    return this.build(input)\n  }\n\n  validateInContext(input: unknown, ctx: ValidationContext) {\n    if (!isPlainObject(input)) {\n      return ctx.issueInvalidType(input, 'object')\n    }\n\n    if (\n      '$type' in input &&\n      input.$type !== undefined &&\n      input.$type !== this.$type\n    ) {\n      return ctx.issueInvalidPropertyValue(input, '$type', [this.$type])\n    }\n\n    return ctx.validate(input, this.schema)\n  }\n}\n\n/**\n * Creates a typed object schema for use in Lexicon unions.\n *\n * Typed objects are identified by their `$type` field, which combines an NSID\n * and a hash (e.g., 'app.bsky.embed.images#view'). Used for union variants.\n *\n * This function offers two overloads:\n * - One that infers the type from arguments (no circular reference support)\n * - One with explicit interface for codegen with circular references\n *\n * @param nsid - The NSID part of the type (e.g., 'app.bsky.embed.images')\n * @param hash - The hash part of the type (e.g., 'view'), defaults to 'main'\n * @param validator - Schema for validating the object properties\n * @returns A new {@link TypedObjectSchema} instance\n *\n * @example\n * ```ts\n * // Image embed view\n * const imageViewSchema = l.typedObject(\n *   'app.bsky.embed.images',\n *   'view',\n *   l.object({\n *     images: l.array(l.object({\n *       thumb: l.string(),\n *       fullsize: l.string(),\n *       alt: l.string(),\n *     })),\n *   })\n * )\n *\n * // Main type (hash defaults to 'main')\n * const postViewSchema = l.typedObject(\n *   'app.bsky.feed.defs',\n *   'postView',\n *   l.object({ uri: l.string(), cid: l.string(), author: authorSchema })\n * )\n *\n * // Use $isTypeOf to narrow union types\n * if (imageViewSchema.$isTypeOf(embed)) {\n *   // embed is narrowed to image view type\n * }\n *\n * // Use $build to construct typed objects\n * const view = imageViewSchema.$build({ images: [...] })\n * // view.$type === 'app.bsky.embed.images#view'\n * ```\n */\nexport function typedObject<\n  const N extends NsidString,\n  const H extends string,\n  const S extends Validator<{ [k: string]: unknown }>,\n>(nsid: N, hash: H, validator: S): TypedObjectSchema<$Type<N, H>, S>\nexport function typedObject<V extends { $type?: $Type }>(\n  nsid: V extends { $type?: infer T extends string }\n    ? T extends `${infer N}#${string}`\n      ? N\n      : T // (T is a \"main\" type, so already an NSID)\n    : never,\n  hash: V extends { $type?: infer T extends string }\n    ? T extends `${string}#${infer H}`\n      ? H\n      : 'main'\n    : never,\n  validator: Validator<Omit<V, '$type'>>,\n): TypedObjectSchema<$TypeOf<V>, Validator<V>>\n/*@__NO_SIDE_EFFECTS__*/\nexport function typedObject<\n  const N extends NsidString,\n  const H extends string,\n  const S extends Validator<{ [k: string]: unknown }>,\n>(nsid: N, hash: H, validator: S) {\n  return new TypedObjectSchema<$Type<N, H>, S>($type(nsid, hash), validator)\n}\n"]}

package/dist/schema/typed-ref.d.ts

@@ -1,4 +1,12 @@
 import { $Typed, InferInput, InferOutput, Schema, ValidationContext, Validator } from '../core.js';
+/**
+ * Interface for validators that have a $type property.
+ *
+ * Used by typed objects and records to identify their type in unions.
+ *
+ * @template TInput - The input type (with optional $type)
+ * @template TOutput - The output type (with non-optional $type)
+ */
 export interface TypedObjectValidator<TInput extends {
     $type?: string;
 } = {
@@ -6,7 +14,27 @@ export interface TypedObjectValidator<TInput extends {
 }, TOutput extends TInput = TInput> extends Validator<TInput, TOutput> {
     $type: NonNullable<TOutput['$type']>;
 }
+/**
+ * Function type that returns a typed object validator, used for lazy resolution.
+ *
+ * @template TValidator - The typed object validator type
+ */
 export type TypedRefGetter<out TValidator extends TypedObjectValidator> = () => TValidator;
+/**
+ * Schema for referencing typed objects with lazy resolution.
+ *
+ * Used in typed unions to reference typed object schemas. Requires the
+ * `$type` field to be present and match the referenced schema's type.
+ * The referenced schema is resolved lazily to support circular references.
+ *
+ * @template TValidator - The referenced typed object validator type
+ *
+ * @example
+ * ```ts
+ * const ref = new TypedRefSchema(() => imageViewSchema)
+ * // ref.$type === 'app.bsky.embed.images#view'
+ * ```
+ */
 export declare class TypedRefSchema<const TValidator extends TypedObjectValidator = TypedObjectValidator> extends Schema<$Typed<InferInput<TValidator>>, $Typed<InferOutput<TValidator>>> {
     #private;
     constructor(getter: TypedRefGetter<TValidator>);
@@ -14,6 +42,31 @@ export declare class TypedRefSchema<const TValidator extends TypedObjectValidato
     get $type(): TValidator['$type'];
     validateInContext(input: unknown, ctx: ValidationContext): import("../core.js").ValidationFailure | import("../core.js").ValidationSuccess<InferInput<TValidator>>;
 }
+/**
+ * Creates a reference to a typed object schema for use in typed unions.
+ *
+ * Unlike regular `ref()`, this requires the referenced schema to have a
+ * `$type` property, and validates that the input's `$type` matches.
+ *
+ * @param get - Function that returns the typed object validator
+ * @returns A new {@link TypedRefSchema} instance
+ *
+ * @example
+ * ```ts
+ * // Reference to image embed view
+ * const imageRef = l.typedRef(() => imageViewSchema)
+ *
+ * // Use in a typed union
+ * const embedUnion = l.typedUnion([
+ *   l.typedRef(() => imageViewSchema),
+ *   l.typedRef(() => videoViewSchema),
+ *   l.typedRef(() => externalViewSchema),
+ * ], true) // closed union
+ *
+ * // The $type is accessible on the ref
+ * console.log(imageRef.$type) // 'app.bsky.embed.images#view'
+ * ```
+ */
 export declare function typedRef<const TValidator extends TypedObjectValidator>(get: TypedRefGetter<TValidator>): TypedRefSchema<TValidator>;
 export declare function typedRef<TInput extends {
     $type?: string;

package/dist/schema/typed-ref.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"typed-ref.d.ts","sourceRoot":"","sources":["../../src/schema/typed-ref.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,MAAM,EACN,UAAU,EACV,WAAW,EACX,MAAM,EACN,iBAAiB,EACjB,SAAS,EACV,MAAM,YAAY,CAAA;AAEnB,MAAM,WAAW,oBAAoB,CACnC,MAAM,SAAS;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,EACtD,OAAO,SAAS,MAAM,GAAG,MAAM,CAC/B,SAAQ,SAAS,CAAC,MAAM,EAAE,OAAO,CAAC;IAClC,KAAK,EAAE,WAAW,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAA;CACrC;AAED,MAAM,MAAM,cAAc,CAAC,GAAG,CAAC,UAAU,SAAS,oBAAoB,IACpE,MAAM,UAAU,CAAA;AAElB,qBAAa,cAAc,CACzB,KAAK,CAAC,UAAU,SAAS,oBAAoB,GAAG,oBAAoB,CACpE,SAAQ,MAAM,CACd,MAAM,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC,EAC9B,MAAM,CAAC,WAAW,CAAC,UAAU,CAAC,CAAC,CAChC;;gBAGa,MAAM,EAAE,cAAc,CAAC,UAAU,CAAC;IAS9C,IAAI,SAAS,IAAI,UAAU,CAE1B;IAED,IAAI,KAAK,IAAI,UAAU,CAAC,OAAO,CAAC,CAE/B;IAED,iBAAiB,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,iBAAiB;CAUzD;AAGD,wBAAgB,QAAQ,CAAC,KAAK,CAAC,UAAU,SAAS,oBAAoB,EACpE,GAAG,EAAE,cAAc,CAAC,UAAU,CAAC,GAC9B,cAAc,CAAC,UAAU,CAAC,CAAA;AAC7B,wBAAgB,QAAQ,CACtB,MAAM,SAAS;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,EACjC,OAAO,SAAS,MAAM,GAAG,MAAM,EAE/B,GAAG,EAAE,cAAc,CAAC,oBAAoB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GACzD,cAAc,CAAC,oBAAoB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA"}
+{"version":3,"file":"typed-ref.d.ts","sourceRoot":"","sources":["../../src/schema/typed-ref.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,MAAM,EACN,UAAU,EACV,WAAW,EACX,MAAM,EACN,iBAAiB,EACjB,SAAS,EACV,MAAM,YAAY,CAAA;AAEnB;;;;;;;GAOG;AACH,MAAM,WAAW,oBAAoB,CACnC,MAAM,SAAS;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,EACtD,OAAO,SAAS,MAAM,GAAG,MAAM,CAC/B,SAAQ,SAAS,CAAC,MAAM,EAAE,OAAO,CAAC;IAClC,KAAK,EAAE,WAAW,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAA;CACrC;AAED;;;;GAIG;AACH,MAAM,MAAM,cAAc,CAAC,GAAG,CAAC,UAAU,SAAS,oBAAoB,IACpE,MAAM,UAAU,CAAA;AAElB;;;;;;;;;;;;;;GAcG;AACH,qBAAa,cAAc,CACzB,KAAK,CAAC,UAAU,SAAS,oBAAoB,GAAG,oBAAoB,CACpE,SAAQ,MAAM,CACd,MAAM,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC,EAC9B,MAAM,CAAC,WAAW,CAAC,UAAU,CAAC,CAAC,CAChC;;gBAGa,MAAM,EAAE,cAAc,CAAC,UAAU,CAAC;IAS9C,IAAI,SAAS,IAAI,UAAU,CAE1B;IAED,IAAI,KAAK,IAAI,UAAU,CAAC,OAAO,CAAC,CAE/B;IAED,iBAAiB,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,iBAAiB;CAUzD;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,wBAAgB,QAAQ,CAAC,KAAK,CAAC,UAAU,SAAS,oBAAoB,EACpE,GAAG,EAAE,cAAc,CAAC,UAAU,CAAC,GAC9B,cAAc,CAAC,UAAU,CAAC,CAAA;AAC7B,wBAAgB,QAAQ,CACtB,MAAM,SAAS;IAAE,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,EACjC,OAAO,SAAS,MAAM,GAAG,MAAM,EAE/B,GAAG,EAAE,cAAc,CAAC,oBAAoB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GACzD,cAAc,CAAC,oBAAoB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA"}

package/dist/schema/typed-ref.js

@@ -3,6 +3,21 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.TypedRefSchema = void 0;
 exports.typedRef = typedRef;
 const core_js_1 = require("../core.js");
+/**
+ * Schema for referencing typed objects with lazy resolution.
+ *
+ * Used in typed unions to reference typed object schemas. Requires the
+ * `$type` field to be present and match the referenced schema's type.
+ * The referenced schema is resolved lazily to support circular references.
+ *
+ * @template TValidator - The referenced typed object validator type
+ *
+ * @example
+ * ```ts
+ * const ref = new TypedRefSchema(() => imageViewSchema)
+ * // ref.$type === 'app.bsky.embed.images#view'
+ * ```
+ */
 class TypedRefSchema extends core_js_1.Schema {
     #getter;
     constructor(getter) {

package/dist/schema/typed-ref.js.map

@@ -1 +1 @@
-{"version":3,"file":"typed-ref.js","sourceRoot":"","sources":["../../src/schema/typed-ref.ts"],"names":[],"mappings":";;;AAkEA,4BAIC;AAtED,wCAOmB;AAYnB,MAAa,cAEX,SAAQ,gBAGT;IACC,OAAO,CAA4B;IAEnC,YAAY,MAAkC;QAC5C,uEAAuE;QACvE,sEAAsE;QAEtE,KAAK,EAAE,CAAA;QAEP,IAAI,CAAC,OAAO,GAAG,MAAM,CAAA;IACvB,CAAC;IAED,IAAI,SAAS;QACX,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IAChC,CAAC;IAED,IAAI,KAAK;QACP,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAA;IAC7B,CAAC;IAED,iBAAiB,CAAC,KAAc,EAAE,GAAsB;QACtD,MAAM,MAAM,GAAG,GAAG,CAAC,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC,SAAS,CAAC,CAAA;QAClD,IAAI,CAAC,MAAM,CAAC,OAAO;YAAE,OAAO,MAAM,CAAA;QAElC,IAAI,MAAM,CAAC,KAAK,CAAC,KAAK,KAAK,IAAI,CAAC,KAAK,EAAE,CAAC;YACtC,OAAO,GAAG,CAAC,yBAAyB,CAAC,MAAM,CAAC,KAAK,EAAE,OAAO,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAA;QAC3E,CAAC;QAED,OAAO,MAAM,CAAA;IACf,CAAC;CACF;AAnCD,wCAmCC;AAYD,SAAgB,QAAQ,CACtB,GAA+B;IAE/B,OAAO,IAAI,cAAc,CAAa,GAAG,CAAC,CAAA;AAC5C,CAAC","sourcesContent":["import {\n  $Typed,\n  InferInput,\n  InferOutput,\n  Schema,\n  ValidationContext,\n  Validator,\n} from '../core.js'\n\nexport interface TypedObjectValidator<\n  TInput extends { $type?: string } = { $type?: string },\n  TOutput extends TInput = TInput,\n> extends Validator<TInput, TOutput> {\n  $type: NonNullable<TOutput['$type']>\n}\n\nexport type TypedRefGetter<out TValidator extends TypedObjectValidator> =\n  () => TValidator\n\nexport class TypedRefSchema<\n  const TValidator extends TypedObjectValidator = TypedObjectValidator,\n> extends Schema<\n  $Typed<InferInput<TValidator>>,\n  $Typed<InferOutput<TValidator>>\n> {\n  #getter: TypedRefGetter<TValidator>\n\n  constructor(getter: TypedRefGetter<TValidator>) {\n    // @NOTE In order to avoid circular dependency issues, we don't resolve\n    // the schema here. Instead, we resolve it lazily when first accessed.\n\n    super()\n\n    this.#getter = getter\n  }\n\n  get validator(): TValidator {\n    return this.#getter.call(null)\n  }\n\n  get $type(): TValidator['$type'] {\n    return this.validator.$type\n  }\n\n  validateInContext(input: unknown, ctx: ValidationContext) {\n    const result = ctx.validate(input, this.validator)\n    if (!result.success) return result\n\n    if (result.value.$type !== this.$type) {\n      return ctx.issueInvalidPropertyValue(result.value, '$type', [this.$type])\n    }\n\n    return result\n  }\n}\n\n/*@__NO_SIDE_EFFECTS__*/\nexport function typedRef<const TValidator extends TypedObjectValidator>(\n  get: TypedRefGetter<TValidator>,\n): TypedRefSchema<TValidator>\nexport function typedRef<\n  TInput extends { $type?: string },\n  TOutput extends TInput = TInput,\n>(\n  get: TypedRefGetter<TypedObjectValidator<TInput, TOutput>>,\n): TypedRefSchema<TypedObjectValidator<TInput, TOutput>>\nexport function typedRef<const TValidator extends TypedObjectValidator>(\n  get: TypedRefGetter<TValidator>,\n): TypedRefSchema<TValidator> {\n  return new TypedRefSchema<TValidator>(get)\n}\n"]}
+{"version":3,"file":"typed-ref.js","sourceRoot":"","sources":["../../src/schema/typed-ref.ts"],"names":[],"mappings":";;;AAuHA,4BAIC;AA3HD,wCAOmB;AAyBnB;;;;;;;;;;;;;;GAcG;AACH,MAAa,cAEX,SAAQ,gBAGT;IACC,OAAO,CAA4B;IAEnC,YAAY,MAAkC;QAC5C,uEAAuE;QACvE,sEAAsE;QAEtE,KAAK,EAAE,CAAA;QAEP,IAAI,CAAC,OAAO,GAAG,MAAM,CAAA;IACvB,CAAC;IAED,IAAI,SAAS;QACX,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IAChC,CAAC;IAED,IAAI,KAAK;QACP,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAA;IAC7B,CAAC;IAED,iBAAiB,CAAC,KAAc,EAAE,GAAsB;QACtD,MAAM,MAAM,GAAG,GAAG,CAAC,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC,SAAS,CAAC,CAAA;QAClD,IAAI,CAAC,MAAM,CAAC,OAAO;YAAE,OAAO,MAAM,CAAA;QAElC,IAAI,MAAM,CAAC,KAAK,CAAC,KAAK,KAAK,IAAI,CAAC,KAAK,EAAE,CAAC;YACtC,OAAO,GAAG,CAAC,yBAAyB,CAAC,MAAM,CAAC,KAAK,EAAE,OAAO,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAA;QAC3E,CAAC;QAED,OAAO,MAAM,CAAA;IACf,CAAC;CACF;AAnCD,wCAmCC;AAqCD,SAAgB,QAAQ,CACtB,GAA+B;IAE/B,OAAO,IAAI,cAAc,CAAa,GAAG,CAAC,CAAA;AAC5C,CAAC","sourcesContent":["import {\n  $Typed,\n  InferInput,\n  InferOutput,\n  Schema,\n  ValidationContext,\n  Validator,\n} from '../core.js'\n\n/**\n * Interface for validators that have a $type property.\n *\n * Used by typed objects and records to identify their type in unions.\n *\n * @template TInput - The input type (with optional $type)\n * @template TOutput - The output type (with non-optional $type)\n */\nexport interface TypedObjectValidator<\n  TInput extends { $type?: string } = { $type?: string },\n  TOutput extends TInput = TInput,\n> extends Validator<TInput, TOutput> {\n  $type: NonNullable<TOutput['$type']>\n}\n\n/**\n * Function type that returns a typed object validator, used for lazy resolution.\n *\n * @template TValidator - The typed object validator type\n */\nexport type TypedRefGetter<out TValidator extends TypedObjectValidator> =\n  () => TValidator\n\n/**\n * Schema for referencing typed objects with lazy resolution.\n *\n * Used in typed unions to reference typed object schemas. Requires the\n * `$type` field to be present and match the referenced schema's type.\n * The referenced schema is resolved lazily to support circular references.\n *\n * @template TValidator - The referenced typed object validator type\n *\n * @example\n * ```ts\n * const ref = new TypedRefSchema(() => imageViewSchema)\n * // ref.$type === 'app.bsky.embed.images#view'\n * ```\n */\nexport class TypedRefSchema<\n  const TValidator extends TypedObjectValidator = TypedObjectValidator,\n> extends Schema<\n  $Typed<InferInput<TValidator>>,\n  $Typed<InferOutput<TValidator>>\n> {\n  #getter: TypedRefGetter<TValidator>\n\n  constructor(getter: TypedRefGetter<TValidator>) {\n    // @NOTE In order to avoid circular dependency issues, we don't resolve\n    // the schema here. Instead, we resolve it lazily when first accessed.\n\n    super()\n\n    this.#getter = getter\n  }\n\n  get validator(): TValidator {\n    return this.#getter.call(null)\n  }\n\n  get $type(): TValidator['$type'] {\n    return this.validator.$type\n  }\n\n  validateInContext(input: unknown, ctx: ValidationContext) {\n    const result = ctx.validate(input, this.validator)\n    if (!result.success) return result\n\n    if (result.value.$type !== this.$type) {\n      return ctx.issueInvalidPropertyValue(result.value, '$type', [this.$type])\n    }\n\n    return result\n  }\n}\n\n/**\n * Creates a reference to a typed object schema for use in typed unions.\n *\n * Unlike regular `ref()`, this requires the referenced schema to have a\n * `$type` property, and validates that the input's `$type` matches.\n *\n * @param get - Function that returns the typed object validator\n * @returns A new {@link TypedRefSchema} instance\n *\n * @example\n * ```ts\n * // Reference to image embed view\n * const imageRef = l.typedRef(() => imageViewSchema)\n *\n * // Use in a typed union\n * const embedUnion = l.typedUnion([\n *   l.typedRef(() => imageViewSchema),\n *   l.typedRef(() => videoViewSchema),\n *   l.typedRef(() => externalViewSchema),\n * ], true) // closed union\n *\n * // The $type is accessible on the ref\n * console.log(imageRef.$type) // 'app.bsky.embed.images#view'\n * ```\n */\n/*@__NO_SIDE_EFFECTS__*/\nexport function typedRef<const TValidator extends TypedObjectValidator>(\n  get: TypedRefGetter<TValidator>,\n): TypedRefSchema<TValidator>\nexport function typedRef<\n  TInput extends { $type?: string },\n  TOutput extends TInput = TInput,\n>(\n  get: TypedRefGetter<TypedObjectValidator<TInput, TOutput>>,\n): TypedRefSchema<TypedObjectValidator<TInput, TOutput>>\nexport function typedRef<const TValidator extends TypedObjectValidator>(\n  get: TypedRefGetter<TValidator>,\n): TypedRefSchema<TValidator> {\n  return new TypedRefSchema<TValidator>(get)\n}\n"]}

package/dist/schema/typed-union.d.ts

@@ -1,6 +1,25 @@
 import { InferInput, InferOutput, Schema, Unknown$TypedObject, ValidationContext } from '../core.js';
+import { TypedObjectSchema } from './typed-object.js';
 import { TypedRefSchema } from './typed-ref.js';
-export declare class TypedUnionSchema<const TValidators extends readonly TypedRefSchema[] = [], const TClosed extends boolean = boolean> extends Schema<TClosed extends true ? InferInput<TValidators[number]> : InferInput<TValidators[number]> | Unknown$TypedObject, TClosed extends true ? InferOutput<TValidators[number]> : InferOutput<TValidators[number]> | Unknown$TypedObject> {
+/**
+ * Schema for Lexicon typed unions (unions discriminated by $type).
+ *
+ * Typed unions are collections of typed objects identified by their `$type`
+ * field. Can be "open" (accept unknown types) or "closed" (only accept
+ * known types).
+ *
+ * @template TValidators - Tuple of {@link TypedRefSchema} or {@link TypedObjectSchema} instances
+ * @template TClosed - Whether the union is closed (rejects unknown $types)
+ *
+ * @example
+ * ```ts
+ * const embedUnion = new TypedUnionSchema([
+ *   l.typedRef(() => imageSchema),
+ *   l.typedRef(() => videoSchema),
+ * ], true) // closed - only accepts images and videos
+ * ```
+ */
+export declare class TypedUnionSchema<const TValidators extends readonly (TypedRefSchema | TypedObjectSchema)[] = [], const TClosed extends boolean = boolean> extends Schema<TClosed extends true ? InferInput<TValidators[number]> : InferInput<TValidators[number]> | Unknown$TypedObject, TClosed extends true ? InferOutput<TValidators[number]> : InferOutput<TValidators[number]> | Unknown$TypedObject> {
     protected readonly validators: TValidators;
     readonly closed: TClosed;
     constructor(validators: TValidators, closed: TClosed);
@@ -8,5 +27,35 @@ export declare class TypedUnionSchema<const TValidators extends readonly TypedRe
     get $types(): unknown[];
     validateInContext(input: unknown, ctx: ValidationContext): import("../core.js").ValidationFailure | import("../core.js").ValidationSuccess<Record<string, unknown>> | import("../core.js").ValidationSuccess<InferInput<TValidators[number]>>;
 }
+/**
+ * Creates a typed union schema for Lexicon unions.
+ *
+ * Typed unions discriminate variants by their `$type` field. Can be open
+ * (accepts unknown types, useful for extensibility) or closed (strict).
+ *
+ * @param refs - Array of typed refs for the union variants
+ * @param closed - Whether to reject unknown $type values
+ * @returns A new {@link TypedUnionSchema} instance
+ *
+ * @example
+ * ```ts
+ * // Closed union - only accepts known types
+ * const embedSchema = l.typedUnion([
+ *   l.typedRef(() => imageViewSchema),
+ *   l.typedRef(() => videoViewSchema),
+ *   l.typedRef(() => externalViewSchema),
+ * ], true)
+ *
+ * // Open union - accepts unknown types for forward compatibility
+ * const feedItemSchema = l.typedUnion([
+ *   l.typedRef(() => postSchema),
+ *   l.typedRef(() => repostSchema),
+ * ], false) // unknown types pass through
+ *
+ * // Get all known $types
+ * console.log(embedSchema.$types)
+ * // ['app.bsky.embed.images#view', 'app.bsky.embed.video#view', ...]
+ * ```
+ */
 export declare function typedUnion<const R extends readonly TypedRefSchema[], const C extends boolean>(refs: R, closed: C): TypedUnionSchema<R, C>;
 //# sourceMappingURL=typed-union.d.ts.map

package/dist/schema/typed-union.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"typed-union.d.ts","sourceRoot":"","sources":["../../src/schema/typed-union.ts"],"names":[],"mappings":"AACA,OAAO,EACL,UAAU,EACV,WAAW,EACX,MAAM,EACN,mBAAmB,EACnB,iBAAiB,EAClB,MAAM,YAAY,CAAA;AAEnB,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAA;AAE/C,qBAAa,gBAAgB,CAC3B,KAAK,CAAC,WAAW,SAAS,SAAS,cAAc,EAAE,GAAG,EAAE,EACxD,KAAK,CAAC,OAAO,SAAS,OAAO,GAAG,OAAO,CACvC,SAAQ,MAAM,CACd,OAAO,SAAS,IAAI,GAChB,UAAU,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,GAC/B,UAAU,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,GAAG,mBAAmB,EACzD,OAAO,SAAS,IAAI,GAChB,WAAW,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,GAChC,WAAW,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,GAAG,mBAAmB,CAC3D;IAEG,SAAS,CAAC,QAAQ,CAAC,UAAU,EAAE,WAAW;aAC1B,MAAM,EAAE,OAAO;gBADZ,UAAU,EAAE,WAAW,EAC1B,MAAM,EAAE,OAAO;IASjC,IAAI,aAAa,IAAI,GAAG,CAAC,OAAO,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC,CAKrD;IAED,IAAI,MAAM,cAET;IAED,iBAAiB,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,iBAAiB;CAsBzD;AAGD,wBAAgB,UAAU,CACxB,KAAK,CAAC,CAAC,SAAS,SAAS,cAAc,EAAE,EACzC,KAAK,CAAC,CAAC,SAAS,OAAO,EACvB,IAAI,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,0BAEnB"}
+{"version":3,"file":"typed-union.d.ts","sourceRoot":"","sources":["../../src/schema/typed-union.ts"],"names":[],"mappings":"AACA,OAAO,EACL,UAAU,EACV,WAAW,EACX,MAAM,EACN,mBAAmB,EACnB,iBAAiB,EAClB,MAAM,YAAY,CAAA;AAEnB,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AACrD,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAA;AAE/C;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,gBAAgB,CAC3B,KAAK,CAAC,WAAW,SAAS,SAAS,CAC/B,cAAc,GACd,iBAAiB,CACpB,EAAE,GAAG,EAAE,EACR,KAAK,CAAC,OAAO,SAAS,OAAO,GAAG,OAAO,CACvC,SAAQ,MAAM,CACd,OAAO,SAAS,IAAI,GAChB,UAAU,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,GAC/B,UAAU,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,GAAG,mBAAmB,EACzD,OAAO,SAAS,IAAI,GAChB,WAAW,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,GAChC,WAAW,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,GAAG,mBAAmB,CAC3D;IAEG,SAAS,CAAC,QAAQ,CAAC,UAAU,EAAE,WAAW;aAC1B,MAAM,EAAE,OAAO;gBADZ,UAAU,EAAE,WAAW,EAC1B,MAAM,EAAE,OAAO;IAUjC,IAAI,aAAa,IAAI,GAAG,CAAC,OAAO,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC,CAKrD;IAED,IAAI,MAAM,cAET;IAED,iBAAiB,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,iBAAiB;CAsBzD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,wBAAgB,UAAU,CACxB,KAAK,CAAC,CAAC,SAAS,SAAS,cAAc,EAAE,EACzC,KAAK,CAAC,CAAC,SAAS,OAAO,EACvB,IAAI,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,0BAEnB"}

package/dist/schema/typed-union.js

@@ -5,13 +5,32 @@ exports.typedUnion = typedUnion;
 const lex_data_1 = require("@atproto/lex-data");
 const core_js_1 = require("../core.js");
 const lazy_property_js_1 = require("../util/lazy-property.js");
+/**
+ * Schema for Lexicon typed unions (unions discriminated by $type).
+ *
+ * Typed unions are collections of typed objects identified by their `$type`
+ * field. Can be "open" (accept unknown types) or "closed" (only accept
+ * known types).
+ *
+ * @template TValidators - Tuple of {@link TypedRefSchema} or {@link TypedObjectSchema} instances
+ * @template TClosed - Whether the union is closed (rejects unknown $types)
+ *
+ * @example
+ * ```ts
+ * const embedUnion = new TypedUnionSchema([
+ *   l.typedRef(() => imageSchema),
+ *   l.typedRef(() => videoSchema),
+ * ], true) // closed - only accepts images and videos
+ * ```
+ */
 class TypedUnionSchema extends core_js_1.Schema {
     validators;
     closed;
     constructor(validators, closed) {
         // @NOTE In order to avoid circular dependency issues, we don't access the
         // refs's schema (or $type) here. Instead, we access them lazily when first
-        // needed.
+        // needed. The biggest issue with this strategy is that we can't throw
+        // early if the refs contain multiple refs with the same $type.
         super();
         this.validators = validators;
         this.closed = closed;
@@ -44,6 +63,36 @@ class TypedUnionSchema extends core_js_1.Schema {
     }
 }
 exports.TypedUnionSchema = TypedUnionSchema;
+/**
+ * Creates a typed union schema for Lexicon unions.
+ *
+ * Typed unions discriminate variants by their `$type` field. Can be open
+ * (accepts unknown types, useful for extensibility) or closed (strict).
+ *
+ * @param refs - Array of typed refs for the union variants
+ * @param closed - Whether to reject unknown $type values
+ * @returns A new {@link TypedUnionSchema} instance
+ *
+ * @example
+ * ```ts
+ * // Closed union - only accepts known types
+ * const embedSchema = l.typedUnion([
+ *   l.typedRef(() => imageViewSchema),
+ *   l.typedRef(() => videoViewSchema),
+ *   l.typedRef(() => externalViewSchema),
+ * ], true)
+ *
+ * // Open union - accepts unknown types for forward compatibility
+ * const feedItemSchema = l.typedUnion([
+ *   l.typedRef(() => postSchema),
+ *   l.typedRef(() => repostSchema),
+ * ], false) // unknown types pass through
+ *
+ * // Get all known $types
+ * console.log(embedSchema.$types)
+ * // ['app.bsky.embed.images#view', 'app.bsky.embed.video#view', ...]
+ * ```
+ */
 /*@__NO_SIDE_EFFECTS__*/
 function typedUnion(refs, closed) {
     return new TypedUnionSchema(refs, closed);

package/dist/schema/typed-union.js.map

@@ -1 +1 @@
-{"version":3,"file":"typed-union.js","sourceRoot":"","sources":["../../src/schema/typed-union.ts"],"names":[],"mappings":";;;AAqEA,gCAKC;AA1ED,gDAAiD;AACjD,wCAMmB;AACnB,+DAAuD;AAGvD,MAAa,gBAGX,SAAQ,gBAOT;IAEsB;IACH;IAFlB,YACqB,UAAuB,EAC1B,MAAe;QAE/B,0EAA0E;QAC1E,2EAA2E;QAC3E,UAAU;QAEV,KAAK,EAAE,CAAA;QAPY,eAAU,GAAV,UAAU,CAAa;QAC1B,WAAM,GAAN,MAAM,CAAS;IAOjC,CAAC;IAED,IAAI,aAAa;QACf,MAAM,GAAG,GAAG,IAAI,GAAG,EAAgC,CAAA;QACnD,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,UAAU;YAAE,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,CAAA;QAE1D,OAAO,IAAA,+BAAY,EAAC,IAAI,EAAE,eAAe,EAAE,GAAG,CAAC,CAAA;IACjD,CAAC;IAED,IAAI,MAAM;QACR,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,IAAI,EAAE,CAAC,CAAA;IAC9C,CAAC;IAED,iBAAiB,CAAC,KAAc,EAAE,GAAsB;QACtD,IAAI,CAAC,IAAA,wBAAa,EAAC,KAAK,CAAC,IAAI,CAAC,CAAC,OAAO,IAAI,KAAK,CAAC,EAAE,CAAC;YACjD,OAAO,GAAG,CAAC,gBAAgB,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAA;QAC9C,CAAC;QAED,MAAM,EAAE,KAAK,EAAE,GAAG,KAAK,CAAA;QAEvB,MAAM,SAAS,GAAG,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,KAAK,CAAC,CAAA;QAC/C,IAAI,SAAS,EAAE,CAAC;YACd,OAAO,GAAG,CAAC,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC,CAAA;QACvC,CAAC;QAED,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YAChB,OAAO,GAAG,CAAC,yBAAyB,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,CAAA;QACnE,CAAC;QAED,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YAC9B,OAAO,GAAG,CAAC,wBAAwB,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAA;QAC/D,CAAC;QAED,OAAO,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,CAAA;IAC3B,CAAC;CACF;AAvDD,4CAuDC;AAED,wBAAwB;AACxB,SAAgB,UAAU,CAGxB,IAAO,EAAE,MAAS;IAClB,OAAO,IAAI,gBAAgB,CAAO,IAAI,EAAE,MAAM,CAAC,CAAA;AACjD,CAAC","sourcesContent":["import { isPlainObject } from '@atproto/lex-data'\nimport {\n  InferInput,\n  InferOutput,\n  Schema,\n  Unknown$TypedObject,\n  ValidationContext,\n} from '../core.js'\nimport { lazyProperty } from '../util/lazy-property.js'\nimport { TypedRefSchema } from './typed-ref.js'\n\nexport class TypedUnionSchema<\n  const TValidators extends readonly TypedRefSchema[] = [],\n  const TClosed extends boolean = boolean,\n> extends Schema<\n  TClosed extends true\n    ? InferInput<TValidators[number]>\n    : InferInput<TValidators[number]> | Unknown$TypedObject,\n  TClosed extends true\n    ? InferOutput<TValidators[number]>\n    : InferOutput<TValidators[number]> | Unknown$TypedObject\n> {\n  constructor(\n    protected readonly validators: TValidators,\n    public readonly closed: TClosed,\n  ) {\n    // @NOTE In order to avoid circular dependency issues, we don't access the\n    // refs's schema (or $type) here. Instead, we access them lazily when first\n    // needed.\n\n    super()\n  }\n\n  get validatorsMap(): Map<unknown, TValidators[number]> {\n    const map = new Map<unknown, TValidators[number]>()\n    for (const ref of this.validators) map.set(ref.$type, ref)\n\n    return lazyProperty(this, 'validatorsMap', map)\n  }\n\n  get $types() {\n    return Array.from(this.validatorsMap.keys())\n  }\n\n  validateInContext(input: unknown, ctx: ValidationContext) {\n    if (!isPlainObject(input) || !('$type' in input)) {\n      return ctx.issueInvalidType(input, '$typed')\n    }\n\n    const { $type } = input\n\n    const validator = this.validatorsMap.get($type)\n    if (validator) {\n      return ctx.validate(input, validator)\n    }\n\n    if (this.closed) {\n      return ctx.issueInvalidPropertyValue(input, '$type', this.$types)\n    }\n\n    if (typeof $type !== 'string') {\n      return ctx.issueInvalidPropertyType(input, '$type', 'string')\n    }\n\n    return ctx.success(input)\n  }\n}\n\n/*@__NO_SIDE_EFFECTS__*/\nexport function typedUnion<\n  const R extends readonly TypedRefSchema[],\n  const C extends boolean,\n>(refs: R, closed: C) {\n  return new TypedUnionSchema<R, C>(refs, closed)\n}\n"]}
+{"version":3,"file":"typed-union.js","sourceRoot":"","sources":["../../src/schema/typed-union.ts"],"names":[],"mappings":";;;AA0HA,gCAKC;AA/HD,gDAAiD;AACjD,wCAMmB;AACnB,+DAAuD;AAIvD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAa,gBAMX,SAAQ,gBAOT;IAEsB;IACH;IAFlB,YACqB,UAAuB,EAC1B,MAAe;QAE/B,0EAA0E;QAC1E,2EAA2E;QAC3E,sEAAsE;QACtE,+DAA+D;QAE/D,KAAK,EAAE,CAAA;QARY,eAAU,GAAV,UAAU,CAAa;QAC1B,WAAM,GAAN,MAAM,CAAS;IAQjC,CAAC;IAED,IAAI,aAAa;QACf,MAAM,GAAG,GAAG,IAAI,GAAG,EAAgC,CAAA;QACnD,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,UAAU;YAAE,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,CAAA;QAE1D,OAAO,IAAA,+BAAY,EAAC,IAAI,EAAE,eAAe,EAAE,GAAG,CAAC,CAAA;IACjD,CAAC;IAED,IAAI,MAAM;QACR,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,IAAI,EAAE,CAAC,CAAA;IAC9C,CAAC;IAED,iBAAiB,CAAC,KAAc,EAAE,GAAsB;QACtD,IAAI,CAAC,IAAA,wBAAa,EAAC,KAAK,CAAC,IAAI,CAAC,CAAC,OAAO,IAAI,KAAK,CAAC,EAAE,CAAC;YACjD,OAAO,GAAG,CAAC,gBAAgB,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAA;QAC9C,CAAC;QAED,MAAM,EAAE,KAAK,EAAE,GAAG,KAAK,CAAA;QAEvB,MAAM,SAAS,GAAG,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,KAAK,CAAC,CAAA;QAC/C,IAAI,SAAS,EAAE,CAAC;YACd,OAAO,GAAG,CAAC,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC,CAAA;QACvC,CAAC;QAED,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YAChB,OAAO,GAAG,CAAC,yBAAyB,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,CAAA;QACnE,CAAC;QAED,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YAC9B,OAAO,GAAG,CAAC,wBAAwB,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAA;QAC/D,CAAC;QAED,OAAO,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,CAAA;IAC3B,CAAC;CACF;AA3DD,4CA2DC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAwB;AACxB,SAAgB,UAAU,CAGxB,IAAO,EAAE,MAAS;IAClB,OAAO,IAAI,gBAAgB,CAAO,IAAI,EAAE,MAAM,CAAC,CAAA;AACjD,CAAC","sourcesContent":["import { isPlainObject } from '@atproto/lex-data'\nimport {\n  InferInput,\n  InferOutput,\n  Schema,\n  Unknown$TypedObject,\n  ValidationContext,\n} from '../core.js'\nimport { lazyProperty } from '../util/lazy-property.js'\nimport { TypedObjectSchema } from './typed-object.js'\nimport { TypedRefSchema } from './typed-ref.js'\n\n/**\n * Schema for Lexicon typed unions (unions discriminated by $type).\n *\n * Typed unions are collections of typed objects identified by their `$type`\n * field. Can be \"open\" (accept unknown types) or \"closed\" (only accept\n * known types).\n *\n * @template TValidators - Tuple of {@link TypedRefSchema} or {@link TypedObjectSchema} instances\n * @template TClosed - Whether the union is closed (rejects unknown $types)\n *\n * @example\n * ```ts\n * const embedUnion = new TypedUnionSchema([\n *   l.typedRef(() => imageSchema),\n *   l.typedRef(() => videoSchema),\n * ], true) // closed - only accepts images and videos\n * ```\n */\nexport class TypedUnionSchema<\n  const TValidators extends readonly (\n    | TypedRefSchema\n    | TypedObjectSchema\n  )[] = [],\n  const TClosed extends boolean = boolean,\n> extends Schema<\n  TClosed extends true\n    ? InferInput<TValidators[number]>\n    : InferInput<TValidators[number]> | Unknown$TypedObject,\n  TClosed extends true\n    ? InferOutput<TValidators[number]>\n    : InferOutput<TValidators[number]> | Unknown$TypedObject\n> {\n  constructor(\n    protected readonly validators: TValidators,\n    public readonly closed: TClosed,\n  ) {\n    // @NOTE In order to avoid circular dependency issues, we don't access the\n    // refs's schema (or $type) here. Instead, we access them lazily when first\n    // needed. The biggest issue with this strategy is that we can't throw\n    // early if the refs contain multiple refs with the same $type.\n\n    super()\n  }\n\n  get validatorsMap(): Map<unknown, TValidators[number]> {\n    const map = new Map<unknown, TValidators[number]>()\n    for (const ref of this.validators) map.set(ref.$type, ref)\n\n    return lazyProperty(this, 'validatorsMap', map)\n  }\n\n  get $types() {\n    return Array.from(this.validatorsMap.keys())\n  }\n\n  validateInContext(input: unknown, ctx: ValidationContext) {\n    if (!isPlainObject(input) || !('$type' in input)) {\n      return ctx.issueInvalidType(input, '$typed')\n    }\n\n    const { $type } = input\n\n    const validator = this.validatorsMap.get($type)\n    if (validator) {\n      return ctx.validate(input, validator)\n    }\n\n    if (this.closed) {\n      return ctx.issueInvalidPropertyValue(input, '$type', this.$types)\n    }\n\n    if (typeof $type !== 'string') {\n      return ctx.issueInvalidPropertyType(input, '$type', 'string')\n    }\n\n    return ctx.success(input)\n  }\n}\n\n/**\n * Creates a typed union schema for Lexicon unions.\n *\n * Typed unions discriminate variants by their `$type` field. Can be open\n * (accepts unknown types, useful for extensibility) or closed (strict).\n *\n * @param refs - Array of typed refs for the union variants\n * @param closed - Whether to reject unknown $type values\n * @returns A new {@link TypedUnionSchema} instance\n *\n * @example\n * ```ts\n * // Closed union - only accepts known types\n * const embedSchema = l.typedUnion([\n *   l.typedRef(() => imageViewSchema),\n *   l.typedRef(() => videoViewSchema),\n *   l.typedRef(() => externalViewSchema),\n * ], true)\n *\n * // Open union - accepts unknown types for forward compatibility\n * const feedItemSchema = l.typedUnion([\n *   l.typedRef(() => postSchema),\n *   l.typedRef(() => repostSchema),\n * ], false) // unknown types pass through\n *\n * // Get all known $types\n * console.log(embedSchema.$types)\n * // ['app.bsky.embed.images#view', 'app.bsky.embed.video#view', ...]\n * ```\n */\n/*@__NO_SIDE_EFFECTS__*/\nexport function typedUnion<\n  const R extends readonly TypedRefSchema[],\n  const C extends boolean,\n>(refs: R, closed: C) {\n  return new TypedUnionSchema<R, C>(refs, closed)\n}\n"]}

package/dist/schema/union.d.ts

@@ -1,9 +1,54 @@
 import { InferInput, InferOutput, Schema, ValidationContext, ValidationFailure, Validator } from '../core.js';
+/**
+ * Type representing a non-empty tuple of validators for union schemas.
+ *
+ * Requires at least one validator in the tuple.
+ */
 export type UnionSchemaValidators = readonly [Validator, ...Validator[]];
+/**
+ * Schema for validating values that match one of several possible schemas.
+ *
+ * Tries each validator in order until one succeeds. If all validators fail,
+ * returns a combined error from all attempts.
+ *
+ * @template TValidators - Tuple type of the validators in the union
+ *
+ * @example
+ * ```ts
+ * const schema = new UnionSchema([l.string(), l.integer()])
+ * schema.validate('hello') // success
+ * schema.validate(42)      // success
+ * schema.validate(true)    // fails
+ * ```
+ */
 export declare class UnionSchema<const TValidators extends UnionSchemaValidators = any> extends Schema<InferInput<TValidators[number]>, InferOutput<TValidators[number]>> {
     protected readonly validators: TValidators;
     constructor(validators: TValidators);
     validateInContext(input: unknown, ctx: ValidationContext): ValidationFailure | import("../core.js").ValidationSuccess<unknown>;
 }
+/**
+ * Creates a union schema that accepts values matching any of the provided schemas.
+ *
+ * Validators are tried in order. Use `discriminatedUnion()` for better
+ * performance when discriminating on a known property.
+ *
+ * @param validators - Non-empty array of validators to try
+ * @returns A new {@link UnionSchema} instance
+ *
+ * @example
+ * ```ts
+ * // String or number
+ * const stringOrNumber = l.union([l.string(), l.integer()])
+ *
+ * // Nullable value
+ * const nullableString = l.union([l.string(), l.null()])
+ *
+ * // Multiple object types
+ * const mediaSchema = l.union([
+ *   l.object({ type: l.literal('image'), url: l.string() }),
+ *   l.object({ type: l.literal('video'), url: l.string(), duration: l.integer() }),
+ * ])
+ * ```
+ */
 export declare function union<const TValidators extends UnionSchemaValidators>(validators: TValidators): UnionSchema<TValidators>;
 //# sourceMappingURL=union.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"union.d.ts","sourceRoot":"","sources":["../../src/schema/union.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,UAAU,EACV,WAAW,EACX,MAAM,EACN,iBAAiB,EAEjB,iBAAiB,EACjB,SAAS,EACV,MAAM,YAAY,CAAA;AAEnB,MAAM,MAAM,qBAAqB,GAAG,SAAS,CAAC,SAAS,EAAE,GAAG,SAAS,EAAE,CAAC,CAAA;AAExE,qBAAa,WAAW,CACtB,KAAK,CAAC,WAAW,SAAS,qBAAqB,GAAG,GAAG,CACrD,SAAQ,MAAM,CACd,UAAU,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,EAC/B,WAAW,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,CACjC;IACa,SAAS,CAAC,QAAQ,CAAC,UAAU,EAAE,WAAW;gBAAvB,UAAU,EAAE,WAAW;IAItD,iBAAiB,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,iBAAiB;CAYzD;AAGD,wBAAgB,KAAK,CAAC,KAAK,CAAC,WAAW,SAAS,qBAAqB,EACnE,UAAU,EAAE,WAAW,4BAGxB"}
+{"version":3,"file":"union.d.ts","sourceRoot":"","sources":["../../src/schema/union.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,UAAU,EACV,WAAW,EACX,MAAM,EACN,iBAAiB,EAEjB,iBAAiB,EACjB,SAAS,EACV,MAAM,YAAY,CAAA;AAEnB;;;;GAIG;AACH,MAAM,MAAM,qBAAqB,GAAG,SAAS,CAAC,SAAS,EAAE,GAAG,SAAS,EAAE,CAAC,CAAA;AAExE;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,WAAW,CACtB,KAAK,CAAC,WAAW,SAAS,qBAAqB,GAAG,GAAG,CACrD,SAAQ,MAAM,CACd,UAAU,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,EAC/B,WAAW,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,CACjC;IACa,SAAS,CAAC,QAAQ,CAAC,UAAU,EAAE,WAAW;gBAAvB,UAAU,EAAE,WAAW;IAItD,iBAAiB,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,iBAAiB;CAYzD;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,wBAAgB,KAAK,CAAC,KAAK,CAAC,WAAW,SAAS,qBAAqB,EACnE,UAAU,EAAE,WAAW,4BAGxB"}

package/dist/schema/union.js

@@ -3,6 +3,22 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.UnionSchema = void 0;
 exports.union = union;
 const core_js_1 = require("../core.js");
+/**
+ * Schema for validating values that match one of several possible schemas.
+ *
+ * Tries each validator in order until one succeeds. If all validators fail,
+ * returns a combined error from all attempts.
+ *
+ * @template TValidators - Tuple type of the validators in the union
+ *
+ * @example
+ * ```ts
+ * const schema = new UnionSchema([l.string(), l.integer()])
+ * schema.validate('hello') // success
+ * schema.validate(42)      // success
+ * schema.validate(true)    // fails
+ * ```
+ */
 class UnionSchema extends core_js_1.Schema {
     validators;
     constructor(validators) {
@@ -21,6 +37,30 @@ class UnionSchema extends core_js_1.Schema {
     }
 }
 exports.UnionSchema = UnionSchema;
+/**
+ * Creates a union schema that accepts values matching any of the provided schemas.
+ *
+ * Validators are tried in order. Use `discriminatedUnion()` for better
+ * performance when discriminating on a known property.
+ *
+ * @param validators - Non-empty array of validators to try
+ * @returns A new {@link UnionSchema} instance
+ *
+ * @example
+ * ```ts
+ * // String or number
+ * const stringOrNumber = l.union([l.string(), l.integer()])
+ *
+ * // Nullable value
+ * const nullableString = l.union([l.string(), l.null()])
+ *
+ * // Multiple object types
+ * const mediaSchema = l.union([
+ *   l.object({ type: l.literal('image'), url: l.string() }),
+ *   l.object({ type: l.literal('video'), url: l.string(), duration: l.integer() }),
+ * ])
+ * ```
+ */
 /*@__NO_SIDE_EFFECTS__*/
 function union(validators) {
     return new UnionSchema(validators);

package/dist/schema/union.js.map

@@ -1 +1 @@
-{"version":3,"file":"union.js","sourceRoot":"","sources":["../../src/schema/union.ts"],"names":[],"mappings":";;;AAqCA,sBAIC;AAzCD,wCAQmB;AAInB,MAAa,WAEX,SAAQ,gBAGT;IACgC;IAA/B,YAA+B,UAAuB;QACpD,KAAK,EAAE,CAAA;QADsB,eAAU,GAAV,UAAU,CAAa;IAEtD,CAAC;IAED,iBAAiB,CAAC,KAAc,EAAE,GAAsB;QACtD,MAAM,QAAQ,GAAwB,EAAE,CAAA;QAExC,KAAK,MAAM,SAAS,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;YACxC,MAAM,MAAM,GAAG,GAAG,CAAC,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC,CAAA;YAC7C,IAAI,MAAM,CAAC,OAAO;gBAAE,OAAO,MAAM,CAAA;YAEjC,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;QACvB,CAAC;QAED,OAAO,GAAG,CAAC,OAAO,CAAC,yBAAe,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC,CAAA;IAC5D,CAAC;CACF;AAtBD,kCAsBC;AAED,wBAAwB;AACxB,SAAgB,KAAK,CACnB,UAAuB;IAEvB,OAAO,IAAI,WAAW,CAAc,UAAU,CAAC,CAAA;AACjD,CAAC","sourcesContent":["import {\n  InferInput,\n  InferOutput,\n  Schema,\n  ValidationContext,\n  ValidationError,\n  ValidationFailure,\n  Validator,\n} from '../core.js'\n\nexport type UnionSchemaValidators = readonly [Validator, ...Validator[]]\n\nexport class UnionSchema<\n  const TValidators extends UnionSchemaValidators = any,\n> extends Schema<\n  InferInput<TValidators[number]>,\n  InferOutput<TValidators[number]>\n> {\n  constructor(protected readonly validators: TValidators) {\n    super()\n  }\n\n  validateInContext(input: unknown, ctx: ValidationContext) {\n    const failures: ValidationFailure[] = []\n\n    for (const validator of this.validators) {\n      const result = ctx.validate(input, validator)\n      if (result.success) return result\n\n      failures.push(result)\n    }\n\n    return ctx.failure(ValidationError.fromFailures(failures))\n  }\n}\n\n/*@__NO_SIDE_EFFECTS__*/\nexport function union<const TValidators extends UnionSchemaValidators>(\n  validators: TValidators,\n) {\n  return new UnionSchema<TValidators>(validators)\n}\n"]}
+{"version":3,"file":"union.js","sourceRoot":"","sources":["../../src/schema/union.ts"],"names":[],"mappings":";;;AAkFA,sBAIC;AAtFD,wCAQmB;AASnB;;;;;;;;;;;;;;;GAeG;AACH,MAAa,WAEX,SAAQ,gBAGT;IACgC;IAA/B,YAA+B,UAAuB;QACpD,KAAK,EAAE,CAAA;QADsB,eAAU,GAAV,UAAU,CAAa;IAEtD,CAAC;IAED,iBAAiB,CAAC,KAAc,EAAE,GAAsB;QACtD,MAAM,QAAQ,GAAwB,EAAE,CAAA;QAExC,KAAK,MAAM,SAAS,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;YACxC,MAAM,MAAM,GAAG,GAAG,CAAC,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC,CAAA;YAC7C,IAAI,MAAM,CAAC,OAAO;gBAAE,OAAO,MAAM,CAAA;YAEjC,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;QACvB,CAAC;QAED,OAAO,GAAG,CAAC,OAAO,CAAC,yBAAe,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC,CAAA;IAC5D,CAAC;CACF;AAtBD,kCAsBC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAwB;AACxB,SAAgB,KAAK,CACnB,UAAuB;IAEvB,OAAO,IAAI,WAAW,CAAc,UAAU,CAAC,CAAA;AACjD,CAAC","sourcesContent":["import {\n  InferInput,\n  InferOutput,\n  Schema,\n  ValidationContext,\n  ValidationError,\n  ValidationFailure,\n  Validator,\n} from '../core.js'\n\n/**\n * Type representing a non-empty tuple of validators for union schemas.\n *\n * Requires at least one validator in the tuple.\n */\nexport type UnionSchemaValidators = readonly [Validator, ...Validator[]]\n\n/**\n * Schema for validating values that match one of several possible schemas.\n *\n * Tries each validator in order until one succeeds. If all validators fail,\n * returns a combined error from all attempts.\n *\n * @template TValidators - Tuple type of the validators in the union\n *\n * @example\n * ```ts\n * const schema = new UnionSchema([l.string(), l.integer()])\n * schema.validate('hello') // success\n * schema.validate(42)      // success\n * schema.validate(true)    // fails\n * ```\n */\nexport class UnionSchema<\n  const TValidators extends UnionSchemaValidators = any,\n> extends Schema<\n  InferInput<TValidators[number]>,\n  InferOutput<TValidators[number]>\n> {\n  constructor(protected readonly validators: TValidators) {\n    super()\n  }\n\n  validateInContext(input: unknown, ctx: ValidationContext) {\n    const failures: ValidationFailure[] = []\n\n    for (const validator of this.validators) {\n      const result = ctx.validate(input, validator)\n      if (result.success) return result\n\n      failures.push(result)\n    }\n\n    return ctx.failure(ValidationError.fromFailures(failures))\n  }\n}\n\n/**\n * Creates a union schema that accepts values matching any of the provided schemas.\n *\n * Validators are tried in order. Use `discriminatedUnion()` for better\n * performance when discriminating on a known property.\n *\n * @param validators - Non-empty array of validators to try\n * @returns A new {@link UnionSchema} instance\n *\n * @example\n * ```ts\n * // String or number\n * const stringOrNumber = l.union([l.string(), l.integer()])\n *\n * // Nullable value\n * const nullableString = l.union([l.string(), l.null()])\n *\n * // Multiple object types\n * const mediaSchema = l.union([\n *   l.object({ type: l.literal('image'), url: l.string() }),\n *   l.object({ type: l.literal('video'), url: l.string(), duration: l.integer() }),\n * ])\n * ```\n */\n/*@__NO_SIDE_EFFECTS__*/\nexport function union<const TValidators extends UnionSchemaValidators>(\n  validators: TValidators,\n) {\n  return new UnionSchema<TValidators>(validators)\n}\n"]}