fhir-runtime 0.2.0

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

@@ -0,0 +1,263 @@
+/**
+ * FHIR R4 StructureDefinition Model
+ *
+ * Defines the complete StructureDefinition resource type as per the FHIR R4
+ * specification, including all sub-types (Mapping, Context, Snapshot, Differential).
+ *
+ * StructureDefinition is the core metadata resource that describes the shape
+ * of other FHIR resources, data types, and extensions. It is the primary input
+ * for snapshot generation and validation.
+ *
+ * @see https://hl7.org/fhir/R4/structuredefinition.html
+ * @module fhir-model
+ */
+import type { FhirBoolean, FhirCanonical, FhirDateTime, FhirId, FhirMarkdown, FhirString, FhirUri, PublicationStatus, StructureDefinitionKind, TypeDerivationRule, ExtensionContextType, FhirVersionCode, CodeableConcept, Coding, ContactDetail, BackboneElement, DomainResource, Identifier, UsageContext } from './primitives.js';
+import type { ElementDefinition } from './element-definition.js';
+/**
+ * A mapping to an external specification that the structure conforms to.
+ * @see https://hl7.org/fhir/R4/structuredefinition-definitions.html#StructureDefinition.mapping
+ */
+export interface StructureDefinitionMapping extends BackboneElement {
+    /** Internal id when this mapping is used (1..1) */
+    identity: FhirId;
+    /** Identifies what this mapping refers to (0..1) */
+    uri?: FhirUri;
+    /** Names what this mapping refers to (0..1) */
+    name?: FhirString;
+    /** Versions, issues, scope limitations, etc. (0..1) */
+    comment?: FhirString;
+}
+/**
+ * Identifies the types of resource or data type elements to which the
+ * extension can be applied. Only relevant when kind = 'resource' and
+ * type = 'Extension'.
+ * @see https://hl7.org/fhir/R4/structuredefinition-definitions.html#StructureDefinition.context
+ */
+export interface StructureDefinitionContext extends BackboneElement {
+    /** fhirpath | element | extension (1..1) */
+    type: ExtensionContextType;
+    /** Where the extension can be used in instances (1..1) */
+    expression: FhirString;
+}
+/**
+ * A snapshot view of the structure, containing all element definitions
+ * with their complete constraint information resolved from the
+ * inheritance chain.
+ * @see https://hl7.org/fhir/R4/structuredefinition-definitions.html#StructureDefinition.snapshot
+ */
+export interface StructureDefinitionSnapshot extends BackboneElement {
+    /**
+     * Definition of elements in the resource (if no StructureDefinition) (1..*)
+     *
+     * The snapshot contains the complete, flattened list of all ElementDefinition
+     * entries with all constraints from the inheritance chain fully resolved.
+     * This is the "semantic truth" used for validation and interpretation.
+     */
+    element: ElementDefinition[];
+}
+/**
+ * A differential view of the structure, containing only the constraints
+ * that differ from the base definition. This is the compact authoring
+ * format used when creating profiles.
+ * @see https://hl7.org/fhir/R4/structuredefinition-definitions.html#StructureDefinition.differential
+ */
+export interface StructureDefinitionDifferential extends BackboneElement {
+    /**
+     * Definition of elements in the resource (if no StructureDefinition) (1..*)
+     *
+     * The differential contains only the constraints that differ from the base
+     * profile. It MUST NOT be used directly for semantic interpretation — it
+     * must first be expanded into a snapshot via snapshot generation.
+     */
+    element: ElementDefinition[];
+}
+/**
+ * A definition of a FHIR structure — a resource, data type, or extension.
+ *
+ * StructureDefinition is the central metadata resource in FHIR. It defines:
+ * - The shape of resources and data types (via snapshot/differential)
+ * - Profile constraints (via derivation = 'constraint')
+ * - Extension definitions (via kind = 'resource', type = 'Extension')
+ *
+ * This interface extends DomainResource and includes all fields defined
+ * in the FHIR R4 specification.
+ *
+ * @see https://hl7.org/fhir/R4/structuredefinition.html
+ */
+export interface StructureDefinition extends DomainResource {
+    /** Resource type discriminator (1..1) */
+    resourceType: 'StructureDefinition';
+    /**
+     * Canonical identifier for this structure definition, represented as a URI
+     * (globally unique) (1..1)
+     * @see https://hl7.org/fhir/R4/structuredefinition-definitions.html#StructureDefinition.url
+     */
+    url: FhirUri;
+    /**
+     * Additional identifier for the structure definition (0..*)
+     * @see https://hl7.org/fhir/R4/structuredefinition-definitions.html#StructureDefinition.identifier
+     */
+    identifier?: Identifier[];
+    /**
+     * Business version of the structure definition (0..1)
+     * @see https://hl7.org/fhir/R4/structuredefinition-definitions.html#StructureDefinition.version
+     */
+    version?: FhirString;
+    /**
+     * Computer-readable name of the structure definition (1..1)
+     *
+     * Name should be usable as an identifier for the module by machine
+     * processing applications such as code generation.
+     * @see https://hl7.org/fhir/R4/structuredefinition-definitions.html#StructureDefinition.name
+     */
+    name: FhirString;
+    /**
+     * Human-readable name for the structure definition (0..1)
+     * @see https://hl7.org/fhir/R4/structuredefinition-definitions.html#StructureDefinition.title
+     */
+    title?: FhirString;
+    /**
+     * Publication status: draft | active | retired | unknown (1..1)
+     * @see https://hl7.org/fhir/R4/structuredefinition-definitions.html#StructureDefinition.status
+     */
+    status: PublicationStatus;
+    /**
+     * For testing purposes, not real usage (0..1)
+     * @see https://hl7.org/fhir/R4/structuredefinition-definitions.html#StructureDefinition.experimental
+     */
+    experimental?: FhirBoolean;
+    /**
+     * Date last changed (0..1)
+     * @see https://hl7.org/fhir/R4/structuredefinition-definitions.html#StructureDefinition.date
+     */
+    date?: FhirDateTime;
+    /**
+     * Name of the publisher (organization or individual) (0..1)
+     * @see https://hl7.org/fhir/R4/structuredefinition-definitions.html#StructureDefinition.publisher
+     */
+    publisher?: FhirString;
+    /**
+     * Contact details for the publisher (0..*)
+     * @see https://hl7.org/fhir/R4/structuredefinition-definitions.html#StructureDefinition.contact
+     */
+    contact?: ContactDetail[];
+    /**
+     * Natural language description of the structure definition (0..1)
+     * @see https://hl7.org/fhir/R4/structuredefinition-definitions.html#StructureDefinition.description
+     */
+    description?: FhirMarkdown;
+    /**
+     * The context that the content is intended to support (0..*)
+     * @see https://hl7.org/fhir/R4/structuredefinition-definitions.html#StructureDefinition.useContext
+     */
+    useContext?: UsageContext[];
+    /**
+     * Intended jurisdiction for structure definition (0..*)
+     * @see https://hl7.org/fhir/R4/structuredefinition-definitions.html#StructureDefinition.jurisdiction
+     */
+    jurisdiction?: CodeableConcept[];
+    /**
+     * Why this structure definition is defined (0..1)
+     * @see https://hl7.org/fhir/R4/structuredefinition-definitions.html#StructureDefinition.purpose
+     */
+    purpose?: FhirMarkdown;
+    /**
+     * Use and/or publishing restrictions (0..1)
+     * @see https://hl7.org/fhir/R4/structuredefinition-definitions.html#StructureDefinition.copyright
+     */
+    copyright?: FhirMarkdown;
+    /**
+     * Assist with indexing and finding (0..*)
+     * @see https://hl7.org/fhir/R4/structuredefinition-definitions.html#StructureDefinition.keyword
+     */
+    keyword?: Coding[];
+    /**
+     * FHIR Version this StructureDefinition targets (0..1)
+     * @see https://hl7.org/fhir/R4/structuredefinition-definitions.html#StructureDefinition.fhirVersion
+     */
+    fhirVersion?: FhirVersionCode;
+    /**
+     * External specification that the content is mapped to (0..*)
+     * @see https://hl7.org/fhir/R4/structuredefinition-definitions.html#StructureDefinition.mapping
+     */
+    mapping?: StructureDefinitionMapping[];
+    /**
+     * The kind of structure: primitive-type | complex-type | resource | logical (1..1)
+     *
+     * Determines the fundamental nature of the structure being defined.
+     * @see https://hl7.org/fhir/R4/structuredefinition-definitions.html#StructureDefinition.kind
+     */
+    kind: StructureDefinitionKind;
+    /**
+     * Whether the structure is abstract (1..1)
+     *
+     * Abstract types cannot be instantiated directly. For example,
+     * `DomainResource` is abstract — you cannot create a resource
+     * with `resourceType: "DomainResource"`.
+     * @see https://hl7.org/fhir/R4/structuredefinition-definitions.html#StructureDefinition.abstract
+     */
+    abstract: FhirBoolean;
+    /**
+     * If an extension, where it can be used in instances (0..*)
+     *
+     * Only meaningful when kind = 'resource' and type = 'Extension'.
+     * Defines the contexts in which the extension can appear.
+     * @see https://hl7.org/fhir/R4/structuredefinition-definitions.html#StructureDefinition.context
+     */
+    context?: StructureDefinitionContext[];
+    /**
+     * FHIRPath invariants — conditions that must be true for the
+     * extension to be valid in a given context (0..*)
+     *
+     * Only meaningful when kind = 'resource' and type = 'Extension'.
+     * @see https://hl7.org/fhir/R4/structuredefinition-definitions.html#StructureDefinition.contextInvariant
+     */
+    contextInvariant?: FhirString[];
+    /**
+     * Type defined or constrained by this structure (1..1)
+     *
+     * For base definitions (derivation = 'specialization'), this is the
+     * type being defined (e.g., 'Patient', 'Observation').
+     * For profiles (derivation = 'constraint'), this is the type being
+     * constrained (must match the type of the base definition).
+     * @see https://hl7.org/fhir/R4/structuredefinition-definitions.html#StructureDefinition.type
+     */
+    type: FhirUri;
+    /**
+     * Definition that this type is constrained/specialized from (0..1)
+     *
+     * The canonical URL of the base StructureDefinition. This forms the
+     * inheritance chain used in snapshot generation.
+     * - For specializations: points to the parent type
+     * - For constraints: points to the profile being constrained
+     * @see https://hl7.org/fhir/R4/structuredefinition-definitions.html#StructureDefinition.baseDefinition
+     */
+    baseDefinition?: FhirCanonical;
+    /**
+     * specialization | constraint (0..1)
+     *
+     * - `specialization`: defines a new type (e.g., Patient specializes DomainResource)
+     * - `constraint`: constrains an existing type (e.g., USCorePatient constrains Patient)
+     * @see https://hl7.org/fhir/R4/structuredefinition-definitions.html#StructureDefinition.derivation
+     */
+    derivation?: TypeDerivationRule;
+    /**
+     * Snapshot view of the structure (0..1)
+     *
+     * Contains the complete, flattened element tree with all constraints
+     * from the inheritance chain resolved. Generated by the snapshot
+     * generation algorithm (fhir-profile module).
+     * @see https://hl7.org/fhir/R4/structuredefinition-definitions.html#StructureDefinition.snapshot
+     */
+    snapshot?: StructureDefinitionSnapshot;
+    /**
+     * Differential constraints of the structure (0..1)
+     *
+     * Contains only the constraints that differ from the base definition.
+     * This is the authoring format — profiles are typically written as
+     * differentials to avoid repeating base constraints.
+     * @see https://hl7.org/fhir/R4/structuredefinition-definitions.html#StructureDefinition.differential
+     */
+    differential?: StructureDefinitionDifferential;
+}
+//# sourceMappingURL=structure-definition.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"structure-definition.d.ts","sourceRoot":"","sources":["../../../src/model/structure-definition.ts"],"names":[],"mappings":"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"}

