`schemas` — Zod boundary schemas

(no submodules)

Purpose

Declares every Zod schema validating the package's public boundaries: AssessOptions, FeedbackOptions, AssessReactiveOptions, CrackTimeOptions, Match (discriminated union over all six pattern types), StrengthResult, and DictionarySet. Every public function Zod-parses its options before any other work, so a malformed input throws PWSTRENGTH.INVALID_OPTIONS with the original ZodError preserved on cause.

Features

Discriminated MatchSchema over six pattern types
Stable StrengthResultSchema exported for downstream consumers
Strict refinements on numeric ranges (e.g. debounceMs ∈ [0, 5000])
AbortSignal and function-typed fields validated via z.custom

Usage: Basic Example

import { AssessOptionsSchema } from "@suaveplan/password-strength/schemas";

const parsed = AssessOptionsSchema.parse({ userInputs: ["alice@example.com"] });
console.log(parsed);

Usage: Advanced Example

import { MatchSchema, StrengthResultSchema } from "@suaveplan/password-strength/schemas";

const match = MatchSchema.parse({
 pattern: "dictionary",
 i: 0,
 j: 7,
 token: "password",
 matchedWord: "password",
 rank: 1,
 dictionaryName: "passwords",
 reversed: false,
 l33t: false,
});
console.log(match.pattern); // narrowed to "dictionary"

API Reference

AssessOptionsSchema — options accepted by assess.
FeedbackOptionsSchema — options accepted by feedback.
AssessReactiveOptionsSchema — options accepted by assessReactive.
CrackTimeOptionsSchema — re-exported from scoring/crack-times.
MatchSchema — discriminated union over all six pattern types.
StrengthResultSchema — the canonical StrengthResult shape.
DictionarySetSchema — Record<string, Map<string, number>>.

Implementation Notes

MatchSchema uses z.discriminatedUnion on the pattern field so callers parsing untrusted JSON get type-narrowed output. Function-typed and AbortSignal-typed fields use z.custom since Zod has no built-in for either. The baseMatch partial is spread into each variant to keep position-tracking fields (i, j, token) consistent across the union without duplication.

Additional Implementation Notes

The implementation follows the canonical zxcvbn algorithm from Wheeler 2016 with the suaveplan-style additions described in the package proposal: structured error codes via the defineCodes registry, Zod boundaries at every public entry point, OTel histograms and counters keyed to low-cardinality attributes, and a strict input-length guard at 200 characters. Consumers integrate with their existing observability stack by installing a meter provider before importing the package, and with their i18n stack via the MessageResolver callback type declared in @suaveplan/types. The bundled data tables are intentionally small to keep the package bundle compact; production deployments should swap in fuller frequency-ranked tables via loadDictionaries. The default English dictionary set is a frozen DictionarySet that the matcher never mutates; caller-supplied dictionaries override defaults by name.

3.2 KiB Raw Blame History

schemas — Zod boundary schemas