gdc-common-utils-ts 2.3.17 → 2.3.18

package/dist/models/index.d.ts

@@ -49,6 +49,7 @@ export * from './relationship-access';
 export * from './response';
 export * from './subject-identifier-ledger';
 export * from './subject-identity-binding';
+export * from './terminology';
 export * from './urlPath';
 export * from './verifiable-credential';
 export * from './wallet';

package/dist/models/index.js

@@ -49,6 +49,7 @@ export * from './relationship-access.js';
 export * from './response.js';
 export * from './subject-identifier-ledger.js';
 export * from './subject-identity-binding.js';
+export * from './terminology.js';
 export * from './urlPath.js';
 export * from './verifiable-credential.js';
 export * from './wallet.js';

package/dist/models/terminology.d.ts

@@ -0,0 +1,59 @@
+/**
+ * One terminology block in the legacy JSON catalog format.
+ *
+ * `id` is normally the canonical coding-system URI. The compatibility alias
+ * `ips` is accepted for the SNOMED IPS catalog used by
+ * the predecessor FHIR utility package.
+ */
+export type TerminologyCatalogResource = Readonly<{
+    id: string;
+    language?: string;
+    attributes: Readonly<Record<string, string>>;
+    meta?: Readonly<Record<string, unknown>>;
+}>;
+/**
+ * Loadable local terminology document compatible with the historic
+ * `data[].attributes[code] = display` JSON shape.
+ */
+export type TerminologyCatalogDocument = Readonly<{
+    id?: string;
+    name?: string;
+    language?: string;
+    system?: string;
+    version?: string;
+    jurisdiction?: string;
+    data: readonly TerminologyCatalogResource[];
+    meta?: Readonly<Record<string, unknown>>;
+}>;
+/** Input for a synchronous local terminology label lookup. */
+export type TerminologyLookupInput = Readonly<{
+    system: string;
+    code: string;
+    language: string;
+    jurisdiction?: string;
+}>;
+/** Input for an offline/local terminology text search. */
+export type TerminologySearchInput = Readonly<{
+    text: string;
+    language: string;
+    jurisdiction?: string;
+    systems?: readonly string[];
+    limit?: number;
+}>;
+/** One terminology option suitable for a coded clinical form control. */
+export type TerminologySearchResult = Readonly<{
+    system: string;
+    code: string;
+    display: string;
+    language: string;
+}>;
+/**
+ * Synchronous terminology contract used by cached and offline applications.
+ *
+ * A future remote terminology client should populate a local implementation
+ * of this contract before synchronous clinical-card rendering.
+ */
+export interface TerminologyProvider {
+    lookup(input: TerminologyLookupInput): string | undefined;
+    search(input: TerminologySearchInput): readonly TerminologySearchResult[];
+}

package/dist/models/terminology.js

@@ -0,0 +1 @@
+export {};

package/dist/utils/clinical-resource-view.d.ts

@@ -45,6 +45,9 @@ export type ClinicalResourceDisplayOptions = Readonly<{
      *
      * Return `undefined` when the product has no translation so the shared
      * reader can fall back to the international `Coding.display`.
+     * `createClinicalCodeTranslator(new LocalTerminologyProvider(catalogs))`
+     * provides the synchronous MVP/offline implementation. Remote terminology
+     * results must be fetched and cached before this render callback runs.
      */
     translateCode?: (input: ClinicalTerminologyTranslationInput) => string | undefined;
 }>;

package/dist/utils/index.d.ts

@@ -81,6 +81,7 @@ export * from './jwt-signer';
 export * from './jwk-thumbprint';
 export * from './legal-organization-onboarding';
 export * from './legal-organization-verification-transaction';
+export * from './local-terminology-provider';
 export * from './license';
 export * from './license-commercial-search';
 export * from './license-list-search';

package/dist/utils/index.js

@@ -81,6 +81,7 @@ export * from './jwt-signer.js';
 export * from './jwk-thumbprint.js';
 export * from './legal-organization-onboarding.js';
 export * from './legal-organization-verification-transaction.js';