package/dist/lib/parser/choice-type-parser.d.ts

@@ -0,0 +1,182 @@
+/**
+ * FHIR Choice Type [x] Parser
+ *
+ * Handles FHIR R4 choice type property dispatch. In FHIR JSON, a choice
+ * type element like `value[x]` does not appear as a single property.
+ * Instead, the property name includes a type suffix:
+ *
+ * ```json
+ * { "valueString": "hello" }
+ * { "valueQuantity": { "value": 42, "unit": "kg" } }
+ * ```
+ *
+ * This module:
+ * 1. Defines the `ChoiceTypeField` descriptor and `ChoiceValue` result type
+ * 2. Provides `extractChoiceValue()` to scan an object for matching properties
+ * 3. Detects multiple-value conflicts (e.g., both `valueString` and `valueBoolean`)
+ * 4. Consumes `_element` companions for primitive choice type variants
+ * 5. Maintains a registry of all known choice type fields in the model
+ *
+ * @see https://hl7.org/fhir/R4/formats.html#choice
+ * @see ADR-003: FHIR R4 Choice Type [x] Representation Strategy
+ * @module fhir-parser
+ */
+import type { ParseIssue } from './parse-error.js';
+/**
+ * Definition of a choice type [x] field.
+ *
+ * Each choice type field has a base name and a set of allowed type suffixes.
+ * The actual JSON property name is `baseName` + one of `allowedTypes`.
+ *
+ * @example
+ * ```typescript
+ * const field: ChoiceTypeField = {
+ *   baseName: 'value',
+ *   allowedTypes: ['String', 'Boolean', 'Integer', 'Quantity', ...],
+ * };
+ * // Matches: valueString, valueBoolean, valueInteger, valueQuantity, ...
+ * ```
+ */
+export interface ChoiceTypeField {
+    /** Base property name (e.g., "value", "defaultValue", "fixed") */
+    readonly baseName: string;
+    /** Allowed type suffixes (e.g., ["String", "Boolean", "Quantity"]) */
+    readonly allowedTypes: readonly string[];
+}
+/**
+ * Parsed choice type value.
+ *
+ * Preserves the original JSON property name for round-trip serialization.
+ */
+export interface ChoiceValue {
+    /** Type suffix (e.g., "String", "Quantity") */
+    readonly typeName: string;
+    /** The actual value from JSON */
+    readonly value: unknown;
+    /** Original JSON property name (e.g., "valueString") — for serialization */
+    readonly propertyName: string;
+    /** _element companion data, if present */
+    readonly elementExtension?: unknown;
+}
+/**
+ * Extract a choice type value from a JSON object.
+ *
+ * Scans all properties of `obj` looking for keys that match
+ * `choiceField.baseName` + one of `choiceField.allowedTypes`.
+ *
+ * Handles:
+ * - Single match → returns `ChoiceValue` with type info
+ * - No match → returns `null` (field not present)
+ * - Multiple matches → returns first match + `MULTIPLE_CHOICE_VALUES` error
+ * - Unknown suffix → `INVALID_CHOICE_TYPE` error
+ * - `_element` companion → consumed and attached to result
+ *
+ * @param obj - The raw JSON object to scan
+ * @param choiceField - The choice type field definition
+ * @param path - JSON path for error reporting
+ * @returns Extracted value, issues, and list of consumed keys
+ *
+ * @example
+ * ```typescript
+ * const field = { baseName: 'value', allowedTypes: ['String', 'Boolean'] };
+ * const obj = { valueString: 'hello' };
+ * const { result, consumedKeys } = extractChoiceValue(obj, field, 'Extension');
+ * // result = { typeName: 'String', value: 'hello', propertyName: 'valueString' }
+ * // consumedKeys = ['valueString']
+ * ```
+ */
+export declare function extractChoiceValue(obj: Record<string, unknown>, choiceField: ChoiceTypeField, path: string): {
+    result: ChoiceValue | null;
+    issues: ParseIssue[];
+    consumedKeys: string[];
+};
+/**
+ * Extract all choice type values from a JSON object for a given set of fields.
+ *
+ * Convenience function that calls `extractChoiceValue` for each field definition
+ * and aggregates results.
+ *
+ * @param obj - The raw JSON object
+ * @param choiceFields - Array of choice type field definitions
+ * @param path - JSON path for error reporting
+ * @returns Map of baseName → ChoiceValue, all issues, and all consumed keys
+ */
+export declare function extractAllChoiceValues(obj: Record<string, unknown>, choiceFields: readonly ChoiceTypeField[], path: string): {
+    results: ReadonlyMap<string, ChoiceValue>;
+    issues: ParseIssue[];
+    consumedKeys: string[];
+};
+/**
+ * All FHIR R4 data types that can appear as choice type suffixes.
+ *
+ * This covers all primitive types (capitalized) and common complex types.
+ * Used by choice fields that allow "any FHIR data type" (~50 types).
+ *
+ * @see https://hl7.org/fhir/R4/datatypes.html
+ */
+export declare const ALL_FHIR_TYPE_SUFFIXES: readonly string[];
+/**
+ * Type suffixes for minValue[x] and maxValue[x] fields.
+ *
+ * These are restricted to orderable types only.
+ * @see https://hl7.org/fhir/R4/elementdefinition-definitions.html#ElementDefinition.minValue_x_
+ */
+export declare const MIN_MAX_VALUE_TYPE_SUFFIXES: readonly string[];
+/**
+ * Type suffixes for UsageContext.value[x].
+ * @see https://hl7.org/fhir/R4/metadatatypes-definitions.html#UsageContext.value_x_
+ */
+export declare const USAGE_CONTEXT_VALUE_TYPE_SUFFIXES: readonly string[];
+/**
+ * All known choice type fields in the fhir-model, grouped by host type.
+ *
+ * This registry is used by the parser to know which choice type fields
+ * exist on each type, enabling proper extraction and validation.
+ *
+ * Coverage: 8 choice type fields across 4 host types.
+ *
+ * | Host Type                  | Base Name      | Allowed Types |
+ * |----------------------------|----------------|---------------|
+ * | Extension                  | value          | All (~50)     |
+ * | UsageContext               | value          | 4             |
+ * | ElementDefinition          | defaultValue   | All (~50)     |
+ * | ElementDefinition          | fixed          | All (~50)     |
+ * | ElementDefinition          | pattern        | All (~50)     |
+ * | ElementDefinition          | minValue       | 9             |
+ * | ElementDefinition          | maxValue       | 9             |
+ * | ElementDefinitionExample   | value          | All (~50)     |
+ */
+export declare const CHOICE_TYPE_FIELDS: ReadonlyMap<string, readonly ChoiceTypeField[]>;
+/**
+ * Get the choice type base names for a given host type.
+ *
+ * Returns an array of base names (e.g., `['value']` for Extension,
+ * `['defaultValue', 'fixed', 'pattern', 'minValue', 'maxValue']` for
+ * ElementDefinition).
+ *
+ * This can be used to pass `choiceFieldBases` to `parseComplexObject`
+ * for Pass 3 key matching, or for other custom parsing logic.
+ *
+ * @param hostType - The FHIR type name (e.g., "Extension", "ElementDefinition")
+ * @returns Array of base names, or empty array if no choice fields
+ */
+export declare function getChoiceFieldBases(hostType: string): readonly string[];
+/**
+ * Get the choice type field definitions for a given host type.
+ *
+ * @param hostType - The FHIR type name
+ * @returns Array of ChoiceTypeField definitions, or empty array
+ */
+export declare function getChoiceFields(hostType: string): readonly ChoiceTypeField[];
+/**
+ * Check whether a property name matches any choice type field for a host type.
+ *
+ * @param key - The JSON property name to check
+ * @param hostType - The FHIR type name
+ * @returns The matching ChoiceTypeField and extracted suffix, or null
+ */
+export declare function matchChoiceTypeProperty(key: string, hostType: string): {
+    field: ChoiceTypeField;
+    suffix: string;
+} | null;
+//# sourceMappingURL=choice-type-parser.d.ts.map

