@cosyte/terminology

A loaded RxNormGraph.

query

string

A free-text drug name to match against loaded concept names.

options?

ApproximateMatchOptions = {}

ApproximateMatchOptions (min score, limit).

Returns

readonly RxNormApproximateMatch[]

The labeled approximate candidates, best-first (possibly empty). Never an exact resolution.

Example

import { loadRxNormGraph, approximateMatch } from "@cosyte/terminology";

const g = loadRxNormGraph({
  conso: "1|ENG||||||||||RXNORM|IN||lisinopril||N||",
  rel: "",
});
approximateMatch(g, "lisinopril")[0]?.approximate; // => true

asTermType()

asTermType(tty): TermType | undefined

Narrow a raw RXNCONSO.TTY string to a known TermType, or undefined when it is not a drug-graph term type this engine models (the atom is then skipped at load, liberal-on-load, never coerced to a wrong type).

Parameters

tty

string

The raw TTY value from an RXNCONSO row.

Returns

TermType | undefined

The narrowed TermType, or undefined when unrecognized.

Example

import { asTermType } from "@cosyte/terminology";

asTermType("SCD"); // => "SCD"
asTermType("ZZZ"); // => undefined

brandsFor()

brandsFor(graph, rxcui): RxNormNavResult

The branded form(s) of a generic concept: an SCD/IN/GPCK that has_tradename a brand. The authored forward edge; not a synthesized inverse of tradename_of.

Parameters

graph

A loaded RxNormGraph.

rxcui

string

The generic concept.

Returns

The branded concept(s) (possibly empty), or a typed unknown source.

Example

import { loadRxNormGraph, brandsFor } from "@cosyte/terminology";

const g = loadRxNormGraph({
  conso: "1|ENG||||||||||RXNORM|SCD||lisinopril 10 MG Oral Tablet||N||\n2|ENG||||||||||RXNORM|SBD||lisinopril 10 MG Oral Tablet [Zestril]||N||",
  rel: "2|||RN|1|||has_tradename|||RXNORM||||||",
});
brandsFor(g, "1").found; // => true

buildSubsumption()

buildSubsumption(cs): Subsumption

Build a cycle-safe ancestor index from a loaded CodeSystem's parent concept-properties.

Parameters

cs

The loaded code system.

Returns

Subsumption

A Subsumption answering transitive-ancestor queries.

Example

import { loadCodeSystem, buildSubsumption } from "@cosyte/terminology";

const cs = loadCodeSystem({
  format: "fhir",
  resource: { resourceType: "CodeSystem", concept: [{ code: "p", concept: [{ code: "c" }] }] },
});
buildSubsumption(cs).ancestorsOf("c").has("p"); // => true

codeableConcept()

codeableConcept(init): CodeableConcept

Construct a deep-frozen CodeableConcept (its coding array and every member frozen).

Parameters

init

CodeableConcept

The concept fields; coding is required (may be empty).

Returns

CodeableConcept

A frozen CodeableConcept.

Example

import { codeableConcept } from "@cosyte/terminology";

const cc = codeableConcept({ coding: [{ code: "2160-0" }] });
Object.isFrozen(cc.coding); // => true

coding()

coding(init): Coding

Construct a deep-frozen Coding.

The returned object is Object.freezed so it cannot be mutated in place: parsed/translated values are immutable by default. Optional fields are only present when supplied (no undefined keys), so structural equality checks stay clean.

Parameters

init

The coding fields; code is required.

Returns

A frozen Coding.

Example

import { coding } from "@cosyte/terminology";

const frozen = coding({ system: "http://loinc.org", code: "2160-0" });
Object.isFrozen(frozen); // => true

consistsOf()

consistsOf(graph, rxcui): RxNormNavResult

The components a drug consists_of: an SCD/SBD → its SCDC/SBDC dose-form components.

Parameters

graph

A loaded RxNormGraph.

rxcui

string

The drug concept.

Returns

The component concept(s) (possibly empty), or a typed unknown source.

Example

import { loadRxNormGraph, consistsOf } from "@cosyte/terminology";

const g = loadRxNormGraph({
  conso: "2|ENG||||||||||RXNORM|SCD||lisinopril 10 MG Oral Tablet||N||\n3|ENG||||||||||RXNORM|SCDC||lisinopril 10 MG||N||",
  rel: "3|||RN|2|||consists_of|||RXNORM||||||",
});
consistsOf(g, "2").found; // => true

doseFormsOf()

doseFormsOf(graph, rxcui): RxNormNavResult

The dose form(s) of a drug: the DF/DFG concepts it has_dose_form / has_doseformgroup.

Parameters

graph

A loaded RxNormGraph.

rxcui

string

The drug concept.

Returns

The dose-form concept(s) (possibly empty), or a typed unknown source.

Example

import { loadRxNormGraph, doseFormsOf } from "@cosyte/terminology";

