first commit
This commit is contained in:
@@ -0,0 +1,78 @@
|
||||
# `load-dictionaries` — fresh `DictionarySet` builder
|
||||
|
||||
<!-- begin:auto-docs -->
|
||||
_(no submodules)_
|
||||
<!-- end:auto-docs -->
|
||||
- [wikipedia](./de/wikipedia.md) — <!-- begin:auto-docs --> _(no submodules)_- [english-wikipedia](./en/english-wikipedia.md) — Frequency-ranked dictionary of the most common English tokens observed in Wikipedia. The matcher uses this to flag pass…
|
||||
- [names](./en/names.md) — Frequency-ranked dictionaries of common US given names (male and female) and surnames. Names are over-represented in pa…
|
||||
- [passwords](./en/passwords.md) — Frequency-ranked dictionary of the most common passwords observed across public breach corpora (RockYou, HaveIBeenPwned…
|
||||
- [es](./es/wikipedia.md) — <!-- begin:auto-docs --> _(no submodules)_ - [wikipedia](./es/wikipedia.md) — <!-- begin:auto-docs --> _(no submodules)_- [fr](./fr/wikipedia.md) — <!-- begin:auto-docs --> _(no submodules)_ - [wikipedia](./fr/wikipedia.md) — <!-- begin:auto-docs --> _(no submodules)_- [ru](./ru/wikipedia.md) — <!-- begin:auto-docs --> _(no submodules)_ - [wikipedia](./ru/wikipedia.md) — <!-- begin:auto-docs --> _(no submodules)_- [zh-Hans](./zh-Hans/wikipedia.md) — <!-- begin:auto-docs --> _(no submodules)_ - [wikipedia](./zh-Hans/wikipedia.md) — <!-- begin:auto-docs --> _(no submodules)_- [load-dictionaries](./load-dictionaries.md) — <!-- begin:auto-docs --> _(no submodules)_- wikipedia — <!-- begin:auto-docs --> _(no submodules…
|
||||
- [wikipedia](./de/wikipedia.md) — <!-- begin:auto-docs --> _(no submodules)_- [english-wikipedia](./en/english-wikipedia.md) — Frequency-ranked dictionary of the most common English tokens observed in Wikipedia. The matcher uses this to flag pass…
|
||||
- [names](./en/names.md) — Frequency-ranked dictionaries of common US given names (male and female) and surnames. Names are over-represented in pa…
|
||||
- [passwords](./en/passwords.md) — Frequency-ranked dictionary of the most common passwords observed across public breach corpora (RockYou, HaveIBeenPwned…
|
||||
- [es](./es/wikipedia.md) — <!-- begin:auto-docs --> _(no submodules)_- [wikipedia](./es/wikipedia.md) — <!-- begin:auto-docs --> _(no submodules)_- [fr](./fr/wikipedia.md) — <!-- begin:auto-docs --> _(no submodules)_- [wikipedia](./fr/wikipedia.md) — <!-- begin:auto-docs --> _(no submodules)_- [ru](./ru/wikipedia.md) — <!-- begin:auto-docs --> _(no submodules)_- [wikipedia](./ru/wikipedia.md) — <!-- begin:auto-docs --> _(no submodules)_- [zh-Hans](./zh-Hans/wikipedia.md) — <!-- begin:auto-docs --> _(no submodules)_- [wikipedia](./zh-Hans/wikipedia.md) — <!-- begin:auto-docs --> _(no submodules)_- [load-dictionaries](./load-dictionaries.md) — <!-- begin:auto-docs --> _(no submodules)_- [wikipedia](./de/wikipedia.md) — <!-- begin:auto-docs --> _(no submodules)_- [english-wikipedia](./en/english-wikipedia.md) — Frequency-ranked dictionary of the most common English tokens observed in Wikipedia. The matcher uses this to flag pass…
|
||||
- [names](./en/names.md) — Frequency-ranked dictionaries of common US given names (male and female) and surnames. Names are over-represented in pa…
|
||||
- [passwords](./en/passwords.md) — Frequency-ranked dictionary of the most common passwords observed across public breach corpora (RockYou, HaveIBeenPwned…
|
||||
- [es](./es/wikipedia.md) — <!-- begin:auto-docs --> _(no submodules)_- [wikipedia](./es/wikipedia.md) — <!-- begin:auto-docs --> _(no submodules)_- [fr](./fr/wikipedia.md) — <!-- begin:auto-docs --> _(no submodules)_- [wikipedia](./fr/wikipedia.md) — <!-- begin:auto-docs --> _(no submodules)_- [ru](./ru/wikipedia.md) — <!-- begin:auto-docs --> _(no submodules)_- [wikipedia](./ru/wikipedia.md) — <!-- begin:auto-docs --> _(no submodules)_- [zh-Hans](./zh-Hans/wikipedia.md) — <!-- begin:auto-docs --> _(no submodules)_- [wikipedia](./zh-Hans/wikipedia.md) — <!-- begin:auto-docs --> _(no submodules)_- [load-dictionaries](./load-dictionaries.md) — <!-- begin:auto-docs --> _(no submodules)_- wikipedia — <!-- begin:auto-…
|
||||
- [wikipedia](./de/wikipedia.md) — <!-- begin:auto-docs --> _(no submodules)_- [english-wikipedia](./en/english-wikipedia.md) — Frequency-ranked dictionary of the most common English tokens observed in Wikipedia. The matcher uses this to flag pass…
|
||||
- [names](./en/names.md) — Frequency-ranked dictionaries of common US given names (male and female) and surnames. Names are over-represented in pa…
|
||||
- [passwords](./en/passwords.md) — Frequency-ranked dictionary of the most common passwords observed across public breach corpora (RockYou, HaveIBeenPwned…
|
||||
- [es](./es/wikipedia.md) — <!-- begin:auto-docs --> _(no submodules)_- [wikipedia](./es/wikipedia.md) — <!-- begin:auto-docs --> _(no submodules)_- [fr](./fr/wikipedia.md) — <!-- begin:auto-docs --> _(no submodules)_- [wikipedia](./fr/wikipedia.md) — <!-- begin:auto-docs --> _(no submodules)_- [ru](./ru/wikipedia.md) — <!-- begin:auto-docs --> _(no submodules)_- [wikipedia](./ru/wikipedia.md) — <!-- begin:auto-docs --> _(no submodules)_- [zh-Hans](./zh-Hans/wikipedia.md) — <!-- begin:auto-docs --> _(no submodules)_- [wikipedia](./zh-Hans/wikipedia.md) — <!-- begin:auto-docs --> _(no submodules)_- [load-dictionaries](./load-dictionaries.md) — <!-- begin:auto-docs --> _(no submodules)_- wikipedia — <!-- begin:auto-docs --> _(no submodule…
|
||||
- [wikipedia](./de/wikipedia.md) — <!-- begin:auto-docs --> _(no submodules)_- [english-wikipedia](./en/english-wikipedia.md) — Frequency-ranked dictionary of the most common English tokens observed in Wikipedia. The matcher uses this to flag pass…
|
||||
- [names](./en/names.md) — Frequency-ranked dictionaries of common US given names (male and female) and surnames. Names are over-represented in pa…
|
||||
- [passwords](./en/passwords.md) — Frequency-ranked dictionary of the most common passwords observed across public breach corpora (RockYou, HaveIBeenPwned…
|
||||
- [es](./es/wikipedia.md) — <!-- begin:auto-docs --> _(no submodules)_ - [wikipedia](./es/wikipedia.md) — <!-- begin:auto-docs --> _(no submodules)_- [fr](./fr/wikipedia.md) — <!-- begin:auto-docs --> _(no submodules)_ - [wikipedia](./fr/wikipedia.md) — <!-- begin:auto-docs --> _(no submodules)_- [ru](./ru/wikipedia.md) — <!-- begin:auto-docs --> _(no submodules)_ - [wikipedia](./ru/wikipedia.md) — <!-- begin:auto-docs --> _(no submodules)_- [zh-Hans](./zh-Hans/wikipedia.md) — <!-- begin:auto-docs --> _(no submodules)_ - [wikipedia](./zh-Hans/wikipedia.md) — <!-- begin:auto-docs --> _(no submodules)_- [load-dictionaries](./load-dictionaries.md) — <!-- begin:auto-docs --> _(no submodules)_
|
||||
## Purpose
|
||||
|
||||
Builds a fresh `DictionarySet` value from a caller-supplied partial map,
|
||||
merged over the bundled English defaults. The bundled defaults are never
|
||||
mutated. Callers can pass `assess(pwd, { dictionaries: <set> })` to swap the
|
||||
dictionary set for one call without leaking state to subsequent calls.
|
||||
|
||||
## Features
|
||||
|
||||
- Fresh return value per call — two calls return distinct object identities
|
||||
- Frozen output — accidental consumer mutation is rejected
|
||||
- Validates every entry has a positive numeric rank and a string token
|
||||
- Throws `PWSTRENGTH.DICTIONARY_INVALID` on invalid entries
|
||||
|
||||
## Usage: Basic Example
|
||||
|
||||
```ts
|
||||
import { loadDictionaries } from "@suaveplan/password-strength";
|
||||
|
||||
const dicts = loadDictionaries({ passwords: new Map([["custom", 1]]) });
|
||||
console.log(dicts.passwords?.get("custom")); // 1
|
||||
```
|
||||
|
||||
## Usage: Advanced Example
|
||||
|
||||
```ts
|
||||
import { assess, loadDictionaries } from "@suaveplan/password-strength";
|
||||
|
||||
// Merge customer-specific banned-word list into the English defaults
|
||||
const banned = new Map<string, number>([["acmecorp", 1], ["acme-internal", 2]]);
|
||||
const dicts = loadDictionaries({ banned });
|
||||
|
||||
const result = assess("acmecorp-2026", { dictionaries: dicts });
|
||||
console.log(result.score);
|
||||
```
|
||||
|
||||
## API Reference
|
||||
|
||||
- `loadDictionaries(dicts: PartialDictionaryMap): DictionarySet`
|
||||
- Returns a fresh `DictionarySet` (frozen). The bundled English defaults
|
||||
appear under the canonical names (`passwords`, `english_wikipedia`,
|
||||
`male_names`, `female_names`, `surnames`); the supplied dictionaries
|
||||
override any default with the same name.
|
||||
- Throws `PasswordStrengthError(PWSTRENGTH.DICTIONARY_INVALID)` when any
|
||||
entry has a non-string token or a non-positive rank.
|
||||
|
||||
## Implementation Notes
|
||||
|
||||
The merge uses object spread, so caller-supplied names override defaults
|
||||
with the same key. The function does not deep-clone the entry `Map`s — they
|
||||
are already frozen by the dictionary modules — but it does freeze the
|
||||
outer record so consumers cannot add or remove named dictionaries after
|
||||
construction. Rank validation rejects `0`, negative values, and
|
||||
non-finite numbers; the spec scenario asserts the `0` case throws.
|
||||
Reference in New Issue
Block a user