@grml/nomadic

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

无害环境管理电子邮件正常化和与供应商认识规则(Gmail、Outlook、Yahoo、iCloud等)和完全自定义的供应商配置相适应.

此软件包已被标记为弃用

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

中文使用文档
文档目录22 节
  1. 目录
  2. 安装
  3. 快开始
  4. 为甚么教化?
  5. API 参考
  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. 内建供应商
  12. 配置
  13. 添加自己的提供者
  14. 覆盖内置提供者
  15. 替换所有提供者
  16. 每个域的默认规则
  17. 选项参考
  18. 食谱
  19. 边缘案件和保障
  20. 限制
  21. 发展
  22. 许可证

游牧

供应商意识 电子邮件正常化和分类 用于浏览器和服务器。 纯粹的无害环境管理,零运行时间依赖性,完全输入.

两个地址可以指向同一个邮箱,即使它们看起来不同. [email protected] 财务报告和审定财务报表 [email protected] 都送到同一个Gmail信箱. nomadic 将任何地址解析为单个 犬类形态 ,并允许您为自己的提供者配置规则.

用它来 调试 注册, 防止 一次性/变相重新登记, 比较 或简单地说 干净 用户输入.


目录


安装

npm install @grml/nomadic

nomadic 船舶作为无害环境管理"type": "module") (中文(简体) ). 它在现代浏览器和节点18+运行,没有运行时间依赖性.

快开始

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"

为甚么教化?

邮件提供者应用自己的规则来决定地址到达的邮箱是:

行为示例同一个邮箱?
加/分地址标记[email protected] - > (中文) [email protected]对
点不敏感 (邮件)[email protected] - > (中文) [email protected]对
别名域 (邮件)[email protected] - > (中文) [email protected]对
案件敏感性[email protected] - > (中文) [email protected]对

nomadic 对每个提供者应用正确的规则并返回一个犬形字符串,因此平等的邮箱比较相等.

API 参考

每个函数都有一个可选 options 对象(参见 配置) (中文(简体) ).

normalizeEmail(email, options?) => string

返回条形体 email投篮 TypeError 若为 email 不是一个字符串。 输入格式不当( 无) @,空的本地/域)返回后修剪并保持不变.

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

normalizeEmailDetailed(email, options?) => NormalizedEmail

喜欢 normalizeEmail,但返回全部分解:

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 何时 a 财务报告和审定财务报表 b 与同一条条形地址正常化(即按照配置的规则将信箱交付给同一条).

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

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

返回拥有地址域名的提供者的ID,或 null 如果没有提供者匹配(或者输入不是一个有效的地址). 永不掷出.

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

DEFAULT_PROVIDERS

只读内置数组 ProviderRule 对象,导出后您可以在上面检查或构建.

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

内建供应商

编号分隔符删除点别名域名显著域
gmail+对gmail.comgmail.com (中文(简体) ). googlemail.com
microsoft+没有无[永久失效連結] 展望.*,热信.*,活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活
yahoo-没有无yhoo.*, ymail.com, 火箭邮件.com
icloud+没有无icloud.com (中文(简体) ). me.com (简体). mac.com
fastmail+没有无sastmail.com, sastmail.fm (中文(简体) )
proton+没有无质子邮件.com,质子.me, pm.me
yandex+没有无yandex.*, ya.ru (英语)
zoho+没有无zoho.com (中文(简体) ). zohomail.com (简体)
mailfence+没有无(原始内容存档于2017-03-26). mailfence.com
runbox+没有无运行框.com
pobox+没有无pobox.com (英语)
tutanota+没有无tuta.com (中文(简体) ). tutanota.com (简体). keemail.me
posteo+没有无posteo.de, posteo.net (英语)
mailbox+没有无邮箱.org
aol无没有无aol.com. 目标.com

所有内置提供者都小写本地部分(它们在实践中对案例不敏感).

未知域 得到一个 保守语 处理:域已小写 本地部分为左 未触及电子邮件(RFC 5321)允许对案件有敏感认识的地方 各个部件和不同的邮箱不得偶然合并。 更冲动 行为与 defaultRule。 。 。 .

配置

添加自己的提供者

通过额外规则 providers。它们由域名匹配,并优先于内置.

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]"

覆盖内置提供者

一个列出一个已存在的域名的用户提供者获胜,让你改变每个域的行为:

// 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]"

替换所有提供者

完全忽略内置, 只使用自己的:

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

每个域的默认规则

将规则应用到不匹配提供者的域中, 例如条 +tags 各地:

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

A 类 defaultRule 从未覆盖匹配的提供者( Yahoo 仍然使用) -(见a/c.5/49/70,附件).

选项参考

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

食谱

复制地址列表

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

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

以别名地址进行区块再登记

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

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

与原始键一起存储一个条形键

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

边缘案件和保障

  • 地址是分拆的 最后一个 @。 。 。 .
  • 引用 当地部分("a..b"@x.com)是逐字保存的,没有点/塔格变换.
  • 索引 0 的分隔符([email protected])为 忽略; 剥去会清空本地部分 .
  • 只有 第一个 分隔符作为切点( q)a+b+c 变成 a) (中文(简体) ).
  • 域默认小写; 匹配的提供者 canonicalDomain (如果有的话)获胜.
  • 非字符串输入抛出 TypeError。格式错误的输入返回时未改变 valid: false。 。 。 .

限制

  • valid 是一种轻量级综合检查, 没有 完全RFC 5322验证或MX验证.
  • 提供商规则反映了写作时有广泛记载的行为;提供商可以改变. 一切都是压倒一切的选择.
  • 快信风格 子域地址 (单位:千美元)[email protected])没有解决,因为它取决于账户的域布局.

发展

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/ 作为独立的脚本并运行在已编译的输出上。 CI (中文(简体) ).github/workflows/ci.yml在所有推/推上建立和运行它们.

许可证

公务员制度委员会

版本与发布记录

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

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

关于 @grml/nomadic 的常见问题

@grml/nomadic 是什么?

无害环境管理电子邮件正常化和与供应商认识规则(Gmail、Outlook、Yahoo、iCloud等)和完全自定义的供应商配置相适应.注意:该包已被作者标记为弃用——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。作者已将其标记为弃用,新项目建议寻找替代方案。