const g = loadRxNormGraph({
  conso: "1|ENG||||||||||RXNORM|SCD||lisinopril 10 MG Oral Tablet||N||\n9|ENG||||||||||RXNORM|DF||Oral Tablet||N||",
  rel: "9|||RN|1|||has_dose_form|||RXNORM||||||",
});
doseFormsOf(g, "1").found; // => true

expand()

expand(vs, ctx?): ExpandResult

$expand: compute the flattened membership of a ValueSet over the supplied code systems.

Parameters

vs

ValueSet

The loaded value set.

ctx?

ExpansionContext = {}

The loaded code systems / referenced value sets the intensional parts resolve against.

Returns

ExpandResult

An ExpandResult: the contains members plus an honest complete flag. When complete is false, contains is a lower bound (never treat it as exhaustive membership).

Example

import { loadValueSet, loadCodeSystem, expand } from "@cosyte/terminology";

const cs = loadCodeSystem({
  format: "fhir",
  resource: {
    resourceType: "CodeSystem",
    url: "http://example.org/cs",
    concept: [{ code: "a" }, { code: "b" }, { code: "c" }],
  },
});
const vs = loadValueSet({
  resourceType: "ValueSet",
  compose: { include: [{ system: "http://example.org/cs", concept: [{ code: "a" }, { code: "b" }] }] },
});
const result = expand(vs, { codeSystems: new Map([["http://example.org/cs", cs]]) });
result.complete; // => true
result.contains.length; // => 2

genericFor()

genericFor(graph, rxcui): RxNormNavResult

The generic form(s) of a branded concept: an SBD/BN/BPCK tradename_of its generic. The authored forward edge; the engine never inverts a has_tradename edge to synthesize this.

Parameters

graph

A loaded RxNormGraph.

rxcui

string

The branded concept.

Returns

The generic concept(s) (possibly empty), or a typed unknown source.

Example

import { loadRxNormGraph, genericFor } from "@cosyte/terminology";

// "SBD(2) tradename_of SCD(1)": subject=RXCUI2=2, object=RXCUI1=1.
const g = loadRxNormGraph({
  conso: "1|ENG||||||||||RXNORM|SCD||lisinopril 10 MG Oral Tablet||N||\n2|ENG||||||||||RXNORM|SBD||lisinopril 10 MG Oral Tablet [Zestril]||N||",
  rel: "1|||RN|2|||tradename_of|||RXNORM||||||",
});
genericFor(g, "2").found; // => true

getArray()

getArray(obj, key): readonly unknown[] | undefined

Read an array property from an untrusted object as a readonly unknown[], or undefined.

The elements are left as unknown: callers narrow each one. A non-array (including a missing key) yields undefined, which callers treat as "no entries" rather than an error.

Parameters

obj

unknown

The source object (may be any unknown).

key

string

The property name to read.

Returns

readonly unknown[] | undefined

The array (elements untyped), or undefined when the key is missing or not an array.

Example

import { getArray } from "@cosyte/terminology";

getArray({ group: [{ source: "a" }] }, "group")?.length; // => 1

getBoolean()

getBoolean(obj, key): boolean | undefined

Read a boolean property from an untrusted object, or undefined if absent/not a boolean.

A non-boolean (including a missing key, or the strings "true"/"false") yields undefined: the accessor never coerces, so a caller can distinguish "explicitly false" from "absent".

Parameters

obj

unknown

The source object (may be any unknown).

key

string

The property name to read.

Returns

boolean | undefined

The boolean value, or undefined when the key is missing or not a boolean.

Example

import { getBoolean } from "@cosyte/terminology";

getBoolean({ inactive: true }, "inactive"); // => true

getConcept()

getConcept(graph, rxcui): RxNormConcept | undefined

Look up a single concept by RXCUI.

Parameters

graph

A loaded RxNormGraph.

rxcui

string

The concept unique identifier.

Returns

RxNormConcept | undefined

The RxNormConcept, or undefined when the RXCUI is not in the release.

Example

import { loadRxNormGraph, getConcept } from "@cosyte/terminology";

const g = loadRxNormGraph({ conso: "1|ENG||||||||||RXNORM|IN||aspirin||N||", rel: "" });
getConcept(g, "1")?.tty; // => "IN"

getNumber()

getNumber(obj, key): number | undefined

Read a number property from an untrusted object, or undefined if absent/not a finite number.

Parameters

obj

unknown

The source object (may be any unknown).

key

string

The property name to read.

Returns

number | undefined

The number value, or undefined when the key is missing or not a finite number.

Example

import { getNumber } from "@cosyte/terminology";

getNumber({ valueInteger: 3 }, "valueInteger"); // => 3

getString()

getString(obj, key): string | undefined

Read a string property from an untrusted object, or undefined if absent/not a string.

Parameters

