ezmedicationinput 0.1.15 → 0.1.17

package/README.md

@@ -8,6 +8,7 @@
 - Emits timing abbreviations (`timing.code`) and repeat structures simultaneously where possible.
 - Maps meal/time blocks to the correct `Timing.repeat.when` **EventTiming** codes and can auto-expand AC/PC/C into specific meals.
 - Outputs SNOMED CT route codings (while providing friendly text) and round-trips known SNOMED routes back into the parser.
+- Auto-codes common PRN (as-needed) reasons and additional dosage instructions while keeping the raw text when no coding is available.
 - Understands ocular and intravitreal shorthand (OD/OS/OU, LE/RE/BE, IVT*, VOD/VOS, etc.) and warns when intravitreal instructions omit an eye side.
 - Parses fractional/ minute-based intervals (`q0.5h`, `q30 min`, `q1/4hr`) plus dose and timing ranges.
 - Supports extensible dictionaries for routes, units, frequency shorthands, and event timing tokens.
@@ -50,6 +51,59 @@ Example output:
 }
 ```
 
+### PRN reasons & additional instructions
+
+`parseSig` identifies PRN (as-needed) clauses and trailing instructions, then
+codes them with SNOMED CT whenever possible.
+
+```ts
+const result = parseSig("1 tab po q4h prn headache; do not exceed 6 tabs/day");
+
+result.fhir.asNeededFor;
+// → [{
+//      text: "headache",
+//      coding: [{
+//        system: "http://snomed.info/sct",
+//        code: "25064002",
+//        display: "Headache"
+//      }]
+//    }]
+
+result.fhir.additionalInstruction;
+// → [{ text: "Do not exceed 6 tablets daily" }]
+```
+
+Customize the dictionaries and lookups through `ParseOptions`:
+
+```ts
+parseSig(input, {
+  prnReasonMap: {
+    migraine: {
+      text: "Migraine",
+      coding: {
+        system: "http://snomed.info/sct",
+        code: "37796009",
+        display: "Migraine"
+      }
+    }
+  },
+  prnReasonResolvers: async (request) => terminologyService.lookup(request),
+  prnReasonSuggestionResolvers: async (request) => terminologyService.suggest(request),
+});
+```
+
+Use `{reason}` in the sig string (e.g. `prn {migraine}`) to force a lookup even
+when a direct match exists. Additional instructions are sourced from a built-in
+set of SNOMED CT concepts under *419492006 – Additional dosage instructions* and
+fall back to plain text when no coding is available. Parsed instructions are
+also echoed in `ParseResult.meta.normalized.additionalInstructions` for quick UI
+rendering.
+
+When a PRN reason cannot be auto-resolved, any registered suggestion resolvers
+are invoked and their responses are surfaced through
+`ParseResult.meta.prnReasonLookups` so client applications can prompt the user
+to choose a coded concept.
+
 ### Sig (directions) suggestions
 
 Use `suggestSig` to drive autocomplete experiences while the clinician is
@@ -126,6 +180,8 @@ result.fhir.site?.coding?.[0];
 
 When the parser encounters an unfamiliar site, it leaves the text untouched and records nothing in `meta.siteLookups`. Wrapping the phrase in braces (e.g. `apply to {mole on scalp}`) preserves the same parsing behavior but flags the entry as a **probe** so `meta.siteLookups` always contains the request. This allows UIs to display lookup widgets even before a matching code exists. Braces are optional when the site is already recognized—they simply make the clinician's intent explicit.
 
+Unknown body sites still populate `Dosage.site.text` and `ParseResult.meta.normalized.site.text`, allowing UIs to echo the verbatim phrase while terminology lookups run asynchronously.
+
 You can extend or replace the built-in codings via `ParseOptions`:
 
 ```ts

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;
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j;
     const dosage = {};
     const repeat = {};
     let hasRepeat = false;
@@ -115,10 +115,40 @@ function toFhir(internal) {
             coding
         };
     }
