@atproto/lex-schema 0.0.10 → 0.0.12

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

@@ -1,8 +1,42 @@
 import { LexMap } from '@atproto/lex-data';
 import { Schema, ValidationContext } from '../core.js';
+/**
+ * Type alias for a plain object with unknown values.
+ */
 export type UnknownObject = LexMap;
+/**
+ * Schema that accepts any plain object without validating its properties.
+ *
+ * Validates that the input is a plain object (not an array, Date, or other
+ * special object type), but does not validate the object's properties.
+ *
+ * @example
+ * ```ts
+ * const schema = new UnknownObjectSchema()
+ * schema.validate({ any: 'props' }) // success
+ * schema.validate([1, 2, 3])        // fails - arrays not accepted
+ * ```
+ */
 export declare class UnknownObjectSchema extends Schema<UnknownObject> {
     validateInContext(input: unknown, ctx: ValidationContext): import("../core.js").ValidationResult<LexMap>;
 }
+/**
+ * Creates a schema that accepts any plain object.
+ *
+ * Unlike `l.unknown()` which accepts any value, this validates that the input
+ * is specifically a plain object (not an array, null, or primitive).
+ *
+ * @returns A new {@link UnknownObjectSchema} instance
+ *
+ * @example
+ * ```ts
+ * // Accept any object shape
+ * const metadataSchema = l.unknownObject()
+ *
+ * metadataSchema.parse({ foo: 1, bar: 'baz' }) // success
+ * metadataSchema.parse([1, 2, 3])              // throws - not a plain object
+ * metadataSchema.parse(null)                   // throws
+ * ```
+ */
 export declare const unknownObject: () => UnknownObjectSchema;
 //# sourceMappingURL=unknown-object.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"unknown-object.d.ts","sourceRoot":"","sources":["../../src/schema/unknown-object.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAY,MAAM,mBAAmB,CAAA;AACpD,OAAO,EAAE,MAAM,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAGtD,MAAM,MAAM,aAAa,GAAG,MAAM,CAAA;AAElC,qBAAa,mBAAoB,SAAQ,MAAM,CAAC,aAAa,CAAC;IAC5D,iBAAiB,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,iBAAiB;CAOzD;AAED,eAAO,MAAM,aAAa,2BAExB,CAAA"}
