@atproto/lex-schema 0.0.11 → 0.0.12

package/dist/schema/dict.js

@@ -5,9 +5,24 @@ exports.dict = dict;
 const lex_data_1 = require("@atproto/lex-data");
 const core_js_1 = require("../core.js");
 /**
+ * Schema for validating dictionary/map-like objects with dynamic keys.
+ *
+ * Unlike `ObjectSchema` which validates a fixed set of properties, `DictSchema`
+ * validates objects where any string key is allowed, with both keys and values
+ * validated against their respective schemas.
+ *
  * @note There is no dictionary in Lexicon schemas. This is a custom extension
  * to allow map-like objects when using the lex library programmatically (i.e.
  * not code generated from a lexicon schema).
+ *
+ * @template TKey - The validator type for dictionary keys (must validate strings)
+ * @template TValue - The validator type for dictionary values
+ *
+ * @example
+ * ```ts
+ * const schema = new DictSchema(l.string(), l.integer())
+ * const result = schema.validate({ a: 1, b: 2, c: 3 })
+ * ```
  */
 class DictSchema extends core_js_1.Schema {
     keySchema;
@@ -50,6 +65,35 @@ class DictSchema extends core_js_1.Schema {
     }
 }
 exports.DictSchema = DictSchema;
+/**
+ * Creates a dictionary schema for validating map-like objects.
+ *
+ * Validates objects where all keys match the key schema and all values
+ * match the value schema. Useful for dynamic key-value mappings.
+ *
+ * @param key - Schema to validate each key (must be a string validator)
+ * @param value - Schema to validate each value
+ * @returns A new {@link DictSchema} instance
+ *
+ * @example
+ * ```ts
+ * // String to number mapping
+ * const scoresSchema = l.dict(l.string(), l.integer())
+ * scoresSchema.parse({ alice: 100, bob: 85 })
+ *
+ * // Constrained keys
+ * const langSchema = l.dict(
+ *   l.string({ minLength: 2, maxLength: 5 }), // Language codes
+ *   l.string() // Translations
+ * )
+ *
+ * // Complex values
+ * const usersById = l.dict(
+ *   l.string({ format: 'did' }),
+ *   l.object({ name: l.string(), age: l.integer() })
+ * )
+ * ```
+ */
 /*@__NO_SIDE_EFFECTS__*/
 function dict(key, value) {
     return new DictSchema(key, value);

package/dist/schema/dict.js.map

@@ -1 +1 @@
-{"version":3,"file":"dict.js","sourceRoot":"","sources":["../../src/schema/dict.ts"],"names":[],"mappings":";;;AAsEA,oBAKC;AA3ED,gDAAiD;AACjD,wCAMmB;AAEnB;;;;GAIG;AACH,MAAa,UAGX,SAAQ,gBAGT;IAEY;IACA;IAFX,YACW,SAAe,EACf,WAAmB;QAE5B,KAAK,EAAE,CAAA;QAHE,cAAS,GAAT,SAAS,CAAM;QACf,gBAAW,GAAX,WAAW,CAAQ;IAG9B,CAAC;IAED,iBAAiB,CACf,KAAc,EACd,GAAsB,EACtB,OAAuD;QAEvD,IAAI,CAAC,IAAA,wBAAa,EAAC,KAAK,CAAC,EAAE,CAAC;YAC1B,OAAO,GAAG,CAAC,gBAAgB,CAAC,KAAK,EAAE,MAAM,CAAC,CAAA;QAC5C,CAAC;QAED,IAAI,IAAyC,CAAA;QAE7C,KAAK,MAAM,GAAG,IAAI,KAAK,EAAE,CAAC;YACxB,IAAI,OAAO,EAAE,WAAW,EAAE,GAAG,CAAC,GAAG,CAAC;gBAAE,SAAQ;YAE5C,MAAM,SAAS,GAAG,GAAG,CAAC,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAC,SAAS,CAAC,CAAA;YACnD,IAAI,CAAC,SAAS,CAAC,OAAO;gBAAE,OAAO,SAAS,CAAA;YACxC,IAAI,SAAS,CAAC,KAAK,KAAK,GAAG,EAAE,CAAC;gBAC5B,mEAAmE;gBACnE,uEAAuE;gBACvE,6DAA6D;gBAC7D,OAAO,GAAG,CAAC,gBAAgB,CAAC,KAAK,EAAE,GAAG,CAAC,CAAA;YACzC,CAAC;YAED,MAAM,WAAW,GAAG,GAAG,CAAC,aAAa,CAAC,KAAK,EAAE,GAAG,EAAE,IAAI,CAAC,WAAW,CAAC,CAAA;YACnE,IAAI,CAAC,WAAW,CAAC,OAAO;gBAAE,OAAO,WAAW,CAAA;YAE5C,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,WAAW,CAAC,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;gBAC9C,IAAI,GAAG,CAAC,OAAO,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;oBACpC,sEAAsE;oBACtE,OAAO,GAAG,CAAC,yBAAyB,CAAC,KAAK,EAAE,GAAG,EAAE,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,CAAA;gBACvE,CAAC;gBAED,IAAI,KAAK,EAAE,GAAG,KAAK,EAAE,CAAA;gBACrB,IAAI,CAAC,GAAG,CAAC,GAAG,WAAW,CAAC,KAAK,CAAA;YAC/B,CAAC;QACH,CAAC;QAED,OAAO,GAAG,CAAC,OAAO,CAAC,IAAI,IAAI,KAAK,CAAC,CAAA;IACnC,CAAC;CACF;AArDD,gCAqDC;AAED,wBAAwB;AACxB,SAAgB,IAAI,CAGlB,GAAS,EAAE,KAAa;IACxB,OAAO,IAAI,UAAU,CAAe,GAAG,EAAE,KAAK,CAAC,CAAA;AACjD,CAAC","sourcesContent":["import { isPlainObject } from '@atproto/lex-data'\nimport {\n  InferInput,\n  InferOutput,\n  Schema,\n  ValidationContext,\n  Validator,\n} from '../core.js'\n\n/**\n * @note There is no dictionary in Lexicon schemas. This is a custom extension\n * to allow map-like objects when using the lex library programmatically (i.e.\n * not code generated from a lexicon schema).\n */\nexport class DictSchema<\n  const TKey extends Validator<string> = any,\n  const TValue extends Validator = any,\n> extends Schema<\n  Record<InferInput<TKey>, InferInput<TValue>>,\n  Record<InferInput<TKey>, InferOutput<TValue>>\n> {\n  constructor(\n    readonly keySchema: TKey,\n    readonly valueSchema: TValue,\n  ) {\n    super()\n  }\n\n  validateInContext(\n    input: unknown,\n    ctx: ValidationContext,\n    options?: { ignoredKeys?: { has(k: string): boolean } },\n  ) {\n    if (!isPlainObject(input)) {\n      return ctx.issueInvalidType(input, 'dict')\n    }\n\n    let copy: undefined | Record<string, unknown>\n\n    for (const key in input) {\n      if (options?.ignoredKeys?.has(key)) continue\n\n      const keyResult = ctx.validate(key, this.keySchema)\n      if (!keyResult.success) return keyResult\n      if (keyResult.value !== key) {\n        // We can't safely \"move\" the key to a different name in the output\n        // object (because there may already be something there), so we issue a\n        // \"required key\" error if the key validation changes the key\n        return ctx.issueRequiredKey(input, key)\n      }\n\n      const valueResult = ctx.validateChild(input, key, this.valueSchema)\n      if (!valueResult.success) return valueResult\n\n      if (!Object.is(valueResult.value, input[key])) {\n        if (ctx.options.mode === 'validate') {\n          // In \"validate\" mode, we can't modify the input, so we issue an error\n          return ctx.issueInvalidPropertyValue(input, key, [valueResult.value])\n        }\n\n        copy ??= { ...input }\n        copy[key] = valueResult.value\n      }\n    }\n\n    return ctx.success(copy ?? input)\n  }\n}\n\n/*@__NO_SIDE_EFFECTS__*/\nexport function dict<\n  const TKey extends Validator<string>,\n  const TValue extends Validator,\n>(key: TKey, value: TValue) {\n  return new DictSchema<TKey, TValue>(key, value)\n}\n"]}
+{"version":3,"file":"dict.js","sourceRoot":"","sources":["../../src/schema/dict.ts"],"names":[],"mappings":";;;AAkHA,oBAKC;AAvHD,gDAAiD;AACjD,wCAMmB;AAEnB;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAa,UAGX,SAAQ,gBAGT;IAEY;IACA;IAFX,YACW,SAAe,EACf,WAAmB;QAE5B,KAAK,EAAE,CAAA;QAHE,cAAS,GAAT,SAAS,CAAM;QACf,gBAAW,GAAX,WAAW,CAAQ;IAG9B,CAAC;IAED,iBAAiB,CACf,KAAc,EACd,GAAsB,EACtB,OAAuD;QAEvD,IAAI,CAAC,IAAA,wBAAa,EAAC,KAAK,CAAC,EAAE,CAAC;YAC1B,OAAO,GAAG,CAAC,gBAAgB,CAAC,KAAK,EAAE,MAAM,CAAC,CAAA;QAC5C,CAAC;QAED,IAAI,IAAyC,CAAA;QAE7C,KAAK,MAAM,GAAG,IAAI,KAAK,EAAE,CAAC;YACxB,IAAI,OAAO,EAAE,WAAW,EAAE,GAAG,CAAC,GAAG,CAAC;gBAAE,SAAQ;YAE5C,MAAM,SAAS,GAAG,GAAG,CAAC,QAAQ,CAAC,GAAG,EAAE,IAAI,CAAC,SAAS,CAAC,CAAA;YACnD,IAAI,CAAC,SAAS,CAAC,OAAO;gBAAE,OAAO,SAAS,CAAA;YACxC,IAAI,SAAS,CAAC,KAAK,KAAK,GAAG,EAAE,CAAC;gBAC5B,mEAAmE;gBACnE,uEAAuE;gBACvE,6DAA6D;gBAC7D,OAAO,GAAG,CAAC,gBAAgB,CAAC,KAAK,EAAE,GAAG,CAAC,CAAA;YACzC,CAAC;YAED,MAAM,WAAW,GAAG,GAAG,CAAC,aAAa,CAAC,KAAK,EAAE,GAAG,EAAE,IAAI,CAAC,WAAW,CAAC,CAAA;YACnE,IAAI,CAAC,WAAW,CAAC,OAAO;gBAAE,OAAO,WAAW,CAAA;YAE5C,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,WAAW,CAAC,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;gBAC9C,IAAI,GAAG,CAAC,OAAO,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;oBACpC,sEAAsE;oBACtE,OAAO,GAAG,CAAC,yBAAyB,CAAC,KAAK,EAAE,GAAG,EAAE,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,CAAA;gBACvE,CAAC;gBAED,IAAI,KAAK,EAAE,GAAG,KAAK,EAAE,CAAA;gBACrB,IAAI,CAAC,GAAG,CAAC,GAAG,WAAW,CAAC,KAAK,CAAA;YAC/B,CAAC;QACH,CAAC;QAED,OAAO,GAAG,CAAC,OAAO,CAAC,IAAI,IAAI,KAAK,CAAC,CAAA;IACnC,CAAC;CACF;AArDD,gCAqDC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAwB;AACxB,SAAgB,IAAI,CAGlB,GAAS,EAAE,KAAa;IACxB,OAAO,IAAI,UAAU,CAAe,GAAG,EAAE,KAAK,CAAC,CAAA;AACjD,CAAC","sourcesContent":["import { isPlainObject } from '@atproto/lex-data'\nimport {\n  InferInput,\n  InferOutput,\n  Schema,\n  ValidationContext,\n  Validator,\n} from '../core.js'\n\n/**\n * Schema for validating dictionary/map-like objects with dynamic keys.\n *\n * Unlike `ObjectSchema` which validates a fixed set of properties, `DictSchema`\n * validates objects where any string key is allowed, with both keys and values\n * validated against their respective schemas.\n *\n * @note There is no dictionary in Lexicon schemas. This is a custom extension\n * to allow map-like objects when using the lex library programmatically (i.e.\n * not code generated from a lexicon schema).\n *\n * @template TKey - The validator type for dictionary keys (must validate strings)\n * @template TValue - The validator type for dictionary values\n *\n * @example\n * ```ts\n * const schema = new DictSchema(l.string(), l.integer())\n * const result = schema.validate({ a: 1, b: 2, c: 3 })\n * ```\n */\nexport class DictSchema<\n  const TKey extends Validator<string> = any,\n  const TValue extends Validator = any,\n> extends Schema<\n  Record<InferInput<TKey>, InferInput<TValue>>,\n  Record<InferInput<TKey>, InferOutput<TValue>>\n> {\n  constructor(\n    readonly keySchema: TKey,\n    readonly valueSchema: TValue,\n  ) {\n    super()\n  }\n\n  validateInContext(\n    input: unknown,\n    ctx: ValidationContext,\n    options?: { ignoredKeys?: { has(k: string): boolean } },\n  ) {\n    if (!isPlainObject(input)) {\n      return ctx.issueInvalidType(input, 'dict')\n    }\n\n    let copy: undefined | Record<string, unknown>\n\n    for (const key in input) {\n      if (options?.ignoredKeys?.has(key)) continue\n\n      const keyResult = ctx.validate(key, this.keySchema)\n      if (!keyResult.success) return keyResult\n      if (keyResult.value !== key) {\n        // We can't safely \"move\" the key to a different name in the output\n        // object (because there may already be something there), so we issue a\n        // \"required key\" error if the key validation changes the key\n        return ctx.issueRequiredKey(input, key)\n      }\n\n      const valueResult = ctx.validateChild(input, key, this.valueSchema)\n      if (!valueResult.success) return valueResult\n\n      if (!Object.is(valueResult.value, input[key])) {\n        if (ctx.options.mode === 'validate') {\n          // In \"validate\" mode, we can't modify the input, so we issue an error\n          return ctx.issueInvalidPropertyValue(input, key, [valueResult.value])\n        }\n\n        copy ??= { ...input }\n        copy[key] = valueResult.value\n      }\n    }\n\n    return ctx.success(copy ?? input)\n  }\n}\n\n/**\n * Creates a dictionary schema for validating map-like objects.\n *\n * Validates objects where all keys match the key schema and all values\n * match the value schema. Useful for dynamic key-value mappings.\n *\n * @param key - Schema to validate each key (must be a string validator)\n * @param value - Schema to validate each value\n * @returns A new {@link DictSchema} instance\n *\n * @example\n * ```ts\n * // String to number mapping\n * const scoresSchema = l.dict(l.string(), l.integer())\n * scoresSchema.parse({ alice: 100, bob: 85 })\n *\n * // Constrained keys\n * const langSchema = l.dict(\n *   l.string({ minLength: 2, maxLength: 5 }), // Language codes\n *   l.string() // Translations\n * )\n *\n * // Complex values\n * const usersById = l.dict(\n *   l.string({ format: 'did' }),\n *   l.object({ name: l.string(), age: l.integer() })\n * )\n * ```\n */\n/*@__NO_SIDE_EFFECTS__*/\nexport function dict<\n  const TKey extends Validator<string>,\n  const TValue extends Validator,\n>(key: TKey, value: TValue) {\n  return new DictSchema<TKey, TValue>(key, value)\n}\n"]}

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

@@ -2,7 +2,20 @@ import { InferInput, InferOutput, Schema, ValidationContext, ValidationResult, V
 import { EnumSchema } from './enum.js';
 import { LiteralSchema } from './literal.js';
 import { ObjectSchema } from './object.js';
+/**
+ * Type representing a single variant in a discriminated union.
+ *
+ * Must be an ObjectSchema with the discriminator property using either
+ * a LiteralSchema or EnumSchema.
+ *
+ * @template Discriminator - The discriminator property name
+ */
 export type DiscriminatedUnionVariant<Discriminator extends string = string> = ObjectSchema<Record<Discriminator, EnumSchema<any> | LiteralSchema<any>>>;
+/**
+ * Type representing a non-empty tuple of discriminated union variants.
+ *
+ * @template TDiscriminator - The discriminator property name
+ */
 export type DiscriminatedUnionVariants<TDiscriminator extends string> = readonly [
     DiscriminatedUnionVariant<TDiscriminator>,
     ...DiscriminatedUnionVariant<TDiscriminator>[]
@@ -16,9 +29,26 @@ type DiscriminatedUnionSchemaOutput<TVariants extends readonly Validator[]> = TV
     ...infer TRest extends readonly Validator[]
 ] ? InferOutput<TValidator> | DiscriminatedUnionSchemaOutput<TRest> : never;
 /**
+ * Schema for validating discriminated unions of objects.
+ *
+ * More efficient than regular union schemas when discriminating on a known
+ * property. Looks up the correct variant schema directly based on the
+ * discriminator value instead of trying each variant in sequence.
+ *
  * @note There is no discriminated union in Lexicon schemas. This is a custom
  * extension to allow optimized validation of union of objects when using the
  * lex library programmatically (i.e. not code generated from a lexicon schema).
+ *
+ * @template TDiscriminator - The discriminator property name
+ * @template TVariants - Tuple type of the variant schemas
+ *
+ * @example
+ * ```ts
+ * const schema = new DiscriminatedUnionSchema('type', [
+ *   l.object({ type: l.literal('text'), content: l.string() }),
+ *   l.object({ type: l.literal('image'), url: l.string() }),
+ * ])
+ * ```
  */
 export declare class DiscriminatedUnionSchema<const TDiscriminator extends string, const TVariants extends DiscriminatedUnionVariants<TDiscriminator>> extends Schema<DiscriminatedUnionSchemaInput<TVariants>, DiscriminatedUnionSchemaOutput<TVariants>> {
     readonly discriminator: TDiscriminator;
@@ -27,6 +57,34 @@ export declare class DiscriminatedUnionSchema<const TDiscriminator extends strin
     constructor(discriminator: TDiscriminator, variants: TVariants);
     validateInContext(input: unknown, ctx: ValidationContext): ValidationResult<DiscriminatedUnionSchemaInput<TVariants>>;
 }
+/**
+ * Creates a discriminated union schema for efficient object type switching.
+ *
+ * Unlike regular `union()`, this schema uses a discriminator property to
+ * directly look up the correct variant, providing O(1) validation instead
+ * of trying each variant sequentially.
+ *
+ * @param discriminator - Property name to discriminate on
+ * @param variants - Non-empty array of object schemas with the discriminator property
+ * @returns A new {@link DiscriminatedUnionSchema} instance
+ *
+ * @example
+ * ```ts
+ * // Message types discriminated by 'kind'
+ * const messageSchema = l.discriminatedUnion('kind', [
+ *   l.object({ kind: l.literal('text'), text: l.string() }),
+ *   l.object({ kind: l.literal('image'), url: l.string(), alt: l.optional(l.string()) }),
+ *   l.object({ kind: l.literal('video'), url: l.string(), duration: l.integer() }),
+ * ])
+ *
+ * // Using enums for multiple values mapping to same variant
+ * const statusSchema = l.discriminatedUnion('status', [
+ *   l.object({ status: l.enum(['pending', 'processing']), startedAt: l.string() }),
+ *   l.object({ status: l.literal('completed'), completedAt: l.string() }),
+ *   l.object({ status: l.literal('failed'), error: l.string() }),
+ * ])
+ * ```
+ */
 export declare function discriminatedUnion<const Discriminator extends string, const Options extends DiscriminatedUnionVariants<Discriminator>>(discriminator: Discriminator, variants: Options): DiscriminatedUnionSchema<Discriminator, Options>;
 export {};
 //# sourceMappingURL=discriminated-union.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"discriminated-union.d.ts","sourceRoot":"","sources":["../../src/schema/discriminated-union.ts"],"names":[],"mappings":"AACA,OAAO,EACL,UAAU,EACV,WAAW,EACX,MAAM,EACN,iBAAiB,EACjB,gBAAgB,EAChB,SAAS,EACV,MAAM,YAAY,CAAA;AACnB,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA;AACtC,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAC5C,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAE1C,MAAM,MAAM,yBAAyB,CAAC,aAAa,SAAS,MAAM,GAAG,MAAM,IACzE,YAAY,CAAC,MAAM,CAAC,aAAa,EAAE,UAAU,CAAC,GAAG,CAAC,GAAG,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,CAAA;AAE3E,MAAM,MAAM,0BAA0B,CAAC,cAAc,SAAS,MAAM,IAClE,SAAS;IACP,yBAAyB,CAAC,cAAc,CAAC;IACzC,GAAG,yBAAyB,CAAC,cAAc,CAAC,EAAE;CAC/C,CAAA;AAEH,KAAK,6BAA6B,CAAC,SAAS,SAAS,SAAS,SAAS,EAAE,IACvE,SAAS,SAAS,SAAS;IACzB,MAAM,UAAU,SAAS,SAAS;IAClC,GAAG,MAAM,KAAK,SAAS,SAAS,SAAS,EAAE;CAC5C,GACG,UAAU,CAAC,UAAU,CAAC,GAAG,6BAA6B,CAAC,KAAK,CAAC,GAC7D,KAAK,CAAA;AAEX,KAAK,8BAA8B,CAAC,SAAS,SAAS,SAAS,SAAS,EAAE,IACxE,SAAS,SAAS,SAAS;IACzB,MAAM,UAAU,SAAS,SAAS;IAClC,GAAG,MAAM,KAAK,SAAS,SAAS,SAAS,EAAE;CAC5C,GACG,WAAW,CAAC,UAAU,CAAC,GAAG,8BAA8B,CAAC,KAAK,CAAC,GAC/D,KAAK,CAAA;AAEX;;;;GAIG;AACH,qBAAa,wBAAwB,CACnC,KAAK,CAAC,cAAc,SAAS,MAAM,EACnC,KAAK,CAAC,SAAS,SAAS,0BAA0B,CAAC,cAAc,CAAC,CAClE,SAAQ,MAAM,CACd,6BAA6B,CAAC,SAAS,CAAC,EACxC,8BAA8B,CAAC,SAAS,CAAC,CAC1C;IAIG,QAAQ,CAAC,aAAa,EAAE,cAAc;IACtC,QAAQ,CAAC,QAAQ,EAAE,SAAS;IAJ9B,QAAQ,CAAC,WAAW,EAAE,GAAG,CAAC,OAAO,EAAE,yBAAyB,CAAC,cAAc,CAAC,CAAC,CAAA;gBAGlE,aAAa,EAAE,cAAc,EAC7B,QAAQ,EAAE,SAAS;IAU9B,iBAAiB,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,iBAAiB;CAwBzD;AAuCD,wBAAgB,kBAAkB,CAChC,KAAK,CAAC,aAAa,SAAS,MAAM,EAClC,KAAK,CAAC,OAAO,SAAS,0BAA0B,CAAC,aAAa,CAAC,EAC/D,aAAa,EAAE,aAAa,EAAE,QAAQ,EAAE,OAAO,oDAKhD"}
+{"version":3,"file":"discriminated-union.d.ts","sourceRoot":"","sources":["../../src/schema/discriminated-union.ts"],"names":[],"mappings":"AACA,OAAO,EACL,UAAU,EACV,WAAW,EACX,MAAM,EACN,iBAAiB,EACjB,gBAAgB,EAChB,SAAS,EACV,MAAM,YAAY,CAAA;AACnB,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA;AACtC,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAC5C,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAE1C;;;;;;;GAOG;AACH,MAAM,MAAM,yBAAyB,CAAC,aAAa,SAAS,MAAM,GAAG,MAAM,IACzE,YAAY,CAAC,MAAM,CAAC,aAAa,EAAE,UAAU,CAAC,GAAG,CAAC,GAAG,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,CAAA;AAE3E;;;;GAIG;AACH,MAAM,MAAM,0BAA0B,CAAC,cAAc,SAAS,MAAM,IAClE,SAAS;IACP,yBAAyB,CAAC,cAAc,CAAC;IACzC,GAAG,yBAAyB,CAAC,cAAc,CAAC,EAAE;CAC/C,CAAA;AAEH,KAAK,6BAA6B,CAAC,SAAS,SAAS,SAAS,SAAS,EAAE,IACvE,SAAS,SAAS,SAAS;IACzB,MAAM,UAAU,SAAS,SAAS;IAClC,GAAG,MAAM,KAAK,SAAS,SAAS,SAAS,EAAE;CAC5C,GACG,UAAU,CAAC,UAAU,CAAC,GAAG,6BAA6B,CAAC,KAAK,CAAC,GAC7D,KAAK,CAAA;AAEX,KAAK,8BAA8B,CAAC,SAAS,SAAS,SAAS,SAAS,EAAE,IACxE,SAAS,SAAS,SAAS;IACzB,MAAM,UAAU,SAAS,SAAS;IAClC,GAAG,MAAM,KAAK,SAAS,SAAS,SAAS,EAAE;CAC5C,GACG,WAAW,CAAC,UAAU,CAAC,GAAG,8BAA8B,CAAC,KAAK,CAAC,GAC/D,KAAK,CAAA;AAEX;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,wBAAwB,CACnC,KAAK,CAAC,cAAc,SAAS,MAAM,EACnC,KAAK,CAAC,SAAS,SAAS,0BAA0B,CAAC,cAAc,CAAC,CAClE,SAAQ,MAAM,CACd,6BAA6B,CAAC,SAAS,CAAC,EACxC,8BAA8B,CAAC,SAAS,CAAC,CAC1C;IAIG,QAAQ,CAAC,aAAa,EAAE,cAAc;IACtC,QAAQ,CAAC,QAAQ,EAAE,SAAS;IAJ9B,QAAQ,CAAC,WAAW,EAAE,GAAG,CAAC,OAAO,EAAE,yBAAyB,CAAC,cAAc,CAAC,CAAC,CAAA;gBAGlE,aAAa,EAAE,cAAc,EAC7B,QAAQ,EAAE,SAAS;IAU9B,iBAAiB,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,iBAAiB;CAwBzD;AAsCD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,wBAAgB,kBAAkB,CAChC,KAAK,CAAC,aAAa,SAAS,MAAM,EAClC,KAAK,CAAC,OAAO,SAAS,0BAA0B,CAAC,aAAa,CAAC,EAC/D,aAAa,EAAE,aAAa,EAAE,QAAQ,EAAE,OAAO,oDAKhD"}

package/dist/schema/discriminated-union.js

@@ -7,9 +7,26 @@ const core_js_1 = require("../core.js");
 const enum_js_1 = require("./enum.js");
 const literal_js_1 = require("./literal.js");
 /**
+ * Schema for validating discriminated unions of objects.
+ *
+ * More efficient than regular union schemas when discriminating on a known
+ * property. Looks up the correct variant schema directly based on the
+ * discriminator value instead of trying each variant in sequence.
+ *
  * @note There is no discriminated union in Lexicon schemas. This is a custom
  * extension to allow optimized validation of union of objects when using the
  * lex library programmatically (i.e. not code generated from a lexicon schema).
+ *
+ * @template TDiscriminator - The discriminator property name
+ * @template TVariants - Tuple type of the variant schemas
+ *
+ * @example
+ * ```ts
+ * const schema = new DiscriminatedUnionSchema('type', [
+ *   l.object({ type: l.literal('text'), content: l.string() }),
+ *   l.object({ type: l.literal('image'), url: l.string() }),
+ * ])
+ * ```
  */
 class DiscriminatedUnionSchema extends core_js_1.Schema {
     discriminator;
@@ -69,6 +86,34 @@ function buildVariantsMap(discriminator, variants) {
     }
     return variantsMap;
 }
+/**
+ * Creates a discriminated union schema for efficient object type switching.
+ *
+ * Unlike regular `union()`, this schema uses a discriminator property to
+ * directly look up the correct variant, providing O(1) validation instead
+ * of trying each variant sequentially.
+ *
+ * @param discriminator - Property name to discriminate on
+ * @param variants - Non-empty array of object schemas with the discriminator property
+ * @returns A new {@link DiscriminatedUnionSchema} instance
+ *
+ * @example
+ * ```ts
+ * // Message types discriminated by 'kind'
+ * const messageSchema = l.discriminatedUnion('kind', [
+ *   l.object({ kind: l.literal('text'), text: l.string() }),
+ *   l.object({ kind: l.literal('image'), url: l.string(), alt: l.optional(l.string()) }),
+ *   l.object({ kind: l.literal('video'), url: l.string(), duration: l.integer() }),
+ * ])
+ *
+ * // Using enums for multiple values mapping to same variant
+ * const statusSchema = l.discriminatedUnion('status', [
+ *   l.object({ status: l.enum(['pending', 'processing']), startedAt: l.string() }),
+ *   l.object({ status: l.literal('completed'), completedAt: l.string() }),
+ *   l.object({ status: l.literal('failed'), error: l.string() }),
+ * ])
+ * ```
+ */
 /*@__NO_SIDE_EFFECTS__*/
 function discriminatedUnion(discriminator, variants) {
     return new DiscriminatedUnionSchema(discriminator, variants);

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

@@ -1 +1 @@
-{"version":3,"file":"discriminated-union.js","sourceRoot":"","sources":["../../src/schema/discriminated-union.ts"],"names":[],"mappings":";;;AA+HA,gDAQC;AAvID,gDAAiD;AACjD,wCAOmB;AACnB,uCAAsC;AACtC,6CAA4C;AA4B5C;;;;GAIG;AACH,MAAa,wBAGX,SAAQ,gBAGT;IAIY;IACA;IAJF,WAAW,CAAyD;IAE7E,YACW,aAA6B,EAC7B,QAAmB;QAE5B,KAAK,EAAE,CAAA;QAHE,kBAAa,GAAb,aAAa,CAAgB;QAC7B,aAAQ,GAAR,QAAQ,CAAW;QAI5B,wEAAwE;QACxE,2EAA2E;QAC3E,8DAA8D;QAC9D,IAAI,CAAC,WAAW,GAAG,gBAAgB,CAAC,aAAa,EAAE,QAAQ,CAAC,CAAA;IAC9D,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,MAAM,EAAE,aAAa,EAAE,GAAG,IAAI,CAAA;QAE9B,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,aAAa,CAAC,EAAE,CAAC;YACzC,OAAO,GAAG,CAAC,gBAAgB,CAAC,KAAK,EAAE,aAAa,CAAC,CAAA;QACnD,CAAC;QAED,MAAM,kBAAkB,GAAG,KAAK,CAAC,aAAa,CAAC,CAAA;QAE/C,MAAM,OAAO,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAA;QACxD,IAAI,OAAO,EAAE,CAAC;YACZ,OAAO,GAAG,CAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAEjC,CAAA;QACH,CAAC;QAED,OAAO,GAAG,CAAC,yBAAyB,CAAC,KAAK,EAAE,aAAa,EAAE;YACzD,GAAG,IAAI,CAAC,WAAW,CAAC,IAAI,EAAE;SAC3B,CAAC,CAAA;IACJ,CAAC;CACF;AA7CD,4DA6CC;AAED,SAAS,gBAAgB,CACvB,aAA4B,EAC5B,QAAmD;IAEnD,MAAM,WAAW,GAAG,IAAI,GAAG,EAGxB,CAAA;IAEH,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,MAAM,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,aAAa,CAAC,CAAA;QAC3C,IAAI,MAAM,YAAY,0BAAa,EAAE,CAAC;YACpC,IAAI,WAAW,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;gBAClC,MAAM,IAAI,SAAS,CAAC,oCAAoC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAA;YACzE,CAAC;YACD,WAAW,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,EAAE,OAAO,CAAC,CAAA;QACxC,CAAC;aAAM,IAAI,MAAM,YAAY,oBAAU,EAAE,CAAC;YACxC,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;gBAChC,IAAI,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;oBACzB,MAAM,IAAI,SAAS,CAAC,oCAAoC,GAAG,EAAE,CAAC,CAAA;gBAChE,CAAC;gBACD,WAAW,CAAC,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,CAAA;YAC/B,CAAC;QACH,CAAC;aAAM,CAAC;YACN,sDAAsD;YAEtD,kDAAkD;YAClD,MAAM,IAAI,SAAS,CACjB,4DAA4D,CAC7D,CAAA;QACH,CAAC;IACH,CAAC;IAED,OAAO,WAAW,CAAA;AACpB,CAAC;AAED,wBAAwB;AACxB,SAAgB,kBAAkB,CAGhC,aAA4B,EAAE,QAAiB;IAC/C,OAAO,IAAI,wBAAwB,CACjC,aAAa,EACb,QAAQ,CACT,CAAA;AACH,CAAC","sourcesContent":["import { isPlainObject } from '@atproto/lex-data'\nimport {\n  InferInput,\n  InferOutput,\n  Schema,\n  ValidationContext,\n  ValidationResult,\n  Validator,\n} from '../core.js'\nimport { EnumSchema } from './enum.js'\nimport { LiteralSchema } from './literal.js'\nimport { ObjectSchema } from './object.js'\n\nexport type DiscriminatedUnionVariant<Discriminator extends string = string> =\n  ObjectSchema<Record<Discriminator, EnumSchema<any> | LiteralSchema<any>>>\n\nexport type DiscriminatedUnionVariants<TDiscriminator extends string> =\n  readonly [\n    DiscriminatedUnionVariant<TDiscriminator>,\n    ...DiscriminatedUnionVariant<TDiscriminator>[],\n  ]\n\ntype DiscriminatedUnionSchemaInput<TVariants extends readonly Validator[]> =\n  TVariants extends readonly [\n    infer TValidator extends Validator,\n    ...infer TRest extends readonly Validator[],\n  ]\n    ? InferInput<TValidator> | DiscriminatedUnionSchemaInput<TRest>\n    : never\n\ntype DiscriminatedUnionSchemaOutput<TVariants extends readonly Validator[]> =\n  TVariants extends readonly [\n    infer TValidator extends Validator,\n    ...infer TRest extends readonly Validator[],\n  ]\n    ? InferOutput<TValidator> | DiscriminatedUnionSchemaOutput<TRest>\n    : never\n\n/**\n * @note There is no discriminated union in Lexicon schemas. This is a custom\n * extension to allow optimized validation of union of objects when using the\n * lex library programmatically (i.e. not code generated from a lexicon schema).\n */\nexport class DiscriminatedUnionSchema<\n  const TDiscriminator extends string,\n  const TVariants extends DiscriminatedUnionVariants<TDiscriminator>,\n> extends Schema<\n  DiscriminatedUnionSchemaInput<TVariants>,\n  DiscriminatedUnionSchemaOutput<TVariants>\n> {\n  readonly variantsMap: Map<unknown, DiscriminatedUnionVariant<TDiscriminator>>\n\n  constructor(\n    readonly discriminator: TDiscriminator,\n    readonly variants: TVariants,\n  ) {\n    super()\n\n    // Although we usually try to avoid initialization work in constructors,\n    // here it is necessary to ensure that invalid discriminated throw from the\n    // place of construction, rather than later during validation.\n    this.variantsMap = buildVariantsMap(discriminator, variants)\n  }\n\n  validateInContext(input: unknown, ctx: ValidationContext) {\n    if (!isPlainObject(input)) {\n      return ctx.issueInvalidType(input, 'object')\n    }\n\n    const { discriminator } = this\n\n    if (!Object.hasOwn(input, discriminator)) {\n      return ctx.issueRequiredKey(input, discriminator)\n    }\n\n    const discriminatorValue = input[discriminator]\n\n    const variant = this.variantsMap.get(discriminatorValue)\n    if (variant) {\n      return ctx.validate(input, variant) as ValidationResult<\n        DiscriminatedUnionSchemaInput<TVariants>\n      >\n    }\n\n    return ctx.issueInvalidPropertyValue(input, discriminator, [\n      ...this.variantsMap.keys(),\n    ])\n  }\n}\n\nfunction buildVariantsMap<Discriminator extends string>(\n  discriminator: Discriminator,\n  variants: DiscriminatedUnionVariants<Discriminator>,\n) {\n  const variantsMap = new Map<\n    unknown,\n    DiscriminatedUnionVariant<Discriminator>\n  >()\n\n  for (const variant of variants) {\n    const schema = variant.shape[discriminator]\n    if (schema instanceof LiteralSchema) {\n      if (variantsMap.has(schema.value)) {\n        throw new TypeError(`Overlapping discriminator value: ${schema.value}`)\n      }\n      variantsMap.set(schema.value, variant)\n    } else if (schema instanceof EnumSchema) {\n      for (const val of schema.values) {\n        if (variantsMap.has(val)) {\n          throw new TypeError(`Overlapping discriminator value: ${val}`)\n        }\n        variantsMap.set(val, variant)\n      }\n    } else {\n      // Only enumerable discriminator schemas are supported\n\n      // Should never happen if types are used correctly\n      throw new TypeError(\n        `Discriminator schema must be a LiteralSchema or EnumSchema`,\n      )\n    }\n  }\n\n  return variantsMap\n}\n\n/*@__NO_SIDE_EFFECTS__*/\nexport function discriminatedUnion<\n  const Discriminator extends string,\n  const Options extends DiscriminatedUnionVariants<Discriminator>,\n>(discriminator: Discriminator, variants: Options) {\n  return new DiscriminatedUnionSchema<Discriminator, Options>(\n    discriminator,\n    variants,\n  )\n}\n"]}
+{"version":3,"file":"discriminated-union.js","sourceRoot":"","sources":["../../src/schema/discriminated-union.ts"],"names":[],"mappings":";;;AAyLA,gDAQC;AAjMD,gDAAiD;AACjD,wCAOmB;AACnB,uCAAsC;AACtC,6CAA4C;AAyC5C;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAa,wBAGX,SAAQ,gBAGT;IAIY;IACA;IAJF,WAAW,CAAyD;IAE7E,YACW,aAA6B,EAC7B,QAAmB;QAE5B,KAAK,EAAE,CAAA;QAHE,kBAAa,GAAb,aAAa,CAAgB;QAC7B,aAAQ,GAAR,QAAQ,CAAW;QAI5B,wEAAwE;QACxE,2EAA2E;QAC3E,8DAA8D;QAC9D,IAAI,CAAC,WAAW,GAAG,gBAAgB,CAAC,aAAa,EAAE,QAAQ,CAAC,CAAA;IAC9D,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,MAAM,EAAE,aAAa,EAAE,GAAG,IAAI,CAAA;QAE9B,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,aAAa,CAAC,EAAE,CAAC;YACzC,OAAO,GAAG,CAAC,gBAAgB,CAAC,KAAK,EAAE,aAAa,CAAC,CAAA;QACnD,CAAC;QAED,MAAM,kBAAkB,GAAG,KAAK,CAAC,aAAa,CAAC,CAAA;QAE/C,MAAM,OAAO,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAA;QACxD,IAAI,OAAO,EAAE,CAAC;YACZ,OAAO,GAAG,CAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAEjC,CAAA;QACH,CAAC;QAED,OAAO,GAAG,CAAC,yBAAyB,CAAC,KAAK,EAAE,aAAa,EAAE;YACzD,GAAG,IAAI,CAAC,WAAW,CAAC,IAAI,EAAE;SAC3B,CAAC,CAAA;IACJ,CAAC;CACF;AA7CD,4DA6CC;AAED,SAAS,gBAAgB,CACvB,aAA4B,EAC5B,QAAmD;IAEnD,MAAM,WAAW,GAAG,IAAI,GAAG,EAGxB,CAAA;IAEH,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,MAAM,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,aAAa,CAAC,CAAA;QAC3C,IAAI,MAAM,YAAY,0BAAa,EAAE,CAAC;YACpC,IAAI,WAAW,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;gBAClC,MAAM,IAAI,SAAS,CAAC,oCAAoC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAA;YACzE,CAAC;YACD,WAAW,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,EAAE,OAAO,CAAC,CAAA;QACxC,CAAC;aAAM,IAAI,MAAM,YAAY,oBAAU,EAAE,CAAC;YACxC,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;gBAChC,IAAI,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;oBACzB,MAAM,IAAI,SAAS,CAAC,oCAAoC,GAAG,EAAE,CAAC,CAAA;gBAChE,CAAC;gBACD,WAAW,CAAC,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,CAAA;YAC/B,CAAC;QACH,CAAC;aAAM,CAAC;YACN,sDAAsD;YAEtD,kDAAkD;YAClD,MAAM,IAAI,SAAS,CACjB,4DAA4D,CAC7D,CAAA;QACH,CAAC;IACH,CAAC;IAED,OAAO,WAAW,CAAA;AACpB,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAwB;AACxB,SAAgB,kBAAkB,CAGhC,aAA4B,EAAE,QAAiB;IAC/C,OAAO,IAAI,wBAAwB,CACjC,aAAa,EACb,QAAQ,CACT,CAAA;AACH,CAAC","sourcesContent":["import { isPlainObject } from '@atproto/lex-data'\nimport {\n  InferInput,\n  InferOutput,\n  Schema,\n  ValidationContext,\n  ValidationResult,\n  Validator,\n} from '../core.js'\nimport { EnumSchema } from './enum.js'\nimport { LiteralSchema } from './literal.js'\nimport { ObjectSchema } from './object.js'\n\n/**\n * Type representing a single variant in a discriminated union.\n *\n * Must be an ObjectSchema with the discriminator property using either\n * a LiteralSchema or EnumSchema.\n *\n * @template Discriminator - The discriminator property name\n */\nexport type DiscriminatedUnionVariant<Discriminator extends string = string> =\n  ObjectSchema<Record<Discriminator, EnumSchema<any> | LiteralSchema<any>>>\n\n/**\n * Type representing a non-empty tuple of discriminated union variants.\n *\n * @template TDiscriminator - The discriminator property name\n */\nexport type DiscriminatedUnionVariants<TDiscriminator extends string> =\n  readonly [\n    DiscriminatedUnionVariant<TDiscriminator>,\n    ...DiscriminatedUnionVariant<TDiscriminator>[],\n  ]\n\ntype DiscriminatedUnionSchemaInput<TVariants extends readonly Validator[]> =\n  TVariants extends readonly [\n    infer TValidator extends Validator,\n    ...infer TRest extends readonly Validator[],\n  ]\n    ? InferInput<TValidator> | DiscriminatedUnionSchemaInput<TRest>\n    : never\n\ntype DiscriminatedUnionSchemaOutput<TVariants extends readonly Validator[]> =\n  TVariants extends readonly [\n    infer TValidator extends Validator,\n    ...infer TRest extends readonly Validator[],\n  ]\n    ? InferOutput<TValidator> | DiscriminatedUnionSchemaOutput<TRest>\n    : never\n\n/**\n * Schema for validating discriminated unions of objects.\n *\n * More efficient than regular union schemas when discriminating on a known\n * property. Looks up the correct variant schema directly based on the\n * discriminator value instead of trying each variant in sequence.\n *\n * @note There is no discriminated union in Lexicon schemas. This is a custom\n * extension to allow optimized validation of union of objects when using the\n * lex library programmatically (i.e. not code generated from a lexicon schema).\n *\n * @template TDiscriminator - The discriminator property name\n * @template TVariants - Tuple type of the variant schemas\n *\n * @example\n * ```ts\n * const schema = new DiscriminatedUnionSchema('type', [\n *   l.object({ type: l.literal('text'), content: l.string() }),\n *   l.object({ type: l.literal('image'), url: l.string() }),\n * ])\n * ```\n */\nexport class DiscriminatedUnionSchema<\n  const TDiscriminator extends string,\n  const TVariants extends DiscriminatedUnionVariants<TDiscriminator>,\n> extends Schema<\n  DiscriminatedUnionSchemaInput<TVariants>,\n  DiscriminatedUnionSchemaOutput<TVariants>\n> {\n  readonly variantsMap: Map<unknown, DiscriminatedUnionVariant<TDiscriminator>>\n\n  constructor(\n    readonly discriminator: TDiscriminator,\n    readonly variants: TVariants,\n  ) {\n    super()\n\n    // Although we usually try to avoid initialization work in constructors,\n    // here it is necessary to ensure that invalid discriminated throw from the\n    // place of construction, rather than later during validation.\n    this.variantsMap = buildVariantsMap(discriminator, variants)\n  }\n\n  validateInContext(input: unknown, ctx: ValidationContext) {\n    if (!isPlainObject(input)) {\n      return ctx.issueInvalidType(input, 'object')\n    }\n\n    const { discriminator } = this\n\n    if (!Object.hasOwn(input, discriminator)) {\n      return ctx.issueRequiredKey(input, discriminator)\n    }\n\n    const discriminatorValue = input[discriminator]\n\n    const variant = this.variantsMap.get(discriminatorValue)\n    if (variant) {\n      return ctx.validate(input, variant) as ValidationResult<\n        DiscriminatedUnionSchemaInput<TVariants>\n      >\n    }\n\n    return ctx.issueInvalidPropertyValue(input, discriminator, [\n      ...this.variantsMap.keys(),\n    ])\n  }\n}\n\nfunction buildVariantsMap<Discriminator extends string>(\n  discriminator: Discriminator,\n  variants: DiscriminatedUnionVariants<Discriminator>,\n) {\n  const variantsMap = new Map<\n    unknown,\n    DiscriminatedUnionVariant<Discriminator>\n  >()\n\n  for (const variant of variants) {\n    const schema = variant.shape[discriminator]\n    if (schema instanceof LiteralSchema) {\n      if (variantsMap.has(schema.value)) {\n        throw new TypeError(`Overlapping discriminator value: ${schema.value}`)\n      }\n      variantsMap.set(schema.value, variant)\n    } else if (schema instanceof EnumSchema) {\n      for (const val of schema.values) {\n        if (variantsMap.has(val)) {\n          throw new TypeError(`Overlapping discriminator value: ${val}`)\n        }\n        variantsMap.set(val, variant)\n      }\n    } else {\n      // Only enumerable discriminator schemas are supported\n\n      // Should never happen if types are used correctly\n      throw new TypeError(\n        `Discriminator schema must be a LiteralSchema or EnumSchema`,\n      )\n    }\n  }\n\n  return variantsMap\n}\n\n/**\n * Creates a discriminated union schema for efficient object type switching.\n *\n * Unlike regular `union()`, this schema uses a discriminator property to\n * directly look up the correct variant, providing O(1) validation instead\n * of trying each variant sequentially.\n *\n * @param discriminator - Property name to discriminate on\n * @param variants - Non-empty array of object schemas with the discriminator property\n * @returns A new {@link DiscriminatedUnionSchema} instance\n *\n * @example\n * ```ts\n * // Message types discriminated by 'kind'\n * const messageSchema = l.discriminatedUnion('kind', [\n *   l.object({ kind: l.literal('text'), text: l.string() }),\n *   l.object({ kind: l.literal('image'), url: l.string(), alt: l.optional(l.string()) }),\n *   l.object({ kind: l.literal('video'), url: l.string(), duration: l.integer() }),\n * ])\n *\n * // Using enums for multiple values mapping to same variant\n * const statusSchema = l.discriminatedUnion('status', [\n *   l.object({ status: l.enum(['pending', 'processing']), startedAt: l.string() }),\n *   l.object({ status: l.literal('completed'), completedAt: l.string() }),\n *   l.object({ status: l.literal('failed'), error: l.string() }),\n * ])\n * ```\n */\n/*@__NO_SIDE_EFFECTS__*/\nexport function discriminatedUnion<\n  const Discriminator extends string,\n  const Options extends DiscriminatedUnionVariants<Discriminator>,\n>(discriminator: Discriminator, variants: Options) {\n  return new DiscriminatedUnionSchema<Discriminator, Options>(\n    discriminator,\n    variants,\n  )\n}\n"]}

package/dist/schema/enum.d.ts

@@ -1,9 +1,57 @@
 import { Schema, ValidationContext } from '../core.js';
+/**
+ * Schema that accepts one of several specific literal values.
+ *
+ * Validates that the input matches one of the allowed values using strict
+ * equality. Similar to TypeScript union of literals.
+ *
+ * @template TValue - The union of literal types
+ *
+ * @example
+ * ```ts
+ * const schema = new EnumSchema(['pending', 'active', 'completed'])
+ * schema.validate('active')  // success
+ * schema.validate('invalid') // fails
+ * ```
+ */
 export declare class EnumSchema<const TValue extends null | string | number | boolean> extends Schema<TValue> {
     readonly values: readonly TValue[];
     constructor(values: readonly TValue[]);
     validateInContext(input: unknown, ctx: ValidationContext): import("../core.js").ValidationResult<TValue>;
 }
+/**
+ * Creates an enum schema that accepts one of the specified values.
+ *
+ * Similar to TypeScript's union of string literals. Use `l.enum()` for
+ * the namespace-friendly alias.
+ *
+ * @param value - Array of allowed values
+ * @returns A new {@link EnumSchema} instance
+ *
+ * @example
+ * ```ts
+ * // String enum
+ * const statusSchema = l.enum(['pending', 'active', 'completed', 'failed'])
+ *
+ * // Number enum
+ * const prioritySchema = l.enum([1, 2, 3, 4, 5])
+ *
+ * // Mixed types
+ * const mixedSchema = l.enum(['auto', 0, 1, true])
+ *
+ * // Use in objects
+ * const taskSchema = l.object({
+ *   title: l.string(),
+ *   status: l.enum(['todo', 'in-progress', 'done']),
+ * })
+ *
+ * // In discriminated unions
+ * const resultSchema = l.discriminatedUnion('status', [
+ *   l.object({ status: l.enum(['pending', 'processing']), progress: l.integer() }),
+ *   l.object({ status: l.literal('completed'), result: l.unknown() }),
+ * ])
+ * ```
+ */
 export declare function enumSchema<const V extends null | string | number | boolean>(value: readonly V[]): EnumSchema<V>;
 export { enumSchema as enum };
 //# sourceMappingURL=enum.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"enum.d.ts","sourceRoot":"","sources":["../../src/schema/enum.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAEtD,qBAAa,UAAU,CACrB,KAAK,CAAC,MAAM,SAAS,IAAI,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CACrD,SAAQ,MAAM,CAAC,MAAM,CAAC;IACV,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE;gBAAzB,MAAM,EAAE,SAAS,MAAM,EAAE;IAI9C,iBAAiB,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,iBAAiB;CAOzD;AAGD,wBAAgB,UAAU,CAAC,KAAK,CAAC,CAAC,SAAS,IAAI,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,EACzE,KAAK,EAAE,SAAS,CAAC,EAAE,iBAGpB;AAGD,OAAO,EAAE,UAAU,IAAI,IAAI,EAAE,CAAA"}
+{"version":3,"file":"enum.d.ts","sourceRoot":"","sources":["../../src/schema/enum.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAEtD;;;;;;;;;;;;;;GAcG;AACH,qBAAa,UAAU,CACrB,KAAK,CAAC,MAAM,SAAS,IAAI,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CACrD,SAAQ,MAAM,CAAC,MAAM,CAAC;IACV,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE;gBAAzB,MAAM,EAAE,SAAS,MAAM,EAAE;IAI9C,iBAAiB,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,iBAAiB;CAOzD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,wBAAgB,UAAU,CAAC,KAAK,CAAC,CAAC,SAAS,IAAI,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,EACzE,KAAK,EAAE,SAAS,CAAC,EAAE,iBAGpB;AAGD,OAAO,EAAE,UAAU,IAAI,IAAI,EAAE,CAAA"}

package/dist/schema/enum.js

@@ -4,6 +4,21 @@ exports.EnumSchema = void 0;
 exports.enumSchema = enumSchema;
 exports.enum = enumSchema;
 const core_js_1 = require("../core.js");
+/**
+ * Schema that accepts one of several specific literal values.
+ *
+ * Validates that the input matches one of the allowed values using strict
+ * equality. Similar to TypeScript union of literals.
+ *
+ * @template TValue - The union of literal types
+ *
+ * @example
+ * ```ts
+ * const schema = new EnumSchema(['pending', 'active', 'completed'])
+ * schema.validate('active')  // success
+ * schema.validate('invalid') // fails
+ * ```
+ */
 class EnumSchema extends core_js_1.Schema {
     values;
     constructor(values) {
@@ -18,6 +33,39 @@ class EnumSchema extends core_js_1.Schema {
     }
 }
 exports.EnumSchema = EnumSchema;
+/**
+ * Creates an enum schema that accepts one of the specified values.
+ *
+ * Similar to TypeScript's union of string literals. Use `l.enum()` for
+ * the namespace-friendly alias.
+ *
+ * @param value - Array of allowed values
+ * @returns A new {@link EnumSchema} instance
+ *
+ * @example
+ * ```ts
+ * // String enum
+ * const statusSchema = l.enum(['pending', 'active', 'completed', 'failed'])
+ *
+ * // Number enum
+ * const prioritySchema = l.enum([1, 2, 3, 4, 5])
+ *
+ * // Mixed types
+ * const mixedSchema = l.enum(['auto', 0, 1, true])
+ *
+ * // Use in objects
+ * const taskSchema = l.object({
+ *   title: l.string(),
+ *   status: l.enum(['todo', 'in-progress', 'done']),
+ * })
+ *
+ * // In discriminated unions
+ * const resultSchema = l.discriminatedUnion('status', [
+ *   l.object({ status: l.enum(['pending', 'processing']), progress: l.integer() }),
+ *   l.object({ status: l.literal('completed'), result: l.unknown() }),
+ * ])
+ * ```
+ */
 /*@__NO_SIDE_EFFECTS__*/
 function enumSchema(value) {
     return new EnumSchema(value);

package/dist/schema/enum.js.map

@@ -1 +1 @@
-{"version":3,"file":"enum.js","sourceRoot":"","sources":["../../src/schema/enum.ts"],"names":[],"mappings":";;;AAmBA,gCAIC;AAGsB,0BAAI;AA1B3B,wCAAsD;AAEtD,MAAa,UAEX,SAAQ,gBAAc;IACD;IAArB,YAAqB,MAAyB;QAC5C,KAAK,EAAE,CAAA;QADY,WAAM,GAAN,MAAM,CAAmB;IAE9C,CAAC;IAED,iBAAiB,CAAC,KAAc,EAAE,GAAsB;QACtD,IAAI,CAAE,IAAI,CAAC,MAA6B,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;YACzD,OAAO,GAAG,CAAC,iBAAiB,CAAC,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,CAAA;QAClD,CAAC;QAED,OAAO,GAAG,CAAC,OAAO,CAAC,KAAe,CAAC,CAAA;IACrC,CAAC;CACF;AAdD,gCAcC;AAED,wBAAwB;AACxB,SAAgB,UAAU,CACxB,KAAmB;IAEnB,OAAO,IAAI,UAAU,CAAI,KAAK,CAAC,CAAA;AACjC,CAAC","sourcesContent":["import { Schema, ValidationContext } from '../core.js'\n\nexport class EnumSchema<\n  const TValue extends null | string | number | boolean,\n> extends Schema<TValue> {\n  constructor(readonly values: readonly TValue[]) {\n    super()\n  }\n\n  validateInContext(input: unknown, ctx: ValidationContext) {\n    if (!(this.values as readonly unknown[]).includes(input)) {\n      return ctx.issueInvalidValue(input, this.values)\n    }\n\n    return ctx.success(input as TValue)\n  }\n}\n\n/*@__NO_SIDE_EFFECTS__*/\nexport function enumSchema<const V extends null | string | number | boolean>(\n  value: readonly V[],\n) {\n  return new EnumSchema<V>(value)\n}\n\n// @NOTE \"enum\" is a reserved keyword in JS/TS\nexport { enumSchema as enum }\n"]}
+{"version":3,"file":"enum.js","sourceRoot":"","sources":["../../src/schema/enum.ts"],"names":[],"mappings":";;;AAmEA,gCAIC;AAGsB,0BAAI;AA1E3B,wCAAsD;AAEtD;;;;;;;;;;;;;;GAcG;AACH,MAAa,UAEX,SAAQ,gBAAc;IACD;IAArB,YAAqB,MAAyB;QAC5C,KAAK,EAAE,CAAA;QADY,WAAM,GAAN,MAAM,CAAmB;IAE9C,CAAC;IAED,iBAAiB,CAAC,KAAc,EAAE,GAAsB;QACtD,IAAI,CAAE,IAAI,CAAC,MAA6B,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;YACzD,OAAO,GAAG,CAAC,iBAAiB,CAAC,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,CAAA;QAClD,CAAC;QAED,OAAO,GAAG,CAAC,OAAO,CAAC,KAAe,CAAC,CAAA;IACrC,CAAC;CACF;AAdD,gCAcC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAwB;AACxB,SAAgB,UAAU,CACxB,KAAmB;IAEnB,OAAO,IAAI,UAAU,CAAI,KAAK,CAAC,CAAA;AACjC,CAAC","sourcesContent":["import { Schema, ValidationContext } from '../core.js'\n\n/**\n * Schema that accepts one of several specific literal values.\n *\n * Validates that the input matches one of the allowed values using strict\n * equality. Similar to TypeScript union of literals.\n *\n * @template TValue - The union of literal types\n *\n * @example\n * ```ts\n * const schema = new EnumSchema(['pending', 'active', 'completed'])\n * schema.validate('active')  // success\n * schema.validate('invalid') // fails\n * ```\n */\nexport class EnumSchema<\n  const TValue extends null | string | number | boolean,\n> extends Schema<TValue> {\n  constructor(readonly values: readonly TValue[]) {\n    super()\n  }\n\n  validateInContext(input: unknown, ctx: ValidationContext) {\n    if (!(this.values as readonly unknown[]).includes(input)) {\n      return ctx.issueInvalidValue(input, this.values)\n    }\n\n    return ctx.success(input as TValue)\n  }\n}\n\n/**\n * Creates an enum schema that accepts one of the specified values.\n *\n * Similar to TypeScript's union of string literals. Use `l.enum()` for\n * the namespace-friendly alias.\n *\n * @param value - Array of allowed values\n * @returns A new {@link EnumSchema} instance\n *\n * @example\n * ```ts\n * // String enum\n * const statusSchema = l.enum(['pending', 'active', 'completed', 'failed'])\n *\n * // Number enum\n * const prioritySchema = l.enum([1, 2, 3, 4, 5])\n *\n * // Mixed types\n * const mixedSchema = l.enum(['auto', 0, 1, true])\n *\n * // Use in objects\n * const taskSchema = l.object({\n *   title: l.string(),\n *   status: l.enum(['todo', 'in-progress', 'done']),\n * })\n *\n * // In discriminated unions\n * const resultSchema = l.discriminatedUnion('status', [\n *   l.object({ status: l.enum(['pending', 'processing']), progress: l.integer() }),\n *   l.object({ status: l.literal('completed'), result: l.unknown() }),\n * ])\n * ```\n */\n/*@__NO_SIDE_EFFECTS__*/\nexport function enumSchema<const V extends null | string | number | boolean>(\n  value: readonly V[],\n) {\n  return new EnumSchema<V>(value)\n}\n\n// @NOTE \"enum\" is a reserved keyword in JS/TS\nexport { enumSchema as enum }\n"]}

package/dist/schema/integer.d.ts

@@ -1,12 +1,54 @@
 import { Schema, ValidationContext } from '../core.js';
+/**
+ * Configuration options for integer schema validation.
+ *
+ * @property minimum - Minimum allowed value (inclusive)
+ * @property maximum - Maximum allowed value (inclusive)
+ */
 export type IntegerSchemaOptions = {
     minimum?: number;
     maximum?: number;
 };
+/**
+ * Schema for validating integer values with optional range constraints.
+ *
+ * Only accepts safe integers (values that can be exactly represented in JavaScript).
+ * Use {@link IntegerSchemaOptions} to constrain the allowed range.
+ *
+ * @example
+ * ```ts
+ * const schema = new IntegerSchema({ minimum: 0, maximum: 100 })
+ * const result = schema.validate(42)
+ * ```
+ */
 export declare class IntegerSchema extends Schema<number> {
     readonly options?: IntegerSchemaOptions | undefined;
     constructor(options?: IntegerSchemaOptions | undefined);
     validateInContext(input: unknown, ctx: ValidationContext): import("../core.js").ValidationResult<number>;
 }
+/**
+ * Creates an integer schema with optional minimum and maximum constraints.
+ *
+ * Validates that the input is a safe integer (can be exactly represented in JavaScript)
+ * and optionally falls within a specified range.
+ *
+ * @param options - Optional configuration for minimum and maximum values
+ * @returns A new {@link IntegerSchema} instance
+ *
+ * @example
+ * ```ts
+ * // Basic integer
+ * const countSchema = l.integer()
+ *
+ * // With minimum value
+ * const positiveSchema = l.integer({ minimum: 1 })
+ *
+ * // With range constraints
+ * const percentSchema = l.integer({ minimum: 0, maximum: 100 })
+ *
+ * // Age validation
+ * const ageSchema = l.integer({ minimum: 0, maximum: 150 })
+ * ```
+ */
 export declare const integer: (options?: IntegerSchemaOptions) => IntegerSchema;
 //# sourceMappingURL=integer.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"integer.d.ts","sourceRoot":"","sources":["../../src/schema/integer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAGtD,MAAM,MAAM,oBAAoB,GAAG;IACjC,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB,CAAA;AAED,qBAAa,aAAc,SAAQ,MAAM,CAAC,MAAM,CAAC;IACnC,QAAQ,CAAC,OAAO,CAAC,EAAE,oBAAoB;gBAA9B,OAAO,CAAC,EAAE,oBAAoB,YAAA;IAInD,iBAAiB,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,iBAAiB;CAezD;AASD,eAAO,MAAM,OAAO,aACR,oBAAoB,kBAG9B,CAAA"}
+{"version":3,"file":"integer.d.ts","sourceRoot":"","sources":["../../src/schema/integer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAGtD;;;;;GAKG;AACH,MAAM,MAAM,oBAAoB,GAAG;IACjC,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB,CAAA;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,aAAc,SAAQ,MAAM,CAAC,MAAM,CAAC;IACnC,QAAQ,CAAC,OAAO,CAAC,EAAE,oBAAoB;gBAA9B,OAAO,CAAC,EAAE,oBAAoB,YAAA;IAInD,iBAAiB,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,iBAAiB;CAezD;AASD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,OAAO,aACR,oBAAoB,kBAG9B,CAAA"}

package/dist/schema/integer.js

@@ -3,6 +3,18 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.integer = exports.IntegerSchema = void 0;
 const core_js_1 = require("../core.js");
 const memoize_js_1 = require("../util/memoize.js");
+/**
+ * Schema for validating integer values with optional range constraints.
+ *
+ * Only accepts safe integers (values that can be exactly represented in JavaScript).
+ * Use {@link IntegerSchemaOptions} to constrain the allowed range.
+ *
+ * @example
+ * ```ts
+ * const schema = new IntegerSchema({ minimum: 0, maximum: 100 })
+ * const result = schema.validate(42)
+ * ```
+ */
 class IntegerSchema extends core_js_1.Schema {
     options;
     constructor(options) {
@@ -29,6 +41,30 @@ exports.IntegerSchema = IntegerSchema;
 function isInteger(input) {
     return Number.isSafeInteger(input);
 }
+/**
+ * Creates an integer schema with optional minimum and maximum constraints.
+ *
+ * Validates that the input is a safe integer (can be exactly represented in JavaScript)
+ * and optionally falls within a specified range.
+ *
+ * @param options - Optional configuration for minimum and maximum values
+ * @returns A new {@link IntegerSchema} instance
+ *
+ * @example
+ * ```ts
+ * // Basic integer
+ * const countSchema = l.integer()
+ *
+ * // With minimum value
+ * const positiveSchema = l.integer({ minimum: 1 })
+ *
+ * // With range constraints
+ * const percentSchema = l.integer({ minimum: 0, maximum: 100 })
+ *
+ * // Age validation
+ * const ageSchema = l.integer({ minimum: 0, maximum: 150 })
+ * ```
+ */
 exports.integer = (0, memoize_js_1.memoizedOptions)(function (options) {
     return new IntegerSchema(options);
 });

package/dist/schema/integer.js.map

@@ -1 +1 @@
-{"version":3,"file":"integer.js","sourceRoot":"","sources":["../../src/schema/integer.ts"],"names":[],"mappings":";;;AAAA,wCAAsD;AACtD,mDAAoD;AAOpD,MAAa,aAAc,SAAQ,gBAAc;IAC1B;IAArB,YAAqB,OAA8B;QACjD,KAAK,EAAE,CAAA;QADY,YAAO,GAAP,OAAO,CAAuB;IAEnD,CAAC;IAED,iBAAiB,CAAC,KAAc,EAAE,GAAsB;QACtD,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC;YACtB,OAAO,GAAG,CAAC,gBAAgB,CAAC,KAAK,EAAE,SAAS,CAAC,CAAA;QAC/C,CAAC;QAED,IAAI,IAAI,CAAC,OAAO,EAAE,OAAO,IAAI,IAAI,IAAI,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;YAClE,OAAO,GAAG,CAAC,aAAa,CAAC,KAAK,EAAE,SAAS,EAAE,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,KAAK,CAAC,CAAA;QACzE,CAAC;QAED,IAAI,IAAI,CAAC,OAAO,EAAE,OAAO,IAAI,IAAI,IAAI,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;YAClE,OAAO,GAAG,CAAC,WAAW,CAAC,KAAK,EAAE,SAAS,EAAE,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,KAAK,CAAC,CAAA;QACvE,CAAC;QAED,OAAO,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,CAAA;IAC3B,CAAC;CACF;AApBD,sCAoBC;AAED;;GAEG;AACH,SAAS,SAAS,CAAC,KAAc;IAC/B,OAAO,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,CAAA;AACpC,CAAC;AAEY,QAAA,OAAO,GAAiB,IAAA,4BAAe,EAAC,UACnD,OAA8B;IAE9B,OAAO,IAAI,aAAa,CAAC,OAAO,CAAC,CAAA;AACnC,CAAC,CAAC,CAAA","sourcesContent":["import { Schema, ValidationContext } from '../core.js'\nimport { memoizedOptions } from '../util/memoize.js'\n\nexport type IntegerSchemaOptions = {\n  minimum?: number\n  maximum?: number\n}\n\nexport class IntegerSchema extends Schema<number> {\n  constructor(readonly options?: IntegerSchemaOptions) {\n    super()\n  }\n\n  validateInContext(input: unknown, ctx: ValidationContext) {\n    if (!isInteger(input)) {\n      return ctx.issueInvalidType(input, 'integer')\n    }\n\n    if (this.options?.minimum != null && input < this.options.minimum) {\n      return ctx.issueTooSmall(input, 'integer', this.options.minimum, input)\n    }\n\n    if (this.options?.maximum != null && input > this.options.maximum) {\n      return ctx.issueTooBig(input, 'integer', this.options.maximum, input)\n    }\n\n    return ctx.success(input)\n  }\n}\n\n/**\n * Simple wrapper around {@link Number.isSafeInteger} that acts as a type guard.\n */\nfunction isInteger(input: unknown): input is number {\n  return Number.isSafeInteger(input)\n}\n\nexport const integer = /*#__PURE__*/ memoizedOptions(function (\n  options?: IntegerSchemaOptions,\n) {\n  return new IntegerSchema(options)\n})\n"]}
+{"version":3,"file":"integer.js","sourceRoot":"","sources":["../../src/schema/integer.ts"],"names":[],"mappings":";;;AAAA,wCAAsD;AACtD,mDAAoD;AAapD;;;;;;;;;;;GAWG;AACH,MAAa,aAAc,SAAQ,gBAAc;IAC1B;IAArB,YAAqB,OAA8B;QACjD,KAAK,EAAE,CAAA;QADY,YAAO,GAAP,OAAO,CAAuB;IAEnD,CAAC;IAED,iBAAiB,CAAC,KAAc,EAAE,GAAsB;QACtD,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC;YACtB,OAAO,GAAG,CAAC,gBAAgB,CAAC,KAAK,EAAE,SAAS,CAAC,CAAA;QAC/C,CAAC;QAED,IAAI,IAAI,CAAC,OAAO,EAAE,OAAO,IAAI,IAAI,IAAI,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;YAClE,OAAO,GAAG,CAAC,aAAa,CAAC,KAAK,EAAE,SAAS,EAAE,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,KAAK,CAAC,CAAA;QACzE,CAAC;QAED,IAAI,IAAI,CAAC,OAAO,EAAE,OAAO,IAAI,IAAI,IAAI,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;YAClE,OAAO,GAAG,CAAC,WAAW,CAAC,KAAK,EAAE,SAAS,EAAE,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,KAAK,CAAC,CAAA;QACvE,CAAC;QAED,OAAO,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,CAAA;IAC3B,CAAC;CACF;AApBD,sCAoBC;AAED;;GAEG;AACH,SAAS,SAAS,CAAC,KAAc;IAC/B,OAAO,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,CAAA;AACpC,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACU,QAAA,OAAO,GAAiB,IAAA,4BAAe,EAAC,UACnD,OAA8B;IAE9B,OAAO,IAAI,aAAa,CAAC,OAAO,CAAC,CAAA;AACnC,CAAC,CAAC,CAAA","sourcesContent":["import { Schema, ValidationContext } from '../core.js'\nimport { memoizedOptions } from '../util/memoize.js'\n\n/**\n * Configuration options for integer schema validation.\n *\n * @property minimum - Minimum allowed value (inclusive)\n * @property maximum - Maximum allowed value (inclusive)\n */\nexport type IntegerSchemaOptions = {\n  minimum?: number\n  maximum?: number\n}\n\n/**\n * Schema for validating integer values with optional range constraints.\n *\n * Only accepts safe integers (values that can be exactly represented in JavaScript).\n * Use {@link IntegerSchemaOptions} to constrain the allowed range.\n *\n * @example\n * ```ts\n * const schema = new IntegerSchema({ minimum: 0, maximum: 100 })\n * const result = schema.validate(42)\n * ```\n */\nexport class IntegerSchema extends Schema<number> {\n  constructor(readonly options?: IntegerSchemaOptions) {\n    super()\n  }\n\n  validateInContext(input: unknown, ctx: ValidationContext) {\n    if (!isInteger(input)) {\n      return ctx.issueInvalidType(input, 'integer')\n    }\n\n    if (this.options?.minimum != null && input < this.options.minimum) {\n      return ctx.issueTooSmall(input, 'integer', this.options.minimum, input)\n    }\n\n    if (this.options?.maximum != null && input > this.options.maximum) {\n      return ctx.issueTooBig(input, 'integer', this.options.maximum, input)\n    }\n\n    return ctx.success(input)\n  }\n}\n\n/**\n * Simple wrapper around {@link Number.isSafeInteger} that acts as a type guard.\n */\nfunction isInteger(input: unknown): input is number {\n  return Number.isSafeInteger(input)\n}\n\n/**\n * Creates an integer schema with optional minimum and maximum constraints.\n *\n * Validates that the input is a safe integer (can be exactly represented in JavaScript)\n * and optionally falls within a specified range.\n *\n * @param options - Optional configuration for minimum and maximum values\n * @returns A new {@link IntegerSchema} instance\n *\n * @example\n * ```ts\n * // Basic integer\n * const countSchema = l.integer()\n *\n * // With minimum value\n * const positiveSchema = l.integer({ minimum: 1 })\n *\n * // With range constraints\n * const percentSchema = l.integer({ minimum: 0, maximum: 100 })\n *\n * // Age validation\n * const ageSchema = l.integer({ minimum: 0, maximum: 150 })\n * ```\n */\nexport const integer = /*#__PURE__*/ memoizedOptions(function (\n  options?: IntegerSchemaOptions,\n) {\n  return new IntegerSchema(options)\n})\n"]}

package/dist/schema/intersection.d.ts

@@ -2,10 +2,15 @@ import { InferInput, InferOutput, Schema, Simplify, ValidationContext } from '..
 import { DictSchema } from './dict.js';
 import { ObjectSchema } from './object.js';
 /**
+ * Type utility for computing the intersection of two object types.
+ *
  * Allows to more accurately represent the intersection of two object types
  * where both types may share some keys, and one of them uses an index
  * signature.
  *
+ * @template A - First object type (typically from ObjectSchema)
+ * @template B - Second object type (typically from DictSchema)
+ *
  * @see {@link https://www.typescriptlang.org/play/?#code/C4TwDgpgBAglC8UDeUBmB7dAuKByARgIYBOuUAvlAGTJQDaA+lAJYB2UAzsMWwOYC6OVgFcAtvgjEKAKGkATCAGMANiWiL0rLlEI4YsjVuBQA1hBA4uPVrwRQARBnT2Dm7QDdCy4dESE6ZiD8UAD0IVAi4pJQABQcABbowspyUBIORMT2AJSyEAAeYOjExqCQUACSrMCSHErAzJoAPNJQsFAFNaxyHFAASkrFck1WfAA0UMKsJqzoAO6sAHxjrVAAQh35XT39g8TDozYTUzPzSyuLdqtwVKttMYHoqO00j88bnRDdvawQ7pJ3NpQAD860BbRwSHBQLadAA0ix2G91oJ1vDggAfWABcxPF5QOH8aFtci5aRlaAwVDMfIQVKIKo1Yh1RQNZq0Jw4AgkMjkCYoRiIzjcPioyISKTkRayBQqNRQQzaQgAMRpdL01NpclcRignm8EFVWrsKrVchxQVC4XF0SxmSAA Playground link}
  */
 export type Intersect<A, B> = B[keyof B] extends never ? A : keyof A & keyof B extends never ? // If A and B don't overlap, just return A & B
@@ -13,11 +18,60 @@ A & B : // Otherwise, properly represent the fact that accessing using an
 A & {
     [K in keyof B]: B[K] | A[keyof A & K];
 };
+/**
+ * Schema for combining an object schema with a dictionary schema.
+ *
+ * Validates that the input matches both the fixed object shape and allows
+ * additional properties that match the dictionary schema. Properties defined
+ * in the object schema are validated by the object, and remaining properties
+ * are validated by the dictionary.
+ *
+ * @template Left - The ObjectSchema type for fixed properties
+ * @template Right - The DictSchema type for additional properties
+ *
+ * @example
+ * ```ts
+ * const schema = new IntersectionSchema(
+ *   l.object({ name: l.string() }),
+ *   l.dict(l.string(), l.integer())
+ * )
+ * // Validates: { name: 'test', score: 100, count: 5 }
+ * ```
+ */
 export declare class IntersectionSchema<const Left extends ObjectSchema = any, const Right extends DictSchema = any> extends Schema<Simplify<Intersect<InferInput<Left>, InferInput<Right>>>, Simplify<Intersect<InferOutput<Left>, InferOutput<Right>>>> {
     protected readonly left: Left;
     protected readonly right: Right;
     constructor(left: Left, right: Right);
     validateInContext(input: unknown, ctx: ValidationContext): import("../core.js").ValidationResult<Record<string, unknown>>;
 }
+/**
+ * Creates an intersection schema combining fixed object properties with dynamic dictionary properties.
+ *
+ * Useful for objects that have a known set of properties plus additional
+ * arbitrary properties that follow a pattern.
+ *
+ * @param left - Object schema defining the fixed, known properties
+ * @param right - Dictionary schema for validating additional properties
+ * @returns A new {@link IntersectionSchema} instance
+ *
+ * @example
+ * ```ts
+ * // Object with fixed and dynamic properties
+ * const configSchema = l.intersection(
+ *   l.object({
+ *     version: l.integer(),
+ *     name: l.string(),
+ *   }),
+ *   l.dict(l.string(), l.string()) // Additional string properties
+ * )
+ *
+ * configSchema.parse({
+ *   version: 1,
+ *   name: 'my-config',
+ *   customField: 'value',
+ *   anotherField: 'another',
+ * })
+ * ```
+ */
 export declare function intersection<const Left extends ObjectSchema, const Right extends DictSchema>(left: Left, right: Right): IntersectionSchema<Left, Right>;
 //# sourceMappingURL=intersection.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"intersection.d.ts","sourceRoot":"","sources":["../../src/schema/intersection.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,UAAU,EACV,WAAW,EACX,MAAM,EACN,QAAQ,EACR,iBAAiB,EAClB,MAAM,YAAY,CAAA;AACnB,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA;AACtC,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAE1C;;;;;;GAMG;AACH,MAAM,MAAM,SAAS,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,SAAS,KAAK,GAClD,CAAC,GACD,MAAM,CAAC,GAAG,MAAM,CAAC,SAAS,KAAK,GAE7B,AADA,8CAA8C;AAC9C,CAAC,GAAG,CAAC,GAGL,AAFA,iEAAiE;AAEjE,CAAC,GAAG;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;CAAE,CAAA;AAEnD,qBAAa,kBAAkB,CAC7B,KAAK,CAAC,IAAI,SAAS,YAAY,GAAG,GAAG,EACrC,KAAK,CAAC,KAAK,SAAS,UAAU,GAAG,GAAG,CACpC,SAAQ,MAAM,CACd,QAAQ,CAAC,SAAS,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,EACxD,QAAQ,CAAC,SAAS,CAAC,WAAW,CAAC,IAAI,CAAC,EAAE,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC,CAC3D;IAEG,SAAS,CAAC,QAAQ,CAAC,IAAI,EAAE,IAAI;IAC7B,SAAS,CAAC,QAAQ,CAAC,KAAK,EAAE,KAAK;gBADZ,IAAI,EAAE,IAAI,EACV,KAAK,EAAE,KAAK;IAKjC,iBAAiB,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,iBAAiB;CAQzD;AAGD,wBAAgB,YAAY,CAC1B,KAAK,CAAC,IAAI,SAAS,YAAY,EAC/B,KAAK,CAAC,KAAK,SAAS,UAAU,EAC9B,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,mCAEzB"}
+{"version":3,"file":"intersection.d.ts","sourceRoot":"","sources":["../../src/schema/intersection.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,UAAU,EACV,WAAW,EACX,MAAM,EACN,QAAQ,EACR,iBAAiB,EAClB,MAAM,YAAY,CAAA;AACnB,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA;AACtC,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAE1C;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,SAAS,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,SAAS,KAAK,GAClD,CAAC,GACD,MAAM,CAAC,GAAG,MAAM,CAAC,SAAS,KAAK,GAE7B,AADA,8CAA8C;AAC9C,CAAC,GAAG,CAAC,GAGL,AAFA,iEAAiE;AAEjE,CAAC,GAAG;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;CAAE,CAAA;AAEnD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,kBAAkB,CAC7B,KAAK,CAAC,IAAI,SAAS,YAAY,GAAG,GAAG,EACrC,KAAK,CAAC,KAAK,SAAS,UAAU,GAAG,GAAG,CACpC,SAAQ,MAAM,CACd,QAAQ,CAAC,SAAS,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,EACxD,QAAQ,CAAC,SAAS,CAAC,WAAW,CAAC,IAAI,CAAC,EAAE,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC,CAC3D;IAEG,SAAS,CAAC,QAAQ,CAAC,IAAI,EAAE,IAAI;IAC7B,SAAS,CAAC,QAAQ,CAAC,KAAK,EAAE,KAAK;gBADZ,IAAI,EAAE,IAAI,EACV,KAAK,EAAE,KAAK;IAKjC,iBAAiB,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,iBAAiB;CAQzD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,wBAAgB,YAAY,CAC1B,KAAK,CAAC,IAAI,SAAS,YAAY,EAC/B,KAAK,CAAC,KAAK,SAAS,UAAU,EAC9B,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,mCAEzB"}