ezmedicationinput 0.1.9 → 0.1.11

package/dist/parser.js

@@ -1,13 +1,25 @@
 "use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.tokenize = tokenize;
 exports.parseInternal = parseInternal;
+exports.applySiteCoding = applySiteCoding;
+exports.applySiteCodingAsync = applySiteCodingAsync;
 const maps_1 = require("./maps");
 const context_1 = require("./context");
 const safety_1 = require("./safety");
 const types_1 = require("./types");
 const object_1 = require("./utils/object");
 const array_1 = require("./utils/array");
+const SNOMED_SYSTEM = "http://snomed.info/sct";
 const BODY_SITE_HINTS = new Set([
     "left",
     "right",
@@ -66,10 +78,14 @@ const BODY_SITE_HINTS = new Set([
     "veins",
     "vagina",
     "vaginal",
+    "penis",
+    "penile",
     "rectum",
     "rectal",
     "anus",
-    "perineum"
+    "perineum",
+    "temple",
+    "temples"
 ]);
 const SITE_CONNECTORS = new Set(["to", "in", "into", "on", "onto", "at"]);
 const SITE_FILLER_WORDS = new Set([
@@ -241,7 +257,7 @@ const OPHTHALMIC_CONTEXT_TOKENS = new Set([
     "be"
 ]);
 function normalizeTokenLower(token) {
-    return token.lower.replace(/\./g, "");
+    return token.lower.replace(/[.{}]/g, "");
 }
 function hasOphthalmicContextHint(tokens, index) {
     for (let offset = -3; offset <= 3; offset++) {
@@ -605,6 +621,68 @@ function tokenize(input) {
     }
     return tokens;
 }
+/**
+ * Locates the span of the detected site tokens within the caller's original
+ * input so downstream consumers can highlight or replace the exact substring.
+ */
+function computeSiteTextRange(input, tokens, indices) {
+    if (!indices.length) {
+        return undefined;
+    }
+    const lowerInput = input.toLowerCase();
+    let searchStart = 0;
+    let rangeStart;
+    let rangeEnd;
+    for (const tokenIndex of indices) {
+        const token = tokens[tokenIndex];
+        if (!token) {
+            continue;
+        }
+        const segment = token.original.trim();
+        if (!segment) {
+            continue;
+        }
+        const lowerSegment = segment.toLowerCase();
+        const foundIndex = lowerInput.indexOf(lowerSegment, searchStart);
+        if (foundIndex === -1) {
+            return undefined;
+        }
+        const segmentEnd = foundIndex + lowerSegment.length;
+        if (rangeStart === undefined) {
+            rangeStart = foundIndex;
+        }
+        rangeEnd = segmentEnd;
+        searchStart = segmentEnd;
+    }
+    if (rangeStart === undefined || rangeEnd === undefined) {
+        return undefined;
+    }
+    return { start: rangeStart, end: rangeEnd };
+}
+/**
+ * Prefers highlighting the sanitized site text when it can be located directly
+ * in the original input; otherwise falls back to the broader token-derived
+ * range.
+ */
+function refineSiteRange(input, sanitized, tokenRange) {
+    if (!input) {
+        return tokenRange;
+    }
+    const trimmed = sanitized.trim();
+    if (!trimmed) {
+        return tokenRange;
+    }
+    const lowerInput = input.toLowerCase();
+    const lowerSanitized = trimmed.toLowerCase();
+    let startIndex = tokenRange ? lowerInput.indexOf(lowerSanitized, tokenRange.start) : -1;
+    if (startIndex === -1) {
+        startIndex = lowerInput.indexOf(lowerSanitized);
+    }
+    if (startIndex === -1) {
+        return tokenRange;
+    }
+    return { start: startIndex, end: startIndex + lowerSanitized.length };
+}
 function splitToken(token) {
     if (/^[0-9]+(?:\.[0-9]+)?$/.test(token)) {
         return [token];
@@ -1169,7 +1247,8 @@ function parseInternal(input, options) {
         dayOfWeek: [],
         when: [],
         warnings: [],
-        siteTokenIndices: new Set()
+        siteTokenIndices: new Set(),
+        siteLookups: []
     };
     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)
@@ -1630,7 +1709,8 @@ function parseInternal(input, options) {
     const leftoverTokens = tokens.filter((t) => !internal.consumed.has(t.index));
     const siteCandidateIndices = new Set();
     for (const token of leftoverTokens) {
-        if (BODY_SITE_HINTS.has(token.lower)) {
+        const normalized = normalizeTokenLower(token);
+        if (BODY_SITE_HINTS.has(normalized)) {
             siteCandidateIndices.add(token.index);
         }
     }
@@ -1646,7 +1726,7 @@ function parseInternal(input, options) {
                 if (!token) {
                     break;
                 }
-                const lower = token.lower;
+                const lower = normalizeTokenLower(token);
                 if (SITE_CONNECTORS.has(lower) ||
                     BODY_SITE_HINTS.has(lower) ||
                     ROUTE_DESCRIPTOR_FILLER_WORDS.has(lower)) {
@@ -1662,7 +1742,7 @@ function parseInternal(input, options) {
                 if (!token) {
                     break;
                 }
-                const lower = token.lower;
+                const lower = normalizeTokenLower(token);
                 if (SITE_CONNECTORS.has(lower) ||
                     BODY_SITE_HINTS.has(lower) ||
                     ROUTE_DESCRIPTOR_FILLER_WORDS.has(lower)) {
@@ -1680,8 +1760,10 @@ function parseInternal(input, options) {
             if (!token) {
                 continue;
             }
-            const lower = token.lower;
-            if (!SITE_CONNECTORS.has(lower) && !SITE_FILLER_WORDS.has(lower)) {
+            const lower = normalizeTokenLower(token);
+            const trimmed = token.original.trim();
+            const isBraceToken = trimmed.length > 0 && /^[{}]+$/.test(trimmed);
+            if (!isBraceToken && !SITE_CONNECTORS.has(lower) && !SITE_FILLER_WORDS.has(lower)) {
                 displayWords.push(token.original);
             }
             mark(internal.consumed, token);
@@ -1691,16 +1773,45 @@ function parseInternal(input, options) {
             .join(" ")
             .trim();
         if (normalizedSite) {
-            const normalizedLower = normalizedSite.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 shouldAttemptRouteDescriptor = strippedDescriptor !== normalizedLower || hasNonSiteWords || strippedDescriptor === "mouth";
-            const appliedRouteDescriptor = shouldAttemptRouteDescriptor && maybeApplyRouteDescriptor(normalizedSite);
-            if (!appliedRouteDescriptor) {
-                internal.siteText = normalizedSite;
-                if (!internal.siteSource) {
-                    internal.siteSource = "text";
+            const tokenRange = computeSiteTextRange(internal.input, tokens, sortedIndices);
+            let sanitized = normalizedSite;
+            let isProbe = false;
+            const probeMatch = sanitized.match(/^\{(.+)}$/);
+            if (probeMatch) {
+                // `{site}` placeholders flag interactive lookups so consumers can prompt
+                // for a coded selection even when the parser cannot resolve the entry.
+                isProbe = true;
+                sanitized = probeMatch[1];
+            }
+            // Remove stray braces and normalize whitespace so lookups and downstream
+            // displays operate on a clean phrase.
+            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;
+            internal.siteLookupRequest = {
+                originalText: normalizedSite,
+                text: sanitized,
+                normalized: sanitized.toLowerCase(),
+                canonical: sanitized ? (0, maps_1.normalizeBodySiteKey)(sanitized) : "",
+                isProbe,
+                inputText: internal.input,
+                sourceText,
+                range
+            };
+            if (sanitized) {
+                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 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;
+                    if (!internal.siteSource) {
+                        internal.siteSource = "text";
+                    }
                 }
             }
         }
@@ -1734,6 +1845,249 @@ function parseInternal(input, options) {
     }
     return internal;
 }
+/**
+ * Resolves parsed site text against SNOMED dictionaries and synchronous
+ * callbacks, applying the best match to the in-progress parse result.
+ */
+function applySiteCoding(internal, options) {
+    runSiteCodingResolutionSync(internal, options);
+}
+/**
+ * Asynchronous counterpart to {@link applySiteCoding} that awaits resolver and
+ * suggestion callbacks so remote terminology services can be used.
+ */
+function applySiteCodingAsync(internal, options) {
+    return __awaiter(this, void 0, void 0, function* () {
+        yield runSiteCodingResolutionAsync(internal, options);
+    });
+}
+/**
+ * Attempts to resolve site codings using built-in dictionaries followed by any
+ * provided synchronous resolvers. Suggestions are collected when resolution
+ * fails or a `{probe}` placeholder requested an interactive lookup.
+ */
+function runSiteCodingResolutionSync(internal, options) {
+    internal.siteLookups = [];
+    const request = internal.siteLookupRequest;
+    if (!request) {
+        return;
+    }
+    const canonical = request.canonical;
+    const customDefinition = lookupBodySiteDefinition(options === null || options === void 0 ? void 0 : options.siteCodeMap, canonical);
+    let resolution = 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)) {
+            const result = resolver(request);
+            if (isPromise(result)) {
+                throw new Error("Site code resolver returned a Promise; use parseSigAsync for asynchronous site resolution.");
+            }
+            if (result) {
+                resolution = result;
+                break;
+            }
+        }
+    }
+    const defaultDefinition = canonical ? maps_1.DEFAULT_BODY_SITE_SNOMED[canonical] : undefined;
+    if (!resolution && defaultDefinition) {
+        // Fall back to bundled SNOMED lookups when no overrides claim the site.
+        resolution = defaultDefinition;
+    }
+    if (resolution) {
+        applySiteDefinition(internal, resolution);
+    }
+    else {
+        internal.siteCoding = undefined;
+    }
+    const needsSuggestions = request.isProbe || !resolution;
+    if (!needsSuggestions) {
+        return;
+    }
+    const suggestionMap = new Map();
+    if (customDefinition) {
+        addSuggestionToMap(suggestionMap, definitionToSuggestion(customDefinition));
+    }
+    if (defaultDefinition) {
+        addSuggestionToMap(suggestionMap, definitionToSuggestion(defaultDefinition));
+    }
+    for (const resolver of toArray(options === null || options === void 0 ? void 0 : options.siteCodeSuggestionResolvers)) {
+        // Aggregates resolver suggestions while guarding against accidental async
+        // usage, mirroring the behavior of site resolvers.
+        const result = resolver(request);
+        if (isPromise(result)) {
+            throw new Error("Site code suggestion resolver returned a Promise; use parseSigAsync for asynchronous site suggestions.");
+        }
+        collectSuggestionResult(suggestionMap, result);
+    }
+    const suggestions = Array.from(suggestionMap.values());
+    if (suggestions.length || request.isProbe) {
+        internal.siteLookups.push({ request, suggestions });
+    }
+}
+/**
+ * Async version of {@link runSiteCodingResolutionSync} that awaits resolver
+ * results and suggestion providers, enabling remote terminology services.
+ */
+function runSiteCodingResolutionAsync(internal, options) {
+    return __awaiter(this, void 0, void 0, function* () {
+        internal.siteLookups = [];
+        const request = internal.siteLookupRequest;
+        if (!request) {
+            return;
+        }
+        const canonical = request.canonical;
+        const customDefinition = lookupBodySiteDefinition(options === null || options === void 0 ? void 0 : options.siteCodeMap, canonical);
+        let resolution = 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)) {
+                const result = yield resolver(request);
+                if (result) {
+                    resolution = result;
+                    break;
+                }
+            }
+        }
+        const defaultDefinition = canonical ? maps_1.DEFAULT_BODY_SITE_SNOMED[canonical] : undefined;
+        if (!resolution && defaultDefinition) {
+            resolution = defaultDefinition;
+        }
+        if (resolution) {
+            applySiteDefinition(internal, resolution);
+        }
+        else {
+            internal.siteCoding = undefined;
+        }
+        const needsSuggestions = request.isProbe || !resolution;
+        if (!needsSuggestions) {
+            return;
+        }
+        const suggestionMap = new Map();
+        if (customDefinition) {
+            addSuggestionToMap(suggestionMap, definitionToSuggestion(customDefinition));
+        }
+        if (defaultDefinition) {
+            addSuggestionToMap(suggestionMap, definitionToSuggestion(defaultDefinition));
+        }
+        for (const resolver of toArray(options === null || options === void 0 ? void 0 : options.siteCodeSuggestionResolvers)) {
+            // Async suggestion providers are awaited, allowing UI workflows to fetch
+            // candidate codes on demand.
+            const result = yield resolver(request);
+            collectSuggestionResult(suggestionMap, result);
+        }
+        const suggestions = Array.from(suggestionMap.values());
+        if (suggestions.length || request.isProbe) {
+            internal.siteLookups.push({ request, suggestions });
+        }
+    });
+}
+/**
+ * Looks up a body-site definition in a caller-provided map, honoring both
+ * direct keys and entries that normalize to the same canonical phrase.
+ */
+function lookupBodySiteDefinition(map, canonical) {
+    if (!map) {
+        return undefined;
+    }
+    const direct = map[canonical];
+    if (direct) {
+        return direct;
+    }
+    for (const [key, definition] of (0, object_1.objectEntries)(map)) {
+        if ((0, maps_1.normalizeBodySiteKey)(key) === canonical) {
+            return definition;
+        }
+    }
+    return undefined;
+}
+/**
+ * Applies the selected body-site definition onto the parser state, defaulting
+ * the coding system to SNOMED CT when the definition omits one.
+ */
+function applySiteDefinition(internal, definition) {
+    var _a;
+    const coding = definition.coding;
+    internal.siteCoding = {
+        code: coding.code,
+        display: coding.display,
+        system: (_a = coding.system) !== null && _a !== void 0 ? _a : SNOMED_SYSTEM
+    };
+    if (definition.text) {
+        internal.siteText = definition.text;
+    }
+}
+/**
+ * Converts a body-site definition into a suggestion payload so all suggestion
+ * sources share consistent structure.
+ */
+function definitionToSuggestion(definition) {
+    var _a;
+    return {
+        coding: {
+            code: definition.coding.code,
+            display: definition.coding.display,
+            system: (_a = definition.coding.system) !== null && _a !== void 0 ? _a : SNOMED_SYSTEM
+        },
+        text: definition.text
+    };
+}
+/**
+ * Inserts a suggestion into a deduplicated map keyed by system and code.
+ */
+function addSuggestionToMap(map, suggestion) {
+    var _a, _b;
+    if (!suggestion) {
+        return;
+    }
+    const coding = suggestion.coding;
+    if (!(coding === null || coding === void 0 ? void 0 : coding.code)) {
+        return;
+    }
+    const key = `${(_a = coding.system) !== null && _a !== void 0 ? _a : SNOMED_SYSTEM}|${coding.code}`;
+    if (!map.has(key)) {
+        map.set(key, {
+            coding: {
+                code: coding.code,
+                display: coding.display,
+                system: (_b = coding.system) !== null && _b !== void 0 ? _b : SNOMED_SYSTEM
+            },
+            text: suggestion.text
+        });
+    }
+}
+/**
+ * Normalizes resolver outputs into a consistent array before merging them into
+ * the suggestion map.
+ */
+function collectSuggestionResult(map, result) {
+    if (!result) {
+        return;
+    }
+    const suggestions = Array.isArray(result)
+        ? result
+        : typeof result === "object" && "suggestions" in result
+            ? result.suggestions
+            : [result];
+    for (const suggestion of suggestions) {
+        addSuggestionToMap(map, suggestion);
+    }
+}
+/**
+ * Wraps scalar or array configuration into an array to simplify iteration.
+ */
+function toArray(value) {
+    if (!value) {
+        return [];
+    }
+    return Array.isArray(value) ? value : [value];
+}
+/**
+ * Detects thenables without relying on `instanceof Promise`, which can break
+ * across execution contexts.
+ */
+function isPromise(value) {
+    return !!value && typeof value.then === "function";
+}
 function normalizeUnit(token, options) {
     var _a;
     const override = enforceHouseholdUnitPolicy((_a = options === null || options === void 0 ? void 0 : options.unitMap) === null || _a === void 0 ? void 0 : _a[token], options);

package/dist/types.d.ts

@@ -289,6 +289,64 @@ export interface FormatOptions {
     locale?: "en" | "th" | string;
     i18n?: SigTranslationConfig;
 }
+export interface BodySiteCode {
+    code: string;
+    display?: string;
+    system?: string;
+}
+export interface BodySiteDefinition {
+    coding: BodySiteCode;
+    text?: string;
+}
+export interface TextRange {
+    /** Inclusive start index of the matched substring within the original input. */
+    start: number;
+    /** Exclusive end index of the matched substring within the original input. */
+    end: number;
+}
+export interface SiteCodeLookupRequest {
+    /** Original site text preserved for debugging or auditing. */
+    originalText: string;
+    /**
+     * Sanitized site text used for human-readable output. Connectors and braces
+     * are stripped but casing is preserved.
+     */
+    text: string;
+    /** Lower-case variant of the text for case-insensitive lookups. */
+    normalized: string;
+    /** Canonical key generated by trimming and collapsing whitespace. */
+    canonical: string;
+    /** Indicates the text was wrapped in `{}` to request interactive lookup. */
+    isProbe: boolean;
+    /** Full original input string provided to the parser. */
+    inputText: string;
+    /**
+     * Substring captured directly from the original input, preserving spacing and
+     * casing. Undefined when a reliable slice cannot be determined.
+     */
+    sourceText?: string;
+    /** Location of {@link sourceText} relative to the original input. */
+    range?: TextRange;
+}
+export interface SiteCodeResolution extends BodySiteDefinition {
+}
+export interface SiteCodeSuggestion {
+    coding: BodySiteCode;
+    text?: string;
+}
+export interface SiteCodeSuggestionsResult {
+    suggestions: SiteCodeSuggestion[];
+}
+/**
+ * Site code resolvers can perform deterministic lookups or remote queries with
+ * access to the original sig text and extracted site range.
+ */
+export type SiteCodeResolver = (request: SiteCodeLookupRequest) => SiteCodeResolution | null | undefined | Promise<SiteCodeResolution | null | undefined>;
+/**
+ * Suggestion providers receive the same context as resolvers, including the
+ * caller's full input and the character range of the detected site phrase.
+ */
+export type SiteCodeSuggestionResolver = (request: SiteCodeLookupRequest) => SiteCodeSuggestionsResult | SiteCodeSuggestion[] | SiteCodeSuggestion | null | undefined | Promise<SiteCodeSuggestionsResult | SiteCodeSuggestion[] | SiteCodeSuggestion | null | undefined>;
 export interface ParseOptions extends FormatOptions {
     /**
      * Optional medication context that assists with default unit inference.
@@ -326,6 +384,23 @@ export interface ParseOptions extends FormatOptions {
      * and tablespoon when set to false. Defaults to true.
      */
     allowHouseholdVolumeUnits?: boolean;
+    /**
+     * Allows mapping normalized site phrases (e.g., "left arm") to
+     * institution-specific codings. Keys are normalized with the same logic as
+     * the default site dictionary (trimmed, lower-cased, collapsing whitespace).
+     */
+    siteCodeMap?: Record<string, BodySiteDefinition>;
+    /**
+     * Callback(s) that can translate detected site text into a coded body site.
+     * Return a promise when using asynchronous terminology services.
+     */
+    siteCodeResolvers?: SiteCodeResolver | SiteCodeResolver[];
+    /**
+     * Callback(s) that surface possible coded body sites for interactive flows
+     * when the parser cannot confidently resolve a site, or the input explicitly
+     * requested a lookup via `{site}` placeholders.
+     */
+    siteCodeSuggestionResolvers?: SiteCodeSuggestionResolver | SiteCodeSuggestionResolver[];
 }
 export interface ParseResult {
     fhir: FhirDosage;
@@ -338,7 +413,15 @@ export interface ParseResult {
         normalized: {
             route?: RouteCode;
             unit?: string;
+            site?: {
+                text?: string;
+                coding?: BodySiteCode;
+            };
         };
+        siteLookups?: Array<{
+            request: SiteCodeLookupRequest;
+            suggestions: SiteCodeSuggestion[];
+        }>;
     };
 }
 /**

package/package.json

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