ezmedicationinput 0.1.13 → 0.1.15

package/README.md

@@ -138,9 +138,25 @@ const result = await parseSigAsync("apply to {left temple} nightly", {
         system: "http://example.org/custom",
         code: "LTEMP",
         display: "Left temple"
-      }
+      },
+      aliases: ["temporal region, left"],
+      text: "Left temple"
     }
   },
+  // any overrides that the user explicitly selected
+  siteCodeSelections: [
+    {
+      canonical: "scalp",
+      resolution: {
+        coding: {
+          system: "http://snomed.info/sct",
+          code: "39937001",
+          display: "Scalp structure"
+        },
+        text: "Scalp"
+      }
+    }
+  ],
   siteCodeResolvers: async (request) => {
     if (request.canonical === "mole on scalp") {
       return {
@@ -171,11 +187,13 @@ result.meta.siteLookups;
 // → [{ request: { text: "left temple", isProbe: true, ... }, suggestions: [...] }]
 ```
 
-- `siteCodeMap` lets you supply deterministic overrides for normalized site phrases.
-- `siteCodeResolvers` (sync or async) can call external services to resolve sites on demand.
-- `siteCodeSuggestionResolvers` return candidate codes; their results populate `meta.siteLookups[0].suggestions`.
-- Each resolver receives the full `SiteCodeLookupRequest`, including the original input, the cleaned site text, and a `{ start, end }` range you can use to highlight the substring in UI workflows.
-- `parseSigAsync` behaves like `parseSig` but awaits asynchronous resolvers and suggestion providers.
+  - `siteCodeMap` lets you supply deterministic overrides for normalized site phrases.
+  - Entries accept an `aliases` array so punctuation-heavy variants (e.g., "first bicuspid, left") can resolve to the same coding.
+  - `siteCodeResolvers` (sync or async) can call external services to resolve sites on demand.
+  - `siteCodeSuggestionResolvers` return candidate codes; their results populate `meta.siteLookups[0].suggestions`.
+  - `siteCodeSelections` let callers override the automatic match for a detected phrase or range—helpful when a clinician chooses a bundled SNOMED option over a custom override.
+  - Each resolver receives the full `SiteCodeLookupRequest`, including the original input, the cleaned site text, and a `{ start, end }` range you can use to highlight the substring in UI workflows.
+  - `parseSigAsync` behaves like `parseSig` but awaits asynchronous resolvers and suggestion providers.
 
 #### Site resolver signatures
 
@@ -225,6 +243,7 @@ You can specify the number of times (total count) the medication is supposed to
 - `allowHouseholdVolumeUnits`: defaults to `true`; set to `false` to ignore
   teaspoon/tablespoon units during parsing and suggestions.
 - Custom `routeMap`, `unitMap`, `freqMap`, and `whenMap` let you augment the built-in dictionaries without mutating them.
+- `siteCodeSelections` override automatic site resolution for matching phrases or ranges so user-picked suggestions stick when re-parsing a sig.
 
 ### Next due dose generation
 

package/dist/maps.js

@@ -170,7 +170,12 @@ exports.DEFAULT_ROUTE_SYNONYMS = (() => {
  * same logic to ensure consistent lookups.
  */
 function normalizeBodySiteKey(value) {
-    return value.trim().toLowerCase().replace(/\s+/g, " ");
+    return value
+        .trim()
+        .toLowerCase()
+        .replace(/[^\p{L}\p{N}]+/gu, " ")
+        .replace(/\s+/g, " ")
+        .trim();
 }
 const DEFAULT_BODY_SITE_SNOMED_SOURCE = [
     {

package/dist/parser.js

@@ -25,16 +25,27 @@ function buildCustomSiteHints(map) {
         return undefined;
     }
     const hints = new Set();
-    for (const key of Object.keys(map)) {
-        const normalized = (0, maps_1.normalizeBodySiteKey)(key);
+    const addPhraseHints = (phrase) => {
+        if (!phrase) {
+            return;
+        }
+        const normalized = (0, maps_1.normalizeBodySiteKey)(phrase);
         if (!normalized) {
-            continue;
+            return;
         }
         for (const part of normalized.split(" ")) {
             if (part) {
                 hints.add(part);
             }
         }
+    };
+    for (const [key, definition] of (0, object_1.objectEntries)(map)) {
+        addPhraseHints(key);
+        if (definition.aliases) {
+            for (const alias of definition.aliases) {
+                addPhraseHints(alias);
+            }
+        }
     }
     return hints;
 }
@@ -175,6 +186,33 @@ const COUNT_CONNECTOR_WORDS = new Set([
     "additional",
     "extra"
 ]);
+const FREQUENCY_SIMPLE_WORDS = {
+    once: 1,
+    twice: 2,
+    thrice: 3
+};
+const FREQUENCY_NUMBER_WORDS = {
+    one: 1,
+    two: 2,
+    three: 3,
+    four: 4,
+    five: 5,
+    six: 6,
+    seven: 7,
+    eight: 8,
+    nine: 9,
+    ten: 10,
+    eleven: 11,
+    twelve: 12
+};
+const FREQUENCY_TIMES_WORDS = new Set(["time", "times", "x"]);
+const FREQUENCY_CONNECTOR_WORDS = new Set(["per", "a", "an", "each", "every"]);
+const FREQUENCY_ADVERB_UNITS = {
+    daily: types_1.FhirPeriodUnit.Day,
+    weekly: types_1.FhirPeriodUnit.Week,
+    monthly: types_1.FhirPeriodUnit.Month,
+    hourly: types_1.FhirPeriodUnit.Hour
+};
 const ROUTE_DESCRIPTOR_FILLER_WORDS = new Set([
     "per",
     "by",
@@ -569,6 +607,115 @@ function tryParseNumericCadence(internal, tokens, index) {
     mark(internal.consumed, unitToken);
     return true;
 }
+function tryParseCountBasedFrequency(internal, tokens, index, options) {
+    const token = tokens[index];
+    if (internal.consumed.has(token.index)) {
+        return false;
+    }
+    if (internal.frequency !== undefined ||
+        internal.frequencyMax !== undefined ||
+        internal.period !== undefined ||
+        internal.periodMax !== undefined) {
+        return false;
+    }
+    const normalized = normalizeTokenLower(token);
+    let value;
+    let requiresPeriod = true;
+    let requiresCue = true;
+    if (/^[0-9]+(?:\.[0-9]+)?$/.test(normalized)) {
+        value = parseFloat(token.original);
+    }
+    else {
+        const simple = FREQUENCY_SIMPLE_WORDS[normalized];
+        if (simple !== undefined) {
+            value = simple;
+            requiresPeriod = false;
+            requiresCue = false;
+        }
+        else {
+            const wordValue = FREQUENCY_NUMBER_WORDS[normalized];
+            if (wordValue === undefined) {
+                return false;
+            }
+            value = wordValue;
+        }
+    }
+    if (!Number.isFinite(value) || value === undefined || value <= 0) {
+        return false;
+    }
+    const nextToken = tokens[index + 1];
+    if (nextToken &&
+        !internal.consumed.has(nextToken.index) &&
+        normalizeUnit(normalizeTokenLower(nextToken), options)) {
+        return false;
+    }
+    const partsToConsume = [];
+    let nextIndex = index + 1;
+    let periodUnit;
+    let sawCue = !requiresCue;
+    let sawTimesWord = false;
+    let sawConnectorWord = false;
+    while (true) {
+        const candidate = tokens[nextIndex];
+        if (!candidate || internal.consumed.has(candidate.index)) {
+            break;
+        }
+        const lower = normalizeTokenLower(candidate);
+        if (FREQUENCY_TIMES_WORDS.has(lower)) {
+            partsToConsume.push(candidate);
+            sawCue = true;
+            sawTimesWord = true;
+            nextIndex += 1;
+            continue;
+        }
+        if (FREQUENCY_CONNECTOR_WORDS.has(lower)) {
+            partsToConsume.push(candidate);
+            sawCue = true;
+            sawConnectorWord = true;
+            nextIndex += 1;
+            continue;
+        }
+        const adverbUnit = mapFrequencyAdverb(lower);
+        if (adverbUnit) {
+            periodUnit = adverbUnit;
+            partsToConsume.push(candidate);
+            break;
+        }
+        const mappedUnit = mapIntervalUnit(lower);
+        if (mappedUnit) {
+            periodUnit = mappedUnit;
+            partsToConsume.push(candidate);
+            break;
+        }
+        break;
+    }
+    if (!periodUnit) {
+        if (requiresPeriod) {
+            return false;
+        }
+        periodUnit = types_1.FhirPeriodUnit.Day;
+    }
+    if (requiresCue && !sawCue) {
+        return false;
+    }
+    internal.frequency = value;
+    internal.period = 1;
+    internal.periodUnit = periodUnit;
+    if (value === 1 && periodUnit === types_1.FhirPeriodUnit.Day && !internal.timingCode) {
+        internal.timingCode = "QD";
+    }
+    let consumeCurrentToken = true;
+    if (value === 1 && !sawConnectorWord && sawTimesWord && periodUnit !== types_1.FhirPeriodUnit.Day) {
+        consumeCurrentToken = false;
+    }
+    if (consumeCurrentToken) {
+        mark(internal.consumed, token);
+    }
+    for (const part of partsToConsume) {
+        mark(internal.consumed, part);
+    }
+    return consumeCurrentToken;
+}
 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"] },
@@ -1233,6 +1380,9 @@ function mapIntervalUnit(token) {
     }
     return undefined;
 }
+function mapFrequencyAdverb(token) {
+    return FREQUENCY_ADVERB_UNITS[token];
+}
 function parseNumericRange(token) {
     const rangeMatch = token.match(/^([0-9]+(?:\.[0-9]+)?)-([0-9]+(?:\.[0-9]+)?)$/);
     if (!rangeMatch) {
@@ -1609,6 +1759,9 @@ function parseInternal(input, options) {
             }
         }
         // Numeric dose
+        if (tryParseCountBasedFrequency(internal, tokens, i, options)) {
+            continue;
+        }
         const rangeValue = parseNumericRange(token.lower);
         if (rangeValue) {
             if (!internal.doseRange) {
@@ -1896,8 +2049,9 @@ function runSiteCodingResolutionSync(internal, options) {
         return;
     }
     const canonical = request.canonical;
+    const selection = pickSiteSelection(options === null || options === void 0 ? void 0 : options.siteCodeSelections, request);
     const customDefinition = lookupBodySiteDefinition(options === null || options === void 0 ? void 0 : options.siteCodeMap, canonical);
-    let resolution = customDefinition;
+    let resolution = selection !== null && selection !== void 0 ? selection : customDefinition;
     if (!resolution) {
         // Allow synchronous resolver callbacks to claim the site.
         for (const resolver of toArray(options === null || options === void 0 ? void 0 : options.siteCodeResolvers)) {
@@ -1927,6 +2081,9 @@ function runSiteCodingResolutionSync(internal, options) {
         return;
     }
     const suggestionMap = new Map();
+    if (selection) {
+        addSuggestionToMap(suggestionMap, definitionToSuggestion(selection));
+    }
     if (customDefinition) {
         addSuggestionToMap(suggestionMap, definitionToSuggestion(customDefinition));
     }
@@ -1959,8 +2116,9 @@ function runSiteCodingResolutionAsync(internal, options) {
             return;
         }
         const canonical = request.canonical;
+        const selection = pickSiteSelection(options === null || options === void 0 ? void 0 : options.siteCodeSelections, request);
         const customDefinition = lookupBodySiteDefinition(options === null || options === void 0 ? void 0 : options.siteCodeMap, canonical);
-        let resolution = customDefinition;
+        let resolution = selection !== null && selection !== void 0 ? selection : customDefinition;
         if (!resolution) {
             // Await asynchronous resolver callbacks (e.g., HTTP terminology services).
             for (const resolver of toArray(options === null || options === void 0 ? void 0 : options.siteCodeResolvers)) {
@@ -1986,6 +2144,9 @@ function runSiteCodingResolutionAsync(internal, options) {
             return;
         }
         const suggestionMap = new Map();
+        if (selection) {
+            addSuggestionToMap(suggestionMap, definitionToSuggestion(selection));
+        }
         if (customDefinition) {
             addSuggestionToMap(suggestionMap, definitionToSuggestion(customDefinition));
         }
@@ -2020,6 +2181,57 @@ function lookupBodySiteDefinition(map, canonical) {
         if ((0, maps_1.normalizeBodySiteKey)(key) === canonical) {
             return definition;
         }
+        if (definition.aliases) {
+            for (const alias of definition.aliases) {
+                if ((0, maps_1.normalizeBodySiteKey)(alias) === canonical) {
+                    return definition;
+                }
+            }
+        }
+    }
+    return undefined;
+}
+function pickSiteSelection(selections, request) {
+    if (!selections) {
+        return undefined;
+    }
+    const canonical = request.canonical;
+    const normalizedText = (0, maps_1.normalizeBodySiteKey)(request.text);
+    const requestRange = request.range;
+    for (const selection of toArray(selections)) {
+        if (!selection) {
+            continue;
+        }
+        let matched = false;
+        if (selection.range) {
+            if (!requestRange) {
+                continue;
+            }
+            if (selection.range.start !== requestRange.start ||
+                selection.range.end !== requestRange.end) {
+                continue;
+            }
+            matched = true;
+        }
+        if (selection.canonical) {
+            if ((0, maps_1.normalizeBodySiteKey)(selection.canonical) !== canonical) {
+                continue;
+            }
+            matched = true;
+        }
+        else if (selection.text) {
+            const normalizedSelection = (0, maps_1.normalizeBodySiteKey)(selection.text);
+            if (normalizedSelection !== canonical && normalizedSelection !== normalizedText) {
+                continue;
+            }
+            matched = true;
+        }
+        if (!selection.range && !selection.canonical && !selection.text) {
+            continue;
+        }
+        if (matched) {
+            return selection.resolution;
+        }
     }
     return undefined;
 }

package/dist/types.d.ts

@@ -297,6 +297,12 @@ export interface BodySiteCode {
 export interface BodySiteDefinition {
     coding: BodySiteCode;
     text?: string;
+    /**
+     * Optional phrases that should resolve to the same coding as this entry.
+     * Aliases are normalized with the same logic as map keys so callers can
+     * provide punctuation-heavy variants such as "first bicuspid, left".
+     */
+    aliases?: string[];
 }
 export interface TextRange {
     /** Inclusive start index of the matched substring within the original input. */
@@ -337,6 +343,24 @@ export interface SiteCodeSuggestion {
 export interface SiteCodeSuggestionsResult {
     suggestions: SiteCodeSuggestion[];
 }
+/**
+ * Allows callers to override the parser's automatic site resolution for a
+ * specific match. Matches can be scoped by the normalized phrase, the original
+ * sanitized text, or the exact character range that was detected.
+ */
+export interface SiteCodeSelection {
+    /** Canonical key (punctuation stripped, lower-case) that should trigger this selection. */
+    canonical?: string;
+    /**
+     * Human-friendly site text used to match the extracted phrase. It is
+     * normalized with the same logic as canonical keys.
+     */
+    text?: string;
+    /** Exact range of the detected phrase within the input string. */
+    range?: TextRange;
+    /** Desired coded definition to apply when the selection matches. */
+    resolution: SiteCodeResolution;
+}
 /**
  * Site code resolvers can perform deterministic lookups or remote queries with
  * access to the original sig text and extracted site range.
@@ -390,6 +414,12 @@ export interface ParseOptions extends FormatOptions {
      * the default site dictionary (trimmed, lower-cased, collapsing whitespace).
      */
     siteCodeMap?: Record<string, BodySiteDefinition>;
+    /**
+     * Explicit selections that override automatic site resolution for matching
+     * phrases. Useful when custom dictionaries provide multiple options but a UI
+     * workflow needs to pin a particular coding for a given match or range.
+     */
+    siteCodeSelections?: SiteCodeSelection | SiteCodeSelection[];
     /**
      * Callback(s) that can translate detected site text into a coded body site.
      * Return a promise when using asynchronous terminology services.

package/package.json

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