check-password-strength

check-password-strength is a small, dependency-light utility for scoring how strong a candidate password is. It evaluates a password against four criteria — lowercase letters, uppercase letters, numbers, and symbols — plus a minimum length, and returns a diversity-and-length-based rating such as “Too weak”, “Weak”, “Medium”, or “Strong”. The default thresholds follow common password-policy conventions, but every option is overridable, including which symbol characters count (with an OWASP-recommended symbol set built in).

The package ships as CommonJS, ES module, and UMD builds with hand-maintained TypeScript definitions, so it drops into Node backends, browser bundles, or a plain <script> tag without extra tooling. It has no UI of its own — it’s a pure function you wire into your own signup or password-change form to drive a strength meter or block weak passwords before submission.

What You Get

• A passwordStrength() function returning { id, value, contains, length } for any password string
• Sensible default tiers (Too weak / Weak / Medium / Strong) based on minimum character-class diversity and length
• Fully overridable options array to match a custom password policy (your own tier count, labels, thresholds)
• An optional restrictSymbolsTo parameter to limit which characters count as “symbol”, including a built-in OWASP-recommended symbol set
• Prebuilt CommonJS, ESM, and UMD bundles plus hand-maintained .d.ts type definitions for zero-config TypeScript use

Common Use Cases

• Driving a live password-strength meter on a signup or account-settings form
• Server-side validation that rejects passwords below a minimum strength tier before they’re hashed and stored
• Enforcing a custom corporate password policy by overriding the default diversity/length thresholds
• Localizing strength labels by mapping the returned numeric id to translated strings

Under The Hood

Architecture — The entire library is one file, src/index.js (~80 lines), exporting a single pure function passwordStrength(password, options, restrictSymbolsTo). It builds an internal rules array of four regex tests (lowercase, uppercase, number, symbol), filters it against the input password to produce a contains array, then filters the caller-supplied (or default) options tier list down to tiers whose minDiversity/minLength are satisfied, sorts by descending id, and merges the best match into the returned strength object. No classes, no internal state, no I/O — a single deterministic transform from string to result object.

Tech Stack — Plain JavaScript (91% of the codebase) with a small hand-written TypeScript declaration file (src/index.d.ts, 8.5%) rather than a compiled TS source. The one runtime dependency is escape-string-regexp (used only when a custom restrictSymbolsTo set is supplied). Rollup (rollup.config.js) builds three output targets from the single source file — CJS (dist/index.js), ESM (dist/index.mjs), and a terser-minified UMD bundle (dist/umd.js) — via @rollup/plugin-commonjs and @rollup/plugin-node-resolve, with rollup-plugin-copy copying the .d.ts file into dist/.

Code Quality — test/index.test.js runs on Vitest and is unusually thorough for the library’s size: it covers every diversity/length boundary for both default and overridden options, symbol-set edge cases (including an emoji and a regression test tied to GitHub PR #81 for special-character escaping), null-password handling, and even shells out via execSync to independently exercise the built CJS, ESM, and UMD bundles (test/cjs.cjs, test/es.mjs, test/umd.cjs). Type correctness is checked separately with tsd against test/index.test-d.ts. No ESLint or Prettier config is present in the repo, so style is not automatically enforced, but the source is small and consistently formatted by hand.

API Design — The public surface is minimal: one function plus two exported constants (defaultOptions, owaspSymbols). Defaults are sensible out of the box (passwordStrength(pwd) alone is enough to get a rating), while every threshold is overridable through a single typed options array, keeping the override path just as simple as the default path. The returned shape (id, value, contains, length) is small and self-describing, and TypeScript generics (Result<V>) let callers type custom tier value types (e.g. translated strings) without losing type safety.