@opencharts/case

Assembles a pure mapper's canonical output into a structured operation case seed.

Overview

@opencharts/case turns the output of @opencharts/mapper's PureResourceMapper.map() into a deterministic case seed — a plain object that identifies the case, its resources, identity-resolution inputs, and business key.

• Source-agnostic: consumes only canonical resource output, never raw source records.
• Pure & deterministic: same input → same output every time. Case id and business key hash are derived via SHA-256 (Node.js built-in node:crypto).
• No persistence coupling: emits a plain object, not a domain aggregate.

Installation

npm install @opencharts/case

Usage

Basic assembly

import { CaseAssembler } from '@opencharts/case';
import { PureResourceMapper, dsl as d } from '@opencharts/mapper';

const mapper = new PureResourceMapper();
const assembler = new CaseAssembler();

const mapped = mapper.map(mappingDefinition, sourceRecord);

const seed = assembler.assemble({
  mapped,
  workflow:       { id: 'chart-chase-v1', version: 1 },
  tenant_id:      'tenant-001',
  integration_id: 'integration-001',
});

console.log(seed);
/*
{
  id:             'OperationCase/ab12cd...',
  tenant_id:      'tenant-001',
  integration_id: 'integration-001',
  workflow:       { id: 'chart-chase-v1', version: 1 },
  business_key:   { category: 'Patient', canonical_hash: { algorithm: 'sha256', value: '...' } },
  resource_parameters: { patient: { identifiers: [...] } },
  resolutions: [{ key: 'patient', resource_type: 'Patient', profile: {...}, identity_parameters: {...}, is_subject: true }],
  state:      'open',
  generation: 1,
  priority:   0,
}
*/

With catalog validation

import { CaseAssembler } from '@opencharts/case';

// resourceValidator from @opencharts/resources
const assembler = new CaseAssembler({ resourceValidator });

const seed = assembler.assemble({ mapped, workflow, tenant_id, integration_id });
// Throws if any mapped resource is not catalog-valid (default onInvalidResource: 'throw')

Skip invalid resources

const assembler = new CaseAssembler({
  resourceValidator,
  onInvalidResource: 'skip',  // drop invalid resources, report them in seed.dropped_resources
});

const seed = assembler.assemble({ ... });
console.log(seed.dropped_resources);
// [{ key: 'encounter', errors: ['Unknown resource type: "UnknownType"'] }]

Optional inputs

const seed = assembler.assemble({
  mapped,
  workflow,
  tenant_id:      'tenant-001',
  integration_id: 'integration-001',
  correlation_id: 'corr-abc123',       // optional: external correlation id
  demand:         demandRef,           // optional: demand reference
  source_records: [{ id: 'rec-1' }],  // optional: provenance
  subject_type:   'Patient',           // which resource type is the subject (default: 'Patient')
  generation:     2,
  priority:       5,
  requireDemand:  true,                // enforce that demand is present
});

canonicalize(value) utility

import { canonicalize } from '@opencharts/case';

const canonical = canonicalize({ b: 2, a: 1 });
// '{"a":1,"b":2}'  — deterministic, key-sorted JSON

CaseAssembler options

| Option | Type | Default | Description | |---|---|---|---| | resourceValidator | object | null | CanonicalResourceValidator — enables catalog validation | | hashPolicyVersion | string | 'case-identity-v1' | Recorded on the business key hash | | onInvalidResource | 'throw'\|'skip' | 'throw' | Policy when catalog validation fails |

assemble(input) inputs

| Field | Required | Description | |---|---|---| | mapped | ✓ | PureResourceMapper.map() output | | workflow | ✓ | { id: string, version?: number } | | tenant_id | ✓ | Tenant identifier | | integration_id | ✓ | Integration identifier | | correlation_id | — | External correlation id | | demand | — | Demand reference (passed through) | | source_records | — | Provenance records (passed through) | | subject_type | — | Resource type treated as the case subject (default: 'Patient') | | subject_ref | — | Pre-resolved subject reference | | category | — | Business category (defaults to business_key.namespace) | | id | — | Override the derived case id | | generation | — | Default: 1 | | priority | — | Default: 0 | | state | — | Default: 'open' | | requireDemand | — | Throws if demand is absent. Default: false |

License

MIT