A Node.js module for crawling and querying FHIR terminology servers. This module maintains a registry of terminology servers, periodically crawls them to gather capability information, and provides an API to find the best server for specific code systems or value sets.

The module consists of three main components:

• ServerRegistries: Top-level container for all registry data
• ServerRegistry: Individual registry containing multiple servers
• ServerInformation: Server metadata and authoritative designations
• ServerVersionInformation: Version-specific server capabilities
• ServerRow: Flattened representation for API responses
• ServerRegistryUtilities: Helper functions for matching and filtering

• Periodically fetches capability statements from configured servers
• Extracts security models, supported code systems, and value sets
• Handles retries and error recovery
• Maintains current state of all servers

• Provides query endpoints for finding servers
• Ranks servers based on:
  • Authoritative designation
  • Availability (no errors)
  • Recency of successful connection
  • Number of resources available
• Supports filtering by registry, server, version, and resource

npm install

const express = require('express');
const RegistryCrawler = require('./crawler');
const RegistryAPI = require('./api');

// Configure crawler
const crawler = new RegistryCrawler({
  timeout: 30000,
  crawlInterval: 5 * 60 * 1000, // 5 minutes
  registryConfigs: [
    {
      code: 'main',
      name: 'Main Registry',
      servers: [
        {
          code: 'tx1',
          name: 'TX Server',
          authCSList: ['http://loinc.org*'],
          versions: [
            {
              version: '4.0.1',
              address: 'https://tx.fhir.org/r4'
            }
          ]
        }
      ]
    }
  ]
});

// Create API
const api = new RegistryAPI(crawler);

// Set up Express
const app = express();
api.registerRoutes(app);

// Start crawler and server
crawler.start();
app.listen(3000);

Find servers for a code system:

GET /api/query/codesystem?system=http://loinc.org&version=4.0

Find servers for a value set:

GET /api/query/valueset?valueset=http://hl7.org/fhir/ValueSet/observation-codes

Find the best server:

GET /api/best-server/codesystem?url=http://snomed.info/sct

Get statistics:

GET /api/registry/stats

List all registries:

GET /api/registry

Get servers in a registry:

GET /api/registry/main/servers

Trigger manual crawl:

POST /api/admin/crawl

Export/Import data:

GET /api/admin/data
POST /api/admin/data

{
  code: 'main',           // Unique registry identifier
  name: 'Main Registry',  // Display name
  address: 'https://...',  // Registry URL
  authority: 'HL7',       // Managing authority
  servers: [...]          // Array of server configs
}

{
  code: 'tx1',            // Unique server identifier
  name: 'TX Server',      // Display name
  address: 'https://...', // Base server URL
  accessInfo: '...',      // Access information
  authCSList: [           // Authoritative code systems
    'http://loinc.org*',  // Supports wildcards
    'http://snomed.info/sct'
  ],
  authVSList: [...],      // Authoritative value sets
  usageList: ['public'],  // Usage tags
  versions: [...]         // Array of version configs
}

{
  version: '4.0.1',       // FHIR version
  address: 'https://...'  // Version-specific endpoint
}

Servers can be marked as authoritative for specific code systems or value sets. This affects ranking:

• Authoritative servers are always ranked first
• Wildcards are supported (e.g., http://loinc.org*)
• Non-authoritative servers are still returned but ranked lower

Run the test suite:

npm test

Run with Jest (if installed):

npm run test:jest

The crawler saves and loads its state in [data]/registry-data.json

Start development server with auto-reload:

npm run dev

This module is a JavaScript port of a Pascal implementation. Key differences:

The crawler detects the following security models:

• open: No authentication required
• password: Basic authentication
• token: Token-based authentication
• oauth: OAuth 2.0
• smart: SMART on FHIR
• cert: Certificate-based authentication

BSD-3-Clause (matching the original Pascal implementation)