ultan

v2.2.2

Published

a month ago

High-performance utility suite for modern JavaScript. Optimized for AI orchestration and RAG pipelines, HealthTech (FHIR/HL7) interoperability, and resilient cloud-native systems.

Why use Ultan?

Ultan is a utility library that bridges traditional JavaScript development with modern AI, healthcare (FHIR/HL7), and cloud-native architectures. Built for Fortune 500 environments, it provides enterprise-grade functions for string manipulation, array operations, object handling, healthcare data processing, AI prompt management, PHI masking, reactive state management, functional programming patterns, number utilities, and a full date/time toolkit.

Whether you're building HIPAA-compliant healthcare applications, AI-powered workflows, or mission-critical enterprise systems, Ultan delivers production-ready utilities that eliminate boilerplate and accelerate development cycles.

The latest release adds a RAG and LLM Ops toolkit (text chunking, embedding similarity, retry with backoff), deeper FHIR/HL7 coverage (coding extraction, HIPAA Safe Harbor de-identification, HL7 v2 segment parsing), and cloud-native resilience primitives (circuit breaker, bounded-concurrency async pooling) so teams shipping AI features alongside healthcare or enterprise systems don't have to reach for five different dependencies.

This release adds four more zero-dependency modules: an MCP stdio server for exposing Ultan (or anything else) as tools to Claude Code, Cursor, and other MCP hosts; a browser-native AI router that runs prompts on-device via Chrome's Prompt API before falling back to the cloud; a USCDI v3 structural validator and demographics masker for the HTI-1 baseline that took effect January 1, 2026; and an edge economic resilience layer (token bucket limiting, a usage-driven hysteresis circuit breaker) for defending serverless deployments against runaway cost. See each section for scope notes, the healthcare helpers in particular are structural aids, not a substitute for a compliance review.

Installation

npm install ultan

Quick Start

const {
  stringFormat,
  isValidFhir,
  getFhirName,
  getAcuityScore,
  fillPrompt,
  parseAiJson,
  maskPHI,
  debounce,
  generateUUID
} = require('ultan');

const patient = {
  resourceType: 'Patient',
  id: '12345',
  name: [{ use: 'official', given: ['John'], family: 'Doe' }]
};

console.log(isValidFhir(patient));
console.log(getFhirName(patient));

Healthcare (FHIR/HL7)

`isValidFhir(resource)`

Validates if an object is a valid FHIR resource by checking for resourceType and id properties.

isValidFhir({ resourceType: 'Patient', id: '123' }); // true
isValidFhir({ name: 'John' });                        // false

`getFhirName(patient)`

Extracts the official name from a FHIR Patient resource, falling back to the first name available.

const name = getFhirName(patientResource); // 'John Q. Doe'
getFhirName({});                           // 'Unknown'

`getAcuityScore({ hr, rr, temp, sbp })`

Calculates clinical acuity score based on vital signs (heart rate, respiratory rate, temperature, systolic blood pressure).

const score = getAcuityScore({ hr: 120, rr: 26, temp: 98.6, sbp: 85 });

`maskPHI(string)`

Masks Protected Health Information including SSN, phone numbers, and email addresses.

const masked = maskPHI('Contact: [email protected] or 555-123-4567');
// 'Contact: [EMAIL_MASKED] or [PHONE_MASKED]'

`isZombie(lastHeartbeat, limit = 300000)`

Detects stagnant sessions or zombie connections based on heartbeat timestamp.

const stale = isZombie('2024-01-01T10:00:00Z', 300000); // true
isZombie(new Date());                                    // false

AI Integration

`fillPrompt(template, variables)`

Replaces {{variable}} placeholders in prompt templates with actual values.

const prompt = fillPrompt('Analyze {{dataType}} for patient {{id}}', {
  dataType: 'vitals',
  id: '12345'
});
// 'Analyze vitals for patient 12345'

`parseAiJson(string)`

Parses JSON from AI responses, handling markdown code fences and malformed output.

const data = parseAiJson('```json\n{"key": "value"}\n```'); // { key: 'value' }
parseAiJson('invalid');                                      // null

`createSignal(initialValue)`

Creates a reactive signal with pub/sub pattern for state management.

const counter = createSignal(0);
counter.subscribe(val => console.log('New value:', val));
counter.set(5);
const current = counter.get(); // 5

String Manipulation

`stringFormat(format, ...args)`

