Skip to main content
Version: v0.0.2

@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 for the UCUM unit table, the code-system identities (OID ↔ URI) and the SNOMED CT concepts the crosswalk resolver 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 content - BYO release.
  • 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. SNOMED CT is copyright © International Health Terminology Standards Development Organisation.

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​