email-suggest

@zanichelli/email-suggest suggests a correction for a mistyped email domain (mario@lgmai.com → mario@gmail.com). See SPEC.md §3 for the API.

Installing

The package is on the public npm registry. No token or .npmrc is needed:

npm install @zanichelli/email-suggest

Releases are published only by CI, from a v*.*.* tag (.github/workflows/publish.yml, SPEC §9).

Usage

suggest is the only runtime export; Suggestion, its return type, is the only type export. Pass it what the user typed; show the hint if it returns something:

import { suggest } from "@zanichelli/email-suggest";

const s = suggest(input.value);
hint.textContent = s ? `Did you mean ${s.address}?` : "";

It returns a Suggestion or null:

suggest("Mario.Rossi@lgmai.com");
// { address: "Mario.Rossi@gmail.com", domain: "gmail.com" }

suggest("info@studio-rossi.con");
// { address: "info@studio-rossi.com", domain: "studio-rossi.com" }

• address is the full corrected address, with the local part exactly as typed (after trimming surrounding whitespace); domain is the corrected domain alone, lowercase.
• null means no hint: the domain is already known (mario@gmail.com), no known domain is close enough (mario@unknown-company.it), there is no @ or one side of it is empty (mario, mario@), or the argument is not a string.
• It never throws, is synchronous and does not touch window or the DOM, so it is safe under server-side rendering.
• It only suggests: it does not validate syntax and never blocks a submit (SPEC §2). Let the user keep what they typed.

make demo serves a page with the hint live, from examples/demo/, at http://127.0.0.1:5180/ (make demo DEMO_PORT=<n> for another port).

Getting started

This repository follows an agent-native setup. Start with AGENTS.md — the project map and command surface, which points at INSTRUCTION.md for the standard contract (the four execution principles).

Requires pre-commit; the command surface also calls ruff directly, so put it on your PATH (pipx/uv/pip). The JS steps (Biome, tsc, vitest, and the pre-commit hook for src/, test/ and root JSON) run in Docker: make needs Docker Compose, not Node.

make install   # set up git hooks (once)
make quality   # run the full local gate