Guides

Guides

Task-by-task usage. Each section: a code example and when to use it.

Errors: ErrorCode and HolonError

ErrorCode is the enum every HOLON error and error response uses. HolonError is the base error class that carries it, with a machine-readable code and optional details.

// throw and match on HOLON errors
import { ErrorCode, HolonError, ValidationError } from "@ontomorph/holon-types";

throw new ValidationError("age must be a positive integer");

// HolonError carries a machine-readable code and optional response detail:
if (err instanceof HolonError && err.code === ErrorCode.CONCEPT_NOT_FOUND) { … }

The subclasses are thrown by the query and validation layers:

InvalidEclError

Thrown when an ECL query is malformed.

InvalidCqlError

Thrown when a CQL query is malformed.

ValidationError

Thrown when input fails validation.

TransactionError

Thrown when a transaction fails.

Use these when you want to raise or catch a HOLON error and branch on err.code rather than parsing message strings.

Results: ok(), err(), and ServiceResult

ServiceResult<T> is a discriminated-union result type used across the HOLON services. Build it with ok() for success and err() for failure.

// return a ServiceResult instead of throwing
import { ok, err, ErrorCode, type ServiceResult } from "@ontomorph/holon-types";

function lookup(id: number): ServiceResult<Concept> {
  const row = find(id);
  return row ? ok(row) : err("no such concept", ErrorCode.CONCEPT_NOT_FOUND);
}

Callers branch on .success. Use this when a function has an expected failure path and you want that failure in the return type instead of a thrown exception.

Vocabulary and domain enums

The enums name the source vocabularies, the concept domains, and the mapping classifiers.

// the supported source vocabularies
import { VocabularyId, DomainId, StandardConcept, MappingEquivalence, MappingOrigin } from "@ontomorph/holon-types";

VocabularyId.SNOMED_CT; // "SNOMED-CT"
VocabularyId.RXNORM;    // "RxNorm"
VocabularyId.LOINC;     // "LOINC"

VocabularyId

The supported source vocabularies (SNOMED-CT, RxNorm, LOINC, ICD11, HPO, FMA, and others).

DomainId

The concept domains, naming what kind of thing a concept is (a Drug, a Measurement, a Condition).

StandardConcept

The standard-concept flags.

MappingEquivalence

A classifier for how two mapped concepts relate.

MappingOrigin

A classifier for where a mapping came from.

Use these to validate identifiers from user input, or to compare against a value the API returned, without hardcoding strings. See Use-Cases for a validation example.

HOLON URI helpers

Parse and emit holon: concept URIs, and name the Turtle MIME type.

// parse and emit holon: concept URIs
import { HOLON_URI_SCHEME, type HolonUriParts, MIME_TURTLE } from "@ontomorph/holon-types";
// HOLON_URI_SCHEME === "holon"; parse and emit holon:… concept URIs, serialize as text/turtle

HOLON_URI_SCHEME

The URI scheme, equal to "holon".

HolonUriParts

The parsed pieces of a holon: URI.

MIME_TURTLE

The text/turtle MIME type, for serializing concepts as Turtle.

Use these when you emit or read HOLON concept URIs, or set a content type for Turtle output.

See also

• Concepts: what each term means.
• API-Reference: the full symbol list.