@cosyte/terminology 0.0.6 → 0.0.8

package/dist/index.d.cts

@@ -963,8 +963,8 @@ interface LoadWarning {
 }
 /**
  * A loaded, immutable code-system release — the queryable model {@link loadCodeSystem} produces and
- * {@link lookup} / {@link validateCode} run over. Concepts are keyed by code for O(1) identity; the
- * map is exposed `readonly` and every concept is frozen.
+ * {@link lookup} / {@link validateCode} run over. Concepts are keyed by code for O(1) identity, and
+ * every concept is frozen.
  */
 interface CodeSystem {
     /** The code system's canonical URI, when supplied by the source. */
@@ -975,7 +975,14 @@ interface CodeSystem {
     readonly name?: string;
     /** The number of loaded concepts. */
     readonly count: number;
-    /** The concepts, keyed by `code`. Read-only; every value frozen. */
+    /**
+     * The concepts, keyed by `code`. A **read-only view**, not a `Map` you were handed: reads and
+     * iteration behave as a `Map`'s do, adding / deleting / clearing is refused however it is
+     * attempted, and every value is frozen.
+     *
+     * A view is not a `Map` instance — `instanceof Map` is `false` and this model cannot be
+     * `structuredClone`d or posted to a worker; copy out what you need (`new Map(…)`).
+     */
     readonly concepts: ReadonlyMap<string, Concept>;
     /** The skipped-row warnings surfaced during load, in line order. Frozen; may be empty. */
     readonly warnings: readonly LoadWarning[];
@@ -2247,11 +2254,11 @@ declare function parseUcum(unit: string): ParseResult;
  * @throws {Error} If reducing `node` reaches an atom with no linear definition, or one whose
  *   definition does not parse. **No expression {@link parseUcum} accepts reaches either**; a node
  *   you assemble yourself can, including by defining an atom in terms of a special unit such as
- *   `Cel`, which lands on the table's own `Cel`. A third guard, against a definition that leads
- *   back to itself, is **not** reachable from a node you assemble — a definition is resolved
- *   against the bundled table, so your atom can name a table atom but never be one — and is
- *   reached only by mutating an atom of the loaded table in place. The message names the fault,
- *   never the atom.
+ *   `Cel`, which lands on the table's own `Cel`. A third guard catches a definition that leads back
+ *   to itself. Naming a table atom does not reach it — a definition is resolved against the loaded
+ *   table, so your atom can name one but never be one — and neither does the table itself, which is
+ *   frozen; what reaches it is a `value` accessor that re-enters `reduce` for the same atom while
+ *   that atom is still being reduced. The message names the fault, never the atom.
  * @example
  * ```ts
  * import { parseUcum, reduce } from "@cosyte/terminology";
@@ -2282,7 +2289,13 @@ declare function reduce(node: UnitNode): Reduction;
 /**
  * Load the UCUM essence table, parsing the embedded verbatim XML on first call and caching it.
  *
- * @returns The immutable in-memory {@link UcumEssence} model (7 base units, 24 prefixes, ~305 atoms).
+ * One table is shared by every caller and by the engine itself, so it is handed out **frozen**: an
+ * atom's definition cannot be rewritten in place, and neither can the `atoms` array the parser
+ * scans. It used to be, and doing so before that atom's first reduction poisoned the
+ * reduction memo for the life of the process — a fabricated unit equivalence that survived putting
+ * the table back. A write is refused, which in strict mode means a `TypeError`.
+ *
+ * @returns The shared, frozen in-memory {@link UcumEssence} model.
  * @example
  * ```ts
  * import { loadUcumEssence } from "@cosyte/terminology";
@@ -2376,6 +2389,13 @@ interface GemEntry {
 /**
  * A loaded, immutable GEM map. Entries are keyed by source code (a source may have many entries — the
  * maps are 1:many). Applied **only** in its {@link direction}; never inverted.
+ *
+ * {@link entries} is a **read-only view**, not a `Map` you were handed, and each source's candidate
+ * list is frozen: nothing that holds a loaded map can delete a source's mapping, or add a target the
+ * steward's file never authored, and have {@link applyGem} answer from it.
+ *
+ * A view is not a `Map` instance — `instanceof Map` is `false` and this model cannot be
+ * `structuredClone`d or posted to a worker; copy out what you need (`new Map(…)`).
  */
 interface GemMap {
     /** Which direction this file maps. Applied only this way. */
@@ -2384,7 +2404,7 @@ interface GemMap {
     readonly version?: string;
     /** The number of loaded entries. */
     readonly count: number;
-    /** Entries keyed by source code, each list in file order. Read-only; frozen. */
+    /** Entries keyed by source code, each list in file order. Each list frozen. */
     readonly entries: ReadonlyMap<string, readonly GemEntry[]>;
     /** The skipped-row warnings surfaced during load, in line order. Frozen; may be empty. */
     readonly warnings: readonly GemLoadWarning[];
@@ -2475,6 +2495,13 @@ interface ComplexMapEntry {
 /**
  * A loaded, immutable SNOMED→ICD-10-CM complex map. Entries are keyed by source concept id; within a
  * source they are ordered by (group, priority). Applied **only** SNOMED→ICD-10-CM; never inverted.
+ *
+ * {@link entries} is a **read-only view**, not a `Map` you were handed, and each source's rule list
+ * is frozen: nothing that holds a loaded map can delete a source concept's rules, or add one your
+ * refset never carried, and have {@link applyComplexMap} resolve from it.
+ *
+ * A view is not a `Map` instance — `instanceof Map` is `false` and this model cannot be
+ * `structuredClone`d or posted to a worker; copy out what you need (`new Map(…)`).
  */
 interface ComplexMap {
     /** The map version/release, when supplied — mappings are release-scoped. */
@@ -3051,16 +3078,25 @@ interface RxNormLoadWarning {
 }
 /**
  * A loaded, immutable RxNorm drug graph: concepts keyed by `RXCUI`, edges indexed by subject, and the
- * NDC→RXCUI attribute index — all frozen. Applied only in the authored edge direction; never inverted.
+ * NDC→RXCUI attribute index. Applied only in the authored edge direction; never inverted.
+ *
+ * Its three indexes are **read-only views**, not `Map`s you were handed: reads and iteration behave
+ * as a `Map`'s do, and adding / deleting / clearing is refused however it is attempted. What that
+ * buys is the never-fabricate invariant surviving the handover — nothing that holds a loaded graph
+ * can empty a medication's ingredient edges, or add an edge or concept the release never authored,
+ * and leave {@link conceptCount} / {@link edgeCount} still reporting the loaded figures.
+ *
+ * A view is not a `Map` instance — `instanceof Map` is `false` and this model cannot be
+ * `structuredClone`d or posted to a worker; copy out what you need (`new Map(…)`).
  */
 interface RxNormGraph {
     /** The release version (e.g. `"RXNORM_2026AA"`), when supplied — mappings are release-scoped. */
     readonly version?: string;
-    /** Concepts keyed by `RXCUI` (first `SAB=RXNORM` atom per `RXCUI` wins). Frozen. */
+    /** Concepts keyed by `RXCUI` (first `SAB=RXNORM` atom per `RXCUI` wins). Each frozen. */
     readonly concepts: ReadonlyMap<string, RxNormConcept>;
-    /** Directed edges indexed by `subject` `RXCUI`, each list in file order. Frozen. */
+    /** Directed edges indexed by `subject` `RXCUI`, each list in file order. Each list frozen. */
     readonly edges: ReadonlyMap<string, readonly RxNormEdge[]>;
-    /** NDC → { rxcui, status } index from `RXNSAT` `ATN=NDC` attributes. Frozen; may be empty. */
+    /** NDC → { rxcui, status } index from `RXNSAT` `ATN=NDC` attributes. Each frozen; may be empty. */
     readonly ndcs: ReadonlyMap<string, {
         readonly rxcui: string;
         readonly status: NdcStatus;

package/dist/index.d.ts

@@ -963,8 +963,8 @@ interface LoadWarning {
 }
 /**
  * A loaded, immutable code-system release — the queryable model {@link loadCodeSystem} produces and
- * {@link lookup} / {@link validateCode} run over. Concepts are keyed by code for O(1) identity; the
- * map is exposed `readonly` and every concept is frozen.
+ * {@link lookup} / {@link validateCode} run over. Concepts are keyed by code for O(1) identity, and
+ * every concept is frozen.
  */
 interface CodeSystem {
     /** The code system's canonical URI, when supplied by the source. */
@@ -975,7 +975,14 @@ interface CodeSystem {
     readonly name?: string;
     /** The number of loaded concepts. */
     readonly count: number;
-    /** The concepts, keyed by `code`. Read-only; every value frozen. */
+    /**
+     * The concepts, keyed by `code`. A **read-only view**, not a `Map` you were handed: reads and
+     * iteration behave as a `Map`'s do, adding / deleting / clearing is refused however it is
+     * attempted, and every value is frozen.
+     *
+     * A view is not a `Map` instance — `instanceof Map` is `false` and this model cannot be
+     * `structuredClone`d or posted to a worker; copy out what you need (`new Map(…)`).
+     */
     readonly concepts: ReadonlyMap<string, Concept>;
     /** The skipped-row warnings surfaced during load, in line order. Frozen; may be empty. */
     readonly warnings: readonly LoadWarning[];
@@ -2247,11 +2254,11 @@ declare function parseUcum(unit: string): ParseResult;
  * @throws {Error} If reducing `node` reaches an atom with no linear definition, or one whose
  *   definition does not parse. **No expression {@link parseUcum} accepts reaches either**; a node
  *   you assemble yourself can, including by defining an atom in terms of a special unit such as
- *   `Cel`, which lands on the table's own `Cel`. A third guard, against a definition that leads
- *   back to itself, is **not** reachable from a node you assemble — a definition is resolved
- *   against the bundled table, so your atom can name a table atom but never be one — and is
- *   reached only by mutating an atom of the loaded table in place. The message names the fault,
- *   never the atom.
+ *   `Cel`, which lands on the table's own `Cel`. A third guard catches a definition that leads back
+ *   to itself. Naming a table atom does not reach it — a definition is resolved against the loaded
+ *   table, so your atom can name one but never be one — and neither does the table itself, which is
+ *   frozen; what reaches it is a `value` accessor that re-enters `reduce` for the same atom while
+ *   that atom is still being reduced. The message names the fault, never the atom.
  * @example
  * ```ts
  * import { parseUcum, reduce } from "@cosyte/terminology";
@@ -2282,7 +2289,13 @@ declare function reduce(node: UnitNode): Reduction;
 /**
  * Load the UCUM essence table, parsing the embedded verbatim XML on first call and caching it.
  *
- * @returns The immutable in-memory {@link UcumEssence} model (7 base units, 24 prefixes, ~305 atoms).
+ * One table is shared by every caller and by the engine itself, so it is handed out **frozen**: an
+ * atom's definition cannot be rewritten in place, and neither can the `atoms` array the parser
+ * scans. It used to be, and doing so before that atom's first reduction poisoned the
+ * reduction memo for the life of the process — a fabricated unit equivalence that survived putting
+ * the table back. A write is refused, which in strict mode means a `TypeError`.
+ *
+ * @returns The shared, frozen in-memory {@link UcumEssence} model.
  * @example
  * ```ts
  * import { loadUcumEssence } from "@cosyte/terminology";
@@ -2376,6 +2389,13 @@ interface GemEntry {
 /**
  * A loaded, immutable GEM map. Entries are keyed by source code (a source may have many entries — the
  * maps are 1:many). Applied **only** in its {@link direction}; never inverted.
+ *
+ * {@link entries} is a **read-only view**, not a `Map` you were handed, and each source's candidate
+ * list is frozen: nothing that holds a loaded map can delete a source's mapping, or add a target the
+ * steward's file never authored, and have {@link applyGem} answer from it.
+ *
+ * A view is not a `Map` instance — `instanceof Map` is `false` and this model cannot be
+ * `structuredClone`d or posted to a worker; copy out what you need (`new Map(…)`).
  */
 interface GemMap {
     /** Which direction this file maps. Applied only this way. */
@@ -2384,7 +2404,7 @@ interface GemMap {
     readonly version?: string;
     /** The number of loaded entries. */
     readonly count: number;
-    /** Entries keyed by source code, each list in file order. Read-only; frozen. */
+    /** Entries keyed by source code, each list in file order. Each list frozen. */
     readonly entries: ReadonlyMap<string, readonly GemEntry[]>;
     /** The skipped-row warnings surfaced during load, in line order. Frozen; may be empty. */
     readonly warnings: readonly GemLoadWarning[];
@@ -2475,6 +2495,13 @@ interface ComplexMapEntry {
 /**
  * A loaded, immutable SNOMED→ICD-10-CM complex map. Entries are keyed by source concept id; within a
  * source they are ordered by (group, priority). Applied **only** SNOMED→ICD-10-CM; never inverted.
+ *
+ * {@link entries} is a **read-only view**, not a `Map` you were handed, and each source's rule list
+ * is frozen: nothing that holds a loaded map can delete a source concept's rules, or add one your
+ * refset never carried, and have {@link applyComplexMap} resolve from it.
+ *
+ * A view is not a `Map` instance — `instanceof Map` is `false` and this model cannot be
+ * `structuredClone`d or posted to a worker; copy out what you need (`new Map(…)`).
  */
 interface ComplexMap {
     /** The map version/release, when supplied — mappings are release-scoped. */
@@ -3051,16 +3078,25 @@ interface RxNormLoadWarning {
 }
 /**
  * A loaded, immutable RxNorm drug graph: concepts keyed by `RXCUI`, edges indexed by subject, and the
- * NDC→RXCUI attribute index — all frozen. Applied only in the authored edge direction; never inverted.
+ * NDC→RXCUI attribute index. Applied only in the authored edge direction; never inverted.
+ *
+ * Its three indexes are **read-only views**, not `Map`s you were handed: reads and iteration behave
+ * as a `Map`'s do, and adding / deleting / clearing is refused however it is attempted. What that
+ * buys is the never-fabricate invariant surviving the handover — nothing that holds a loaded graph
+ * can empty a medication's ingredient edges, or add an edge or concept the release never authored,
+ * and leave {@link conceptCount} / {@link edgeCount} still reporting the loaded figures.
+ *
+ * A view is not a `Map` instance — `instanceof Map` is `false` and this model cannot be
+ * `structuredClone`d or posted to a worker; copy out what you need (`new Map(…)`).
  */
 interface RxNormGraph {
     /** The release version (e.g. `"RXNORM_2026AA"`), when supplied — mappings are release-scoped. */
     readonly version?: string;
-    /** Concepts keyed by `RXCUI` (first `SAB=RXNORM` atom per `RXCUI` wins). Frozen. */
+    /** Concepts keyed by `RXCUI` (first `SAB=RXNORM` atom per `RXCUI` wins). Each frozen. */
     readonly concepts: ReadonlyMap<string, RxNormConcept>;
-    /** Directed edges indexed by `subject` `RXCUI`, each list in file order. Frozen. */
+    /** Directed edges indexed by `subject` `RXCUI`, each list in file order. Each list frozen. */
     readonly edges: ReadonlyMap<string, readonly RxNormEdge[]>;
-    /** NDC → { rxcui, status } index from `RXNSAT` `ATN=NDC` attributes. Frozen; may be empty. */
+    /** NDC → { rxcui, status } index from `RXNSAT` `ATN=NDC` attributes. Each frozen; may be empty. */
     readonly ndcs: ReadonlyMap<string, {
         readonly rxcui: string;
         readonly status: NdcStatus;

package/dist/index.mjs

@@ -565,6 +565,31 @@ function translate(sourceCoding, map) {
   );
 }
 
+// src/common/frozen-map.ts
+function frozenMap(source, what) {
+  const refuse = () => {
+    throw new TypeError(`Cannot mutate ${what} (it is immutable)`);
+  };
+  const view = {
+    get size() {
+      return source.size;
+    },
+    get: (key) => source.get(key),
+    has: (key) => source.has(key),
+    keys: () => source.keys(),
+    values: () => source.values(),
+    entries: () => source.entries(),
+    forEach: (callback, thisArg) => {
+      for (const [key, value] of source) callback.call(thisArg, value, key, view);
+    },
+    [Symbol.iterator]: () => source[Symbol.iterator](),
+    set: refuse,
+    delete: refuse,
+    clear: refuse
+  };
+  return Object.freeze(view);
+}
+
 // src/codesystem/status.ts
 var defaultStatusMapper = (raw) => {
   switch (raw.trim().toUpperCase()) {
@@ -971,15 +996,6 @@ function parseRrf(source) {
 }
 
 // src/codesystem/load.ts
-function sealConceptMap(map) {
-  const guard = () => {
-    throw new TypeError("Cannot mutate a loaded CodeSystem's concepts map (it is immutable)");
-  };
-  for (const method of ["set", "delete", "clear"]) {
-    Object.defineProperty(map, method, { value: guard, writable: false, configurable: false });
-  }
-  return map;
-}
 function loadCodeSystem(source) {
   let concepts;
   let warnings;
@@ -1017,7 +1033,7 @@ function loadCodeSystem(source) {
     }
   }
   out.count = concepts.size;
-  out.concepts = sealConceptMap(concepts);
+  out.concepts = frozenMap(concepts, "a loaded CodeSystem's concepts map");
   out.warnings = Object.freeze(warnings);
   return Object.freeze(out);
 }
@@ -3731,7 +3747,29 @@ function parseEssence(xml) {
   atoms.sort((a, b) => b.code.length - a.code.length);
   const atomByCode = new Map(atoms.map((a) => [a.code, a]));
   const prefixByCode = new Map(prefixes.map((p) => [p.code, p]));
-  return { prefixes, atoms, atomByCode, prefixByCode };
+  return freezeEssence({ prefixes, atoms, atomByCode, prefixByCode });
+}
+function refuseTableWrite() {
+  throw new TypeError("the UCUM unit table is immutable");
+}
+function sealLookup(map) {
+  return Object.defineProperties(map, {
+    set: { value: refuseTableWrite },
+    delete: { value: refuseTableWrite },
+    clear: { value: refuseTableWrite }
+  });
+}
+function freezeEssence(essence) {
+  for (const atom of essence.atoms) {
+    if (atom.value) Object.freeze(atom.value);
+    Object.freeze(atom);
+  }
+  for (const prefix of essence.prefixes) Object.freeze(prefix);
+  Object.freeze(essence.atoms);
+  Object.freeze(essence.prefixes);
+  sealLookup(essence.atomByCode);
+  sealLookup(essence.prefixByCode);
+  return Object.freeze(essence);
 }
 var cached;
 function loadUcumEssence() {
@@ -4045,21 +4083,25 @@ function loadGems(source) {
     if (trimmed === "") continue;
     const fields = trimmed.split(/\s+/);
     if (fields.length !== 3) {
-      warnings.push({
-        code: "TERM_GEM_MALFORMED_ROW",
-        line: i + 1,
-        detail: `expected 3 whitespace-delimited fields, found ${String(fields.length)}`
-      });
+      warnings.push(
+        Object.freeze({
+          code: "TERM_GEM_MALFORMED_ROW",
+          line: i + 1,
+          detail: `expected 3 whitespace-delimited fields, found ${String(fields.length)}`
+        })
+      );
       continue;
     }
     const [src, tgt, flagStr] = fields;
     const flags = decodeFlags(flagStr);
     if (flags === void 0) {
-      warnings.push({
-        code: "TERM_GEM_MALFORMED_ROW",
-        line: i + 1,
-        detail: "flag field is not a 5-digit code"
-      });
+      warnings.push(
+        Object.freeze({
+          code: "TERM_GEM_MALFORMED_ROW",
+          line: i + 1,
+          detail: "flag field is not a 5-digit code"
+        })
+      );
       continue;
     }
     const entry = { source: src, flags };
@@ -4070,11 +4112,12 @@ function loadGems(source) {
     else entries.set(src, [frozen]);
     count++;
   }
+  for (const list of entries.values()) Object.freeze(list);
   return Object.freeze({
     direction: source.direction,
     ...source.version !== void 0 ? { version: source.version } : {},
     count,
-    entries,
+    entries: frozenMap(entries, "a loaded GEM map's entries"),
     warnings: Object.freeze(warnings)
   });
 }
@@ -4222,11 +4265,13 @@ function parseRf2(content) {
     const groupN = Number(at(f, iGroup));
     const priorityN = Number(at(f, iPriority));
     if (source === "" || !Number.isFinite(groupN) || !Number.isFinite(priorityN)) {
-      warnings.push({
-        code: "TERM_COMPLEX_MAP_MALFORMED_ROW",
-        line: i + 1,
-        detail: "row is missing referencedComponentId / mapGroup / mapPriority"
-      });
+      warnings.push(
+        Object.freeze({
+          code: "TERM_COMPLEX_MAP_MALFORMED_ROW",
+          line: i + 1,
+          detail: "row is missing referencedComponentId / mapGroup / mapPriority"
+        })
+      );
       continue;
     }
     rows.push({
@@ -4269,7 +4314,7 @@ function loadComplexMap(input) {
   }
   const out = {
     count,
-    entries,
+    entries: frozenMap(entries, "a loaded complex map's entries"),
     warnings
   };
   if (input.version !== void 0) out.version = input.version;
@@ -4563,9 +4608,9 @@ function loadRxNormGraph(source) {
   const ndcs = source.sat !== void 0 ? parseNdcs(source.sat, warnings) : /* @__PURE__ */ new Map();
   for (const list of edges.values()) Object.freeze(list);
   const out = {
-    concepts,
-    edges,
-    ndcs,
+    concepts: frozenMap(concepts, "a loaded RxNorm graph's concepts"),
+    edges: frozenMap(edges, "a loaded RxNorm graph's edges"),
+    ndcs: frozenMap(ndcs, "a loaded RxNorm graph's NDC index"),
     conceptCount: concepts.size,
     edgeCount,
     warnings: Object.freeze(warnings)
@@ -4729,7 +4774,7 @@ function approximateMatch(graph, query, options = {}) {
 }
 
 // src/index.ts
-var VERSION = "0.0.6";
+var VERSION = "0.0.8";
 
 export { COMPLEX_MAP_SOURCE_SYSTEM, DIAGNOSTIC_CODES, FATAL_CODES, HL7_V2_OID_ROOT, HL7_V2_URL_PREFIX, ICD10CM_ORDER_FILE_FIELDS, ICD10CM_SYSTEM, ICD9CM_SYSTEM, MAP_CATEGORIES, NO_MAP_CATEGORIES, RELA, RELA_INVERSE, RXNORM_SYSTEM, SNOMEDCT_SYSTEM, SYSTEM_IDENTITIES, TERM_TYPES, TerminologyError, VERSION, applyComplexMap, applyGem, approximateMatch, asTermType, brandsFor, buildSubsumption, codeableConcept, coding, consistsOf, defaultStatusMapper, doseFormsOf, expand, genericFor, getArray, getBoolean, getConcept, getNumber, getString, ingredientsOf, invertGem, isA, isJsonObject, isSynonymTermType, isUnknownSystem, loadCodeSystem, loadComplexMap, loadConceptMap, loadGems, loadRxNormGraph, loadUcumEssence, loadValueSet, lookup, makeStatus, matchesFilter, parseCsv, parseCsvSource, parseFhirCodeSystem, parseFixedWidth, parseRrf, parseRrfLine, parseUcum, reduce, relatedByRela, resolveNdc, resolveSystem, sliceField, translate, ucumEqual, unsupportedOps, validateCode, validateCodeInValueSet, validateUcum };
 //# sourceMappingURL=index.mjs.map