obj

unknown

The source object (may be any unknown).

key

string

The property name to read.

Returns

string | undefined

The string value, or undefined when the key is missing or not a string.

Example

import { getString } from "@cosyte/terminology";

getString({ url: "http://loinc.org" }, "url"); // => "http://loinc.org"

ingredientsOf()

ingredientsOf(graph, rxcui): RxNormNavResult

The ingredients of a concept: the concepts it links to by a direct has_ingredient / has_precise_ingredient edge in the loaded release.

This follows the authored, direct edge only (never-fabricate, never a synthesized path), and RxNorm's ingredient topology is not the obvious one. Always read the TTY of what comes back:

concepts on the clinical side (SCDC, SCDF, SCDG) link to the ingredient itself, an IN;
concepts on the branded side (SBD, SBDC, SBDF, SBDG) link to their brand name, a BN. That is what the release says and what is echoed back, term type included. It is not the active ingredient. (has_precise_ingredient, which this function also follows, likewise reaches a PIN.)
a clinical drug (SCD) carries no has_ingredient edge at all. RxNorm authors none, in any release, so this honestly returns found-with-empty-targets rather than walking a path on the caller's behalf.
the precise forms (SCDFP, SBDFP, SCDGP) carry neither edge, so this returns found-with-empty-targets for them too. They do not behave like their non-precise siblings: an SCDFP reaches its basis-of-strength substance(s) by has_boss, a one-to-many relation with a different meaning whose targets can be a PIN or a plain IN, and which this function deliberately does not follow; an SBDFP and an SCDGP author no ingredient-bearing edge at all and are reached instead through form_of / tradename_of / isa.

Those pairings are the ones RxNorm authors, not a closed set a caller may rely on: check the returned TTY rather than assuming it from the one you queried.

To reach an active ingredient, walk to the CLINICAL component and take its edge. From an SCD that is SCD ⟶consists_of⟶ SCDC ⟶has_ingredient⟶ IN, i.e. consistsOf then ingredientsOf. From an SBD it needs one more decision, because consists_of returns both its branded component (SBDC, whose own ingredient edge is the BN again) and the clinical SCDC: it is the SCDC that leads to the IN. The engine never invents the transitive edge and never picks that branch for you.

Parameters

graph

A loaded RxNormGraph.

rxcui

string

The concept (a drug or a clinical/branded component).

Returns

The directly-linked ingredient concepts (possibly empty), or a typed unknown source.

Example

import { loadRxNormGraph, ingredientsOf } from "@cosyte/terminology";

// The ingredient edge is authored on the COMPONENT, not on the clinical drug.
const g = loadRxNormGraph({
  conso: "1|ENG||||||||||RXNORM|IN||lisinopril||N||\n2|ENG||||||||||RXNORM|SCDC||lisinopril 10 MG||N||",
  rel: "1|||RN|2|||has_ingredient|||RXNORM||||||",
});
ingredientsOf(g, "2").found; // => true

invertGem()

invertGem(map): never

Refuse to invert a directional GEM map. Always throws FATAL_CODES.TERM_MAP_NOT_INVERTIBLE.

The never-invert invariant made explicit and discoverable: a forward GEM (9→10) is not the inverse of the backward GEM (10→9): CMS ships them as separate artifacts and "forward and backward mappings are not simply the reverse". To resolve the other direction, load the other file with loadGems; the engine never synthesizes an inverse.

Parameters

map

GemMap

The map an inversion was (incorrectly) requested for.

Returns

never

Never: always throws.

Throws

TERM_MAP_NOT_INVERTIBLE, always.

Example

import { loadGems, invertGem } from "@cosyte/terminology";

const gems = loadGems({ direction: "9-to-10", content: "0010 A000 00000\n" });
invertGem(gems); // throws TERM_MAP_NOT_INVERTIBLE

isA()

isA(sub, code, anchor): boolean

True when code is-a anchor: the same code, or a (transitive) descendant of it.

Parameters

sub

Subsumption

The subsumption index (from buildSubsumption).

code

string

The candidate code.

anchor

string

The ancestor code to test against.

Returns

boolean

Whether code is anchor or a descendant of it.

Example

import { loadCodeSystem, buildSubsumption, isA } from "@cosyte/terminology";

const cs = loadCodeSystem({
  format: "fhir",
  resource: { resourceType: "CodeSystem", concept: [{ code: "p", concept: [{ code: "c" }] }] },
});
isA(buildSubsumption(cs), "c", "p"); // => true

isJsonObject()

isJsonObject(value): value is Record<string, unknown>

Narrow an unknown to a plain JSON object (a non-null, non-array object).

Parameters

value

unknown

The value to test.

Returns

value is Record<string, unknown>

true when value is a non-null, non-array object.

Example

import { isJsonObject } from "@cosyte/terminology";

