@opencharts/normalizer

Versioned transform registry and built-in normalizer functions for OpenCharts.

Overview

@opencharts/normalizer provides:

• CanonicalNormalizerRegistry — a versioned store of named transform functions. Normalizers are referenced by { name, version } from mapping bindings.
• registerBuiltinNormalizers — registers the built-in transform set (string, date, gender, collection, crosswalk, regex, hashing normalizers).

All normalizers are pure functions: same input always yields the same output. No I/O, no side effects, no global state.

Installation

npm install @opencharts/normalizer

Usage

With the SDK

import { createCanonicalSystem } from '@opencharts/sdk';

// Built-in normalizers are registered automatically
const { normalizers } = createCanonicalSystem();

const trimFn = normalizers.get('trim', 1);
console.log(trimFn('  hello  ')); // 'hello'

Manual setup

import {
  CanonicalNormalizerRegistry,
  registerBuiltinNormalizers,
} from '@opencharts/normalizer';

const normalizers = new CanonicalNormalizerRegistry();
registerBuiltinNormalizers(normalizers);

Register a custom normalizer

normalizers.register('parse_npi', 1, (value) => {
  if (typeof value !== 'string') return null;
  const cleaned = value.replace(/\D/g, '');
  return cleaned.length === 10 ? cleaned : null;
});

Apply a transform chain

// Apply multiple transforms in sequence
const result = normalizers.apply('  718-7  ', [
  { name: 'trim', version: 1 },
  { name: 'uppercase', version: 1 },
]);
console.log(result); // '718-7'

Built-in Normalizers

String transforms

| Name | Version | Description | |---|---|---| | trim | 1 | String.prototype.trim() | | uppercase | 1 | String.prototype.toUpperCase() | | lowercase | 1 | String.prototype.toLowerCase() | | normalize_identifier_system | 1 | Trim + lowercase (for system URIs) | | normalize_status | 1 | Trim + lowercase + replace spaces with - |

Date transforms

| Name | Version | Description | |---|---|---| | to_iso_date | 1 | Converts YYYYMMDD, M/D/YYYY, MM/DD/YYYY, ISO → YYYY-MM-DD | | to_iso_datetime | 1 | Converts any parseable datetime → ISO 8601 with timezone |

Gender transform

| Name | Version | Description | |---|---|---| | to_fhir_administrative_gender | 1 | Maps m/male/f/female/o/other/u/unknown → FHIR gender |

Collection transforms

| Name | Version | Description | |---|---|---| | to_array | 1 | Wraps non-array in [value]; null → [] | | remove_empty | 1 | Filters null and empty strings from an array | | flatten | 1 | Flattens nested arrays; options: { depth } | | split | 1 | Splits a delimited string; options: { delimiter, trim, keepEmpty } | | delimited | 1 | Splits "v1\|s1, v2\|s2" into [{value,system}]; options: { item, pair, fields } | | map_values | 1 | Crosswalk lookup; options: { table, default, passthrough } | | regex_extract | 1 | Extracts capture groups; options: { pattern, flags, format, default } |

Canonical / hashing transforms

| Name | Version | Description | |---|---|---| | sort_canonical | 1 | Recursively sorts object keys for a deterministic representation | | compact_hash | 1 | Stable 32-bit string hash of the canonical JSON |

API Reference

CanonicalNormalizerRegistry

| Method | Description | |---|---| | register(name, version, fn) | Register fn(value, options?) => result; each name+version is unique | | get(name, version) | Returns the function; throws if not registered | | has(name, version) | Returns boolean | | apply(value, chain) | Applies [{ name, version }] transforms in sequence | | list() | Returns all registered "name::version" keys |

License

MIT