fhir-runtime 0.2.0

package/dist/lib/parser/parse-error.d.ts

@@ -0,0 +1,146 @@
+/**
+ * FHIR JSON Parse Error Types
+ *
+ * Structured error types for the fhir-parser module. Provides precise
+ * error localization via JSON path tracking and supports collecting
+ * multiple issues (errors + warnings) in a single parse pass.
+ *
+ * Design decisions:
+ * - Result type over exceptions: allows multi-error collection
+ * - Path tracking: every issue carries the JSON path for precise localization
+ * - Warning support: non-fatal issues (e.g., unknown properties) reported
+ *   as warnings without blocking the parse
+ *
+ * @module fhir-parser
+ */
+/**
+ * Severity level of a parse issue.
+ *
+ * - `error` — the issue prevents correct interpretation of the data
+ * - `warning` — the data can still be used, but something unexpected was found
+ */
+export type ParseSeverity = 'error' | 'warning';
+/**
+ * Machine-readable error codes for parse issues.
+ *
+ * Each code corresponds to a specific category of parsing problem.
+ * Consumers can switch on these codes for programmatic error handling.
+ */
+export type ParseErrorCode = 
+/** JSON syntax error (e.g., malformed JSON string) */
+'INVALID_JSON'
+/** Missing required `resourceType` property */
+ | 'MISSING_RESOURCE_TYPE'
+/** `resourceType` value is not a recognized FHIR resource type */
+ | 'UNKNOWN_RESOURCE_TYPE'
+/** Primitive value has wrong JavaScript type (e.g., string where number expected) */
+ | 'INVALID_PRIMITIVE'
+/** Object structure does not match expected shape (e.g., array where object expected) */
+ | 'INVALID_STRUCTURE'
+/** Choice type `[x]` property name has an unrecognized type suffix */
+ | 'INVALID_CHOICE_TYPE'
+/** Multiple variants of the same choice type field are present */
+ | 'MULTIPLE_CHOICE_VALUES'
+/** `_element` array length does not match the corresponding value array */
+ | 'ARRAY_MISMATCH'
+/** Unexpected `null` value in a non-nullable position */
+ | 'UNEXPECTED_NULL'
+/** Property name not recognized for this type (severity: warning) */
+ | 'UNEXPECTED_PROPERTY';
+/**
+ * A single issue encountered during parsing.
+ *
+ * Issues are collected throughout the parse process and returned in the
+ * {@link ParseResult}. Both errors and warnings use this same structure.
+ *
+ * @example
+ * ```typescript
+ * const issue: ParseIssue = {
+ *   severity: 'error',
+ *   code: 'MISSING_RESOURCE_TYPE',
+ *   message: 'Object is missing the required "resourceType" property',
+ *   path: '$',
+ * };
+ * ```
+ */
+export interface ParseIssue {
+    /** Severity level — `error` blocks successful parsing, `warning` does not */
+    readonly severity: ParseSeverity;
+    /** Machine-readable error code for programmatic handling */
+    readonly code: ParseErrorCode;
+    /** Human-readable description of the issue */
+    readonly message: string;
+    /**
+     * JSON path where the issue was detected.
+     *
+     * Uses dot notation with array indices:
+     * - `"StructureDefinition"` — root level
+     * - `"StructureDefinition.snapshot.element[0].type[1].code"` — nested
+     * - `"$"` — before resourceType is known
+     */
+    readonly path: string;
+}
+/**
+ * Result of a parse operation.
+ *
+ * Uses a discriminated union on `success`:
+ * - `success: true` — parsing succeeded; `data` contains the parsed value,
+ *   `issues` may contain warnings
+ * - `success: false` — parsing failed; `data` is `undefined`,
+ *   `issues` contains at least one error
+ *
+ * @typeParam T - The expected output type (e.g., `StructureDefinition`)
+ *
+ * @example
+ * ```typescript
+ * const result = parseFhirJson(jsonString);
+ * if (result.success) {
+ *   console.log(result.data.url); // T is available
+ * } else {
+ *   for (const issue of result.issues) {
+ *     console.error(`[${issue.path}] ${issue.message}`);
+ *   }
+ * }
+ * ```
+ */
+export type ParseResult<T> = {
+    readonly success: true;
+    readonly data: T;
+    readonly issues: readonly ParseIssue[];
+} | {
+    readonly success: false;
+    readonly data: undefined;
+    readonly issues: readonly ParseIssue[];
+};
+/**
+ * Create a successful parse result.
+ *
+ * @param data - The parsed value
+ * @param issues - Any warnings collected during parsing (default: none)
+ */
+export declare function parseSuccess<T>(data: T, issues?: ParseIssue[]): ParseResult<T>;
+/**
+ * Create a failed parse result.
+ *
+ * @param issues - The error(s) that caused the failure (must contain at least one error)
+ */
+export declare function parseFailure<T>(issues: ParseIssue[]): ParseResult<T>;
+/**
+ * Create a single parse issue.
+ *
+ * Convenience factory to reduce boilerplate when constructing issues.
+ *
+ * @param severity - Error or warning
+ * @param code - Machine-readable error code
+ * @param message - Human-readable description
+ * @param path - JSON path where the issue was detected
+ */
+export declare function createIssue(severity: ParseSeverity, code: ParseErrorCode, message: string, path: string): ParseIssue;
+/**
+ * Check whether an issues array contains at least one error (not just warnings).
+ *
+ * Useful for determining whether to return success or failure after
+ * collecting issues from sub-parsers.
+ */
+export declare function hasErrors(issues: readonly ParseIssue[]): boolean;
+//# sourceMappingURL=parse-error.d.ts.map