package/dist/lib/parser/choice-type-parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"choice-type-parser.d.ts","sourceRoot":"","sources":["../../../src/parser/choice-type-parser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAQnD;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,eAAe;IAC9B,kEAAkE;IAClE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,sEAAsE;IACtE,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;CAC1C;AAED;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,+CAA+C;IAC/C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,iCAAiC;IACjC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,4EAA4E;IAC5E,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,0CAA0C;IAC1C,QAAQ,CAAC,gBAAgB,CAAC,EAAE,OAAO,CAAC;CACrC;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,WAAW,EAAE,eAAe,EAC5B,IAAI,EAAE,MAAM,GACX;IAAE,MAAM,EAAE,WAAW,GAAG,IAAI,CAAC;IAAC,MAAM,EAAE,UAAU,EAAE,CAAC;IAAC,YAAY,EAAE,MAAM,EAAE,CAAA;CAAE,CA4E9E;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,YAAY,EAAE,SAAS,eAAe,EAAE,EACxC,IAAI,EAAE,MAAM,GACX;IACD,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IAC1C,MAAM,EAAE,UAAU,EAAE,CAAC;IACrB,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB,CAgBA;AAMD;;;;;;;GAOG;AACH,eAAO,MAAM,sBAAsB,EAAE,SAAS,MAAM,EAwD1C,CAAC;AAEX;;;;;GAKG;AACH,eAAO,MAAM,2BAA2B,EAAE,SAAS,MAAM,EAU/C,CAAC;AAEX;;;GAGG;AACH,eAAO,MAAM,iCAAiC,EAAE,SAAS,MAAM,EAKrD,CAAC;AAMX;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,kBAAkB,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,eAAe,EAAE,CAgC7E,CAAC;AAEH;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAIvE;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,eAAe,EAAE,CAE5E;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACrC,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,GACf;IAAE,KAAK,EAAE,eAAe,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAenD"}

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

