ezmedicationinput 0.1.1 → 0.1.3

package/README.md

@@ -49,6 +49,39 @@ Example output:
 }
 ```
 
+### Sig (directions) suggestions
+
+Use `suggestSig` to drive autocomplete experiences while the clinician is
+typing shorthand medication directions (sig = directions). It returns an array
+of canonical direction strings and accepts the same `ParseOptions` context plus
+a `limit` and custom PRN reasons.
+
+```ts
+import { suggestSig } from "ezmedicationinput";
+
+const suggestions = suggestSig("1 drop to od q2h", {
+  limit: 5,
+  context: { dosageForm: "ophthalmic solution" },
+});
+
+// → ["1 drop oph q2h", "1 drop oph q2h prn pain", ...]
+```
+
+Highlights:
+
+- Recognizes plural units and their singular counterparts (`tab`/`tabs`,
+  `puff`/`puffs`, `mL`/`millilitres`, etc.) and normalizes spelled-out metric,
+  SI-prefixed masses/volumes (`micrograms`, `microliters`, `nanograms`,
+  `liters`, `kilograms`, etc.) alongside household measures like `teaspoon`
+  and `tablespoons` (set `allowHouseholdVolumeUnits: false` to omit them).
+- Keeps matching even when intermediary words such as `to`, `in`, or ocular
+  site shorthand (`od`, `os`, `ou`) appear in the prefix.
+- Emits dynamic interval suggestions, including arbitrary `q<number>h` cadences
+  and common range patterns like `q4-6h`.
+- Supports multiple timing tokens in sequence (e.g. `1 tab po morn hs`).
+- Surfaces PRN reasons from built-ins or custom `prnReasons` entries while
+  preserving numeric doses pulled from the typed prefix.
+
 ## Dictionaries
 
 The library exposes default dictionaries in `maps.ts` for routes, units, frequencies (Timing abbreviations + repeat defaults), and event timing tokens. You can extend or override them via the `ParseOptions` argument.
@@ -63,8 +96,12 @@ Key EventTiming mappings include:
 | `pc breakfast`  | `PCM`
 | `pc lunch`      | `PCD`
 | `pc dinner`     | `PCV`
+| `breakfast`, `bfast`, `brkfst`, `brk` | `CM`
+| `lunch`, `lunchtime` | `CD`
+| `dinner`, `dinnertime`, `supper`, `suppertime` | `CV`
 | `am`, `morning` | `MORN`
-| `noon`          | `NOON`
+| `noon`, `midday`, `mid-day` | `NOON`
+| `afternoon`, `aft` | `AFT`
 | `pm`, `evening` | `EVE`
 | `night`         | `NIGHT`
 | `hs`, `bedtime` | `HS`
@@ -82,11 +119,14 @@ Routes always include SNOMED CT codings. Every code from the SNOMED Route of Adm
   `null` to explicitly disable context-based inference.
 - `smartMealExpansion`: when `true`, generic AC/PC/C tokens expand into specific EventTiming combinations (e.g. `1x2 po ac` → `ACM` + `ACV`).
 - `twoPerDayPair`: controls whether 2× AC/PC/C doses expand to breakfast+dinner (default) or breakfast+lunch.
+- `eventClock`: optional map of `EventTiming` codes to HH:mm strings that drives chronological ordering of parsed `when` values.
+- `allowHouseholdVolumeUnits`: defaults to `true`; set to `false` to ignore
+  teaspoon/tablespoon units during parsing and suggestions.
 - Custom `routeMap`, `unitMap`, `freqMap`, and `whenMap` let you augment the built-in dictionaries without mutating them.
 
 ### Next due dose generation
 
-`nextDueDoses` produces upcoming administration timestamps from an existing FHIR `Dosage`. Supply the order start, the reference window, and a clinic configuration that defines anchor times.
+`nextDueDoses` produces upcoming administration timestamps from an existing FHIR `Dosage`. Supply the evaluation window (`from`), optionally the order start (`orderedAt`), and clinic clock details such as a time zone and event timing anchors.
 
 ```ts
 import { EventTiming, nextDueDoses, parseSig } from "ezmedicationinput";
