Skip to main content
Version: v0.0.4

@cosyte/terminology

Public entry point for @cosyte/terminology - a zero-dependency, developer-focused terminology engine for US healthcare code systems.

Unlike its sibling @cosyte/* packages, this is not a wire-format parser: it mirrors the FHIR Terminology Module ($translate, $lookup, $validate-code, $expand, …), operating over consumer-supplied FHIR resources. It ships the engine and no code-system release (SNOMED CT / CPT / LOINC / UMLS / RxNorm are strictly BYO). It is not content-free: see What is bundled at the end of this note, which includes the UCUM unit table, the code-system identities (OID ↔ URI), the SNOMED CT concepts the crosswalk resolver names and RxNorm's relationship and term-type names, each with its copyright.

Code-system identity and ConceptMap translation:

  • resolveSystem - the code-system identity / canonical-URI resolver (mnemonic | OID → URI).
  • loadConceptMap + translate - the ConceptMap $translate engine, with the never-fabricate / never-invert invariants: an unmapped source is a typed TranslateUnmapped, never a guessed target; a directional map is never run backwards.

The CodeSystem load layer, with the FHIR $lookup / $validate-code operations:

  • loadCodeSystem - load a consumer-supplied release (RRF / CSV / fixed-width / FHIR CodeSystem JSON) into an immutable model. Ships the loader; no code-system release.
  • lookup - code → display + properties, carrying status (deprecated / header-not-billable).
  • validateCode - is a code a valid member of the system, with its status flags.

The never-fabricate invariant holds here too: an unknown code is a typed unknown / valid: false, never a fabricated display or a guessed valid: true.

The ValueSet binding layer - FHIR $expand / $validate-code over a compose:

  • loadValueSet - load a consumer-supplied FHIR ValueSet (intensional compose and/or a pre-computed expansion) into an immutable model.
  • expand - flatten membership over the supplied CodeSystems (include/exclude, explicit concept lists, is-a/property filters, referenced value sets), with an honest complete flag: an unresolvable part is a typed TERM_VALUESET_CANNOT_EXPAND, never a guess.
  • validateCodeInValueSet - binding membership, returning a decided result only when proven and a typed undetermined otherwise (a truncated expansion never reads as complete).

The UCUM unit layer - a hand-rolled UCUM grammar parser + validation + representation canonicalization (recognition only, no magnitude conversion):

  • validateUcum - is a string a valid UCUM unit; if so, its canonical descriptor. An invalid unit is a typed TERM_UCUM_INVALID, never a guessed "nearest" unit.
  • ucumEqual - do two expressions denote the same unit (N ≡ kg.m/s2), by reducing both to base dimensions. Not magnitude conversion (mg/dL → mmol/L is refused).
  • parseUcum / reduce / loadUcumEssence - the underlying grammar parser, dimensional reducer, and the in-memory model of the vendored, verbatim UCUM table.

The crosswalk resolvers - the never-fabricate/never-invert invariant applied to the published, directional reference maps:

The RxNorm drug relationship graph - ingredient / brand / clinical-drug / dose-form navigation over a caller-supplied RxNorm RRF release:

  • loadRxNormGraph - load RXNCONSO (concepts, typed by TTY), RXNREL (directed RELA edges, normalized to the documented RXCUI2 ⟶RELA⟶ RXCUI1 direction), and optionally RXNSAT (NDC attributes) into an immutable graph. Ships no RxNorm release - BYO.
  • ingredientsOf / genericFor / brandsFor / doseFormsOf / consistsOf / relatedByRela - graph navigation following authored edges only (the engine never synthesizes an inverse). An absent RXCUI is a typed RxNormUnknown.
  • resolveNdc - NDC → RXCUI carrying the temporal status and the as-of release; an absent NDC is a typed NdcUnmapped, never a guess.
  • approximateMatch - the opt-in, explicitly labeled similarity path (never the default, never an exact code assertion).

What is bundled. No code-system release is. What is bundled includes the following, named with its copyright:

  • the UCUM unit table (ucum-essence.xml, version 2.2, revision-date 2024-06-17) - copyright ©1999–2024 Regenstrief Institute, Inc., all rights reserved, reproduced verbatim under the UCUM Copyright Notice and License (https://ucum.org/license), embedded byte-for-byte in the published build and parsed at runtime; no modified or derivative copy is distributed. The UCUM Specification is provided "as is" without warranty of any kind - see the License for the full disclaimer. The complete notice ships with this package at vendor/ucum/NOTICE.md.
  • the code-system identity facts (SYSTEM_IDENTITIES) - OID ↔ canonical-URI pairings, which identify the systems rather than listing any system's codes.
  • the SNOMED CT concepts the crosswalk resolver names, each with its description: the four map-category concepts (MAP_CATEGORIES) a complex-map row's mapCategoryId refers to, and the two gender findings (248152002 Female, 248153007 Male) a gender IFA rule is written against. Further SNOMED CT identifiers, and ICD-10-CM codes, appear in the API documentation examples, which are distributed in the compiled declaration files and in the build's sourcemaps. SNOMED CT is copyright © International Health Terminology Standards Development Organisation.
  • the RxNorm relationship and term-type names the drug-graph API is written against: the relationship names in RELA / RELA_INVERSE (has_ingredient, tradename_of, …), and the term-type codes in TERM_TYPES, each with its name as published by the U.S. National Library of Medicine (SCD reads "Semantic Clinical Drug"). Individual RxNorm identifiers also appear in the API documentation examples, with their RxNorm names and term types (for instance RXCUI 316151, "lisinopril 10 MG"), and in README.md as well as the places named above. RxNorm is produced by the National Library of Medicine; no RxNorm release is bundled.

The LICENSE file that ships with this package carries the MIT text for the package's own code and a third-party notices section naming each of the above.

The content packs that would change this (the CMS GEM files, the RxNorm Current Prescribable subset) are not bundled; a caller supplies them, as they do a SNOMED CT, CPT, LOINC, UMLS or VSAC release, under whatever terms its steward sets. This states what is distributed and under whose copyright; it is not legal advice, and makes no claim about whether a particular use is permitted to you.

Classes​

Interfaces​

Type Aliases​

Variables​

Functions​