fhir-runtime 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (124) hide show
  1. package/CHANGELOG.md +211 -0
  2. package/LICENSE +21 -0
  3. package/README.md +261 -0
  4. package/dist/cjs/index.cjs +7368 -0
  5. package/dist/cjs/index.cjs.map +7 -0
  6. package/dist/cjs/index.d.ts +4224 -0
  7. package/dist/cjs/package.json +5 -0
  8. package/dist/esm/index.d.ts +4224 -0
  9. package/dist/esm/index.mjs +7250 -0
  10. package/dist/esm/index.mjs.map +7 -0
  11. package/dist/esm/package.json +5 -0
  12. package/dist/index.d.ts +4224 -0
  13. package/dist/lib/context/bundle-loader.d.ts +124 -0
  14. package/dist/lib/context/bundle-loader.d.ts.map +1 -0
  15. package/dist/lib/context/core-definitions/index.d.ts +72 -0
  16. package/dist/lib/context/core-definitions/index.d.ts.map +1 -0
  17. package/dist/lib/context/errors.d.ts +114 -0
  18. package/dist/lib/context/errors.d.ts.map +1 -0
  19. package/dist/lib/context/fhir-context.d.ts +72 -0
  20. package/dist/lib/context/fhir-context.d.ts.map +1 -0
  21. package/dist/lib/context/index.d.ts +21 -0
  22. package/dist/lib/context/index.d.ts.map +1 -0
  23. package/dist/lib/context/inheritance-resolver.d.ts +98 -0
  24. package/dist/lib/context/inheritance-resolver.d.ts.map +1 -0
  25. package/dist/lib/context/inner-type-extractor.d.ts +80 -0
  26. package/dist/lib/context/inner-type-extractor.d.ts.map +1 -0
  27. package/dist/lib/context/loaders/composite-loader.d.ts +47 -0
  28. package/dist/lib/context/loaders/composite-loader.d.ts.map +1 -0
  29. package/dist/lib/context/loaders/file-loader.d.ts +47 -0
  30. package/dist/lib/context/loaders/file-loader.d.ts.map +1 -0
  31. package/dist/lib/context/loaders/index.d.ts +11 -0
  32. package/dist/lib/context/loaders/index.d.ts.map +1 -0
  33. package/dist/lib/context/loaders/memory-loader.d.ts +42 -0
  34. package/dist/lib/context/loaders/memory-loader.d.ts.map +1 -0
  35. package/dist/lib/context/registry.d.ts +116 -0
  36. package/dist/lib/context/registry.d.ts.map +1 -0
  37. package/dist/lib/context/types.d.ts +266 -0
  38. package/dist/lib/context/types.d.ts.map +1 -0
  39. package/dist/lib/fhirpath/atoms.d.ts +228 -0
  40. package/dist/lib/fhirpath/atoms.d.ts.map +1 -0
  41. package/dist/lib/fhirpath/cache.d.ts +79 -0
  42. package/dist/lib/fhirpath/cache.d.ts.map +1 -0
  43. package/dist/lib/fhirpath/date.d.ts +17 -0
  44. package/dist/lib/fhirpath/date.d.ts.map +1 -0
  45. package/dist/lib/fhirpath/functions.d.ts +28 -0
  46. package/dist/lib/fhirpath/functions.d.ts.map +1 -0
  47. package/dist/lib/fhirpath/index.d.ts +20 -0
  48. package/dist/lib/fhirpath/index.d.ts.map +1 -0
  49. package/dist/lib/fhirpath/lexer/parse.d.ts +100 -0
  50. package/dist/lib/fhirpath/lexer/parse.d.ts.map +1 -0
  51. package/dist/lib/fhirpath/lexer/tokenize.d.ts +80 -0
  52. package/dist/lib/fhirpath/lexer/tokenize.d.ts.map +1 -0
  53. package/dist/lib/fhirpath/parse.d.ts +101 -0
  54. package/dist/lib/fhirpath/parse.d.ts.map +1 -0
  55. package/dist/lib/fhirpath/tokenize.d.ts +20 -0
  56. package/dist/lib/fhirpath/tokenize.d.ts.map +1 -0
  57. package/dist/lib/fhirpath/types.d.ts +111 -0
  58. package/dist/lib/fhirpath/types.d.ts.map +1 -0
  59. package/dist/lib/fhirpath/utils.d.ts +81 -0
  60. package/dist/lib/fhirpath/utils.d.ts.map +1 -0
  61. package/dist/lib/index.d.ts +24 -0
  62. package/dist/lib/index.d.ts.map +1 -0
  63. package/dist/lib/model/canonical-profile.d.ts +381 -0
  64. package/dist/lib/model/canonical-profile.d.ts.map +1 -0
  65. package/dist/lib/model/element-definition.d.ts +503 -0
  66. package/dist/lib/model/element-definition.d.ts.map +1 -0
  67. package/dist/lib/model/index.d.ts +14 -0
  68. package/dist/lib/model/index.d.ts.map +1 -0
  69. package/dist/lib/model/primitives.d.ts +464 -0
  70. package/dist/lib/model/primitives.d.ts.map +1 -0
  71. package/dist/lib/model/structure-definition.d.ts +263 -0
  72. package/dist/lib/model/structure-definition.d.ts.map +1 -0
  73. package/dist/lib/parser/choice-type-parser.d.ts +182 -0
  74. package/dist/lib/parser/choice-type-parser.d.ts.map +1 -0
  75. package/dist/lib/parser/index.d.ts +16 -0
  76. package/dist/lib/parser/index.d.ts.map +1 -0
  77. package/dist/lib/parser/json-parser.d.ts +171 -0
  78. package/dist/lib/parser/json-parser.d.ts.map +1 -0
  79. package/dist/lib/parser/parse-error.d.ts +146 -0
  80. package/dist/lib/parser/parse-error.d.ts.map +1 -0
  81. package/dist/lib/parser/primitive-parser.d.ts +136 -0
  82. package/dist/lib/parser/primitive-parser.d.ts.map +1 -0
  83. package/dist/lib/parser/serializer.d.ts +64 -0
  84. package/dist/lib/parser/serializer.d.ts.map +1 -0
  85. package/dist/lib/parser/structure-definition-parser.d.ts +63 -0
  86. package/dist/lib/parser/structure-definition-parser.d.ts.map +1 -0
  87. package/dist/lib/profile/canonical-builder.d.ts +87 -0
  88. package/dist/lib/profile/canonical-builder.d.ts.map +1 -0
  89. package/dist/lib/profile/constraint-merger.d.ts +100 -0
  90. package/dist/lib/profile/constraint-merger.d.ts.map +1 -0
  91. package/dist/lib/profile/element-merger.d.ts +80 -0
  92. package/dist/lib/profile/element-merger.d.ts.map +1 -0
  93. package/dist/lib/profile/element-sorter.d.ts +81 -0
  94. package/dist/lib/profile/element-sorter.d.ts.map +1 -0
  95. package/dist/lib/profile/errors.d.ts +150 -0
  96. package/dist/lib/profile/errors.d.ts.map +1 -0
  97. package/dist/lib/profile/index.d.ts +27 -0
  98. package/dist/lib/profile/index.d.ts.map +1 -0
  99. package/dist/lib/profile/path-utils.d.ts +180 -0
  100. package/dist/lib/profile/path-utils.d.ts.map +1 -0
  101. package/dist/lib/profile/slicing-handler.d.ts +121 -0
  102. package/dist/lib/profile/slicing-handler.d.ts.map +1 -0
  103. package/dist/lib/profile/snapshot-generator.d.ts +73 -0
  104. package/dist/lib/profile/snapshot-generator.d.ts.map +1 -0
  105. package/dist/lib/profile/types.d.ts +220 -0
  106. package/dist/lib/profile/types.d.ts.map +1 -0
  107. package/dist/lib/validator/errors.d.ts +83 -0
  108. package/dist/lib/validator/errors.d.ts.map +1 -0
  109. package/dist/lib/validator/index.d.ts +23 -0
  110. package/dist/lib/validator/index.d.ts.map +1 -0
  111. package/dist/lib/validator/invariant-validator.d.ts +62 -0
  112. package/dist/lib/validator/invariant-validator.d.ts.map +1 -0
  113. package/dist/lib/validator/path-extractor.d.ts +123 -0
  114. package/dist/lib/validator/path-extractor.d.ts.map +1 -0
  115. package/dist/lib/validator/slicing-validator.d.ts +119 -0
  116. package/dist/lib/validator/slicing-validator.d.ts.map +1 -0
  117. package/dist/lib/validator/structure-validator.d.ts +74 -0
  118. package/dist/lib/validator/structure-validator.d.ts.map +1 -0
  119. package/dist/lib/validator/types.d.ts +288 -0
  120. package/dist/lib/validator/types.d.ts.map +1 -0
  121. package/dist/lib/validator/validation-rules.d.ts +198 -0
  122. package/dist/lib/validator/validation-rules.d.ts.map +1 -0
  123. package/dist/tsdoc-metadata.json +11 -0
  124. package/package.json +76 -0