package/dist/lib/parser/parse-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse-error.d.ts","sourceRoot":"","sources":["../../../src/parser/parse-error.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAMH;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,SAAS,CAAC;AAEhD;;;;;GAKG;AACH,MAAM,MAAM,cAAc;AACxB,sDAAsD;AACpD,cAAc;AAChB,+CAA+C;GAC7C,uBAAuB;AACzB,kEAAkE;GAChE,uBAAuB;AACzB,qFAAqF;GACnF,mBAAmB;AACrB,yFAAyF;GACvF,mBAAmB;AACrB,sEAAsE;GACpE,qBAAqB;AACvB,kEAAkE;GAChE,wBAAwB;AAC1B,2EAA2E;GACzE,gBAAgB;AAClB,yDAAyD;GACvD,iBAAiB;AACnB,qEAAqE;GACnE,qBAAqB,CAAC;AAM1B;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,UAAU;IACzB,6EAA6E;IAC7E,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;IAEjC,4DAA4D;IAC5D,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAE9B,8CAA8C;IAC9C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB;;;;;;;OAOG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAMD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,IACrB;IAAE,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,SAAS,UAAU,EAAE,CAAA;CAAE,GACpF;IAAE,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,SAAS,UAAU,EAAE,CAAA;CAAE,CAAC;AAMlG;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,GAAE,UAAU,EAAO,GAAG,WAAW,CAAC,CAAC,CAAC,CAElF;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,EAAE,UAAU,EAAE,GAAG,WAAW,CAAC,CAAC,CAAC,CAKpE;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CACzB,QAAQ,EAAE,aAAa,EACvB,IAAI,EAAE,cAAc,EACpB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,GACX,UAAU,CAEZ;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,SAAS,UAAU,EAAE,GAAG,OAAO,CAEhE"}

package/dist/lib/parser/primitive-parser.d.ts

