@grml/nomadic

中文文档
0.1.1发布于 2026/06/04ISCTypeScriptES Module零依赖近 30 天下载 12.5万

ESM email normalization and canonicalization with provider-aware rules (Gmail, Outlook, Yahoo, iCloud, and more) and fully customizable provider configuration.

此软件包已被标记为弃用

Package no longer supported. Contact Support at https://www.npmjs.com/support for more info.

原始使用文档
文档目录22 节
  1. Table of contents
  2. Installation
  3. Quick start
  4. Why canonicalization?
  5. API reference
  6. normalizeEmail(email, options?) => string
  7. normalizeEmailDetailed(email, options?) => NormalizedEmail
  8. isSameEmail(a, b, options?) => boolean
  9. getEmailProvider(email, options?) => string | null
  10. DEFAULT_PROVIDERS
  11. Built-in providers
  12. Configuration
  13. Add your own provider
  14. Override a built-in provider
  15. Replace all providers
  16. A default rule for every domain
  17. Options reference
  18. Recipes
  19. Edge cases & guarantees
  20. Limitations
  21. Development
  22. License

nomadic

Provider-aware email normalization and canonicalization for the browser and the server. Pure ESM, zero runtime dependencies, fully typed.

Two addresses can point to the same mailbox even when they look different. [email protected] and [email protected] both deliver to the same Gmail inbox. nomadic resolves any address to a single canonical form using per-provider rules, and lets you configure rules for your own providers.

Use it to deduplicate sign-ups, prevent disposable/aliased re-registration, compare addresses for equality, or simply clean user input.


Table of contents


Installation

npm install @grml/nomadic

nomadic ships as ESM ("type": "module"). It runs in modern browsers and in Node 18+, and has no runtime dependencies.

Quick start

import { normalizeEmail, isSameEmail, getEmailProvider } from "@grml/nomadic";

normalizeEmail("[email protected]"); // "[email protected]"
normalizeEmail("[email protected]");          // "[email protected]" (dots kept)
normalizeEmail("[email protected]");            // "[email protected]"  (Yahoo uses '-')
normalizeEmail("[email protected]");                   // "[email protected]" (unknown domain: conservative)

isSameEmail("[email protected]", "[email protected]");   // true
getEmailProvider("[email protected]");                  // "microsoft"

Why canonicalization?

Mail providers apply their own rules to decide which mailbox an address reaches:

BehaviorExampleSame mailbox?
Plus/sub-address tagging[email protected] -> [email protected]yes
Dot-insensitivity (Gmail)[email protected] -> [email protected]yes
Alias domains (Gmail)[email protected] -> [email protected]yes
Case-insensitivity[email protected] -> [email protected]yes

nomadic applies the right rules for each provider and returns one canonical string, so equal mailboxes compare equal.

API reference

Every function takes an optional options object (see Configuration).

normalizeEmail(email, options?) => string

Returns the canonical form of email. Throws TypeError if email is not a string. Malformed input (no @, empty local/domain) is returned trimmed and unchanged.

normalizeEmail("  [email protected] "); // "[email protected]"

normalizeEmailDetailed(email, options?) => NormalizedEmail

Like normalizeEmail, but returns the full breakdown:

normalizeEmailDetailed("[email protected]");
// {
//   normalized: "[email protected]",
//   local: "johndoe",
//   domain: "gmail.com",
//   providerId: "gmail",   // null for unknown domains
//   subaddress: "promo",   // the stripped tag, or null
//   valid: true,           // does it look like a syntactically valid address?
// }

isSameEmail(a, b, options?) => boolean

true when a and b normalize to the same canonical address (i.e. deliver to the same mailbox under the configured rules).

isSameEmail("[email protected]", "[email protected]"); // true
isSameEmail("[email protected]", "[email protected]");              // false (distinct mailboxes)

getEmailProvider(email, options?) => string | null

Returns the id of the provider that owns the address's domain, or null if no provider matches (or the input is not a valid address). Never throws.

getEmailProvider("[email protected]");   // "proton"
getEmailProvider("[email protected]"); // null

DEFAULT_PROVIDERS

The read-only array of built-in ProviderRule objects, exported so you can inspect or build on top of it.

import { DEFAULT_PROVIDERS } from "@grml/nomadic";
DEFAULT_PROVIDERS.flatMap((p) => p.domains); // every recognized domain

Built-in providers

idSeparatorRemoves dotsAlias domainNotable domains
gmail+yesgmail.comgmail.com, googlemail.com
microsoft+nononeoutlook.*, hotmail.*, live.*, msn.com
yahoo-nononeyahoo.*, ymail.com, rocketmail.com
icloud+nononeicloud.com, me.com, mac.com
fastmail+nononefastmail.com, fastmail.fm
proton+nononeprotonmail.com, proton.me, pm.me
yandex+nononeyandex.*, ya.ru
zoho+nononezoho.com, zohomail.com, zoho.eu
mailfence+nononemailfence.com
runbox+nononerunbox.com
pobox+nononepobox.com
tutanota+nononetuta.com, tutanota.com, keemail.me
posteo+nononeposteo.de, posteo.net
mailbox+nononemailbox.org
aolnonenononeaol.com, aim.com

All built-in providers lowercase the local part (they are case-insensitive in practice).

Unknown domains get a conservative treatment: the domain is lowercased and the local part is left untouched. The email spec (RFC 5321) permits case-sensitive local parts, and distinct mailboxes must not be merged by accident. Opt into more aggressive behavior with defaultRule.

