ezmedicationinput 0.1.45 → 0.1.47

package/dist/maps.d.ts

@@ -25,10 +25,11 @@ export declare const DEFAULT_ROUTE_SYNONYMS: Record<string, RouteSynonym>;
  * same logic to ensure consistent lookups.
  */
 export declare function normalizeBodySiteKey(value: string): string;
-export declare const DEFAULT_BODY_SITE_SNOMED_SOURCE: Array<{
+type BodySiteSnomedSourceEntry = {
     names: string[];
     definition: BodySiteDefinition;
-}>;
+};
+export declare const DEFAULT_BODY_SITE_SNOMED_SOURCE: BodySiteSnomedSourceEntry[];
 export declare const DEFAULT_BODY_SITE_SNOMED: Record<string, BodySiteDefinition>;
 export declare const DEFAULT_BODY_SITE_HINTS: Set<string>;
 export declare const HOUSEHOLD_VOLUME_UNITS: readonly ["tsp", "tbsp"];
@@ -80,3 +81,4 @@ export declare const DEFAULT_PRN_REASON_DEFINITIONS: Record<string, PrnReasonDef
  * Finds a default PRN reason definition by its SNOMED coding.
  */
 export declare function findPrnReasonDefinitionByCoding(system: string, code: string): PrnReasonDefinition | undefined;
+export {};

package/dist/parser-state.d.ts

@@ -1,5 +1,5 @@
 import { AnnotatedLexToken } from "./lexer/meaning";