+{"version":3,"file":"unknown-object.d.ts","sourceRoot":"","sources":["../../src/schema/unknown-object.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAY,MAAM,mBAAmB,CAAA;AACpD,OAAO,EAAE,MAAM,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAGtD;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,CAAA;AAElC;;;;;;;;;;;;GAYG;AACH,qBAAa,mBAAoB,SAAQ,MAAM,CAAC,aAAa,CAAC;IAC5D,iBAAiB,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,iBAAiB;CAOzD;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,aAAa,2BAExB,CAAA"}

package/dist/schema/unknown-object.js

@@ -4,6 +4,19 @@ exports.unknownObject = exports.UnknownObjectSchema = void 0;
 const lex_data_1 = require("@atproto/lex-data");
 const core_js_1 = require("../core.js");
 const memoize_js_1 = require("../util/memoize.js");
+/**
+ * Schema that accepts any plain object without validating its properties.
+ *
+ * Validates that the input is a plain object (not an array, Date, or other
+ * special object type), but does not validate the object's properties.
+ *
+ * @example
+ * ```ts
+ * const schema = new UnknownObjectSchema()
+ * schema.validate({ any: 'props' }) // success
+ * schema.validate([1, 2, 3])        // fails - arrays not accepted
+ * ```
+ */
 class UnknownObjectSchema extends core_js_1.Schema {
     validateInContext(input, ctx) {
         if ((0, lex_data_1.isLexMap)(input)) {
@@ -13,6 +26,24 @@ class UnknownObjectSchema extends core_js_1.Schema {
     }
 }
 exports.UnknownObjectSchema = UnknownObjectSchema;
+/**
+ * Creates a schema that accepts any plain object.
+ *
+ * Unlike `l.unknown()` which accepts any value, this validates that the input
+ * is specifically a plain object (not an array, null, or primitive).
+ *
+ * @returns A new {@link UnknownObjectSchema} instance
+ *
+ * @example
+ * ```ts
+ * // Accept any object shape
+ * const metadataSchema = l.unknownObject()
+ *
+ * metadataSchema.parse({ foo: 1, bar: 'baz' }) // success
+ * metadataSchema.parse([1, 2, 3])              // throws - not a plain object
+ * metadataSchema.parse(null)                   // throws
+ * ```
+ */
 exports.unknownObject = (0, memoize_js_1.memoizedOptions)(function () {
     return new UnknownObjectSchema();
 });

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

@@ -1 +1 @@
-{"version":3,"file":"unknown-object.js","sourceRoot":"","sources":["../../src/schema/unknown-object.ts"],"names":[],"mappings":";;;AAAA,gDAAoD;AACpD,wCAAsD;AACtD,mDAAoD;AAIpD,MAAa,mBAAoB,SAAQ,gBAAqB;IAC5D,iBAAiB,CAAC,KAAc,EAAE,GAAsB;QACtD,IAAI,IAAA,mBAAQ,EAAC,KAAK,CAAC,EAAE,CAAC;YACpB,OAAO,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,CAAA;QAC3B,CAAC;QAED,OAAO,GAAG,CAAC,gBAAgB,CAAC,KAAK,EAAE,SAAS,CAAC,CAAA;IAC/C,CAAC;CACF;AARD,kDAQC;AAEY,QAAA,aAAa,GAAiB,IAAA,4BAAe,EAAC;IACzD,OAAO,IAAI,mBAAmB,EAAE,CAAA;AAClC,CAAC,CAAC,CAAA","sourcesContent":["import { LexMap, isLexMap } from '@atproto/lex-data'\nimport { Schema, ValidationContext } from '../core.js'\nimport { memoizedOptions } from '../util/memoize.js'\n\nexport type UnknownObject = LexMap\n\nexport class UnknownObjectSchema extends Schema<UnknownObject> {\n  validateInContext(input: unknown, ctx: ValidationContext) {\n    if (isLexMap(input)) {\n      return ctx.success(input)\n    }\n\n    return ctx.issueInvalidType(input, 'unknown')\n  }\n}\n\nexport const unknownObject = /*#__PURE__*/ memoizedOptions(function () {\n  return new UnknownObjectSchema()\n})\n"]}
+{"version":3,"file":"unknown-object.js","sourceRoot":"","sources":["../../src/schema/unknown-object.ts"],"names":[],"mappings":";;;AAAA,gDAAoD;AACpD,wCAAsD;AACtD,mDAAoD;AAOpD;;;;;;;;;;;;GAYG;AACH,MAAa,mBAAoB,SAAQ,gBAAqB;IAC5D,iBAAiB,CAAC,KAAc,EAAE,GAAsB;QACtD,IAAI,IAAA,mBAAQ,EAAC,KAAK,CAAC,EAAE,CAAC;YACpB,OAAO,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,CAAA;QAC3B,CAAC;QAED,OAAO,GAAG,CAAC,gBAAgB,CAAC,KAAK,EAAE,SAAS,CAAC,CAAA;IAC/C,CAAC;CACF;AARD,kDAQC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACU,QAAA,aAAa,GAAiB,IAAA,4BAAe,EAAC;IACzD,OAAO,IAAI,mBAAmB,EAAE,CAAA;AAClC,CAAC,CAAC,CAAA","sourcesContent":["import { LexMap, isLexMap } from '@atproto/lex-data'\nimport { Schema, ValidationContext } from '../core.js'\nimport { memoizedOptions } from '../util/memoize.js'\n\n/**\n * Type alias for a plain object with unknown values.\n */\nexport type UnknownObject = LexMap\n\n/**\n * Schema that accepts any plain object without validating its properties.\n *\n * Validates that the input is a plain object (not an array, Date, or other\n * special object type), but does not validate the object's properties.\n *\n * @example\n * ```ts\n * const schema = new UnknownObjectSchema()\n * schema.validate({ any: 'props' }) // success\n * schema.validate([1, 2, 3])        // fails - arrays not accepted\n * ```\n */\nexport class UnknownObjectSchema extends Schema<UnknownObject> {\n  validateInContext(input: unknown, ctx: ValidationContext) {\n    if (isLexMap(input)) {\n      return ctx.success(input)\n    }\n\n    return ctx.issueInvalidType(input, 'unknown')\n  }\n}\n\n/**\n * Creates a schema that accepts any plain object.\n *\n * Unlike `l.unknown()` which accepts any value, this validates that the input\n * is specifically a plain object (not an array, null, or primitive).\n *\n * @returns A new {@link UnknownObjectSchema} instance\n *\n * @example\n * ```ts\n * // Accept any object shape\n * const metadataSchema = l.unknownObject()\n *\n * metadataSchema.parse({ foo: 1, bar: 'baz' }) // success\n * metadataSchema.parse([1, 2, 3])              // throws - not a plain object\n * metadataSchema.parse(null)                   // throws\n * ```\n */\nexport const unknownObject = /*#__PURE__*/ memoizedOptions(function () {\n  return new UnknownObjectSchema()\n})\n"]}

package/dist/schema/unknown.d.ts

@@ -1,6 +1,39 @@
 import { Schema, ValidationContext } from '../core.js';
+/**
+ * Schema that accepts any value without validation.
+ *
+ * Passes through any input unchanged. Use sparingly as it bypasses
+ * type safety. Useful for dynamic data or when the schema is not
+ * known at compile time.
+ *
+ * @example
+ * ```ts
+ * const schema = new UnknownSchema()
+ * schema.validate(anything) // always succeeds
+ * ```
+ */
 export declare class UnknownSchema extends Schema<unknown> {
     validateInContext(input: unknown, ctx: ValidationContext): import("../core.js").ValidationResult<unknown>;
 }
+/**
+ * Creates an unknown schema that accepts any value.
+ *
+ * The value passes through without any validation or transformation.
+ * Use this when you need to accept arbitrary data.
+ *
+ * @returns A new {@link UnknownSchema} instance
+ *
+ * @example
+ * ```ts
+ * // Accept any value
+ * const anyDataSchema = l.unknown()
+ *
+ * // In an object with a dynamic field
+ * const flexibleSchema = l.object({
+ *   type: l.string(),
+ *   data: l.unknown(),
+ * })
+ * ```
+ */
 export declare const unknown: () => UnknownSchema;
 //# sourceMappingURL=unknown.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"unknown.d.ts","sourceRoot":"","sources":["../../src/schema/unknown.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAGtD,qBAAa,aAAc,SAAQ,MAAM,CAAC,OAAO,CAAC;IAChD,iBAAiB,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,iBAAiB;CAGzD;AAED,eAAO,MAAM,OAAO,qBAElB,CAAA"}
+{"version":3,"file":"unknown.d.ts","sourceRoot":"","sources":["../../src/schema/unknown.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAGtD;;;;;;;;;;;;GAYG;AACH,qBAAa,aAAc,SAAQ,MAAM,CAAC,OAAO,CAAC;IAChD,iBAAiB,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,iBAAiB;CAGzD;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,OAAO,qBAElB,CAAA"}

package/dist/schema/unknown.js

@@ -3,12 +3,45 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.unknown = exports.UnknownSchema = void 0;
 const core_js_1 = require("../core.js");
 const memoize_js_1 = require("../util/memoize.js");
+/**
+ * Schema that accepts any value without validation.
+ *
+ * Passes through any input unchanged. Use sparingly as it bypasses
+ * type safety. Useful for dynamic data or when the schema is not
+ * known at compile time.
+ *
+ * @example
+ * ```ts
+ * const schema = new UnknownSchema()
+ * schema.validate(anything) // always succeeds
+ * ```
+ */
 class UnknownSchema extends core_js_1.Schema {
     validateInContext(input, ctx) {
         return ctx.success(input);
     }
 }
 exports.UnknownSchema = UnknownSchema;
+/**
+ * Creates an unknown schema that accepts any value.
+ *
+ * The value passes through without any validation or transformation.
+ * Use this when you need to accept arbitrary data.
+ *
+ * @returns A new {@link UnknownSchema} instance
+ *
+ * @example
+ * ```ts
+ * // Accept any value
+ * const anyDataSchema = l.unknown()
+ *
+ * // In an object with a dynamic field
+ * const flexibleSchema = l.object({
+ *   type: l.string(),
+ *   data: l.unknown(),
+ * })
+ * ```
+ */
 exports.unknown = (0, memoize_js_1.memoizedOptions)(function () {
     return new UnknownSchema();
 });

package/dist/schema/unknown.js.map

@@ -1 +1 @@
-{"version":3,"file":"unknown.js","sourceRoot":"","sources":["../../src/schema/unknown.ts"],"names":[],"mappings":";;;AAAA,wCAAsD;AACtD,mDAAoD;AAEpD,MAAa,aAAc,SAAQ,gBAAe;IAChD,iBAAiB,CAAC,KAAc,EAAE,GAAsB;QACtD,OAAO,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,CAAA;IAC3B,CAAC;CACF;AAJD,sCAIC;AAEY,QAAA,OAAO,GAAiB,IAAA,4BAAe,EAAC;IACnD,OAAO,IAAI,aAAa,EAAE,CAAA;AAC5B,CAAC,CAAC,CAAA","sourcesContent":["import { Schema, ValidationContext } from '../core.js'\nimport { memoizedOptions } from '../util/memoize.js'\n\nexport class UnknownSchema extends Schema<unknown> {\n  validateInContext(input: unknown, ctx: ValidationContext) {\n    return ctx.success(input)\n  }\n}\n\nexport const unknown = /*#__PURE__*/ memoizedOptions(function () {\n  return new UnknownSchema()\n})\n"]}
+{"version":3,"file":"unknown.js","sourceRoot":"","sources":["../../src/schema/unknown.ts"],"names":[],"mappings":";;;AAAA,wCAAsD;AACtD,mDAAoD;AAEpD;;;;;;;;;;;;GAYG;AACH,MAAa,aAAc,SAAQ,gBAAe;IAChD,iBAAiB,CAAC,KAAc,EAAE,GAAsB;QACtD,OAAO,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,CAAA;IAC3B,CAAC;CACF;AAJD,sCAIC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACU,QAAA,OAAO,GAAiB,IAAA,4BAAe,EAAC;IACnD,OAAO,IAAI,aAAa,EAAE,CAAA;AAC5B,CAAC,CAAC,CAAA","sourcesContent":["import { Schema, ValidationContext } from '../core.js'\nimport { memoizedOptions } from '../util/memoize.js'\n\n/**\n * Schema that accepts any value without validation.\n *\n * Passes through any input unchanged. Use sparingly as it bypasses\n * type safety. Useful for dynamic data or when the schema is not\n * known at compile time.\n *\n * @example\n * ```ts\n * const schema = new UnknownSchema()\n * schema.validate(anything) // always succeeds\n * ```\n */\nexport class UnknownSchema extends Schema<unknown> {\n  validateInContext(input: unknown, ctx: ValidationContext) {\n    return ctx.success(input)\n  }\n}\n\n/**\n * Creates an unknown schema that accepts any value.\n *\n * The value passes through without any validation or transformation.\n * Use this when you need to accept arbitrary data.\n *\n * @returns A new {@link UnknownSchema} instance\n *\n * @example\n * ```ts\n * // Accept any value\n * const anyDataSchema = l.unknown()\n *\n * // In an object with a dynamic field\n * const flexibleSchema = l.object({\n *   type: l.string(),\n *   data: l.unknown(),\n * })\n * ```\n */\nexport const unknown = /*#__PURE__*/ memoizedOptions(function () {\n  return new UnknownSchema()\n})\n"]}

package/dist/schema/with-default.d.ts

@@ -1,9 +1,53 @@
 import { InferInput, InferOutput, Schema, ValidationContext, Validator } from '../core.js';
+/**
+ * Schema wrapper that provides a default value when the input is undefined.
+ *
+ * In parse mode, when the input is `undefined`, the default value is used
+ * instead. In validate mode, undefined values pass through unchanged (the
+ * default is not applied).
+ *
+ * @template TValidator - The wrapped validator type
+ *
+ * @example
+ * ```ts
+ * const schema = new WithDefaultSchema(l.integer(), 0)
+ * schema.parse(undefined) // 0
+ * schema.parse(42)        // 42
+ * ```
+ */
 export declare class WithDefaultSchema<const TValidator extends Validator> extends Schema<InferInput<TValidator>, InferOutput<TValidator>> {
     readonly validator: TValidator;
     readonly defaultValue: InferInput<TValidator>;
     constructor(validator: TValidator, defaultValue: InferInput<TValidator>);
     validateInContext(input: unknown, ctx: ValidationContext): import("../core.js").ValidationResult<InferInput<TValidator>>;
 }
+/**
+ * Creates a schema that applies a default value when the input is undefined.
+ *
+ * Commonly used with `optional()` to provide fallback values for missing
+ * properties. The default value is validated against the schema.
+ *
+ * @param validator - The validator for the value
+ * @param defaultValue - The default value to use when input is undefined
+ * @returns A new {@link WithDefaultSchema} instance
+ *
+ * @example
+ * ```ts
+ * // Integer with default
+ * const countSchema = l.withDefault(l.integer(), 0)
+ * countSchema.parse(undefined) // 0
+ * countSchema.parse(5)         // 5
+ *
+ * // Commonly combined with optional in objects
+ * const settingsSchema = l.object({
+ *   theme: l.optional(l.withDefault(l.string(), 'light')),
+ *   pageSize: l.optional(l.withDefault(l.integer(), 25)),
+ * })
+ * settingsSchema.parse({}) // { theme: 'light', pageSize: 25 }
+ *
+ * // Boolean with default
+ * const enabledSchema = l.withDefault(l.boolean(), false)
+ * ```
+ */
 export declare function withDefault<const TValidator extends Validator>(validator: TValidator, defaultValue: InferInput<TValidator>): WithDefaultSchema<TValidator>;
 //# sourceMappingURL=with-default.d.ts.map

package/dist/schema/with-default.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"with-default.d.ts","sourceRoot":"","sources":["../../src/schema/with-default.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,UAAU,EACV,WAAW,EACX,MAAM,EACN,iBAAiB,EACjB,SAAS,EACV,MAAM,YAAY,CAAA;AAEnB,qBAAa,iBAAiB,CAC5B,KAAK,CAAC,UAAU,SAAS,SAAS,CAClC,SAAQ,MAAM,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,WAAW,CAAC,UAAU,CAAC,CAAC;IAE7D,QAAQ,CAAC,SAAS,EAAE,UAAU;IAC9B,QAAQ,CAAC,YAAY,EAAE,UAAU,CAAC,UAAU,CAAC;gBADpC,SAAS,EAAE,UAAU,EACrB,YAAY,EAAE,UAAU,CAAC,UAAU,CAAC;IAK/C,iBAAiB,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,iBAAiB;CASzD;AAED,wBAAgB,WAAW,CAAC,KAAK,CAAC,UAAU,SAAS,SAAS,EAC5D,SAAS,EAAE,UAAU,EACrB,YAAY,EAAE,UAAU,CAAC,UAAU,CAAC,iCAGrC"}
+{"version":3,"file":"with-default.d.ts","sourceRoot":"","sources":["../../src/schema/with-default.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,UAAU,EACV,WAAW,EACX,MAAM,EACN,iBAAiB,EACjB,SAAS,EACV,MAAM,YAAY,CAAA;AAEnB;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,iBAAiB,CAC5B,KAAK,CAAC,UAAU,SAAS,SAAS,CAClC,SAAQ,MAAM,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,WAAW,CAAC,UAAU,CAAC,CAAC;IAE7D,QAAQ,CAAC,SAAS,EAAE,UAAU;IAC9B,QAAQ,CAAC,YAAY,EAAE,UAAU,CAAC,UAAU,CAAC;gBADpC,SAAS,EAAE,UAAU,EACrB,YAAY,EAAE,UAAU,CAAC,UAAU,CAAC;IAK/C,iBAAiB,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,iBAAiB;CASzD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,WAAW,CAAC,KAAK,CAAC,UAAU,SAAS,SAAS,EAC5D,SAAS,EAAE,UAAU,EACrB,YAAY,EAAE,UAAU,CAAC,UAAU,CAAC,iCAGrC"}

package/dist/schema/with-default.js

@@ -3,6 +3,22 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.WithDefaultSchema = void 0;
 exports.withDefault = withDefault;
 const core_js_1 = require("../core.js");
+/**
+ * Schema wrapper that provides a default value when the input is undefined.
+ *
+ * In parse mode, when the input is `undefined`, the default value is used
+ * instead. In validate mode, undefined values pass through unchanged (the
+ * default is not applied).
+ *
+ * @template TValidator - The wrapped validator type
+ *
+ * @example
+ * ```ts
+ * const schema = new WithDefaultSchema(l.integer(), 0)
+ * schema.parse(undefined) // 0
+ * schema.parse(42)        // 42
+ * ```
+ */
 class WithDefaultSchema extends core_js_1.Schema {
     validator;
     defaultValue;
@@ -21,6 +37,34 @@ class WithDefaultSchema extends core_js_1.Schema {
     }
 }
 exports.WithDefaultSchema = WithDefaultSchema;
+/**
+ * Creates a schema that applies a default value when the input is undefined.
+ *
+ * Commonly used with `optional()` to provide fallback values for missing
+ * properties. The default value is validated against the schema.
+ *
+ * @param validator - The validator for the value
+ * @param defaultValue - The default value to use when input is undefined
+ * @returns A new {@link WithDefaultSchema} instance
+ *
+ * @example
+ * ```ts
+ * // Integer with default
+ * const countSchema = l.withDefault(l.integer(), 0)
+ * countSchema.parse(undefined) // 0
+ * countSchema.parse(5)         // 5
+ *
+ * // Commonly combined with optional in objects
+ * const settingsSchema = l.object({
+ *   theme: l.optional(l.withDefault(l.string(), 'light')),
+ *   pageSize: l.optional(l.withDefault(l.integer(), 25)),
+ * })
+ * settingsSchema.parse({}) // { theme: 'light', pageSize: 25 }
+ *
+ * // Boolean with default
+ * const enabledSchema = l.withDefault(l.boolean(), false)
+ * ```
+ */
 function withDefault(validator, defaultValue) {
     return new WithDefaultSchema(validator, defaultValue);
 }

package/dist/schema/with-default.js.map

@@ -1 +1 @@
-{"version":3,"file":"with-default.js","sourceRoot":"","sources":["../../src/schema/with-default.ts"],"names":[],"mappings":";;;AA6BA,kCAKC;AAlCD,wCAMmB;AAEnB,MAAa,iBAEX,SAAQ,gBAAuD;IAEpD;IACA;IAFX,YACW,SAAqB,EACrB,YAAoC;QAE7C,KAAK,EAAE,CAAA;QAHE,cAAS,GAAT,SAAS,CAAY;QACrB,iBAAY,GAAZ,YAAY,CAAwB;IAG/C,CAAC;IAED,iBAAiB,CAAC,KAAc,EAAE,GAAsB;QACtD,kEAAkE;QAClE,iCAAiC;QACjC,IAAI,KAAK,KAAK,SAAS,IAAI,GAAG,CAAC,OAAO,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;YAC3D,OAAO,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,YAAY,EAAE,IAAI,CAAC,SAAS,CAAC,CAAA;QACxD,CAAC;QAED,OAAO,GAAG,CAAC,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC,SAAS,CAAC,CAAA;IAC5C,CAAC;CACF;AAnBD,8CAmBC;AAED,SAAgB,WAAW,CACzB,SAAqB,EACrB,YAAoC;IAEpC,OAAO,IAAI,iBAAiB,CAAa,SAAS,EAAE,YAAY,CAAC,CAAA;AACnE,CAAC","sourcesContent":["import {\n  InferInput,\n  InferOutput,\n  Schema,\n  ValidationContext,\n  Validator,\n} from '../core.js'\n\nexport class WithDefaultSchema<\n  const TValidator extends Validator,\n> extends Schema<InferInput<TValidator>, InferOutput<TValidator>> {\n  constructor(\n    readonly validator: TValidator,\n    readonly defaultValue: InferInput<TValidator>,\n  ) {\n    super()\n  }\n\n  validateInContext(input: unknown, ctx: ValidationContext) {\n    // When in a validation context, the output should not be altered,\n    // so we don't apply the default.\n    if (input === undefined && ctx.options.mode !== 'validate') {\n      return ctx.validate(this.defaultValue, this.validator)\n    }\n\n    return ctx.validate(input, this.validator)\n  }\n}\n\nexport function withDefault<const TValidator extends Validator>(\n  validator: TValidator,\n  defaultValue: InferInput<TValidator>,\n) {\n  return new WithDefaultSchema<TValidator>(validator, defaultValue)\n}\n"]}
+{"version":3,"file":"with-default.js","sourceRoot":"","sources":["../../src/schema/with-default.ts"],"names":[],"mappings":";;;AAyEA,kCAKC;AA9ED,wCAMmB;AAEnB;;;;;;;;;;;;;;;GAeG;AACH,MAAa,iBAEX,SAAQ,gBAAuD;IAEpD;IACA;IAFX,YACW,SAAqB,EACrB,YAAoC;QAE7C,KAAK,EAAE,CAAA;QAHE,cAAS,GAAT,SAAS,CAAY;QACrB,iBAAY,GAAZ,YAAY,CAAwB;IAG/C,CAAC;IAED,iBAAiB,CAAC,KAAc,EAAE,GAAsB;QACtD,kEAAkE;QAClE,iCAAiC;QACjC,IAAI,KAAK,KAAK,SAAS,IAAI,GAAG,CAAC,OAAO,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;YAC3D,OAAO,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,YAAY,EAAE,IAAI,CAAC,SAAS,CAAC,CAAA;QACxD,CAAC;QAED,OAAO,GAAG,CAAC,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC,SAAS,CAAC,CAAA;IAC5C,CAAC;CACF;AAnBD,8CAmBC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,SAAgB,WAAW,CACzB,SAAqB,EACrB,YAAoC;IAEpC,OAAO,IAAI,iBAAiB,CAAa,SAAS,EAAE,YAAY,CAAC,CAAA;AACnE,CAAC","sourcesContent":["import {\n  InferInput,\n  InferOutput,\n  Schema,\n  ValidationContext,\n  Validator,\n} from '../core.js'\n\n/**\n * Schema wrapper that provides a default value when the input is undefined.\n *\n * In parse mode, when the input is `undefined`, the default value is used\n * instead. In validate mode, undefined values pass through unchanged (the\n * default is not applied).\n *\n * @template TValidator - The wrapped validator type\n *\n * @example\n * ```ts\n * const schema = new WithDefaultSchema(l.integer(), 0)\n * schema.parse(undefined) // 0\n * schema.parse(42)        // 42\n * ```\n */\nexport class WithDefaultSchema<\n  const TValidator extends Validator,\n> extends Schema<InferInput<TValidator>, InferOutput<TValidator>> {\n  constructor(\n    readonly validator: TValidator,\n    readonly defaultValue: InferInput<TValidator>,\n  ) {\n    super()\n  }\n\n  validateInContext(input: unknown, ctx: ValidationContext) {\n    // When in a validation context, the output should not be altered,\n    // so we don't apply the default.\n    if (input === undefined && ctx.options.mode !== 'validate') {\n      return ctx.validate(this.defaultValue, this.validator)\n    }\n\n    return ctx.validate(input, this.validator)\n  }\n}\n\n/**\n * Creates a schema that applies a default value when the input is undefined.\n *\n * Commonly used with `optional()` to provide fallback values for missing\n * properties. The default value is validated against the schema.\n *\n * @param validator - The validator for the value\n * @param defaultValue - The default value to use when input is undefined\n * @returns A new {@link WithDefaultSchema} instance\n *\n * @example\n * ```ts\n * // Integer with default\n * const countSchema = l.withDefault(l.integer(), 0)\n * countSchema.parse(undefined) // 0\n * countSchema.parse(5)         // 5\n *\n * // Commonly combined with optional in objects\n * const settingsSchema = l.object({\n *   theme: l.optional(l.withDefault(l.string(), 'light')),\n *   pageSize: l.optional(l.withDefault(l.integer(), 25)),\n * })\n * settingsSchema.parse({}) // { theme: 'light', pageSize: 25 }\n *\n * // Boolean with default\n * const enabledSchema = l.withDefault(l.boolean(), false)\n * ```\n */\nexport function withDefault<const TValidator extends Validator>(\n  validator: TValidator,\n  defaultValue: InferInput<TValidator>,\n) {\n  return new WithDefaultSchema<TValidator>(validator, defaultValue)\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atproto/lex-schema",
-  "version": "0.0.10",
+  "version": "0.0.12",
   "license": "MIT",
   "description": "Lexicon schema system for AT Lexicons",
   "keywords": [
@@ -31,13 +31,13 @@
       "types": "./dist/index.d.ts",
       "browser": "./dist/index.js",
       "import": "./dist/index.js",
-      "require": "./dist/index.js"
+      "default": "./dist/index.js"
     }
   },
   "dependencies": {
     "tslib": "^2.8.1",
-    "@atproto/syntax": "0.4.3",
-    "@atproto/lex-data": "0.0.9"
+    "@atproto/syntax": "^0.4.3",
+    "@atproto/lex-data": "^0.0.11"
   },
   "devDependencies": {
     "vitest": "^4.0.16"

package/src/core/$type.ts

@@ -1,6 +1,25 @@
 import { NsidString } from './string-format.js'
 import { OmitKey, Simplify } from './types.js'
 
+/**
+ * Constructs the `$type` string type for a given NSID and hash.
+ *
+ * The `$type` value identifies a schema definition within a lexicon:
+ * - For "main" definitions: just the NSID (e.g., `'app.bsky.feed.post'`)
+ * - For named definitions: NSID + hash + name (e.g., `'app.bsky.feed.defs#postView'`)
+ *
+ * @typeParam N - The NSID string type
+ * @typeParam H - The hash/definition name (use `'main'` for the main definition)
+ *
+ * @example
+ * ```typescript
+ * type MainType = $Type<'app.bsky.feed.post', 'main'>
+ * // Result: 'app.bsky.feed.post'
+ *
+ * type DefType = $Type<'app.bsky.feed.defs', 'postView'>
+ * // Result: 'app.bsky.feed.defs#postView'
+ * ```
+ */
 export type $Type<
   N extends NsidString = NsidString,
   H extends string = string,
@@ -12,8 +31,41 @@ export type $Type<
       : `${N}#${H}`
   : never
 
+/**
+ * Extracts the `$type` string type from an object type.
+ *
+ * @typeParam O - An object type with an optional `$type` property
+ *
+ * @example
+ * ```typescript
+ * type Post = { $type: 'app.bsky.feed.post'; text: string }
+ * type PostType = $TypeOf<Post>
+ * // Result: 'app.bsky.feed.post'
+ * ```
+ */
 export type $TypeOf<O extends { $type?: string }> = NonNullable<O['$type']>
 
+/**
+ * Constructs a `$type` string value from an NSID and definition name.
+ *
+ * For the "main" definition, returns just the NSID. For named definitions,
+ * returns the NSID followed by `#` and the definition name.
+ *
+ * @typeParam N - The NSID string type
+ * @typeParam H - The definition name type
+ * @param nsid - The NSID of the lexicon
+ * @param hash - The definition name within the lexicon (use `'main'` for the main definition)
+ * @returns The constructed `$type` string
+ *
+ * @example
+ * ```typescript
+ * $type('app.bsky.feed.post', 'main')
+ * // Returns: 'app.bsky.feed.post'
+ *
+ * $type('app.bsky.feed.defs', 'postView')
+ * // Returns: 'app.bsky.feed.defs#postView'
+ * ```
+ */
 /*@__NO_SIDE_EFFECTS__*/
 export function $type<N extends NsidString, H extends string>(
   nsid: N,
@@ -22,12 +74,50 @@ export function $type<N extends NsidString, H extends string>(
   return (hash === 'main' ? nsid : `${nsid}#${hash}`) as $Type<N, H>
 }
 
+/**
+ * Represents an object with a required `$type` property.
+ *
+ * This type adds a `$type` property to an existing object type, useful for
+ * representing typed AT Protocol objects.
+ *
+ * @typeParam V - The base object type
+ * @typeParam T - The `$type` string literal type
+ *
+ * @example
+ * ```typescript
+ * type Post = $Typed<{ text: string; createdAt: string }, 'app.bsky.feed.post'>
+ * // Result: { $type: 'app.bsky.feed.post'; text: string; createdAt: string }
+ * ```
+ */
 export type $Typed<V, T extends string = string> = Simplify<
   V & {
     $type: T
   }
 >
 
+/**
+ * Ensures an object has the specified `$type` property.
+ *
+ * If the object already has the correct `$type`, returns it unchanged.
+ * Otherwise, creates a new object with the `$type` property added.
+ *
+ * @typeParam V - The object type (may already have `$type`)
+ * @typeParam T - The expected `$type` string
+ * @param value - The object to add `$type` to
+ * @param $type - The `$type` value to ensure
+ * @returns The object with the `$type` property
+ *
+ * @example
+ * ```typescript
+ * const post = $typed({ text: 'hello' }, 'app.bsky.feed.post')
+ * // Result: { $type: 'app.bsky.feed.post', text: 'hello' }
+ *
+ * // If already typed, returns same object
+ * const typed = { $type: 'app.bsky.feed.post', text: 'hello' }
+ * const same = $typed(typed, 'app.bsky.feed.post')
+ * console.log(typed === same) // true
+ * ```
+ */
 export function $typed<V extends { $type?: unknown }, T extends string>(
   value: V,
   $type: T,
@@ -35,33 +125,75 @@ export function $typed<V extends { $type?: unknown }, T extends string>(
   return value.$type === $type ? (value as $Typed<V, T>) : { ...value, $type }
 }
 
+/**
+ * Represents an object with an optional `$type` property.
+ *
+ * This is used for objects that may or may not have type information,
+ * such as input parameters that accept both typed and untyped values.
+ *
+ * @typeParam V - The base object type
+ * @typeParam T - The optional `$type` string literal type
+ */
 export type $TypedMaybe<V, T extends string = string> = Simplify<
   V & {
     $type?: T
   }
 >
 
+/**
+ * Removes the `$type` property from an object type.
+ *
+ * Useful for extracting the "content" of a typed object without the type marker.
+ *
+ * @typeParam V - An object type with an optional `$type` property
+ *
+ * @example
+ * ```typescript
+ * type Post = { $type: 'app.bsky.feed.post'; text: string }
+ * type PostContent = Un$Typed<Post>
+ * // Result: { text: string }
+ * ```
+ */
 export type Un$Typed<V extends { $type?: string }> = OmitKey<V, '$type'>
 
+/**
+ * Unique symbol for branding unknown `$type` strings.
+ * @internal
+ */
 declare const unknown$TypeSymbol: unique symbol
+
+/**
+ * Represents an unknown or unrecognized `$type` string.
+ *
+ * This branded type is used in union types to distinguish between
+ * known typed objects and unknown typed objects (from open unions).
+ * The branding prevents accidentally matching known `$type` values.
+ */
 export type Unknown$Type = string & { [unknown$TypeSymbol]: true }
 
-// In order to prevent places that expect a union of known and unknown $typed
-// objects (like lexicons schema open unions), from accepting an invalid version
-// of the known $typed objects, we need to prevent any other properties from
-// being present.
-//
-// For example, if we expect:
-// ```ts
-// type MyOpenUnion = { $type: 'A'; a: number } | Unknown$TypedObject
-// ```
-// we want to make that that the following is rejected:
-// ```ts
-// { $type: 'A' }
-// ```
-//
-// If we typed `Unknown$TypedObject` as `{ $type: string }`, `{ $type: 'A' }`
-// would be a valid `MyOpenUnion` as it would match the `Unknown$TypedObject`.
-// By using a $type property that uniquely describes unknown values, we ensure
-// that only valid known typed objects, or a type casted value, can be used.
+/**
+ * Represents an object with an unknown `$type` value.
+ *
+ * This type is used in open union schemas to represent typed objects that
+ * don't match any of the known types. The {@link Unknown$Type} branding ensures
+ * that invalid instances of known types don't accidentally match this type.
+ *
+ * For example, in an open union like:
+ * ```typescript
+ * type MyOpenUnion = { $type: 'A'; a: number } | Unknown$TypedObject
+ * ```
+ *
+ * A value `{ $type: 'A' }` (missing the required `a` property) will NOT match
+ * `Unknown$TypedObject` because `'A'` is not assignable to `Unknown$Type`.
+ * This ensures that malformed instances of known types are properly rejected.
+ *
+ * @example
+ * ```typescript
+ * // This represents any typed object we don't recognize
+ * const unknownTyped: Unknown$TypedObject = {
+ *   $type: 'some.unknown.type' as Unknown$Type,
+ *   // ... arbitrary properties
+ * }
+ * ```
+ */
 export type Unknown$TypedObject = { $type: Unknown$Type }

package/src/core/record-key.ts

@@ -1,7 +1,36 @@
 import { isValidRecordKey } from '@atproto/syntax'
 
+/**
+ * The valid record key constraint types in a lexicon definition.
+ *
+ * - `'any'` - Accepts any valid record key
+ * - `'nsid'` - Record key must be a valid NSID
+ * - `'tid'` - Record key must be a valid TID
+ * - `'literal:...'` - Record key must be the exact specified value
+ *
+ * @example
+ * ```typescript
+ * const constraint: LexiconRecordKey = 'tid'
+ * const literalConstraint: LexiconRecordKey = 'literal:self'
+ * ```
+ */
 export type LexiconRecordKey = 'any' | 'nsid' | 'tid' | `literal:${string}`
 
+/**
+ * Type guard that checks if a value is a valid lexicon record key constraint.
+ *
+ * @typeParam T - The input type
+ * @param key - The value to check
+ * @returns `true` if the value is a valid record key constraint
+ *
+ * @example
+ * ```typescript
+ * if (isLexiconRecordKey(value)) {
+ *   // value is typed as LexiconRecordKey
+ *   console.log('Valid constraint:', value)
+ * }
+ * ```
+ */
 /*@__NO_SIDE_EFFECTS__*/
 export function isLexiconRecordKey<T>(key: T): key is T & LexiconRecordKey {
   return (
@@ -15,6 +44,21 @@ export function isLexiconRecordKey<T>(key: T): key is T & LexiconRecordKey {
   )
 }
 
+/**
+ * Validates and returns a value as a lexicon record key constraint, throwing if invalid.
+ *
+ * @param key - The value to validate
+ * @returns The value typed as {@link LexiconRecordKey}
+ * @throws {Error} If the value is not a valid record key constraint
+ *
+ * @example
+ * ```typescript
+ * const constraint = asLexiconRecordKey('tid')
+ * // constraint is typed as LexiconRecordKey
+ *
+ * asLexiconRecordKey('invalid') // throws Error
+ * ```
+ */
 /*@__NO_SIDE_EFFECTS__*/
 export function asLexiconRecordKey(key: unknown): LexiconRecordKey {
   if (isLexiconRecordKey(key)) return key