@@ -0,0 +1,136 @@
+/**
+ * FHIR Primitive Type Parser
+ *
+ * Handles the FHIR JSON dual-property representation of primitive types:
+ * - `name`: the actual value (string | number | boolean)
+ * - `_name`: the Element metadata (id, extension)
+ *
+ * FHIR R4 JSON Representation Rules (§2.6.2):
+ * 1. Primitive values appear as JSON string, number, or boolean
+ * 2. Element metadata (id, extension) appears under `_name`
+ * 3. Either or both may be present
+ * 4. For arrays, `null` is used for positional alignment
+ *
+ * Stage-1 Strategy:
+ * - Values are passed through as branded types (no regex validation)
+ * - `_element` id and extension are merged onto the result
+ * - Regex validation is deferred to fhir-validator (Phase 5)
+ *
+ * @see https://hl7.org/fhir/R4/json.html#primitive
+ * @module fhir-parser
+ */
+import type { ParseIssue } from './parse-error.js';
+/**
+ * Expected JavaScript type for a FHIR primitive type name.
+ *
+ * FHIR R4 JSON type mapping:
+ * - `boolean` → JSON boolean
+ * - `integer`, `positiveInt`, `unsignedInt` → JSON number (integer)
+ * - `decimal` → JSON number
+ * - All others → JSON string
+ */
+export type PrimitiveJsType = 'boolean' | 'number' | 'string';
+/**
+ * Get the expected JavaScript type for a FHIR primitive type name.
+ *
+ * Returns `'string'` for unknown type names (safe default).
+ */
+export declare function getExpectedJsType(fhirType: string): PrimitiveJsType;
+/**
+ * Validate that a primitive value has the correct JavaScript type.
+ *
+ * This performs structural validation only (correct JS type). It does NOT
+ * validate the value against FHIR regex patterns — that is the responsibility
+ * of fhir-validator (Phase 5).
+ *
+ * @param value - The JSON value to validate
+ * @param fhirType - The FHIR primitive type name (e.g., "string", "boolean", "integer")
+ * @param path - JSON path for error reporting
+ * @returns A `ParseIssue` if validation fails, or `null` if valid
+ */
+export declare function validatePrimitiveValue(value: unknown, fhirType: string, path: string): ParseIssue | null;
+/**
+ * The result of parsing a `_element` companion object.
+ *
+ * Contains the `id` and `extension` fields from the Element base type.
+ */
+export interface ElementMetadata {
+    /** Element id (0..1) */
+    readonly id?: string;
+    /** Extensions (0..*) */
+    readonly extension?: unknown[];
+}
+/**
+ * A merged primitive value combining the JSON value with Element metadata.
+ *
+ * This is the internal representation produced by the parser for primitive
+ * fields that have a `_element` companion.
+ *
+ * When no `_element` is present, the value is stored directly (not wrapped).
+ */
+export interface PrimitiveWithMetadata {
+    /** The primitive value (string | number | boolean), absent when only _element is present */
+    readonly value?: unknown;
+    /** Element id from _element (0..1) */
+    readonly id?: string;
+    /** Extensions from _element (0..*) */
+    readonly extension?: unknown[];
+}
+/**
+ * Merge a primitive value with its `_element` companion.
+ *
+ * Handles all combinations:
+ * - Value only → returns value directly (no wrapping)
+ * - Value + _element → returns `PrimitiveWithMetadata`
+ * - _element only (no value) → returns `PrimitiveWithMetadata` with undefined value
+ * - Neither → returns `undefined`
+ *
+ * @param value - The primitive JSON value (string | number | boolean | undefined)
+ * @param elementExtension - The `_element` companion object (or undefined)
+ * @param fhirType - The FHIR primitive type name (for JS type validation)
+ * @param path - JSON path for error reporting
+ *
+ * @example
+ * ```typescript
+ * // Value only
+ * mergePrimitiveElement("1970-03-30", undefined, "date", "Patient.birthDate")
+ * // → { result: "1970-03-30", issues: [] }
+ *
+ * // Value + _element
+ * mergePrimitiveElement("1970-03-30", { id: "314159" }, "date", "Patient.birthDate")
+ * // → { result: { value: "1970-03-30", id: "314159" }, issues: [] }
+ *
+ * // _element only
+ * mergePrimitiveElement(undefined, { extension: [...] }, "date", "Patient.birthDate")
+ * // → { result: { value: undefined, extension: [...] }, issues: [] }
+ * ```
+ */
+export declare function mergePrimitiveElement(value: unknown, elementExtension: unknown, fhirType: string, path: string): {
+    result: unknown;
+    issues: ParseIssue[];
+};
+/**
+ * Merge a repeating primitive array with its `_element` companion array.
+ *
+ * FHIR JSON uses null-alignment for repeating primitives:
+ * ```json
+ * "code": ["au", "nz"],
+ * "_code": [null, { "extension": [...] }]
+ * ```
+ *
+ * Rules:
+ * - Both arrays must have the same length (or `_element` may be absent)
+ * - `null` in the value array means "no value at this position" (only _element)
+ * - `null` in the `_element` array means "no metadata at this position"
+ * - If lengths differ, report `ARRAY_MISMATCH` error
+ *
+ * @param values - The primitive value array
+ * @param elementExtensions - The `_element` companion array (or undefined)
+ * @param fhirType - The FHIR primitive type name (for JS type validation)
+ * @param path - JSON path for error reporting
+ */
+export declare function mergePrimitiveArray(values: unknown[], elementExtensions: unknown[] | undefined, fhirType: string, path: string): {
+    result: unknown[];
+    issues: ParseIssue[];
+};
+//# sourceMappingURL=primitive-parser.d.ts.map