-import { CanonicalAdditionalInstructionExpr, CanonicalDoseRange, CanonicalPrnReasonExpr, CanonicalSigClause, EventTiming, FhirCoding, FhirDayOfWeek, FhirPrimitiveElement, FhirPeriodUnit, PrnReasonLookupRequest, PrnReasonSuggestion, RouteCode, SiteCodeLookupRequest, SiteCodeSuggestion } from "./types";
+import { CanonicalAdditionalInstructionExpr, BodySiteSpatialRelation, CanonicalDoseRange, CanonicalPrnReasonExpr, CanonicalSigClause, EventTiming, FhirCoding, FhirDayOfWeek, FhirPrimitiveElement, FhirPeriodUnit, PrnReasonLookupRequest, PrnReasonSuggestion, RouteCode, SiteCodeLookupRequest, SiteCodeSuggestion } from "./types";
 export interface SiteLookupDetail {
     request: SiteCodeLookupRequest;
     suggestions: SiteCodeSuggestion[];
@@ -23,6 +23,7 @@ export declare class ParserState {
     siteLookups: SiteLookupDetail[];
     customSiteHints?: Set<string>;
     prnReasonLookupRequest?: PrnReasonLookupRequest;
+    prnReasonLookupRequests?: PrnReasonLookupRequest[];
     prnReasonLookups: PrnReasonLookupDetail[];
     methodVerb?: string;
     productFormKey?: string;
@@ -84,6 +85,8 @@ export declare class ParserState {
     set siteSource(value: "abbreviation" | "text" | "selection" | "resolver" | undefined);
     get siteCoding(): LocalizedCoding | undefined;
     set siteCoding(value: LocalizedCoding | undefined);
+    get siteSpatialRelation(): BodySiteSpatialRelation | undefined;
+    set siteSpatialRelation(value: BodySiteSpatialRelation | undefined);
     get additionalInstructions(): CanonicalAdditionalInstructionExpr[];
     set additionalInstructions(value: CanonicalAdditionalInstructionExpr[]);
     get patientInstruction(): string | undefined;

package/dist/parser.d.ts

@@ -1,20 +1,10 @@
 import { ParserState, Token } from "./parser-state";
+export { applyPrnReasonCoding, applyPrnReasonCodingAsync } from "./prn-reason-coding";
+export { applySiteCoding, applySiteCodingAsync } from "./site-coding";
 import { ParseOptions, TextRange } from "./types";
 export declare function tokenize(input: string): Token[];
-export declare function findUnparsedTokenGroups(internal: ParserState): Array<{
+export declare function findUnparsedTokenGroups(state: ParserState): Array<{
     tokens: Token[];
     range?: TextRange;
 }>;
 export declare function parseClauseState(input: string, options?: ParseOptions): ParserState;
-/**
- * Resolves parsed site text against SNOMED dictionaries and synchronous
- * callbacks, applying the best match to the in-progress parse result.
- */
-export declare function applyPrnReasonCoding(internal: ParserState, options?: ParseOptions): void;
-export declare function applyPrnReasonCodingAsync(internal: ParserState, options?: ParseOptions): Promise<void>;
-export declare function applySiteCoding(internal: ParserState, options?: ParseOptions): void;
-/**
- * Asynchronous counterpart to {@link applySiteCoding} that awaits resolver and
- * suggestion callbacks so remote terminology services can be used.
- */
-export declare function applySiteCodingAsync(internal: ParserState, options?: ParseOptions): Promise<void>;

package/dist/prn-reason-coding.d.ts

@@ -0,0 +1,8 @@
+import { ParserState } from "./parser-state";
+import { ParseOptions } from "./types";
+/**
+ * Resolves parsed PRN reason text against SNOMED dictionaries and synchronous
+ * callbacks, applying the best match to the in-progress parse result.
+ */
+export declare function applyPrnReasonCoding(internal: ParserState, options?: ParseOptions): void;
+export declare function applyPrnReasonCodingAsync(internal: ParserState, options?: ParseOptions): Promise<void>;

package/dist/site-coding.d.ts

@@ -0,0 +1,5 @@
+import { ParserState } from "./parser-state";
+import { BodySiteDefinition, ParseOptions } from "./types";
+export declare function applySiteCoding(internal: ParserState, options?: ParseOptions): void;
+export declare function applySiteCodingAsync(internal: ParserState, options?: ParseOptions): Promise<void>;
+export declare function lookupBodySiteDefinition(map: Record<string, BodySiteDefinition> | undefined, canonical: string): BodySiteDefinition | undefined;

package/dist/snomed-postcoordination.d.ts

@@ -0,0 +1,25 @@
+import { BodySiteSpatialRelation, FhirCoding } from "./types";
+export declare function hasSnomedFindingSitePostcoordination(code: string | undefined): boolean;
+export declare function buildSnomedFindingSitePostcoordinationCode(focusCode: string, siteCode: string): string;
+export declare function hasSnomedTopographicalModifierPostcoordination(code: string | undefined): boolean;
+export declare function buildSnomedBodySiteTopographicalModifierPostcoordinationCode(siteCode: string, modifierCode: string): string;
+export declare function hasSnomedBodySiteLateralityPostcoordination(code: string | undefined): boolean;
+export declare function buildSnomedBodySiteLateralityPostcoordinationCode(siteCode: string, lateralityCode: string): string;
+export declare function parseSnomedBodySiteTopographicalModifierPostcoordinationCode(code: string | undefined): {
+    siteCode: string;
+    modifierCode: string;
+} | undefined;
+export declare function parseSnomedBodySiteLateralityPostcoordinationCode(code: string | undefined): {
+    siteCode: string;
+    lateralityCode: string;
+} | undefined;
+export declare function parseSnomedFindingSitePostcoordinationCode(code: string | undefined): {
+    focusCode: string;
+    siteCode: string;
+} | undefined;
+export declare function buildSnomedFindingSiteCoding(params: {
+    focusCoding: FhirCoding | undefined;
+    siteCoding: FhirCoding | undefined;
+    display?: string;
+    spatialRelation?: BodySiteSpatialRelation;
+}): FhirCoding | undefined;

package/dist/snomed.d.ts

@@ -0,0 +1,13 @@
+export declare const SNOMED_SYSTEM = "http://snomed.info/sct";
+export declare const SNOMED_CT_FINDING_SITE_ATTRIBUTE_CODE = "363698007";
+export declare const SNOMED_CT_FINDING_SITE_ATTRIBUTE_DISPLAY = "Finding site";
+export declare const SNOMED_CT_TOPOGRAPHICAL_MODIFIER_CODE = "106233006";
+export declare const SNOMED_CT_TOPOGRAPHICAL_MODIFIER_DISPLAY = "Topographical modifier";
+export declare const SNOMED_CT_LATERALITY_ATTRIBUTE_CODE = "272741003";
+export declare const SNOMED_CT_LATERALITY_ATTRIBUTE_DISPLAY = "Laterality";
+export declare const SNOMED_CT_LEFT_QUALIFIER_CODE = "7771000";
+export declare const SNOMED_CT_LEFT_QUALIFIER_DISPLAY = "Left";
+export declare const SNOMED_CT_RIGHT_QUALIFIER_CODE = "24028007";
+export declare const SNOMED_CT_RIGHT_QUALIFIER_DISPLAY = "Right";
+export declare const SNOMED_CT_BILATERAL_QUALIFIER_CODE = "51440002";
+export declare const SNOMED_CT_BILATERAL_QUALIFIER_DISPLAY = "Right and left";

package/dist/types.d.ts

@@ -3,12 +3,14 @@ export interface FhirCoding {
     system?: string;
     code?: string;
     display?: string;
+    extension?: FhirExtension[];
     _display?: FhirPrimitiveElement;
     i18n?: Record<string, string>;
 }
 export interface FhirCodeableConcept {
     coding?: FhirCoding[];
     text?: string;
+    extension?: FhirExtension[];
     _text?: FhirPrimitiveElement;
 }
 export interface FhirExtension {
@@ -16,6 +18,8 @@ export interface FhirExtension {
     extension?: FhirExtension[];
     valueCode?: string;
     valueString?: string;
+    valueCoding?: FhirCoding;
+    valueCodeableConcept?: FhirCodeableConcept;
 }
 export interface FhirPrimitiveElement {
     extension?: FhirExtension[];
@@ -26,6 +30,38 @@ export interface FhirQuantity {
     system?: string;
     code?: string;
 }
+export type DoseUnitKind = "metric" | "biologic_unit" | "counted_presentation" | "device_actuation" | "infusion_rate" | "product_specific_amount" | "length_of_product" | "body_area_proxy" | "qualitative_amount";
+export type DoseUnitApproximationConfidence = "exact" | "approximate" | "product_specific";
+export interface DoseUnitApproximation {
+    value: number;
+    unit: string;
+    confidence: DoseUnitApproximationConfidence;
+    basis: string;
+    source?: string;
+}
+export interface DoseUnitTerminologyEntry {
+    unit: string;
+    kind: DoseUnitKind;
+    aliases?: string[];
+    /**
+     * Defaults to true. Use false for terminology entries such as infusion-rate
+     * units that should be exposed to consumers but must not be accepted as a
+     * doseQuantity unit until rateQuantity parsing is implemented.
+     */
+    parseAsDose?: boolean;
+    approximateQuantity?: DoseUnitApproximation;
+}
+export interface DoseUnitSemantics {
+    unit: string;
+    kind: DoseUnitKind;
+    parseAsDose?: boolean;
+    approximateQuantity?: DoseUnitApproximation;
+}
+export interface EstimatedQuantity extends FhirQuantity {
+    confidence?: DoseUnitApproximationConfidence;
+    basis?: string;
+    source?: string;
+}
 export interface FhirRange {
     low?: FhirQuantity;
     high?: FhirQuantity;
@@ -297,6 +333,12 @@ export type RouteCode = SNOMEDCTRouteCodes;
 export declare const RouteCode: typeof SNOMEDCTRouteCodes;
 export interface MedicationContext {
     dosageForm?: string;
+    /**
+     * Optional anatomical context used to disambiguate shorthand body-site
+     * phrases, e.g. Thai "ระหว่างนิ้ว" can mean fingers by default but toes
+     * when the active context is foot/feet/toes.
+     */
+    bodySiteContext?: string;
     /** "Simple" strength string; might be the only way strength is provided
      * for discrete units this is the amount of medication for unit e.g. "500 mg" (1 tablet), or for mixed tablets might be like "400 mg + 80 mg"
      * for things like creams or fluids or syrupsit might be "2%", 5 g/100g, 100mg/ 100 g, 262 mg/15 mL, 200 mg/2 mL, 1 mg/dL, or "400 mg/5mL + 80 mg/5mL"
@@ -306,6 +348,18 @@ export interface MedicationContext {
     strengthQuantity?: FhirQuantity;
     strengthRatio?: FhirRatio;
     strengthCodeableConcept?: FhirCodeableConcept;
+    /**
+     * Canonical presentation/package unit for fractional package instructions
+     * such as "1/2 bottle". When the parsed dose unit matches this value,
+     * containerValue/containerUnit describe the inner amount held by one package.
+     */
+    packageUnit?: string;
+    /**
+     * Optional per-unit approximation overrides keyed by normalized dose unit
+     * (for example FTU, drop, pump, applicatorful). These are used only for
+     * estimated amount reporting; they do not rewrite the parsed dose unit.
+     */
+    unitApproximationMap?: Record<string, DoseUnitApproximation>;
     containerValue?: number;
     containerUnit?: string;
     defaultUnit?: string;
@@ -339,9 +393,17 @@ export interface BodySiteCode {
     system?: string;
     i18n?: Record<string, string>;
 }
+export interface BodySiteSpatialRelation {
+    relationText: string;
+    relationCoding?: FhirCoding;
+    targetText?: string;
+    targetCoding?: BodySiteCode;
+    sourceText?: string;
+}
 export interface BodySiteDefinition {
     coding?: BodySiteCode;
     text?: string;
+    spatialRelation?: BodySiteSpatialRelation;
     routeHint?: RouteCode;
     /**
      * Optional phrases that should resolve to the same coding as this entry.
@@ -455,6 +517,12 @@ export interface SiteCodeLookupRequest {
     sourceText?: string;
     /** Location of {@link sourceText} relative to the original input. */
     range?: TextRange;
+    /**
+     * Parsed spatial relation when the site phrase is relation + body site
+     * (for example, "below ear" or "top of hand"). Terminology callbacks can
+     * use this to code either the full site phrase or the relation target.
+     */
+    spatialRelation?: BodySiteSpatialRelation;
 }
 export interface SiteCodeResolution extends BodySiteDefinition {
 }
@@ -465,11 +533,22 @@ export interface SiteCodeSuggestion {
 export interface SiteCodeSuggestionsResult {
     suggestions: SiteCodeSuggestion[];
 }
+/**
+ * PRN reason lookup context. For located reasons such as "pain at hand",
+ * `headCanonical` is the symptom head ("pain"), `locativeSiteCanonical` is the
+ * parsed site key when known ("hand"), `locativeSiteCoding` is preferred for
+ * coded SNOMED/FHIR output when present, and `locativeSiteSpatialRelation`
+ * carries modifiers such as "below ear" that refine the locative site.
+ */
 export interface PrnReasonLookupRequest {
     originalText: string;
     text: string;
     normalized: string;
     canonical: string;
+    headCanonical?: string;
+    locativeSiteCanonical?: string;
+    locativeSiteCoding?: FhirCoding;
+    locativeSiteSpatialRelation?: BodySiteSpatialRelation;
     isProbe: boolean;
     inputText: string;
     sourceText?: string;
@@ -606,6 +685,13 @@ export interface ParseOptions extends FormatOptions {
      * the default site dictionary (trimmed, lower-cased, collapsing whitespace).
      */
     siteCodeMap?: Record<string, BodySiteDefinition>;
+    /**
+     * Defaults to true. When true, parsed spatial body-site phrases without a
+     * direct pre-coordinated site code may emit SNOMED topographical modifier
+     * postcoordination in FHIR Dosage.site.coding while preserving the structured
+     * spatial-relation extension.
+     */
+    bodySitePostcoordination?: boolean;
     /**
      * Explicit selections that override automatic site resolution for matching
      * phrases. Useful when custom dictionaries provide multiple options but a UI
@@ -660,6 +746,7 @@ export interface CanonicalRouteExpr {
 export interface CanonicalSiteExpr {
     text?: string;
     coding?: BodySiteCode;
+    spatialRelation?: BodySiteSpatialRelation;
     source?: "abbreviation" | "text" | "selection" | "resolver";
     inferred?: boolean;
     evidence?: CanonicalEvidence[];
@@ -689,6 +776,7 @@ export interface CanonicalScheduleExpr {
 export interface CanonicalPrnReasonExpr {
     text?: string;
     coding?: FhirCoding;
+    spatialRelation?: BodySiteSpatialRelation;
 }
 export interface CanonicalPrnExpr {
     enabled: boolean;
@@ -755,28 +843,31 @@ export interface ParseResult {
 export interface ParseNormalizedMeta {
     route?: RouteCode;
     unit?: string;
-    site?: {
-        text?: string;
-        coding?: BodySiteCode;
-    };
+    unitKind?: DoseUnitKind;
+    unitSemantics?: DoseUnitSemantics;
+    site?: BodySiteDetail;
     method?: {
         text?: string;
         coding?: FhirCoding;
     };
     patientInstruction?: string;
-    prnReason?: {
-        text?: string;
-        coding?: FhirCoding;
-    };
-    prnReasons?: Array<{
-        text?: string;
-        coding?: FhirCoding;
-    }>;
+    prnReason?: ConceptSiteDetail;
+    prnReasons?: ConceptSiteDetail[];
     additionalInstructions?: Array<{
         text?: string;
         coding?: FhirCoding;
     }>;
 }
+export interface BodySiteDetail {
+    text?: string;
+    coding?: BodySiteCode;
+    spatialRelation?: BodySiteSpatialRelation;
+}
+export interface ConceptSiteDetail {
+    text?: string;
+    coding?: FhirCoding;
+    spatialRelation?: BodySiteSpatialRelation;
+}
 export interface ParseBatchSegmentMeta {
     index: number;
     text: string;
@@ -787,17 +878,17 @@ export interface ParseBatchResult {
     count: number;
     items: ParseResult[];
     /**
-     * Legacy compatibility field mirroring the first parsed item so existing
+     * Top-level compatibility field mirroring the first parsed item so existing
      * single-sig integrations can migrate incrementally.
      */
     fhir: FhirDosage;
     /**
-     * Legacy compatibility field mirroring the first parsed item so existing
+     * Top-level compatibility field mirroring the first parsed item so existing
      * single-sig integrations can migrate incrementally.
      */
     shortText: string;
     /**
-     * Legacy compatibility field mirroring the first parsed item so existing
+     * Top-level compatibility field mirroring the first parsed item so existing
      * single-sig integrations can migrate incrementally.
      */
     longText: string;
@@ -841,7 +932,7 @@ export interface LintBatchResult {
     count: number;
     items: LintResult[];
     /**
-     * Legacy compatibility fields mirroring the first parsed item so existing
+     * Top-level compatibility fields mirroring the first parsed item so existing
      * consumers of `lintSig` can migrate incrementally.
      */
     result: ParseResult;
@@ -894,6 +985,9 @@ export interface NextDueDoseOptions {
 export interface TotalUnitsResult {
     totalUnits: number;
     totalContainers?: number;
+    totalContainerQuantity?: FhirQuantity;
+    totalApproximateQuantity?: EstimatedQuantity;
+    totalApproximateIngredientQuantity?: EstimatedQuantity;
 }
 export interface TotalUnitsOptions extends NextDueDoseOptions {
     dosage: FhirDosage | FhirDosage[];

package/dist/unit-lexicon.d.ts

@@ -0,0 +1,8 @@
+import type { DoseUnitApproximation, DoseUnitKind, DoseUnitSemantics, DoseUnitTerminologyEntry, MedicationContext, ParseOptions } from "./types";
+export declare function normalizeUnit(token: string, options?: ParseOptions): string | undefined;
+export declare function getDoseUnitKind(unit: string | undefined): DoseUnitKind | undefined;
+export declare function getDoseUnitApproximation(unit: string | undefined, context?: MedicationContext | null): DoseUnitApproximation | undefined;
+export declare function getDoseUnitSemantics(unit: string | undefined, context?: MedicationContext | null): DoseUnitSemantics | undefined;
+export declare function listDoseUnitTerminology(): DoseUnitTerminologyEntry[];
+export declare function enforceHouseholdUnitPolicy(unit: string | undefined, options?: ParseOptions): string | undefined;
+export declare function isDiscreteUnit(unit: string): boolean;

package/package.json

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

package/dist/segment.d.ts

@@ -1,6 +0,0 @@
-export interface SigSegment {
-    text: string;
-    start: number;
-    end: number;
-}
-export declare function splitSigSegments(input: string): SigSegment[];