@@ -0,0 +1,47 @@
1
+ /**
2
+ * fhir-context — FileSystemLoader
3
+ *
4
+ * Loads StructureDefinitions from local JSON files on disk.
5
+ * Uses the fhir-parser module to parse raw JSON into typed models.
6
+ *
7
+ * URL-to-path mapping strategy:
8
+ * - Extract the resource name from the canonical URL tail
9
+ * (e.g., `http://hl7.org/fhir/StructureDefinition/Patient` → `Patient`)
10
+ * - Look for `{basePath}/{name}.json`
11
+ *
12
+ * @module fhir-context
13
+ */
14
+ import type { StructureDefinition } from '../../model/index.js';
15
+ import type { StructureDefinitionLoader } from '../types.js';
16
+ /**
17
+ * Extract the resource name from a canonical URL.
18
+ *
19
+ * @param url - e.g. `"http://hl7.org/fhir/StructureDefinition/Patient"`
20
+ * @returns The last path segment, e.g. `"Patient"`
21
+ */
22
+ export declare function extractResourceName(url: string): string;
23
+ /**
24
+ * A loader that resolves StructureDefinitions from local JSON files.
25
+ *
26
+ * @example
27
+ * ```typescript
28
+ * const loader = new FileSystemLoader('/path/to/definitions');
29
+ * const sd = await loader.load('http://hl7.org/fhir/StructureDefinition/Patient');
30
+ * // Reads /path/to/definitions/Patient.json
31
+ * ```
32
+ */
33
+ export declare class FileSystemLoader implements StructureDefinitionLoader {
34
+ private readonly _basePath;
35
+ /**
36
+ * @param basePath - Directory containing `{ResourceName}.json` files
37
+ */
38
+ constructor(basePath: string);
39
+ load(url: string): Promise<StructureDefinition | null>;
40
+ canLoad(url: string): boolean;
41
+ getSourceType(): string;
42
+ /**
43
+ * The base directory this loader reads from.
44
+ */
45
+ get basePath(): string;
46
+ }
47
+ //# sourceMappingURL=file-loader.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"file-loader.d.ts","sourceRoot":"","sources":["../../../../src/context/loaders/file-loader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAMH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAChE,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAC;AAI7D;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAGvD;AAED;;;;;;;;;GASG;AACH,qBAAa,gBAAiB,YAAW,yBAAyB;IAChE,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IAEnC;;OAEG;gBACS,QAAQ,EAAE,MAAM;IAItB,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,GAAG,IAAI,CAAC;IAiC5D,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAM7B,aAAa,IAAI,MAAM;IAIvB;;OAEG;IACH,IAAI,QAAQ,IAAI,MAAM,CAErB;CACF"}
@@ -0,0 +1,11 @@
1
+ /**
2
+ * fhir-context — Loader Barrel Exports
3
+ *
4
+ * Re-exports all concrete {@link StructureDefinitionLoader} implementations.
5
+ *
6
+ * @module fhir-context
7
+ */
8
+ export { MemoryLoader } from './memory-loader.js';
9
+ export { FileSystemLoader, extractResourceName } from './file-loader.js';
10
+ export { CompositeLoader } from './composite-loader.js';
11
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/context/loaders/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AACzE,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC"}
@@ -0,0 +1,42 @@
1
+ /**
2
+ * fhir-context — MemoryLoader
3
+ *
4
+ * Loads StructureDefinitions from an in-memory Map.
5
+ * Primary use cases:
6
+ * - Unit testing (inject known definitions)
7
+ * - Preloaded core FHIR R4 definitions
8
+ *
9
+ * @module fhir-context
10
+ */
11
+ import type { StructureDefinition } from '../../model/index.js';
12
+ import type { StructureDefinitionLoader } from '../types.js';
13
+ /**
14
+ * A loader that resolves StructureDefinitions from an in-memory Map.
15
+ *
16
+ * The map is keyed by canonical URL. Lookups are synchronous but the
17
+ * interface returns a Promise for consistency with other loaders.
18
+ *
19
+ * @example
20
+ * ```typescript
21
+ * const definitions = new Map<string, StructureDefinition>();
22
+ * definitions.set('http://hl7.org/fhir/StructureDefinition/Patient', patientSD);
23
+ * const loader = new MemoryLoader(definitions);
24
+ * ```
25
+ */
26
+ export declare class MemoryLoader implements StructureDefinitionLoader {
27
+ private readonly _definitions;
28
+ /**
29
+ * @param definitions - Map of canonical URL → StructureDefinition.
30
+ * The map is **not** copied; mutations to the
31
+ * original map are visible to the loader.
32
+ */
33
+ constructor(definitions: Map<string, StructureDefinition>);
34
+ load(url: string): Promise<StructureDefinition | null>;
35
+ canLoad(url: string): boolean;
36
+ getSourceType(): string;
37
+ /**
38
+ * Number of definitions currently held in the map.
39
+ */
40
+ get size(): number;
41
+ }
42
+ //# sourceMappingURL=memory-loader.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"memory-loader.d.ts","sourceRoot":"","sources":["../../../../src/context/loaders/memory-loader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAChE,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAC;AAE7D;;;;;;;;;;;;GAYG;AACH,qBAAa,YAAa,YAAW,yBAAyB;IAC5D,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAmC;IAEhE;;;;OAIG;gBACS,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,mBAAmB,CAAC;IAInD,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,GAAG,IAAI,CAAC;IAI5D,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAI7B,aAAa,IAAI,MAAM;IAIvB;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;CACF"}
@@ -0,0 +1,116 @@
1
+ /**
2
+ * fhir-context — StructureDefinition Registry
3
+ *
4
+ * In-memory registry for storing and querying StructureDefinitions.
5
+ * Keyed by canonical URL with optional `|version` support.
6
+ *
7
+ * This is an internal component used by {@link FhirContextImpl}.
8
+ * It is not exported from the public API.
9
+ *
10
+ * @module fhir-context
11
+ */
12
+ import type { StructureDefinition } from '../model/index.js';
13
+ /**
14
+ * Parse a canonical URL that may contain a `|version` suffix.
15
+ *
16
+ * @param urlWithVersion - e.g. `"http://hl7.org/fhir/StructureDefinition/Patient|4.0.1"`
17
+ * @returns `{ url, version }` where `version` is `undefined` if absent
18
+ */
19
+ export declare function parseVersionedUrl(urlWithVersion: string): {
20
+ url: string;
21
+ version: string | undefined;
22
+ };
23
+ /**
24
+ * Build a versioned registry key from URL and version.
25
+ *
26
+ * @param url - Canonical URL (without version)
27
+ * @param version - Semantic version string, or `undefined`
28
+ * @returns `"url|version"` if version is present, otherwise just `"url"`
29
+ */
30
+ export declare function buildVersionedKey(url: string, version: string | undefined): string;
31
+ /**
32
+ * In-memory registry for StructureDefinitions.
33
+ *
34
+ * Storage strategy:
35
+ * - **Primary map**: keyed by `url|version` (exact match)
36
+ * - **Latest map**: keyed by bare `url` → points to the most recently
37
+ * registered version (for unversioned lookups)
38
+ *
39
+ * When a lookup uses a bare URL (no `|version`), the latest map is consulted.
40
+ * When a lookup uses `url|version`, the primary map is used for exact match.
41
+ */
42
+ export declare class StructureDefinitionRegistry {
43
+ /** Primary storage: `url|version` → StructureDefinition */
44
+ private readonly _entries;
45
+ /** Latest-version index: bare `url` → `url|version` key in _entries */
46
+ private readonly _latestIndex;
47
+ /** Statistics counters */
48
+ private _queryCount;
49
+ private _hitCount;
50
+ /**
51
+ * Register a StructureDefinition.
52
+ *
53
+ * Validates that the definition has a `url` field. If a definition with
54
+ * the same URL (and version) already exists, it is silently replaced.
55
+ *
56
+ * @param sd - The StructureDefinition to register
57
+ * @throws {@link InvalidStructureDefinitionError} if `sd.url` is missing
58
+ */
59
+ register(sd: StructureDefinition): void;
60
+ /**
61
+ * Remove a StructureDefinition by canonical URL.
62
+ *
63
+ * @param urlWithVersion - Canonical URL (with optional `|version`)
64
+ * @returns `true` if a definition was removed, `false` if not found
65
+ */
66
+ delete(urlWithVersion: string): boolean;
67
+ /**
68
+ * Remove all entries and reset statistics.
69
+ */
70
+ clear(): void;
71
+ /**
72
+ * Retrieve a StructureDefinition by canonical URL.
73
+ *
74
+ * - If `urlWithVersion` contains `|version`, performs exact match.
75
+ * - If no version, returns the latest registered version.
76
+ *
77
+ * @param urlWithVersion - Canonical URL (with optional `|version`)
78
+ * @returns The StructureDefinition, or `undefined` if not found
79
+ */
80
+ get(urlWithVersion: string): StructureDefinition | undefined;
81
+ /**
82
+ * Check whether a StructureDefinition is registered.
83
+ *
84
+ * @param urlWithVersion - Canonical URL (with optional `|version`)
85
+ */
86
+ has(urlWithVersion: string): boolean;
87
+ /**
88
+ * Total number of registered StructureDefinitions.
89
+ */
90
+ get size(): number;
91
+ /**
92
+ * Return all registered canonical URLs (including version suffixes).
93
+ */
94
+ getAllKeys(): string[];
95
+ /**
96
+ * Return all registered bare URLs (without version suffixes).
97
+ */
98
+ getAllUrls(): string[];
99
+ /**
100
+ * Total number of `get()` calls.
101
+ */
102
+ get queryCount(): number;
103
+ /**
104
+ * Number of `get()` calls that returned a result (cache hits).
105
+ */
106
+ get hitCount(): number;
107
+ /**
108
+ * Number of `get()` calls that returned `undefined` (cache misses).
109
+ */
110
+ get missCount(): number;
111
+ /**
112
+ * Cache hit ratio (0–1). Returns 0 if no queries have been made.
113
+ */
114
+ get hitRate(): number;
115
+ }
116
+ //# sourceMappingURL=registry.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../../src/context/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAO7D;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,cAAc,EAAE,MAAM,GAAG;IACzD,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;CAC7B,CASA;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,GAAG,SAAS,GAC1B,MAAM,CAER;AAMD;;;;;;;;;;GAUG;AACH,qBAAa,2BAA2B;IACtC,2DAA2D;IAC3D,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA0C;IAEnE,uEAAuE;IACvE,OAAO,CAAC,QAAQ,CAAC,YAAY,CAA6B;IAE1D,0BAA0B;IAC1B,OAAO,CAAC,WAAW,CAAK;IACxB,OAAO,CAAC,SAAS,CAAK;IAMtB;;;;;;;;OAQG;IACH,QAAQ,CAAC,EAAE,EAAE,mBAAmB,GAAG,IAAI;IAqBvC;;;;;OAKG;IACH,MAAM,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO;IAyBvC;;OAEG;IACH,KAAK,IAAI,IAAI;IAWb;;;;;;;;OAQG;IACH,GAAG,CAAC,cAAc,EAAE,MAAM,GAAG,mBAAmB,GAAG,SAAS;IAuB5D;;;;OAIG;IACH,GAAG,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO;IAUpC;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;OAEG;IACH,UAAU,IAAI,MAAM,EAAE;IAItB;;OAEG;IACH,UAAU,IAAI,MAAM,EAAE;IAQtB;;OAEG;IACH,IAAI,UAAU,IAAI,MAAM,CAEvB;IAED;;OAEG;IACH,IAAI,QAAQ,IAAI,MAAM,CAErB;IAED;;OAEG;IACH,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED;;OAEG;IACH,IAAI,OAAO,IAAI,MAAM,CAEpB;CACF"}
@@ -0,0 +1,266 @@
1
+ /**
2
+ * fhir-context — Public Interfaces & Types
3
+ *
4
+ * Defines the core abstractions for the FHIR context module:
5
+ * - {@link FhirContext} — central registry and lifecycle manager
6
+ * - {@link StructureDefinitionLoader} — pluggable loading strategy
7
+ * - {@link LoaderOptions} — loader configuration
8
+ * - {@link ContextStatistics} — runtime metrics
9
+ *
10
+ * This module is conceptually equivalent to HAPI's `FhirContext` +
11
+ * `IValidationSupport` interface, adapted for TypeScript/async patterns.
12
+ *
13
+ * @see https://hapifhir.io/hapi-fhir/docs/
14
+ * @module fhir-context
15
+ */
16
+ import type { StructureDefinition, CanonicalProfile } from '../model/index.js';
17
+ /**
18
+ * Central registry and lifecycle manager for FHIR StructureDefinitions.
19
+ *
20
+ * `FhirContext` is the primary entry point for accessing FHIR definitions
21
+ * at runtime. It manages loading, caching, and resolution of
22
+ * StructureDefinitions from one or more sources.
23
+ *
24
+ * Conceptual mapping:
25
+ * - HAPI `FhirContext` → registry + lifecycle
26
+ * - HAPI `IValidationSupport` → loader delegation
27
+ *
28
+ * Phase 4 (`fhir-profile`) will use this interface to load base definitions
29
+ * during snapshot generation.
30
+ *
31
+ * @example
32
+ * ```typescript
33
+ * const context = new FhirContextImpl({ loaders: [memoryLoader, fileLoader] });
34
+ * await context.preloadCoreDefinitions();
35
+ *
36
+ * const patient = await context.loadStructureDefinition(
37
+ * 'http://hl7.org/fhir/StructureDefinition/Patient'
38
+ * );
39
+ * const chain = await context.resolveInheritanceChain(patient.url!);
40
+ * // → ['http://hl7.org/fhir/StructureDefinition/Patient',
41
+ * // 'http://hl7.org/fhir/StructureDefinition/DomainResource',
42
+ * // 'http://hl7.org/fhir/StructureDefinition/Resource']
43
+ * ```
44
+ */
45
+ export interface FhirContext {
46
+ /**
47
+ * Load a StructureDefinition by canonical URL.
48
+ *
49
+ * Resolution order:
50
+ * 1. Check internal registry (cache hit)
51
+ * 2. Delegate to configured loaders (cache miss)
52
+ * 3. Parse, validate, and register the result
53
+ *
54
+ * Supports versioned URLs in `url|version` format
55
+ * (e.g., `"http://example.org/Profile|1.0.0"`).
56
+ *
57
+ * @param url - Canonical URL, optionally with `|version` suffix
58
+ * @returns Resolved StructureDefinition
59
+ * @throws {@link ResourceNotFoundError} if no loader can resolve the URL
60
+ * @throws {@link LoaderError} if a loader fails during loading
61
+ * @throws {@link InvalidStructureDefinitionError} if the loaded resource is malformed
62
+ */
63
+ loadStructureDefinition(url: string): Promise<StructureDefinition>;
64
+ /**
65
+ * Synchronously retrieve a StructureDefinition from the registry.
66
+ *
67
+ * Does **not** trigger any loader — only checks the in-memory registry.
68
+ * Use {@link loadStructureDefinition} if you need on-demand loading.
69
+ *
70
+ * @param url - Canonical URL (with optional `|version`)
71
+ * @returns The cached StructureDefinition, or `undefined` if not loaded
72
+ */
73
+ getStructureDefinition(url: string): StructureDefinition | undefined;
74
+ /**
75
+ * Check whether a StructureDefinition is present in the registry.
76
+ *
77
+ * @param url - Canonical URL (with optional `|version`)
78
+ */
79
+ hasStructureDefinition(url: string): boolean;
80
+ /**
81
+ * Resolve the full inheritance chain for a profile.
82
+ *
83
+ * Walks the `baseDefinition` links from the given URL up to the root
84
+ * resource type (e.g., `Resource`). Each base is loaded on demand if
85
+ * not already in the registry.
86
+ *
87
+ * @param url - Canonical URL of the starting profile
88
+ * @returns Array of canonical URLs from child to root
89
+ * (e.g., `[ChinesePatient, Patient, DomainResource, Resource]`)
90
+ * @throws {@link CircularDependencyError} if a cycle is detected
91
+ * @throws {@link ResourceNotFoundError} if a base definition cannot be found
92
+ */
93
+ resolveInheritanceChain(url: string): Promise<string[]>;
94
+ /**
95
+ * Register a StructureDefinition in the registry.
96
+ *
97
+ * This is used for:
98
+ * - Manually adding definitions (e.g., custom profiles)
99
+ * - Phase 4: caching generated snapshots back into the context
100
+ *
101
+ * If a definition with the same URL (and version) already exists,
102
+ * it will be replaced and any cached inheritance chains invalidated.
103
+ *
104
+ * @param sd - The StructureDefinition to register
105
+ * @throws {@link InvalidStructureDefinitionError} if `sd.url` is missing
106
+ */
107
+ registerStructureDefinition(sd: StructureDefinition): void;
108
+ /**
109
+ * Preload FHIR R4 core StructureDefinitions.
110
+ *
111
+ * Loads base resource types (Resource, DomainResource, Patient,
112
+ * Observation, etc.) into the registry so they are available
113
+ * synchronously via {@link getStructureDefinition}.
114
+ *
115
+ * Should be called once during application initialization.
116
+ */
117
+ preloadCoreDefinitions(): Promise<void>;
118
+ /**
119
+ * Return runtime statistics for monitoring and diagnostics.
120
+ */
121
+ getStatistics(): ContextStatistics;
122
+ /**
123
+ * Register a CanonicalProfile and its extracted InnerTypes.
124
+ *
125
+ * This is the primary method for making InnerTypes available for
126
+ * downstream consumption (UI forms, recursive validation, etc.).
127
+ * Typically called after snapshot generation + `extractInnerTypes()`.
128
+ *
129
+ * @param profile - The CanonicalProfile (with innerTypes populated)
130
+ */
131
+ registerCanonicalProfile(profile: CanonicalProfile): void;
132
+ /**
133
+ * Retrieve an InnerType schema by its generated type name.
134
+ *
135
+ * @param typeName - Generated type name (e.g., `'PatientContact'`)
136
+ * @returns The InnerType CanonicalProfile, or `undefined` if not registered
137
+ */
138
+ getInnerType(typeName: string): CanonicalProfile | undefined;
139
+ /**
140
+ * Check whether an InnerType is registered.
141
+ *
142
+ * @param typeName - Generated type name (e.g., `'PatientContact'`)
143
+ */
144
+ hasInnerType(typeName: string): boolean;
145
+ /**
146
+ * Release all cached data and reset internal state.
147
+ *
148
+ * After calling `dispose()`, the context must be re-initialized
149
+ * (e.g., by calling {@link preloadCoreDefinitions} again).
150
+ */
151
+ dispose(): void;
152
+ }
153
+ /**
154
+ * Pluggable strategy for loading StructureDefinitions from an external source.
155
+ *
156
+ * Implementations include:
157
+ * - `MemoryLoader` — loads from an in-memory map (for testing / preloaded data)
158
+ * - `FileSystemLoader` — loads from local JSON files
159
+ * - `CompositeLoader` — chains multiple loaders (fallback pattern)
160
+ *
161
+ * Conceptually equivalent to HAPI's `IValidationSupport` implementations.
162
+ */
163
+ export interface StructureDefinitionLoader {
164
+ /**
165
+ * Attempt to load a StructureDefinition by canonical URL.
166
+ *
167
+ * @param url - Canonical URL (without `|version` — version is stripped
168
+ * by the caller before delegation)
169
+ * @returns The loaded StructureDefinition, or `null` if this loader
170
+ * cannot resolve the URL (allows fallback to next loader)
171
+ * @throws {@link LoaderError} on I/O or parse failures
172
+ */
173
+ load(url: string): Promise<StructureDefinition | null>;
174
+ /**
175
+ * Quick check whether this loader is likely able to resolve the URL.
176
+ *
177
+ * This is a hint — returning `true` does not guarantee `load()` will
178
+ * succeed. Returning `false` allows the composite loader to skip this
179
+ * source entirely.
180
+ *
181
+ * @param url - Canonical URL to check
182
+ */
183
+ canLoad(url: string): boolean;
184
+ /**
185
+ * Human-readable identifier for the loader source.
186
+ *
187
+ * Used in error messages and diagnostics.
188
+ *
189
+ * @returns Source type label (e.g., `'memory'`, `'filesystem'`, `'http'`)
190
+ */
191
+ getSourceType(): string;
192
+ }
193
+ /**
194
+ * Configuration options for creating a {@link FhirContext}.
195
+ */
196
+ export interface FhirContextOptions {
197
+ /**
198
+ * One or more loaders to use for resolving StructureDefinitions.
199
+ *
200
+ * When multiple loaders are provided, they are tried in order
201
+ * (first match wins — chain of responsibility pattern).
202
+ */
203
+ loaders: StructureDefinitionLoader[];
204
+ /**
205
+ * Whether to automatically call {@link FhirContext.preloadCoreDefinitions}
206
+ * during initialization.
207
+ *
208
+ * @defaultValue `true`
209
+ */
210
+ preloadCore?: boolean;
211
+ /**
212
+ * Path to the FHIR R4 specification directory.
213
+ *
214
+ * Used by the core definition preloader to locate `profiles-resources.json`
215
+ * and `profiles-types.json`.
216
+ *
217
+ * @defaultValue `undefined` (uses bundled definitions)
218
+ */
219
+ specDirectory?: string;
220
+ }
221
+ /**
222
+ * Options for individual loader instances.
223
+ */
224
+ export interface LoaderOptions {
225
+ /**
226
+ * Base directory or URL prefix for resolving relative paths.
227
+ */
228
+ basePath?: string;
229
+ /**
230
+ * Request timeout in milliseconds (for future HTTP loaders).
231
+ *
232
+ * @defaultValue `30000`
233
+ */
234
+ timeout?: number;
235
+ /**
236
+ * Number of retry attempts on transient failures.
237
+ *
238
+ * @defaultValue `0`
239
+ */
240
+ retryCount?: number;
241
+ }
242
+ /**
243
+ * Runtime metrics for the {@link FhirContext}.
244
+ *
245
+ * Useful for monitoring cache effectiveness and diagnosing
246
+ * performance issues.
247
+ */
248
+ export interface ContextStatistics {
249
+ /** Total number of StructureDefinitions in the registry */
250
+ totalLoaded: number;
251
+ /** Number of `loadStructureDefinition` calls resolved from cache */
252
+ cacheHits: number;
253
+ /** Number of `loadStructureDefinition` calls that required loader delegation */
254
+ cacheMisses: number;
255
+ /** Total number of loader invocations across all loaders */
256
+ loaderCalls: number;
257
+ /** Number of inheritance chains resolved */
258
+ chainsResolved: number;
259
+ /** Number of `registerStructureDefinition` calls */
260
+ registrations: number;
261
+ }
262
+ /**
263
+ * Create a fresh statistics object with all counters at zero.
264
+ */
265
+ export declare function createEmptyStatistics(): ContextStatistics;
266
+ //# sourceMappingURL=types.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/context/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAM/E;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;;;;;;;;;;;;;OAgBG;IACH,uBAAuB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAEnE;;;;;;;;OAQG;IACH,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,mBAAmB,GAAG,SAAS,CAAC;IAErE;;;;OAIG;IACH,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IAE7C;;;;;;;;;;;;OAYG;IACH,uBAAuB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAExD;;;;;;;;;;;;OAYG;IACH,2BAA2B,CAAC,EAAE,EAAE,mBAAmB,GAAG,IAAI,CAAC;IAE3D;;;;;;;;OAQG;IACH,sBAAsB,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAExC;;OAEG;IACH,aAAa,IAAI,iBAAiB,CAAC;IAEnC;;;;;;;;OAQG;IACH,wBAAwB,CAAC,OAAO,EAAE,gBAAgB,GAAG,IAAI,CAAC;IAE1D;;;;;OAKG;IACH,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS,CAAC;IAE7D;;;;OAIG;IACH,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;IAExC;;;;;OAKG;IACH,OAAO,IAAI,IAAI,CAAC;CACjB;AAMD;;;;;;;;;GASG;AACH,MAAM,WAAW,yBAAyB;IACxC;;;;;;;;OAQG;IACH,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,GAAG,IAAI,CAAC,CAAC;IAEvD;;;;;;;;OAQG;IACH,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IAE9B;;;;;;OAMG;IACH,aAAa,IAAI,MAAM,CAAC;CACzB;AAMD;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;;OAKG;IACH,OAAO,EAAE,yBAAyB,EAAE,CAAC;IAErC;;;;;OAKG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IAEtB;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAMD;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,2DAA2D;IAC3D,WAAW,EAAE,MAAM,CAAC;IAEpB,oEAAoE;IACpE,SAAS,EAAE,MAAM,CAAC;IAElB,gFAAgF;IAChF,WAAW,EAAE,MAAM,CAAC;IAEpB,4DAA4D;IAC5D,WAAW,EAAE,MAAM,CAAC;IAEpB,4CAA4C;IAC5C,cAAc,EAAE,MAAM,CAAC;IAEvB,oDAAoD;IACpD,aAAa,EAAE,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,wBAAgB,qBAAqB,IAAI,iBAAiB,CASzD"}