isJsonObject({ resourceType: "ConceptMap" }); // => true

isSynonymTermType()

isSynonymTermType(tty): boolean

Is this term type a synonym-class one (PSN / SY / TMSY)?

Appendix 5 defines each as a "synonym of another TTY": it labels an alternate name for a concept, never the concept's own kind. So a synonym atom can never establish an RXCUI's term type, and ../rxnorm/load.loadRxNormGraph will not let one: an RXCUI whose release supplies only synonym atoms is skipped and surfaced, never typed "TMSY".

Parameters

tty

TermType

A TermType.

Returns

boolean

true for PSN / SY / TMSY; false for every defining term type.

Example

import { isSynonymTermType } from "@cosyte/terminology";

isSynonymTermType("TMSY"); // => true
isSynonymTermType("SCDF"); // => false

isUnknownSystem()

isUnknownSystem(result): result is UnknownSystem

Type guard: did resolveSystem fail to recognize the identifier?

Parameters

result

ResolveSystemResult

A resolveSystem result.

Returns

result is UnknownSystem

true when the result is a typed UnknownSystem.

Example

import { resolveSystem, isUnknownSystem } from "@cosyte/terminology";

isUnknownSystem(resolveSystem("nope")); // => true

loadCodeSystem()

loadCodeSystem(source): CodeSystem

Load a consumer-supplied code-system release into an immutable, queryable CodeSystem.

Dispatches on source.format:

"rrf": pipe-delimited RxNorm/UMLS release (one parameterized reader for both).
"csv": RFC-4180 CSV (e.g. LOINC Loinc.csv), with real quote handling.
"fixed-width": slice-by-column order files (e.g. ICD-10-CM; see ICD10CM_ORDER_FILE_FIELDS).
"fhir": a native FHIR R4 CodeSystem JSON resource.

Liberal on load: a malformed row is skipped and surfaced in warnings (never a crash, never a partial concept). Conservative on structure: an unusable source (wrong FHIR resourceType, or a CSV whose configured columns are absent from the header) throws a typed TerminologyError carrying TERM_CODESYSTEM_MALFORMED.

Parameters

source

CodeSystemSource

The release descriptor (a discriminated CodeSystemSource).

Returns

The immutable, deep-frozen CodeSystem.

Throws

TERM_CODESYSTEM_MALFORMED when the source is structurally unusable.

Example

import { loadCodeSystem } from "@cosyte/terminology";

const cs = loadCodeSystem({
  format: "fhir",
  resource: {
    resourceType: "CodeSystem",
    url: "http://example.org/cs",
    concept: [{ code: "A", display: "Alpha" }],
  },
});
cs.count; // => 1

loadComplexMap()

loadComplexMap(input): ComplexMap

Load a SNOMED→ICD-10-CM complex map from caller-supplied rows or a raw RF2 refset into an immutable ComplexMap, keyed by source concept and ordered by (group, priority).

Liberal on load: a structurally unusable RF2 row is skipped and surfaced as a warning; only an unusable source (empty content, header missing required columns) is a fatal FATAL_CODES.TERM_CROSSWALK_MALFORMED. Ships no SNOMED CT release or refset: the rows are the caller's, under their own licence.

Parameters

input

ComplexMapInput

Structured rows, or a raw RF2 extended-map refset content.

Returns

ComplexMap

The immutable ComplexMap.

Throws

TERM_CROSSWALK_MALFORMED when the source is structurally unusable.

Example

import { loadComplexMap } from "@cosyte/terminology";

const map = loadComplexMap({
  format: "rows",
  rows: [
    { source: "195967001", group: 1, priority: 1, rule: "TRUE", advice: "ALWAYS J45.909", target: "J45.909", category: "447637006" },
  ],
});
map.count; // => 1

loadConceptMap()

loadConceptMap(json): ConceptMap

Load an untrusted FHIR R4 ConceptMap JSON value into an immutable ConceptMap.

Accepts the standard resource shape: a top-level object with resourceType: "ConceptMap" and an optional group[]. source[x]/target[x] scopes are read from either the Uri or Canonical variant. The result is deep-frozen. Anything structurally unusable throws a TerminologyError carrying FATAL_CODES.TERM_CONCEPTMAP_MALFORMED.

Parameters

json

unknown

The untrusted resource (typically JSON.parse output, hence unknown).

Returns

ConceptMap

The immutable, validated ConceptMap.

Throws

TERM_CONCEPTMAP_MALFORMED when the resource is not a usable ConceptMap.

Example

import { loadConceptMap } from "@cosyte/terminology";

const map = loadConceptMap({
  resourceType: "ConceptMap",
  url: "http://example.org/cm/gender",
  group: [
    {
      source: "http://hl7.org/fhir/administrative-gender",
      target: "http://terminology.hl7.org/CodeSystem/v2-0001",
      element: [{ code: "male", target: [{ code: "M", equivalence: "equivalent" }] }],
    },
  ],
});
map.group.length; // => 1

