ezmedicationinput 0.1.23 → 0.1.25

package/README.md

@@ -352,6 +352,58 @@ Key rules:
 
 `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.
 
+### Medication amount calculation
+
+`calculateTotalUnits` computes the total amount of medication (and optionally the number of containers) required for a specific duration. It accounts for complex schedules, dose ranges (using the high value), and unit conversions between doses and containers.
+
+```ts
+import { calculateTotalUnits, parseSig } from "ezmedicationinput";
+
+const { fhir } = parseSig("1x3 po pc");
+
+const result = calculateTotalUnits({
+  dosage: fhir,
+  from: "2024-01-01T08:00:00Z",
+  durationValue: 7,
+  durationUnit: "d",
+  timeZone: "Asia/Bangkok",
+  context: {
+    containerValue: 30, // 30 tabs per bottle
+    containerUnit: "tab"
+  }
+});
+
+// → { totalUnits: 21, totalContainers: 1 }
+```
+
+It can also handle strength-based conversions (e.g. calculating how many 100mL bottles are needed for a 500mg TID dose of a 250mg/5mL suspension).
+
+### Strength parsing
+
+Use `parseStrength` to normalize medication strength strings into FHIR-compliant **Quantity** or **Ratio** structures. It understands percentages, ratios, and composite strengths.
+
+```ts
+import { parseStrength } from "ezmedicationinput";
+
+// Percentage (infers g/100mL for liquids or g/100g for solids)
+parseStrength("1%", { dosageForm: "cream" }); 
+// → { strengthRatio: { numerator: { value: 1, unit: "g" }, denominator: { value: 100, unit: "g" } } }
+
+// Ratios
+parseStrength("250mg/5mL");
+// → { strengthRatio: { numerator: { value: 250, unit: "mg" }, denominator: { value: 5, unit: "mL" } } }
+
+// Composite (sums components into a single ratio)
+parseStrength("875mg + 125mg");
+// → { strengthQuantity: { value: 1000, unit: "mg" } }
+
+// Simple Quantity
+parseStrength("500mg");
+// → { strengthQuantity: { value: 500, unit: "mg" } }
+```
+
+`parseStrengthIntoRatio` is also available if you specifically need a FHIR Ratio object regardless of the denominator.
+
 ### 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/fhir.js

@@ -9,7 +9,7 @@ const object_1 = require("./utils/object");
 const array_1 = require("./utils/array");
 const SNOMED_SYSTEM = "http://snomed.info/sct";
 function toFhir(internal) {
-    var _a, _b, _c, _d, _e, _f, _g, _h, _j;
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k;
     const dosage = {};
     const repeat = {};
     let hasRepeat = false;
@@ -42,6 +42,10 @@ function toFhir(internal) {
         repeat.when = [...internal.when];
         hasRepeat = true;
     }
+    if ((_a = internal.timeOfDay) === null || _a === void 0 ? void 0 : _a.length) {
+        repeat.timeOfDay = [...internal.timeOfDay];
+        hasRepeat = true;
+    }
     if (hasRepeat) {
         dosage.timing = { repeat };
     }
@@ -49,7 +53,7 @@ function toFhir(internal) {
         dosage.timing = {};
     }
     if (internal.timingCode) {
-        dosage.timing = (_a = dosage.timing) !== null && _a !== void 0 ? _a : {};
+        dosage.timing = (_b = dosage.timing) !== null && _b !== void 0 ? _b : {};
         dosage.timing.code = {
             coding: [{ code: internal.timingCode }],
             text: internal.timingCode
@@ -82,7 +86,7 @@ function toFhir(internal) {
     // Emit SNOMED-coded routes whenever we have parsed or inferred route data.
     if (internal.routeCode || internal.routeText) {
         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);
+        const text = (_c = internal.routeText) !== null && _c !== void 0 ? _c : (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 = {
@@ -100,11 +104,11 @@ function toFhir(internal) {
             dosage.route = { text };
         }
     }
-    if (internal.siteText || ((_c = internal.siteCoding) === null || _c === void 0 ? void 0 : _c.code)) {
-        const coding = ((_d = internal.siteCoding) === null || _d === void 0 ? void 0 : _d.code)
+    if (internal.siteText || ((_d = internal.siteCoding) === null || _d === void 0 ? void 0 : _d.code)) {
+        const coding = ((_e = internal.siteCoding) === null || _e === void 0 ? void 0 : _e.code)
             ? [
                 {
-                    system: (_e = internal.siteCoding.system) !== null && _e !== void 0 ? _e : SNOMED_SYSTEM,
+                    system: (_f = internal.siteCoding.system) !== null && _f !== void 0 ? _f : SNOMED_SYSTEM,
                     code: internal.siteCoding.code,
                     display: internal.siteCoding.display
                 }
@@ -115,7 +119,7 @@ function toFhir(internal) {
             coding
         };
     }
-    if ((_f = internal.additionalInstructions) === null || _f === void 0 ? void 0 : _f.length) {
+    if ((_g = internal.additionalInstructions) === null || _g === void 0 ? void 0 : _g.length) {
         dosage.additionalInstruction = internal.additionalInstructions.map((instruction) => {
             var _a, _b;
             return ({
@@ -134,15 +138,15 @@ function toFhir(internal) {
     }
     if (internal.asNeeded) {
         dosage.asNeededBoolean = true;
-        if (internal.asNeededReason || ((_g = internal.asNeededReasonCoding) === null || _g === void 0 ? void 0 : _g.code)) {
+        if (internal.asNeededReason || ((_h = internal.asNeededReasonCoding) === null || _h === void 0 ? void 0 : _h.code)) {
             const concept = {};
             if (internal.asNeededReason) {
                 concept.text = internal.asNeededReason;
             }
-            if ((_h = internal.asNeededReasonCoding) === null || _h === void 0 ? void 0 : _h.code) {
+            if ((_j = internal.asNeededReasonCoding) === null || _j === void 0 ? void 0 : _j.code) {
                 concept.coding = [
                     {
-                        system: (_j = internal.asNeededReasonCoding.system) !== null && _j !== void 0 ? _j : SNOMED_SYSTEM,
+                        system: (_k = internal.asNeededReasonCoding.system) !== null && _k !== void 0 ? _k : SNOMED_SYSTEM,
                         code: internal.asNeededReasonCoding.code,
                         display: internal.asNeededReasonCoding.display
                     }
@@ -158,7 +162,7 @@ function toFhir(internal) {
     return 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, _4, _5, _6, _7, _8, _9, _10, _11;
+    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, _4, _5, _6, _7, _8, _9, _10, _11, _12, _13;
     const internal = {
         input: (_a = dosage.text) !== null && _a !== void 0 ? _a : "",
         tokens: [],
@@ -169,24 +173,27 @@ function internalFromFhir(dosage) {
         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))
             : [],
+        timeOfDay: ((_g = (_f = dosage.timing) === null || _f === void 0 ? void 0 : _f.repeat) === null || _g === void 0 ? void 0 : _g.timeOfDay)
+            ? [...dosage.timing.repeat.timeOfDay]
+            : [],
         warnings: [],
-        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,
-        count: (_l = (_k = dosage.timing) === null || _k === void 0 ? void 0 : _k.repeat) === null || _l === void 0 ? void 0 : _l.count,
-        frequency: (_o = (_m = dosage.timing) === null || _m === void 0 ? void 0 : _m.repeat) === null || _o === void 0 ? void 0 : _o.frequency,
-        frequencyMax: (_q = (_p = dosage.timing) === null || _p === void 0 ? void 0 : _p.repeat) === null || _q === void 0 ? void 0 : _q.frequencyMax,
-        period: (_s = (_r = dosage.timing) === null || _r === void 0 ? void 0 : _r.repeat) === null || _s === void 0 ? void 0 : _s.period,
-        periodMax: (_u = (_t = dosage.timing) === null || _t === void 0 ? void 0 : _t.repeat) === null || _u === void 0 ? void 0 : _u.periodMax,
-        periodUnit: (_w = (_v = dosage.timing) === null || _v === void 0 ? void 0 : _v.repeat) === null || _w === void 0 ? void 0 : _w.periodUnit,
-        routeText: (_x = dosage.route) === null || _x === void 0 ? void 0 : _x.text,
-        siteText: (_y = dosage.site) === null || _y === void 0 ? void 0 : _y.text,
+        timingCode: (_l = (_k = (_j = (_h = dosage.timing) === null || _h === void 0 ? void 0 : _h.code) === null || _j === void 0 ? void 0 : _j.coding) === null || _k === void 0 ? void 0 : _k[0]) === null || _l === void 0 ? void 0 : _l.code,
+        count: (_o = (_m = dosage.timing) === null || _m === void 0 ? void 0 : _m.repeat) === null || _o === void 0 ? void 0 : _o.count,
+        frequency: (_q = (_p = dosage.timing) === null || _p === void 0 ? void 0 : _p.repeat) === null || _q === void 0 ? void 0 : _q.frequency,
+        frequencyMax: (_s = (_r = dosage.timing) === null || _r === void 0 ? void 0 : _r.repeat) === null || _s === void 0 ? void 0 : _s.frequencyMax,
+        period: (_u = (_t = dosage.timing) === null || _t === void 0 ? void 0 : _t.repeat) === null || _u === void 0 ? void 0 : _u.period,
+        periodMax: (_w = (_v = dosage.timing) === null || _v === void 0 ? void 0 : _v.repeat) === null || _w === void 0 ? void 0 : _w.periodMax,
+        periodUnit: (_y = (_x = dosage.timing) === null || _x === void 0 ? void 0 : _x.repeat) === null || _y === void 0 ? void 0 : _y.periodUnit,
+        routeText: (_z = dosage.route) === null || _z === void 0 ? void 0 : _z.text,
+        siteText: (_0 = dosage.site) === null || _0 === void 0 ? void 0 : _0.text,
         asNeeded: dosage.asNeededBoolean,
-        asNeededReason: (_0 = (_z = dosage.asNeededFor) === null || _z === void 0 ? void 0 : _z[0]) === null || _0 === void 0 ? void 0 : _0.text,
+        asNeededReason: (_2 = (_1 = dosage.asNeededFor) === null || _1 === void 0 ? void 0 : _1[0]) === null || _2 === void 0 ? void 0 : _2.text,
         siteTokenIndices: new Set(),
         siteLookups: [],
         prnReasonLookups: [],
         additionalInstructions: []
     };
-    const routeCoding = (_2 = (_1 = dosage.route) === null || _1 === void 0 ? void 0 : _1.coding) === null || _2 === void 0 ? void 0 : _2.find((code) => code.system === SNOMED_SYSTEM);
+    const routeCoding = (_4 = (_3 = dosage.route) === null || _3 === void 0 ? void 0 : _3.coding) === null || _4 === void 0 ? void 0 : _4.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 = maps_1.ROUTE_BY_SNOMED[routeCoding.code];
@@ -195,7 +202,7 @@ function internalFromFhir(dosage) {
             internal.routeText = maps_1.ROUTE_TEXT[mapped];
         }
     }
-    const siteCoding = (_4 = (_3 = dosage.site) === null || _3 === void 0 ? void 0 : _3.coding) === null || _4 === void 0 ? void 0 : _4.find((code) => code.system === SNOMED_SYSTEM);
+    const siteCoding = (_6 = (_5 = dosage.site) === null || _5 === void 0 ? void 0 : _5.coding) === null || _6 === void 0 ? void 0 : _6.find((code) => code.system === SNOMED_SYSTEM);
     if (siteCoding === null || siteCoding === void 0 ? void 0 : siteCoding.code) {
         internal.siteCoding = {
             code: siteCoding.code,
@@ -203,7 +210,7 @@ function internalFromFhir(dosage) {
             system: siteCoding.system
         };
     }
-    const reasonCoding = (_7 = (_6 = (_5 = dosage.asNeededFor) === null || _5 === void 0 ? void 0 : _5[0]) === null || _6 === void 0 ? void 0 : _6.coding) === null || _7 === void 0 ? void 0 : _7[0];
+    const reasonCoding = (_9 = (_8 = (_7 = dosage.asNeededFor) === null || _7 === void 0 ? void 0 : _7[0]) === null || _8 === void 0 ? void 0 : _8.coding) === null || _9 === void 0 ? void 0 : _9[0];
     if (reasonCoding === null || reasonCoding === void 0 ? void 0 : reasonCoding.code) {
         internal.asNeededReasonCoding = {
             code: reasonCoding.code,
@@ -211,7 +218,7 @@ function internalFromFhir(dosage) {
             system: reasonCoding.system
         };
     }
-    if ((_8 = dosage.additionalInstruction) === null || _8 === void 0 ? void 0 : _8.length) {
+    if ((_10 = dosage.additionalInstruction) === null || _10 === void 0 ? void 0 : _10.length) {
         internal.additionalInstructions = dosage.additionalInstruction.map((concept) => {
             var _a;
             return ({
@@ -226,13 +233,13 @@ function internalFromFhir(dosage) {
             });
         });
     }
-    const doseAndRate = (_9 = dosage.doseAndRate) === null || _9 === void 0 ? void 0 : _9[0];
+    const doseAndRate = (_11 = dosage.doseAndRate) === null || _11 === void 0 ? void 0 : _11[0];
     if (doseAndRate === null || doseAndRate === void 0 ? void 0 : doseAndRate.doseRange) {
         const { low, high } = doseAndRate.doseRange;
         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 = (_11 = (_10 = low === null || low === void 0 ? void 0 : low.unit) !== null && _10 !== void 0 ? _10 : high === null || high === void 0 ? void 0 : high.unit) !== null && _11 !== void 0 ? _11 : internal.unit;
+        internal.unit = (_13 = (_12 = low === null || low === void 0 ? void 0 : low.unit) !== null && _12 !== void 0 ? _12 : high === null || high === void 0 ? void 0 : high.unit) !== null && _13 !== void 0 ? _13 : internal.unit;
     }
     else if (doseAndRate === null || doseAndRate === void 0 ? void 0 : doseAndRate.doseQuantity) {
         const dose = doseAndRate.doseQuantity;

package/dist/format.js

@@ -515,6 +515,7 @@ function formatInternal(internal, style, localization) {
     return defaults[style];
 }
 function formatShort(internal) {
+    var _a;
     const parts = [];
     const dosePart = formatDoseShort(internal);
     if (dosePart) {
@@ -561,6 +562,9 @@ function formatShort(internal) {
             .map((d) => d.charAt(0).toUpperCase() + d.slice(1, 3))
             .join(","));
     }
+    if ((_a = internal.timeOfDay) === null || _a === void 0 ? void 0 : _a.length) {
+        parts.push(internal.timeOfDay.map(t => t.slice(0, 5)).join(","));
+    }
     if (internal.count !== undefined) {
         parts.push(`x${stripTrailingZero(internal.count)}`);
     }
@@ -575,13 +579,24 @@ function formatShort(internal) {
     return parts.filter(Boolean).join(" ");
 }
 function formatLong(internal) {
-    var _a;
+    var _a, _b;
     const grammar = resolveRouteGrammar(internal);
     const dosePart = (_a = formatDoseLong(internal)) !== null && _a !== void 0 ? _a : "the medication";
     const sitePart = formatSite(internal, grammar);
     const routePart = buildRoutePhrase(internal, grammar, Boolean(sitePart));
     const frequencyPart = describeFrequency(internal);
     const eventParts = collectWhenPhrases(internal);
+    if ((_b = internal.timeOfDay) === null || _b === void 0 ? void 0 : _b.length) {
+        for (const time of internal.timeOfDay) {
+            const parts = time.split(":");
+            const h = parseInt(parts[0], 10);
+            const m = parseInt(parts[1], 10);
+            const isAm = h < 12;
+            const displayH = h % 12 || 12;
+            const displayM = m < 10 ? `0${m}` : `${m}`;
+            eventParts.push(`at ${displayH}:${displayM}${isAm ? " am" : " pm"}`);
+        }
+    }
     const timing = combineFrequencyAndEvents(frequencyPart, eventParts);
     const dayPart = describeDayOfWeek(internal);
     const countPart = internal.count

package/dist/index.d.ts

@@ -1,11 +1,13 @@
-import { FhirDosage, FormatOptions, ParseOptions, ParseResult } from "./types";
+import { FhirDosage, FormatOptions, LintResult, ParseOptions, ParseResult } from "./types";
 export { parseInternal } from "./parser";
 export { suggestSig } from "./suggest";
 export * from "./types";
-export { nextDueDoses } from "./schedule";
+export { nextDueDoses, calculateTotalUnits } from "./schedule";
+export { parseStrength, parseStrengthIntoRatio } from "./utils/strength";
 export { getRegisteredSigLocalizations, registerSigLocalization, resolveSigLocalization, resolveSigTranslation } from "./i18n";
 export type { SigLocalization, SigLocalizationConfig, SigTranslation, SigTranslationConfig } from "./i18n";
 export declare function parseSig(input: string, options?: ParseOptions): ParseResult;
+export declare function lintSig(input: string, options?: ParseOptions): LintResult;
 export declare function parseSigAsync(input: string, options?: ParseOptions): Promise<ParseResult>;
 export declare function formatSig(dosage: FhirDosage, style?: "short" | "long", options?: FormatOptions): string;
 export declare function fromFhirDosage(dosage: FhirDosage, options?: FormatOptions): ParseResult;

package/dist/index.js

@@ -23,8 +23,9 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.resolveSigTranslation = exports.resolveSigLocalization = exports.registerSigLocalization = exports.getRegisteredSigLocalizations = exports.nextDueDoses = exports.suggestSig = exports.parseInternal = void 0;
+exports.resolveSigTranslation = exports.resolveSigLocalization = exports.registerSigLocalization = exports.getRegisteredSigLocalizations = exports.parseStrengthIntoRatio = exports.parseStrength = exports.calculateTotalUnits = exports.nextDueDoses = exports.suggestSig = exports.parseInternal = void 0;
 exports.parseSig = parseSig;
+exports.lintSig = lintSig;
 exports.parseSigAsync = parseSigAsync;
 exports.formatSig = formatSig;
 exports.fromFhirDosage = fromFhirDosage;
@@ -39,6 +40,10 @@ Object.defineProperty(exports, "suggestSig", { enumerable: true, get: function (
 __exportStar(require("./types"), exports);
 var schedule_1 = require("./schedule");
 Object.defineProperty(exports, "nextDueDoses", { enumerable: true, get: function () { return schedule_1.nextDueDoses; } });
+Object.defineProperty(exports, "calculateTotalUnits", { enumerable: true, get: function () { return schedule_1.calculateTotalUnits; } });
+var strength_1 = require("./utils/strength");
+Object.defineProperty(exports, "parseStrength", { enumerable: true, get: function () { return strength_1.parseStrength; } });
+Object.defineProperty(exports, "parseStrengthIntoRatio", { enumerable: true, get: function () { return strength_1.parseStrengthIntoRatio; } });
 var i18n_2 = require("./i18n");
 Object.defineProperty(exports, "getRegisteredSigLocalizations", { enumerable: true, get: function () { return i18n_2.getRegisteredSigLocalizations; } });
 Object.defineProperty(exports, "registerSigLocalization", { enumerable: true, get: function () { return i18n_2.registerSigLocalization; } });
@@ -50,6 +55,25 @@ function parseSig(input, options) {
     (0, parser_1.applySiteCoding)(internal, options);
     return buildParseResult(internal, options);
 }
+function lintSig(input, options) {
+    const internal = (0, parser_1.parseInternal)(input, options);
+    (0, parser_1.applyPrnReasonCoding)(internal, options);
+    (0, parser_1.applySiteCoding)(internal, options);
+    const result = buildParseResult(internal, options);
+    const groups = (0, parser_1.findUnparsedTokenGroups)(internal);
+    const issues = groups.map((group) => {
+        const text = group.range
+            ? internal.input.slice(group.range.start, group.range.end)
+            : group.tokens.map((token) => token.original).join(" ");
+        return {
+            message: "Unrecognized text",
+            text: text.trim() || text,
+            tokens: group.tokens.map((token) => token.original),
+            range: group.range
+        };
+    });
+    return { result, issues };
+}
 function parseSigAsync(input, options) {
     return __awaiter(this, void 0, void 0, function* () {
         const internal = (0, parser_1.parseInternal)(input, options);

package/dist/internal-types.d.ts

@@ -32,6 +32,7 @@ export interface ParsedSigInternal {
     periodUnit?: FhirPeriodUnit;
     dayOfWeek: FhirDayOfWeek[];
     when: EventTiming[];
+    timeOfDay?: string[];
     timingCode?: string;
     asNeeded?: boolean;
     asNeededReason?: string;

package/dist/parser.d.ts

@@ -1,6 +1,10 @@
 import { ParsedSigInternal, Token } from "./internal-types";
-import { ParseOptions } from "./types";
+import { ParseOptions, TextRange } from "./types";
 export declare function tokenize(input: string): Token[];
+export declare function findUnparsedTokenGroups(internal: ParsedSigInternal): Array<{
+    tokens: Token[];
+    range?: TextRange;
+}>;
 export declare function parseInternal(input: string, options?: ParseOptions): ParsedSigInternal;
 /**
  * Resolves parsed site text against SNOMED dictionaries and synchronous

package/dist/parser.js

@@ -10,6 +10,7 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.tokenize = tokenize;
+exports.findUnparsedTokenGroups = findUnparsedTokenGroups;
 exports.parseInternal = parseInternal;
 exports.applyPrnReasonCoding = applyPrnReasonCoding;
 exports.applyPrnReasonCodingAsync = applyPrnReasonCodingAsync;
@@ -748,6 +749,114 @@ function tryParseCountBasedFrequency(internal, tokens, index, options) {
     }
     return consumeCurrentToken;
 }
+function parseTimeToFhir(timeStr) {
+    const clean = timeStr.toLowerCase().trim();
+    // Match 9:00, 9.00, 9:00am, 9pm, 9 am, 9
+    const match = clean.match(/^(\d{1,2})[:.](\d{2})\s*(am|pm)?$/) ||
+        clean.match(/^(\d{1,2})\s*(am|pm)$/) ||
+        clean.match(/^(\d{1,2})$/);
+    if (!match)
+        return undefined;
+    let hour = parseInt(match[1], 10);
+    let minute = 0;
+    let ampm;
+    if (match[2] && !isNaN(parseInt(match[2], 10))) {
+        minute = parseInt(match[2], 10);
+        ampm = match[3];
+    }
+    else {
+        ampm = match[2];
+    }
+    if (ampm === "pm" && hour < 12)
+        hour += 12;
+    if (ampm === "am" && hour === 12)
+        hour = 0;
+    if (hour < 0 || hour > 23 || minute < 0 || minute > 59)
+        return undefined;
+    const h = hour < 10 ? `0${hour}` : `${hour}`;
+    const m = minute < 10 ? `0${minute}` : `${minute}`;
+    return `${h}:${m}:00`;
+}
+function tryParseTimeBasedSchedule(internal, tokens, index) {
+    const token = tokens[index];
+    if (internal.consumed.has(token.index))
+        return false;
+    const isAtPrefix = token.lower === "@" || token.lower === "at";
+    if (!isAtPrefix && !/^\d/.test(token.lower))
+        return false;
+    let nextIndex = isAtPrefix ? index + 1 : index;
+    const times = [];
+    const consumedIndices = [];
+    const timeTokens = [];
+    if (isAtPrefix)
+        consumedIndices.push(index);
+    while (nextIndex < tokens.length) {
+        const nextToken = tokens[nextIndex];
+        if (!nextToken || internal.consumed.has(nextToken.index))
+            break;
+        let timeStr = nextToken.lower;
+        let lookaheadIndices = [];
+        // Look ahead for am/pm if current token is just a number or doesn't have am/pm
+        if (!timeStr.includes("am") && !timeStr.includes("pm")) {
+            const nextNext = tokens[nextIndex + 1];
+            if (nextNext && !internal.consumed.has(nextNext.index) && (nextNext.lower === "am" || nextNext.lower === "pm")) {
+                timeStr += nextNext.lower;
+                lookaheadIndices.push(nextIndex + 1);
+            }
+        }
+        const time = parseTimeToFhir(timeStr);
+        if (time) {
+            times.push(time);
+            timeTokens.push(timeStr);
+            consumedIndices.push(nextIndex);
+            for (const idx of lookaheadIndices) {
+                consumedIndices.push(idx);
+            }
+            nextIndex += 1 + lookaheadIndices.length;
+            // Support comma or space separated times
+            const separatorToken = tokens[nextIndex];
+            // Check if there is another time after the separator
+            if (separatorToken && (separatorToken.lower === "," || separatorToken.lower === "and")) {
+                // Peek for next time
+                let peekIndex = nextIndex + 1;
+                let peekToken = tokens[peekIndex];
+                if (peekToken) {
+                    let peekStr = peekToken.lower;
+                    let peekNext = tokens[peekIndex + 1];
+                    if (peekNext && !internal.consumed.has(peekNext.index) && (peekNext.lower === "am" || peekNext.lower === "pm")) {
+                        peekStr += peekNext.lower;
+                    }
+                    if (parseTimeToFhir(peekStr)) {
+                        consumedIndices.push(nextIndex);
+                        nextIndex++;
+                        continue;
+                    }
+                }
+            }
+            continue;
+        }
+        break;
+    }
+    if (times.length > 0) {
+        if (!isAtPrefix) {
+            const hasClearTimeFormat = timeTokens.some((t) => t.includes(":") || t.includes("am") || t.includes("pm"));
+            if (!hasClearTimeFormat) {
+                return false;
+            }
+        }
+        internal.timeOfDay = internal.timeOfDay || [];
+        for (const time of times) {
+            if (!(0, array_1.arrayIncludes)(internal.timeOfDay, time)) {
+                internal.timeOfDay.push(time);
+            }
+        }
+        for (const idx of consumedIndices) {
+            mark(internal.consumed, tokens[idx]);
+        }
+        return true;
+    }
+    return false;
+}
 const SITE_UNIT_ROUTE_HINTS = [
     { pattern: /\beye(s)?\b/i, route: types_1.RouteCode["Ophthalmic route"] },
     { pattern: /\beyelid(s)?\b/i, route: types_1.RouteCode["Ophthalmic route"] },
@@ -885,6 +994,68 @@ function refineSiteRange(input, sanitized, tokenRange) {
     }
     return { start: startIndex, end: startIndex + lowerSanitized.length };
 }
+function findUnparsedTokenGroups(internal) {
+    const leftoverTokens = internal.tokens
+        .filter((token) => !internal.consumed.has(token.index))
+        .sort((a, b) => a.index - b.index);
+    if (leftoverTokens.length === 0) {
+        return [];
+    }
+    const groups = [];
+    let currentGroup = [];
+    let previousIndex;
+    let minimumStart = 0;
+    const locateRange = (tokensToLocate, initial) => {
+        const lowerInput = internal.input.toLowerCase();
+        let searchStart = minimumStart;
+        let rangeStart;
+        let rangeEnd;
+        for (const token of tokensToLocate) {
+            const segment = token.original.trim();
+            if (!segment) {
+                continue;
+            }
+            const lowerSegment = segment.toLowerCase();
+            const foundIndex = lowerInput.indexOf(lowerSegment, searchStart);
+            if (foundIndex === -1) {
+                return initial;
+            }
+            if (rangeStart === undefined) {
+                rangeStart = foundIndex;
+            }
+            const segmentEnd = foundIndex + lowerSegment.length;
+            rangeEnd = rangeEnd === undefined ? segmentEnd : Math.max(rangeEnd, segmentEnd);
+            searchStart = segmentEnd;
+        }
+        if (rangeStart === undefined || rangeEnd === undefined) {
+            return initial;
+        }
+        return { start: rangeStart, end: rangeEnd };
+    };
+    const flush = () => {
+        if (!currentGroup.length) {
+            return;
+        }
+        const indices = currentGroup.map((token) => token.index);
+        const initialRange = computeTokenRange(internal.input, internal.tokens, indices);
+        const range = locateRange(currentGroup, initialRange);
+        groups.push({ tokens: currentGroup, range });
+        if (range) {
+            minimumStart = Math.max(minimumStart, range.end);
+        }
+        currentGroup = [];
+        previousIndex = undefined;
+    };
+    for (const token of leftoverTokens) {
+        if (previousIndex !== undefined && token.index !== previousIndex + 1) {
+            flush();
+        }
+        currentGroup.push(token);
+        previousIndex = token.index;
+    }
+    flush();
+    return groups;
+}
 function splitToken(token) {
     if (/^[0-9]+(?:\.[0-9]+)?$/.test(token)) {
         return [token];
@@ -1322,7 +1493,8 @@ function applyWhenToken(internal, token, code) {
     addWhen(internal.when, code);
     mark(internal.consumed, token);
 }
-function parseMealContext(internal, tokens, index, code) {
+function parseAnchorSequence(internal, tokens, index, prefixCode) {
+    var _a;
     const token = tokens[index];
     let converted = 0;
     for (let lookahead = index + 1; lookahead < tokens.length; lookahead++) {
@@ -1330,30 +1502,57 @@ function parseMealContext(internal, tokens, index, code) {
         if (internal.consumed.has(nextToken.index)) {
             continue;
         }
-        if (MEAL_CONTEXT_CONNECTORS.has(nextToken.lower)) {
+        const lower = nextToken.lower;
+        if (MEAL_CONTEXT_CONNECTORS.has(lower) || lower === ",") {
             mark(internal.consumed, nextToken);
             continue;
         }
-        const meal = maps_1.MEAL_KEYWORDS[nextToken.lower];
-        if (!meal) {
-            break;
+        const day = maps_1.DAY_OF_WEEK_TOKENS[lower];
+        if (day) {
+            if (!(0, array_1.arrayIncludes)(internal.dayOfWeek, day)) {
+                internal.dayOfWeek.push(day);
+            }
+            mark(internal.consumed, nextToken);
+            converted++;
+            continue;
         }
-        const whenCode = code === types_1.EventTiming["After Meal"]
-            ? meal.pc
-            : code === types_1.EventTiming["Before Meal"]
-                ? meal.ac
-                : code;
-        addWhen(internal.when, whenCode);
-        mark(internal.consumed, nextToken);
-        converted++;
+        const meal = maps_1.MEAL_KEYWORDS[lower];
+        if (meal) {
+            const whenCode = prefixCode === types_1.EventTiming["After Meal"]
+                ? meal.pc
+                : prefixCode === types_1.EventTiming["Before Meal"]
+                    ? meal.ac
+                    : ((_a = maps_1.EVENT_TIMING_TOKENS[lower]) !== null && _a !== void 0 ? _a : meal.pc); // fallback to general or conservative default
+            addWhen(internal.when, whenCode);
+            mark(internal.consumed, nextToken);
+            converted++;
+            continue;
+        }
+        const whenCode = maps_1.EVENT_TIMING_TOKENS[lower];
+        if (whenCode) {
+            if (prefixCode && !meal) {
+                // if we have pc/ac, we only want to follow it with explicit meals
+                // to avoid over-consuming anchors that should be separate (like 'pc hs')
+                break;
+            }
+            addWhen(internal.when, whenCode);
+            mark(internal.consumed, nextToken);
+            converted++;
+            continue;
+        }
+        break;
     }
     if (converted > 0) {
         mark(internal.consumed, token);
-        return;
+        return true;
     }
-    applyWhenToken(internal, token, code);
+    if (prefixCode) {
+        applyWhenToken(internal, token, prefixCode);
+        return true;
+    }
+    return false;
 }
-function parseSeparatedQ(internal, tokens, index, options) {
+function parseSeparatedInterval(internal, tokens, index, options) {
     const token = tokens[index];
     const next = tokens[index + 1];
     if (!next || internal.consumed.has(next.index)) {
@@ -1673,11 +1872,14 @@ function parseInternal(input, options) {
             applyWhenToken(internal, token, types_1.EventTiming.Meal);
             continue;
         }
-        if (token.lower === "q") {
-            if (parseSeparatedQ(internal, tokens, i, options)) {
+        if (token.lower === "q" || token.lower === "every" || token.lower === "each") {
+            if (parseSeparatedInterval(internal, tokens, i, options)) {
                 continue;
             }
         }
+        if (tryParseTimeBasedSchedule(internal, tokens, i)) {
+            continue;
+        }
         if (tryParseNumericCadence(internal, tokens, i)) {
             continue;
         }
@@ -1705,12 +1907,22 @@ function parseInternal(input, options) {
             continue;
         }
         // Event timing tokens
-        if (token.lower === "pc" || token.lower === "ac") {
-            parseMealContext(internal, tokens, i, token.lower === "pc"
+        if (token.lower === "pc" || token.lower === "ac" || token.lower === "after" || token.lower === "before") {
+            parseAnchorSequence(internal, tokens, i, (token.lower === "pc" || token.lower === "after")
                 ? types_1.EventTiming["After Meal"]
                 : types_1.EventTiming["Before Meal"]);
             continue;
         }
+        if (token.lower === "at" || token.lower === "@" || token.lower === "on") {
+            if (parseAnchorSequence(internal, tokens, i)) {
+                continue;
+            }
+            if (tryParseTimeBasedSchedule(internal, tokens, i)) {
+                continue;
+            }
+            mark(internal.consumed, token);
+            continue;
+        }
         const nextToken = tokens[i + 1];
         if (nextToken && !internal.consumed.has(nextToken.index)) {
             const combo = `${token.lower} ${nextToken.lower}`;

package/dist/schedule.d.ts

@@ -1,6 +1,7 @@
-import { FhirDosage, NextDueDoseOptions } from "./types";
+import { FhirDosage, NextDueDoseOptions, TotalUnitsOptions, TotalUnitsResult } from "./types";
 /**
  * Produces the next dose timestamps in ascending order according to the
  * provided configuration and dosage metadata.
  */
 export declare function nextDueDoses(dosage: FhirDosage, options: NextDueDoseOptions): string[];
+export declare function calculateTotalUnits(options: TotalUnitsOptions): TotalUnitsResult;

package/dist/schedule.js

@@ -1,8 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.nextDueDoses = nextDueDoses;
+exports.calculateTotalUnits = calculateTotalUnits;
 const types_1 = require("./types");
 const array_1 = require("./utils/array");
+const units_1 = require("./utils/units");
+const strength_1 = require("./utils/strength");
 /**
  * Default institution times used when a dosage only specifies frequency without
  * explicit EventTiming anchors. Clinics can override these through the
@@ -228,8 +231,12 @@ function makeZonedDate(timeZone, year, month, day, hour, minute, second) {
 }
 /** Convenience wrapper around makeZonedDate for day-level math. */
 function makeZonedDateFromDay(base, timeZone, clock) {
+    var _a, _b, _c;
     const { year, month, day } = getTimeParts(base, timeZone);
-    const [hour, minute, second] = clock.split(":").map((value) => Number(value));
+    const parts = clock.split(":").map((value) => Number(value));
+    const hour = (_a = parts[0]) !== null && _a !== void 0 ? _a : 0;
+    const minute = (_b = parts[1]) !== null && _b !== void 0 ? _b : 0;
+    const second = (_c = parts[2]) !== null && _c !== void 0 ? _c : 0;
     return makeZonedDate(timeZone, year, month, day, hour, minute, second);
 }
 /** Returns a Date pinned to the start of the local day. */
@@ -244,7 +251,8 @@ function startOfLocalDay(date, timeZone) {
 /** Adds a number of calendar days while remaining aligned to the time zone. */
 function addLocalDays(date, days, timeZone) {
     const { year, month, day } = getTimeParts(date, timeZone);
-    const zoned = makeZonedDate(timeZone, year, month, day + days, 0, 0, 0);
+    const rollover = new Date(Date.UTC(year, month - 1, day + days));
+    const zoned = makeZonedDate(timeZone, rollover.getUTCFullYear(), rollover.getUTCMonth() + 1, rollover.getUTCDate(), 0, 0, 0);
     if (!zoned) {
         throw new Error("Unable to shift local day – invalid calendar combination");
     }
@@ -895,3 +903,202 @@ function addCalendarMonths(date, months, timeZone) {
     }
     return final;
 }
+/**
+ * Internal helper to count dose events within a time range.
+ */
+function countScheduleEvents(dosage, from, to, config, baseTime, orderedAt, limit) {
+    var _a, _b, _c;
+    const timing = dosage.timing;
+    const repeat = timing === null || timing === void 0 ? void 0 : timing.repeat;
+    if (!timing || !repeat)
+        return 0;
+    const dayFilter = new Set(((_a = repeat.dayOfWeek) !== null && _a !== void 0 ? _a : []).map((day) => day.toLowerCase()));
+    const enforceDayFilter = dayFilter.size > 0;
+    const seen = new Set();
+    let count = 0;
+    const timeZone = config.timeZone;
+    const recordCandidate = (candidate) => {
+        if (!candidate)
+            return false;
+        if (candidate < from || candidate >= to)
+            return false;
+        const iso = formatZonedIso(candidate, timeZone);
+        if (seen.has(iso))
+            return false;
+        seen.add(iso);
+        count += 1;
+        return true;
+    };
+    const whenCodes = (_b = repeat.when) !== null && _b !== void 0 ? _b : [];
+    const timeOfDayEntries = (_c = repeat.timeOfDay) !== null && _c !== void 0 ? _c : [];
+    if (whenCodes.length > 0 || timeOfDayEntries.length > 0) {
+        const expanded = expandWhenCodes(whenCodes, config, repeat);
+        if (timeOfDayEntries.length > 0) {
+            for (const clock of timeOfDayEntries) {
+                expanded.push({ time: normalizeClock(clock), dayShift: 0 });
+            }
+            expanded.sort((a, b) => {
+                if (a.dayShift !== b.dayShift)
+                    return a.dayShift - b.dayShift;
+                return a.time.localeCompare(b.time);
+            });
+        }
+        if ((0, array_1.arrayIncludes)(whenCodes, types_1.EventTiming.Immediate)) {
+            const immediateSource = orderedAt !== null && orderedAt !== void 0 ? orderedAt : from;
+            if (!orderedAt || orderedAt >= from) {
+                recordCandidate(immediateSource);
+            }
+        }
+        if (expanded.length === 0)
+            return count;
+        let currentDay = startOfLocalDay(from, timeZone);
+        let iterations = 0;
+        const maxIterations = limit !== undefined ? limit * 31 : 365 * 31;
+        while (count < (limit !== null && limit !== void 0 ? limit : Infinity) && currentDay < to && iterations < maxIterations) {
+            const weekday = getLocalWeekday(currentDay, timeZone);
+            if (!enforceDayFilter || dayFilter.has(weekday)) {
+                for (const entry of expanded) {
+                    const targetDay = entry.dayShift === 0
+                        ? currentDay
+                        : addLocalDays(currentDay, entry.dayShift, timeZone);
+                    const zoned = makeZonedDateFromDay(targetDay, timeZone, entry.time);
+                    if (zoned)
+                        recordCandidate(zoned);
+                }
+            }
+            currentDay = addLocalDays(currentDay, 1, timeZone);
+            iterations += 1;
+        }
+        return count;
+    }
+    const treatAsInterval = !!repeat.period &&
+        !!repeat.periodUnit &&
+        (!repeat.frequency ||
+            repeat.periodUnit !== "d" ||
+            (repeat.frequency === 1 && repeat.period > 1)) &&
+        !enforceDayFilter;
+    if (treatAsInterval) {
+        const increment = createIntervalStepper(repeat, timeZone);
+        if (!increment)
+            return count;
+        let current = baseTime;
+        let guard = 0;
+        const maxIterations = limit !== undefined ? limit * 1000 : 10000;
+        // Advance to "from"
+        while (current < from && guard < maxIterations) {
+            const next = increment(current);
+            if (!next || next.getTime() === current.getTime())
+                break;
+            current = next;
+            guard++;
+        }
+        while (current < to && count < (limit !== null && limit !== void 0 ? limit : Infinity) && guard < maxIterations) {
+            const weekday = getLocalWeekday(current, timeZone);
+            if (!enforceDayFilter || dayFilter.has(weekday)) {
+                recordCandidate(current);
+            }
+            const next = increment(current);
+            if (!next || next.getTime() === current.getTime())
+                break;
+            current = next;
+            guard += 1;
+        }
+        return count;
+    }
+    if (repeat.frequency && repeat.period && repeat.periodUnit) {
+        const clocks = resolveFrequencyClocks(timing, config);
+        if (clocks.length === 0)
+            return count;
+        let currentDay = startOfLocalDay(from, timeZone);
+        let iterations = 0;
+        const maxIterations = limit !== undefined ? limit * 31 : 365 * 31;
+        while (count < (limit !== null && limit !== void 0 ? limit : Infinity) && currentDay < to && iterations < maxIterations) {
+            const weekday = getLocalWeekday(currentDay, timeZone);
+            if (!enforceDayFilter || dayFilter.has(weekday)) {
+                for (const clock of clocks) {
+                    const zoned = makeZonedDateFromDay(currentDay, timeZone, clock);
+                    if (zoned)
+                        recordCandidate(zoned);
+                }
+            }
+            currentDay = addLocalDays(currentDay, 1, timeZone);
+            iterations += 1;
+        }
+    }
+    // Fallback for dayOfWeek with period/periodUnit but no explicit frequency/clocks
+    if (enforceDayFilter && repeat.period && repeat.periodUnit) {
+        const clocks = ["08:00:00"]; // Default to morning if no times specified
+        let currentDayIter = startOfLocalDay(from, timeZone);
+        let iter = 0;
+        const maxIter = limit !== undefined ? limit * 31 : 365 * 31;
+        while (count < (limit !== null && limit !== void 0 ? limit : Infinity) && currentDayIter < to && iter < maxIter) {
+            const weekday = getLocalWeekday(currentDayIter, timeZone);
+            if (dayFilter.has(weekday)) {
+                for (const clock of clocks) {
+                    const zoned = makeZonedDateFromDay(currentDayIter, timeZone, clock);
+                    if (zoned)
+                        recordCandidate(zoned);
+                }
+            }
+            currentDayIter = addLocalDays(currentDayIter, 1, timeZone);
+            iter += 1;
+        }
+        return count;
+    }
+    return count;
+}
+function calculateTotalUnits(options) {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m;
+    const { dosage, durationValue, durationUnit, roundToMultiple, context } = options;
+    const from = coerceDate(options.from, "from");
+    const providedConfig = options.config;
+    const timeZone = (_a = options.timeZone) !== null && _a !== void 0 ? _a : providedConfig === null || providedConfig === void 0 ? void 0 : providedConfig.timeZone;
+    if (!timeZone) {
+        throw new Error("timeZone is required for calculateTotalUnits");
+    }
+    const eventClock = Object.assign(Object.assign({}, ((_b = providedConfig === null || providedConfig === void 0 ? void 0 : providedConfig.eventClock) !== null && _b !== void 0 ? _b : {})), ((_c = options.eventClock) !== null && _c !== void 0 ? _c : {}));
+    const mealOffsets = Object.assign(Object.assign({}, ((_d = providedConfig === null || providedConfig === void 0 ? void 0 : providedConfig.mealOffsets) !== null && _d !== void 0 ? _d : {})), ((_e = options.mealOffsets) !== null && _e !== void 0 ? _e : {}));
+    const frequencyDefaults = mergeFrequencyDefaults(providedConfig === null || providedConfig === void 0 ? void 0 : providedConfig.frequencyDefaults, options.frequencyDefaults);
+    const config = {
+        timeZone,
+        eventClock,
+        mealOffsets,
+        frequencyDefaults
+    };
+    // Calculate end date based on duration
+    let endDay;
+    const dummyRepeat = { period: durationValue, periodUnit: durationUnit };
+    const stepper = createIntervalStepper(dummyRepeat, timeZone);
+    if (stepper) {
+        endDay = stepper(from) || from;
+    }
+    else {
+        endDay = from;
+    }
+    const count = countScheduleEvents(dosage, from, endDay, config, options.orderedAt ? coerceDate(options.orderedAt, "orderedAt") : from, options.orderedAt ? coerceDate(options.orderedAt, "orderedAt") : null, 2000);
+    const doseQuantity = (_j = (_h = (_g = (_f = dosage.doseAndRate) === null || _f === void 0 ? void 0 : _f[0]) === null || _g === void 0 ? void 0 : _g.doseQuantity) === null || _h === void 0 ? void 0 : _h.value) !== null && _j !== void 0 ? _j : 0;
+    let totalUnits = count * doseQuantity;
+    if (roundToMultiple && roundToMultiple > 0) {
+        totalUnits = Math.ceil(totalUnits / roundToMultiple) * roundToMultiple;
+    }
+    const result = { totalUnits };
+    // Handle containers
+    const containerValue = context === null || context === void 0 ? void 0 : context.containerValue;
+    const containerUnit = context === null || context === void 0 ? void 0 : context.containerUnit;
+    const doseUnit = (_m = (_l = (_k = dosage.doseAndRate) === null || _k === void 0 ? void 0 : _k[0]) === null || _l === void 0 ? void 0 : _l.doseQuantity) === null || _m === void 0 ? void 0 : _m.unit;
+    if (containerValue && containerValue > 0) {
+        let effectiveUnits = totalUnits;
+        if (containerUnit && doseUnit && containerUnit !== doseUnit) {
+            let strength = context === null || context === void 0 ? void 0 : context.strengthRatio;
+            if (!strength && (context === null || context === void 0 ? void 0 : context.strength)) {
+                strength = (0, strength_1.parseStrengthIntoRatio)(context.strength, context) || undefined;
+            }
+            const converted = (0, units_1.convertValue)(totalUnits, doseUnit, containerUnit, strength);
+            if (converted !== null) {
+                effectiveUnits = converted;
+            }
+        }
+        result.totalContainers = Math.ceil(effectiveUnits / containerValue);
+    }
+    return result;
+}

package/dist/types.d.ts

@@ -279,6 +279,12 @@ export type RouteCode = SNOMEDCTRouteCodes;
 export declare const RouteCode: typeof SNOMEDCTRouteCodes;
 export interface MedicationContext {
     dosageForm?: string;
+    /** "Simple" strength string; might be the only way strength is provided
+     * for discrete units this is the amount of medication for unit e.g. "500 mg" (1 tablet), or for mixed tablets might be like "400 mg + 80 mg"
+     * for things like creams or fluids or syrupsit might be "2%", 5 g/100g, 100mg/ 100 g, 262 mg/15 mL, 200 mg/2 mL, 1 mg/dL, or "400 mg/5mL + 80 mg/5mL"
+     * In the "x + y" case, the strengthQuantity/strengthRatio will be the sum of the two ingredients.
+     */
+    strength?: string;
     strengthQuantity?: FhirQuantity;
     strengthRatio?: FhirRatio;
     strengthCodeableConcept?: FhirCodeableConcept;
@@ -527,6 +533,22 @@ export interface ParseResult {
         }>;
     };
 }
+export interface LintIssue {
+    /** Human-readable description of why the segment could not be parsed. */
+    message: string;
+    /** Original substring that triggered the issue. */
+    text: string;
+    /** Tokens contributing to the unparsed segment. */
+    tokens: string[];
+    /** Location of {@link text} relative to the caller's original input. */
+    range?: TextRange;
+}
+export interface LintResult {
+    /** Standard parse output including FHIR representation and metadata. */
+    result: ParseResult;
+    /** Segments of the input that could not be interpreted. */
+    issues: LintIssue[];
+}
 /**
  * Maps EventTiming codes (or other institution-specific timing strings) to
  * 24-hour clock representations such as "08:00".
@@ -568,3 +590,14 @@ export interface NextDueDoseOptions {
     frequencyDefaults?: FrequencyFallbackTimes;
     config?: NextDueDoseConfig;
 }
+export interface TotalUnitsResult {
+    totalUnits: number;
+    totalContainers?: number;
+}
+export interface TotalUnitsOptions extends NextDueDoseOptions {
+    dosage: FhirDosage;
+    durationValue: number;
+    durationUnit: FhirPeriodUnit;
+    roundToMultiple?: number;
+    context?: MedicationContext;
+}

package/dist/utils/strength.d.ts

@@ -0,0 +1,12 @@
+import { FhirRatio, FhirQuantity, MedicationContext } from "../types";
+/**
+ * High-level strength parser that returns the most appropriate FHIR representation.
+ */
+export declare function parseStrength(strength: string, context?: MedicationContext): {
+    strengthQuantity?: FhirQuantity;
+    strengthRatio?: FhirRatio;
+};
+/**
+ * Internal helper to parse a strength string into a FHIR Ratio.
+ */
+export declare function parseStrengthIntoRatio(strength: string, context?: MedicationContext): FhirRatio | null;

package/dist/utils/strength.js

@@ -0,0 +1,149 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseStrength = parseStrength;
+exports.parseStrengthIntoRatio = parseStrengthIntoRatio;
+const units_1 = require("./units");
+const maps_1 = require("../maps");
+const array_1 = require("./array");
+/**
+ * High-level strength parser that returns the most appropriate FHIR representation.
+ */
+function parseStrength(strength, context) {
+    var _a, _b, _c;
+    const ratio = parseStrengthIntoRatio(strength, context);
+    if (!ratio)
+        return {};
+    if (((_a = ratio.denominator) === null || _a === void 0 ? void 0 : _a.value) === 1 && (((_b = ratio.denominator) === null || _b === void 0 ? void 0 : _b.unit) === "unit" || !((_c = ratio.denominator) === null || _c === void 0 ? void 0 : _c.unit))) {
+        return { strengthQuantity: ratio.numerator };
+    }
+    return { strengthRatio: ratio };
+}
+/**
+ * Internal helper to parse a strength string into a FHIR Ratio.
+ */
+function parseStrengthIntoRatio(strength, context) {
+    var _a, _b, _c, _d, _e;
+    const parts = strength.split("+").map((p) => p.trim());
+    let totalMgPerMlOrG = 0;
+    let hasVolume = false;
+    let hasWeightDenominator = false;
+    let targetNumUnit;
+    let targetDenUnit;
+    let targetDenValue;
+    for (const part of parts) {
+        const ratio = parseSingleStrengthPart(part, context);
+        if (!ratio || !((_a = ratio.numerator) === null || _a === void 0 ? void 0 : _a.value) || ratio.numerator.value === 0)
+            continue;
+        const nUnit = ratio.numerator.unit;
+        const dUnit = ((_b = ratio.denominator) === null || _b === void 0 ? void 0 : _b.unit) || "unit";
+        const dCat = (0, units_1.getUnitCategory)(dUnit);
+        // Save target units from the first part
+        if (!targetNumUnit)
+            targetNumUnit = nUnit;
+        if (!targetDenUnit)
+            targetDenUnit = dUnit;
+        if (targetDenValue === undefined)
+            targetDenValue = (_c = ratio.denominator) === null || _c === void 0 ? void 0 : _c.value;
+        const nValue = ratio.numerator.value;
+        const dValue = (_e = (_d = ratio.denominator) === null || _d === void 0 ? void 0 : _d.value) !== null && _e !== void 0 ? _e : 1;
+        const nFactor = (0, units_1.getBaseUnitFactor)(nUnit);
+        const dFactor = (dCat === "volume" || dCat === "mass") ? (0, units_1.getBaseUnitFactor)(dUnit) : 1;
+        totalMgPerMlOrG += (nValue * nFactor) / (dValue * dFactor);
+        if (dCat === "volume")
+            hasVolume = true;
+        if (dCat === "mass")
+            hasWeightDenominator = true;
+    }
+    if (totalMgPerMlOrG === 0)
+        return null;
+    const isComposite = parts.length > 1;
+    const resultNumUnit = isComposite ? "mg" : (targetNumUnit || "mg");
+    let resultDenUnit = targetDenUnit || "unit";
+    if (isComposite) {
+        if (hasVolume)
+            resultDenUnit = "mL";
+        else if (hasWeightDenominator)
+            resultDenUnit = "g";
+        else
+            resultDenUnit = "unit";
+    }
+    const resultDenValue = isComposite ? 1 : (targetDenValue !== null && targetDenValue !== void 0 ? targetDenValue : 1);
+    const denCat = (0, units_1.getUnitCategory)(resultDenUnit);
+    const dBaseFactor = (denCat === "volume" || denCat === "mass")
+        ? (0, units_1.getBaseUnitFactor)(resultDenUnit)
+        : 1;
+    const totalBaseDenominatorValue = resultDenValue * dBaseFactor;
+    const totalNumeratorMg = totalMgPerMlOrG * totalBaseDenominatorValue;
+    const finalNumValue = totalNumeratorMg / (0, units_1.getBaseUnitFactor)(resultNumUnit);
+    return {
+        numerator: { value: finalNumValue, unit: resultNumUnit },
+        denominator: { value: resultDenValue, unit: resultDenUnit }
+    };
+}
+function isSolidDosageForm(form) {
+    const normalized = form.toLowerCase().trim();
+    // 1. Get the default unit for this form
+    let unit = maps_1.DEFAULT_UNIT_BY_NORMALIZED_FORM[normalized];
+    if (!unit) {
+        const mapped = maps_1.KNOWN_DOSAGE_FORMS_TO_DOSE[normalized];
+        if (mapped) {
+            unit = maps_1.DEFAULT_UNIT_BY_NORMALIZED_FORM[mapped];
+        }
+    }
+    // 2. Identify if it's explicitly a liquid/gas unit
+    const liquidUnits = ["ml", "spray", "puff", "drop"];
+    if (unit) {
+        const u = unit.toLowerCase();
+        if ((0, array_1.arrayIncludes)(liquidUnits, u))
+            return false;
+        // Any other mapped unit (g, tab, cap, etc.) is considered solid for % purpose
+        return true;
+    }
+    // 3. Keyword-based heuristics as fallback
+    const solidKeywords = [
+        "tablet", "capsule", "patch", "cream", "ointment", "gel", "paste",
+        "suppositor", "powder", "lozenge", "patch", "stick", "implant",
+        "piece", "granule", "lozenge", "pessary"
+    ];
+    for (let i = 0; i < solidKeywords.length; i++) {
+        if (normalized.indexOf(solidKeywords[i]) !== -1)
+            return true;
+    }
+    return false;
+}
+function parseSingleStrengthPart(part, context) {
+    var _a, _b;
+    const p = part.trim();
+    // 1. Percentage
+    const percentMatch = p.match(/^(\d+(?:\.\d+)?)\s*%$/);
+    if (percentMatch) {
+        const isSolid = (context === null || context === void 0 ? void 0 : context.dosageForm) && isSolidDosageForm(context.dosageForm);
+        return {
+            numerator: { value: parseFloat(percentMatch[1]), unit: "g" },
+            denominator: { value: 100, unit: isSolid ? "g" : "mL" }
+        };
+    }
+    // 2. Ratio
+    const ratioMatch = p.match(/^(\d+(?:\.\d+)?)\s*([a-zA-Z0-9%]+)?\s*\/\s*(\d+(?:\.\d+)?)?\s*([a-zA-Z0-9%]+)$/);
+    if (ratioMatch) {
+        return {
+            numerator: {
+                value: parseFloat(ratioMatch[1]),
+                unit: ((_a = ratioMatch[2]) === null || _a === void 0 ? void 0 : _a.trim()) || "mg"
+            },
+            denominator: {
+                value: ratioMatch[3] ? parseFloat(ratioMatch[3]) : 1,
+                unit: (_b = ratioMatch[4]) === null || _b === void 0 ? void 0 : _b.trim()
+            }
+        };
+    }
+    // 3. Simple Quantity
+    const quantityMatch = p.match(/^(\d+(?:\.\d+)?)\s*([a-zA-Z0-9%]+)$/);
+    if (quantityMatch) {
+        return {
+            numerator: { value: parseFloat(quantityMatch[1]), unit: quantityMatch[2].trim() },
+            denominator: { value: 1, unit: "unit" }
+        };
+    }
+    return null;
+}

package/dist/utils/units.d.ts

@@ -0,0 +1,14 @@
+export declare const MASS_UNITS: Record<string, number>;
+export declare const VOLUME_UNITS: Record<string, number>;
+export declare function getUnitCategory(unit?: string): "mass" | "volume" | "other";
+export declare function getBaseUnitFactor(unit?: string): number;
+export declare function convertValue(value: number, fromUnit: string, toUnit: string, strength?: {
+    numerator: {
+        value: number;
+        unit: string;
+    };
+    denominator: {
+        value: number;
+        unit: string;
+    };
+}): number | null;

package/dist/utils/units.js

@@ -0,0 +1,82 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VOLUME_UNITS = exports.MASS_UNITS = void 0;
+exports.getUnitCategory = getUnitCategory;
+exports.getBaseUnitFactor = getBaseUnitFactor;
+exports.convertValue = convertValue;
+exports.MASS_UNITS = {
+    kg: 1000000,
+    g: 1000,
+    mg: 1,
+    mcg: 0.001,
+    ug: 0.001,
+    microg: 0.001,
+    ng: 0.000001
+};
+exports.VOLUME_UNITS = {
+    l: 1000,
+    dl: 100,
+    ml: 1,
+    ul: 0.001,
+    microl: 0.001,
+    cm3: 1,
+    tsp: 5,
+    tbsp: 15
+};
+function getUnitCategory(unit) {
+    if (!unit)
+        return "other";
+    const u = unit.toLowerCase();
+    if (exports.MASS_UNITS[u] !== undefined)
+        return "mass";
+    if (exports.VOLUME_UNITS[u] !== undefined)
+        return "volume";
+    return "other";
+}
+function getBaseUnitFactor(unit) {
+    var _a, _b;
+    if (!unit)
+        return 1;
+    const u = unit.toLowerCase();
+    return (_b = (_a = exports.MASS_UNITS[u]) !== null && _a !== void 0 ? _a : exports.VOLUME_UNITS[u]) !== null && _b !== void 0 ? _b : 1;
+}
+function convertValue(value, fromUnit, toUnit, strength) {
+    const f = fromUnit.toLowerCase();
+    const t = toUnit.toLowerCase();
+    if (f === t)
+        return value;
+    const fCat = getUnitCategory(f);
+    const tCat = getUnitCategory(t);
+    // 1. Same category conversion
+    if (fCat === tCat && fCat !== "other") {
+        const fFactor = getBaseUnitFactor(f);
+        const tFactor = getBaseUnitFactor(t);
+        return (value * fFactor) / tFactor;
+    }
+    // 2. Cross-category conversion using strength
+    if (strength && ((fCat === "mass" && tCat === "volume") || (fCat === "volume" && tCat === "mass"))) {
+        const numUnit = strength.numerator.unit.toLowerCase();
+        const denUnit = strength.denominator.unit.toLowerCase();
+        const numCat = getUnitCategory(numUnit);
+        const denCat = getUnitCategory(denUnit);
+        if (numCat !== denCat && numCat !== "other" && denCat !== "other") {
+            const massSide = numCat === "mass" ? strength.numerator : strength.denominator;
+            const volSide = numCat === "volume" ? strength.numerator : strength.denominator;
+            // Normalize bridge to base units (mg/mL)
+            const bridgeDensity = (massSide.value * getBaseUnitFactor(massSide.unit)) / (volSide.value * getBaseUnitFactor(volSide.unit));
+            if (fCat === "mass") {
+                // Mass to Volume: value_mg / density_mg_per_ml
+                const valueMg = value * getBaseUnitFactor(fromUnit);
+                const valueMl = valueMg / bridgeDensity;
+                return valueMl / getBaseUnitFactor(toUnit);
+            }
+            else {
+                // Volume to Mass: value_ml * density_mg_per_ml
+                const valueMl = value * getBaseUnitFactor(fromUnit);
+                const valueMg = valueMl * bridgeDensity;
+                return valueMg / getBaseUnitFactor(toUnit);
+            }
+        }
+    }
+    return null;
+}

package/package.json

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

package/dist/utils/enum.d.ts

@@ -1,2 +0,0 @@
-export declare function enumEntries<T extends Record<string, string | number>>(enumeration: T): Array<[keyof T, T[keyof T]]>;
-export declare function enumValues<T extends Record<string, string | number>>(enumeration: T): Array<T[keyof T]>;

package/dist/utils/enum.js

@@ -1,7 +0,0 @@
-import { objectEntries, objectValues } from "./object";
-export function enumEntries(enumeration) {
-    return objectEntries(enumeration);
-}
-export function enumValues(enumeration) {
-    return objectValues(enumeration);
-}