package/dist/lib/parser/primitive-parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"primitive-parser.d.ts","sourceRoot":"","sources":["../../../src/parser/primitive-parser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAQnD;;;;;;;;GAQG;AACH,MAAM,MAAM,eAAe,GAAG,SAAS,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAmC9D;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,eAAe,CAEnE;AAeD;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,GACX,UAAU,GAAG,IAAI,CAyBnB;AAMD;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,wBAAwB;IACxB,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IACrB,wBAAwB;IACxB,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,EAAE,CAAC;CAChC;AA+ED;;;;;;;GAOG;AACH,MAAM,WAAW,qBAAqB;IACpC,4FAA4F;IAC5F,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB,sCAAsC;IACtC,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IACrB,sCAAsC;IACtC,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,EAAE,CAAC;CAChC;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,OAAO,EACd,gBAAgB,EAAE,OAAO,EACzB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,GACX;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,UAAU,EAAE,CAAA;CAAE,CAqC3C;AAMD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,OAAO,EAAE,EACjB,iBAAiB,EAAE,OAAO,EAAE,GAAG,SAAS,EACxC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,GACX;IAAE,MAAM,EAAE,OAAO,EAAE,CAAC;IAAC,MAAM,EAAE,UAAU,EAAE,CAAA;CAAE,CA8E7C"}

package/dist/lib/parser/serializer.d.ts

@@ -0,0 +1,64 @@
+/**
+ * FHIR JSON Serializer
+ *
+ * Converts TypeScript model objects back into FHIR R4 JSON.
+ * This is the inverse of the parser: it takes a `Resource` (or more
+ * specifically a `StructureDefinition`) and produces a FHIR-conformant
+ * JSON string or plain object.
+ *
+ * ## Serialization Rules
+ *
+ * 1. **resourceType first** — always the first property in output
+ * 2. **Choice type restoration** — `ChoiceValue.propertyName` restores the
+ *    original JSON property name (e.g., `fixedString`, `patternCoding`)
+ * 3. **Empty value omission** — `undefined`, empty arrays `[]`, and
+ *    empty objects `{}` are omitted from output
+ * 4. **Property ordering** — `resourceType` first, then remaining
+ *    properties in alphabetical order (FHIR canonical JSON convention)
+ * 5. **Null alignment** — preserved in arrays for primitive `_element` alignment
+ *
+ * ## Scope (Stage-1)
+ *
+ * Stage-1 focuses on StructureDefinition serialization. The serializer
+ * handles:
+ * - All StructureDefinition top-level fields
+ * - All ElementDefinition fields including sub-types
+ * - Choice type fields (defaultValue[x], fixed[x], pattern[x], minValue[x], maxValue[x])
+ * - Example value[x] choice types
+ * - snapshot/differential element containers
+ *
+ * @module fhir-parser
+ */
+import type { Resource } from '../model/primitives.js';
+/**
+ * Serialize a Resource object to a FHIR JSON string.
+ *
+ * Output conforms to FHIR R4 JSON conventions:
+ * - `resourceType` is the first property
+ * - Remaining properties are in alphabetical order
+ * - Choice type fields use their original JSON property names
+ * - Empty values (`undefined`, `[]`, `{}`) are omitted
+ *
+ * @param resource - The Resource to serialize
+ * @returns A FHIR JSON string (pretty-printed with 2-space indent)
+ *
+ * @example
+ * ```typescript
+ * const sd: StructureDefinition = { resourceType: 'StructureDefinition', ... };
+ * const json = serializeToFhirJson(sd);
+ * // '{\n  "resourceType": "StructureDefinition",\n  ...\n}'
+ * ```
+ */
+export declare function serializeToFhirJson(resource: Resource): string;
+/**
+ * Serialize a Resource object to a plain JavaScript object suitable
+ * for FHIR JSON (without calling `JSON.stringify`).
+ *
+ * Use this when you need the object form (e.g., for storage or
+ * further manipulation) rather than a string.
+ *
+ * @param resource - The Resource to serialize
+ * @returns A plain object conforming to FHIR JSON conventions
+ */
+export declare function serializeToFhirObject(resource: Resource): Record<string, unknown>;
+//# sourceMappingURL=serializer.d.ts.map

