@atproto/lex-schema 0.0.10 → 0.0.12

package/src/schema/unknown-object.ts

@@ -2,8 +2,24 @@ import { LexMap, isLexMap } from '@atproto/lex-data'
 import { Schema, ValidationContext } from '../core.js'
 import { memoizedOptions } from '../util/memoize.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 class UnknownObjectSchema extends Schema<UnknownObject> {
   validateInContext(input: unknown, ctx: ValidationContext) {
     if (isLexMap(input)) {
@@ -14,6 +30,24 @@ export class UnknownObjectSchema extends Schema<UnknownObject> {
   }
 }
 
+/**
+ * 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 const unknownObject = /*#__PURE__*/ memoizedOptions(function () {
   return new UnknownObjectSchema()
 })

package/src/schema/unknown.ts

@@ -1,12 +1,45 @@
 import { Schema, ValidationContext } from '../core.js'
 import { memoizedOptions } from '../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
+ * ```
+ */
 export class UnknownSchema extends Schema<unknown> {
   validateInContext(input: unknown, ctx: ValidationContext) {
     return ctx.success(input)
   }
 }
 
+/**
+ * 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 const unknown = /*#__PURE__*/ memoizedOptions(function () {
   return new UnknownSchema()
 })

package/src/schema/with-default.ts

@@ -6,6 +6,22 @@ import {
   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 class WithDefaultSchema<
   const TValidator extends Validator,
 > extends Schema<InferInput<TValidator>, InferOutput<TValidator>> {
@@ -27,6 +43,34 @@ export class 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)
+ * ```
+ */
 export function withDefault<const TValidator extends Validator>(
   validator: TValidator,
   defaultValue: InferInput<TValidator>,