ezmedicationinput 0.1.13 → 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/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;
 }
@@ -1896,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)) {
@@ -1927,6 +1939,9 @@ function runSiteCodingResolutionSync(internal, options) {
         return;
     }
     const suggestionMap = new Map();
+    if (selection) {
+        addSuggestionToMap(suggestionMap, definitionToSuggestion(selection));
+    }
     if (customDefinition) {
         addSuggestionToMap(suggestionMap, definitionToSuggestion(customDefinition));
     }
@@ -1959,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)) {
@@ -1986,6 +2002,9 @@ function runSiteCodingResolutionAsync(internal, options) {
             return;
         }
         const suggestionMap = new Map();
+        if (selection) {
+            addSuggestionToMap(suggestionMap, definitionToSuggestion(selection));
+        }
         if (customDefinition) {
             addSuggestionToMap(suggestionMap, definitionToSuggestion(customDefinition));
         }
@@ -2020,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.13",
+  "version": "0.1.14",
   "description": "Parse concise medication sigs into FHIR R5 Dosage JSON",
   "type": "module",
   "main": "dist/index.js",