@hadron-memory/urn-lib-js

中文文档
0.0.22发布于 2026/11/14MITTypeScriptES Module零依赖近 30 天下载 1.2万

硬URN作曲/平面/规范化——固定-公司驱动,与骨灰管-lib-go的跨语言等同

中文使用文档
文档目录11 节
  1. 状态
  2. 获取 Loc: 使用分解器而不是 pathSegments
  3. 使用量
  4. 符合性
  5. 出票人和代理任务(语法 v2)
  6. App事件(语法 v2)
  7. 赠款(语法v2)
  8. 根登记政策
  9. 动作( 语法 v2)
  10. AI 服务配置( 语法 v2)
  11. 许可证

@hadron-memory/urn-lib-js (英语)

Hadron URN为JavaScript & TypeScript作曲 / 剖析 / 正常化.

发自内心 urn-lib-go两者 执行 同样的符合性 (单位:千美元)fixtures/corpus.json(b) —— 所以两种语言不能漂移 存在到 替换已经漂移过 : hadron-server / portal / docs / cli (hadron-server #239, #693) (英语).

状态

增一相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相. 此放出纯自存的端口 切片为 hadron-server/src/lib/urn.ts 拼写地,在共同的书目背后:

  • 计划 —— 说 CANONICAL_SCHEME, (中文(简体) ), LEGACY_SCHEME, (中文(简体) ), hasSchemePrefix, (中文(简体) ), normalizeScheme
  • 登记 ——锁定类型登记簿(URN_TYPES, (中文(简体) ), ROLE_MARKERS, (中文(简体) ), RESERVED_SLUGS, (...) (中文(简体) )
  • 常态 —— 说 normalizeUrnForLookup, (中文(简体) ), legacyMemoryUrnToCanonical, (中文(简体) ), agentSlugFromUrn
  • 弹片 —— 说 validateAtomShape, (中文(简体) ), validateUserSlug, (中文(简体) ), validateOrgSlug (需要点取出根,为"692", validateUserHandle (dot-free, 第692页), deriveSlugFromName
  • 遗产 —— 说 parseUrnInput, (中文(简体) ), formatUrn, (中文(简体) ), validateUrnType (021前表面)
  • 解析器 —— 说 parseUrn (Cononical-form parser, D11猫 1+4),, (中文(简体) ), isParserCanonical, (中文(简体) ), toParserCanonical
  • 编曲 —— 说 formatCanonicalUrn, (中文(简体) ), composeNodeUrn, (中文(简体) ), composeEdgeUrn
  • 显示 —— 说 parseDisplayUrn, (中文(简体) ), DISPLAY_URN_TYPES (容忍的 spec-010 芯片解析器/注册器——与严格的克诺克解析器分开;倒回 unknown 未注册显示类型)
  • 错误 —— 说 UrnParseError + 机器稳定 UrnParseErrorReason 工会

Grammar-v2 平面形式 (hardon-server#694) 移植: parseUrnV2 编号 : composeUrnV2 编号 : isFlatV2 结束 hrn:<type>:<root>[:<segment>...] (单一) 结肠,无锡吉尔,为v1表面添加剂.

实体 v2 形状 (原服务器#696,决定D-2026-07-15-006) 也移植过 :

  • 隐藏 ——两个形状,而分量决定: hrn:secret:<root>:<name> (org/user root + 完全一个名字原子)和 App 密语 hrn:secret:<root>:app:<app-slug>:<name> (字面小写 app 标记, 然后是App的sult和这个秘密的名字; vers-lib-js#40. hrn:secret:<root>:app 仍然是平地的秘密命名 app两个部分、四个或四个以上部分以及任何其他部分 标记 (APP, (中文(简体) ), memory, (中文(简体) ), org, (中文(简体) ), agent, (中文(简体) ), user) 被拒绝, App 形状 从不坐落在保留根下(server, (中文(简体) ), platform) (中文(简体) ). 679号 :: 拼写 <root>::<app|memory>:<slug>::<name> 被拒绝 parseUrn从来没有正常化. 以 composeAppSecretUrnV2· ; parseSecretUrnV2 就说是谁的 (单位:千美元){ownerKind: 'root', root, name} 或者说 {ownerKind: 'app', root, appSlug, name}, (中文(简体) ), 所以消费者永远也不要重新思考 均等规则.
  • 应用程序 —— 说 hrn:apprun:<root>:<app>:<run-id> (固定不变).
  • 节点 —— 说 hrn:noderev:<root>:<mem>:<loc...>:<rev>, (中文(简体) ), 最终焦虑 (最近一次发言) 原子是修订版 id; 分解为 parseNodeRevUrnV2。 。 。 .
  • 节点/边缘 —— 说 hrn:<type>:<root>:<mem>:<loc...> (一个内存+至少一个) loc 原子; loc 是一个 不透明终端 (边接器从不重拆) 输入 source:target) (中文(简体) ).
  • #data 碎片 —— 说 <node-or-apprun-urn>#data (节点数据是 其父母,而不是独立类型. composeDataFragmentV2 总是发出一个 犬类 hrn: URN,甚至从一个遗产 urn:- 骗人的家长.

#696 降级了 v1 节点 -编 类型字(data, (中文(简体) ), condition改为: 碎片 这改变了拼法,而不是意义 parseUrn 地图a 零碎平方v2 URN 在碎片的v1类型词上: hrn:node:<root>:<mem>:<loc>#data 解析为 type: 'data' 在父母身边 路径, 这恰恰是 v1 hrn:data:<root>::<mem>::<loc> 读取 同样的资源. parserCanonical 保留 v2 形式( 包含碎片), 因此 圆通相通. 一个V2上的碎片仅限 父关系( e)apprun, (中文(简体) ), worker)没有v1 类型等同并保持其 unknown-type 出错; 达到 parseUrnV2 何时 您需要父类型和片段作为单独的字段.

已键入的帮助 : composeSecretUrnV2, (中文(简体) ), composeAppSecretUrnV2, (中文(简体) ), parseSecretUrnV2, (中文(简体) ), composeAppRunUrnV2, (中文(简体) ), composeNodeRevUrnV2, (中文(简体) ), composeDataFragmentV2,以及 parseNodeRevUrnV2。 。 。 .

尚未移植(后来的增量,由同一实体提供):遗留链-平面 正常化 + 存储的别名地图( hadron- server # 697) 和统一 校长组合 执行(哈德伦服务器#692).

获取 Loc: 使用分解器而不是 pathSegments

ParsedUrn.pathSegments 是一个 原始分块,其形状跟随输入 语法 (# 12) v1 输入被分割 ::,因此一个部分可能带有内部 :; 平面- v2 输入在单上分割 :,所以每个原子都是自己的元素. 因此,一种资源的两种拼写不同:

parseUrn('hrn:node:acme.com::specs::cor:urn').pathSegments  // ['acme.com', 'specs', 'cor:urn']
parseUrn('hrn:node:acme.com:specs:cor:urn').pathSegments    // ['acme.com', 'specs', 'cor', 'urn']

这影响到每个类型,其v1形式允许内部 : 在一段内 memory (价值角色标记如: app-user:<id>, (中文(简体) ), node,以及 edge。 。 。 . org, (中文(简体) ), user, (中文(简体) ), agent, (中文(简体) ), app, (中文(简体) ), secret 财务报告和审定财务报表 asset 在两种语法下都是相同的.

splitNodeUrn 编号 : splitEdgeUrn 实现语法正常化并报告a #data 因此,一个打来电话的人 从来不需要知道它是什么语法:

splitNodeUrn('hrn:node:acme.com::specs::cor:urn');       // { memoryUrn: 'acme.com:specs', loc: 'cor:urn' }
splitNodeUrn('hrn:node:acme.com:specs:cor:urn');         // { memoryUrn: 'acme.com:specs', loc: 'cor:urn' }
splitNodeUrn('hrn:node:acme.com:specs:cor:urn#data');    // { …, loc: 'cor:urn', fragment: 'data' }

边缘是 不透明终端 —— 说 splitEdgeUrn 永不重分割为 source:target启用 parseUrnV2 如果您想要 v2 根 / 片段 / 块作为单独的字段.

当碎片是 仅限 核电站有问题, parseUrn 这么说的 页:1 fragment-unsupported 而不是泄露v1 解析者的申诉 关于 # 字符 :

parseUrn('hrn:node:acme.com:mem:loc#bogus');  // UrnParseError, reason 'fragment-unsupported'
parseUrn('hrn:worker:acme.com:eng:iris#data'); // 'unknown-type' — worker has no v1 form either way

测试是去除碎片是否会使输入解析. 如果是 本来的原因已经存在了 所以把错误的名字都修好 前进.

两个都回来 NodeLikeUrnParts (节点和边缘共用一个形状). 在v1之下 记忆可能 多个部分终端 :: 段为 loc :

splitNodeUrn('hrn:node:mm.org::coding-app::coding-agent::app-mem::a:b');
// { memoryUrn: 'mm.org:coding-app:coding-agent:app-mem', loc: 'a:b' }

两者都是 自验证他们拒绝一个未注册的片段词和一个 边缘上的片段(只有 node编号 :apprun 因此,他们永远不会 比较宽容 parseUrn 对于相同的输入.

已知缺口 : 没有 splitMemoryUrn 然而,v2叶 mem 平等性 不受约束,所以 hrn:mem:<root>:<a>:<b>:<c> 不能拆分为容器 vs 叶子直到 v2 spec spins it (hadron-server #698).

使用量

import { normalizeUrnForLookup, validateOrgSlug, UrnParseError } from '@hadron-memory/urn-lib-js';

normalizeUrnForLookup('acme.com::specs::cor:urn'); // 'acme.com:specs:cor:urn'

try {
  validateOrgSlug('Acme.com');
} catch (e) {
  if (e instanceof UrnParseError) console.log(e.reason); // 'slug-not-lowercase'
}

符合性

fixtures/corpus.json 是行为真相的来源 每个案件都是 { fn, in: [args], out?, throws? } —— 说 out 是预期的回报, throws 实值 预想数 UrnParseError.reason,既不意味着 void 一定要打电话 别扔了. test/corpus.test.ts * 审理与执行有关的每一个案件; urn-lib-go 运行相同的文件. 增加行为 通过增加一个案件, 而不是通过编辑一种语言的测试.

npm是记录的软件包管理器. package-lock.json 是唯一一个 树上的锁文件——不要再加第二个.

npm install
npm test          # runs the corpus
npm run build

出票人和代理任务(语法 v2)

hrn:ticker:<root>:<app-slug>:<ticker-slug> 财务报告和审定财务报表 hrn:agenttask:<root>:<app-slug>:<task-id> 每一部分在后面有两段 root根. 使用 composeTickerUrnV2 与滴答的永久衍生出弹片和 composeAgentTaskUrnV2 与任务的身份。 两个都通过 parseUrnV2, (中文(简体) ), 让他们自己的展出徽章, 并正常化的遗产 urn: 前缀为 hrn:。 。 。 . 它们没有v1等同物; parseUrn 拒绝他们 unknown-type。 。 。 .

任务标识遵循共享的URN原子规则(字母/数字、点、下划线和 连字符,最多64个字符). 32-hex 或 cuid ID 在任务编号中有效 叶;根名注册限制不适用于该叶.

App事件(语法 v2)

hrn:appevent:<root>:<app-slug>:<event-id> 在 App 活动中的一次事件地址 (cor:urn:010:01). 它在根后有两段 hrn:agenttask启用 composeAppEventUrnV2 与事件的身份。 它解释 结束 parseUrnV2,使自己的显示徽章, 正常化的遗产 urn: 前缀为 hrn:,拒绝 #data 碎片。 仅限v2: parseUrn 拒绝它 unknown-type。事件id是一个URN原子(字母/数字, 点,下划线和连字符,最多为64个字符.

赠款(语法v2)

hrn:grant:<root>:<app-slug>:<grant-id> 在一个 App 中处理一个赠款 (cor:urn:010:01,格兰特行;裁定0255项9). 它有两个部分 根后,喜欢 hrn:appevent,以App弹片作为容器和 格兰特的ID作为叶子。 使用 composeGrantUrnV2 与补助金的ID。 它解释 结束 parseUrnV2,使自己的显示徽章, 正常化的遗产 urn: 前缀为 hrn:,拒绝 #data 碎片。 补助金是普通的 URN 原子(字母/数字、点、下划线和连字符,最多64个) 字符);没有只使用UUID的规则。 没有定义其他的分量,所以 这里没有全奥尔格的补助金 现在 parseUrn (v1) 拒绝 hrn:grant 与 unknown-type;这是当前的行为,而不是裁定的拒绝(赠款) 绿地 v2 仍以 Cor:rn:010:01提出.

根登记政策

validateOrgSlug 承认组织名称被点缀和取消。 都一样 validateUserHandle 拒绝32-hex/cuid-形状的根(root-id-shaped)和 保留根词 hrn编号 :urn (单位:千美元)reserved-word-slug) (中文(简体) ). 新手柄还剩 点无所取. 小写、字符集和长度检查仍然有效.

这是创建/重命名政策 。 普通弹壳验证、URN解析和 成分仍然宽大,所以现有存储的URN和ID形任务叶 还来回转接 过时的 org-root-not-dotted 理由是退休.

动作( 语法 v2)

hrn:action:<root>:<agent-slug>:<code> 根后有两段: 团队特工的弹出和动作密码(cor:urn:010:01). 使用 composeActionUrnV2。它通过 parseUrnV2,使其自己的显示 徽章,使遗产正常化 urn: 前缀为 hrn:它没有v1 等值; parseUrn 拒绝它 unknown-type两个部分都遵循 共享的URN原子规则(字母/数字、点、下划线和连字符,最多64个) 字符).

AI 服务配置( 语法 v2)

hrn:aiconf:<owner-root>:<owner-kind>[:<owner-slug>]:<name>: 所有者类型 (准确,小写第一段)决定形状(cor:urn:010:01). org 带 org:<name> (单位:千美元)hrn:aiconf:acme.com:org:default(三); app 财务报告和审定财务报表 agent 带 <kind>:<owner-slug>:<name> (单位:千美元)hrn:aiconf:acme.com:app:mealplan:default) (中文(简体) ). 任意 拒绝其他类型作为 invalid-segment-shape, (中文(简体) ), server 包括:a 哈德伦Server所有者没有URN形式,所以"lib"为它建造了一无所有. 在 保留根 server 财务报告和审定财务报表 platform 配置完全是一个部分 名称( e)hrn:aiconf:server:default),没有物主型相随而来. 一个名字是一个原子 在正常情况下,一个结束于 - 或者说 _ 被拒绝。 以 composeUrnV2('aiconf', root, ...parts)。仅检查 lib 形状: 类型匹配配置的真正所有者是分辨率( hadron- server# 3857) .

许可证

麻省理工学院巴拉贡股份有限公司.

版本与发布记录

@hadron-memory/urn-lib-js 共发布 17 个版本,首次发布于 2026/07/16;过去 12 个月发布了 17 个版本。

版本发布日期距今
0.0.22latest2026/11/143 天前
0.0.182026/11/0116 天前
0.0.172026/10/121 个月前
0.0.152026/08/252 个月前
0.0.132026/08/163 个月前
0.0.122026/08/163 个月前

关于 @hadron-memory/urn-lib-js 的常见问题

@hadron-memory/urn-lib-js 是什么?

硬URN作曲/平面/规范化——固定-公司驱动,与骨灰管-lib-go的跨语言等同

如何安装 @hadron-memory/urn-lib-js?

在项目目录运行 npm install @hadron-memory/urn-lib-js,或使用 pnpm add / yarn add / bun add。

@hadron-memory/urn-lib-js 支持 TypeScript 吗?

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

@hadron-memory/urn-lib-js 支持 ESM 还是 CommonJS?

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

@hadron-memory/urn-lib-js 可以商用吗?

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

@hadron-memory/urn-lib-js 的下载量有多少?

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

@hadron-memory/urn-lib-js 还在维护吗?

最新版本 0.0.22 发布于 2026/11/14(3 天前);至今共发布 17 个版本,其中过去 12 个月发布了 17 个;首次发布于 2026/07/16。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。