# `names` — US Census name dictionaries

## Purpose

Frequency-ranked dictionaries of common US given names (male and female) and
surnames. Names are over-represented in password breach corpora; the
matcher needs three separate dictionaries so feedback can attribute a match
to a name vs a surname vs a generic word.

## Features

- Three frozen `ReadonlyMap<string, number>` dictionaries
- `MALE_NAMES_DICTIONARY`: 20 most common male given names
- `FEMALE_NAMES_DICTIONARY`: 20 most common female given names
- `SURNAMES_DICTIONARY`: 20 most common surnames
- Public-domain US Census source data

## Usage: Basic Example

```ts
import { SURNAMES_DICTIONARY } from "@suaveplan/password-strength/dicts/en";

console.log(SURNAMES_DICTIONARY.get("smith")); // 1
```

## Usage: Advanced Example

```ts
import { loadDictionaries } from "@suaveplan/password-strength";
import {
 FEMALE_NAMES_DICTIONARY,
 MALE_NAMES_DICTIONARY,
 SURNAMES_DICTIONARY,
} from "@suaveplan/password-strength/dicts/en";

const dicts = loadDictionaries({
 male_names: MALE_NAMES_DICTIONARY,
 female_names: FEMALE_NAMES_DICTIONARY,
 surnames: SURNAMES_DICTIONARY,
});
```

## API Reference

- `MALE_NAMES_DICTIONARY: ReadonlyMap<string, number>`
- `FEMALE_NAMES_DICTIONARY: ReadonlyMap<string, number>`
- `SURNAMES_DICTIONARY: ReadonlyMap<string, number>`

## Implementation Notes

Each list is intentionally short to keep the bundle compact; production
deployments may extend any of the three by passing a fuller dictionary to
`loadDictionaries`. The lists are frozen at module load so consumers cannot
accidentally mutate them. The three-way split (male / female / surnames)
preserves zxcvbn's original feedback signal — knowing whether a match is a
given name vs a surname helps the resolver pick the right warning string.

## 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.