@opencharts/core

Foundational zero-dependency primitives for the OpenCharts ecosystem.

Overview

@opencharts/core contains the shared building blocks that every other OpenCharts package depends on. It has no runtime dependencies and no side effects on import.

• Entity — base class providing typed validation helpers and serialization utilities for all domain entities.
• deepFreeze — recursively freeze objects so published registry definitions are genuinely immutable.
• OUTCOMES — canonical outcome vocabulary shared across adapters and integrations.
• DEPENDENCY_RELATIONS / DEPENDENCY_REQUIRES — canonical enums for workflow step dependency expressions.

Installation

npm install @opencharts/core

Usage

Entity base class

Extend Entity to build validated, serializable domain objects.

import { Entity } from '@opencharts/core';

class PatientName extends Entity {
  static REQUIRED_FIELDS = ['family'];

  #data = {};

  constructor(data = {}) {
    super();
    if (data.family != null) this.family = data.family;
    if (data.given != null)  this.given  = data.given;
  }

  get family() { return this.#data.family; }
  set family(value) { this.#data.family = this.string(value, 'family'); }

  get given() { return this.#data.given; }
  set given(value) { this.#data.given = this.stringArray(value, 'given'); }

  validate() {
    this.validateRequired(this.#data, PatientName.REQUIRED_FIELDS);
    return this;
  }

  toJSON() { return this.serialize(this.#data); }
}

const name = new PatientName({ family: 'Smith', given: ['John', 'Paul'] });
name.validate();
console.log(name.toJSON());
// { family: 'Smith', given: ['John', 'Paul'] }

Built-in validators:

| Method | Description | |---|---| | string(value, field) | Non-empty string | | date(value, field) | Valid date (returns Date) | | integer(value, field, { min }) | Integer ≥ min | | number(value, field, { min, max }) | Finite number in range | | enumValue(value, values, field) | One of the allowed values | | object(value, field) | Plain object (deep-cloned) | | array(value, field) | Array (deep-cloned) | | stringArray(value, field) | Array of strings | | mapOfNumbers(value, field) | Map or plain object of string→number | | subStructure(value, Class, field) | Instance of Class or plain object (auto-constructed) | | validateRequired(data, fields) | Throws if any field is null/undefined | | serialize(data) | Converts Map, Date, nested toJSON to plain object |

deepFreeze

import { deepFreeze } from '@opencharts/core';

const catalog = deepFreeze({
  name: 'Patient',
  parameters: { identifiers: { type: 'array' } },
});

// All nested objects are frozen — mutations throw in strict mode
catalog.parameters.identifiers.type = 'string'; // throws TypeError

OUTCOMES

import { OUTCOMES } from '@opencharts/core';

console.log(OUTCOMES);
// ['success', 'empty', 'not_ready', 'throttled', 'unauthorized', ...]

function handleResult(outcome) {
  if (!OUTCOMES.includes(outcome)) {
    throw new Error(`Unknown outcome: ${outcome}`);
  }
  // ...
}

Workflow vocabulary

import { DEPENDENCY_RELATIONS, DEPENDENCY_REQUIRES } from '@opencharts/core';

// DEPENDENCY_RELATIONS: ['case', 'same_resource', 'referenced_resource', 'parent_output']
// DEPENDENCY_REQUIRES:  ['succeeded', 'settled', 'output_accepted', 'succeeded_or_skipped']

API Reference

Entity (class)

Base class for all domain entities. See src/Entity.js for full documentation.

deepFreeze(obj) → obj

Recursively freezes obj in place. Primitives and null are returned unchanged. Already-frozen objects are short-circuited. Returns the same reference.

OUTCOMES (string[])

Canonical outcome values: 'success', 'empty', 'not_ready', 'throttled', 'unauthorized', 'forbidden', 'not_found', 'invalid', 'ambiguous', 'transient_error', 'permanent_error', 'duplicate_work', 'cancelled', 'unknown'.

DEPENDENCY_RELATIONS (string[])

'case' | 'same_resource' | 'referenced_resource' | 'parent_output'

DEPENDENCY_REQUIRES (string[])

'succeeded' | 'settled' | 'output_accepted' | 'succeeded_or_skipped'

License

MIT