Replaces {0}, {1}, etc. placeholders with arguments.

stringFormat('Hello, {0}! Welcome to {1}.', 'Alice', 'Ultan');
// 'Hello, Alice! Welcome to Ultan.'

`toTitleCase(string)`

Converts string to title case.

toTitleCase('hello world'); // 'Hello World'

`sanitizeString(string)`

Escapes HTML special characters.

sanitizeString('<script>alert("xss")</script>');
// '&lt;script&gt;alert(&quot;xss&quot;)&lt;/script&gt;'

`fromBase64(base64)` / `toBase64(string)`

Base64 encoding and decoding with UTF-8 support.

const encoded = toBase64('Hello World');
const decoded = fromBase64(encoded); // 'Hello World'

`countOccurrences(string, substring)`

Counts substring occurrences.

countOccurrences('hello world hello', 'hello'); // 2

String Expansion

`camelCase(string)`

Converts a string (space-separated, kebab, snake, or PascalCase) to camelCase.

camelCase('the quick brown fox'); // 'theQuickBrownFox'
camelCase('the-quick-brown-fox'); // 'theQuickBrownFox'
camelCase('the_quick_brown_fox'); // 'theQuickBrownFox'

`kebabCase(string)`

Converts a string to kebab-case.

kebabCase('the quick brown fox'); // 'the-quick-brown-fox'
kebabCase('theQuickBrownFox');    // 'the-quick-brown-fox'

`snakeCase(string)`

Converts a string to snake_case.

snakeCase('the quick brown fox'); // 'the_quick_brown_fox'
snakeCase('theQuickBrownFox');    // 'the_quick_brown_fox'

`pascalCase(string)`

Converts a string to PascalCase.

pascalCase('the quick brown fox'); // 'TheQuickBrownFox'
pascalCase('the-quick-brown-fox'); // 'TheQuickBrownFox'

`truncate(string, length, suffix = '...')`

Truncates a string to a maximum length, appending a suffix if truncated. Suffix defaults to '...'.

truncate('hello world', 8);       // 'hello...'
truncate('hello world', 8, '!');  // 'hello w!'
truncate('hi', 10);               // 'hi'

`capitalize(string)`

Uppercases the first character of a string, leaving the rest unchanged.

capitalize('hello world'); // 'Hello world'
capitalize('HELLO');       // 'HELLO'

Object Utilities

`isEmpty(value)`

Checks if object, array, or string is empty. Returns true for null and undefined.

isEmpty({});        // true
isEmpty([1]);       // false
isEmpty('');        // true
isEmpty(null);      // true

`deepClone(object)`

Creates a deep copy using structuredClone with a JSON fallback.

const clone = deepClone({ nested: { data: [1, 2, 3] } });

`setNestedProperty(object, path, value)`

Sets a nested property using dot notation, creating intermediate objects as needed.

const obj = {};
setNestedProperty(obj, 'user.profile.name', 'John');
// obj === { user: { profile: { name: 'John' } } }

`getNestedProperty(object, path)`

Retrieves a nested property using dot notation. Returns null for missing paths.

getNestedProperty(obj, 'user.profile.name'); // 'John'

`objectToArray(object)` / `arrayToObject(array)`

Converts between objects and key-value pair arrays.

objectToArray({ a: 1, b: 2 });        // [['a', 1], ['b', 2]]
arrayToObject([['a', 1], ['b', 2]]); // { a: 1, b: 2 }

Object Expansion

`pick(object, keys)`

Returns a new object containing only the specified keys.

pick({ a: 1, b: 2, c: 3 }, ['a', 'c']); // { a: 1, c: 3 }

`omit(object, keys)`

Returns a new object with the specified keys excluded.

omit({ a: 1, b: 2, c: 3 }, ['b']); // { a: 1, c: 3 }

`flipObject(object)`

Swaps an object's keys and values.

flipObject({ a: 'x', b: 'y' }); // { x: 'a', y: 'b' }

Array Utilities

`mergeArrays(array1, array2)`

Merges two arrays, removing duplicates.

mergeArrays([1, 2, 3], [3, 4, 5]); // [1, 2, 3, 4, 5]

`sumArray(array)` / `averageArray(array)`

Calculates the sum or average of a numeric array.

sumArray([1, 2, 3, 4]);   // 10
averageArray([10, 20, 30]); // 20

`arrayDifference(array1, array2)`