@@ -0,0 +1,16 @@
+/**
+ * `fhir-parser` — Public API
+ *
+ * Unified exports for the FHIR JSON parsing and serialization module.
+ * Internal helpers (primitive merging, choice extraction, validation) are
+ * intentionally kept private.
+ *
+ * @packageDocumentation
+ */
+export type { ParseSeverity, ParseErrorCode, ParseIssue, ParseResult } from './parse-error.js';
+export { parseSuccess, parseFailure, createIssue, hasErrors } from './parse-error.js';
+export { parseFhirJson, parseFhirObject } from './json-parser.js';
+export { parseStructureDefinition, parseElementDefinition } from './structure-definition-parser.js';
+export { serializeToFhirJson, serializeToFhirObject } from './serializer.js';
+export type { ChoiceValue, ChoiceTypeField } from './choice-type-parser.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/parser/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/F,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAGtF,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAGlE,OAAO,EAAE,wBAAwB,EAAE,sBAAsB,EAAE,MAAM,kCAAkC,CAAC;AAGpG,OAAO,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAG7E,YAAY,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC"}

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

@@ -0,0 +1,171 @@
+/**
+ * Core FHIR JSON Parser Engine
+ *
+ * Main entry point for parsing FHIR R4 JSON into TypeScript model types.
+ * Handles JSON.parse, resourceType dispatch, and provides the generic
+ * complex-type parsing infrastructure used by all downstream parsers.
+ *
+ * Architecture:
+ * ```
+ * parseFhirJson(string)
+ *   └─ parseFhirObject(unknown)
+ *        ├─ validateRootObject()
+ *        ├─ extractResourceType()
+ *        └─ dispatch by resourceType:
+ *             ├─ "StructureDefinition" → parseStructureDefinitionObject() [Task 2.5]
+ *             └─ other → parseGenericResource()
+ * ```
+ *
+ * This module also exports lower-level utilities (`parseComplexObject`,
+ * `isPlainObject`, path helpers) that Task 2.3–2.5 build upon.
+ *
+ * @module fhir-parser
+ */
+import type { Resource } from '../model/primitives.js';
+import { type ParseResult, type ParseIssue } from './parse-error.js';
+/**
+ * A plain JSON object — `Record<string, unknown>` that is not null and not an array.
+ *
+ * This is the fundamental input shape for all FHIR complex type parsers.
+ */
+export type JsonObject = Record<string, unknown>;
+/**
+ * Check whether a value is a plain JSON object (non-null, non-array, typeof "object").
+ */
+export declare function isPlainObject(value: unknown): value is JsonObject;
+/**
+ * Append a property name to a JSON path.
+ *
+ * @example
+ * pathAppend("Patient", "name") // "Patient.name"
+ * pathAppend("$", "resourceType") // "$.resourceType"
+ */
+export declare function pathAppend(base: string, property: string): string;
+/**
+ * Append an array index to a JSON path.
+ *
+ * @example
+ * pathIndex("Patient.name", 0) // "Patient.name[0]"
+ */
+export declare function pathIndex(base: string, index: number): string;
+/**
+ * Metadata describing a single property of a FHIR complex type.
+ *
+ * Used by {@link parseComplexObject} to know how to interpret each JSON key.
+ */
+export interface PropertyDescriptor {
+    /** The property name as it appears in the TypeScript interface */
+    readonly name: string;
+    /**
+     * Whether this property holds a primitive FHIR type.
+     *
+     * When true, the parser will look for a companion `_name` property
+     * carrying id/extension metadata (FHIR primitive element split).
+     */
+    readonly isPrimitive: boolean;
+    /**
+     * The FHIR primitive type name (e.g., `'string'`, `'boolean'`, `'id'`).
+     *
+     * Required when `isPrimitive` is true. Used by `mergePrimitiveElement`
+     * to validate the JavaScript type of the value (string, number, or boolean).
+     * Defaults to `'string'` when not specified.
+     */
+    readonly fhirType?: string;
+    /**
+     * Whether this property is an array (max cardinality > 1).
+     *
+     * FHIR JSON always uses arrays for repeating elements, even when
+     * only one value is present.
+     */
+    readonly isArray: boolean;
+    /**
+     * Parser function for complex-type values.
+     *
+     * Called for each value (or array element) to recursively parse
+     * nested complex types. If `undefined`, the value is passed through
+     * as-is (used for primitives and `unknown` choice-type placeholders).
+     */
+    readonly parseElement?: (obj: JsonObject, path: string) => {
+        result: unknown;
+        issues: ParseIssue[];
+    };
+}
+/**
+ * A schema describing all known properties of a FHIR complex type.
+ *
+ * Maps property names to their descriptors. Properties not in this map
+ * are reported as `UNEXPECTED_PROPERTY` warnings.
+ *
+ * Choice type `[x]` fields are NOT included here — they are handled
+ * separately by the choice-type-parser (Task 2.4).
+ */
+export type PropertySchema = ReadonlyMap<string, PropertyDescriptor>;
+/**
+ * Result of parsing a complex object — the assembled result record
+ * plus any issues collected during parsing.
+ */
+export interface ComplexParseResult {
+    readonly result: JsonObject;
+    readonly issues: ParseIssue[];
+}
+/**
+ * Parse a FHIR complex type JSON object using a property schema.
+ *
+ * This is the workhorse function that all type-specific parsers delegate to.
+ * It uses a 4-pass strategy to process the JSON object's keys:
+ *
+ * 1. **Pass 1: Known properties** — maps non-primitive properties into the result,
+ *    recursing for complex types. Primitive properties are marked as consumed but
+ *    their values are deferred to Pass 2 for `_element` merging.
+ * 2. **Pass 2: Primitive `_element` merging** — for each primitive property in the
+ *    schema, calls `mergePrimitiveElement` (or `mergePrimitiveArray`) from
+ *    primitive-parser to merge the JSON value with its `_name` companion carrying
+ *    id/extension metadata.
+ * 3. **Pass 3: Choice type `[x]`** — identifies choice type properties by matching
+ *    `choiceFieldBases` prefixes with uppercase type suffixes, stores values as-is
+ *    (full extraction delegated to choice-type-parser in Task 2.4)
+ * 4. **Pass 4: Unexpected properties** — emits `UNEXPECTED_PROPERTY` warnings for
+ *    any remaining unconsumed keys
+ *
+ * @param obj - The raw JSON object to parse
+ * @param path - Current JSON path (for error reporting)
+ * @param schema - Property descriptors for this type
+ * @param choiceFieldBases - Base names of choice type `[x]` fields (e.g., `["value", "defaultValue"]`).
+ *   Any key starting with one of these bases is treated as a potential choice type
+ *   property and NOT flagged as unexpected. Actual choice type extraction is
+ *   deferred to Task 2.4.
+ */
+export declare function parseComplexObject(obj: JsonObject, path: string, schema: PropertySchema, choiceFieldBases?: readonly string[]): ComplexParseResult;
+/**
+ * Parse a FHIR JSON string into a Resource object.
+ *
+ * This is the main entry point for the parser. It:
+ * 1. Calls `JSON.parse()` with error capture
+ * 2. Delegates to {@link parseFhirObject} for structural parsing
+ *
+ * Stage-1 supports dedicated parsing for `StructureDefinition` (Task 2.5).
+ * All other resource types are parsed generically.
+ *
+ * @param json - A FHIR JSON string
+ * @returns A `ParseResult` containing the parsed `Resource` or error details
+ *
+ * @example
+ * ```typescript
+ * const result = parseFhirJson('{"resourceType":"Patient","id":"123"}');
+ * if (result.success) {
+ *   console.log(result.data.resourceType); // "Patient"
+ * }
+ * ```
+ */
+export declare function parseFhirJson(json: string): ParseResult<Resource>;
+/**
+ * Parse an already-parsed JSON value into a Resource object.
+ *
+ * Use this when you already have a JavaScript object (e.g., from a database
+ * or from `JSON.parse()` called externally).
+ *
+ * @param obj - An unknown value (expected to be a plain JSON object with `resourceType`)
+ * @returns A `ParseResult` containing the parsed `Resource` or error details
+ */
+export declare function parseFhirObject(obj: unknown): ParseResult<Resource>;
+//# sourceMappingURL=json-parser.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"json-parser.d.ts","sourceRoot":"","sources":["../../../src/parser/json-parser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,UAAU,EAKhB,MAAM,kBAAkB,CAAC;AAQ1B;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEjD;;GAEG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,UAAU,CAEjE;AAMD;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEjE;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAE7D;AAMD;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,kEAAkE;IAClE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAE9B;;;;;;OAMG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAE3B;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAE1B;;;;;;OAMG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,KAAK;QAAE,MAAM,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,UAAU,EAAE,CAAA;KAAE,CAAC;CACtG;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,cAAc,GAAG,WAAW,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;AAErE;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,UAAU,EAAE,CAAC;CAC/B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,UAAU,EACf,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,cAAc,EACtB,gBAAgB,GAAE,SAAS,MAAM,EAAO,GACvC,kBAAkB,CAgIpB;AAoHD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC,QAAQ,CAAC,CAcjE;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,GAAG,WAAW,CAAC,QAAQ,CAAC,CA+DnE"}