loadGems()

loadGems(source): GemMap

Load a CMS GEM file into an immutable GemMap, keyed by source code.

Liberal on load: a structurally unusable line (not three whitespace-delimited fields, or a malformed 5-digit flag) is skipped and surfaced as a GemLoadWarning, never a partially-parsed entry. An unusable source is not possible here (an all-malformed file loads to an empty map with warnings): there is no fatal for GEM load. Ships no GEM content: the entries are the caller's public-domain file.

Parameters

source

GemSource

The GemSource (raw content + direction + version).

Returns

GemMap

The immutable GemMap.

Example

import { loadGems, applyGem } from "@cosyte/terminology";

// Synthetic rows in the CMS GEM format (source target flags): an exact map and a No-Map.
const gems = loadGems({
  direction: "9-to-10",
  version: "2018",
  content: "0010 A000 00000\nV290 NoDx 11000\n",
});
applyGem(gems, "0010").mapped; // => true

loadRxNormGraph()

loadRxNormGraph(source): RxNormGraph

Load a caller-supplied RxNorm RRF release into an immutable RxNormGraph.

Parses RXNCONSO (concepts), RXNREL (directed edges, normalized to the documented direction), and (when supplied) RXNSAT (NDC attributes). Liberal on load: a structurally unusable row is a skipped, surfaced RxNormLoadWarning, never partial. Ships no RxNorm release: the graph is entirely the caller's release.

A concept is typed only by a defining atom, never by a synonym-class one and never by file order; an RXCUI no defining atom could type is skipped and surfaced as TERM_RXNORM_UNTYPED_CONCEPT. See the module documentation.

Parameters

source

RxNormGraphSource

The RxNormGraphSource (RRF file contents + optional version).

Returns

The immutable RxNormGraph.

Example

import { loadRxNormGraph } from "@cosyte/terminology";

// Synthetic rows in the RxNorm RRF wire format (no RxNorm release is bundled).
const graph = loadRxNormGraph({
  conso: "1|ENG||||||||||RXNORM|IN||lisinopril||N||\n2|ENG||||||||||RXNORM|SCDC||lisinopril 10 MG||N||",
  // "SCDC(2) has_ingredient IN(1)": subject=RXCUI2=2, object=RXCUI1=1.
  rel: "1|||RN|2|||has_ingredient|||RXNORM||||||",
});
graph.conceptCount; // => 2

loadUcumEssence()

loadUcumEssence(): UcumEssence

Load the UCUM essence table, parsing the embedded verbatim XML on first call and caching it.

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

UcumEssence

The shared, frozen in-memory UcumEssence model.

Example

import { loadUcumEssence } from "@cosyte/terminology";

const essence = loadUcumEssence();
essence.atomByCode.has("m"); // => true

loadValueSet()

loadValueSet(json): ValueSet

Load an untrusted FHIR R4 ValueSet JSON value into an immutable ValueSet.

Accepts the standard resource shape: resourceType: "ValueSet" with an optional intensional compose (include/exclude of system/concept/filter/valueSet) and/or a pre-computed expansion (contains, with total and the valueset-toocostly extension read into a derived truncated flag). The result is deep-frozen. Anything structurally unusable throws a TerminologyError carrying FATAL_CODES.TERM_VALUESET_MALFORMED.

Parameters

json

unknown

The untrusted resource (typically JSON.parse output, hence unknown).

Returns

ValueSet

The immutable, validated ValueSet.

Throws

TERM_VALUESET_MALFORMED when the resource is not a usable ValueSet.

Example

import { loadValueSet } from "@cosyte/terminology";

const vs = loadValueSet({
  resourceType: "ValueSet",
  url: "http://example.org/vs/colors",
  compose: {
    include: [{ system: "http://example.org/cs", concept: [{ code: "red" }, { code: "green" }] }],
  },
});
vs.compose?.include.length; // => 1

lookup()

lookup(cs, code): LookupOutcome

$lookup: resolve a code to its display, definition, status, and properties in a loaded release.

Parameters

cs

The loaded CodeSystem.

code

string

The code to look up.

Returns

LookupOutcome

A LookupResult when found, or a typed LookupUnknown: never a guess.

Example

import { loadCodeSystem, lookup } from "@cosyte/terminology";

const cs = loadCodeSystem({
  format: "fhir",
  resource: { resourceType: "CodeSystem", concept: [{ code: "A", display: "Alpha" }] },
});
const r = lookup(cs, "A");
r.found === true && r.display; // => "Alpha"

makeStatus()

makeStatus(activity, raw?, billable?): ConceptStatus