Returns elements present in array1 but not in array2.

arrayDifference([1, 2, 3], [2, 3, 4]); // [1]

`removeFalsyValues(array)`

Filters out all falsy values (false, 0, '', null, undefined, NaN).

removeFalsyValues([0, 1, false, 2, '', 3, null, undefined]); // [1, 2, 3]

`groupBy(array, key)`

Groups an array of objects by a shared property.

groupBy([{ type: 'A', val: 1 }, { type: 'B', val: 2 }, { type: 'A', val: 3 }], 'type');
// { A: [{ type: 'A', val: 1 }, { type: 'A', val: 3 }], B: [{ type: 'B', val: 2 }] }

Array Expansion

`flatten(array, depth = Infinity)`

Flattens a nested array to a specified depth. Defaults to fully flat.

flatten([[1, [2, 3]], [4]]);       // [1, 2, 3, 4]
flatten([[1, [2, [3]]]], 1);       // [1, [2, [3]]]

`partition(array, predicate)`

Splits an array into two groups based on a predicate function. Returns [passing, failing].

const [evens, odds] = partition([1, 2, 3, 4, 5], n => n % 2 === 0);
// evens: [2, 4], odds: [1, 3, 5]

`range(start, end, step = 1)`

Generates an array of numbers. When called with one argument, starts from 0.

range(5);          // [0, 1, 2, 3, 4]
range(1, 5);       // [1, 2, 3, 4]
range(0, 10, 3);   // [0, 3, 6, 9]

`chunk(array, size)`

Splits an array into chunks of the given size. The final chunk may be smaller.

chunk([1, 2, 3, 4, 5], 2); // [[1, 2], [3, 4], [5]]
chunk([1, 2, 3], 3);       // [[1, 2, 3]]

`intersect(array1, array2)`

Returns elements present in both arrays.

intersect([1, 2, 3], [2, 3, 4]); // [2, 3]

`unique(array)`

Removes duplicate values from an array.

unique([1, 2, 2, 3, 3, 3]); // [1, 2, 3]

`orderBy(array, key, order = 'asc')`

Sorts an array of objects by a key (string property name or accessor function). Supports 'asc' and 'desc' order.

const data = [{ n: 3 }, { n: 1 }, { n: 2 }];
orderBy(data, 'n');           // [{ n: 1 }, { n: 2 }, { n: 3 }]
orderBy(data, 'n', 'desc');   // [{ n: 3 }, { n: 2 }, { n: 1 }]
orderBy(data, x => x.n);     // function accessor also supported

Function Utilities

`debounce(function, delay = 300)`

Delays function execution until after delay milliseconds have elapsed since the last invocation.

const debouncedSearch = debounce(searchFunction, 500);

`throttle(function, limit)`

Ensures a function executes at most once per limit milliseconds.

const throttledScroll = throttle(handleScroll, 100);

Function Expansion

`once(fn)`

Wraps a function so it executes only on the first call. Subsequent calls return the cached result.

const init = once(() => expensiveSetup());
init(); // runs expensiveSetup
init(); // returns cached result, does not re-run

`memoize(fn, keyFn?)`

Caches function results by argument signature. An optional keyFn can provide a custom cache key.

const expensiveFn = memoize(n => computeHeavy(n));
expensiveFn(5); // computed
expensiveFn(5); // returned from cache

// Custom key function
const memoized = memoize((a, b) => a + b, (a, b) => `${a}-${b}`);

`pipe(...fns)`

Composes functions left to right, passing the output of each as input to the next.

const transform = pipe(
  x => x + 1,
  x => x * 2,
  x => x - 3
);
transform(5); // 9

`compose(...fns)`

Composes functions right to left (standard mathematical composition).

const transform = compose(
  x => x - 3,
  x => x * 2,
  x => x + 1
);
transform(5); // 9

Number Utilities

`getRandomInRange(min, max)`

Returns a random float in the given range (inclusive of min, exclusive of max).

getRandomInRange(1, 10); // e.g. 7.342...

`round(number, decimals = 2)`

Rounds a number to the specified number of decimal places.

round(3.14159, 2); // 3.14
round(1.005, 2);   // 1.01

`generateUUID()`

Generates a RFC 4122-compliant UUID v4.

const id = generateUUID(); // 'f47ac10b-58cc-4372-a567-0e02b2c3d479'

Number Expansion

`clamp(min, val, max)`

