fhir-runtime 0.2.0

package/dist/lib/validator/validation-rules.d.ts

@@ -0,0 +1,198 @@
+/**
+ * fhir-validator — Validation Rules: Cardinality, Type, Fixed/Pattern & Reference
+ *
+ * Implements the core structural validation rules:
+ * - {@link validateCardinality} — min/max cardinality checks
+ * - {@link validateType} — FHIR type constraint checks
+ * - {@link inferFhirType} — heuristic FHIR type inference from JS values
+ * - {@link validateRequired} — required element (min≥1) presence check
+ * - {@link validateFixed} — fixed value exact-match checks
+ * - {@link validatePattern} — pattern value partial-match checks
+ * - {@link matchesPattern} — recursive partial object matching
+ * - {@link deepEqual} — recursive deep equality comparison
+ * - {@link validateReference} — reference target profile checks
+ * - {@link extractReferenceType} — extract resource type from reference string
+ *
+ * These functions operate on individual {@link CanonicalElement} definitions
+ * and produce {@link ValidationIssue} entries when violations are found.
+ *
+ * @module fhir-validator
+ */
+import type { CanonicalElement } from '../model/canonical-profile.js';
+import type { ValidationIssue } from './types.js';
+/**
+ * Validate cardinality (min/max) for an element.
+ *
+ * Checks that the number of values found for an element falls within
+ * the allowed range defined by `element.min` and `element.max`.
+ *
+ * @param element - The canonical element definition with min/max constraints.
+ * @param values - The extracted values for this element.
+ * @param issues - Mutable array to push validation issues into.
+ *
+ * @example
+ * ```typescript
+ * // element: min=1, max=1
+ * validateCardinality(element, [], issues);
+ * // → issues: [{ code: 'CARDINALITY_MIN_VIOLATION', ... }]
+ * ```
+ */
+export declare function validateCardinality(element: CanonicalElement, values: unknown[], issues: ValidationIssue[]): void;
+/**
+ * Validate that a required element (min ≥ 1) is present.
+ *
+ * This is a convenience wrapper that checks element presence without
+ * needing to extract values first. It only checks the `exists` flag.
+ *
+ * @param element - The canonical element definition.
+ * @param exists - Whether the element exists in the resource.
+ * @param issues - Mutable array to push validation issues into.
+ */
+export declare function validateRequired(element: CanonicalElement, exists: boolean, issues: ValidationIssue[]): void;
+/**
+ * Infer the FHIR type from a JavaScript value.
+ *
+ * Uses heuristics to determine the most likely FHIR type based on
+ * the JavaScript runtime type and object shape. This is inherently
+ * imperfect — for example, a JS `string` could be any of the FHIR
+ * string-like primitives. The inference returns the broadest matching
+ * category.
+ *
+ * **Type mapping:**
+ *
+ * | JS type | Inferred FHIR type |
+ * |---------|-------------------|
+ * | `string` | `'string'` |
+ * | `boolean` | `'boolean'` |
+ * | `number` (integer) | `'integer'` |
+ * | `number` (decimal) | `'decimal'` |
+ * | `object` with `system`+`code` | `'Coding'` |
+ * | `object` with `coding` array | `'CodeableConcept'` |
+ * | `object` with `value`+`unit` or `value`+`system` | `'Quantity'` |
+ * | `object` with `reference` | `'Reference'` |
+ * | `object` with `start` or `end` | `'Period'` |
+ * | `object` with `numerator`+`denominator` | `'Ratio'` |
+ * | `object` with `line`+`city` or `city`+`state` | `'Address'` |
+ * | `object` with `family` or `given` | `'HumanName'` |
+ * | `object` with `system`+`value` (no `code`) | `'Identifier'` |
+ * | `object` with `contentType` or `data` | `'Attachment'` |
+ * | `object` with `url`+`value[x]` shape | `'Extension'` |
+ * | other `object` | `'BackboneElement'` |
+ * | `null`/`undefined` | `'null'` |
+ *
+ * @param value - The JavaScript value to infer type from.
+ * @returns The inferred FHIR type name.
+ */
+export declare function inferFhirType(value: unknown): string;
+/**
+ * Validate type constraints for an element value.
+ *
+ * Checks that the inferred FHIR type of a value matches at least one
+ * of the allowed types defined in the element's type constraints.
+ *
+ * If the element has no type constraints (backbone element), validation
+ * is skipped. If the element allows multiple types (choice type), the
+ * value must match at least one.
+ *
+ * @param element - The canonical element definition with type constraints.
+ * @param value - The actual value to validate.
+ * @param issues - Mutable array to push validation issues into.
+ *
+ * @example
+ * ```typescript
+ * // element.types = [{ code: 'string' }]
+ * validateType(element, 42, issues);
+ * // → issues: [{ code: 'TYPE_MISMATCH', ... }]
+ * ```
+ */
+export declare function validateType(element: CanonicalElement, value: unknown, issues: ValidationIssue[]): void;
+/**
+ * Validate that a choice type element uses an allowed type suffix.
+ *
+ * For elements like `Observation.value[x]`, checks that the concrete
+ * property name (e.g., `valueQuantity`) uses a type suffix that matches
+ * one of the allowed types in the element definition.
+ *
+ * @param element - The canonical element definition (must be a choice type).
+ * @param concreteFieldSuffix - The type suffix from the concrete property
+ *   (e.g., `'Quantity'` from `valueQuantity`).
+ * @param issues - Mutable array to push validation issues into.
+ */
+export declare function validateChoiceType(element: CanonicalElement, concreteFieldSuffix: string, issues: ValidationIssue[]): void;
+/**
+ * Perform a recursive deep equality comparison between two values.
+ *
+ * Handles primitives, `null`, `undefined`, arrays (order-sensitive),
+ * and plain objects. Does NOT handle `Date`, `RegExp`, `Map`, `Set`,
+ * or other special JS types — those are not relevant for FHIR JSON.
+ *
+ * @param a - First value.
+ * @param b - Second value.
+ * @returns `true` if the values are deeply equal.
+ */
+export declare function deepEqual(a: unknown, b: unknown): boolean;
+/**
+ * Validate a fixed value constraint on an element.
+ *
+ * When `element.fixed` is defined, the actual value MUST be deeply equal
+ * to the fixed value. This is an exact-match constraint — no additional
+ * or missing fields are allowed.
+ *
+ * @param element - The canonical element definition (may have `fixed`).
+ * @param value - The actual value to validate.
+ * @param issues - Mutable array to push validation issues into.
+ */
+export declare function validateFixed(element: CanonicalElement, value: unknown, issues: ValidationIssue[]): void;
+/**
+ * Check if a value matches a pattern (partial/subset match).
+ *
+ * A pattern match means: every field present in the `pattern` must also
+ * be present in `value` with the same value. However, `value` may contain
+ * additional fields not in the pattern.
+ *
+ * For primitives and arrays, this falls back to deep equality.
+ * For objects, it performs recursive subset matching.
+ *
+ * @param value - The actual value to check.
+ * @param pattern - The pattern to match against.
+ * @returns `true` if the value matches the pattern.
+ */
+export declare function matchesPattern(value: unknown, pattern: unknown): boolean;
+/**
+ * Validate a pattern value constraint on an element.
+ *
+ * When `element.pattern` is defined, the actual value must be a superset
+ * of the pattern — all fields in the pattern must exist in the value with
+ * matching values, but the value may contain additional fields.
+ *
+ * @param element - The canonical element definition (may have `pattern`).
+ * @param value - The actual value to validate.
+ * @param issues - Mutable array to push validation issues into.
+ */
+export declare function validatePattern(element: CanonicalElement, value: unknown, issues: ValidationIssue[]): void;
+/**
+ * Extract the resource type from a FHIR reference string.
+ *
+ * Handles the following reference formats:
+ * - Relative: `"Patient/123"` → `"Patient"`
+ * - Absolute: `"http://example.org/fhir/Patient/123"` → `"Patient"`
+ * - URN: `"urn:uuid:abc-123"` → `undefined` (cannot determine type)
+ * - Fragment: `"#contained-1"` → `undefined`
+ *
+ * @param reference - The reference string to parse.
+ * @returns The resource type, or `undefined` if it cannot be determined.
+ */
+export declare function extractReferenceType(reference: string | undefined): string | undefined;
+/**
+ * Validate reference target profile constraints.
+ *
+ * Checks that a Reference value's target resource type matches at least
+ * one of the allowed target profiles defined in the element's type
+ * constraints.
+ *
+ * @param element - The canonical element definition with Reference type constraints.
+ * @param value - The actual value (expected to be a Reference object).
+ * @param issues - Mutable array to push validation issues into.
+ */
+export declare function validateReference(element: CanonicalElement, value: unknown, issues: ValidationIssue[]): void;
+//# sourceMappingURL=validation-rules.d.ts.map