+export * from './local-terminology-provider.js';
 export * from './license.js';
 export * from './license-commercial-search.js';
 export * from './license-list-search.js';

package/dist/utils/local-terminology-provider.d.ts

@@ -0,0 +1,27 @@
+import type { TerminologyCatalogDocument, TerminologyLookupInput, TerminologyProvider, TerminologySearchInput, TerminologySearchResult } from '../models/terminology.js';
+import type { ClinicalTerminologyTranslationInput } from './clinical-resource-view.js';
+/**
+ * In-memory terminology provider compatible with the historic JSON
+ * catalogs. It performs no network requests and keeps catalog loading under
+ * application control.
+ */
+export declare class LocalTerminologyProvider implements TerminologyProvider {
+    private readonly terms;
+    private readonly byIdentity;
+    private readonly byScopedIdentity;
+    constructor(catalogs: readonly TerminologyCatalogDocument[]);
+    /** Returns the best local label for one canonical coding identity. */
+    lookup(input: TerminologyLookupInput): string | undefined;
+    /**
+     * Searches local labels and codes, optionally constrained to coding systems.
+     * Results are deterministic and contain at most 100 entries.
+     */
+    search(input: TerminologySearchInput): readonly TerminologySearchResult[];
+    private identityKey;
+    private scopedIdentityKey;
+}
+/**
+ * Adapts a synchronous local terminology provider to
+ * `ClinicalResourceDisplayOptions.translateCode`.
+ */
+export declare function createClinicalCodeTranslator(provider: Pick<TerminologyProvider, 'lookup'>): (input: ClinicalTerminologyTranslationInput) => string | undefined;

package/dist/utils/local-terminology-provider.js