+    if ((_f = internal.additionalInstructions) === null || _f === void 0 ? void 0 : _f.length) {
+        dosage.additionalInstruction = internal.additionalInstructions.map((instruction) => {
+            var _a, _b;
+            return ({
+                text: instruction.text,
+                coding: ((_a = instruction.coding) === null || _a === void 0 ? void 0 : _a.code)
+                    ? [
+                        {
+                            system: (_b = instruction.coding.system) !== null && _b !== void 0 ? _b : SNOMED_SYSTEM,
+                            code: instruction.coding.code,
+                            display: instruction.coding.display
+                        }
+                    ]
+                    : undefined
+            });
+        });
+    }
     if (internal.asNeeded) {
         dosage.asNeededBoolean = true;
-        if (internal.asNeededReason) {
-            dosage.asNeededFor = [{ text: internal.asNeededReason }];
+        if (internal.asNeededReason || ((_g = internal.asNeededReasonCoding) === null || _g === void 0 ? void 0 : _g.code)) {
+            const concept = {};
+            if (internal.asNeededReason) {
+                concept.text = internal.asNeededReason;
+            }
+            if ((_h = internal.asNeededReasonCoding) === null || _h === void 0 ? void 0 : _h.code) {
+                concept.coding = [
+                    {
+                        system: (_j = internal.asNeededReasonCoding.system) !== null && _j !== void 0 ? _j : SNOMED_SYSTEM,
+                        code: internal.asNeededReasonCoding.code,
+                        display: internal.asNeededReasonCoding.display
+                    }
+                ];
+            }
+            dosage.asNeededFor = [concept];
         }
     }
     const longText = (0, format_1.formatInternal)(internal, "long");
@@ -128,7 +158,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;
+    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;
     const internal = {
         input: (_a = dosage.text) !== null && _a !== void 0 ? _a : "",
         tokens: [],
@@ -152,7 +182,9 @@ function internalFromFhir(dosage) {
         asNeeded: dosage.asNeededBoolean,
         asNeededReason: (_0 = (_z = dosage.asNeededFor) === null || _z === void 0 ? void 0 : _z[0]) === null || _0 === void 0 ? void 0 : _0.text,
         siteTokenIndices: new Set(),
-        siteLookups: []
+        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);
     if (routeCoding === null || routeCoding === void 0 ? void 0 : routeCoding.code) {
@@ -171,13 +203,36 @@ function internalFromFhir(dosage) {
             system: siteCoding.system
         };
     }
-    const doseAndRate = (_5 = dosage.doseAndRate) === null || _5 === void 0 ? void 0 : _5[0];
+    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];
+    if (reasonCoding === null || reasonCoding === void 0 ? void 0 : reasonCoding.code) {
+        internal.asNeededReasonCoding = {
+            code: reasonCoding.code,
+            display: reasonCoding.display,
+            system: reasonCoding.system
+        };
+    }
+    if ((_8 = dosage.additionalInstruction) === null || _8 === void 0 ? void 0 : _8.length) {
+        internal.additionalInstructions = dosage.additionalInstruction.map((concept) => {
+            var _a;
+            return ({
+                text: concept.text,
+                coding: ((_a = concept.coding) === null || _a === void 0 ? void 0 : _a[0])
+                    ? {
+                        code: concept.coding[0].code,
+                        display: concept.coding[0].display,
+                        system: concept.coding[0].system
+                    }
+                    : undefined
+            });
+        });
+    }
+    const doseAndRate = (_9 = dosage.doseAndRate) === null || _9 === void 0 ? void 0 : _9[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 = (_7 = (_6 = low === null || low === void 0 ? void 0 : low.unit) !== null && _6 !== void 0 ? _6 : high === null || high === void 0 ? void 0 : high.unit) !== null && _7 !== void 0 ? _7 : internal.unit;
+        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;
     }
     else if (doseAndRate === null || doseAndRate === void 0 ? void 0 : doseAndRate.doseQuantity) {
         const dose = doseAndRate.doseQuantity;

package/dist/format.js

@@ -69,6 +69,11 @@ const ROUTE_GRAMMAR = {
         routePhrase: ({ hasSite }) => (hasSite ? undefined : "into the eye"),
         sitePreposition: "into"
     },
+    [types_1.RouteCode["Per rectum"]]: {
+        verb: "Use",
+        routePhrase: ({ hasSite }) => (hasSite ? undefined : "rectally"),
+        sitePreposition: "into"
+    },
     [types_1.RouteCode["Topical route"]]: {
         verb: "Apply",
         routePhrase: ({ hasSite }) => (hasSite ? undefined : "topically"),
@@ -137,6 +142,9 @@ function grammarFromRouteText(text) {
     if (normalized.includes("intravenous") || normalized === "iv") {
         return ROUTE_GRAMMAR[types_1.RouteCode["Intravenous route"]];
     }
+    if (normalized.includes("rectal") || normalized.includes("rectum")) {
+        return ROUTE_GRAMMAR[types_1.RouteCode["Per rectum"]];
+    }
     if (normalized.includes("nasal")) {
         return ROUTE_GRAMMAR[types_1.RouteCode["Nasal route"]];
     }
@@ -412,6 +420,11 @@ function formatSite(internal, grammar) {
         return undefined;
     }
     const lower = text.toLowerCase();
+    if (internal.routeCode === types_1.RouteCode["Per rectum"]) {
+        if (lower === "rectum" || lower === "rectal") {
+            return undefined;
+        }
+    }
     let preposition = grammar.sitePreposition;
     if (!preposition) {
         if (lower.includes("eye")) {
@@ -603,9 +616,33 @@ function formatLong(internal) {
     }
     const body = segments.filter(Boolean).join(" ").replace(/\s+/g, " ").trim();
     if (!body) {
-        return `${grammar.verb}.`;
+        const instructionText = formatAdditionalInstructions(internal);
+        if (!instructionText) {
+            return `${grammar.verb}.`;
+        }
+        return `${grammar.verb}. ${instructionText}`.trim();
+    }
+    const instructionText = formatAdditionalInstructions(internal);
+    const baseSentence = `${grammar.verb} ${body}.`;
+    return instructionText ? `${baseSentence} ${instructionText}` : baseSentence;
+}
+function formatAdditionalInstructions(internal) {
+    var _a;
+    if (!((_a = internal.additionalInstructions) === null || _a === void 0 ? void 0 : _a.length)) {
+        return undefined;
+    }
+    const phrases = internal.additionalInstructions
+        .map((instruction) => { var _a; return instruction.text || ((_a = instruction.coding) === null || _a === void 0 ? void 0 : _a.display); })
+        .filter((text) => Boolean(text))
+        .map((text) => text.trim())
+        .filter((text) => text.length > 0);
+    if (!phrases.length) {
+        return undefined;
     }
-    return `${grammar.verb} ${body}.`;
+    return phrases
+        .map((phrase) => (/[.!?]$/.test(phrase) ? phrase : `${phrase}.`))
+        .join(" ")
+        .trim();
 }
 function stripTrailingZero(value) {
     const text = value.toString();

package/dist/index.js

@@ -46,12 +46,14 @@ Object.defineProperty(exports, "resolveSigLocalization", { enumerable: true, get
 Object.defineProperty(exports, "resolveSigTranslation", { enumerable: true, get: function () { return i18n_2.resolveSigTranslation; } });
 function parseSig(input, options) {
     const internal = (0, parser_1.parseInternal)(input, options);
+    (0, parser_1.applyPrnReasonCoding)(internal, options);
     (0, parser_1.applySiteCoding)(internal, options);
     return buildParseResult(internal, options);
 }
 function parseSigAsync(input, options) {
     return __awaiter(this, void 0, void 0, function* () {
         const internal = (0, parser_1.parseInternal)(input, options);
+        yield (0, parser_1.applyPrnReasonCodingAsync)(internal, options);
         yield (0, parser_1.applySiteCodingAsync)(internal, options);
         return buildParseResult(internal, options);
     });
@@ -62,7 +64,7 @@ function formatSig(dosage, style = "short", options) {
     return (0, format_1.formatInternal)(internal, style, localization);
 }
 function fromFhirDosage(dosage, options) {
-    var _a, _b, _c;
+    var _a, _b, _c, _d, _e, _f;
     const internal = (0, fhir_1.internalFromFhir)(dosage);
     const localization = (0, i18n_1.resolveSigLocalization)(options === null || options === void 0 ? void 0 : options.locale, options === null || options === void 0 ? void 0 : options.i18n);
     const shortText = (0, format_1.formatInternal)(internal, "short", localization);
@@ -89,13 +91,40 @@ function fromFhirDosage(dosage, options) {
                             }
                             : undefined
                     }
+                    : undefined,
+                prnReason: internal.asNeededReason || ((_d = internal.asNeededReasonCoding) === null || _d === void 0 ? void 0 : _d.code)
+                    ? {
+                        text: internal.asNeededReason,
+                        coding: ((_e = internal.asNeededReasonCoding) === null || _e === void 0 ? void 0 : _e.code)
+                            ? {
+                                code: internal.asNeededReasonCoding.code,
+                                display: internal.asNeededReasonCoding.display,
+                                system: internal.asNeededReasonCoding.system
+                            }
+                            : undefined
+                    }
+                    : undefined,
+                additionalInstructions: ((_f = internal.additionalInstructions) === null || _f === void 0 ? void 0 : _f.length)
+                    ? internal.additionalInstructions.map((instruction) => {
+                        var _a;
+                        return ({
+                            text: instruction.text,
+                            coding: ((_a = instruction.coding) === null || _a === void 0 ? void 0 : _a.code)
+                                ? {
+                                    code: instruction.coding.code,
+                                    display: instruction.coding.display,
+                                    system: instruction.coding.system
+                                }
+                                : undefined
+                        });
+                    })
                     : undefined
             }
         }
     };
 }
 function buildParseResult(internal, options) {
-    var _a;
+    var _a, _b, _c;
     const localization = (0, i18n_1.resolveSigLocalization)(options === null || options === void 0 ? void 0 : options.locale, options === null || options === void 0 ? void 0 : options.i18n);
     const shortText = (0, format_1.formatInternal)(internal, "short", localization);
     const longText = (0, format_1.formatInternal)(internal, "long", localization);
@@ -114,6 +143,28 @@ function buildParseResult(internal, options) {
             system: internal.siteCoding.system
         }
         : undefined;
+    const prnReasonCoding = ((_b = internal.asNeededReasonCoding) === null || _b === void 0 ? void 0 : _b.code)
+        ? {
+            code: internal.asNeededReasonCoding.code,
+            display: internal.asNeededReasonCoding.display,
+            system: internal.asNeededReasonCoding.system
+        }
+        : undefined;
+    const additionalInstructions = ((_c = internal.additionalInstructions) === null || _c === void 0 ? void 0 : _c.length)
+        ? internal.additionalInstructions.map((instruction) => {
+            var _a;
+            return ({
+                text: instruction.text,
+                coding: ((_a = instruction.coding) === null || _a === void 0 ? void 0 : _a.code)
+                    ? {
+                        code: instruction.coding.code,
+                        display: instruction.coding.display,
+                        system: instruction.coding.system
+                    }
+                    : undefined
+            });
+        })
+        : undefined;
     const siteLookups = internal.siteLookups.length
         ? internal.siteLookups.map((entry) => ({
             request: entry.request,
@@ -127,6 +178,21 @@ function buildParseResult(internal, options) {
             }))
         }))
         : undefined;
+    const prnReasonLookups = internal.prnReasonLookups.length
+        ? internal.prnReasonLookups.map((entry) => ({
+            request: entry.request,
+            suggestions: entry.suggestions.map((suggestion) => ({
+                coding: suggestion.coding
+                    ? {
+                        code: suggestion.coding.code,
+                        display: suggestion.coding.display,
+                        system: suggestion.coding.system
+                    }
+                    : undefined,
+                text: suggestion.text
+            }))
+        }))
+        : undefined;
     return {
         fhir,
         shortText,
@@ -145,9 +211,17 @@ function buildParseResult(internal, options) {
                         text: internal.siteText,
                         coding: siteCoding
                     }
-                    : undefined
+                    : undefined,
+                prnReason: internal.asNeededReason || prnReasonCoding
+                    ? {
+                        text: internal.asNeededReason,
+                        coding: prnReasonCoding
+                    }
+                    : undefined,
+                additionalInstructions
             },
-            siteLookups
+            siteLookups,
+            prnReasonLookups
         }
     };
 }

package/dist/internal-types.d.ts

@@ -1,8 +1,12 @@
-import { EventTiming, FhirCoding, FhirDayOfWeek, FhirPeriodUnit, RouteCode, SiteCodeLookupRequest, SiteCodeSuggestion } from "./types";
+import { EventTiming, FhirCoding, FhirDayOfWeek, FhirPeriodUnit, PrnReasonLookupRequest, PrnReasonSuggestion, RouteCode, SiteCodeLookupRequest, SiteCodeSuggestion } from "./types";
 export interface SiteLookupDetail {
     request: SiteCodeLookupRequest;
     suggestions: SiteCodeSuggestion[];
 }
+export interface PrnReasonLookupDetail {
+    request: PrnReasonLookupRequest;
+    suggestions: PrnReasonSuggestion[];
+}
 export interface Token {
     original: string;
     lower: string;
@@ -31,6 +35,7 @@ export interface ParsedSigInternal {
     timingCode?: string;
     asNeeded?: boolean;
     asNeededReason?: string;
+    asNeededReasonCoding?: FhirCoding;
     warnings: string[];
     siteText?: string;
     siteSource?: "abbreviation" | "text";
@@ -39,4 +44,10 @@ export interface ParsedSigInternal {
     siteLookupRequest?: SiteCodeLookupRequest;
     siteLookups: SiteLookupDetail[];
     customSiteHints?: Set<string>;
+    prnReasonLookupRequest?: PrnReasonLookupRequest;
+    prnReasonLookups: PrnReasonLookupDetail[];
+    additionalInstructions: Array<{
+        text?: string;
+        coding?: FhirCoding;
+    }>;
 }

package/dist/maps.d.ts

@@ -1,4 +1,4 @@
-import { BodySiteDefinition, EventTiming, FhirDayOfWeek, FhirPeriodUnit, RouteCode, SNOMEDCTRouteCodes } from "./types";
+import { AdditionalInstructionDefinition, BodySiteDefinition, EventTiming, FhirDayOfWeek, FhirPeriodUnit, PrnReasonDefinition, RouteCode, SNOMEDCTRouteCodes } from "./types";
 /**
  * SNOMED CT codings aligned with every known RouteCode. Keeping the structure
  * data-driven ensures any additions to the enumeration are surfaced
@@ -58,3 +58,19 @@ export declare const KNOWN_DOSAGE_FORMS_TO_DOSE: Record<string, string>;
 export declare const KNOWN_TMT_DOSAGE_FORM_TO_SNOMED_ROUTE: Record<string, SNOMEDCTRouteCodes>;
 export declare const DEFAULT_UNIT_BY_NORMALIZED_FORM: Record<string, string>;
 export declare const DEFAULT_UNIT_BY_ROUTE: Partial<Record<RouteCode, string>>;
+export declare function normalizePrnReasonKey(value: string): string;
+export declare function normalizeAdditionalInstructionKey(value: string): string;
+export interface PrnReasonDictionaryEntry {
+    canonical: string;
+    definition: PrnReasonDefinition;
+    terms: string[];
+}
+export declare const DEFAULT_PRN_REASON_ENTRIES: PrnReasonDictionaryEntry[];
+export declare const DEFAULT_PRN_REASON_DEFINITIONS: Record<string, PrnReasonDefinition>;
+export interface AdditionalInstructionDictionaryEntry {
+    canonical: string;
+    definition: AdditionalInstructionDefinition;
+    terms: string[];
+}
+export declare const DEFAULT_ADDITIONAL_INSTRUCTION_ENTRIES: AdditionalInstructionDictionaryEntry[];
+export declare const DEFAULT_ADDITIONAL_INSTRUCTION_DEFINITIONS: Record<string, AdditionalInstructionDefinition>;