Constrains a value within an inclusive range.

clamp(1, 5, 10);  // 5  (within range)
clamp(1, 0, 10);  // 1  (below min, returns min)
clamp(1, 15, 10); // 10 (above max, returns max)

`isPrime(number)`

Returns true if the number is a prime number.

isPrime(2);  // true
isPrime(17); // true
isPrime(1);  // false
isPrime(10); // false

DateTime Utilities

`addTime(date, amount, unit)`

Returns a new date with the specified amount of time added. Supports 'millisecond', 'second', 'minute', 'hour', 'day', 'week', 'month', and 'year'.

addTime(new Date(2026, 0, 1), 5, 'day');   // Jan 6, 2026
addTime(new Date(2026, 0, 15), 2, 'month'); // Mar 15, 2026
addTime(new Date(2026, 0, 1), 1, 'year');  // Jan 1, 2027

`subtractTime(date, amount, unit)`

Returns a new date with the specified amount of time subtracted. Accepts the same units as addTime.

subtractTime(new Date(2026, 0, 10), 5, 'day'); // Jan 5, 2026

`startOf(date, unit)`

Returns a new date set to the start of the given unit. Supports 'day', 'month', 'year', 'week', and 'hour'.

startOf(new Date(2026, 3, 15, 14, 30), 'day');   // Apr 15, 2026 00:00:00.000
startOf(new Date(2026, 3, 15), 'month');           // Apr 1, 2026 00:00:00.000

`endOf(date, unit)`

Returns a new date set to the end of the given unit. Supports 'day', 'month', 'year', 'week', and 'hour'.

endOf(new Date(2026, 3, 15), 'day');   // Apr 15, 2026 23:59:59.999
endOf(new Date(2026, 3, 15), 'month'); // Apr 30, 2026 23:59:59.999

`isBefore(date1, date2)`

Returns true if date1 is strictly before date2.

isBefore(new Date(2026, 0, 1), new Date(2026, 6, 1)); // true

`isAfter(date1, date2)`

Returns true if date1 is strictly after date2.

isAfter(new Date(2026, 6, 1), new Date(2026, 0, 1)); // true

`isSameDay(date1, date2)`

Returns true if both dates fall on the same calendar day regardless of time.

isSameDay(new Date(2026, 3, 15, 10), new Date(2026, 3, 15, 22)); // true
isSameDay(new Date(2026, 3, 15), new Date(2026, 3, 16));          // false

`diffDates(date1, date2, unit = 'day')`

Returns the difference between two dates in the specified unit. Supports 'day', 'month', and 'year'.

diffDates(new Date(2026, 0, 1), new Date(2026, 0, 11), 'day');   // 10
diffDates(new Date(2026, 0, 1), new Date(2026, 5, 1), 'month');  // 5

`isWeekend(date)`

Returns true if the date falls on a Saturday or Sunday.

isWeekend(new Date(2026, 3, 11)); // true  (Saturday)
isWeekend(new Date(2026, 3, 13)); // false (Monday)

`isLeapYear(year)`

Returns true if the given year is a leap year.

isLeapYear(2024); // true
isLeapYear(2026); // false
isLeapYear(2000); // true
isLeapYear(1900); // false

`daysInMonth(year, month)`

Returns the number of days in a given month. Month is 1-indexed (January = 1).

daysInMonth(2026, 2); // 28
daysInMonth(2024, 2); // 29 (leap year)
daysInMonth(2026, 1); // 31

`formatRelative(date)`

Returns a human-readable relative time string such as '2 hours ago' or '3 days from now'.

formatRelative(new Date(Date.now() - 90000));   // '1 minute ago'
formatRelative(new Date(Date.now() - 7200000)); // '2 hours ago'
formatRelative(new Date(Date.now() + 86400000)); // '1 day from now'

HTTP/Network

`reqFlow(url, options = {})`

Simplified fetch wrapper that throws on non-OK responses and parses the response body as JSON.

const data = await reqFlow('https://api.example.com/data', {
  method: 'POST',
  body: JSON.stringify({ key: 'value' })
});

Miscellaneous

`greet({ name, age })`

Console logs a greeting. Parameters are destructured with defaults.

greet({ name: 'Alice', age: 30 }); // 'Hello, Alice! You are 30 years old.'
greet();                            // 'Hello, User! You are unknown years old.'

`getType(value)`

