`schemas`

(no submodules)

Purpose

Owns the Zod boundary schemas that every public generator function uses to validate its opts argument. Schema mismatch throws PwgenError(PWGEN.INVALID_OPTIONS) with the original ZodError attached as cause, so callers can introspect the failing field path while keeping the typed error code stable for logging.

Strict-mode schemas reject unknown fields rather than silently dropping them — typos like requrieDigits (with a transposed i) surface immediately instead of being ignored at runtime. Three schemas are exported: GeneratePasswordOptionsSchema, GeneratePassphraseOptionsSchema, and EntropyOptionsSchema.

Features

Strict-object schemas reject unknown fields.
Positive-integer guards on length-shaped fields.
Discriminated wordlist accepts "long", "short", an inline string[], or any registry name.
All three schemas are invoked from at least one production call site (the conformance script verifies this).

Usage: Basic Example

import { GeneratePasswordOptionsSchema } from "@suaveplan/password-generator/schemas";

const result = GeneratePasswordOptionsSchema.safeParse({ length: 16 });
if (!result.success) throw result.error;

Usage: Advanced Example

import {
 EntropyOptionsSchema,
 GeneratePassphraseOptionsSchema,
} from "@suaveplan/password-generator/schemas";

// Pre-validate user-supplied JSON before forwarding to the generator
function fromJson(raw: unknown) {
 const parsed = GeneratePassphraseOptionsSchema.parse(raw);
 return parsed;
}

// Compose with downstream schemas
import z from "zod";
const apiBody = z.object({
 mode: z.literal("passphrase"),
 opts: GeneratePassphraseOptionsSchema,
});

API Reference

GeneratePasswordOptionsSchema — strict object mirroring GeneratePasswordOptions.
GeneratePassphraseOptionsSchema — strict object mirroring GeneratePassphraseOptions. length is optional in the schema (the generator applies the default 6).
EntropyOptionsSchema — strict object mirroring EntropyOptions.

Implementation Notes

The schemas live in a single feature module to keep the conformance script's src/schemas/ discovery simple — the script walks that directory and verifies every exported *Schema is invoked via .parse( or .safeParse( somewhere outside the directory. This pattern also matches the layout the cbor, validation, and vault packages already use, so reviewers don't need to context-switch.

Strict-object semantics are non-negotiable for boundary surfaces — Zod's default passthrough would let typos silently pass through to the generator and corrupt observability (a requireDigit typo with a missing s would not enable required-digit quotas but recordError would never fire). The trade-off — slightly more verbose error messages when adding new options forces a schema update in the same commit — is the entire point of the gate.

2.9 KiB Raw Blame History

schemas