Skip to content

README.md

Latest commit

 

History

History
121 lines (91 loc) · 3.92 KB

README.md

File metadata and controls

121 lines (91 loc) · 3.92 KB
Raw

Health Samurai

@health-samurai/aidbox-fhirpath-lsp

A FHIRPath language server that runs entirely in the browser.

npm

No server process, no WebSocket connections — just a Web Worker providing autocompletion, diagnostics, hover information, and go-to-definition for FHIRPath expressions in CodeMirror editors.

Installation

pnpm add @health-samurai/aidbox-fhirpath-lsp

Peer dependencies: react, react-dom, @codemirror/lsp-client, @codemirror/state.

How it works

The LSP server runs in a Web Worker and communicates with CodeMirror via a MessageChannel. FHIR type information (StructureDefinitions) is resolved through the Aidbox client and cached in IndexedDB so subsequent loads are fast.

CodeMirror ←→ LSP Transport (MessageChannel) ←→ Web Worker (FHIRPath LSP)
                                                       ↕
                                                  Aidbox Client → FHIR Server
                                                       ↕
                                                    IndexedDB Cache

Features

  • Autocompletion — Context-aware suggestions for FHIRPath functions, fields, and resource types
  • Diagnostics — Real-time validation and error highlighting
  • Hover — Inline type information and documentation
  • Go-to-definition — Jump to type definitions
  • Find references — Locate all usages
  • Code actions — Quick fixes and suggestions
  • Context type prefix — With a resource type set (e.g. Patient), expressions like name.first() work without the Patient. prefix
  • IndexedDB caching — StructureDefinitions are cached locally to avoid redundant network requests

Usage

React hook

import { useCodeMirrorLsp } from "@health-samurai/aidbox-fhirpath-lsp";
import { AidboxClient } from "@health-samurai/aidbox-client";

function FhirPathEditor() {
  const { extension, setContextType } = useCodeMirrorLsp(client, {
    contextType: "Patient",
    debug: false,
  });

  // `extension` goes into the CodeMirror editor setup
  // `setContextType("Observation")` switches context dynamically
}

Standalone (no React)

import { createCodeMirrorLsp } from "@health-samurai/aidbox-fhirpath-lsp";
import { EditorState } from "@codemirror/state";

const { extension, setContextType } = createCodeMirrorLsp(client, {
  contextType: "Patient",
});

const state = EditorState.create({
  doc: "name.where(use = 'official').first()",
  extensions: [
    // ... other CodeMirror extensions
    extension,
  ],
});

Caching

The wrapCache helper adds IndexedDB caching to resolve/search functions:

import { wrapCache } from "@health-samurai/aidbox-fhirpath-lsp";

const cachedCallbacks = wrapCache({
  resolve: (typeName) => fetchStructureDefinition(typeName),
  search: (kind) => searchStructureDefinitions(kind),
});

LSP methods supported

Method Description
textDocument/completion Autocomplete suggestions
textDocument/hover Type info and documentation
textDocument/definition Jump to definition
textDocument/references Find all references
textDocument/publishDiagnostics Error and warning markers
textDocument/documentSymbol Document outline
textDocument/codeAction Quick fixes

Development

cd packages/aidbox-fhirpath-lsp
pnpm build          # Build library + worker
pnpm tsc:check      # Type-check
pnpm lint:fix       # Lint and format with Biome

The worker is built separately by Vite as a standalone ES module (see vite.config.ts).