package/dist/lib/validator/validation-rules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation-rules.d.ts","sourceRoot":"","sources":["../../../src/validator/validation-rules.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AACtE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAOlD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,gBAAgB,EACzB,MAAM,EAAE,OAAO,EAAE,EACjB,MAAM,EAAE,eAAe,EAAE,GACxB,IAAI,CA4BN;AAMD;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,gBAAgB,EACzB,MAAM,EAAE,OAAO,EACf,MAAM,EAAE,eAAe,EAAE,GACxB,IAAI,CAWN;AA6BD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CA2BpD;AA2KD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,gBAAgB,EACzB,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,eAAe,EAAE,GACxB,IAAI,CA8BN;AAMD;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,gBAAgB,EACzB,mBAAmB,EAAE,MAAM,EAC3B,MAAM,EAAE,eAAe,EAAE,GACxB,IAAI,CAoBN;AAMD;;;;;;;;;;GAUG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,GAAG,OAAO,CA4CzD;AAMD;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,gBAAgB,EACzB,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,eAAe,EAAE,GACxB,IAAI,CAuBN;AAMD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAmCxE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,gBAAgB,EACzB,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,eAAe,EAAE,GACxB,IAAI,CAuBN;AAMD;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAkCtF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,gBAAgB,EACzB,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,eAAe,EAAE,GACxB,IAAI,CA+DN"}

