ezmedicationinput 0.1.12 → 0.1.14

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/internal-types.d.ts

@@ -38,4 +38,5 @@ export interface ParsedSigInternal {
     siteCoding?: FhirCoding;
     siteLookupRequest?: SiteCodeLookupRequest;
     siteLookups: SiteLookupDetail[];
+    customSiteHints?: Set<string>;
 }

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

@@ -20,6 +20,39 @@ const types_1 = require("./types");
 const object_1 = require("./utils/object");
 const array_1 = require("./utils/array");
 const SNOMED_SYSTEM = "http://snomed.info/sct";
+function buildCustomSiteHints(map) {
+    if (!map) {
+        return undefined;
+    }
+    const hints = new Set();
+    const addPhraseHints = (phrase) => {
+        if (!phrase) {
+            return;
+        }
+        const normalized = (0, maps_1.normalizeBodySiteKey)(phrase);
+        if (!normalized) {
+            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;
+}
+function isBodySiteHint(word, customSiteHints) {
+    var _a;
+    return BODY_SITE_HINTS.has(word) || ((_a = customSiteHints === null || customSiteHints === void 0 ? void 0 : customSiteHints.has(word)) !== null && _a !== void 0 ? _a : false);
+}
 const BODY_SITE_HINTS = new Set([
     "left",
     "right",
@@ -362,7 +395,7 @@ function hasBodySiteContextBefore(internal, tokens, index) {
             continue;
         }
         const normalized = normalizeTokenLower(token);
-        if (BODY_SITE_HINTS.has(normalized)) {
+        if (isBodySiteHint(normalized, internal.customSiteHints)) {
             return true;
         }
         if (EYE_SITE_TOKENS[normalized]) {
@@ -399,7 +432,7 @@ function hasBodySiteContextAfter(internal, tokens, index) {
         if (SITE_FILLER_WORDS.has(normalized)) {
             continue;
         }
-        if (BODY_SITE_HINTS.has(normalized)) {
+        if (isBodySiteHint(normalized, internal.customSiteHints)) {
             return true;
         }
         if (seenConnector) {
@@ -481,7 +514,7 @@ function shouldTreatEyeTokenAsSite(internal, tokens, index, context) {
         if (SITE_CONNECTORS.has(normalized)) {
             continue;
         }
-        if (BODY_SITE_HINTS.has(normalized)) {
+        if (isBodySiteHint(normalized, internal.customSiteHints)) {
             return false;
         }
         if (EYE_SITE_TOKENS[normalized]) {
@@ -1248,7 +1281,8 @@ function parseInternal(input, options) {
         when: [],
         warnings: [],
         siteTokenIndices: new Set(),
-        siteLookups: []
+        siteLookups: [],
+        customSiteHints: buildCustomSiteHints(options === null || options === void 0 ? void 0 : options.siteCodeMap)
     };
     const context = (_a = options === null || options === void 0 ? void 0 : options.context) !== null && _a !== void 0 ? _a : undefined;
     const customRouteMap = (options === null || options === void 0 ? void 0 : options.routeMap)
@@ -1366,7 +1400,7 @@ function parseInternal(input, options) {
                 setRoute(internal, synonym.code, synonym.text);
                 for (const part of slice) {
                     mark(internal.consumed, part);
-                    if (BODY_SITE_HINTS.has(part.lower)) {
+                    if (isBodySiteHint(part.lower, internal.customSiteHints)) {
                         internal.siteTokenIndices.add(part.index);
                     }
                 }
@@ -1710,7 +1744,7 @@ function parseInternal(input, options) {
     const siteCandidateIndices = new Set();
     for (const token of leftoverTokens) {
         const normalized = normalizeTokenLower(token);
-        if (BODY_SITE_HINTS.has(normalized)) {
+        if (isBodySiteHint(normalized, internal.customSiteHints)) {
             siteCandidateIndices.add(token.index);
         }
     }
@@ -1728,7 +1762,7 @@ function parseInternal(input, options) {
                 }
                 const lower = normalizeTokenLower(token);
                 if (SITE_CONNECTORS.has(lower) ||
-                    BODY_SITE_HINTS.has(lower) ||
+                    isBodySiteHint(lower, internal.customSiteHints) ||
                     ROUTE_DESCRIPTOR_FILLER_WORDS.has(lower)) {
                     indicesToInclude.add(token.index);
                     prev -= 1;
@@ -1744,7 +1778,7 @@ function parseInternal(input, options) {
                 }
                 const lower = normalizeTokenLower(token);
                 if (SITE_CONNECTORS.has(lower) ||
-                    BODY_SITE_HINTS.has(lower) ||
+                    isBodySiteHint(lower, internal.customSiteHints) ||
                     ROUTE_DESCRIPTOR_FILLER_WORDS.has(lower)) {
                     indicesToInclude.add(token.index);
                     next += 1;
@@ -1802,7 +1836,7 @@ function parseInternal(input, options) {
                 const normalizedLower = sanitized.toLowerCase();
                 const strippedDescriptor = normalizeRouteDescriptorPhrase(normalizedLower);
                 const siteWords = normalizedLower.split(/\s+/).filter((word) => word.length > 0);
-                const hasNonSiteWords = siteWords.some((word) => !BODY_SITE_HINTS.has(word));
+                const hasNonSiteWords = siteWords.some((word) => !isBodySiteHint(word, internal.customSiteHints));
                 const shouldAttemptRouteDescriptor = strippedDescriptor !== normalizedLower || hasNonSiteWords || strippedDescriptor === "mouth";
                 const appliedRouteDescriptor = shouldAttemptRouteDescriptor && maybeApplyRouteDescriptor(sanitized);
                 if (!appliedRouteDescriptor) {
@@ -1873,8 +1907,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)) {
@@ -1904,6 +1939,9 @@ function runSiteCodingResolutionSync(internal, options) {
         return;
     }
     const suggestionMap = new Map();
+    if (selection) {
+        addSuggestionToMap(suggestionMap, definitionToSuggestion(selection));
+    }
     if (customDefinition) {
         addSuggestionToMap(suggestionMap, definitionToSuggestion(customDefinition));
     }
@@ -1936,8 +1974,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)) {
@@ -1963,6 +2002,9 @@ function runSiteCodingResolutionAsync(internal, options) {
             return;
         }
         const suggestionMap = new Map();
+        if (selection) {
+            addSuggestionToMap(suggestionMap, definitionToSuggestion(selection));
+        }
         if (customDefinition) {
             addSuggestionToMap(suggestionMap, definitionToSuggestion(customDefinition));
         }
@@ -1997,6 +2039,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.12",
+  "version": "0.1.14",
   "description": "Parse concise medication sigs into FHIR R5 Dosage JSON",
   "type": "module",
   "main": "dist/index.js",