ezmedicationinput 0.1.2 → 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,6 +119,9 @@ 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

package/dist/maps.d.ts

@@ -19,6 +19,7 @@ export interface RouteSynonym {
     text: string;
 }
 export declare const DEFAULT_ROUTE_SYNONYMS: Record<string, RouteSynonym>;
+export declare const HOUSEHOLD_VOLUME_UNITS: readonly ["tsp", "tbsp"];
 export declare const DEFAULT_UNIT_SYNONYMS: Record<string, string>;
 export interface FrequencyDescriptor {
     code?: string;

package/dist/maps.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_UNIT_BY_ROUTE = exports.DEFAULT_UNIT_BY_NORMALIZED_FORM = exports.KNOWN_TMT_DOSAGE_FORM_TO_SNOMED_ROUTE = exports.KNOWN_DOSAGE_FORMS_TO_DOSE = exports.WORD_FREQUENCIES = exports.DAY_OF_WEEK_TOKENS = exports.DISCOURAGED_TOKENS = exports.MEAL_KEYWORDS = exports.EVENT_TIMING_TOKENS = exports.TIMING_ABBREVIATIONS = exports.DEFAULT_UNIT_SYNONYMS = exports.DEFAULT_ROUTE_SYNONYMS = exports.ROUTE_BY_SNOMED = exports.ROUTE_TEXT = exports.ROUTE_SNOMED = void 0;
+exports.DEFAULT_UNIT_BY_ROUTE = exports.DEFAULT_UNIT_BY_NORMALIZED_FORM = exports.KNOWN_TMT_DOSAGE_FORM_TO_SNOMED_ROUTE = exports.KNOWN_DOSAGE_FORMS_TO_DOSE = exports.WORD_FREQUENCIES = exports.DAY_OF_WEEK_TOKENS = exports.DISCOURAGED_TOKENS = exports.MEAL_KEYWORDS = exports.EVENT_TIMING_TOKENS = exports.TIMING_ABBREVIATIONS = exports.DEFAULT_UNIT_SYNONYMS = exports.HOUSEHOLD_VOLUME_UNITS = exports.DEFAULT_ROUTE_SYNONYMS = exports.ROUTE_BY_SNOMED = exports.ROUTE_TEXT = exports.ROUTE_SNOMED = void 0;
 const types_1 = require("./types");
 const object_1 = require("./utils/object");
 const ROUTE_TEXT_OVERRIDES = {
@@ -140,7 +140,92 @@ exports.DEFAULT_ROUTE_SYNONYMS = (() => {
     }
     return map;
 })();
-exports.DEFAULT_UNIT_SYNONYMS = {
+const UNIT_PREFIXES = [
+    { canonical: "", abbreviations: [""], names: [{ singular: "", plural: "" }] },
+    {
+        canonical: "m",
+        abbreviations: ["m"],
+        names: [{ singular: "milli", plural: "milli" }],
+    },
+    {
+        canonical: "mc",
+        abbreviations: ["mc", "µ", "μ", "u"],
+        names: [{ singular: "micro", plural: "micro" }],
+    },
+    {
+        canonical: "n",
+        abbreviations: ["n"],
+        names: [{ singular: "nano", plural: "nano" }],
+    },
+    {
+        canonical: "k",
+        abbreviations: ["k"],
+        names: [{ singular: "kilo", plural: "kilo" }],
+    },
+];
+const METRIC_UNIT_BASES = [
+    {
+        canonical: "g",
+        abbreviations: ["g"],
+        names: [
+            { singular: "gram", plural: "grams" },
+            { singular: "gramme", plural: "grammes" },
+        ],
+    },
+    {
+        canonical: "L",
+        abbreviations: ["l"],
+        names: [
+            { singular: "liter", plural: "liters" },
+            { singular: "litre", plural: "litres" },
+        ],
+    },
+];
+function assignUnitSynonym(map, key, canonical) {
+    const normalized = key.trim().toLowerCase();
+    if (!normalized || map[normalized]) {
+        return;
+    }
+    map[normalized] = canonical;
+}
+function addMetricUnitSynonyms(map) {
+    for (const prefix of UNIT_PREFIXES) {
+        for (const base of METRIC_UNIT_BASES) {
+            const canonical = `${prefix.canonical}${base.canonical}`;
+            for (const prefixAbbrev of prefix.abbreviations) {
+                for (const baseAbbrev of base.abbreviations) {
+                    if (!baseAbbrev) {
+                        continue;
+                    }
+                    const token = `${prefixAbbrev}${baseAbbrev}`;
+                    assignUnitSynonym(map, token, canonical);
+                    assignUnitSynonym(map, `${token}s`, canonical);
+                    if (token.endsWith(".")) {
+                        assignUnitSynonym(map, token.replace(/\.+$/, ""), canonical);
+                    }
+                }
+            }
+            for (const prefixName of prefix.names) {
+                for (const baseName of base.names) {
+                    const singular = `${prefixName.singular}${baseName.singular}`;
+                    const plural = `${prefixName.singular}${baseName.plural}`;
+                    const hyphenSingular = prefixName.singular
+                        ? `${prefixName.singular}-${baseName.singular}`
+                        : baseName.singular;
+                    const hyphenPlural = prefixName.singular
+                        ? `${prefixName.singular}-${baseName.plural}`
+                        : baseName.plural;
+                    assignUnitSynonym(map, singular, canonical);
+                    assignUnitSynonym(map, plural, canonical);
+                    assignUnitSynonym(map, hyphenSingular, canonical);
+                    assignUnitSynonym(map, hyphenPlural, canonical);
+                }
+            }
+        }
+    }
+}
+exports.HOUSEHOLD_VOLUME_UNITS = ["tsp", "tbsp"];
+const STATIC_UNIT_SYNONYMS = {
     tab: "tab",
     tabs: "tab",
     tablet: "tab",
@@ -149,13 +234,6 @@ exports.DEFAULT_UNIT_SYNONYMS = {
     caps: "cap",
     capsule: "cap",
     capsules: "cap",
-    ml: "mL",
-    "milliliter": "mL",
-    "milliliters": "mL",
-    mg: "mg",
-    g: "g",
-    mcg: "mcg",
-    ug: "mcg",
     puff: "puff",
     puffs: "puff",
     spray: "spray",
@@ -166,8 +244,25 @@ exports.DEFAULT_UNIT_SYNONYMS = {
     patches: "patch",
     supp: "suppository",
     suppository: "suppository",
-    suppositories: "suppository"
+    suppositories: "suppository",
+    tsp: "tsp",
+    "tsp.": "tsp",
+    tsps: "tsp",
+    "tsps.": "tsp",
+    teaspoon: "tsp",
+    teaspoons: "tsp",
+    tbsp: "tbsp",
+    "tbsp.": "tbsp",
+    tbs: "tbsp",
+    "tbs.": "tbsp",
+    tablespoon: "tbsp",
+    tablespoons: "tbsp",
 };
+exports.DEFAULT_UNIT_SYNONYMS = (() => {
+    const map = Object.assign({}, STATIC_UNIT_SYNONYMS);
+    addMetricUnitSynonyms(map);
+    return map;
+})();
 exports.TIMING_ABBREVIATIONS = {
     qd: {
         code: "QD",
@@ -256,12 +351,26 @@ exports.EVENT_TIMING_TOKENS = {
     "@meal": types_1.EventTiming.Meal,
     "@meals": types_1.EventTiming.Meal,
     cm: types_1.EventTiming.Breakfast,
+    breakfast: types_1.EventTiming.Breakfast,
+    bfast: types_1.EventTiming.Breakfast,
+    brkfst: types_1.EventTiming.Breakfast,
+    brk: types_1.EventTiming.Breakfast,
     cd: types_1.EventTiming.Lunch,
+    lunch: types_1.EventTiming.Lunch,
+    lunchtime: types_1.EventTiming.Lunch,
     cv: types_1.EventTiming.Dinner,
+    dinner: types_1.EventTiming.Dinner,
+    dinnertime: types_1.EventTiming.Dinner,
+    supper: types_1.EventTiming.Dinner,
+    suppertime: types_1.EventTiming.Dinner,
     am: types_1.EventTiming.Morning,
     morning: types_1.EventTiming.Morning,
     morn: types_1.EventTiming.Morning,
     noon: types_1.EventTiming.Noon,
+    midday: types_1.EventTiming.Noon,
+    "mid-day": types_1.EventTiming.Noon,
+    afternoon: types_1.EventTiming.Afternoon,
+    aft: types_1.EventTiming.Afternoon,
     pm: types_1.EventTiming.Evening,
     evening: types_1.EventTiming.Evening,
     night: types_1.EventTiming.Night,
@@ -271,12 +380,25 @@ exports.EVENT_TIMING_TOKENS = {
     waking: types_1.EventTiming.Wake,
     stat: types_1.EventTiming.Immediate
 };
-exports.MEAL_KEYWORDS = {
-    breakfast: { pc: types_1.EventTiming["After Breakfast"], ac: types_1.EventTiming["Before Breakfast"] },
-    lunch: { pc: types_1.EventTiming["After Lunch"], ac: types_1.EventTiming["Before Lunch"] },
-    dinner: { pc: types_1.EventTiming["After Dinner"], ac: types_1.EventTiming["Before Dinner"] },
-    supper: { pc: types_1.EventTiming["After Dinner"], ac: types_1.EventTiming["Before Dinner"] }
-};
+const MEAL_KEYWORD_ENTRIES = [];
+function registerMealKeywords(keys, meal) {
+    for (const key of keys) {
+        MEAL_KEYWORD_ENTRIES.push([key, meal]);
+    }
+}
+registerMealKeywords(["breakfast", "bfast", "brkfst", "brk"], {
+    pc: types_1.EventTiming["After Breakfast"],
+    ac: types_1.EventTiming["Before Breakfast"]
+});
+registerMealKeywords(["lunch", "lunchtime"], {
+    pc: types_1.EventTiming["After Lunch"],
+    ac: types_1.EventTiming["Before Lunch"]
+});
+registerMealKeywords(["dinner", "dinnertime", "supper", "suppertime"], {
+    pc: types_1.EventTiming["After Dinner"],
+    ac: types_1.EventTiming["Before Dinner"]
+});
+exports.MEAL_KEYWORDS = (0, object_1.objectFromEntries)(MEAL_KEYWORD_ENTRIES);
 exports.DISCOURAGED_TOKENS = {
     qd: "QD",
     qod: "QOD",
@@ -555,6 +677,8 @@ exports.KNOWN_TMT_DOSAGE_FORM_TO_SNOMED_ROUTE = {
     collodion: types_1.SNOMEDCTRouteCodes["Oral route"],
     "powder for rectal solution": types_1.SNOMEDCTRouteCodes["Per rectum"],
     "eye drops, solution": types_1.SNOMEDCTRouteCodes["Ocular route (qualifier value)"],
+    "eye drops": types_1.SNOMEDCTRouteCodes["Ocular route (qualifier value)"],
+    "eye drop": types_1.SNOMEDCTRouteCodes["Ocular route (qualifier value)"],
     "oromucosal paste": types_1.SNOMEDCTRouteCodes["Oromucosal use"],
     "dental paste": types_1.SNOMEDCTRouteCodes["Dental use"],
     "solution for peritoneal dialysis": types_1.SNOMEDCTRouteCodes["Intradialytic route"],

package/dist/parser.js

@@ -82,6 +82,7 @@ const SITE_FILLER_WORDS = new Set([
     "their",
     "my"
 ]);
+const HOUSEHOLD_VOLUME_UNIT_SET = new Set(maps_1.HOUSEHOLD_VOLUME_UNITS.map((unit) => unit.toLowerCase()));
 const OCULAR_DIRECTION_WORDS = new Set([
     "left",
     "right",
@@ -589,6 +590,84 @@ function removeWhen(target, code) {
         index = target.indexOf(code);
     }
 }
+const DEFAULT_EVENT_TIMING_WEIGHTS = {
+    [types_1.EventTiming.Immediate]: 0,
+    [types_1.EventTiming.Wake]: 6 * 3600,
+    [types_1.EventTiming["After Sleep"]]: 6 * 3600 + 15 * 60,
+    [types_1.EventTiming["Early Morning"]]: 7 * 3600,
+    [types_1.EventTiming["Before Meal"]]: 7 * 3600 + 30 * 60,
+    [types_1.EventTiming["Before Breakfast"]]: 7 * 3600 + 45 * 60,
+    [types_1.EventTiming.Morning]: 8 * 3600,
+    [types_1.EventTiming.Breakfast]: 8 * 3600 + 15 * 60,
+    [types_1.EventTiming.Meal]: 8 * 3600 + 30 * 60,
+    [types_1.EventTiming["After Breakfast"]]: 9 * 3600,
+    [types_1.EventTiming["After Meal"]]: 9 * 3600 + 15 * 60,
+    [types_1.EventTiming["Late Morning"]]: 10 * 3600 + 30 * 60,
+    [types_1.EventTiming["Before Lunch"]]: 11 * 3600 + 45 * 60,
+    [types_1.EventTiming.Noon]: 12 * 3600,
+    [types_1.EventTiming.Lunch]: 12 * 3600 + 15 * 60,
+    [types_1.EventTiming["After Lunch"]]: 12 * 3600 + 45 * 60,
+    [types_1.EventTiming["Early Afternoon"]]: 13 * 3600 + 30 * 60,
+    [types_1.EventTiming.Afternoon]: 15 * 3600,
+    [types_1.EventTiming["Late Afternoon"]]: 16 * 3600 + 30 * 60,
+    [types_1.EventTiming["Before Dinner"]]: 17 * 3600 + 30 * 60,
+    [types_1.EventTiming.Dinner]: 18 * 3600,
+    [types_1.EventTiming["After Dinner"]]: 19 * 3600,
+    [types_1.EventTiming["Early Evening"]]: 19 * 3600 + 30 * 60,
+    [types_1.EventTiming.Evening]: 20 * 3600,
+    [types_1.EventTiming["Late Evening"]]: 21 * 3600,
+    [types_1.EventTiming.Night]: 22 * 3600,
+    [types_1.EventTiming["Before Sleep"]]: 22 * 3600 + 30 * 60,
+};
+function parseClockToSeconds(clock) {
+    const match = clock.match(/^(\d{1,2}):(\d{2})(?::(\d{2}))?$/);
+    if (!match) {
+        return undefined;
+    }
+    const hour = Number(match[1]);
+    const minute = Number(match[2]);
+    const second = match[3] ? Number(match[3]) : 0;
+    if (!Number.isFinite(hour) ||
+        !Number.isFinite(minute) ||
+        !Number.isFinite(second) ||
+        hour < 0 ||
+        hour > 23 ||
+        minute < 0 ||
+        minute > 59 ||
+        second < 0 ||
+        second > 59) {
+        return undefined;
+    }
+    return hour * 3600 + minute * 60 + second;
+}
+function computeWhenWeight(code, options) {
+    var _a, _b;
+    const clock = (_a = options === null || options === void 0 ? void 0 : options.eventClock) === null || _a === void 0 ? void 0 : _a[code];
+    if (clock) {
+        const seconds = parseClockToSeconds(clock);
+        if (seconds !== undefined) {
+            return seconds;
+        }
+    }
+    return (_b = DEFAULT_EVENT_TIMING_WEIGHTS[code]) !== null && _b !== void 0 ? _b : 10000;
+}
+function sortWhenValues(internal, options) {
+    if (internal.when.length < 2) {
+        return;
+    }
+    const weighted = internal.when.map((code, index) => ({
+        code,
+        weight: computeWhenWeight(code, options),
+        index,
+    }));
+    weighted.sort((a, b) => {
+        if (a.weight !== b.weight) {
+            return a.weight - b.weight;
+        }
+        return a.index - b.index;
+    });
+    internal.when.splice(0, internal.when.length, ...weighted.map((entry) => entry.code));
+}
 // Translate the requested expansion context into the appropriate sequence of
 // EventTiming values (e.g., AC -> ACM/ACD/ACV) for the detected frequency.
 function computeMealExpansions(base, frequency, pairPreference) {
@@ -653,6 +732,37 @@ function computeMealExpansions(base, frequency, pairPreference) {
     }
     return [types_1.EventTiming.Breakfast, types_1.EventTiming.Lunch, types_1.EventTiming.Dinner, bedtime];
 }
+function reconcileMealTimingSpecificity(internal) {
+    if (!internal.when.length) {
+        return;
+    }
+    const convertSpecifics = (base, mappings) => {
+        if (!(0, array_1.arrayIncludes)(internal.when, base)) {
+            return;
+        }
+        let replaced = false;
+        for (const [general, specific] of mappings) {
+            if ((0, array_1.arrayIncludes)(internal.when, general)) {
+                removeWhen(internal.when, general);
+                addWhen(internal.when, specific);
+                replaced = true;
+            }
+        }
+        if (replaced) {
+            removeWhen(internal.when, base);
+        }
+    };
+    convertSpecifics(types_1.EventTiming["Before Meal"], [
+        [types_1.EventTiming.Breakfast, types_1.EventTiming["Before Breakfast"]],
+        [types_1.EventTiming.Lunch, types_1.EventTiming["Before Lunch"]],
+        [types_1.EventTiming.Dinner, types_1.EventTiming["Before Dinner"]],
+    ]);
+    convertSpecifics(types_1.EventTiming["After Meal"], [
+        [types_1.EventTiming.Breakfast, types_1.EventTiming["After Breakfast"]],
+        [types_1.EventTiming.Lunch, types_1.EventTiming["After Lunch"]],
+        [types_1.EventTiming.Dinner, types_1.EventTiming["After Dinner"]],
+    ]);
+}
 // Optionally replace generic meal tokens with concrete breakfast/lunch/dinner
 // EventTiming codes when the cadence makes the intent obvious.
 function expandMealTimings(internal, options) {
@@ -1225,10 +1335,10 @@ function parseInternal(input, options) {
         }
     }
     if (internal.unit === undefined) {
-        internal.unit = (0, context_1.inferUnitFromContext)(context);
+        internal.unit = enforceHouseholdUnitPolicy((0, context_1.inferUnitFromContext)(context), options);
     }
     if (internal.unit === undefined) {
-        const fallbackUnit = inferUnitFromRouteHints(internal);
+        const fallbackUnit = enforceHouseholdUnitPolicy(inferUnitFromRouteHints(internal), options);
         if (fallbackUnit) {
             internal.unit = fallbackUnit;
         }
@@ -1269,8 +1379,10 @@ function parseInternal(input, options) {
             internal.timingCode = "QID";
         }
     }
+    reconcileMealTimingSpecificity(internal);
     // Expand generic meal markers into specific EventTiming codes when asked to.
     expandMealTimings(internal, options);
+    sortWhenValues(internal, options);
     // Determine site text from leftover tokens (excluding PRN reason tokens)
     const leftoverTokens = tokens.filter((t) => !internal.consumed.has(t.index));
     const siteCandidateIndices = new Set();
@@ -1369,16 +1481,24 @@ function parseInternal(input, options) {
 }
 function normalizeUnit(token, options) {
     var _a;
-    const override = (_a = options === null || options === void 0 ? void 0 : options.unitMap) === null || _a === void 0 ? void 0 : _a[token];
+    const override = enforceHouseholdUnitPolicy((_a = options === null || options === void 0 ? void 0 : options.unitMap) === null || _a === void 0 ? void 0 : _a[token], options);
     if (override) {
         return override;
     }
-    const defaultUnit = maps_1.DEFAULT_UNIT_SYNONYMS[token];
+    const defaultUnit = enforceHouseholdUnitPolicy(maps_1.DEFAULT_UNIT_SYNONYMS[token], options);
     if (defaultUnit) {
         return defaultUnit;
     }
     return undefined;
 }
+function enforceHouseholdUnitPolicy(unit, options) {
+    if (unit &&
+        (options === null || options === void 0 ? void 0 : options.allowHouseholdVolumeUnits) === false &&
+        HOUSEHOLD_VOLUME_UNIT_SET.has(unit.toLowerCase())) {
+        return undefined;
+    }
+    return unit;
+}
 function inferUnitFromRouteHints(internal) {
     if (internal.routeCode) {
         const unit = maps_1.DEFAULT_UNIT_BY_ROUTE[internal.routeCode];

package/dist/suggest.js

@@ -2,50 +2,123 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.suggestSig = suggestSig;
 const context_1 = require("./context");
+const maps_1 = require("./maps");
+const types_1 = require("./types");
 const DEFAULT_LIMIT = 10;
+const HOUSEHOLD_VOLUME_UNIT_SET = new Set(maps_1.HOUSEHOLD_VOLUME_UNITS.map((unit) => unit.trim().toLowerCase()));
+const ROUTE_TOKEN_BY_CODE = {
+    [types_1.RouteCode["Oral route"]]: "po",
+    [types_1.RouteCode["Respiratory tract route (qualifier value)"]]: "inh",
+    [types_1.RouteCode["Nasal route"]]: "in",
+    [types_1.RouteCode["Ophthalmic route"]]: "oph",
+    [types_1.RouteCode["Per rectum"]]: "pr",
+    [types_1.RouteCode["Transdermal route"]]: "transdermal",
+    [types_1.RouteCode["Topical route"]]: "topical",
+};
 const DEFAULT_UNIT_ROUTE_ORDER = [
-    { unit: "tab", route: "po" },
-    { unit: "cap", route: "po" },
-    { unit: "mL", route: "po" },
-    { unit: "mg", route: "po" },
-    { unit: "puff", route: "inh" },
-    { unit: "spray", route: "in" },
-    { unit: "drop", route: "oph" },
-    { unit: "suppository", route: "pr" },
-    { unit: "patch", route: "transdermal" },
-    { unit: "g", route: "topical" }
+    { unit: "tab", routeCode: types_1.RouteCode["Oral route"] },
+    { unit: "cap", routeCode: types_1.RouteCode["Oral route"] },
+    { unit: "tsp", routeCode: types_1.RouteCode["Oral route"] },
+    { unit: "tbsp", routeCode: types_1.RouteCode["Oral route"] },
+    { unit: "mL", routeCode: types_1.RouteCode["Oral route"] },
+    { unit: "L", routeCode: types_1.RouteCode["Oral route"] },
+    { unit: "mcL", routeCode: types_1.RouteCode["Oral route"] },
+    { unit: "nL", routeCode: types_1.RouteCode["Oral route"] },
+    { unit: "mg", routeCode: types_1.RouteCode["Oral route"] },
+    { unit: "mcg", routeCode: types_1.RouteCode["Oral route"] },
+    { unit: "ng", routeCode: types_1.RouteCode["Oral route"] },
+    { unit: "g", routeCode: types_1.RouteCode["Topical route"] },
+    { unit: "kg", routeCode: types_1.RouteCode["Topical route"] },
+    { unit: "puff", routeCode: types_1.RouteCode["Respiratory tract route (qualifier value)"] },
+    { unit: "spray", routeCode: types_1.RouteCode["Nasal route"] },
+    { unit: "drop", routeCode: types_1.RouteCode["Ophthalmic route"] },
+    { unit: "suppository", routeCode: types_1.RouteCode["Per rectum"] },
+    { unit: "patch", routeCode: types_1.RouteCode["Transdermal route"] },
 ];
-const DEFAULT_ROUTE_BY_UNIT = {
-    tab: "po",
-    tabs: "po",
-    tablet: "po",
-    cap: "po",
-    capsule: "po",
-    ml: "po",
-    mg: "po",
-    puff: "inh",
-    puffs: "inh",
-    spray: "in",
-    sprays: "in",
-    drop: "oph",
-    drops: "oph",
-    suppository: "pr",
-    suppositories: "pr",
-    patch: "transdermal",
-    patches: "transdermal",
-    g: "topical"
-};
-const FREQUENCY_CODES = ["qd", "bid", "tid", "qid"];
-const INTERVAL_CODES = ["q4h", "q6h", "q8h"];
-const WHEN_TOKENS = ["ac", "pc", "hs", "am", "pm"];
-const CORE_WHEN_TOKENS = ["pc", "ac", "hs"];
-const FREQUENCY_NUMBERS = [1, 2, 3, 4];
-const FREQ_TOKEN_BY_NUMBER = {
-    1: "qd",
-    2: "bid",
-    3: "tid",
-    4: "qid",
-};
+const ROUTE_TOKEN_BY_UNIT = (() => {
+    var _a, _b, _c;
+    const map = new Map();
+    const assign = (unit, token) => {
+        if (!unit || !token) {
+            return;
+        }
+        const normalizedUnit = normalizeKey(unit);
+        if (!normalizedUnit || map.has(normalizedUnit)) {
+            return;
+        }
+        map.set(normalizedUnit, normalizeSpacing(token));
+    };
+    for (const routeCodeKey in maps_1.DEFAULT_UNIT_BY_ROUTE) {
+        if (!Object.prototype.hasOwnProperty.call(maps_1.DEFAULT_UNIT_BY_ROUTE, routeCodeKey)) {
+            continue;
+        }
+        const routeCode = routeCodeKey;
+        const unit = maps_1.DEFAULT_UNIT_BY_ROUTE[routeCode];
+        if (!unit) {
+            continue;
+        }
+        const token = (_a = ROUTE_TOKEN_BY_CODE[routeCode]) !== null && _a !== void 0 ? _a : maps_1.ROUTE_TEXT[routeCode];
+        assign(unit, token);
+    }
+    for (const preference of DEFAULT_UNIT_ROUTE_ORDER) {
+        const token = (_c = (_b = preference.routeToken) !== null && _b !== void 0 ? _b : ROUTE_TOKEN_BY_CODE[preference.routeCode]) !== null && _c !== void 0 ? _c : maps_1.ROUTE_TEXT[preference.routeCode];
+        assign(preference.unit, token);
+    }
+    return map;
+})();
+const BASE_INTERVAL_CODES = Object.keys(maps_1.TIMING_ABBREVIATIONS)
+    .filter((token) => /^q\d+h$/.test(token))
+    .sort((a, b) => Number.parseInt(a.slice(1, -1), 10) - Number.parseInt(b.slice(1, -1), 10));
+const DEFAULT_INTERVAL_RANGES = ["q2-4h", "q4-6h", "q6-8h", "q8-12h"];
+const BASE_WHEN_TOKEN_CANDIDATES = [
+    "ac",
+    "pc",
+    "hs",
+    "am",
+    "pm",
+    "morn",
+    "morning",
+    "noon",
+    "afternoon",
+    "evening",
+    "night",
+    "bedtime",
+    "wake",
+    "waking",
+    "breakfast",
+    "lunch",
+    "dinner",
+    "stat",
+];
+const WHEN_TOKENS = BASE_WHEN_TOKEN_CANDIDATES.filter((token) => maps_1.EVENT_TIMING_TOKENS[token] !== undefined);
+const WHEN_COMBINATIONS = [
+    "am",
+    "morning",
+    "morn",
+    "noon",
+    "afternoon",
+    "pm",
+    "evening",
+    "night",
+    "hs",
+    "bedtime",
+].filter((token) => maps_1.EVENT_TIMING_TOKENS[token] !== undefined);
+const CORE_WHEN_TOKENS = ["pc", "ac", "hs"].filter((token) => maps_1.EVENT_TIMING_TOKENS[token] !== undefined);
+const FREQUENCY_CODES = ["qd", "od", "bid", "tid", "qid"].filter((token) => maps_1.TIMING_ABBREVIATIONS[token] !== undefined);
+const FREQ_TOKEN_BY_NUMBER = {};
+for (const [frequency, token] of [
+    [1, "qd"],
+    [2, "bid"],
+    [3, "tid"],
+    [4, "qid"],
+]) {
+    if (maps_1.TIMING_ABBREVIATIONS[token]) {
+        FREQ_TOKEN_BY_NUMBER[frequency] = token;
+    }
+}
+const FREQUENCY_NUMBERS = Object.keys(FREQ_TOKEN_BY_NUMBER)
+    .map((value) => Number.parseInt(value, 10))
+    .sort((a, b) => a - b);
 const DEFAULT_PRN_REASONS = [
     "pain",
     "nausea",
@@ -59,6 +132,72 @@ const DEFAULT_PRN_REASONS = [
     "dyspnea",
 ];
 const DEFAULT_DOSE_COUNTS = ["1", "2"];
+const OPTIONAL_MATCH_TOKENS = new Set([
+    "to",
+    "into",
+    "in",
+    "on",
+    "onto",
+    "per",
+    "for",
+    "the",
+    "od",
+    "os",
+    "ou",
+]);
+const ROUTE_TOKEN_FRAGMENTS = new Set();
+for (const phrase of Object.keys(maps_1.DEFAULT_ROUTE_SYNONYMS)) {
+    for (const fragment of phrase.split(/\s+/)) {
+        const normalized = fragment.trim();
+        if (normalized) {
+            ROUTE_TOKEN_FRAGMENTS.add(normalized);
+        }
+    }
+}
+const SKIPPABLE_CANDIDATE_TOKENS = new Set([
+    ...Array.from(OPTIONAL_MATCH_TOKENS),
+    ...Array.from(ROUTE_TOKEN_FRAGMENTS),
+]);
+const UNIT_LOOKUP = (() => {
+    const canonicalByKey = new Map();
+    const variantsByCanonical = new Map();
+    const registerVariant = (canonical, variant) => {
+        const normalizedCanonical = normalizeKey(canonical);
+        if (!normalizedCanonical) {
+            return;
+        }
+        let variants = variantsByCanonical.get(normalizedCanonical);
+        if (!variants) {
+            variants = new Set();
+            variantsByCanonical.set(normalizedCanonical, variants);
+        }
+        variants.add(normalizeSpacing(canonical));
+        variants.add(normalizeSpacing(variant));
+    };
+    for (const token in maps_1.DEFAULT_UNIT_SYNONYMS) {
+        if (!Object.prototype.hasOwnProperty.call(maps_1.DEFAULT_UNIT_SYNONYMS, token)) {
+            continue;
+        }
+        const canonicalValue = maps_1.DEFAULT_UNIT_SYNONYMS[token];
+        const canonical = normalizeSpacing(canonicalValue);
+        registerVariant(canonical, canonical);
+        registerVariant(canonical, token);
+        canonicalByKey.set(normalizeKey(token), canonical);
+        canonicalByKey.set(normalizeKey(canonical), canonical);
+    }
+    return { canonicalByKey, variantsByCanonical };
+})();
+function resolveCanonicalUnit(unit) {
+    var _a;
+    if (!unit) {
+        return undefined;
+    }
+    const normalized = normalizeKey(unit);
+    if (!normalized) {
+        return undefined;
+    }
+    return (_a = UNIT_LOOKUP.canonicalByKey.get(normalized)) !== null && _a !== void 0 ? _a : normalizeSpacing(unit);
+}
 function normalizeKey(value) {
     return value.trim().toLowerCase();
 }
@@ -67,33 +206,153 @@ function normalizeSpacing(value) {
         .trim()
         .replace(/\s+/g, " ");
 }
-function buildUnitRoutePairs(contextUnit) {
+function getUnitVariants(unit) {
+    var _a;
+    const canonical = (_a = resolveCanonicalUnit(unit)) !== null && _a !== void 0 ? _a : normalizeSpacing(unit);
+    const normalizedCanonical = normalizeKey(canonical);
+    const variants = new Set();
+    const push = (candidate) => {
+        if (!candidate) {
+            return;
+        }
+        const normalizedCandidate = normalizeSpacing(candidate);
+        if (!normalizedCandidate) {
+            return;
+        }
+        variants.add(normalizedCandidate);
+    };
+    push(canonical);
+    push(unit);
+    const canonicalVariants = UNIT_LOOKUP.variantsByCanonical.get(normalizedCanonical);
+    if (canonicalVariants) {
+        for (const candidate of canonicalVariants) {
+            push(candidate);
+        }
+    }
+    return [...variants];
+}
+function buildIntervalTokens(input) {
+    const intervals = new Set();
+    const add = (token) => {
+        if (!token) {
+            return;
+        }
+        const normalized = token.trim().toLowerCase();
+        if (!normalized) {
+            return;
+        }
+        intervals.add(normalized);
+    };
+    for (const token of BASE_INTERVAL_CODES) {
+        add(token);
+    }
+    for (const token of DEFAULT_INTERVAL_RANGES) {
+        add(token);
+    }
+    const normalizedInput = input.toLowerCase();
+    const rawTokens = normalizedInput.split(/[^a-z0-9-]+/g);
+    for (const rawToken of rawTokens) {
+        if (!rawToken) {
+            continue;
+        }
+        const match = rawToken.match(/^q(\d{1,2})(?:-(\d{1,2}))?(h?)$/);
+        if (!match) {
+            continue;
+        }
+        const first = Number.parseInt(match[1], 10);
+        const second = match[2] ? Number.parseInt(match[2], 10) : undefined;
+        if (Number.isNaN(first) || first <= 0 || first > 48) {
+            continue;
+        }
+        if (second !== undefined) {
+            if (Number.isNaN(second) || second < first || second > 48) {
+                continue;
+            }
+        }
+        const normalized = `q${first}${second ? `-${second}` : ""}h`;
+        add(normalized);
+    }
+    return [...intervals];
+}
+function buildWhenSequences() {
+    const sequences = [];
+    for (const token of WHEN_TOKENS) {
+        sequences.push([token]);
+    }
+    for (let i = 0; i < WHEN_COMBINATIONS.length; i++) {
+        const first = WHEN_COMBINATIONS[i];
+        for (let j = i + 1; j < WHEN_COMBINATIONS.length; j++) {
+            const second = WHEN_COMBINATIONS[j];
+            sequences.push([first, second]);
+        }
+    }
+    return sequences;
+}
+function tokenizeForMatching(value) {
+    return value
+        .toLowerCase()
+        .split(/\s+/)
+        .map((token) => token.replace(/^[^a-z0-9-]+|[^a-z0-9-]+$/g, ""))
+        .filter((token) => token.length > 0)
+        .filter((token) => !OPTIONAL_MATCH_TOKENS.has(token));
+}
+function canonicalizeForMatching(value) {
+    return tokenizeForMatching(value).join(" ");
+}
+function tokensMatch(prefixTokens, candidateTokens) {
+    if (prefixTokens.length === 0) {
+        return true;
+    }
+    let prefixIndex = 0;
+    for (const candidateToken of candidateTokens) {
+        if (prefixIndex >= prefixTokens.length) {
+            return true;
+        }
+        const prefixToken = prefixTokens[prefixIndex];
+        if (candidateToken.startsWith(prefixToken)) {
+            prefixIndex += 1;
+            if (prefixIndex >= prefixTokens.length) {
+                return true;
+            }
+            continue;
+        }
+        if (!SKIPPABLE_CANDIDATE_TOKENS.has(candidateToken)) {
+            return false;
+        }
+    }
+    return prefixIndex >= prefixTokens.length;
+}
+function buildUnitRoutePairs(contextUnit, options) {
+    var _a, _b;
     const pairs = [];
     const seen = new Set();
-    const addPair = (unit, route) => {
+    const addPair = (unit, routeOverride) => {
         var _a;
-        if (!unit) {
+        const canonicalUnit = resolveCanonicalUnit(unit);
+        if (!canonicalUnit) {
+            return;
+        }
+        const normalizedUnit = normalizeKey(canonicalUnit);
+        if ((options === null || options === void 0 ? void 0 : options.allowHouseholdVolumeUnits) === false &&
+            HOUSEHOLD_VOLUME_UNIT_SET.has(normalizedUnit)) {
             return;
         }
-        const cleanUnit = unit.trim();
-        if (!cleanUnit) {
+        const resolvedRoute = (_a = routeOverride !== null && routeOverride !== void 0 ? routeOverride : ROUTE_TOKEN_BY_UNIT.get(normalizedUnit)) !== null && _a !== void 0 ? _a : "po";
+        const cleanRoute = normalizeSpacing(resolvedRoute);
+        if (!cleanRoute) {
             return;
         }
-        const normalizedUnit = cleanUnit.toLowerCase();
-        const resolvedRoute = (_a = route !== null && route !== void 0 ? route : DEFAULT_ROUTE_BY_UNIT[normalizedUnit]) !== null && _a !== void 0 ? _a : "po";
-        const key = `${normalizedUnit}::${resolvedRoute.toLowerCase()}`;
+        const key = `${normalizedUnit}::${normalizeKey(cleanRoute)}`;
         if (seen.has(key)) {
             return;
         }
         seen.add(key);
-        pairs.push({ unit: cleanUnit, route: resolvedRoute });
+        pairs.push({ unit: canonicalUnit, route: cleanRoute });
     };
-    if (contextUnit) {
-        const normalized = normalizeKey(contextUnit);
-        addPair(contextUnit, DEFAULT_ROUTE_BY_UNIT[normalized]);
-    }
-    for (const pair of DEFAULT_UNIT_ROUTE_ORDER) {
-        addPair(pair.unit, pair.route);
+    addPair(contextUnit);
+    for (const preference of DEFAULT_UNIT_ROUTE_ORDER) {
+        const routeToken = (_b = (_a = preference.routeToken) !== null && _a !== void 0 ? _a : ROUTE_TOKEN_BY_CODE[preference.routeCode]) !== null && _b !== void 0 ? _b : maps_1.ROUTE_TEXT[preference.routeCode];
+        addPair(preference.unit, routeToken);
     }
     return pairs;
 }
@@ -144,7 +403,7 @@ function buildDoseValues(input) {
     }
     return [...values];
 }
-function generateCandidateSignatures(pairs, doseValues, prnReasons) {
+function generateCandidateDirections(pairs, doseValues, prnReasons, intervalTokens, whenSequences) {
     const suggestions = [];
     const seen = new Set();
     const push = (value) => {
@@ -160,41 +419,57 @@ function generateCandidateSignatures(pairs, doseValues, prnReasons) {
         suggestions.push(normalized);
     };
     for (const pair of pairs) {
+        const unitVariants = getUnitVariants(pair.unit);
         for (const code of FREQUENCY_CODES) {
-            for (const dose of doseValues) {
-                push(`${dose} ${pair.unit} ${pair.route} ${code}`);
+            for (const unitVariant of unitVariants) {
+                for (const dose of doseValues) {
+                    push(`${dose} ${unitVariant} ${pair.route} ${code}`);
+                }
             }
             push(`${pair.route} ${code}`);
         }
-        for (const interval of INTERVAL_CODES) {
-            for (const dose of doseValues) {
-                push(`${dose} ${pair.unit} ${pair.route} ${interval}`);
-                for (const reason of prnReasons) {
-                    push(`${dose} ${pair.unit} ${pair.route} ${interval} prn ${reason}`);
+        for (const interval of intervalTokens) {
+            for (const unitVariant of unitVariants) {
+                for (const dose of doseValues) {
+                    push(`${dose} ${unitVariant} ${pair.route} ${interval}`);
+                    for (const reason of prnReasons) {
+                        push(`${dose} ${unitVariant} ${pair.route} ${interval} prn ${reason}`);
+                    }
                 }
             }
             push(`${pair.route} ${interval}`);
         }
         for (const freq of FREQUENCY_NUMBERS) {
             const freqToken = FREQ_TOKEN_BY_NUMBER[freq];
+            if (!freqToken) {
+                continue;
+            }
             push(`1x${freq} ${pair.route} ${freqToken}`);
             for (const when of CORE_WHEN_TOKENS) {
                 push(`1x${freq} ${pair.route} ${when}`);
             }
         }
-        for (const when of WHEN_TOKENS) {
-            for (const dose of doseValues) {
-                push(`${dose} ${pair.unit} ${pair.route} ${when}`);
+        for (const whenSequence of whenSequences) {
+            const suffix = whenSequence.join(" ");
+            for (const unitVariant of unitVariants) {
+                for (const dose of doseValues) {
+                    push(`${dose} ${unitVariant} ${pair.route} ${suffix}`);
+                }
             }
-            push(`${pair.route} ${when}`);
+            push(`${pair.route} ${suffix}`);
         }
         for (const reason of prnReasons) {
-            push(`1 ${pair.unit} ${pair.route} prn ${reason}`);
+            for (const unitVariant of unitVariants) {
+                for (const dose of doseValues) {
+                    push(`${dose} ${unitVariant} ${pair.route} prn ${reason}`);
+                }
+            }
+            push(`${pair.route} prn ${reason}`);
         }
     }
     return suggestions;
 }
-function matchesPrefix(candidate, prefix, prefixCompact) {
+function matchesPrefix(candidate, prefix, prefixCompact, prefixTokens, prefixTokensNoDashes, prefixCanonical, prefixCanonicalCompact, prefixNoDashes, prefixCanonicalNoDashes) {
     if (!prefix) {
         return true;
     }
@@ -203,21 +478,53 @@ function matchesPrefix(candidate, prefix, prefixCompact) {
         return true;
     }
     const compactCandidate = normalizedCandidate.replace(/\s+/g, "");
-    return compactCandidate.startsWith(prefixCompact);
+    if (compactCandidate.startsWith(prefixCompact)) {
+        return true;
+    }
+    const candidateNoDashes = normalizedCandidate.replace(/-/g, "");
+    if (candidateNoDashes.startsWith(prefixNoDashes)) {
+        return true;
+    }
+    const canonicalCandidate = canonicalizeForMatching(candidate);
+    if (canonicalCandidate.startsWith(prefixCanonical)) {
+        return true;
+    }
+    const canonicalCompact = canonicalCandidate.replace(/\s+/g, "");
+    if (canonicalCompact.startsWith(prefixCanonicalCompact)) {
+        return true;
+    }
+    const candidateTokens = tokenizeForMatching(candidate);
+    if (tokensMatch(prefixTokens, candidateTokens)) {
+        return true;
+    }
+    const canonicalNoDashes = canonicalCandidate.replace(/-/g, "");
+    if (canonicalNoDashes.startsWith(prefixCanonicalNoDashes)) {
+        return true;
+    }
+    const candidateTokensNoDashes = candidateTokens.map((token) => token.replace(/-/g, ""));
+    return tokensMatch(prefixTokensNoDashes, candidateTokensNoDashes);
 }
 function suggestSig(input, options) {
     var _a, _b;
     const limit = (_a = options === null || options === void 0 ? void 0 : options.limit) !== null && _a !== void 0 ? _a : DEFAULT_LIMIT;
     const prefix = normalizeSpacing(input.toLowerCase());
     const prefixCompact = prefix.replace(/\s+/g, "");
+    const prefixNoDashes = prefix.replace(/-/g, "");
+    const prefixCanonical = canonicalizeForMatching(prefix);
+    const prefixCanonicalCompact = prefixCanonical.replace(/\s+/g, "");
+    const prefixCanonicalNoDashes = prefixCanonical.replace(/-/g, "");
+    const prefixTokens = tokenizeForMatching(prefixCanonical);
+    const prefixTokensNoDashes = prefixTokens.map((token) => token.replace(/-/g, ""));
     const contextUnit = (0, context_1.inferUnitFromContext)((_b = options === null || options === void 0 ? void 0 : options.context) !== null && _b !== void 0 ? _b : undefined);
-    const pairs = buildUnitRoutePairs(contextUnit);
+    const pairs = buildUnitRoutePairs(contextUnit, options);
     const doseValues = buildDoseValues(input);
     const prnReasons = buildPrnReasons(options === null || options === void 0 ? void 0 : options.prnReasons);
-    const candidates = generateCandidateSignatures(pairs, doseValues, prnReasons);
+    const intervalTokens = buildIntervalTokens(input);
+    const whenSequences = buildWhenSequences();
+    const candidates = generateCandidateDirections(pairs, doseValues, prnReasons, intervalTokens, whenSequences);
     const results = [];
     for (const candidate of candidates) {
-        if (matchesPrefix(candidate, prefix, prefixCompact)) {
+        if (matchesPrefix(candidate, prefix, prefixCompact, prefixTokens, prefixTokensNoDashes, prefixCanonical, prefixCanonicalCompact, prefixNoDashes, prefixCanonicalNoDashes)) {
             results.push(candidate);
         }
         if (results.length >= limit) {

package/dist/types.d.ts

@@ -303,6 +303,11 @@ export interface ParseOptions extends FormatOptions {
         intervalWeeks?: number;
     }>;
     whenMap?: Record<string, EventTiming>;
+    /**
+     * Allows supplying institution-specific event clock anchors so parsed
+     * EventTiming arrays can be ordered chronologically for that locale.
+     */
+    eventClock?: EventClockMap;
     allowDiscouraged?: boolean;
     /**
      * When enabled the parser will expand generic meal timing tokens (AC/PC/C)
@@ -315,6 +320,11 @@ export interface ParseOptions extends FormatOptions {
      * Defaults to "breakfast+dinner" to mirror common clinical practice.
      */
     twoPerDayPair?: "breakfast+dinner" | "breakfast+lunch";
+    /**
+     * Allows disabling recognition of household volume units such as teaspoon
+     * and tablespoon when set to false. Defaults to true.
+     */
+    allowHouseholdVolumeUnits?: boolean;
 }
 export interface ParseResult {
     fhir: FhirDosage;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ezmedicationinput",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Parse concise medication sigs into FHIR R5 Dosage JSON",
   "type": "module",
   "main": "dist/index.js",