Configuration

Add your own provider

Pass extra rules via providers. They are matched by domain and take precedence over the built-ins.

import { normalizeEmail, type ProviderRule } from "@grml/nomadic";

const corporate: ProviderRule = {
  id: "corp",
  domains: ["mycompany.com", "mycompany.co"],
  canonicalDomain: "mycompany.com", // collapse the alias
  lowercaseLocal: true,
  removeDots: true,
  subaddressSeparators: ["+"],
};

normalizeEmail("[email protected]", { providers: [corporate] });
// "[email protected]"

Override a built-in provider

A user provider that lists an existing domain wins, letting you change behavior per domain:

// Treat gmail.com strictly: keep dots, don't collapse googlemail, just lowercase.
normalizeEmail("[email protected]", {
  providers: [{ id: "gmail-strict", domains: ["gmail.com"], lowercaseLocal: true }],
});
// "[email protected]"

Replace all providers

Ignore the built-ins entirely and use only your own:

normalizeEmail("[email protected]", {
  replaceDefaultProviders: true,
  providers: [{ id: "only", domains: ["only.com"], subaddressSeparators: ["+"] }],
});
// gmail.com now matches nothing -> conservative default

A default rule for every domain

Apply rules to domains that match no provider, e.g. strip +tags everywhere:

normalizeEmail("[email protected]", {
  defaultRule: { lowercaseLocal: true, subaddressSeparators: ["+"] },
});
// "[email protected]"

A defaultRule never overrides a matched provider (Yahoo still uses -, etc.).

Options reference

interface NormalizeOptions {
  providers?: ProviderRule[];        // extra/override rules (win by domain)
  replaceDefaultProviders?: boolean; // ignore the built-ins entirely (default: false)
  defaultRule?: DefaultRule;         // rule for unmatched domains
  lowercaseDomain?: boolean;         // default: true
}

interface ProviderRule {
  id: string;                        // stable identifier, e.g. "gmail"
  domains: string[];                 // domains this rule applies to (case-insensitive)
  canonicalDomain?: string;          // collapse all matched domains to this one
  lowercaseLocal?: boolean;          // lowercase the local part
  removeDots?: boolean;              // strip dots from the local part (Gmail)
  subaddressSeparators?: string[];   // tag separators, e.g. ["+"] or ["-"]
}

// DefaultRule is a ProviderRule without `id`, `domains`, or `canonicalDomain`.

Recipes

Deduplicate a list of addresses

import { normalizeEmail } from "@grml/nomadic";

const unique = [...new Map(
  rawEmails.map((e) => [normalizeEmail(e), e]),
).values()];

Block re-registration with an aliased address

import { isSameEmail } from "@grml/nomadic";

const alreadyUsed = existingUsers.some((u) => isSameEmail(u.email, signup.email));

Store a canonical key alongside the original

const { normalized, valid } = normalizeEmailDetailed(input);
if (!valid) throw new Error("Invalid email");
await db.users.insert({ email: input, emailKey: normalized });

Edge cases & guarantees

  • The address is split on the last @.
  • Quoted local parts ("a..b"@x.com) are preserved verbatim, with no dot/tag transforms.
  • A separator at index 0 ([email protected]) is ignored; stripping it would empty the local part.
  • Only the first separator is used as the cut point (a+b+c becomes a).
  • Domains are lowercased by default; the matched provider's canonicalDomain (if any) wins.
  • Non-string input throws TypeError. Malformed input is returned unchanged with valid: false.

Limitations

  • valid is a lightweight syntactic check, not full RFC 5322 validation or MX verification.
  • Provider rules reflect widely-documented behavior at the time of writing; providers can change. Everything is overridable via options.
  • Fastmail-style subdomain addressing ([email protected]) is not resolved, because it depends on the account's domain layout.

Development

npm install      # install dependencies
npm run build    # compile TypeScript to dist/ (tsc)
npm test         # build output is run as node scripts (dist/tests/*.js)

Tests live in tests/ as standalone scripts and run against the compiled output. CI (.github/workflows/ci.yml) builds and runs them on every push/PR.

License

ISC

版本与发布记录

@grml/nomadic 共发布 2 个版本,首次发布于 2026/06/04;过去 12 个月发布了 2 个版本。

版本发布日期距今
0.1.1latest2026/06/045 个月前
0.1.02026/06/045 个月前

关于 @grml/nomadic 的常见问题

@grml/nomadic 是什么?

ESM email normalization and canonicalization with provider-aware rules (Gmail, Outlook, Yahoo, iCloud, and more) and fully customizable provider configuration.注意:该包已被作者标记为弃用——Package no longer supported. Contact Support at https://www.npmjs.com/support for more info.

如何安装 @grml/nomadic?

在项目目录运行 npm install @grml/nomadic,或使用 pnpm add / yarn add / bun add。

@grml/nomadic 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@grml/nomadic 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@grml/nomadic 可以商用吗?

@grml/nomadic 使用 ISC 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@grml/nomadic 的下载量有多少?

根据 npm 官方下载统计,@grml/nomadic 在 2026/10/17 – 2026/11/15 这 30 天内被下载 125,122 次,日均约 4,171 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@grml/nomadic 还在维护吗?

最新版本 0.1.1 发布于 2026/06/04(5 个月前);至今共发布 2 个版本,其中过去 12 个月发布了 2 个;首次发布于 2026/06/04。作者已将其标记为弃用,新项目建议寻找替代方案。