@haraka/电子邮件地址
一个高性能的零依赖电子邮件地址解析器和电子邮件地址验证器 简单, SMTP 软件 信封 (RFC 5321和电子邮件) 页眉 (RFC 5322/6532)格式。 作为无害环境管理和CJS的双重出版物使用 import 或者说 require。 。 。 .
不遵守严格RFC但包括宽大 邮递 选项。 最佳级 O(n) 语 业绩(基准) (中文(简体) ).
parseEnvelope('<[email protected]>') // → Address
parseHeader('"Alice" <a@x>, "Bob" <b@x>') // → Address[]
parseHeader('Friends: a@x, b@x;') // → [Group]
信封侧柄 <>, (中文(简体) ), <Postmaster>,点原子和引用的地方部分,
IPv4/IPv6地址字元和IDN(U-lables → punycode). 页眉侧会添加显示名称,注释(包括嵌入),折叠白空间,组语法,过时
制作真实世界的邮件仍然会发出.
安装
npm install @haraka/email-address
使用量
无害环境管理和CJS两个切入点都暴露出一个相同的 Address 课.
信封
import { Address, parseEnvelope } from '@haraka/email-address'
const addr = parseEnvelope('<[email protected]>')
addr.user // 'user'
addr.host // 'example.com'
addr.address // '[email protected]'
addr.format() // '<[email protected]>'
addr.isNull() // false
// The class form is preserved for back-compat with v3:
new Address('<[email protected]>').format() // '<[email protected]>'
页眉
parseHeader 接受全套标题制作——命名添加器,
添加- spec, 地址列表, 以及组 。 返回总是一个阵列,
混合 Address 财务报告和审定财务报表 Group 按文档顺序排列.
import { parseHeader, parseFrom, Group } from '@haraka/email-address'
const list = parseHeader(
'"Alice Smith" <[email protected]>, [email protected] (Bob), ' +
'Friends: [email protected], [email protected];',
)
for (const entry of list) {
if (entry instanceof Group) {
console.log('group:', entry.phrase, entry.addresses.length, 'members')
} else {
console.log(entry.phrase, entry.address, entry.name())
}
}
// Header-shaped shortcuts:
parseFrom('Travis CI <[email protected]>') // → Address[]
parseSender('"Anne, PMPM" <[email protected]>') // → Address
parseReplyTo('=?utf-8?Q?Anne?= <[email protected]>') // → Address[]
平面地址验证(网表、通用)
当您只需要“ 这是有效的电子邮件地址 ” — 注册表格、 联系页、 CSV 导入项 — 使用 parseAddress (在错误输入上)或 isValid (返回布尔) 他们拒绝任何不光彩的东西 local@domain:角括号,注释,显示姓名,地址列表,以及组都失败.
import { parseAddress, isValid } from '@haraka/email-address'
isValid('[email protected]') // true
isValid('<[email protected]>') // false (angle brackets are envelope-only)
isValid('Alice <[email protected]>') // false (display names are header-only)
isValid('not-an-email') // false
// Strict, RFC-conformant — "user@example" (no TLD) is valid by default:
isValid('user@localhost') // true
// Web-form preset: require a TLD:
isValid('user@localhost', { requireTLD: true }) // false
isValid('[email protected]', { requireTLD: true }) // true
// Throwing variant — returns an Address when valid:
const a = parseAddress('[email protected]')
a.user // 'first.last'
a.host // 'example.com'
司法理事会
const { Address, parseEnvelope, parseHeader, Group } = require('@haraka/email-address')
parseEnvelope('<[email protected]>').format()
parseHeader('"Alice" <a@x>')[0].phrase // 'Alice'
两种样式在 examples/esm.mjs 财务报告和审定财务报表 examples/cjs.cjs;每个打印解析字段,用于同一组输入.
对于国际化地址,解析器保留了原始的U-label形式并懒散地暴露出A-label(punycode)形式:
const addr = new Address('<δοκιμή@παράδειγμα.gr>')
addr.user // 'δοκιμή'
addr.original_host // 'παράδειγμα.gr'
addr.host // 'xn--hxajbheg2az3al.gr'
addr.is_utf8 // true
addr.format(true) // '<δοκιμή@xn--hxajbheg2az3al.gr>'
模块布局
包裹 exports 映射自动解析到右侧文件 :
| 消费者风格 | 决定 | 页:1 |
|---|---|---|
import { Address } from '@haraka/email-address' | index.js | 本土无害环境管理;犬类来源. |
require('@haraka/email-address') | dist/cjs/index.cjs | 自动生成 CJS 镜像树 . |
| 类型脚本 | index.d.ts | 不论进入点,类型相同. |
API 密码
解析器
| 函数 | 回返 | 说明 |
|---|---|---|
parseEnvelope(input, opts?) | Address | RFC-5321 单一信封地址(MAIL FROM: 编号 : RCPT TO:) (中文(简体) ). |
parseHeader(input, opts?) | (Address | Group)[] | RFC-5322头值. 默认 startAt = 'address-list'。 。 。 . |
parseFrom(input) | (Address | Group)[] | parseHeader(input, { startAt: 'from' })。 。 。 . |
parseSender(input) | Address | parseHeader(input, { startAt: 'sender' })[0] —— 说 Sender: 按语法是单位地址. |
parseReplyTo(input) | (Address | Group)[] | parseHeader(input, { startAt: 'reply-to' })。 。 。 . |
new Address(envelope, opts?) | Address | 后相兼容构造器——等同 parseEnvelope。 。 。 . |
new Address(user, host, opts?) | Address | 在不解析的情况下从部分中构建地址 . |
信封选项
| 选项 | 类型 | 默认 | 效果 |
|---|---|---|---|
postel | boolean | false | 你接受的东西要自由 何时 true: (1) 畸形 [IPv6:…] (b) 256-oct RFC 5321 §4.5.3.1.3 路径限制和64-octet §4.5.3.1.1 局部部分限制提高到998-octet SMTP文本行上限(§4.5.3.1.6) |
页眉选项
| 选项 | 类型 | 默认 | 效果 |
|---|---|---|---|
startAt | 'address-list' | 'from' | 'sender' | 'reply-to' | 'mailbox' | 'mailbox-list' | 'group' | 'angle-addr' | 'address' | 'address-list' | RFC-5322开始生产 主要用于 parseFrom 编号 : parseSender 编号 : parseReplyTo 包装. |
allowAtInDisplayName | boolean | true | 接受 @ 内部显示名称——在现实世界中常见 From: 数值 foo@example <[email protected]>。 。 。 . |
allowCommaInDisplayName | boolean | false | 接受 , 内显示名称。 默认关闭,因为它打破 ,- 分开的地址列表语法. |
postel | boolean | false | 你接受的东西要自由 启用两个 RFC-5322 § 4.4 obs- * 生产 : 本地边 (多词的本地部分,例如: "foo"."bar"@x.com和 obs- mbox 列表 无效条目( e)a@x, , b@y,在组合中指向或中间逗号). |
Address 属性
| 财产 | 说明 |
|---|---|
user | 当地部分为书面(案件保存,引文保存). |
host | 域名形式:小写,U-标签转换为A-标签(punycode). |
original_host | 成文域:大小写保存,U-标签保存. |
original | 完整的输入字符串 . |
is_utf8 | true 何时 无论是 本地部分或域包含非ASCII(RFC 6531). 不设. |
address | user@host 使用 original_host 因此,案件被保留下来。 唯读取出. |
phrase | 从页眉解析显示名称 。 信封分隔地址的空字符串 . |
comment | 轨迹 (…) 从页眉中解析 。 信封分隔地址的空字符串 . |
group | 关闭 Group 当解析在一个, 否则 null。 。 。 . |
Address 方法
| 方法 | 回返 |
|---|---|
isNull() | true 用于无倒向路径的(<> / 空输入). |
format(use_punycode = false) | 冠状. 信封 : <user@host>。标题 : Phrase <user@host> (Comment)与 use_punycode = true,圆码 host 已使用. |
name() | 从 Heuristic 个人姓名提取 phrase 编号 : comment 编号 : address. 回归 '' 当找不到可用文件时. |
toString() | 与 format()。 。 。 . |
Group
Group 实例出现在 parseHeader 输入时的结果
包含类似 Friends: a@x, b@x;. 每个成员 Address 已经
联合国 .group 字段指向附件 Group。 。 。 .
| 外地/方法 | 说明 |
|---|---|
phrase | 组显示名 . |
addresses | Address[] ——按文件顺序分组成员. |
format() | phrase:addr1,addr2,…; 按RFC 5322§3.4进行渲染. |
name() | 从 Heuristic 个人姓名提取 phrase。 。 。 . |
姓名处理公用事业
从 address-rfc2822 用于源兼容性 :
| 函数 | 说明 |
|---|---|
nameCase(s) | 带有Mc/O'和罗马数字的特案标题level iii support → Level III Support) (中文(简体) ). |
isAllLower(s) 编号 : isAllUpper(s) | 用于大小写检测的助手 nameCase。 。 。 . |
extractName(phrase, address?) | 背后的热情 Address.prototype.name() ——曝出可直接使用. |
遵守标准
此解析器的目标是默认严格符合SMTP信封语法. 下表跟踪每个相关的RFC以及模块对此所做的.
| RFC (RFC ) (法语) | 议题 | 状态 |
|---|---|---|
| RFC 821 (韩语) 编号 : 第2821号 编号 : 第5321号 | SMTP 信封地址 | 相会相会. 执行§4.1.2(邮箱、路径、源路由、ADL)、§4.1.3(地址文字)和§4.5.3.1的长度限制. |
| RFC 5321 第4.1.2节 | 地方部分(点弦,引自) | 相会相会. 两种表格都进行了解析;保存了大小写;引用了页(\x已接受. |
| RFC 5321 第4.1.3节 | IPv4 地址文字 | 相会相会. 严格octet验证(0-255,无前置0). |
| RFC 5321 第4.1.3节 | IPv6 地址文字 | 符合规定(严格). 这个 IPv6: 标记是对 IPv6- full / IPv6-comp / IPv6v4- full / IPv6v4-comp 生产进行验证. 这个 postel: true 选项选择返回到后退. |
| RFC 5321 第4.1.2节 | 源路线/ ADL | 差异(已丢弃). 源路由分析正确但静态投放;只有最后的邮箱被保留. RFC 5321 调取出源路由; 需要时从外部保存. |
| RFC 5321 第4.5.3.1.1节 | 64个地方部分 | 相会相会. 字节被计算为UTF-8 octets. postel: true 将上限提高到998octets(第4.5.3.1.6节SMTP文本行上限). |
| RFC 5321 第4.5.3.1.2节 | 255-octet域名 | 相会相会. 在任何IDN编码之前检查过了 . |
| RFC 5321 第4.5.3.1.3节 | 256-octet 路径 | 相会相会. 在输入字符串上执行. postel: true 将上限提高到998octets(第4.5.3.1.6节SMTP文本行上限). |
| RFC 1035 第2.3.4节 编号 : RFC 5321 第4.5.3.1.1节 | 63-octet标签 | 相会相会. 如果每个子域标签的UTF-8长度超过63个octets,则会被拒绝. |
| RFC 1123 第2.1节 | 标签可能以数字开头 | 相会相会. |
| 第3629号公约 | UTF-8 八分点计数 | 相会相会. 用途 Buffer.byteLength(..., 'utf8') 检查每个地方的长度. |
| RFC 5322 (韩语) | 信件头地址语法 | 合规通过 parseHeader。 。 。 . 对§3.4(名称添加、添加- spec、组、地址-列表)的递归-descent解析器,带有默认允许的§4.4过时生产(FWS周围) @,点点显示名称, _ 在遗留标签中,嵌入式评论)。 信封解析仍然拒绝这些——它们只适用于信头路径. |
| RFC 6531 (韩语) | SPTPUTF8——国际化地址 | 协和 (基础). 本地部分和域均接受非ASCII代码点. is_utf8 设定为 无论是 侧面包含非ASCII。 Unicode 正常化( NBC) 是 没有 执行. |
| RFC 5890 (法语) 编号 : 第5891号 编号 : 第5892号 编号 : UTS-46号 | IDNA2008 / UTS-46 (英语) | 协和会 (通过平台). IDN 转换使用节点的内置 url.domainToASCII,它执行UTS-46(IDNA2008有过渡规则). 无效的 IDN 标签 . |
| RFC 5893 (法语) | Bidi(从右到左)规则 | 继承自 domainToASCII。 。 。 . 未由本模块单独执行 . |
| RFC 5198 (法语) | 网- Unicode (NFC) (NFC) | 差额(未正常化). 解析器保留了调用者提供的形式. 如果需要在编码上进行比特等同的比较,则将外部规范化. |
许可证
麻省理工学院.