package/dist/lib/parser/serializer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serializer.d.ts","sourceRoot":"","sources":["../../../src/parser/serializer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAuBvD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,CAG9D;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,QAAQ,GACjB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAKzB"}

package/dist/lib/parser/structure-definition-parser.d.ts

@@ -0,0 +1,63 @@
+/**
+ * StructureDefinition & ElementDefinition Parser
+ *
+ * Dedicated parser for the most important resource type in Stage-1.
+ * All downstream modules (fhir-context, fhir-profile, fhir-validator)
+ * depend on correctly parsed StructureDefinitions.
+ *
+ * Architecture:
+ * ```
+ * parseStructureDefinition(obj, path)
+ *   ├── top-level fields (url, name, status, kind, type, abstract, ...)
+ *   ├── sub-types:
+ *   │     ├── mapping[] → parseSDMapping()
+ *   │     ├── context[] → parseSDContext()
+ *   │     ├── snapshot  → parseSnapshot()  → element[] → parseElementDefinition()
+ *   │     └── differential → parseDifferential() → element[] → parseElementDefinition()
+ *   └── unknown property detection
+ *
+ * parseElementDefinition(obj, path)
+ *   ├── basic fields (path, sliceName, min, max, ...)
+ *   ├── sub-types:
+ *   │     ├── slicing → parseSlicing() → discriminator[] → parseDiscriminator()
+ *   │     ├── base → parseBase()
+ *   │     ├── type[] → parseEDType()
+ *   │     ├── constraint[] → parseConstraint()
+ *   │     ├── binding → parseBinding()
+ *   │     ├── example[] → parseExample()  ← contains choice type
+ *   │     └── mapping[] → parseEDMapping()
+ *   └── choice type fields:
+ *         ├── defaultValue[x] → extractChoiceValue()
+ *         ├── fixed[x] → extractChoiceValue()
+ *         ├── pattern[x] → extractChoiceValue()
+ *         ├── minValue[x] → extractChoiceValue()
+ *         └── maxValue[x] → extractChoiceValue()
+ * ```
+ *
+ * @module fhir-parser
+ */
+import type { StructureDefinition } from '../model/structure-definition.js';
+import type { ElementDefinition } from '../model/element-definition.js';
+import type { ParseResult, ParseIssue } from './parse-error.js';
+/**
+ * Parse an ElementDefinition JSON object.
+ *
+ * ElementDefinition is the most complex data type in FHIR,
+ * with ~37 fields and 8 sub-types.
+ */
+export declare function parseElementDefinition(obj: Record<string, unknown>, path: string): {
+    result: ElementDefinition;
+    issues: ParseIssue[];
+};
+/**
+ * Parse a StructureDefinition JSON object.
+ *
+ * This is the most important parse function in Stage-1. All downstream
+ * modules (fhir-context, fhir-profile, fhir-validator) depend on
+ * correctly parsed StructureDefinitions.
+ *
+ * @param obj - A parsed JSON object (already validated as having resourceType = "StructureDefinition")
+ * @param path - Current JSON path (for error reporting)
+ */
+export declare function parseStructureDefinition(obj: Record<string, unknown>, path: string): ParseResult<StructureDefinition>;
+//# sourceMappingURL=structure-definition-parser.d.ts.map

package/dist/lib/parser/structure-definition-parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"structure-definition-parser.d.ts","sourceRoot":"","sources":["../../../src/parser/structure-definition-parser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,kCAAkC,CAAC;AAO5E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AAYxE,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAoXhE;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,IAAI,EAAE,MAAM,GACX;IAAE,MAAM,EAAE,iBAAiB,CAAC;IAAC,MAAM,EAAE,UAAU,EAAE,CAAA;CAAE,CA+GrD;AA0GD;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CACtC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,IAAI,EAAE,MAAM,GACX,WAAW,CAAC,mBAAmB,CAAC,CA6GlC"}

package/dist/lib/profile/canonical-builder.d.ts