Returns a lowercase type string, correctly handling null, arrays, and other edge cases.

getType([]);   // 'array'
getType({});   // 'object'
getType(null); // 'null'

`formatDate(date)`

Formats a Date object as MM/DD/YYYY.

formatDate(new Date(2026, 0, 1)); // '01/01/2026'

Regular Expressions

Pre-compiled regex patterns accessible via the regexes object:

regexes.email - Email address validation
regexes.phone - International phone numbers
regexes.url - HTTP/HTTPS URLs

const { regexes } = require('ultan');
regexes.email.test('[email protected]');         // true
regexes.url.test('https://vgs.studio');          // true

Constants

`DaysOfWeek`

Frozen object with full weekday names.

const { DaysOfWeek } = require('ultan');
console.log(DaysOfWeek.MONDAY);    // 'Monday'
console.log(DaysOfWeek.SATURDAY);  // 'Saturday'

`HttpStatus`

Frozen object of common HTTP status codes.

const { HttpStatus } = require('ultan');
if (response.status === HttpStatus.NOT_FOUND) { }
if (response.status === HttpStatus.TOO_MANY_REQUESTS) { }
if (response.status === HttpStatus.SERVICE_UNAVAILABLE) { }

AI and RAG Expansion

`chunkText(text, options)`

Splits long text into overlapping chunks for embedding pipelines, preferring paragraph and sentence boundaries over hard character cuts. Accepts size (max characters per chunk, default 500) and overlap (shared characters between consecutive chunks, default 50). Throws if overlap is not smaller than size.

const chunks = chunkText(patientHistoryText, { size: 500, overlap: 50 });
// ['Patient presents with chest pain...', 'Recommend ECG and troponin panel...', ...]

`cosineSimilarity(vectorA, vectorB)`

Computes the cosine similarity between two equal-length embedding vectors locally, without a vector database. Returns a value from -1 to 1; throws if the vectors differ in length.

cosineSimilarity([0.1, 0.2, 0.9], [0.15, 0.21, 0.85]); // 0.9978...
cosineSimilarity([1, 0], [0, 1]);                       // 0

`retryWithBackoff(fn, options)`

Retries an async function with exponential backoff, for transient 429 or 5xx errors from AI or cloud APIs. Accepts retries (default 3), delay in ms (default 1000), and factor (default 2, the multiplier applied to delay after each attempt).

const response = await retryWithBackoff(() => openAiCall(), { retries: 3, delay: 1000 });

Healthcare Expansion

`extractCoding(resource, systemCode)`

Recursively walks a FHIR resource including nested component entries and Bundles, this returns every code from coding arrays that match the given system URI, such as LOINC or SNOMED-CT.

const loincCodes = extractCoding(observation, 'http://loinc.org');
// ['85354-9', '8480-6']

`deidentifyFhir(resource)`

Returns a deep copy of a FHIR resource with the common HIPAA Safe Harbor identifiers removed or masked: name and telecom are masked, address keeps only state/country, birthDate/deceasedDateTime are reduced to the year, identifier values are hashed, and photo is removed. Recurses into nested elements like contact, and never mutates the original resource.

const cleanResearchData = deidentifyFhir(patientResource);
// { ...patientResource, name: '[NAME_MASKED]', birthDate: '1980', ... }

`parseHl7Segment(hl7String, segmentId)`

Isolates every occurrence of a segment (like PID or OBX) from a raw HL7 v2 pipe-delimited message and splits each into its fields, ready for further mapping to FHIR or another schema. Returns an array of field arrays, since segments such as OBX commonly repeat.

const [pid] = parseHl7Segment(rawHl7String, 'PID');
// ['PID', '1', '', '123456', '', 'DOE^JOHN', '', '19800101', 'M']

Resilience and Async Utilities

`circuitBreaker(asyncFn, options)`

Wraps an async function in a circuit breaker so a struggling downstream service, a slow EHR, a stalled LLM endpoint, fails fast instead of cascading. After failureThreshold consecutive failures (default 5) the circuit opens and rejects immediately without calling asyncFn; after cooldown ms (default 10000) it allows one trial call, closing again on success or reopening on failure.

const secureFetch = circuitBreaker(fetchPatientRecords, { failureThreshold: 5, cooldown: 10000 });

`asyncPool(concurrencyLimit, array, iteratorFn)`