Assemble a frozen ConceptStatus from a normalized activity, carrying the raw token and (for classification systems) the billable flag, and attaching the stable diagnostic code for the two concerns it distinguishes: TERM_CONCEPT_DEPRECATED and TERM_CONCEPT_HEADER_NOT_BILLABLE.

Parameters

activity

ConceptActivity

The normalized activity.

raw?

string

The verbatim steward token, if any (omitted from the result when empty).

billable?

boolean

The billable flag for a classification system, if applicable.

Returns

ConceptStatus

A frozen ConceptStatus.

Example

import { makeStatus } from "@cosyte/terminology";

makeStatus("deprecated", "DEPRECATED").code; // => "TERM_CONCEPT_DEPRECATED"

matchesFilter()

matchesFilter(concept, filter, sub): FilterMatch

Evaluate one ConceptSetFilter against one Concept, using the release's hierarchy.

The concept filter property (and the hierarchy operators regardless of property) reads the code itself / its subsumption; other properties read the concept's property values. An unimplemented operator returns { supported: false }: never a coerced matched.

Parameters

concept

Concept

The concept under test.

filter

ConceptSetFilter

The filter predicate.

sub

Subsumption

The subsumption index for the concept's code system.

Returns

FilterMatch

A FilterMatch.

Example

import { loadCodeSystem, buildSubsumption, matchesFilter } from "@cosyte/terminology";

const cs = loadCodeSystem({
  format: "fhir",
  resource: { resourceType: "CodeSystem", concept: [{ code: "p", concept: [{ code: "c" }] }] },
});
const dog = cs.concepts.get("c");
dog && matchesFilter(dog, { property: "concept", op: "is-a", value: "p" }, buildSubsumption(cs)).matched; // => true

parseCsv()

parseCsv(content): string[][]

Parse RFC-4180 CSV content into rows of fields (the .rows of parseCsvRows). Lenient: a stray mid-field quote is literal, so a malformed quote never silently swallows subsequent rows.

Parameters

content

string

The raw CSV text.

Returns

string[][]

The rows, each an array of field strings (untrimmed).

Example

import { parseCsv } from "@cosyte/terminology";

parseCsv('a,b\n"x,y","z""q"'); // => [["a", "b"], ["x,y", 'z"q']]

parseCsvSource()

parseCsvSource(source): object

Parse a CsvSource into concepts and skipped-row warnings.

Parameters

source

CsvSource

The CSV source.

Returns

object

The parsed concepts (by code) and the load warnings.

concepts

concepts: Map<string, Concept>

warnings

warnings: LoadWarning[]

Throws

TERM_CODESYSTEM_MALFORMED when the file has no header row, or a configured code/display/status/property column is absent from the header. The message names the missing column's role, never the name you configured.

Example

import { parseCsvSource } from "@cosyte/terminology";

const { concepts } = parseCsvSource({
  format: "csv",
  content: "CODE,NAME\n2160-0,Creatinine",
  columns: { code: "CODE", display: "NAME" },
});
concepts.get("2160-0")?.display; // => "Creatinine"

parseFhirCodeSystem()

parseFhirCodeSystem(source): object

Parse a FhirCodeSystemSource into concepts, a resolved url/version/name, and warnings.

Parameters

source

FhirCodeSystemSource

The FHIR CodeSystem source.

Returns

object

The parsed concepts (by code), the load warnings, and the resource metadata.

concepts

concepts: Map<string, Concept>

name?

optional name?: string

url?

optional url?: string

version?

optional version?: string

warnings

warnings: LoadWarning[]

Throws

TERM_CODESYSTEM_MALFORMED when the resource is not a FHIR CodeSystem.

Example

import { parseFhirCodeSystem } from "@cosyte/terminology";

const { concepts } = parseFhirCodeSystem({
  resource: { resourceType: "CodeSystem", concept: [{ code: "A", display: "Alpha" }] },
  format: "fhir",
});
concepts.get("A")?.display; // => "Alpha"

parseFixedWidth()

parseFixedWidth(source): object

Parse a FixedWidthSource into concepts and skipped-row warnings.

Parameters

source

FixedWidthSource

The fixed-width source.

Returns

object

The parsed concepts (by code) and the load warnings.

concepts

concepts: Map<string, Concept>

warnings

warnings: LoadWarning[]

Example

import { parseFixedWidth } from "@cosyte/terminology";

const { concepts } = parseFixedWidth({
  format: "fixed-width",
  content: "A00 1 Cholera",
  fields: { code: { start: 0, end: 3 }, display: { start: 6 } },
});
concepts.get("A00")?.display; // => "Cholera"

parseRrf()

parseRrf(source): object

Parse an RrfSource into concepts (first row per code wins) and skipped-row warnings.

A code that recurs across rows (RRF repeats a code once per atom/attribute) keeps its first occurrence, a documented v1 limitation: preferred-atom selection (TS/STT/ISPREF) and attribute merging are later work. The result is data only; loadCodeSystem freezes it.

