elfensky/alpha5

# alpha5 [](https://github.com/elfensky/alpha5/actions/workflows/ci.yml) NORAD Alpha-5 标识符编解码器 —— 在整数与 Space-Track 及现代 TLE/3LE 文件使用的 5 字符格式之间进行卫星目录 ID 的编码与解码（`A0123` ↔ `100123`）。零依赖。纯 ESM。约 70 行源码。该规范由美国太空军（US Space Force）冻结。 ## 安装 ``` npm install alpha5 ``` 需要 Node.js 20 或更高版本。同样适用于浏览器 —— 没有运行时依赖。 ## 用法 ``` import { decode, encode } from 'alpha5'; // or, for a namespace import: // import * as alpha5 from 'alpha5'; // alpha5.decode('A0123'); // Plain numeric designators round-trip unchanged. decode('25544'); // 25544 encode(25544); // '25544' // Alpha-5 designators decode to their canonical integer. decode('A0123'); // 100123 encode(100123); // 'A0123' // The I/O letters are reserved. decode('I0000'); // throws Error decode('O0000'); // throws Error // Boundaries: A0000 = 100,000, Z9999 = 339,999. encode(339999); // 'Z9999' encode(340000); // throws Error: exceeds Alpha-5 range ``` ## API ### `decode(s: string): number` 将 NORAD 标识符字符串解码为 `0..339_999` 范围内的整数值。 接受纯数字字符串（`"25544"`、`"00007"`）和 Alpha-5 标识符（`"A0123"`、`"Z9999"`）。接受任意长度的数字输入，因此省略了前导零的 JSON 数据源（例如用 `"7"` 代替 `"00007"`）依然可以正确解码。 如果输入出现以下情况则抛出异常： - 不是字符串，或者为空 - 包含空格、符号前缀，或十进制/科学记数法/十六进制/八进制/二进制标记 - 使用了保留字母（`I` 或 `O`） - 使用了小写字母 - 在字母前缀后有非数字尾部 - 解码后的值大于 `339_999` ### `encode(n: number): string` 将整数 NORAD ID 编码为其 5 字符标识符字符串。 - `0..99_999` 之间的值会进行零填充至 5 位数字（`encode(7) === "00007"`）。 - `100_000..339_999` 之间的值使用 Alpha-5 字母前缀（`encode(100123) === "A0123"`）。 - 输出**始终精确为 5 个字符**，且永远不包含保留字母 `I` 或 `O`。 如果 `n` 不是非负有限整数，或超过 `339_999` 则抛出异常。`BigInt`、布尔值、字符串、`null`、`undefined`、`NaN`、`±Infinity` 以及非整数浮点数均会被拒绝 —— 仅接受普通的有限整数。 ## 完整字母表 原文引自 [Space-Track Alpha-5 文档](https://www.space-track.org/documentation#tle-alpha5)： | 字母 | 值 | | 字母 | 值 | | 字母 | 值 | | ------ | ----- | --- | ------ | ----- | --- | ------ | ----- | | A | 10 | | J | 18 | | S | 26 | | B | 11 | | K | 19 | | T | 27 | | C | 12 | | L | 20 | | U | 28 | | D | 13 | | M | 21 | | V | 29 | | E | 14 | | N | 22 | | W | 30 | | F | 15 | | P | 23 | | X | 31 | | G | 16 | | Q | 24 | | Y | 32 | | H | 17 | | R | 25 | | Z | 33 | `I` 和 `O` 被省略。 ## 原因 当卫星目录接近传统 5 位 NORAD 字段的 100,000 个 objects 限制时，美国太空军引入了 **Alpha-5** 作为权宜之计：5 字符字段的首个字符变为字母（从 `A`=10 到 `Z`=33，跳过 `I` 和 `O` 以避免与 `1` 和 `0` 混淆），将可寻址范围扩展至 339,999 个 objects。 如果您从 Space-Track 获取 TLE、3LE 或 GP/GP_HISTORY 数据，就需要这个编解码器。官方 Space-Track API 仅接受整数 NORAD ID 进行过滤，因此传入的任何 5 字符标识符都必须先进行解码，然后才能将其用作数据库键或查询参数。 规范： ## 稳定性 Alpha-5 规范由美国太空军冻结。本库严格遵循该规范，并针对官方文档中的所有示例、完整字母表、双向的两个 I/O 跳过边界，以及 0–339,999 整个范围内的往返属性检查进行了测试。 如果规范发生更改（Space-Track 建议新任务迁移至 XML/JSON/KVN —— Alpha-5 本身就是权宜之计），本库也会随之更新。 ## 未提供的功能 - **不提供非填充输出选项。** 本库生成标准的 5 字符 Alpha-5；如果您希望对低于 100,000 的 ID 进行非填充输出，只需使用 `String(n)`。变宽输出不属于 Alpha-5 规范，且会淡化本库的用途。 - **不提供 TLE/3LE 行的批量解析。** 这是一个仅用于目录 ID 字段的编解码器。请使用像 [`tle.js`](https://www.npmjs.com/package/tle.js) 这样的 TLE 解析器来处理完整的 TLE/3LE，并在提取后将目录字段传递给 `decode`。 - **没有错误子类。** 所有失败都会抛出带有描述性信息的普通 `Error`。如果您需要区分失败模式，请匹配该信息。 ## 许可证 MIT © Andrei Lavrenov

标签：GNU通用公共许可证, MITM代理, Node.js, NORAD, TLE, 卫星通信, 数据可视化, 编解码工具, 自定义脚本, 航天数据