Maps over an array asynchronously while limiting how many calls run at once, so processing thousands of records or embeddings doesn't exhaust memory or hit provider rate limits. Resolves to an array of results in the original input order regardless of completion order.

// Uploads files 5 at a time
await asyncPool(5, largeBatchOfFiles, uploadToS3);

`safeJsonParse(string, fallback = null)`

Parses a JSON string and returns a fallback value instead of throwing when the input is malformed, this is handy for webhook payloads and other untrusted input.

safeJsonParse('{"a":1}');      // { a: 1 }
safeJsonParse('not json', {}); // {}

Object and Data Utilities

`deepMerge(...objects)`

Deeply merges any number of objects. Nested objects are merged recursively and arrays are concatenated rather than replaced, so combining config objects never silently drops data. Returns a new object; none of the inputs are mutated.

deepMerge({ api: { timeout: 1000 } }, { api: { retries: 3 } });
// { api: { timeout: 1000, retries: 3 } }

deepMerge({ tags: ['a', 'b'] }, { tags: ['c'] });
// { tags: ['a', 'b', 'c'] }

`isMatch(object, source)`

Checks whether object contains every key/value pair in source, recursing into nested objects and comparing Date values by timestamp rather than by reference. Useful for writing fast, dependency-free filtering logic.

isMatch({ name: 'John', age: 30 }, { age: 30 }); // true
items.filter(item => isMatch(item, { status: 'active' }));

Agentic Integration (MCP Server)

`createMcpServer(serverMetadata)`

Creates a zero-dependency Model Context Protocol server for the stdio transport that terminal-native AI hosts (Claude Code, Claude Desktop, Cursor) use to launch and talk to local tool servers. Returns a handle exposing registerTool, start, stop, listTools, and log. The server speaks newline-delimited JSON-RPC 2.0 on stdout exclusively, never write anything else there, since it will corrupt the stream for the client parsing it line by line; use the returned log() (or any stderr-based logger) for diagnostics instead.

const server = createMcpServer({ name: 'ultan-tools', version: '1.0.0' });

server.registerTool(
  'chunk-text',
  'Splits long text into overlapping chunks for embeddings',
  { type: 'object', properties: { text: { type: 'string' }, size: { type: 'number' } }, required: ['text'] },
  async ({ text, size }) => ({
    content: [{ type: 'text', text: JSON.stringify(chunkText(text, { size })) }],
  }),
);

server.start(); // listens on the real process.stdin / process.stdout

