@peerbits/fhir-validator 1.0.0

package/LICENSE

@@ -0,0 +1,105 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work.
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work.
+
+      "Contribution" shall mean any work of authorship intentionally
+      submitted to Licensor for inclusion in the Work.
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have
+      made, use, offer to sell, sell, import, and otherwise transfer the
+      Work. If You institute patent litigation against any entity
+      alleging that the Work constitutes direct or contributory patent
+      infringement, then any patent licenses granted to You under this
+      License for that Work shall terminate as of the date such
+      litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof provided that You meet the
+      following conditions:
+
+      (a) You must give any other recipients a copy of this License; and
+      (b) You must cause modified files to carry prominent notices; and
+      (c) You must retain all copyright, patent, trademark, and
+          attribution notices from the Source form; and
+      (d) If the Work includes a NOTICE file, any Derivative Works must
+          include a readable copy of its attribution notices.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You shall be under the terms of this License, without additional
+      terms or conditions.
+
+   6. Trademarks. This License does not grant permission to use trade
+      names, trademarks, service marks, or product names of the Licensor.
+
+   7. Disclaimer of Warranty. The Work is provided on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied.
+
+   8. Limitation of Liability. In no event shall any Contributor be
+      liable for damages arising as a result of this License or out of
+      the use or inability to use the Work.
+
+   9. Accepting Warranty or Additional Liability. You may choose to offer
+      support, warranty, indemnity, or other liability obligations, but
+      only on Your own behalf and sole responsibility.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,211 @@
+# @peerbits/fhir-validator
+
+> Fast, lightweight structural, cardinality, and reference validation for FHIR R4 resources.
+
+[![CI](https://github.com/PeerbitsSolution/fhir-validator/actions/workflows/ci.yml/badge.svg)](https://github.com/PeerbitsSolution/fhir-validator/actions)
+[![CodeQL](https://github.com/PeerbitsSolution/fhir-validator/actions/workflows/codeql.yml/badge.svg)](https://github.com/PeerbitsSolution/fhir-validator/actions)
+[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
+
+> [!IMPORTANT]
+> **Scope & Positioning**: `@peerbits/fhir-validator` is a fast in-memory **structural and reference validator** for FHIR R4 resources. It is **not** a full FHIR profile conformance engine, does not evaluate FHIRPath invariant expressions, and is not an ONC certification test kit.
+>
+> **Read our [Known Limitations](docs/KNOWN_LIMITATIONS.md)** for a clear overview of supported checks vs. out-of-scope capabilities and recommended full-conformance alternatives.
+
+---
+
+## The Peerbits HealthTech Toolkit Narrative
+
+`@peerbits/fhir-validator` works seamlessly alongside the rest of the Peerbits Open Source healthcare stack:
+
+1. **[`@peerbits/smart-launch`](../smart-launch)** — Performs EHR SMART-on-FHIR OAuth2 / OIDC discovery and authorization.
+2. **[`@peerbits/fhir-client`](../fhir-client)** — Connects to FHIR servers and executes type-safe CRUD, searches, and batch bundles.
+3. **`@peerbits/fhir-validator`** — Inspects and verifies payload integrity at runtime, catching missing fields, invalid references, and malformed codings before requests hit the wire or database.
+
+---
+
+## Features
+
+- **Zero-Dependency & In-Memory**: Pure TypeScript with zero runtime dependencies. Runs in Node.js, browsers, Edge workers, and Lambda functions.
+- **7 Core Resource Types**: Base structural rules and cardinality checks for:
+  - `Patient`
+  - `Observation`
+  - `Encounter`
+  - `Condition`
+  - `Coverage`
+  - `Claim`
+  - `ClaimResponse`
+- **Reference Target-Type Enforcement**: Checks that `Reference` elements target allowed resource types per the FHIR R4 specification.
+- **Coding & CodeableConcept Shape Verification**: Structural validation of `code` and URI `system` fields without heavy external network calls.
+- **Pluggable Profile Constraints**: Declaratively enforce additional required fields, cardinality minimums, and fixed values on top of base specifications (includes illustrative `USCorePatientProfile` and `USCoreObservationVitalsProfile`).
+- **OperationOutcome-Aligned Output**: Returns `{ valid: boolean, issues: ValidationIssue[] }` with diagnostic severities (`error`, `warning`, `information`).
+
+---
+
+## Installation
+
+```bash
+npm install @peerbits/fhir-validator
+```
+
+---
+
+## Quick Start
+
+### 1. Validating a Resource
+
+```typescript
+import { validate } from "@peerbits/fhir-validator";
+
+const observation = {
+  resourceType: "Observation",
+  id: "heart-rate-001",
+  status: "final",
+  code: {
+    coding: [
+      {
+        system: "http://loinc.org",
+        code: "8867-4",
+        display: "Heart rate",
+      },
+    ],
+  },
+  subject: {
+    reference: "Patient/synthetic-patient-001",
+  },
+  valueQuantity: {
+    value: 72,
+    unit: "/min",
+    system: "http://unitsofmeasure.org",
+    code: "/min",
+  },
+};
+
+const result = validate(observation);
+console.log(result.valid); // true
+console.log(result.issues); // []
+```
+
+### 2. Catching Structural Errors (Before / After)
+
+When passed a resource with deliberate errors:
+
+```typescript
+import { validate } from "@peerbits/fhir-validator";
+
+const malformedObservation = {
+  resourceType: "Observation",
+  // 1. Missing required 'status'
+  code: {
+    coding: [
+      {
+        // 2. Missing required 'system' URI
+        code: "8867-4",
+      },
+    ],
+  },
+  subject: {
+    // 3. Disallowed target resource type for Observation.subject
+    reference: "Claim/claim-999",
+  },
+};
+
+const result = validate(malformedObservation);
+console.log(result.valid); // false
+console.log(result.issues);
+```
+
+**Result Output (`ValidationIssue[]`):**
+
+```json
+{
+  "valid": false,
+  "issues": [
+    {
+      "severity": "error",
+      "path": "Observation.status",
+      "code": "required",
+      "message": "Missing required 'status' in 'Observation'."
+    },
+    {
+      "severity": "error",
+      "path": "Observation.code.coding[0].system",
+      "code": "required",
+      "message": "Missing required 'system' URI in 'Observation.code.coding[0]'."
+    },
+    {
+      "severity": "error",
+      "path": "Observation.subject",
+      "code": "invalid-reference-type",
+      "message": "Reference at 'Observation.subject' targets disallowed resource type 'Claim'. Allowed types: Patient, Group, Device, Location."
+    }
+  ]
+}
+```
+
+---
+
+## Applying Profile Constraints
+
+You can pass profile constraints to enforce additional requirements beyond base FHIR:
+
+```typescript
+import { validate, USCorePatientProfile } from "@peerbits/fhir-validator";
+
+const minimalPatient = {
+  resourceType: "Patient",
+  id: "patient-1",
+  gender: "female",
+};
+
+// Base validation passes (since name & identifier are optional in base FHIR R4)
+const baseResult = validate(minimalPatient);
+console.log(baseResult.valid); // true
+
+// US Core Patient requires name and identifier
+const profileResult = validate(minimalPatient, { profile: USCorePatientProfile });
+console.log(profileResult.valid); // false
+console.log(profileResult.issues);
+// => Issues flagging missing 'Patient.identifier' and 'Patient.name'
+```
+
+---
+
+## API Reference
+
+### `validate(resource: unknown, options?: ValidateOptions): ValidationResult`
+
+Validates any JSON object against base FHIR R4 rules and optional profile constraints.
+
+#### `ValidationResult`
+- `valid: boolean` — `true` if zero issues with `severity: "error"` were found.
+- `issues: ValidationIssue[]` — List of validation issues.
+
+#### `ValidationIssue`
+- `severity: "error" | "warning" | "information"`
+- `path: string` — Dot-notated element path (e.g. `Observation.code.coding[0].system`).
+- `code: string` — Machine-readable issue code (e.g. `required`, `invalid-type`, `invalid-reference-type`).
+- `message: string` — Human-readable description.
+
+---
+
+## Contributing & Development
+
+```bash
+# Install dependencies
+npm install
+
+# Run test suite
+npm test
+
+# Type check
+npm run typecheck
+
+# Build bundle
+npm run build
+```
+
+---
+
+## License
+
+[Apache 2.0](LICENSE) © Peerbits

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@peerbits/fhir-validator",
+  "version": "1.0.0",
+  "description": "Structural, cardinality, and reference validation for FHIR R4 resources — a fast base-spec validator with a pluggable illustrative-profile mechanism (not a full conformance engine)",
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "lint": "eslint .",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/PeerbitsSolution/fhir-validator.git"
+  },
+  "keywords": [
+    "fhir",
+    "fhir-validation",
+    "healthcare",
+    "typescript",
+    "conformance"
+  ],
+  "devDependencies": {
+    "@typescript-eslint/eslint-plugin": "^8.0.0",
+    "@typescript-eslint/parser": "^8.0.0",
+    "eslint": "^9.0.0",
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}