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

schemas

(no submodules)

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

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

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.