start({ stdin, stdout }) also accepts injected streams (e.g. Node's stream.PassThrough), which is how this library's own test suite exercises it without spawning a real subprocess.

Browser-Native AI Router

`queryBrowserAiStatus()`

Probes the current environment for Chrome's on-device Prompt API. Targets the current LanguageModel global (self.LanguageModel / window.LanguageModel), with a fallback to the older window.ai.languageModel shape for browsers that haven't migrated off it yet. Resolves to { supported, availability, api, reason }, and reports supported: false rather than throwing in any non-browser environment, including plain Node.js.

const status = await queryBrowserAiStatus();
// { supported: true, availability: 'available', api: 'LanguageModel', reason: null }

`routeAiTask(promptTemplate, templateVariables, fallbackCloudResolver, options)`

Fills a fillPrompt-style template and runs it on-device when a local model is available, otherwise calls fallbackCloudResolver(filledPrompt, templateVariables). Falls through to the cloud resolver automatically if the local model is unsupported, still downloading, or throws. Pass { forceCloud: true } to always use the cloud path, or { systemPrompt, onRoute } to set a system prompt or observe which path was taken.

const { text, source } = await routeAiTask(
  'Summarize this note for a clinician: {{note}}',
  { note: patientNoteText },
  (prompt) => callCloudModel(prompt), // only called if no local model is available
);
// source is 'local' or 'cloud'

This module only does anything in a browser-like global scope, bundle it into client-side code rather than calling it from a backend script, where it will always (safely) fall back to the cloud resolver.

HealthTech Interoperability Expansion

`validateUscdiV3CareTeam(resource)`

Structurally validates a FHIR CareTeam resource against the shape USCDI v3 expects for care team members: a resolvable member reference and at least one coded role (with both system and code), not just a free-text name. Returns { valid, errors } rather than a bare boolean so callers can see exactly what's missing.

validateUscdiV3CareTeam({
  resourceType: 'CareTeam',
  id: 'ct-1',
  status: 'active',
  participant: [{
    member: { reference: 'Practitioner/123' },
    role: [{ coding: [{ system: 'http://nucc.org/provider-taxonomy', code: '207Q00000X' }] }],
  }],
});
// { valid: true, errors: [] }

This is a structural helper, not an ONC certification tool, it can confirm a resource has the shape USCDI v3 needs, not that a system has passed certification testing (which runs through an ONC-Authorized Certification Body).

`maskClinicalDemographics(patientResource)`

Non-mutating demographic masking pass over a FHIR Patient (or similar) resource: masks name components (given/family/text → "[MASKED]") while preserving the HumanName shape, deletes telecom and photo entirely, truncates birthDate/deceasedDateTime to the year, and hashes identifier values with a deterministic base-31 polynomial hash (the same algorithm as Java's String.hashCode()) so repeated identifiers still match each other after masking.

maskClinicalDemographics({
  resourceType: 'Patient',
  name: [{ given: ['John'], family: 'Doe' }],
  birthDate: '1980-05-14',
  identifier: [{ value: 'MRN12345' }],
});
// { resourceType: 'Patient', name: [{ given: ['[MASKED]'], family: '[MASKED]' }], birthDate: '1980', identifier: [{ value: '[ID_...]' }] }

Distinct from deidentifyFhir above: that function collapses name to a single string and masks (rather than deletes) telecom, and already handles address down to state/country, which this function does not touch. Neither function alone, nor both together, covers the full 18-category HIPAA Safe Harbor list (notably missing here: geographic subdivisions, ages over 89, device/vehicle identifiers, biometric identifiers, and URLs/IPs) treat this as a strong first pass, not a substitute for a compliance review.

Edge Economic Resilience

`initTokenBucketLimiter(options)`

An in-memory token bucket rate limiter, keyed per caller (IP, user id, API key). Accepts capacity (burst size, default 60), refillRate (tokens per refillIntervalMs, default 1), refillIntervalMs (default 1000), and maxTrackedKeys (default 10000, bounding memory by evicting the least-recently-touched key once exceeded). Returns { consume, peek, reset, size }.

const limiter = initTokenBucketLimiter({ capacity: 30, refillRate: 30, refillIntervalMs: 60000 }); // 30/minute per key

const { allowed, retryAfterMs } = limiter.consume(req.ip);
if (!allowed) return res.status(429).set('Retry-After', String(Math.ceil(retryAfterMs / 1000))).end();

This guards a single process/instance. In a horizontally scaled deployment, each instance enforces its own limit independently rather than a coordinated fleet-wide ceiling, back it with a shared store (Redis, DynamoDB) if you need the latter.

`initHysteresisBillingBreaker(fetchUsageTelemetry, options)`

A circuit breaker driven by continuous usage telemetry (e.g. "% of monthly budget consumed") rather than failure counts, so a runaway cost curve trips it even when every individual request is succeeding. Trips OPEN at tripThreshold (default 90, meaning 90%) and only returns to CLOSED below recoverThreshold (default 85) the gap between them is the hysteresis band that stops it flapping open and closed. fetchUsageTelemetry should return (or resolve to) a 0–100 number, or { usagePercent }. Returns { check, getState, getLastUsage, isOpen, wrap, start, stop }, and starts optimistically CLOSED until the first check() runs.

const breaker = initHysteresisBillingBreaker(() => fetchMonthlySpendPercent(), {
  tripThreshold: 90,
  recoverThreshold: 85,
  onOpen: () => alertOncall('billing breaker tripped'),
});
breaker.start(); // polls every 15s by default

await breaker.wrap(() => callExpensiveDownstreamApi());

License

MIT

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Why use Ultan?

Table of Contents

Installation

Quick Start

Healthcare (FHIR/HL7)

isValidFhir(resource)

getFhirName(patient)

getAcuityScore({ hr, rr, temp, sbp })

maskPHI(string)

isZombie(lastHeartbeat, limit = 300000)

AI Integration

fillPrompt(template, variables)

parseAiJson(string)

createSignal(initialValue)

String Manipulation

stringFormat(format, ...args)

toTitleCase(string)

sanitizeString(string)

fromBase64(base64) / toBase64(string)

countOccurrences(string, substring)

String Expansion

camelCase(string)

kebabCase(string)

snakeCase(string)

pascalCase(string)

truncate(string, length, suffix = '...')

capitalize(string)