@@ -0,0 +1,154 @@
+const SNOMED_SYSTEM = 'http://snomed.info/sct';
+const DEFAULT_LANGUAGE = 'en';
+const DEFAULT_LIMIT = 20;
+const MAX_LIMIT = 100;
+function normalizedString(value) {
+    return typeof value === 'string' ? value.trim() : '';
+}
+function normalizeSystem(value) {
+    const system = normalizedString(value);
+    return system.toLowerCase() === 'ips' ? SNOMED_SYSTEM : system;
+}
+function normalizeLanguage(value) {
+    return normalizedString(value).replace(/_/g, '-').toLowerCase();
+}
+function normalizeJurisdiction(value) {
+    return normalizedString(value).toUpperCase();
+}
+function languageCandidates(language) {
+    const normalized = normalizeLanguage(language);
+    const base = normalized.split('-')[0];
+    return [...new Set([normalized, base, DEFAULT_LANGUAGE].filter(Boolean))];
+}
+function searchableText(value) {
+    return value
+        .normalize('NFD')
+        .replace(/[\u0300-\u036f]/g, '')
+        .toLocaleLowerCase();
+}
+function normalizedLimit(value) {
+    if (!Number.isFinite(value))
+        return DEFAULT_LIMIT;
+    return Math.max(1, Math.min(MAX_LIMIT, Math.trunc(value)));
+}
+/**
+ * In-memory terminology provider compatible with the historic JSON
+ * catalogs. It performs no network requests and keeps catalog loading under
+ * application control.
+ */
+export class LocalTerminologyProvider {
+    terms;
+    byIdentity;
+    byScopedIdentity;
+    constructor(catalogs) {
+        const terms = [];
+        const byIdentity = new Map();
+        const byScopedIdentity = new Map();
+        for (const catalog of catalogs) {
+            const catalogLanguage = normalizeLanguage(catalog.language) || DEFAULT_LANGUAGE;
+            const jurisdiction = normalizeJurisdiction(catalog.jurisdiction) || undefined;
+            for (const resource of catalog.data || []) {
+                const system = normalizeSystem(resource.id || catalog.system);
+                const language = normalizeLanguage(resource.language) || catalogLanguage;
+                if (!system || !language || !resource.attributes)
+                    continue;
+                for (const [rawCode, rawDisplay] of Object.entries(resource.attributes)) {
+                    const code = normalizedString(rawCode);
+                    const display = normalizedString(rawDisplay);
+                    if (!code || !display)
+                        continue;
+                    const term = { system, code, display, language, jurisdiction };
+                    terms.push(term);
+                    byIdentity.set(this.identityKey(language, system, code), display);
+                    byScopedIdentity.set(this.scopedIdentityKey(language, jurisdiction, system, code), display);
+                }
+            }
+        }
+        this.terms = terms;
+        this.byIdentity = byIdentity;
+        this.byScopedIdentity = byScopedIdentity;
+    }
+    /** Returns the best local label for one canonical coding identity. */
+    lookup(input) {
+        const system = normalizeSystem(input.system);
+        const code = normalizedString(input.code);
+        const jurisdiction = normalizeJurisdiction(input.jurisdiction) || undefined;
+        if (!system || !code)
+            return undefined;
+        for (const language of languageCandidates(input.language)) {
+            if (jurisdiction) {
+                const scopedDisplay = this.byScopedIdentity.get(this.scopedIdentityKey(language, jurisdiction, system, code)) || this.byScopedIdentity.get(this.scopedIdentityKey(language, undefined, system, code));
+                if (scopedDisplay)
+                    return scopedDisplay;
+                continue;
+            }
+            const display = this.byIdentity.get(this.identityKey(language, system, code));
+            if (display)
+                return display;
+        }
+        return undefined;
+    }
+    /**
+     * Searches local labels and codes, optionally constrained to coding systems.
+     * Results are deterministic and contain at most 100 entries.
+     */
+    search(input) {
+        const query = searchableText(normalizedString(input.text));
+        if (!query)
+            return [];
+        const allowedSystems = new Set((input.systems || []).map(normalizeSystem).filter(Boolean));
+        const jurisdiction = normalizeJurisdiction(input.jurisdiction);
+        const languages = languageCandidates(input.language);
+        const languageRank = new Map(languages.map((language, index) => [language, index]));
+        const selected = new Map();
+        for (const term of this.terms) {
+            if (allowedSystems.size > 0 && !allowedSystems.has(term.system))
+                continue;
+            if (jurisdiction && term.jurisdiction && term.jurisdiction !== jurisdiction)
+                continue;
+            const rank = languageRank.get(term.language);
+            if (rank === undefined)
+                continue;
+            if (!searchableText(term.code).includes(query)
+                && !searchableText(term.display).includes(query)) {
+                continue;
+            }
+            const identity = `${term.system}\u0000${term.code}`;
+            const current = selected.get(identity);
+            if (!current || rank < current.rank)
+                selected.set(identity, { term, rank });
+        }
+        return [...selected.values()]
+            .sort((left, right) => (left.rank - right.rank
+            || left.term.display.localeCompare(right.term.display)
+            || left.term.code.localeCompare(right.term.code)))
+            .slice(0, normalizedLimit(input.limit))
+            .map(({ term }) => ({
+            system: term.system,
+            code: term.code,
+            display: term.display,
+            language: term.language,
+        }));
+    }
+    identityKey(language, system, code) {
+        return `${language}\u0000${system}\u0000${code}`;
+    }
+    scopedIdentityKey(language, jurisdiction, system, code) {
+        return `${language}\u0000${jurisdiction || ''}\u0000${system}\u0000${code}`;
+    }
+}
+/**
+ * Adapts a synchronous local terminology provider to
+ * `ClinicalResourceDisplayOptions.translateCode`.
+ */
+export function createClinicalCodeTranslator(provider) {
+    return (input) => {
+        if (!input.system)
+            return undefined;
+        return provider.lookup({
+            system: input.system,
+            code: input.code,
+            language: input.locale,
+        });
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gdc-common-utils-ts",
-  "version": "2.3.17",
+  "version": "2.3.18",
   "publishConfig": {
     "access": "public"
   },