Initial Commit

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

@@ -0,0 +1,78 @@
+# schemas
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+Provides Zod schemas for all public option types in `@suaveplan/surrealdb`. Schema validation runs at the boundaries where user-provided configuration enters the package, catching misconfigured URLs, missing credentials, or malformed init options before they reach the driver. Using Zod allows the same schema to generate TypeScript types via `z.infer`, keeping type definitions and runtime validation in sync.
+
+Schemas are exported independently so consumers can use them in their own validation pipelines without importing full adapter classes.
+
+## Features
+
+- `AuthCredentialsSchema` — validates username and password fields
+- `SurrealDBConfigSchema` — validates full connection config including URL format
+- `DiscoverOptionsSchema` — validates schema discovery options (extensions, recursive)
+- `SchemaFileSchema` — validates individual schema file descriptors
+- `InitOptionsSchema` — validates database init options
+- `AdvancedInitOptionsSchema` — extends init options with parallel and timeout fields
+
+## Usage: Basic Example
+
+```ts
+import { SurrealDBConfigSchema } from "@suaveplan/surrealdb/schemas/schemas";
+
+const config = SurrealDBConfigSchema.parse({
+  url: "ws://localhost:8000",
+  namespace: "prod",
+  database: "app",
+  auth: { username: "root", password: "secret" },
+});
+```
+
+## Usage: Advanced Example
+
+```ts
+import {
+  InitOptionsSchema,
+  SurrealDBConfigSchema,
+} from "@suaveplan/surrealdb/schemas/schemas";
+
+// Validate and merge defaults
+const opts = InitOptionsSchema.parse({ dryRun: true });
+const cfg = SurrealDBConfigSchema.safeParse(rawInput);
+if (!cfg.success) {
+  console.error("Invalid SurrealDB config:", cfg.error.flatten());
+}
+```
+
+## API Reference
+
+### `AuthCredentialsSchema`
+
+`z.object({ username: z.string().min(1), password: z.string().min(1) })`
+
+### `SurrealDBConfigSchema`
+
+Validates `url` (URL format), `namespace`, `database`, `auth`.
+
+### `DiscoverOptionsSchema`
+
+Optional `extensions: string[]` and `recursive: boolean`.
+
+### `SchemaFileSchema`
+
+Required `name` and `path`, optional `content`.
+
+### `InitOptionsSchema`
+
+Optional `schemaDir`, `schemas`, `dryRun`, `parallel`, `timeout`. Strict — no extra keys.
+
+### `AdvancedInitOptionsSchema`
+
+Extends `InitOptionsSchema` with `parallel` and `timeout` fields.
+
+## Implementation Notes
+
+All schemas use `.strict()` where appropriate to reject extra keys and surface accidental typos in configuration objects early. URL validation in `SurrealDBConfigSchema` uses `z.string().url()`, which accepts both `ws://` and `wss://` URLs as Zod v4 validates them as valid URL schemes.