Parameters

source

RrfSource

The RRF source.

Returns

object

The parsed concepts (by code) and the load warnings.

concepts

concepts: Map<string, Concept>

warnings

warnings: LoadWarning[]

Example

import { parseRrf } from "@cosyte/terminology";

const { concepts } = parseRrf({
  format: "rrf",
  content: "1|Aspirin|",
  columns: { code: 0, display: 1 },
});
concepts.get("1")?.display; // => "Aspirin"

parseRrfLine()

parseRrfLine(line): readonly string[]

Split one RRF line into its fields, dropping the single reserved trailing pipe.

Parameters

line

string

One RRF line (no line terminator).

Returns

readonly string[]

The fields, in column order.

Example

import { parseRrfLine } from "@cosyte/terminology";

parseRrfLine("316151|ENG|lisinopril 10 MG|"); // => ["316151", "ENG", "lisinopril 10 MG"]

parseUcum()

parseUcum(unit): ParseResult

Parse a UCUM unit expression into an AST.

Parameters

unit

string

The unit expression (e.g. "mmol/L", "kg.m/s2", "10*3/ul").

Returns

ParseResult

The parsed UnitNode, or a typed ParseFailure with a value-free reason.

Example

import { parseUcum } from "@cosyte/terminology";

parseUcum("mmol/L").ok; // => true
parseUcum("m/").ok; // => false

reduce()

reduce(node): Reduction

Reduce a parsed UCUM unit to its canonical Reduction: a linear scalar×dimension form, or an opaque special form for expressions involving a non-linear special unit.

The reduction of one atom is cached against that atom object, so a UnitNode you assembled yourself is answered from its own atoms and cannot change how a unit off parseUcum reduces, in this call or any later one.

Parameters

node

UnitNode

The AST from parseUcum.

Returns

Reduction

The reduced form.

Throws

If reducing node reaches an atom with no linear definition, or one whose definition does not parse. No expression 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 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

import { parseUcum, reduce } from "@cosyte/terminology";

const parsed = parseUcum("N");
if (parsed.ok) {
  const r = reduce(parsed.node);
  r.kind; // => "linear"  (1000 × g·m·s⁻²)
}

relatedByRela()

relatedByRela(graph, rxcui, predicate): RxNormNavResult

Follow one or more RELA predicates out of a concept (the generic navigation primitive). Direction is the authored edge direction (subject ⟶predicate⟶ object); the engine never inverts.

Parameters

graph

A loaded RxNormGraph.

rxcui

string

The source concept.

predicate

string | readonly string[]

A RELA name, or an array of them (any-of).

Returns

A RxNormNavResult: the related concepts (possibly empty), or a typed unknown source.

Example

import { loadRxNormGraph, relatedByRela, RELA } from "@cosyte/terminology";

// "SCDC(2) has_ingredient IN(1)": subject=RXCUI2=2, object=RXCUI1=1.
const g = loadRxNormGraph({
  conso: "1|ENG||||||||||RXNORM|IN||lisinopril||N||\n2|ENG||||||||||RXNORM|SCDC||lisinopril 10 MG||N||",
  rel: "1|||RN|2|||has_ingredient|||RXNORM||||||",
});
const r = relatedByRela(g, "2", RELA.HAS_INGREDIENT);
r.found && r.targets[0]?.name; // => "lisinopril"

resolveNdc()

resolveNdc(graph, ndc): NdcResult

Resolve an NDC (National Drug Code) to its RXCUI in the loaded release, carrying the temporal status and the as-of release. NDC↔RXCUI is many:1 and changes across releases, so an NDC present in the release is active as of that release; an absent NDC is a typed NdcUnmapped, never a guessed RXCUI.

Parameters

graph

A loaded RxNormGraph (load with sat supplied to populate NDC attributes).

ndc

string

The NDC (as it appears in the release, e.g. 11-digit).

Returns

NdcResult

An NdcResult: a resolution with status + asOf, or a typed absence.

Example

import { loadRxNormGraph, resolveNdc } from "@cosyte/terminology";

const g = loadRxNormGraph({
  conso: "2|ENG||||||||||RXNORM|SCD||lisinopril 10 MG Oral Tablet||N||",
  rel: "",
  sat: "2||||||||NDC|RXNORM|00000000000|N||",
  version: "RXNORM_2026AA",
});
const r = resolveNdc(g, "00000000000");
r.resolved && r.status; // => "active"

resolveSystem()

resolveSystem(id): ResolveSystemResult

Resolve a code-system identifier to its canonical SystemIdentity.

Accepts, in order of attempt: a canonical URI (case-insensitive), a v2-XXXX mnemonic or a v2 table URI/OID (resolved structurally), a bare or urn:oid:-prefixed OID, or an HL7 v2 Table 0396 mnemonic. Whitespace is trimmed. An empty or unrecognized identifier yields a typed UnknownSystem: the resolver never invents a URI.