@@ -97,24 +137,22 @@ const schedule = nextDueDoses(fhir, {
   orderedAt: "2024-01-01T08:15:00Z",
   from: "2024-01-01T09:00:00Z",
   limit: 5,
-  config: {
-    timeZone: "Asia/Bangkok",
-    eventClock: {
-      [EventTiming.Morning]: "08:00",
-      [EventTiming.Noon]: "12:00",
-      [EventTiming.Evening]: "18:00",
-      [EventTiming["Before Sleep"]]: "22:00",
-      [EventTiming.Breakfast]: "08:00",
-      [EventTiming.Lunch]: "12:30",
-      [EventTiming.Dinner]: "18:30"
-    },
-    mealOffsets: {
-      [EventTiming["Before Meal"]]: -30,
-      [EventTiming["After Meal"]]: 30
-    },
-    frequencyDefaults: {
-      byCode: { BID: ["08:00", "20:00"] }
-    }
+  timeZone: "Asia/Bangkok",
+  eventClock: {
+    [EventTiming.Morning]: "08:00",
+    [EventTiming.Noon]: "12:00",
+    [EventTiming.Evening]: "18:00",
+    [EventTiming["Before Sleep"]]: "22:00",
+    [EventTiming.Breakfast]: "08:00",
+    [EventTiming.Lunch]: "12:30",
+    [EventTiming.Dinner]: "18:30"
+  },
+  mealOffsets: {
+    [EventTiming["Before Meal"]]: -30,
+    [EventTiming["After Meal"]]: 30
+  },
+  frequencyDefaults: {
+    byCode: { BID: ["08:00", "20:00"] }
   }
 });
 
@@ -128,6 +166,8 @@ Key rules:
 - Pure frequency schedules (`BID`, `TID`, etc.) fall back to clinic-defined institution times.
 - All timestamps are emitted as ISO strings that include the clinic time-zone offset.
 
+`from` is required and marks the evaluation window. `orderedAt` is optional—when supplied it acts as the baseline for interval calculations; otherwise the `from` timestamp is reused. The options bag also accepts `timeZone`, `eventClock`, `mealOffsets`, and `frequencyDefaults` at the top level (mirroring the legacy `config` object). `limit` defaults to 10 when omitted.
+
 ### Ocular & intravitreal shortcuts
 
 The parser recognizes ophthalmic shorthands such as `OD`, `OS`, `OU`, `LE`, `RE`, and `BE`, as well as intravitreal-specific tokens including `IVT`, `IVTOD`, `IVTOS`, `IVTLE`, `IVTBE`, `VOD`, and `VOS`. Intravitreal sigs require an eye side; the parser surfaces a warning if one is missing so downstream workflows can prompt the clinician for clarification.

package/dist/context.js

@@ -1,12 +1,17 @@
-import { DEFAULT_UNIT_BY_NORMALIZED_FORM, KNOWN_DOSAGE_FORMS_TO_DOSE } from "./maps";
-export function normalizeDosageForm(form) {
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeDosageForm = normalizeDosageForm;
+exports.inferUnitFromContext = inferUnitFromContext;
+const maps_1 = require("./maps");
+function normalizeDosageForm(form) {
+    var _a;
     if (!form) {
         return undefined;
     }
     const key = form.trim().toLowerCase();
-    return KNOWN_DOSAGE_FORMS_TO_DOSE[key] ?? key;
+    return (_a = maps_1.KNOWN_DOSAGE_FORMS_TO_DOSE[key]) !== null && _a !== void 0 ? _a : key;
 }
-export function inferUnitFromContext(ctx) {
+function inferUnitFromContext(ctx) {
     if (!ctx) {
         return undefined;
     }
@@ -16,7 +21,7 @@ export function inferUnitFromContext(ctx) {
     if (ctx.dosageForm) {
         const normalized = normalizeDosageForm(ctx.dosageForm);
         if (normalized) {
-            const unit = DEFAULT_UNIT_BY_NORMALIZED_FORM[normalized];
+            const unit = maps_1.DEFAULT_UNIT_BY_NORMALIZED_FORM[normalized];
             if (unit) {
                 return unit;
             }

package/dist/fhir.d.ts

@@ -1,4 +1,4 @@
-import { ParsedSigInternal } from "./parser";
+import { ParsedSigInternal } from "./internal-types";
 import { FhirDosage } from "./types";
 export declare function toFhir(internal: ParsedSigInternal): FhirDosage;
 export declare function internalFromFhir(dosage: FhirDosage): ParsedSigInternal;

package/dist/fhir.js

@@ -1,8 +1,15 @@
-import { formatInternal } from "./format";
-import { ROUTE_BY_SNOMED, ROUTE_SNOMED, ROUTE_TEXT } from "./maps";
-import { EventTiming } from "./types";
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toFhir = toFhir;
+exports.internalFromFhir = internalFromFhir;
+const format_1 = require("./format");
+const maps_1 = require("./maps");
+const types_1 = require("./types");
+const object_1 = require("./utils/object");
+const array_1 = require("./utils/array");
 const SNOMED_SYSTEM = "http://snomed.info/sct";
-export function toFhir(internal) {
+function toFhir(internal) {
+    var _a, _b;
     const dosage = {};
     const repeat = {};
     let hasRepeat = false;
@@ -38,7 +45,7 @@ export function toFhir(internal) {
         dosage.timing = {};
     }
     if (internal.timingCode) {
-        dosage.timing = dosage.timing ?? {};
+        dosage.timing = (_a = dosage.timing) !== null && _a !== void 0 ? _a : {};
         dosage.timing.code = {
             coding: [{ code: internal.timingCode }],
             text: internal.timingCode
@@ -70,9 +77,8 @@ export function toFhir(internal) {
     }
     // Emit SNOMED-coded routes whenever we have parsed or inferred route data.
     if (internal.routeCode || internal.routeText) {
-        const coding = internal.routeCode ? ROUTE_SNOMED[internal.routeCode] : undefined;
-        const text = internal.routeText ??
-            (internal.routeCode ? ROUTE_TEXT[internal.routeCode] : undefined);
+        const coding = internal.routeCode ? maps_1.ROUTE_SNOMED[internal.routeCode] : undefined;
+        const text = (_b = internal.routeText) !== null && _b !== void 0 ? _b : (internal.routeCode ? maps_1.ROUTE_TEXT[internal.routeCode] : undefined);
         if (coding) {
             // Provide both text and coding so human-readable and coded systems align.
             dosage.route = {
@@ -99,53 +105,55 @@ export function toFhir(internal) {
             dosage.asNeededFor = [{ text: internal.asNeededReason }];
         }
     }
-    const longText = formatInternal(internal, "long");
+    const longText = (0, format_1.formatInternal)(internal, "long");
     if (longText) {
         dosage.text = longText;
     }
     return dosage;
 }
-export function internalFromFhir(dosage) {
+function internalFromFhir(dosage) {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s, _t, _u, _v, _w, _x, _y, _z, _0, _1, _2, _3;
     const internal = {
-        input: dosage.text ?? "",
+        input: (_a = dosage.text) !== null && _a !== void 0 ? _a : "",
         tokens: [],
         consumed: new Set(),
-        dayOfWeek: dosage.timing?.repeat?.dayOfWeek
+        dayOfWeek: ((_c = (_b = dosage.timing) === null || _b === void 0 ? void 0 : _b.repeat) === null || _c === void 0 ? void 0 : _c.dayOfWeek)
             ? [...dosage.timing.repeat.dayOfWeek]
             : [],
-        when: dosage.timing?.repeat?.when
-            ? dosage.timing.repeat.when.filter((value) => Object.values(EventTiming).includes(value))
+        when: ((_e = (_d = dosage.timing) === null || _d === void 0 ? void 0 : _d.repeat) === null || _e === void 0 ? void 0 : _e.when)
+            ? dosage.timing.repeat.when.filter((value) => (0, array_1.arrayIncludes)((0, object_1.objectValues)(types_1.EventTiming), value))
             : [],
         warnings: [],
-        timingCode: dosage.timing?.code?.coding?.[0]?.code,
-        frequency: dosage.timing?.repeat?.frequency,
-        frequencyMax: dosage.timing?.repeat?.frequencyMax,
-        period: dosage.timing?.repeat?.period,
-        periodMax: dosage.timing?.repeat?.periodMax,
-        periodUnit: dosage.timing?.repeat?.periodUnit,
-        routeText: dosage.route?.text,
-        siteText: dosage.site?.text,
+        timingCode: (_j = (_h = (_g = (_f = dosage.timing) === null || _f === void 0 ? void 0 : _f.code) === null || _g === void 0 ? void 0 : _g.coding) === null || _h === void 0 ? void 0 : _h[0]) === null || _j === void 0 ? void 0 : _j.code,
+        frequency: (_l = (_k = dosage.timing) === null || _k === void 0 ? void 0 : _k.repeat) === null || _l === void 0 ? void 0 : _l.frequency,
+        frequencyMax: (_o = (_m = dosage.timing) === null || _m === void 0 ? void 0 : _m.repeat) === null || _o === void 0 ? void 0 : _o.frequencyMax,
+        period: (_q = (_p = dosage.timing) === null || _p === void 0 ? void 0 : _p.repeat) === null || _q === void 0 ? void 0 : _q.period,
+        periodMax: (_s = (_r = dosage.timing) === null || _r === void 0 ? void 0 : _r.repeat) === null || _s === void 0 ? void 0 : _s.periodMax,
+        periodUnit: (_u = (_t = dosage.timing) === null || _t === void 0 ? void 0 : _t.repeat) === null || _u === void 0 ? void 0 : _u.periodUnit,
+        routeText: (_v = dosage.route) === null || _v === void 0 ? void 0 : _v.text,
+        siteText: (_w = dosage.site) === null || _w === void 0 ? void 0 : _w.text,
         asNeeded: dosage.asNeededBoolean,
-        asNeededReason: dosage.asNeededFor?.[0]?.text
+        asNeededReason: (_y = (_x = dosage.asNeededFor) === null || _x === void 0 ? void 0 : _x[0]) === null || _y === void 0 ? void 0 : _y.text,
+        siteTokenIndices: new Set()
     };
-    const routeCoding = dosage.route?.coding?.find((code) => code.system === SNOMED_SYSTEM);
-    if (routeCoding?.code) {
+    const routeCoding = (_0 = (_z = dosage.route) === null || _z === void 0 ? void 0 : _z.coding) === null || _0 === void 0 ? void 0 : _0.find((code) => code.system === SNOMED_SYSTEM);
+    if (routeCoding === null || routeCoding === void 0 ? void 0 : routeCoding.code) {
         // Translate SNOMED codings back into the simplified enum for round-trip fidelity.
-        const mapped = ROUTE_BY_SNOMED[routeCoding.code];
+        const mapped = maps_1.ROUTE_BY_SNOMED[routeCoding.code];
         if (mapped) {
             internal.routeCode = mapped;
-            internal.routeText = ROUTE_TEXT[mapped];
+            internal.routeText = maps_1.ROUTE_TEXT[mapped];
         }
     }
-    const doseAndRate = dosage.doseAndRate?.[0];
-    if (doseAndRate?.doseRange) {
+    const doseAndRate = (_1 = dosage.doseAndRate) === null || _1 === void 0 ? void 0 : _1[0];
+    if (doseAndRate === null || doseAndRate === void 0 ? void 0 : doseAndRate.doseRange) {
         const { low, high } = doseAndRate.doseRange;
-        if (low?.value !== undefined && high?.value !== undefined) {
+        if ((low === null || low === void 0 ? void 0 : low.value) !== undefined && (high === null || high === void 0 ? void 0 : high.value) !== undefined) {
             internal.doseRange = { low: low.value, high: high.value };
         }
-        internal.unit = low?.unit ?? high?.unit ?? internal.unit;
+        internal.unit = (_3 = (_2 = low === null || low === void 0 ? void 0 : low.unit) !== null && _2 !== void 0 ? _2 : high === null || high === void 0 ? void 0 : high.unit) !== null && _3 !== void 0 ? _3 : internal.unit;
     }
-    else if (doseAndRate?.doseQuantity) {
+    else if (doseAndRate === null || doseAndRate === void 0 ? void 0 : doseAndRate.doseQuantity) {
         const dose = doseAndRate.doseQuantity;
         if (dose.value !== undefined) {
             internal.dose = dose.value;

package/dist/format.d.ts

@@ -1,2 +1,3 @@
-import { ParsedSigInternal } from "./parser";
-export declare function formatInternal(internal: ParsedSigInternal, style: "short" | "long"): string;
+import { ParsedSigInternal } from "./internal-types";
+import type { SigLocalization } from "./i18n";
+export declare function formatInternal(internal: ParsedSigInternal, style: "short" | "long", localization?: SigLocalization): string;