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

undo.schemas

(no submodules)

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

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

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.