@opencharts/demand

Domain entities for demand expectations and artifact matching requirements.

Overview

@opencharts/demand provides the domain entities used to express what data is expected (demanded) and the scope in which an artifact may satisfy that demand.

Exported classes

| Class | Description | |---|---| | DemandExpectation | A single explicit business/data requirement | | Hash | Canonical identity hash { algorithm, value, policy_version? } | | EntityRef | Reference to another entity { type, id, version? } | | ArtifactSelector | Canonical artifact matching specification | | Period | Date/time interval { start?, end? } | | DemandScope | Clinical/business scope for demand matching |

All classes extend Entity from @opencharts/core and validate field values immediately on assignment.

Installation

npm install @opencharts/demand

Usage

Hash

import { Hash } from '@opencharts/demand';

const hash = new Hash({ algorithm: 'sha256', value: 'abc123...' });
hash.validate();
console.log(hash.toJSON()); // { algorithm: 'sha256', value: 'abc123...' }

EntityRef

import { EntityRef } from '@opencharts/demand';

const ref = new EntityRef({ type: 'Patient', id: 'p-001', version: 3 });
ref.validate();

ArtifactSelector

import { ArtifactSelector } from '@opencharts/demand';

const selector = new ArtifactSelector({
  system: 'loinc',
  type: 'Observation',
  selector: '718-7',    // code (string or object)
  parameters: { value_set: 'hemoglobin' },
});
selector.validate();

Period

import { Period } from '@opencharts/demand';

const period = new Period({ start: '2024-01-01', end: '2024-12-31' });
period.validate();
// start/end are stored as Date objects; validate() checks start <= end

DemandScope

import { DemandScope, EntityRef, Period } from '@opencharts/demand';

const scope = new DemandScope({
  subject_ref:      { type: 'Patient',     id: 'p-001' },
  appointment_ref:  { type: 'Appointment', id: 'apt-001' },
  service_period:   { start: '2024-01-01', end: '2024-12-31' },
});
scope.validate();

DemandExpectation

import { DemandExpectation } from '@opencharts/demand';

const demand = new DemandExpectation({
  id:        'de-001',
  case_id:   'case-abc',
  workflow_step: 'fetch-labs',
  selector: {
    system: 'loinc',
    type: 'Observation',
    selector: '718-7',
  },
  scope: {
    subject_ref: { type: 'Patient', id: 'p-001' },
    service_period: { start: '2024-01-01', end: '2024-12-31' },
  },
  required: true,
  satisfied: false,
});
demand.validate();
console.log(demand.toJSON());

Field Reference

DemandExpectation

| Field | Type | Required | Description | |---|---|---|---| | id | string | ✓ | Unique demand expectation id | | case_id | string | ✓ | Owning case id | | workflow_step | string | ✓ | The workflow step that requires this artifact | | selector | ArtifactSelector | ✓ | What artifact is required | | scope | DemandScope | — | Clinical/business scope | | required | boolean | — | Whether absence is a failure | | satisfied | boolean | — | Whether the demand has been met |

ArtifactSelector

| Field | Type | Required | Description | |---|---|---|---| | system | string | ✓ | Matching dialect (loinc, fhir-search, identifier, …) | | type | string | ✓ | Target artifact / resource type | | selector | string | object | ✓ | Canonical selector or expression | | parameters | object | — | Versioned, canonicalizable parameters |

DemandScope

| Field | Type | Description | |---|---|---| | subject_ref | EntityRef | Patient/subject scope | | appointment_ref | EntityRef | Appointment scope | | encounter_ref | EntityRef | Encounter scope | | provider_ref | EntityRef | Provider scope | | facility_ref | EntityRef | Facility/location scope | | service_period | Period | Clinical service date range | | authored_period | Period | Artifact-authored date range | | additional | object | Workflow-specific scope fields |

License

MIT