@@ -0,0 +1,87 @@
+/**
+ * fhir-profile — Canonical Profile Builder
+ *
+ * Converts a StructureDefinition (with populated snapshot) into the
+ * internal {@link CanonicalProfile} semantic model defined in Phase 1.
+ *
+ * The CanonicalProfile is MedXAI's own abstraction optimized for
+ * downstream consumption (validation, runtime, application layer):
+ * - Pre-resolved inheritance (flattened snapshot)
+ * - Semantic types (`max: 'unbounded'` instead of `"*"`)
+ * - Non-optional flags (mustSupport/isModifier/isSummary always boolean)
+ * - O(1) element lookup via `Map<string, CanonicalElement>`
+ *
+ * Exported functions:
+ * - {@link buildCanonicalProfile} — convert full SD → CanonicalProfile
+ * - {@link buildCanonicalElement} — convert single ElementDefinition → CanonicalElement
+ * - {@link buildTypeConstraints} — convert ElementDefinitionType[] → TypeConstraint[]
+ * - {@link buildBindingConstraint} — convert ElementDefinitionBinding → BindingConstraint
+ * - {@link buildInvariants} — convert ElementDefinitionConstraint[] → Invariant[]
+ * - {@link buildSlicingDefinition} — convert ElementDefinitionSlicing → SlicingDefinition
+ *
+ * @module fhir-profile
+ */
+import type { CanonicalProfile, CanonicalElement, TypeConstraint, BindingConstraint, Invariant, SlicingDefinition } from '../model/index.js';
+import type { ElementDefinition, ElementDefinitionType, ElementDefinitionBinding, ElementDefinitionConstraint, ElementDefinitionSlicing, StructureDefinition } from '../model/index.js';
+/**
+ * Convert a StructureDefinition (with snapshot) to a CanonicalProfile.
+ *
+ * Precondition: `sd.snapshot` must exist (generated by SnapshotGenerator).
+ * If snapshot is missing, throws an error.
+ *
+ * @param sd - The StructureDefinition with populated snapshot.
+ * @returns The internal CanonicalProfile representation.
+ * @throws Error if sd.snapshot is missing.
+ */
+export declare function buildCanonicalProfile(sd: StructureDefinition): CanonicalProfile;
+/**
+ * Convert a single ElementDefinition to a CanonicalElement.
+ *
+ * Applies the following normalizations:
+ * - `max: "*"` → `max: 'unbounded'`; numeric strings → numbers
+ * - `mustSupport/isModifier/isSummary: undefined` → `false`
+ * - `constraint: undefined` → `[]`
+ * - `type: undefined` → `[]`
+ *
+ * @param ed - The ElementDefinition from a snapshot.
+ * @returns The normalized CanonicalElement.
+ */
+export declare function buildCanonicalElement(ed: ElementDefinition): CanonicalElement;
+/**
+ * Convert ElementDefinitionType[] to TypeConstraint[].
+ *
+ * Returns an empty array if types is undefined or empty.
+ *
+ * @param types - The FHIR type array from an ElementDefinition.
+ * @returns Normalized TypeConstraint array.
+ */
+export declare function buildTypeConstraints(types: readonly ElementDefinitionType[] | undefined): TypeConstraint[];
+/**
+ * Convert ElementDefinitionBinding to BindingConstraint.
+ *
+ * Returns undefined if binding is undefined or has no strength.
+ *
+ * @param binding - The FHIR binding from an ElementDefinition.
+ * @returns Normalized BindingConstraint or undefined.
+ */
+export declare function buildBindingConstraint(binding: ElementDefinitionBinding | undefined): BindingConstraint | undefined;
+/**
+ * Convert ElementDefinitionConstraint[] to Invariant[].
+ *
+ * Returns an empty array if constraints is undefined or empty.
+ *
+ * @param constraints - The FHIR constraint array from an ElementDefinition.
+ * @returns Normalized Invariant array.
+ */
+export declare function buildInvariants(constraints: readonly ElementDefinitionConstraint[] | undefined): Invariant[];
+/**
+ * Convert ElementDefinitionSlicing to SlicingDefinition.
+ *
+ * Returns undefined if slicing is undefined.
+ * Normalizes `ordered` to boolean (default false).
+ *
+ * @param slicing - The FHIR slicing from an ElementDefinition.
+ * @returns Normalized SlicingDefinition or undefined.
+ */
+export declare function buildSlicingDefinition(slicing: ElementDefinitionSlicing | undefined): SlicingDefinition | undefined;
+//# sourceMappingURL=canonical-builder.d.ts.map

