ezmedicationinput 0.1.16 → 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/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")) {

package/dist/maps.js

@@ -1254,6 +1254,7 @@ exports.DEFAULT_UNIT_BY_ROUTE = (() => {
     ensure(types_1.RouteCode["Otic route"], "drop");
     ensure(types_1.RouteCode["Respiratory tract route (qualifier value)"], "puff");
     ensure(types_1.RouteCode["Transdermal route"], "patch");
+    ensure(types_1.RouteCode["Per rectum"], "suppository");
     return resolved;
 })();
 function normalizePrnReasonKey(value) {
@@ -1281,7 +1282,7 @@ const DEFAULT_PRN_REASON_SOURCE = [
         }
     },
     {
-        names: ["nausea", "queasiness"],
+        names: ["nausea", "queasiness", "vomiting", "n/v", "nausea and vomiting"],
         definition: {
             coding: { system: SNOMED_SYSTEM, code: "422587007", display: "Nausea" },
             text: "Nausea"

package/dist/parser.js

@@ -1897,6 +1897,7 @@ function parseInternal(input, options) {
     if (internal.asNeeded && prnReasonStart !== undefined) {
         const reasonTokens = [];
         const reasonIndices = [];
+        const reasonObjects = [];
         for (let i = prnReasonStart; i < tokens.length; i++) {
             const token = tokens[i];
             if (internal.consumed.has(token.index)) {
@@ -1904,36 +1905,77 @@ function parseInternal(input, options) {
             }
             reasonTokens.push(token.original);
             reasonIndices.push(token.index);
+            reasonObjects.push(token);
             mark(internal.consumed, token);
         }
         if (reasonTokens.length > 0) {
-            const joined = reasonTokens.join(" ").trim();
-            if (joined) {
-                const sortedIndices = reasonIndices.sort((a, b) => a - b);
-                const range = computeTokenRange(internal.input, tokens, sortedIndices);
-                const sourceText = range ? internal.input.slice(range.start, range.end) : undefined;
-                let sanitized = joined.replace(/\s+/g, " ").trim();
-                let isProbe = false;
-                const probeMatch = sanitized.match(/^\{(.+)}$/);
-                if (probeMatch) {
-                    isProbe = true;
-                    sanitized = probeMatch[1];
+            let sortedIndices = reasonIndices.slice().sort((a, b) => a - b);
+            let range = computeTokenRange(internal.input, tokens, sortedIndices);
+            let sourceText = range ? internal.input.slice(range.start, range.end) : undefined;
+            if (sourceText) {
+                const cutoff = determinePrnReasonCutoff(reasonObjects, sourceText);
+                if (cutoff !== undefined) {
+                    for (let i = cutoff; i < reasonObjects.length; i++) {
+                        internal.consumed.delete(reasonObjects[i].index);
+                    }
+                    reasonObjects.splice(cutoff);
+                    reasonTokens.splice(cutoff);
+                    reasonIndices.splice(cutoff);
+                    while (reasonTokens.length > 0) {
+                        const lastToken = reasonTokens[reasonTokens.length - 1];
+                        if (!lastToken || /^[;:.,-]+$/.test(lastToken.trim())) {
+                            const removedObject = reasonObjects.pop();
+                            if (removedObject) {
+                                internal.consumed.delete(removedObject.index);
+                            }
+                            reasonTokens.pop();
+                            const removedIndex = reasonIndices.pop();
+                            if (removedIndex !== undefined) {
+                                internal.consumed.delete(removedIndex);
+                            }
+                            continue;
+                        }
+                        break;
+                    }
+                    if (reasonTokens.length > 0) {
+                        sortedIndices = reasonIndices.slice().sort((a, b) => a - b);
+                        range = computeTokenRange(internal.input, tokens, sortedIndices);
+                        sourceText = range ? internal.input.slice(range.start, range.end) : undefined;
+                    }
+                    else {
+                        range = undefined;
+                        sourceText = undefined;
+                    }
+                }
+            }
+            if (reasonTokens.length > 0) {
+                const joined = reasonTokens.join(" ").trim();
+                if (joined) {
+                    let sanitized = joined.replace(/\s+/g, " ").trim();
+                    let isProbe = false;
+                    const probeMatch = sanitized.match(/^\{(.+)}$/);
+                    if (probeMatch) {
+                        isProbe = true;
+                        sanitized = probeMatch[1];
+                    }
+                    sanitized = sanitized.replace(/[{}]/g, " ").replace(/\s+/g, " ").trim();
+                    const text = sanitized || joined;
+                    internal.asNeededReason = text;
+                    const normalized = text.toLowerCase();
+                    const canonical = sanitized
+                        ? (0, maps_1.normalizePrnReasonKey)(sanitized)
+                        : (0, maps_1.normalizePrnReasonKey)(text);
+                    internal.prnReasonLookupRequest = {
+                        originalText: joined,
+                        text,
+                        normalized,
+                        canonical: canonical !== null && canonical !== void 0 ? canonical : "",
+                        isProbe,
+                        inputText: internal.input,
+                        sourceText,
+                        range
+                    };
                 }
-                sanitized = sanitized.replace(/[{}]/g, " ").replace(/\s+/g, " ").trim();
-                const text = sanitized || joined;
-                internal.asNeededReason = text;
-                const normalized = text.toLowerCase();
-                const canonical = sanitized ? (0, maps_1.normalizePrnReasonKey)(sanitized) : (0, maps_1.normalizePrnReasonKey)(text);
-                internal.prnReasonLookupRequest = {
-                    originalText: joined,
-                    text,
-                    normalized,
-                    canonical: canonical !== null && canonical !== void 0 ? canonical : "",
-                    isProbe,
-                    inputText: internal.input,
-                    sourceText,
-                    range
-                };
             }
         }
     }
@@ -2028,27 +2070,30 @@ function parseInternal(input, options) {
             sanitized = sanitized.replace(/[{}]/g, " ").replace(/\s+/g, " ").trim();
             const range = refineSiteRange(internal.input, sanitized, tokenRange);
             const sourceText = range ? internal.input.slice(range.start, range.end) : undefined;
+            const displayText = normalizeSiteDisplayText(sanitized, options === null || options === void 0 ? void 0 : options.siteCodeMap);
+            const displayLower = displayText.toLowerCase();
+            const canonical = displayText ? (0, maps_1.normalizeBodySiteKey)(displayText) : "";
             internal.siteLookupRequest = {
                 originalText: normalizedSite,
-                text: sanitized,
-                normalized: sanitized.toLowerCase(),
-                canonical: sanitized ? (0, maps_1.normalizeBodySiteKey)(sanitized) : "",
+                text: displayText,
+                normalized: displayLower,
+                canonical,
                 isProbe,
                 inputText: internal.input,
                 sourceText,
                 range
             };
-            if (sanitized) {
+            if (displayText) {
                 const normalizedLower = sanitized.toLowerCase();
                 const strippedDescriptor = normalizeRouteDescriptorPhrase(normalizedLower);
-                const siteWords = normalizedLower.split(/\s+/).filter((word) => word.length > 0);
+                const siteWords = displayLower.split(/\s+/).filter((word) => word.length > 0);
                 const hasNonSiteWords = siteWords.some((word) => !isBodySiteHint(word, internal.customSiteHints));
                 const shouldAttemptRouteDescriptor = strippedDescriptor !== normalizedLower || hasNonSiteWords || strippedDescriptor === "mouth";
                 const appliedRouteDescriptor = shouldAttemptRouteDescriptor && maybeApplyRouteDescriptor(sanitized);
                 if (!appliedRouteDescriptor) {
                     // Preserve the clean site text for FHIR output and resolver context
                     // whenever we keep the original phrase.
-                    internal.siteText = sanitized;
+                    internal.siteText = displayText;
                     if (!internal.siteSource) {
                         internal.siteSource = "text";
                     }
@@ -2399,29 +2444,194 @@ function findAdditionalInstructionDefinition(text, canonical) {
     }
     return undefined;
 }
+const BODY_SITE_ADJECTIVE_SUFFIXES = [
+    "al",
+    "ial",
+    "ual",
+    "ic",
+    "ous",
+    "ive",
+    "ary",
+    "ory",
+    "atic",
+    "etic",
+    "ular",
+    "otic",
+    "ile",
+    "eal",
+    "inal",
+    "aneal",
+    "enal"
+];
+const DEFAULT_SITE_SYNONYM_KEYS = (() => {
+    const map = new Map();
+    for (const [key, definition] of (0, object_1.objectEntries)(maps_1.DEFAULT_BODY_SITE_SNOMED)) {
+        if (!definition) {
+            continue;
+        }
+        const normalized = key.trim();
+        if (!normalized) {
+            continue;
+        }
+        const existing = map.get(definition);
+        if (existing) {
+            if (existing.indexOf(normalized) === -1) {
+                existing.push(normalized);
+            }
+        }
+        else {
+            map.set(definition, [normalized]);
+        }
+    }
+    return map;
+})();
+function normalizeSiteDisplayText(text, customSiteMap) {
+    var _a;
+    const trimmed = text.trim();
+    if (!trimmed) {
+        return trimmed;
+    }
+    const canonicalInput = (0, maps_1.normalizeBodySiteKey)(trimmed);
+    if (!canonicalInput || !isAdjectivalSitePhrase(canonicalInput)) {
+        return trimmed;
+    }
+    const definition = (_a = lookupBodySiteDefinition(customSiteMap, canonicalInput)) !== null && _a !== void 0 ? _a : maps_1.DEFAULT_BODY_SITE_SNOMED[canonicalInput];
+    if (!definition) {
+        return trimmed;
+    }
+    const preferred = pickPreferredBodySitePhrase(canonicalInput, definition, customSiteMap);
+    if (!preferred) {
+        return trimmed;
+    }
+    return preferred;
+}
+function pickPreferredBodySitePhrase(canonical, definition, customSiteMap) {
+    const synonyms = new Set();
+    synonyms.add(canonical);
+    if (definition.aliases) {
+        for (const alias of definition.aliases) {
+            const normalizedAlias = (0, maps_1.normalizeBodySiteKey)(alias);
+            if (normalizedAlias) {
+                synonyms.add(normalizedAlias);
+            }
+        }
+    }
+    const defaultSynonyms = DEFAULT_SITE_SYNONYM_KEYS.get(definition);
+    if (defaultSynonyms) {
+        for (const synonym of defaultSynonyms) {
+            synonyms.add(synonym);
+        }
+    }
+    if (customSiteMap) {
+        for (const [key, candidate] of (0, object_1.objectEntries)(customSiteMap)) {
+            if (!candidate) {
+                continue;
+            }
+            if (candidate === definition) {
+                const normalizedKey = (0, maps_1.normalizeBodySiteKey)(key);
+                if (normalizedKey) {
+                    synonyms.add(normalizedKey);
+                }
+            }
+            if (candidate.aliases) {
+                for (const alias of candidate.aliases) {
+                    const normalizedAlias = (0, maps_1.normalizeBodySiteKey)(alias);
+                    if (normalizedAlias) {
+                        synonyms.add(normalizedAlias);
+                    }
+                }
+            }
+        }
+    }
+    const candidates = Array.from(synonyms).filter((phrase) => phrase && !isAdjectivalSitePhrase(phrase));
+    if (!candidates.length) {
+        return undefined;
+    }
+    candidates.sort((a, b) => scoreBodySitePhrase(b) - scoreBodySitePhrase(a));
+    const best = candidates[0];
+    if (!best) {
+        return undefined;
+    }
+    if ((0, maps_1.normalizeBodySiteKey)(best) === canonical) {
+        return undefined;
+    }
+    return best;
+}
+function scoreBodySitePhrase(phrase) {
+    const lower = phrase.toLowerCase();
+    const words = lower.split(/\s+/).filter((part) => part.length > 0);
+    let score = 0;
+    if (!/(structure|region|entire|proper|body)/.test(lower)) {
+        score += 3;
+    }
+    if (!lower.includes(" of ")) {
+        score += 1;
+    }
+    if (words.length <= 2) {
+        score += 1;
+    }
+    if (words.length === 1) {
+        score += 0.5;
+    }
+    score -= words.length * 0.2;
+    score -= lower.length * 0.01;
+    return score;
+}
+function isAdjectivalSitePhrase(phrase) {
+    const normalized = phrase.trim().toLowerCase();
+    if (!normalized) {
+        return false;
+    }
+    const words = normalized.split(/\s+/).filter((word) => word.length > 0);
+    if (words.length !== 1) {
+        return false;
+    }
+    const last = words[words.length - 1];
+    if (last.length <= 3) {
+        return false;
+    }
+    return BODY_SITE_ADJECTIVE_SUFFIXES.some((suffix) => last.endsWith(suffix));
+}
 function collectAdditionalInstructions(internal, tokens) {
     var _a, _b, _c, _d, _e, _f;
     if (internal.additionalInstructions.length) {
         return;
     }
-    const leftover = tokens.filter((token) => !internal.consumed.has(token.index));
-    if (!leftover.length) {
-        return;
-    }
     const punctuationOnly = /^[;:.,-]+$/;
-    const contentTokens = leftover.filter((token) => !punctuationOnly.test(token.original));
-    if (!contentTokens.length) {
+    const trailing = [];
+    let expectedIndex;
+    for (let cursor = tokens.length - 1; cursor >= 0; cursor--) {
+        const token = tokens[cursor];
+        if (!token) {
+            continue;
+        }
+        if (internal.consumed.has(token.index)) {
+            if (trailing.length > 0) {
+                break;
+            }
+            continue;
+        }
+        if (expectedIndex !== undefined && token.index !== expectedIndex - 1) {
+            break;
+        }
+        trailing.unshift(token);
+        expectedIndex = token.index;
+    }
+    if (!trailing.length) {
         return;
     }
-    const leftoverIndices = leftover.map((token) => token.index).sort((a, b) => a - b);
-    const contiguous = leftoverIndices.every((index, i) => i === 0 || index === leftoverIndices[i - 1] + 1);
-    if (!contiguous) {
+    const contentTokens = trailing.filter((token) => !punctuationOnly.test(token.original));
+    if (!contentTokens.length) {
         return;
     }
-    const lastIndex = leftoverIndices[leftoverIndices.length - 1];
+    const trailingIndices = trailing.map((token) => token.index).sort((a, b) => a - b);
+    const lastIndex = trailingIndices[trailingIndices.length - 1];
     for (let i = lastIndex + 1; i < tokens.length; i++) {
-        const trailingToken = tokens[i];
-        if (!internal.consumed.has(trailingToken.index)) {
+        const nextToken = tokens[i];
+        if (!nextToken) {
+            continue;
+        }
+        if (!internal.consumed.has(nextToken.index)) {
             return;
         }
     }
@@ -2434,7 +2644,33 @@ function collectAdditionalInstructions(internal, tokens) {
         return;
     }
     const contentIndices = contentTokens.map((token) => token.index).sort((a, b) => a - b);
-    const range = computeTokenRange(internal.input, tokens, contentIndices);
+    const lowerInput = internal.input.toLowerCase();
+    let trailingRange;
+    let searchEnd = lowerInput.length;
+    let rangeStart;
+    let rangeEnd;
+    for (let i = contentTokens.length - 1; i >= 0; i--) {
+        const fragment = contentTokens[i].original.trim();
+        if (!fragment) {
+            continue;
+        }
+        const lowerFragment = fragment.toLowerCase();
+        const foundIndex = lowerInput.lastIndexOf(lowerFragment, searchEnd - 1);
+        if (foundIndex === -1) {
+            rangeStart = undefined;
+            rangeEnd = undefined;
+            break;
+        }
+        rangeStart = foundIndex;
+        if (rangeEnd === undefined) {
+            rangeEnd = foundIndex + lowerFragment.length;
+        }
+        searchEnd = foundIndex;
+    }
+    if (rangeStart !== undefined && rangeEnd !== undefined) {
+        trailingRange = { start: rangeStart, end: rangeEnd };
+    }
+    const range = trailingRange !== null && trailingRange !== void 0 ? trailingRange : computeTokenRange(internal.input, tokens, contentIndices);
     let separatorDetected = false;
     if (range) {
         for (let cursor = range.start - 1; cursor >= 0; cursor--) {
@@ -2499,11 +2735,81 @@ function collectAdditionalInstructions(internal, tokens) {
     }
     if (instructions.length) {
         internal.additionalInstructions = instructions;
-        for (const token of leftover) {
+        for (const token of trailing) {
             mark(internal.consumed, token);
         }
     }
 }
+function determinePrnReasonCutoff(tokens, sourceText) {
+    const separatorIndex = findPrnReasonSeparator(sourceText);
+    if (separatorIndex === undefined) {
+        return undefined;
+    }
+    const lowerSource = sourceText.toLowerCase();
+    let searchOffset = 0;
+    for (let i = 0; i < tokens.length; i++) {
+        const token = tokens[i];
+        const fragment = token.original.trim();
+        if (!fragment) {
+            continue;
+        }
+        const lowerFragment = fragment.toLowerCase();
+        const position = lowerSource.indexOf(lowerFragment, searchOffset);
+        if (position === -1) {
+            continue;
+        }
+        const end = position + lowerFragment.length;
+        searchOffset = end;
+        if (position >= separatorIndex) {
+            return i;
+        }
+    }
+    return undefined;
+}
+function findPrnReasonSeparator(sourceText) {
+    var _a;
+    for (let i = 0; i < sourceText.length; i++) {
+        const ch = sourceText[i];
+        if (ch === "\n" || ch === "\r") {
+            if (sourceText.slice(i + 1).trim().length > 0) {
+                return i;
+            }
+            continue;
+        }
+        if (ch === ";") {
+            if (sourceText.slice(i + 1).trim().length > 0) {
+                return i;
+            }
+            continue;
+        }
+        if (ch === "-") {
+            const prev = sourceText[i - 1];
+            const next = sourceText[i + 1];
+            const hasWhitespaceAround = (!prev || /\s/.test(prev)) && (!next || /\s/.test(next));
+            if (hasWhitespaceAround && sourceText.slice(i + 1).trim().length > 0) {
+                return i;
+            }
+            continue;
+        }
+        if (ch === ":" || ch === ".") {
+            const rest = sourceText.slice(i + 1);
+            if (!rest.trim().length) {
+                continue;
+            }
+            const nextChar = rest.replace(/^\s+/, "")[0];
+            if (!nextChar) {
+                continue;
+            }
+            if (ch === "." &&
+                /[0-9]/.test((_a = sourceText[i - 1]) !== null && _a !== void 0 ? _a : "") &&
+                /[0-9]/.test(nextChar)) {
+                continue;
+            }
+            return i;
+        }
+    }
+    return undefined;
+}
 function lookupPrnReasonDefinition(map, canonical) {
     if (!map) {
         return undefined;

package/package.json

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