Use Cases

Use Cases

Three scenarios where you install @ontomorph/holon-types on its own.

You want to build your own transport that speaks the HOLON contract

You are writing a custom client, or a server that answers HOLON requests. You do not want the bundled HTTP client, but you do want the exact entity shapes and codes the API uses, so your responses match.

Import the response shapes and return them directly:

// a handler that returns the API's own shape
import { type ConceptResponse, ErrorCode, HolonError } from "@ontomorph/holon-types";

async function getConcept(id: number): Promise<ConceptResponse> {
  const concept = await store.find(id);
  if (!concept) {
    throw new HolonError("concept not found", ErrorCode.CONCEPT_NOT_FOUND);
  }
  return concept;
}

Because ConceptResponse is the same interface the client reads, a client built on @ontomorph/holon-client consumes your server without adapters.

You want to share error codes across a codebase

Several packages in your codebase raise and handle HOLON failures. You want one source of truth for the codes, without every package depending on the HTTP client.

Depend on @ontomorph/holon-types and match on err.code:

// central error handling, no client dependency
import { HolonError, ErrorCode } from "@ontomorph/holon-types";

function toHttpStatus(err: unknown): number {
  if (err instanceof HolonError && err.code === ErrorCode.UNAUTHORIZED) return 401;
  if (err instanceof HolonError && err.code === ErrorCode.RATE_LIMIT_EXCEEDED) return 429;
  return 500;
}

Matching on err.code rather than message strings keeps the handling stable as messages change.

You want to validate a vocabulary id from user input

A user or an upstream system hands you a vocabulary string. You want to confirm it is one HOLON supports before you pass it on.

Check the value against the VocabularyId enum:

// narrow an unknown string to a VocabularyId
import { VocabularyId, ValidationError } from "@ontomorph/holon-types";

function asVocabularyId(input: string): VocabularyId {
  const known = Object.values(VocabularyId) as string[];
  if (!known.includes(input)) {
    throw new ValidationError(`unknown vocabulary: ${input}`);
  }
  return input as VocabularyId;
}

You reject unsupported vocabularies at the boundary, with the same ValidationError the rest of HOLON uses.

See also

• Guides: the building blocks used above.
• API-Reference: every symbol these examples import.