package/dist/lib/profile/canonical-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical-builder.d.ts","sourceRoot":"","sources":["../../../src/profile/canonical-builder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EACV,gBAAgB,EAChB,gBAAgB,EAChB,cAAc,EACd,iBAAiB,EACjB,SAAS,EACT,iBAAiB,EAElB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EACV,iBAAiB,EACjB,qBAAqB,EACrB,wBAAwB,EACxB,2BAA2B,EAC3B,wBAAwB,EACxB,mBAAmB,EACpB,MAAM,mBAAmB,CAAC;AAM3B;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,EAAE,EAAE,mBAAmB,GAAG,gBAAgB,CAyB/E;AAMD;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,EAAE,EAAE,iBAAiB,GAAG,gBAAgB,CAuB7E;AAMD;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,SAAS,qBAAqB,EAAE,GAAG,SAAS,GAClD,cAAc,EAAE,CAoBlB;AAMD;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,wBAAwB,GAAG,SAAS,GAC5C,iBAAiB,GAAG,SAAS,CAkB/B;AAMD;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,WAAW,EAAE,SAAS,2BAA2B,EAAE,GAAG,SAAS,GAC9D,SAAS,EAAE,CAsBb;AAMD;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,wBAAwB,GAAG,SAAS,GAC5C,iBAAiB,GAAG,SAAS,CAqB/B"}

package/dist/lib/profile/constraint-merger.d.ts

@@ -0,0 +1,100 @@
+/**
+ * fhir-profile — Constraint Merging Engine
+ *
+ * Implements field-level merging of differential ElementDefinition constraints
+ * onto snapshot elements. This is the most granular part of snapshot generation.
+ *
+ * Corresponds to HAPI FHIR R4:
+ * - `ProfileUtilities.updateFromDefinition()` → {@link mergeConstraints}
+ * - `ProfileUtilities.updateFromBase()` → {@link setBaseTraceability}
+ *
+ * Merge strategies per field (from HAPI research):
+ * - **Overwrite**: short, definition, comment, requirements, label, fixed, pattern,
+ *   maxLength, minValue, maxValue, mustSupport, defaultValue, meaningWhenMissing
+ * - **Validate-then-overwrite**: min, max, type[], binding
+ * - **Append/union**: constraint[], alias[], example[], mapping[]
+ * - **Conditional**: isModifier (extensions only), isSummary (base guard)
+ *
+ * @module fhir-profile
+ */
+import type { ElementDefinition, ElementDefinitionBinding, ElementDefinitionConstraint, ElementDefinitionType } from '../model/index.js';
+import type { SnapshotIssue } from './types.js';
+/**
+ * Apply differential constraints onto a snapshot element.
+ *
+ * Corresponds to HAPI `updateFromDefinition(dest, source, ...)`.
+ * The `dest` element is mutated in place and also returned.
+ *
+ * @param dest - The working snapshot element (initially cloned from base).
+ * @param source - The differential element to apply.
+ * @param issues - Mutable array to collect issues.
+ * @returns The mutated `dest` element.
+ */
+export declare function mergeConstraints(dest: ElementDefinition, source: ElementDefinition, issues: SnapshotIssue[]): ElementDefinition;
+/**
+ * Populate `dest.base` with traceability information from the base element.
+ *
+ * Corresponds to HAPI `updateFromBase(derived, base)`.
+ * If `base` already has a `.base`, we copy from `base.base` (preserving
+ * original ancestry). Otherwise we copy from `base` directly.
+ *
+ * @param dest - The element to set base traceability on.
+ * @param base - The base element to derive traceability from.
+ */
+export declare function setBaseTraceability(dest: ElementDefinition, base: ElementDefinition): void;
+/**
+ * Merge cardinality constraints (min/max) with validation.
+ *
+ * Rules:
+ * - `derived.min` must be >= `base.min` (except for slices)
+ * - `derived.max` must be <= `base.max`
+ *
+ * @internal Exported for direct testing.
+ */
+export declare function mergeCardinality(dest: ElementDefinition, source: ElementDefinition, issues: SnapshotIssue[], path?: string): void;
+/**
+ * Merge type constraints with compatibility validation.
+ *
+ * Each derived type must be compatible with at least one base type.
+ * Special allowances: Extension, Element, *, Resource/DomainResource.
+ *
+ * If valid, derived types replace base types entirely.
+ *
+ * @returns The merged type array (derived types if valid, base types if no diff).
+ */
+export declare function mergeTypes(baseTypes: readonly ElementDefinitionType[] | undefined, diffTypes: readonly ElementDefinitionType[] | undefined, issues: SnapshotIssue[], path: string): ElementDefinitionType[] | undefined;
+/**
+ * Merge binding constraints with strength validation.
+ *
+ * Rules:
+ * - Cannot relax a REQUIRED binding (REQUIRED → anything else = error)
+ * - Derived binding replaces base binding
+ *
+ * @returns The merged binding.
+ */
+export declare function mergeBinding(baseBinding: ElementDefinitionBinding | undefined, diffBinding: ElementDefinitionBinding | undefined, issues: SnapshotIssue[], path: string): ElementDefinitionBinding | undefined;
+/**
+ * Merge constraint (invariant) lists by appending derived constraints,
+ * de-duplicating by `key`.
+ *
+ * Base constraints are kept; derived constraints with the same key
+ * replace the base version.
+ *
+ * @returns The merged constraint array.
+ */
+export declare function mergeConstraintList(baseConstraints: readonly ElementDefinitionConstraint[] | undefined, diffConstraints: readonly ElementDefinitionConstraint[] | undefined): ElementDefinitionConstraint[] | undefined;
+/**
+ * Determine whether max value `a` is larger than max value `b`.
+ *
+ * FHIR max is either a non-negative integer string or `"*"` (unbounded).
+ * `"*"` is treated as infinity.
+ *
+ * @example
+ * isLargerMax('5', '3')   // true
+ * isLargerMax('*', '3')   // true
+ * isLargerMax('3', '*')   // false
+ * isLargerMax('3', '3')   // false
+ * isLargerMax('*', '*')   // false
+ */
+export declare function isLargerMax(a: string, b: string): boolean;
+//# sourceMappingURL=constraint-merger.d.ts.map

