first commit

docs/foundation/flow/undo/src/schemas/undo.schemas.md

@@ -0,0 +1,118 @@
+# 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.