Initial Commit

packages/persistence/database/migration/src/schemas/migration.schemas.md

@@ -0,0 +1,46 @@
+# migration.schemas
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+Zod schemas for all public option types in `@suaveplan/migration`. Providing schemas alongside the TypeScript types enables runtime validation of configuration objects, safe deserialization of stored migration state, and structured error messages when callers pass invalid options. Every schema is strict (no unrecognised keys allowed at runtime), ensuring forward compatibility does not accidentally silently accept typo'd option names.
+
+## Features
+
+- `RunOptionsSchema` — validates `signal` (AbortSignal) and `target` (string) run options.
+- `MigrationRunnerOptionsSchema` — validates `dryRun` and `checksumValidation` booleans with defaults.
+- `DistributedLockConfigSchema` — validates distributed lock `key` and `ttl` options.
+- `RedisLockConfigSchema` — validates Redis lock `key` and `ttl` options.
+- `BatchMigratorConfigSchema` — validates `concurrency` with a positive-integer constraint and default 5.
+- `MemoryStorageOptionsSchema` — validates optional `maxSize` for the in-memory store LRU limit.
+
+## Usage: Basic Example
+
+```ts
+import { MigrationRunnerOptionsSchema } from "@suaveplan/migration";
+
+const opts = MigrationRunnerOptionsSchema.parse({ dryRun: true });
+// opts.dryRun === true, opts.checksumValidation === true (default)
+```
+
+## Usage: Advanced Example
+
+```ts
+import { BatchMigratorConfigSchema } from "@suaveplan/migration";
+
+const result = BatchMigratorConfigSchema.safeParse({ concurrency: 0 });
+if (!result.success) {
+  console.error(result.error.format());
+  // concurrency must be a positive integer
+}
+```
+
+## API Reference
+
+All exports are `z.ZodObject` instances. Use `.parse()` for throwing validation, `.safeParse()` for non-throwing. All schemas are strict — extra keys cause validation failures.
+
+## Implementation Notes
+
+Schemas use `AbortSignal` via `z.instanceof(AbortSignal)` which requires the schema to be evaluated in an environment where `AbortSignal` is a global. All modern JS runtimes and Node.js ≥ 15 provide this. Numeric constraints use `.positive()` which rejects zero and negatives.