# undo.schemas

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->
## Purpose

Provides Zod schemas for all option objects accepted by `@suaveplan/undo` constructors and factory functions. Each schema validates user-supplied configuration at runtime, producing clear error messages for invalid inputs before any internal state is created.

The schemas use `z.strict()` where applicable to prevent unrecognized keys from silently leaking into option objects — a common source of configuration bugs in JavaScript applications. Callback options like `clock`, `idGenerator`, `onTruncate`, and `dependencyCheck` are validated as `z.function()` to confirm they are callable without inspecting their signatures at runtime.

## Features

- `UndoStackOptionsSchema` — validates `maxEntries`, `maxMemoryBytes`, `onTruncate`, `clock`, `idGenerator`
- `BranchingOptionsSchema` — validates `initialBranchLabel`, `branchOnDiverge`, `maxEntries`, `clock`, `idGenerator`
- `HistoryCompressorOptionsSchema` — validates `compressionDepth`, `maxHistorySize` as positive integers
- `CommandMergerOptionsSchema` — validates `maxCount`, `timeWindowMs`, `clock`
- `SelectiveUndoOptionsSchema` — extends `UndoStackOptionsSchema` with `throwOnConflict`, `dependencyCheck`
- All numeric limits validated as positive integers to prevent nonsensical values
- Exported `z.infer`-compatible input types for each schema

## Usage: Basic Example

```ts
import { UndoStackOptionsSchema } from "@suaveplan/undo/schemas/undo.schemas";

const result = UndoStackOptionsSchema.safeParse({
  maxEntries: 100,
  maxMemoryBytes: 1_048_576,
});

if (!result.success) {
  console.error(result.error.flatten());
} else {
  const opts = result.data;
  console.log(opts.maxEntries); // 100
}
```

## Usage: Advanced Example

```ts
import {
  BranchingOptionsSchema,
  CommandMergerOptionsSchema,
  HistoryCompressorOptionsSchema,
  SelectiveUndoOptionsSchema,
} from "@suaveplan/undo/schemas/undo.schemas";

// Branching with custom clock
BranchingOptionsSchema.parse({
  branchOnDiverge: true,
  initialBranchLabel: "main",
  clock: Date.now,
  idGenerator: () => crypto.randomUUID(),
});

// Compressor with depth + size limit
HistoryCompressorOptionsSchema.parse({
  compressionDepth: 50,
  maxHistorySize: 200,
});

// Merger with time window
CommandMergerOptionsSchema.parse({
  maxCount: 20,
  timeWindowMs: 500,
  clock: Date.now,
});

// Selective undo with dependency checker
SelectiveUndoOptionsSchema.parse({
  throwOnConflict: true,
  dependencyCheck: (a: unknown, b: unknown) => false,
  maxEntries: 50,
});

// Invalid input — throws ZodError
try {
  UndoStackOptionsSchema.parse({ maxEntries: -1 });
} catch (e) {
  // ZodError: maxEntries must be a positive integer
}
```

## API Reference

### `UndoStackOptionsSchema`

Validates `UndoStackOptions`. All fields optional.

| Field | Validation |
|---|---|
| `maxEntries` | `z.number().int().positive()` |
| `maxMemoryBytes` | `z.number().int().positive()` |
| `onTruncate` | `z.function()` |
| `clock` | `z.function()` |
| `idGenerator` | `z.function()` |

### `BranchingOptionsSchema`

Same as `UndoStackOptionsSchema` minus `onTruncate`/`maxMemoryBytes`, plus `initialBranchLabel` (non-empty string) and `branchOnDiverge` (boolean).

### `HistoryCompressorOptionsSchema`

`compressionDepth` and `maxHistorySize` — both positive integers.

### `CommandMergerOptionsSchema`

`maxCount` (positive integer), `timeWindowMs` (positive number), `clock` (function).

### `SelectiveUndoOptionsSchema`

Extends `UndoStackOptionsSchema` with `throwOnConflict` (boolean) and `dependencyCheck` (function).

## Implementation Notes

`SelectiveUndoOptionsSchema` extends rather than duplicates `UndoStackOptionsSchema` to keep them in sync — any change to the base automatically propagates. The `z.function()` validator accepts any callable but does not validate arity or return types; this is intentional because TypeScript's type system already enforces those contracts at call sites. `z.strict()` on base schemas prevents typo'd option names from silently being ignored.