Parameters

id

string

The identifier (canonical URI, OID, urn:oid: OID, or mnemonic).

Returns

ResolveSystemResult

The resolved SystemIdentity, or { unknown: true, input }.

Example

import { resolveSystem } from "@cosyte/terminology";

resolveSystem("2.16.840.1.113883.6.1"); // => { url: "http://loinc.org", … }
resolveSystem("SCT"); // => { url: "http://snomed.info/sct", … }
resolveSystem("http://example.com/nope"); // => { unknown: true, input: "http://example.com/nope" }

sliceField()

sliceField(line, slice): string

Extract and trim a FieldSlice from a line (end omitted slices to end of line).

Parameters

line

string

The source line.

slice

FieldSlice

The half-open [start, end) slice.

Returns

string

The trimmed field text (empty when the slice is entirely past the line's end).

Example

import { sliceField } from "@cosyte/terminology";

sliceField("00001 A00     1 Cholera", { start: 6, end: 13 }); // => "A00"

translate()

translate(sourceCoding, map): TranslateResult

Translate a source Coding through a loaded ConceptMap.

Matches the coding's code against each applicable group's element.code (the source side, never targets, so the map is never inverted) and returns every declared target for it. A target with an unmatched equivalence, or with no code, is treated as "no target" (the FHIR way of asserting a non-mapping), and does not count as a match. When nothing matches, the map author's group.unmapped directive (if any) is reported via the result's UnmappedMode but never silently applied.

Parameters

sourceCoding

The source concept to translate.

map

ConceptMap

A ConceptMap from loadConceptMap.

Returns

TranslateResult

A TranslateResult: matched targets, or a typed unmapped outcome.

Example

import { loadConceptMap, translate } from "@cosyte/terminology";

const map = loadConceptMap({
  resourceType: "ConceptMap",
  group: [
    {
      source: "http://hl7.org/fhir/administrative-gender",
      target: "http://terminology.hl7.org/CodeSystem/v2-0001",
      element: [{ code: "male", target: [{ code: "M", equivalence: "equivalent" }] }],
    },
  ],
});
const r = translate(
  { system: "http://hl7.org/fhir/administrative-gender", code: "male" },
  map,
);
r.unmapped; // => false

ucumEqual()

ucumEqual(a, b): boolean

Whether two UCUM expressions denote the same unit: i.e. they reduce to the same canonical form (equal base dimensions and equal scale). This recognizes representational equivalences (N ≡ kg.m/s2, mmol/L ≡ mmol.L-1, annotations inert) but is not magnitude conversion: mg and g are different units and compare unequal.

A unit is never equal to an invalid expression, and a special (non-linear) unit (Cel, [pH]) is equal only to a structurally identical special unit: never to a linear unit (the never-fabricate posture: the engine will not assert an equivalence it cannot prove).

Parameters

a

string

The first UCUM unit expression.

b

string

The second UCUM unit expression.

Returns

boolean

true iff both are valid and denote the same unit.

Example

import { ucumEqual } from "@cosyte/terminology";

ucumEqual("N", "kg.m/s2"); // => true
ucumEqual("mmol/L", "mmol.L-1"); // => true
ucumEqual("mg", "g"); // => false

unsupportedOps()

unsupportedOps(filters): readonly ConceptSetFilter[]

The filters whose operator the engine does not implement (regex / generalizes / unknown): a non-empty result means the caller must surface a typed cannot-expand, never mis-expand.

Parameters

filters

readonly ConceptSetFilter[]

The component's filters.

Returns

readonly ConceptSetFilter[]

The subset with an unimplemented operator (empty when all are supported).

Example

import { unsupportedOps } from "@cosyte/terminology";

unsupportedOps([{ property: "concept", op: "is-a", value: "x" }]).length; // => 0

validateCode()

validateCode(cs, code): ValidateCodeResult

$validate-code: is code a valid member of the loaded code system?

A found code is valid: true, carrying its status (a deprecated or header code is present but flagged: never silently clean). An absent code is valid: false with TERM_CODE_UNKNOWN, never a guessed true.

Parameters

cs

The loaded CodeSystem.

code

string

The code to validate.

Returns

ValidateCodeResult

A ValidateCodeResult.

Example

import { loadCodeSystem, validateCode } from "@cosyte/terminology";

const cs = loadCodeSystem({
  format: "fhir",
  resource: { resourceType: "CodeSystem", concept: [{ code: "A", display: "Alpha" }] },
});
validateCode(cs, "A").valid; // => true
validateCode(cs, "ZZZ").valid; // => false

validateCodeInValueSet()

validateCodeInValueSet(coding, valueSet, ctx?): ValueSetMembership

$validate-code (ValueSet): is coding a member of valueSet?

Parameters

coding