package/dist/tsdoc-metadata.json

@@ -0,0 +1,11 @@
+// This file is read by tools that parse documentation comments conforming to the TSDoc standard.
+// It should be published with your NPM package.  It should not be tracked by Git.
+{
+  "tsdocVersion": "0.12",
+  "toolPackages": [
+    {
+      "packageName": "@microsoft/api-extractor",
+      "packageVersion": "7.56.1"
+    }
+  ]
+}

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "fhir-runtime",
+  "version": "0.2.0",
+  "description": "FHIR R4 Core Library - TypeScript implementation with parser, validator, context, and profile support",
+  "homepage": "https://medxai.com.cn",
+  "license": "MIT",
+  "author": "Fangjun <fangjun20208@gmail.com>",
+  "keywords": [
+    "fhir",
+    "fhir-r4",
+    "healthcare",
+    "hl7",
+    "typescript",
+    "parser",
+    "validator",
+    "medical",
+    "interoperability"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/medxaidev/medxai.git",
+    "directory": "packages/fhir-core"
+  },
+  "bugs": {
+    "url": "https://github.com/medxaidev/medxai/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "sideEffects": false,
+  "type": "module",
+  "main": "./dist/cjs/index.cjs",
+  "module": "./dist/esm/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.mjs"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "clean": "rimraf dist",
+    "build": "npm run clean && tsc && node ./scripts/esbuild.mjs",
+    "test": "vitest run",
+    "prepublishOnly": "npm run test && npm run build"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "typescript": "5.9.3",
+    "@types/node": "25.2.0",
+    "rimraf": "6.1.2",
+    "esbuild": "0.27.2",
+    "@microsoft/api-extractor": "7.56.1",
+    "vitest": "4.0.18",
+    "tsx": "4.21.0"
+  },
+  "peerDependencies": {},
+  "engines": {
+    "node": ">=18.0.0",
+    "npm": ">=9.0.0"
+  }
+}