fhir-runtime 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,211 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] - 2026-03-04
+
+### Changed
+
+- **Package renamed** from `@medxai/fhir-core` to `fhir-runtime`
+- **License changed** from Apache-2.0 to MIT
+- Updated all documentation to reflect new package name and branding
+- Updated package.json metadata (repository, bugs, homepage)
+
+### Added
+
+#### Testing & Quality Assurance
+
+- **US Core IG Verification Suite**
+  - 70 US Core StructureDefinitions successfully parsed
+  - 55 resource profiles converted to CanonicalProfiles
+  - 15 extension definitions processed
+  - Official examples validated against declared profiles
+  - FHIRPath evaluation on US Core resources
+  - Profile-to-example matching verification
+
+- **Comprehensive Stress Testing**
+  - Malformed input resilience testing
+  - Deep nesting stress tests
+  - Large payload stress tests (bundle processing)
+  - FHIRPath complexity stress tests
+  - Memory pressure tests (batch processing)
+  - Concurrent safety tests (parallel operations)
+
+- **Test Coverage Expansion**
+  - Expanded to 2,400+ tests across 45 test files
+  - 100% pass rate maintained
+  - All 6 modules fully tested
+
+#### Documentation
+
+- Created new v0.2 API reference (`docs/api/fhir-runtime-api-v0.2.md`)
+- Created new v0.2 capability contract (`docs/specs/engine-capability-contract-v0.2.md`)
+- Updated technical overview with testing section
+- Completely rewrote README.md with:
+  - Production-ready presentation
+  - Quick start examples
+  - Comprehensive testing documentation
+  - Architecture diagrams
+  - Use cases and performance notes
+
+### Fixed
+
+- No bug fixes in this release (documentation and testing focus)
+
+### Deprecated
+
+- Old package name `@medxai/fhir-core` (use `fhir-runtime` instead)
+- v0.1 documentation files (use v0.2 versions)
+
+### Security
+
+- No security changes in this release
+
+---
+
+## [0.1.0] - 2026-03-04 (Initial Release as @medxai/fhir-core)
+
+### Added
+
+#### Core Capabilities
+
+- **FHIR R4 JSON Parsing & Serialization**
+  - Full support for all FHIR R4 resource types
+  - Primitive `_element` split handling
+  - Choice type `[x]` dispatch and tagging
+  - Null alignment in sparse arrays
+  - StructureDefinition-specific parsing (37 ElementDefinition fields)
+
+- **Context & Registry Management**
+  - StructureDefinition registry with inheritance resolution
+  - Pluggable loader architecture (MemoryLoader, FileSystemLoader, CompositeLoader)
+  - Bundle loading (profiles-resources, profiles-types)
+  - 73 bundled FHIR R4 core definitions
+  - InnerType extraction for BackboneElement schemas
+
+- **Snapshot Generation**
+  - HAPI-semantically-equivalent snapshot generation
+  - Base-driven merge algorithm
+  - Constraint tightening validation
+  - Slicing support (extension, type, value)
+  - Circular dependency detection
+  - Validated against 35 HAPI-generated fixtures (100% pass rate)
+
+- **Profile-Based Validation**
+  - 9 structural validation rules:
+    - Cardinality (min/max)
+    - Required elements
+    - Type compatibility
+    - Fixed values
+    - Pattern values
+    - Choice types
+    - Reference targets
+    - Slicing discriminators
+    - FHIRPath invariants
+  - Snapshot-driven validation using CanonicalProfile
+  - Structured result objects (no-throw contract)
+
+- **FHIRPath Expression Engine**
+  - 60+ standard FHIRPath functions
+  - Pratt parser with operator precedence
+  - AST caching (LRU, 128 entries)
+  - Support for FHIRPath §5.1–5.9, §6.3, §6.5
+  - FHIR-specific functions (resolve, extension, hasValue)
+  - Variable scoping ($this, $index, $total)
+
+#### Architecture & Design
+
+- **Zero runtime dependencies** — Pure TypeScript implementation
+- **Structured results over exceptions** — ParseResult, SnapshotResult, ValidationResult
+- **Deterministic** — Same input always produces same output
+- **Type-safe** — Full TypeScript definitions for all FHIR R4 types
+- **Modular architecture** — 6 independent modules (model, parser, context, profile, validator, fhirpath)
+
+#### Package Details
+
+- ESM + CJS module formats
+- Full TypeScript type declarations
+- 211 public exports across 6 modules
+- Node.js ≥18.0.0 support
+- TypeScript 5.9 compatibility
+
+---
+
+## Version Comparison
+
+### API Compatibility
+
+- **v0.2.0 is fully compatible with v0.1.0** — No breaking changes
+- All 211 exports remain unchanged
+- Only package name and license changed
+
+### Migration from v0.1.0 to v0.2.0
+
+```diff
+- import { parseFhirJson } from '@medxai/fhir-core';
++ import { parseFhirJson } from 'fhir-runtime';
+```
+
+```diff
+- npm install @medxai/fhir-core
++ npm install fhir-runtime
+```
+
+---
+
+## Release Notes
+
+### v0.2.0 Highlights
+
+This release focuses on **production readiness** through extensive testing and documentation improvements:
+
+- ✅ **2,400+ tests** — Comprehensive test coverage across all modules
+- ✅ **US Core IG verified** — Real-world Implementation Guide validation
+- ✅ **Stress tested** — Resilience under extreme conditions
+- ✅ **Zero dependencies** — No external runtime dependencies
+- ✅ **HAPI-equivalent** — 100% snapshot fixture compatibility
+
+### v0.1.0 Highlights
+
+Initial release providing complete FHIR R4 structural capabilities:
+
+- ✅ **Parsing** — Full FHIR R4 JSON support
+- ✅ **Validation** — 9 structural rules + FHIRPath invariants
+- ✅ **Snapshot generation** — HAPI-equivalent differential expansion
+- ✅ **FHIRPath** — 60+ functions with Pratt parser
+- ✅ **Context management** — Registry, loaders, inheritance resolution
+
+---
+
+## Roadmap
+
+### Planned for v0.3.0
+
+- Terminology service integration (ValueSet expansion, code validation)
+- Additional IG support (more Implementation Guides verified)
+- Performance optimizations
+- Enhanced error messages
+
+### Planned for v1.0.0
+
+- Stable API freeze
+- Long-term support commitment
+- Production deployment guidelines
+- Enterprise support options
+
+---
+
+## Links
+
+- **Repository**: https://github.com/medxaidev/medxai
+- **Issues**: https://github.com/medxaidev/medxai/issues
+- **Documentation**: [docs/](docs/)
+- **License**: [MIT](LICENSE)
+
+---
+
+[0.2.0]: https://github.com/medxaidev/medxai/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/medxaidev/medxai/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jason fang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,261 @@
+# fhir-runtime
+
+> **A production-ready FHIR R4 runtime engine for TypeScript/Node.js**
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue)](https://www.typescriptlang.org/)
+[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18.0.0-green)](https://nodejs.org/)
+[![Tests](https://img.shields.io/badge/Tests-2400%2B%20passing-brightgreen)]()
+
+`fhir-runtime` is a **structural FHIR R4 engine** that provides comprehensive capabilities for parsing, validating, and manipulating FHIR resources — without requiring a running FHIR server, database, or external terminology service.
+
+Designed as a pure runtime layer with **zero dependencies**, it's suitable for embedding in servers, CLIs, web applications, or custom platforms.
+
+---
+
+## ✨ Features
+
+### Core Capabilities
+
+- **🔍 FHIR R4 JSON Parsing** — Full support for primitives, choice types, extensions
+- **✅ Profile-Based Validation** — 9 structural validation rules + FHIRPath invariants
+- **📸 Snapshot Generation** — HAPI-equivalent differential expansion
+- **🧮 FHIRPath Engine** — 60+ functions, Pratt parser with AST caching
+- **📦 Bundle Loading** — Load FHIR specification bundles and IGs
+- **🔄 Context Management** — Registry, loaders, inheritance resolution
+- **🎯 InnerType Extraction** — BackboneElement schema for UI/validation
+
+### Quality & Testing
+
+- **2,400+ tests** across 45 test files — 100% passing
+- **US Core IG verified** — 70 StructureDefinitions, 55 profiles validated
+- **HAPI-equivalent** — 35/35 snapshot fixtures match HAPI output
+- **Stress tested** — Malformed input, deep nesting, large payloads, concurrency
+- **Zero dependencies** — Pure TypeScript, no external runtime deps
+- **Type-safe** — Full TypeScript definitions for all FHIR R4 types
+
+---
+
+## 📦 Installation
+
+```bash
+npm install fhir-runtime
+```
+
+**Requirements:**
+
+- Node.js ≥18.0.0
+- TypeScript ≥5.0 (for TypeScript projects)
+
+---
+
+## 🚀 Quick Start
+
+### Parse a FHIR Resource
+
+```typescript
+import { parseFhirJson } from "fhir-runtime";
+
+const result = parseFhirJson(`{
+  "resourceType": "Patient",
+  "id": "example",
+  "name": [{ "family": "Doe", "given": ["John"] }]
+}`);
+
+if (result.success) {
+  console.log(result.data.resourceType); // "Patient"
+  console.log(result.data.name[0].family); // "Doe"
+}
+```
+
+### Validate Against a Profile
+
+```typescript
+import {
+  StructureValidator,
+  buildCanonicalProfile,
+  parseStructureDefinition,
+} from "fhir-runtime";
+
+// Load a profile
+const sdResult = parseStructureDefinition(profileJson);
+const profile = buildCanonicalProfile(sdResult.data);
+
+// Validate a resource
+const validator = new StructureValidator();
+const result = validator.validate(patientResource, profile);
+
+if (!result.valid) {
+  result.issues.forEach((issue) => {
+    console.error(`${issue.severity}: ${issue.message} at ${issue.path}`);
+  });
+}
+```
+
+### Generate a Snapshot
+
+```typescript
+import { FhirContextImpl, SnapshotGenerator } from "fhir-runtime";
+
+const ctx = new FhirContextImpl({ loaders: [] });
+await ctx.preloadCoreDefinitions();
+
+const generator = new SnapshotGenerator(ctx, { generateCanonical: true });
+const result = await generator.generate(myProfile);
+
+if (result.success) {
+  console.log(
+    `Generated ${result.structureDefinition.snapshot.element.length} elements`,
+  );
+}
+```
+
+### Evaluate FHIRPath
+
+```typescript
+import { evalFhirPath, evalFhirPathBoolean } from "fhir-runtime";
+
+const patient = { resourceType: "Patient", name: [{ given: ["John"] }] };
+
+const names = evalFhirPath("Patient.name.given", patient);
+// → ['John']
+
+const hasOfficial = evalFhirPathBoolean(
+  "name.where(use='official').exists()",
+  patient,
+);
+// → false
+```
+
+---
+
+## 📚 Documentation
+
+- **[Technical Overview](docs/overview/fhir-runtime-overview.md)** — Architecture, design principles, capabilities
+- **[API Reference](docs/api/fhir-runtime-api-v0.2.md)** — Complete API documentation (211 exports)
+- **[Capability Contract](docs/specs/engine-capability-contract-v0.2.md)** — Behavioral guarantees, error semantics
+
+---
+
+## 🧪 Testing & Quality
+
+### Test Coverage
+
+```
+✅ 2,400+ tests across 45 test files
+✅ 100% pass rate on HAPI snapshot fixtures (35/35)
+✅ All 6 modules fully tested (parser, context, profile, validator, fhirpath, model)
+```
+
+### US Core IG Verification
+
+```
+✅ 70 US Core StructureDefinitions parsed
+✅ 55 resource profiles converted to CanonicalProfiles
+✅ 15 extension definitions processed
+✅ Official examples validated against declared profiles
+✅ FHIRPath evaluation on US Core resources
+✅ Profile-to-example matching verified
+```
+
+### Stress Testing
+
+```
+✅ Malformed input resilience — graceful error handling
+✅ Deep nesting stress — recursive structure validation
+✅ Large payload stress — bundle processing performance
+✅ FHIRPath complexity — complex expression evaluation
+✅ Memory pressure — batch processing stability
+✅ Concurrent safety — parallel operation validation
+```
+
+---
+
+## 🏗️ Architecture
+
+### Module Structure
+
+```
+src/
+├── model/        ← FHIR R4 type definitions (branded primitives, enums, complex types)
+├── parser/       ← JSON parsing & serialization
+├── context/      ← SD registry, loaders, inheritance resolution, bundle loading
+├── profile/      ← Snapshot generation, canonical builder, constraint merging
+├── validator/    ← Structural validation (9 rules + FHIRPath invariants)
+└── fhirpath/     ← FHIRPath expression engine (Pratt parser, 60+ functions)
+```
+
+### HAPI FHIR Equivalence
+
+| fhir-runtime         | HAPI FHIR                                         |
+| -------------------- | ------------------------------------------------- |
+| `FhirContextImpl`    | `FhirContext` + `DefaultProfileValidationSupport` |
+| `SnapshotGenerator`  | `ProfileUtilities.generateSnapshot()`             |
+| `StructureValidator` | `FhirInstanceValidator`                           |
+| `evalFhirPath()`     | `FHIRPathEngine.evaluate()`                       |
+| `CompositeLoader`    | `ValidationSupportChain`                          |
+
+---
+
+## 🎯 Use Cases
+
+- **FHIR Servers** — Validation layer for REST operations
+- **CLI Tools** — Parse, validate, generate snapshots, evaluate FHIRPath
+- **Web Applications** — Client-side FHIR processing without server dependency
+- **IG Publishers** — Profile validation and snapshot generation
+- **Testing Frameworks** — FHIR resource validation in test suites
+- **Data Pipelines** — ETL with FHIR validation and transformation
+
+---
+
+## 📄 License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+
+---
+
+## 🤝 Contributing
+
+Contributions are welcome! This project maintains:
+
+- **Zero runtime dependencies** — Keep it that way
+- **100% test pass rate** — All tests must pass
+- **Type safety** — Full TypeScript coverage
+- **HAPI equivalence** — Snapshot generation must match HAPI output
+
+---
+
+## 📊 Package Details
+
+| Property                 | Value                           |
+| ------------------------ | ------------------------------- |
+| Package name             | `fhir-runtime`                  |
+| Version                  | 0.2.0                           |
+| License                  | MIT                             |
+| FHIR Version             | R4 (4.0.1)                      |
+| Module formats           | ESM + CJS                       |
+| Runtime dependencies     | None (zero dependencies)        |
+| Bundled core definitions | 73 FHIR R4 StructureDefinitions |
+| Public exports           | 211 symbols across 6 modules    |
+| Test coverage            | 2,400+ tests across 45 files    |
+
+---
+
+## 🔗 Related Projects
+
+- **[HAPI FHIR](https://hapifhir.io/)** — Reference Java implementation
+- **[HL7 FHIR Specification](https://hl7.org/fhir/R4/)** — Official FHIR R4 spec
+- **[US Core IG](https://www.hl7.org/fhir/us/core/)** — US Core Implementation Guide
+
+---
+
+## ⚡ Performance
+
+- **Zero dependencies** — Minimal bundle size, fast installation
+- **AST caching** — FHIRPath expressions cached (LRU, 128 entries)
+- **Deterministic** — Same input always produces same output
+- **Memory efficient** — Streaming bundle loading, lazy evaluation
+
+---
+
+**Made with ❤️ for the FHIR community**