package/dist/lib/profile/constraint-merger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constraint-merger.d.ts","sourceRoot":"","sources":["../../../src/profile/constraint-merger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EACV,iBAAiB,EAEjB,wBAAwB,EACxB,2BAA2B,EAG3B,qBAAqB,EAGtB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAOhD;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,iBAAiB,EACvB,MAAM,EAAE,iBAAiB,EACzB,MAAM,EAAE,aAAa,EAAE,GACtB,iBAAiB,CAgFnB;AAMD;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,iBAAiB,EACvB,IAAI,EAAE,iBAAiB,GACtB,IAAI,CAcN;AAMD;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,iBAAiB,EACvB,MAAM,EAAE,iBAAiB,EACzB,MAAM,EAAE,aAAa,EAAE,EACvB,IAAI,CAAC,EAAE,MAAM,GACZ,IAAI,CAyCN;AAMD;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CACxB,SAAS,EAAE,SAAS,qBAAqB,EAAE,GAAG,SAAS,EACvD,SAAS,EAAE,SAAS,qBAAqB,EAAE,GAAG,SAAS,EACvD,MAAM,EAAE,aAAa,EAAE,EACvB,IAAI,EAAE,MAAM,GACX,qBAAqB,EAAE,GAAG,SAAS,CA0BrC;AA0CD;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAC1B,WAAW,EAAE,wBAAwB,GAAG,SAAS,EACjD,WAAW,EAAE,wBAAwB,GAAG,SAAS,EACjD,MAAM,EAAE,aAAa,EAAE,EACvB,IAAI,EAAE,MAAM,GACX,wBAAwB,GAAG,SAAS,CAiBtC;AAMD;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CACjC,eAAe,EAAE,SAAS,2BAA2B,EAAE,GAAG,SAAS,EACnE,eAAe,EAAE,SAAS,2BAA2B,EAAE,GAAG,SAAS,GAClE,2BAA2B,EAAE,GAAG,SAAS,CAwB3C;AA0ED;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAUzD"}