`config-schema`

(no submodules)

Purpose

Defines the Zod schemas that validate every public option bundle accepted by @suaveplan/api-plugin-database. The schemas live in one place so the plugin factory, the pool, the migration runner, and the tenancy callables all parse their inputs through a single canonical surface. Defaults match production-sensible knobs (10-connection pool ceiling, 5-second acquire timeout, 60-second migration lease, jittered 3-attempt retry) so callers can pass only what they want to override.

The schemas use z.object().default(...) on every nested section so partial input is filled out completely. Two cross-section invariants are enforced via superRefine: pool.min <= pool.max and retry.baseBackoffMs <= retry.maxBackoffMs. Failed parses surface a ZodError that callers wrap into a DatabaseError(DATABASE.INVALID_CONFIG) with the underlying error attached as cause.

Features

Five nested sections: pool, retry, tenancy, migrations, plus top-level connection fields.
Every leaf carries a default so parse({}) succeeds end-to-end.
Two superRefine invariants prevent nonsensical combinations.
All numeric knobs are z.number().int().min(...) so floating-point values and negative budgets are rejected before they hit production code.

Usage: Basic

import { DatabasePluginOptionsSchema } from "@suaveplan/api-plugin-database/config/config-schema";

const config = DatabasePluginOptionsSchema.parse({
    url: "ws://localhost:8000/rpc",
});
console.log(config.pool.max); // 10 (default)

Usage: Advanced

import {
    DatabasePluginOptionsSchema,
    type DatabasePluginConfigParsed,
} from "@suaveplan/api-plugin-database";

function loadConfig(json: unknown): DatabasePluginConfigParsed {
    const result = DatabasePluginOptionsSchema.safeParse(json);
    if (!result.success) {
        throw new Error(
            `Database config failed validation: ${result.error.message}`
        );
    }
    return result.data;
}

API Reference

`PoolConfigSchema`, `RetryConfigSchema`, `TenancyConfigSchema`, `MigrationConfigSchema`

Section schemas with .default(...)-applied fields. Exported in case downstream packages want to compose them into a larger config.

`DatabasePluginOptionsSchema`

Top-level schema. Accepts a partial input bundle; emits a fully populated DatabasePluginConfigParsed. Throws ZodError on invalid input. superRefine enforces pool.min <= pool.max and retry.baseBackoffMs <= retry.maxBackoffMs.

`type DatabasePluginConfigParsed`

z.infer of the top-level schema — the canonical parsed shape consumed by every internal module.

Implementation Notes

The schemas live at the package boundary; internal modules consume DatabasePluginConfigParsed, not the raw options shape. This makes every internal call site cast-free.
url defaults to ws://localhost:8000/rpc so the schema can be invoked with parse({}) in tests and dev scaffolding without crashing on missing fields. Production deployments are expected to pass a real URL.
superRefine runs after every section has been defaulted, so cross-section invariants always see fully populated values.
The zod package is imported via the default-import form (import z from "zod") per the suaveplan convention documented in feedback_zod_import.md.

3.3 KiB Raw Blame History

config-schema