@atomic-ehr/fhir-canonical-manager

中文文档
0.0.29发布于 2026/10/14MITTypeScriptES Module零依赖构建来源已验证近 30 天下载 9350

npm canary [!][npm版本] (https://img.shields.io/npm/v/@原子-ehr/fhir-canonical-man) (中文(简体) )

中文使用文档
文档目录51 节
  1. 特征
  2. 安装
  3. 快速启动
  4. CLI 使用量
  5. 安装
  6. 开始
  7. 图标
  8. CLI 实例
  9. 快速引用
  10. 核心概念
  11. 软件包管理
  12. 资源分辨率
  13. API 参考
  14. CanonicalManager(config)
  15. 补丁和缺陷处理( D)
  16. init(): Promise<void>
  17. resolve(url, options?): Promise<Resource>
  18. resolveEntry(url, options?): Promise<IndexEntry>
  19. read(reference): Promise<Resource>
  20. search(params): Promise<Resource[]>
  21. searchEntries(params): Promise<IndexEntry[]>
  22. packages(): Promise<PackageId[]>
  23. addPackages(packages: string[]): Promise<void>
  24. getSearchParametersForResource(resourceType): Promise<Searc…
  25. destroy(): Promise<void>
  26. CLI 参考
  27. 命令概览
  28. 全球选项
  29. 搜索选项
  30. 前缀搜索
  31. 过滤组合
  32. 输出格式
  33. 目录结构
  34. 缓存格式
  35. 高级使用
  36. 使用多个软件包
  37. 自定义注册配置
  38. 建造 FHIR 验证器
  39. 分析软件包依赖性
  40. 业绩考量
  41. 启动性能
  42. 内存使用
  43. 最佳做法
  44. 处理错误
  45. 类型脚本
  46. 发展
  47. 项目结构
  48. 所需资源
  49. 许可证
  50. 捐款
  51. 发展指导方针

@ 原子- ehr/ fhir- canonical- 管理器

npm canary npm version CI

为 FHIR 资源设置的 TypeScript 软件包管理器,提供犬形URL 分辨率. 这个库帮助您通过一个简单,实用的API来发现,解析和管理 FHIR 软件包及其资源.

特征

  • 🚀 自动软件包管理 - 自动安装和管理FHIR软件包
  • 💾 持续缓存 - Caches 软件包元数据到磁盘,用于快速的后加载
  • 🔍 光学 URL 分辨率 - 将词汇URL解为特定资源版本
  • 📦 多个软件包支持 - 与多个FHIR包同时工作
  • 🎯 灵活搜索 - 按类型、类型、URL、版本或包搜索资源
  • ⚡ 业绩优化 - 有磁盘连续的内存缓存
  • 🛠️ 类型脚本第一 - 全面类型的脚本支持
  • 🩹 软件包处理 - 可编成的补丁、犬科排斥、指数恢复和诊断报告
  • 🖥️ CLI 工具 - 用于软件包管理和资源发现的命令行接口

安装

bun install @atomic-ehr/fhir-canonical-manager
# or
npm install @atomic-ehr/fhir-canonical-manager

快速启动

import { CanonicalManager } from '@atomic-ehr/fhir-canonical-manager';

// Create and initialize the manager
const manager = CanonicalManager({
    packages: ["hl7.fhir.r4.core"],
    workingDir: "tmp/fhir",
    registry: "https://fs.get-ig.org/pkgs/" // optional, default registry
});

await manager.init();

// Resolve and read a resource
const resource = await manager.resolve('http://hl7.org/fhir/StructureDefinition/Patient');
console.log(resource.url); // http://hl7.org/fhir/StructureDefinition/Patient

CLI 使用量

软件包包括一个强大的命令行接口(fcm)用于管理FHIR包并搜索资源而无需写入代码.

安装

# Install globally
npm install -g @atomic-ehr/fhir-canonical-manager

# Or use with npx
npx @atomic-ehr/fhir-canonical-manager

# Or run directly with bunx
bunx @atomic-ehr/fhir-canonical-manager

开始

# Create a new project and initialize with FHIR packages
mkdir my-fhir-project && cd my-fhir-project
fcm init hl7.fhir.r4.core

# Search for resources
fcm search Patient

# Get a specific resource
fcm resolve http://hl7.org/fhir/StructureDefinition/Patient

图标

fcm init

在当前目录中初始化 FHIR 包 .

# Initialize with packages
fcm init hl7.fhir.r4.core [email protected]

# With custom registry
fcm init hl7.fhir.r4.core --registry https://packages.simplifier.net

# Initialize from existing package.json
fcm init

配置存储于 package.json数字 :

{
  "fcm": {
    "packages": ["hl7.fhir.r4.core", "[email protected]"],
    "registry": "https://fs.get-ig.org/pkgs/"
  }
}

fcm list

列出已安装的软件包或资源 .

# List all packages
fcm list

# List resources in a package
fcm list hl7.fhir.r4.core

# Filter by type
fcm list hl7.fhir.r4.core --type StructureDefinition

# Output as JSON
fcm list --json

搜索具有高级过滤和前缀匹配能力的资源.

基本用途:

# Search by URL pattern
fcm search Patient

# Prefix search - space-separated terms match URL components
fcm search str def pat  # Matches: StructureDefinition/Patient

资源类型快捷键 :

fcm search -sd          # All StructureDefinitions
fcm search -cs          # All CodeSystems
fcm search -vs          # All ValueSets
fcm search -sd patient  # Patient-related StructureDefinitions

高级过滤 :

# Filter by type (-t)
fcm search -t Extension              # All Extensions
fcm search -t Patient                # Resources with type="Patient"
fcm search -sd -t Patient            # Patient StructureDefinition specifically

# Filter by kind (-k)
fcm search -k resource               # All resources (Patient, Observation, etc.)
fcm search -k complex-type           # All complex types (HumanName, Address, etc.)
fcm search -k primitive-type         # All primitive types (string, boolean, etc.)

# Combine filters
fcm search -t Extension -k complex-type  # All Extension complex types
fcm search -sd pat -t Extension          # Patient-related Extensions

# Filter by package
fcm search allergy --package hl7.fhir.us.core

# Output as JSON
fcm search Patient --json

输出格式 : 默认情况下,结果以格式显示为每行1:

url, {"resourceType":"...", "kind":"...", "type":"..."}

示例输出 :

http://hl7.org/fhir/StructureDefinition/Patient, {"resourceType":"StructureDefinition","kind":"resource","type":"Patient"}

fcm resolve

获取资源 .

# Display resource
fcm resolve http://hl7.org/fhir/StructureDefinition/Patient

# Save to file
fcm resolve http://hl7.org/fhir/ValueSet/administrative-gender > gender.json

# Show only specific fields
fcm resolve http://hl7.org/fhir/StructureDefinition/Patient --fields url,type,kind

fcm searchparam

显示特定 FHIR 资源类型的搜索参数.

# Display search parameters for Patient resource
fcm searchparam Patient

# Output as JSON
fcm searchparam Observation --format json

# Export as CSV for spreadsheet analysis
fcm searchparam Encounter --format csv > encounter-params.csv

输出格式 :

  • 图表 (默认): 以多行格式显示每个参数,并有完整数据
  • 乔森: 输出为 JSON 阵列, 有代码、 类型、 表达式和 URL 字段
  • (单位:千美元): 导出为用于电子表格分析的 CSV

示例输出(表格式) :

Code:       active
Type:       token
Expression: Patient.active
URL:        http://hl7.org/fhir/SearchParameter/Patient-active
---
Code:       address
Type:       string
Expression: Patient.address | Person.address | Practitioner.address |
            RelatedPerson.address
URL:        http://hl7.org/fhir/SearchParameter/individual-address
---
Code:       identifier
Type:       token
Expression: Patient.identifier
URL:        http://hl7.org/fhir/SearchParameter/Patient-identifier
---

Total: 29 search parameters

CLI 实例

# Set up a new FHIR project
mkdir my-fhir-project && cd my-fhir-project
fcm init hl7.fhir.r4.core

# Search for Observation-related resources
fcm search observation

# Get a specific resource and save it
fcm resolve http://hl7.org/fhir/StructureDefinition/Observation > observation.json

# List all ValueSets in JSON format
fcm search --type ValueSet --json > valuesets.json

快速引用

任务命令
启动项目fcm init hl7.fhir.r4.core
列表软件包fcm list
列表软件包资源fcm list hl7.fhir.r4.core
搜索所有资源fcm search
按名称搜索fcm search Patient
以前缀搜索fcm search str def pat
所有结构定义fcm search -sd
所有代码系统fcm search -cs
所有值设置fcm search -vs
按类型过滤fcm search -t Extension
按类型过滤fcm search -k resource
组合过滤器fcm search -sd -t Patient
获取资源fcm resolve <url>
获取搜索参数fcm searchparam Patient
导出为 JSONfcm search --json
导出参数为 CSVfcm searchparam Patient --format csv
帮助fcm --help

核心概念

软件包管理

管理器自动处理 FHIR 包安装 :

  1. 创建工作目录, 如果它不存在
  2. 初始化 a package.json 扶养管理
  3. 使用 npm 安装指定的 FHIR 包
  4. 扫描软件包 .index.json 文件
  5. 构建所有资源的内在索引
  6. 持久缓存到 .fcm/cache/index.json

资源分辨率

资源由下列机构确定:

  • 目录 URL: FHIR 资源的唯一标识符
  • 参考编号: 基于软件包和文件路径的不透明、决定性散列
  • 软件包上下文: 可选软件包名称/版本限制

API 参考

CanonicalManager(config)

创建新实例的 Cononic 管理器 .

interface Config {
  packages: string[];               // FHIR packages to install (e.g., ["hl7.fhir.r4.core"])
  workingDir: string;               // Directory for packages and cache
  registry?: string;                // NPM registry URL (optional)
  dropCache?: boolean;              // Rebuild the cache instead of loading it from disk
  patches?: Partial<Patches>;       // Per-phase handler lists (see "Patches & defect handling")
  packageIndex?: PackageIndexMode;  // How to treat shipped .index.json files (default "use")
  /** @deprecated use `patches` — equivalent to package/resource handlers */
  preprocessPackage?: (ctx: PreprocessContext) => PreprocessContext;
  /** @deprecated use `packageIndex` */
  ignorePackageIndex?: boolean;
}

示例

const manager = CanonicalManager({
    packages: [
        "hl7.fhir.r4.core",
        "[email protected]"
    ],
    workingDir: "./fhir-packages",
    registry: "https://fs.get-ig.org/pkgs/"
});

补丁和缺陷处理( D)

真实世界 FHIR 包船缺陷(缺少依赖性,犬类 URL 类型, 无法使用的值设置绑定、 交叉版本类型引用、 腐败 .index.json) (中文(简体) ). CanonicalManager 揭露出三个把柄在他们周围工作.

packageIndex - 如何对待装运货物 .index.json

type PackageIndexMode = "use" | "recover" | "regenerate";
  • "use" (默认) : 信任已发送的索引; 仅在目录是时扫描目录 缺席。 腐败指数是 警告( e) 大约但不在周围工作(比对先前的行为).
  • "recover": 使用索引,但返回到 每个包装 目录扫描时 它腐败或不完整(不可解析,或磁盘上缺少的引用文件).
  • "regenerate":忽略已运出索引并总是扫描.

ignorePackageIndex 是一个被贬值的别名( )true → "regenerate", (中文(简体) ), false → "use"(三); 设置它和 packageIndex 掷出.

patches ——可相容的转变和排除

patches 是一个单 Patches 可选对象 每阶段处理者名单, (中文(简体) ), 按每个处理器转换的值键—— packageJson, (中文(简体) ), indexEntry,以及 fhirResource。 。 。 . 每个处理器收到其包ID、该值和诊断槽,然后返回 a 转换值或 undefined 以至无;处于相位的处理器从左到右运行。 这个 indexEntry 处理器也可以返回 null 改为 丢入 条子(它从未进入) 页:1 仅提供您需要的阶段; 已贬值 preprocessPackage 现附上 在您的包 Json/fhir 资源处理器之后 .

import type { PackagePatch } from "@atomic-ehr/fhir-canonical-manager";

// A handler is (pkg, value, report) => transformedValue | undefined.
// Fix a package's declared version at the package phase:
const fixVersion: PackagePatch = (pkg, packageJson) => ({ ...packageJson, version: "1.2.3" });

// patches: { packageJson: [fixVersion] }

捆绑的补丁帮助从 @atomic-ehr/fhir-canonical-manager/patch 子路径 :

  • 范围界定组合器 —— 说 inPackage(match, [handlers]) 仅应用于匹配包(名称, {name, version},或上游)和巢; inResource(url, [handlers]) 将资源处理器扩展到一个峡谷.
  • 明确修正 (单位:千美元)packageJson 页:1 ensureDependency(deps) 使包在给定的版本中声明每个依赖性(添加缺失的,调整不匹配的,从不增加包本身); renamePackage(from, to) 修补一个字形显示的名称.
  • 资源修正 (单位:千美元)fhirResource 页:1 replaceText(from, to) 替换整个串行体的字符串(typo'd Canonics,错误的参考目标,无法使用的 ValueSet 绑定值——范围!); ensureCodes(url, codes) 在不触及现有概念的情况下,将缺少的代码附加到代码系统中; patchElement(elementId, (element) => element) 重写一个结构定义要素(snapshot and difference)——例如拓宽或缩小其参考目标;以 inResource(url, [...])。 。 。 .
  • 索引修正 (单位:千美元)indexEntry 页:1 excludeCanonical({package?, url, reason}) 从索引中去掉条条(产出) 财务报告和审定财务报表 将理由记录在 report()。 。 。 .
  • 接线 —— 说 applyPatches, (中文(简体) ), matchPackage。 。 。 .

譬如说, excludeCanonical 丢弃条条形体( 例如, R4 扩展名, 引用 R5 唯一类型) :

import { CanonicalManager } from "@atomic-ehr/fhir-canonical-manager";
import { excludeCanonical } from "@atomic-ehr/fhir-canonical-manager/patch";

const manager = CanonicalManager({
    packages: ["hl7.fhir.uv.extensions.r4"],
    workingDir: "./fhir-packages",
    patches: {
        indexEntry: [
            excludeCanonical({
                url: "http://hl7.org/fhir/StructureDefinition/specimen-additive",
                reason: "Uses CodeableReference, not available in R4",
            }),
        ],
    },
});

缓存符 : 上盘索引记录了包船的内容,所以管理者使用 不同 patches 可共享工作目录.

  • indexEntry 财务报告和审定财务报表 fhirResource 运行每个负载和每个读数——自由更改它们.
  • packageJson 也在安装和扫描时间运行,并且是缓存软件包的一部分 元数据,所以改变它仍然需要 dropCache: true (或经清理的工作目录).

report() - 你为什么看见你看到的

const report = manager.report(); // ReportEntry[]
//   { kind: "index-recovery"; package; reason; recovered }
//   | { kind: "exclusion"; package; url; reason }
//   | { kind: "deprecation"; message }

返回每个缺陷处理行动的记录(索引回收、排除、, 被贬损通知),因此下游工具可以解释一个犬科动物之所以缺失或被改变的原因.

缓存运行提醒 : exclusion 每次运行、缓存或不记录条目,因为 页:1 indexEntry 相位运行在每个负载. index-recovery 条目仅在 大楼 索引,所以一个缓存的运行报告 对他们来说什么都没有——使用 dropCache: true 改为 如果您需要了解为什么一个软件包的索引被修复,则重建.

init(): Promise<void>

初始化管理器 。 这种方法 :

  • 确保工作目录存在
  • 创建 .fcm/cache 目录
  • 检查已存在的缓存
  • 如果没有缓存:安装软件包并构建索引
  • 如果缓存存在: 从磁盘装入( 快速启动)
await manager.init();

resolve(url, options?): Promise<Resource>

直接向 FHIR 资源解析 Canonic URL .

// Simple resolution
const patient = await manager.resolve(
    'http://hl7.org/fhir/StructureDefinition/Patient'
);

// With package constraint
const patient = await manager.resolve(
    'http://hl7.org/fhir/StructureDefinition/Patient',
    { package: 'hl7.fhir.r4.core' }
);

// With version constraint
const patient = await manager.resolve(
    'http://hl7.org/fhir/StructureDefinition/Patient',
    { version: '4.0.1' }
);

resolveEntry(url, options?): Promise<IndexEntry>

将条形URL确定为索引条目(只有元数据).

const entry = await manager.resolveEntry(
    'http://hl7.org/fhir/StructureDefinition/Patient'
);

console.log(entry);
// {
//   id: "opaque-reference-id",
//   resourceType: "StructureDefinition",
//   url: "http://hl7.org/fhir/StructureDefinition/Patient",
//   version: "4.0.1",
//   kind: "resource",
//   type: "Patient",
//   package: { name: "hl7.fhir.r4.core", version: "4.0.1" }
// }

read(reference): Promise<Resource>

使用其引用读取资源.

const entry = await manager.resolveEntry(url);
const resource = await manager.read(entry);

search(params): Promise<Resource[]>

搜索并返回全部资源匹配标准 .

// Get all StructureDefinitions
const structures = await manager.search({
    type: 'StructureDefinition'
});

// Get all resources of kind "resource"
const resources = await manager.search({
    kind: 'resource'
});

// Complex search
const valuesets = await manager.search({
    type: 'ValueSet',
    package: { name: 'hl7.fhir.r4.core', version: '4.0.1' }
});

searchEntries(params): Promise<IndexEntry[]>

搜索并返回索引条目(仅元数据).

// Find all CodeSystems
const entries = await manager.searchEntries({
    type: 'CodeSystem'
});

// Find by URL
const entries = await manager.searchEntries({
    url: 'http://hl7.org/fhir/StructureDefinition/Patient'
});

搜索参数 :

  • kind?: string - 资源类型(例如“资源”、“数据类型”、“原始类型”)
  • url?: string - Canonical URL(精确匹配)
  • type?: string - 资源类型(例如“定义”、“价值”)
  • version?: string - 资源版本
  • package?: PackageId - 按软件包名称和版本过滤

packages(): Promise<PackageId[]>

列出所有已装入的软件包.

const packages = await manager.packages();
// [
//   { name: "hl7.fhir.r4.core", version: "4.0.1" },
//   { name: "hl7.fhir.us.core", version: "5.0.1" }
// ]

addPackages(packages: string[]): Promise<void>

运行时添加(并在需要时安装)额外的FHIR包.

await manager.addPackages(
    "[email protected]",
    "hl7.fhir.us.davinci-drug-formulary"
);
  • 接受一个或多个包指定符: 名称或名称@ version
  • 如果管理器尚未启用, 则会附加并正常 init() 安装流程控点
  • 已显示的软件包被跳过( 专有)
  • 安装了新的, node_modules 重新扫描,缓存持续
  • 资源立即提供给 resolve, (中文(简体) ), search, CLI 命令

回返情况: Promise<void> (索引更新时的解析)

getSearchParametersForResource(resourceType): Promise<SearchParameter[]>

获取适用于特定 FHIR 资源类型的所有搜索参数.

// Get search parameters for Patient resource
const searchParams = await manager.getSearchParametersForResource('Patient');

// Each parameter contains FHIR SearchParameter fields
searchParams.forEach(param => {
    console.log(`${param.code}: ${param.type} - ${param.expression}`);
});

// Example output:
// identifier: token - Patient.identifier
// name: string - Patient.name
// birthdate: date - Patient.birthDate
// gender: token - Patient.gender

返回所有FHIR字段保存的搜索参数阵列资源,包括:

  • url: 搜索参数的分类 URL
  • code: 查询中使用的搜索参数名称
  • type: 参数类型(指针、字符串、日期、参考等)
  • expression: FHIRPath 表达式
  • base: 该参数适用于资源类型的矩阵
  • 额外的 FHIR 搜索参数字段

destroy(): Promise<void>

清理资源并清除内存的缓存(磁盘缓存持续存在).

await manager.destroy();

CLI 参考

这个 fcm 命令行接口提供了全面的FHIR资源管理能力.

命令概览

命令说明
fcm init [packages...]在当前目录中初始化 FHIR 包
fcm list [package]列表软件包或资源
fcm search [terms...]使用高级过滤器搜索资源
fcm resolve <url>按犬类 URL 获取资源
fcm searchparam <resourceType>显示资源类型的搜索参数

全球选项

  • --help, (中文(简体) ), -h - 显示帮助信息
  • --version, (中文(简体) ), -v - 显示版本编号
  • --json - 作为JSON的产出结果(可供列表、搜索、解析)

搜索选项

选项说明示例
-sd过滤到结构定义fcm search -sd
-cs过滤到代码系统fcm search -cs
-vs过滤到值Setsfcm search -vs
-t <type>按类型字段过滤fcm search -t Extension
-k <kind>按类型字段过滤fcm search -k resource
--type <resourceType>通过资源过滤Typefcm search --type ValueSet
--package <name>按软件包过滤fcm search --package hl7.fhir.us.core

搜索命令支持智能前缀匹配. 当您提供多个空间分隔术语时, 每个术语会被匹配为 URL 组件的前缀 :

# Search for "str" AND "def" AND "pat" as prefixes
fcm search str def pat

# This matches URLs like:
# - http://hl7.org/fhir/StructureDefinition/Patient
# - http://hl7.org/fhir/StructureDefinition/PatientContact

过滤组合

过滤器可以合并进行精确的搜索 :

# Find all Extension complex types
fcm search -t Extension -k complex-type

# Find Patient-related Extensions
fcm search -sd pat -t Extension

# Find all primitive types in US Core
fcm search -k primitive-type --package hl7.fhir.us.core

输出格式

默认( 单行) :

http://hl7.org/fhir/StructureDefinition/Patient, {"resourceType":"StructureDefinition","kind":"resource","type":"Patient"}

JSON 格式 :

fcm search Patient --json

返回完整的索引 Entry 对象为 JSON 阵列.

目录结构

初始化后,您的工作目录将包含:

workingDir/
├── package.json          # NPM package file
├── node_modules/         # Installed FHIR packages
│   ├── hl7.fhir.r4.core/
│   │   ├── package.json
│   │   ├── .index.json   # FHIR resource index
│   │   └── *.json        # FHIR resources
│   └── .../
└── .fcm/
    └── cache/
        └── index.json    # Cached index for fast startup

缓存格式

缓存作为JSON文件被存储,其结构如下:

{
  entries: {
    "http://hl7.org/fhir/StructureDefinition/Patient": [
      {
        id: "hash-based-id",
        resourceType: "StructureDefinition",
        url: "http://hl7.org/fhir/StructureDefinition/Patient",
        version: "4.0.1",
        kind: "resource",
        type: "Patient",
        package: { name: "hl7.fhir.r4.core", version: "4.0.1" }
      }
    ]
  },
  packages: {
    "hl7.fhir.r4.core": {
      id: { name: "hl7.fhir.r4.core", version: "4.0.1" },
      path: "/path/to/node_modules/hl7.fhir.r4.core",
      canonical: "http://hl7.org/fhir",
      fhirVersions: ["4.0.1"]
    }
  },
  references: {
    "hash-based-id": {
      packageName: "hl7.fhir.r4.core",
      packageVersion: "4.0.1",
      filePath: "/path/to/resource.json",
      resourceType: "StructureDefinition",
      url: "http://hl7.org/fhir/StructureDefinition/Patient",
      version: "4.0.1"
    }
  }
}

高级使用

使用多个软件包

const manager = CanonicalManager({
    packages: [
        "hl7.fhir.r4.core",
        "[email protected]",
        "hl7.fhir.us.davinci-drug-formulary"
    ],
    workingDir: "./fhir-packages"
});

await manager.init();

// Search across all packages
const allValueSets = await manager.search({ type: 'ValueSet' });

// Search in specific package
const usCoreProfiles = await manager.search({
    type: 'StructureDefinition',
    package: { name: 'hl7.fhir.us.core', version: '5.0.1' }
});

自定义注册配置

// Use the default FHIR package registry
const manager = CanonicalManager({
    packages: ["hl7.fhir.r4.core"],
    workingDir: "./fhir-packages",
    registry: "https://fs.get-ig.org/pkgs/"
});

// Use a custom NPM registry
const manager = CanonicalManager({
    packages: ["hl7.fhir.r4.core"],
    workingDir: "./fhir-packages",
    registry: "https://my-private-registry.com"
});

建造 FHIR 验证器

async function validateResource(resource: any, manager: CanonicalManager) {
    // Get the profile URL from the resource
    const profileUrl = resource.meta?.profile?.[0];
    if (!profileUrl) {
        throw new Error('No profile specified');
    }

    // Resolve the StructureDefinition
    const profile = await manager.resolve(profileUrl);

    // Validate resource against profile
    // ... validation logic ...
}

分析软件包依赖性

async function analyzeValueSetDependencies(manager: CanonicalManager) {
    // Get all ValueSets
    const valueSets = await manager.search({ type: 'ValueSet' });

    const dependencies = new Map<string, Set<string>>();

    for (const vs of valueSets) {
        const vsPackage = vs.package?.name || 'unknown';

        // Check compose.include for external code systems
        if (vs.compose?.include) {
            for (const include of vs.compose.include) {
                if (include.system) {
                    try {
                        const cs = await manager.resolve(include.system);
                        const csPackage = cs.package?.name || 'unknown';

                        if (csPackage !== vsPackage) {
                            if (!dependencies.has(vsPackage)) {
                                dependencies.set(vsPackage, new Set());
                            }
                            dependencies.get(vsPackage)!.add(csPackage);
                        }
                    } catch {
                        // External code system not in our packages
                    }
                }
            }
        }
    }

    return dependencies;
}

业绩考量

启动性能

  • 首发: 由于软件包安装和索引构建而放慢
  • 随后运行: 从磁盘缓存加载快速启动
  • 缓存无效: 删除 .fcm/cache 强制重建

内存使用

  • 所有索引条目都保留在内存,以快速查找
  • 资源内容按需加载
  • 对于大型软件包,请考虑内存要求

最佳做法

  1. 重用管理器实例: 创建一次, 使用多次
  2. 使用 searchEntries() 元数据: 比 search() 当你不需要全部资源时
  3. 指定软件包限制: 当知道软件包时更快的解析度
  4. 缓存工作目录: 应用程序实例之间的共享

处理错误

管理器丢出错误 :

  • 未初始化:呼叫 init() 采用其他方法之前
  • 找不到资源 : Canonical URL 不存在
  • 无效的引用: 引用ID无效
  • 软件包安装失败:网络或登记问题
try {
    const resource = await manager.resolve('http://invalid.url/Resource');
} catch (error) {
    console.error('Failed to resolve:', error.message);
}

类型脚本

interface Reference {
    id: string;              // Opaque identifier
    resourceType: string;    // FHIR resource type
}

interface PackageId {
    name: string;           // Package name
    version: string;        // Package version
}

interface IndexEntry extends Reference {
    indexVersion: number;   // Index format version
    kind?: string;         // resource, datatype, primitive, etc.
    url?: string;          // Canonical URL
    type?: string;         // Specific type (e.g., "Patient")
    version?: string;      // Resource version
    package?: PackageId;   // Source package
}

interface Resource extends Reference {
    url?: string;          // Canonical URL
    version?: string;      // Resource version
    [key: string]: any;    // Other FHIR properties
}

interface SourceContext {
    id?: string;
    package?: PackageId;
    url?: string;
    path?: string;
}

发展

要安装依赖性 :

bun install

进行测试:

bun test

举例来说:

bun run example.ts

项目结构

fhir-canonical-manager/
├── src/
│   ├── index.ts          # Core library implementation
│   ├── compat.ts         # Bun/Node.js compatibility layer
│   └── cli/              # CLI implementation
│       ├── index.ts      # CLI entry point
│       ├── init.ts       # Init command
│       ├── list.ts       # List command
│       ├── search.ts     # Search command
│       └── resolve.ts    # Resolve command
├── test/
│   ├── index.test.ts     # Core library tests
│   ├── cli.test.ts       # CLI unit tests
│   └── cli-integration.test.ts # CLI integration tests
├── dist/                 # Compiled output (generated)
├── example.ts            # Usage example
├── package.json
├── tsconfig.json
└── README.md

所需资源

  • 节点.js 18+或 Bun 1.0+
  • 类型脚本 5.0+
  • 软件包安装的网络访问

许可证

麻省理工学院

捐款

欢迎捐款! 请随意提交拉力请求.

发展指导方针

  1. 单一文件中的所有代码 : src/index.ts
  2. 功能编程风格
  3. 除Node.js内建外,没有外部依赖关系
  4. 综合测试 test/index.test.ts
  5. 用 API 修改更新 README.md

版本与发布记录

@atomic-ehr/fhir-canonical-manager 共发布 98 个版本,首次发布于 2025/07/31;过去 12 个月发布了 69 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
0.0.29latest2026/10/1424 天前
0.0.29-canary.20261014123756.2929e7dcanary2026/10/1424 天前
0.0.28-canary.20261014111502.f48d9d02026/10/1424 天前
0.0.282026/09/251 个月前
0.0.28-canary.20260925083515.c7f09842026/09/251 个月前
0.0.27-canary.20260925083243.c157bdb2026/09/251 个月前

关于 @atomic-ehr/fhir-canonical-manager 的常见问题

@atomic-ehr/fhir-canonical-manager 是什么?

[!][npm版本] (https://img.shields.io/npm/v/@原子-ehr/fhir-canonical-man) (中文(简体) )

如何安装 @atomic-ehr/fhir-canonical-manager?

在项目目录运行 npm install @atomic-ehr/fhir-canonical-manager,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:typescript(^5)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。它还提供命令行工具 fcm,可以用 npx fcm 直接运行。

@atomic-ehr/fhir-canonical-manager 支持 TypeScript 吗?

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

@atomic-ehr/fhir-canonical-manager 支持 ESM 还是 CommonJS?

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

@atomic-ehr/fhir-canonical-manager 可以商用吗?

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

@atomic-ehr/fhir-canonical-manager 的下载量有多少?

根据 npm 官方下载统计,@atomic-ehr/fhir-canonical-manager 在 2026/10/07 – 2026/11/05 这 30 天内被下载 9,350 次,日均约 312 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@atomic-ehr/fhir-canonical-manager 还在维护吗?

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