@peerbits/medical-terminology 0.1.0

package/LICENSE

@@ -0,0 +1,105 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work.
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work.
+
+      "Contribution" shall mean any work of authorship intentionally
+      submitted to Licensor for inclusion in the Work.
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have
+      made, use, offer to sell, sell, import, and otherwise transfer the
+      Work. If You institute patent litigation against any entity
+      alleging that the Work constitutes direct or contributory patent
+      infringement, then any patent licenses granted to You under this
+      License for that Work shall terminate as of the date such
+      litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof provided that You meet the
+      following conditions:
+
+      (a) You must give any other recipients a copy of this License; and
+      (b) You must cause modified files to carry prominent notices; and
+      (c) You must retain all copyright, patent, trademark, and
+          attribution notices from the Source form; and
+      (d) If the Work includes a NOTICE file, any Derivative Works must
+          include a readable copy of its attribution notices.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You shall be under the terms of this License, without additional
+      terms or conditions.
+
+   6. Trademarks. This License does not grant permission to use trade
+      names, trademarks, service marks, or product names of the Licensor.
+
+   7. Disclaimer of Warranty. The Work is provided on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied.
+
+   8. Limitation of Liability. In no event shall any Contributor be
+      liable for damages arising as a result of this License or out of
+      the use or inability to use the Work.
+
+   9. Accepting Warranty or Additional Liability. You may choose to offer
+      support, warranty, indemnity, or other liability obligations, but
+      only on Your own behalf and sole responsibility.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,139 @@
+# @peerbits/medical-terminology
+
+> Terminology system-URI registry and code format/checksum validation utilities — ships zero licensed terminology datasets (see [Licensing](./docs/LICENSING.md))
+
+**Category:** Medical Coding — Terminology & Code-Handling Utilities · **License:** Apache-2.0 · **Status:** Stable
+
+[![CI](https://github.com/PeerbitsSolution/medical-terminology/actions/workflows/ci.yml/badge.svg)](https://github.com/PeerbitsSolution/medical-terminology/actions/workflows/ci.yml)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
+[![npm version](https://img.shields.io/npm/v/@peerbits/medical-terminology.svg)](https://www.npmjs.com/package/@peerbits/medical-terminology)
+
+---
+
+## 1. What problem does this solve?
+
+Healthcare applications regularly handle coded concepts across disparate medical terminology systems—LOINC, SNOMED CT, ICD-10-CM, RxNorm, CPT, and UCUM. Validating these concepts in ingestion pipelines typically forces teams to either deploy heavy terminology servers (like Ontoserver or UMLS TS) or omit validation entirely, allowing malformed identifiers and invalid URIs to corrupt downstream FHIR records.
+
+`@peerbits/medical-terminology` provides a zero-dependency, in-memory validation engine that standardizes canonical system URIs and validates code syntax, pattern structures, and Verhoeff check-digits client-side, with an optional pluggable provider architecture for teams that connect real terminology services.
+
+> **⚠️ Licensing Note:** This repository ships canonical code-system URI metadata and structural format/checksum validators only. It does **not** include or distribute any proprietary CPT, SNOMED CT, or RxNorm concept datasets. See [docs/LICENSING.md](./docs/LICENSING.md) for full compliance details.
+
+---
+
+## 2. Features
+
+- **Canonical System URI Registry**: Standardized URIs, OIDs, and short-names for 6 major medical coding systems:
+  - **LOINC** (`http://loinc.org`)
+  - **SNOMED CT** (`http://snomed.info/sct`)
+  - **ICD-10-CM** (`http://hl7.org/fhir/sid/icd-10-cm`)
+  - **RxNorm** (`http://www.nlm.nih.gov/research/umls/rxnorm`)
+  - **CPT** (`http://www.ama-assn.org/go/cpt`)
+  - **UCUM** (`http://unitsofmeasure.org`)
+- **Fast Structural & Checksum Validation**:
+  - Full Verhoeff check-digit calculation and validation for SNOMED SCTIDs.
+  - RegEx & structural format validation for LOINC, ICD-10-CM, CPT (5-digit syntax), RxNorm (RxCUI numeric format), and UCUM syntax.
+- **Pluggable Provider Architecture**: Register runtime lookup hooks (e.g., UMLS REST API, local Terminology Server) to augment structural checks with real-time concept validation.
+- **Zero Runtime Dependencies**: Pure TypeScript with zero external network or database requirements.
+
+---
+
+## 3. Installation
+
+```bash
+npm install @peerbits/medical-terminology
+```
+
+---
+
+## 4. Demo and Quick Start
+
+[Peerbits HealthTech - Medical Terminology Demo](https://healthcare.peerbits.com/demo/medical-terminology)
+
+```ts
+import { validate, SYSTEM_REGISTRY, isValidSctid } from "@peerbits/medical-terminology";
+
+// 1. Validate a LOINC observation code
+const loincResult = validate({
+  system: "http://loinc.org",
+  code: "8867-4",
+});
+console.log(loincResult.valid); // true
+
+// 2. Validate SNOMED CT Concept ID with Verhoeff check-digit
+const snomedResult = validate({
+  system: "http://snomed.info/sct",
+  code: "73211009", // Diabetes mellitus
+});
+console.log(snomedResult.valid); // true
+
+// 3. Catch invalid formats early
+const invalidResult = validate({
+  system: "http://hl7.org/fhir/sid/icd-10-cm",
+  code: "INVALID_CODE",
+});
+console.log(invalidResult.valid); // false
+console.log(invalidResult.issues);
+// [ { severity: "error", path: "code", code: "invalid-format", message: "..." } ]
+```
+
+---
+
+## 5. Pluggable Terminology Providers
+
+You can register custom terminology lookup providers to resolve live concepts while falling back gracefully if offline:
+
+```ts
+import { registerProvider, validateWithProvider } from "@peerbits/medical-terminology";
+
+// Register an in-house or external terminology resolver
+registerProvider("loinc", async (code) => {
+  const isFound = await checkLocalDatabase(code);
+  return { found: isFound, display: isFound ? "Heart rate" : undefined };
+});
+
+// Validate format AND verify existence through the provider
+const result = await validateWithProvider({
+  system: "http://loinc.org",
+  code: "8867-4",
+});
+
+console.log(result.valid); // true
+```
+
+---
+
+## 6. Architecture
+
+```
+src/
+├── index.ts              # Package entry point and exports
+├── registry.ts           # Canonical URIs, OIDs, and system metadata
+├── provider.ts           # Pluggable terminology provider interface
+├── types.ts              # TypeScript declarations and error shapes
+├── validate.ts           # Unified validation engine
+└── validators/
+    ├── cpt.ts            # CPT 5-digit format check (Zero dataset content)
+    ├── icd10cm.ts        # ICD-10-CM alphanumeric structural check
+    ├── loinc.ts          # LOINC hyphenated identifier check
+    ├── rxnorm.ts         # RxNorm RxCUI numeric format check
+    ├── snomed.ts         # SNOMED CT Verhoeff check-digit algorithm
+    └── ucum.ts           # UCUM unit syntax validator
+```
+
+---
+
+## 7. Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md).
+
+---
+
+## 8. License
+
+Apache License 2.0 — see [LICENSE](./LICENSE).
+
+---
+
+## 9. About PeerbitsSolution
+
+`@peerbits/medical-terminology` is part of the [PeerbitsSolution HealthTech Open Source](https://github.com/PeerbitsSolution) initiative—reusable engineering components extracted from our healthcare technology work. This repository contains generalized, reusable logic only; it is not tied to any specific client engagement or commercial product.

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export declare const VERSION = "1.0.0";
+export { validate, validateWithProvider } from "./validate.js";
+export { registerProvider, unregisterProvider, clearProviders, lookup, hasProvider, getRegisteredProviderSystems, } from "./provider.js";
+export { SYSTEM_REGISTRY, getSupportedSystems, getSystemByIdentifier, getSystemByShortName, getSystemByUri, } from "./registry.js";
+export { isValidLoincFormat } from "./validators/loinc.js";
+export { isValidIcd10CmFormat } from "./validators/icd10cm.js";
+export { isValidCptFormat } from "./validators/cpt.js";
+export { isValidRxNormFormat } from "./validators/rxnorm.js";
+export { isValidUcumSyntax } from "./validators/ucum.js";
+export { calculateSctidCheckDigit, isValidSctid, } from "./validators/snomed.js";
+export type { CodedConcept, ProviderLookupResult, SupportedTerminologySystem, TerminologyProvider, TerminologySystem, ValidationIssue, ValidationResult, ValidationSeverity, } from "./types.js";

package/dist/index.js

@@ -0,0 +1,10 @@
+export const VERSION = "1.0.0";
+export { validate, validateWithProvider } from "./validate.js";
+export { registerProvider, unregisterProvider, clearProviders, lookup, hasProvider, getRegisteredProviderSystems, } from "./provider.js";
+export { SYSTEM_REGISTRY, getSupportedSystems, getSystemByIdentifier, getSystemByShortName, getSystemByUri, } from "./registry.js";
+export { isValidLoincFormat } from "./validators/loinc.js";
+export { isValidIcd10CmFormat } from "./validators/icd10cm.js";
+export { isValidCptFormat } from "./validators/cpt.js";
+export { isValidRxNormFormat } from "./validators/rxnorm.js";
+export { isValidUcumSyntax } from "./validators/ucum.js";
+export { calculateSctidCheckDigit, isValidSctid, } from "./validators/snomed.js";

package/dist/provider.d.ts

@@ -0,0 +1,7 @@
+import type { CodedConcept, ProviderLookupResult, TerminologyProvider } from "./types.js";
+export declare function registerProvider(system: string, provider: TerminologyProvider): void;
+export declare function unregisterProvider(system: string): boolean;
+export declare function clearProviders(): void;
+export declare function getRegisteredProviderSystems(): readonly string[];
+export declare function hasProvider(system: string): boolean;
+export declare function lookup(system: string, code: string, concept: Readonly<CodedConcept>): Promise<ProviderLookupResult | undefined>;

package/dist/provider.js

@@ -0,0 +1,42 @@
+import { getSystemByIdentifier } from "./registry.js";
+const providers = new Map();
+export function registerProvider(system, provider) {
+    if (typeof system !== "string") {
+        throw new TypeError("Provider registration requires a string system identifier.");
+    }
+    const s = getSystemByIdentifier(system);
+    if (!s) {
+        throw new TypeError(`Cannot register provider for unknown system identifier: "${system}".`);
+    }
+    if (typeof provider !== "function") {
+        throw new TypeError("Provider must be a function.");
+    }
+    providers.set(s.uri, provider);
+}
+export function unregisterProvider(system) {
+    if (typeof system !== "string")
+        return false;
+    const s = getSystemByIdentifier(system);
+    return s ? providers.delete(s.uri) : false;
+}
+export function clearProviders() {
+    providers.clear();
+}
+export function getRegisteredProviderSystems() {
+    return Object.freeze([...providers.keys()]);
+}
+export function hasProvider(system) {
+    if (typeof system !== "string")
+        return false;
+    const s = getSystemByIdentifier(system);
+    return !!s && providers.has(s.uri);
+}
+export async function lookup(system, code, concept) {
+    if (typeof system !== "string" || typeof code !== "string")
+        return undefined;
+    const s = getSystemByIdentifier(system);
+    const fn = s ? providers.get(s.uri) : undefined;
+    if (!fn)
+        return undefined;
+    return await fn(code, concept);
+}

package/dist/registry.d.ts

@@ -0,0 +1,6 @@
+import type { SupportedTerminologySystem, TerminologySystem } from "./types.js";
+export declare const SYSTEM_REGISTRY: Readonly<Record<SupportedTerminologySystem, Readonly<TerminologySystem>>>;
+export declare const getSupportedSystems: () => readonly TerminologySystem[];
+export declare const getSystemByShortName: (shortName: string) => TerminologySystem | undefined;
+export declare const getSystemByUri: (uri: string) => TerminologySystem | undefined;
+export declare const getSystemByIdentifier: (identifier: string) => TerminologySystem | undefined;

package/dist/registry.js

@@ -0,0 +1,67 @@
+export const SYSTEM_REGISTRY = Object.freeze({
+    loinc: Object.freeze({
+        shortName: "loinc",
+        uri: "http://loinc.org",
+        displayName: "LOINC",
+        oid: "2.16.840.1.113883.6.1",
+        description: "Logical Observation Identifiers Names and Codes",
+    }),
+    snomed: Object.freeze({
+        shortName: "snomed",
+        uri: "http://snomed.info/sct",
+        displayName: "SNOMED CT",
+        oid: "2.16.840.1.113883.6.96",
+        description: "SNOMED Clinical Terms",
+    }),
+    icd10cm: Object.freeze({
+        shortName: "icd10cm",
+        uri: "http://hl7.org/fhir/sid/icd-10-cm",
+        displayName: "ICD-10-CM",
+        oid: "2.16.840.1.113883.6.90",
+        description: "International Classification of Diseases, 10th Revision, Clinical Modification",
+    }),
+    rxnorm: Object.freeze({
+        shortName: "rxnorm",
+        uri: "http://www.nlm.nih.gov/research/umls/rxnorm",
+        displayName: "RxNorm",
+        oid: "2.16.840.1.113883.6.88",
+        description: "National Library of Medicine RxNorm",
+    }),
+    cpt: Object.freeze({
+        shortName: "cpt",
+        uri: "http://www.ama-assn.org/go/cpt",
+        displayName: "CPT",
+        oid: "2.16.840.1.113883.6.12",
+        description: "Current Procedural Terminology (AMA)",
+    }),
+    ucum: Object.freeze({
+        shortName: "ucum",
+        uri: "http://unitsofmeasure.org",
+        displayName: "UCUM",
+        oid: "2.16.840.1.113883.6.8",
+        description: "Unified Code for Units of Measure",
+    }),
+});
+const allSystems = Object.freeze(Object.values(SYSTEM_REGISTRY));
+const byUri = new Map(allSystems.map((s) => [s.uri.toLowerCase(), s]));
+const byShortName = new Map(allSystems.map((s) => [s.shortName.toLowerCase(), s]));
+const byOid = new Map(allSystems
+    .filter((s) => !!s.oid)
+    .map((s) => [s.oid.toLowerCase(), s]));
+export const getSupportedSystems = () => allSystems;
+export const getSystemByShortName = (shortName) => {
+    if (typeof shortName !== "string")
+        return undefined;
+    return byShortName.get(shortName.trim().toLowerCase());
+};
+export const getSystemByUri = (uri) => {
+    if (typeof uri !== "string")
+        return undefined;
+    return byUri.get(uri.trim().toLowerCase());
+};
+export const getSystemByIdentifier = (identifier) => {
+    if (typeof identifier !== "string")
+        return undefined;
+    const clean = identifier.trim().toLowerCase();
+    return byUri.get(clean) ?? byShortName.get(clean) ?? byOid.get(clean);
+};

package/dist/types.d.ts

@@ -0,0 +1,32 @@
+export type SupportedTerminologySystem = "loinc" | "snomed" | "icd10cm" | "rxnorm" | "cpt" | "ucum";
+export type ValidationSeverity = "error" | "warning" | "information";
+export interface TerminologySystem {
+    shortName: SupportedTerminologySystem;
+    uri: string;
+    displayName: string;
+    oid?: string;
+    description?: string;
+}
+export interface CodedConcept {
+    system: string;
+    code: string;
+    display?: string;
+}
+export interface ValidationIssue {
+    severity: ValidationSeverity;
+    path: string;
+    code: string;
+    message: string;
+}
+export interface ValidationResult {
+    valid: boolean;
+    issues: ValidationIssue[];
+    system?: TerminologySystem;
+    providerConfigured: boolean;
+}
+export interface ProviderLookupResult {
+    found: boolean;
+    display?: string;
+    message?: string;
+}
+export type TerminologyProvider = (code: string, concept: Readonly<CodedConcept>) => ProviderLookupResult | Promise<ProviderLookupResult>;

package/dist/types.js

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

package/dist/validate.d.ts

@@ -0,0 +1,15 @@
+import type { ValidationResult } from "./types.js";
+/**
+ * Validates the structure and code format of a coded concept.
+ *
+ * @param concept The input concept object (e.g., { system, code, display? }).
+ * @returns ValidationResult with validity flag, issues, and system metadata.
+ */
+export declare function validate(concept: unknown): ValidationResult;
+/**
+ * Validates format and dispatches to a registered TerminologyProvider if configured.
+ *
+ * @param concept The input concept object (e.g., { system, code, display? }).
+ * @returns Promise<ValidationResult> with format & provider validation results.
+ */
+export declare function validateWithProvider(concept: unknown): Promise<ValidationResult>;

package/dist/validate.js

@@ -0,0 +1,159 @@
+import { hasProvider, lookup } from "./provider.js";
+import { getSystemByIdentifier, getSystemByUri } from "./registry.js";
+import { isValidLoincFormat } from "./validators/loinc.js";
+import { isValidIcd10CmFormat } from "./validators/icd10cm.js";
+import { isValidCptFormat } from "./validators/cpt.js";
+import { isValidRxNormFormat } from "./validators/rxnorm.js";
+import { isValidSctid } from "./validators/snomed.js";
+import { isValidUcumSyntax } from "./validators/ucum.js";
+const formatChecks = {
+    loinc: isValidLoincFormat,
+    icd10cm: isValidIcd10CmFormat,
+    cpt: isValidCptFormat,
+    rxnorm: isValidRxNormFormat,
+    snomed: isValidSctid,
+    ucum: isValidUcumSyntax,
+};
+/**
+ * Safely extracts a string property value from an unknown object without throwing
+ * or triggering prototype pollution side-effects.
+ */
+function extractString(target, key) {
+    if (!target || typeof target !== "object" || Array.isArray(target)) {
+        return undefined;
+    }
+    try {
+        const val = target[key];
+        if (typeof val === "string") {
+            return val;
+        }
+    }
+    catch {
+        // If a getter throws or proxy traps fail, fail safely
+        return undefined;
+    }
+    return undefined;
+}
+/**
+ * Validates the structure and code format of a coded concept.
+ *
+ * @param concept The input concept object (e.g., { system, code, display? }).
+ * @returns ValidationResult with validity flag, issues, and system metadata.
+ */
+export function validate(concept) {
+    const issues = [];
+    if (!concept || typeof concept !== "object" || Array.isArray(concept)) {
+        return {
+            valid: false,
+            issues: [
+                {
+                    severity: "error",
+                    path: "",
+                    code: "invalid-type",
+                    message: "Coded concept must be a non-null object.",
+                },
+            ],
+            providerConfigured: false,
+        };
+    }
+    const rawSystem = extractString(concept, "system");
+    const rawCode = extractString(concept, "code");
+    if (rawSystem === undefined || rawSystem.trim().length === 0) {
+        issues.push({
+            severity: "error",
+            path: "system",
+            code: "required",
+            message: "A string system URI is required.",
+        });
+    }
+    if (rawCode === undefined || rawCode.trim().length === 0) {
+        issues.push({
+            severity: "error",
+            path: "code",
+            code: "required",
+            message: "A non-empty code string is required.",
+        });
+    }
+    if (issues.length > 0) {
+        return {
+            valid: false,
+            issues,
+            providerConfigured: false,
+        };
+    }
+    const systemStr = rawSystem.trim();
+    const codeStr = rawCode.trim();
+    // Try matching system by URI, shortName, or OID
+    const system = getSystemByUri(systemStr) ?? getSystemByIdentifier(systemStr);
+    if (!system) {
+        issues.push({
+            severity: "warning",
+            path: "system",
+            code: "unknown-system",
+            message: `Unknown terminology system: "${systemStr}". Format validation was skipped.`,
+        });
+        return {
+            valid: true,
+            issues,
+            providerConfigured: false,
+        };
+    }
+    const validator = formatChecks[system.shortName];
+    const isFormatValid = validator ? validator(codeStr) : true;
+    if (!isFormatValid) {
+        issues.push({
+            severity: "error",
+            path: "code",
+            code: "invalid-format",
+            message: `Code "${codeStr}" does not match the structural format for ${system.displayName}.`,
+        });
+    }
+    return {
+        valid: issues.filter((i) => i.severity === "error").length === 0,
+        issues,
+        system,
+        providerConfigured: hasProvider(system.uri),
+    };
+}
+/**
+ * Validates format and dispatches to a registered TerminologyProvider if configured.
+ *
+ * @param concept The input concept object (e.g., { system, code, display? }).
+ * @returns Promise<ValidationResult> with format & provider validation results.
+ */
+export async function validateWithProvider(concept) {
+    const result = validate(concept);
+    if (!result.valid || !result.system || !result.providerConfigured) {
+        return result;
+    }
+    const rawCode = extractString(concept, "code") ?? "";
+    const rawDisplay = extractString(concept, "display");
+    const codedConcept = {
+        system: result.system.uri,
+        code: rawCode.trim(),
+        display: rawDisplay,
+    };
+    try {
+        const providerResult = await lookup(result.system.uri, codedConcept.code, codedConcept);
+        if (providerResult && providerResult.found === false) {
+            result.issues.push({
+                severity: "warning",
+                path: "code",
+                code: "provider-not-found",
+                message: providerResult.message ??
+                    `Code "${codedConcept.code}" was not found in the registered ${result.system.displayName} provider.`,
+            });
+        }
+    }
+    catch (error) {
+        result.issues.push({
+            severity: "warning",
+            path: "code",
+            code: "provider-failed",
+            message: error instanceof Error
+                ? `Provider error: ${error.message}`
+                : "Provider failed during concept lookup. Format validation remains valid.",
+        });
+    }
+    return result;
+}

package/dist/validators/cpt.d.ts

@@ -0,0 +1,9 @@
+/**
+ * CPT Code Structural Format Validator.
+ *
+ * ⚠️ LEGAL BOUNDARY NOTICE:
+ * This validator checks structural syntax ONLY (5-digit numeric or 4-digit + trailing alpha).
+ * This repository contains ZERO real CPT codes, descriptions, or copyrighted AMA material.
+ * See docs/LICENSING.md for legal compliance requirements.
+ */
+export declare const isValidCptFormat: (code: string) => boolean;

package/dist/validators/cpt.js

@@ -0,0 +1,14 @@
+/**
+ * CPT Code Structural Format Validator.
+ *
+ * ⚠️ LEGAL BOUNDARY NOTICE:
+ * This validator checks structural syntax ONLY (5-digit numeric or 4-digit + trailing alpha).
+ * This repository contains ZERO real CPT codes, descriptions, or copyrighted AMA material.
+ * See docs/LICENSING.md for legal compliance requirements.
+ */
+export const isValidCptFormat = (code) => {
+    if (typeof code !== "string")
+        return false;
+    const trimmed = code.trim();
+    return /^\d{5}$|^\d{4}[A-Za-z]$/.test(trimmed);
+};

package/dist/validators/icd10cm.d.ts

@@ -0,0 +1,7 @@
+/**
+ * ICD-10-CM Code Format Validator.
+ * Standard format: Letter (A-Z) followed by 2 alphanumeric characters,
+ * optionally followed by a period and 1-4 alphanumeric characters (e.g. "A00.1", "E11.9", "S82.101A").
+ * Public domain specification (CMS / CDC NCHS).
+ */
+export declare const isValidIcd10CmFormat: (code: string) => boolean;

package/dist/validators/icd10cm.js

@@ -0,0 +1,12 @@
+/**
+ * ICD-10-CM Code Format Validator.
+ * Standard format: Letter (A-Z) followed by 2 alphanumeric characters,
+ * optionally followed by a period and 1-4 alphanumeric characters (e.g. "A00.1", "E11.9", "S82.101A").
+ * Public domain specification (CMS / CDC NCHS).
+ */
+export const isValidIcd10CmFormat = (code) => {
+    if (typeof code !== "string")
+        return false;
+    const trimmed = code.trim();
+    return /^[A-Za-z][0-9][0-9A-Za-z](?:\.?[0-9A-Za-z]{1,4})?$/.test(trimmed);
+};

package/dist/validators/loinc.d.ts

@@ -0,0 +1,6 @@
+/**
+ * LOINC Code Format Validator.
+ * Standard LOINC format: 1 to 6 digits, hyphen, 1 check-digit (e.g. "8867-4", "100000-1").
+ * Sourced from Regenstrief LOINC specifications.
+ */
+export declare const isValidLoincFormat: (code: string) => boolean;

package/dist/validators/loinc.js

@@ -0,0 +1,11 @@
+/**
+ * LOINC Code Format Validator.
+ * Standard LOINC format: 1 to 6 digits, hyphen, 1 check-digit (e.g. "8867-4", "100000-1").
+ * Sourced from Regenstrief LOINC specifications.
+ */
+export const isValidLoincFormat = (code) => {
+    if (typeof code !== "string")
+        return false;
+    const trimmed = code.trim();
+    return /^\d{1,6}-\d$/.test(trimmed);
+};

package/dist/validators/rxnorm.d.ts

@@ -0,0 +1,7 @@
+/**
+ * RxNorm Code Structural Format Validator.
+ * RxNorm Concept Unique Identifiers (RxCUI) are numeric strings of 1 to 8 digits.
+ * Sourced from National Library of Medicine (NLM) specification.
+ * Zero proprietary code-to-concept datasets shipped.
+ */
+export declare const isValidRxNormFormat: (code: string) => boolean;

package/dist/validators/rxnorm.js

@@ -0,0 +1,12 @@
+/**
+ * RxNorm Code Structural Format Validator.
+ * RxNorm Concept Unique Identifiers (RxCUI) are numeric strings of 1 to 8 digits.
+ * Sourced from National Library of Medicine (NLM) specification.
+ * Zero proprietary code-to-concept datasets shipped.
+ */
+export const isValidRxNormFormat = (code) => {
+    if (typeof code !== "string")
+        return false;
+    const trimmed = code.trim();
+    return /^\d{1,8}$/.test(trimmed);
+};

package/dist/validators/snomed.d.ts

@@ -0,0 +1,19 @@
+/**
+ * SNOMED CT SCTID Checksum & Format Validator.
+ * Implements the Verhoeff check-digit algorithm specified by SNOMED International.
+ *
+ * ⚠️ LEGAL BOUNDARY NOTICE:
+ * This validator checks the structural Verhoeff check-digit ONLY.
+ * It contains ZERO proprietary SNOMED concept dictionaries or descriptions.
+ */
+/**
+ * Calculates the Verhoeff check digit for a given numeric SCTID body.
+ * @param body Numeric string without the trailing check digit (1 to 17 digits).
+ * @returns The single check-digit string, or undefined if input is non-numeric.
+ */
+export declare function calculateSctidCheckDigit(body: string): string | undefined;
+/**
+ * Validates whether a full SCTID string is structurally valid with a correct Verhoeff check digit.
+ * SNOMED SCTIDs are 6 to 18 digits (or 2 to 18 digits for test vectors).
+ */
+export declare function isValidSctid(sctid: string): boolean;

package/dist/validators/snomed.js

@@ -0,0 +1,68 @@
+/**
+ * SNOMED CT SCTID Checksum & Format Validator.
+ * Implements the Verhoeff check-digit algorithm specified by SNOMED International.
+ *
+ * ⚠️ LEGAL BOUNDARY NOTICE:
+ * This validator checks the structural Verhoeff check-digit ONLY.
+ * It contains ZERO proprietary SNOMED concept dictionaries or descriptions.
+ */
+// Dihedral group D5 multiplication table
+const d = [
+    [0, 1, 2, 3, 4, 5, 6, 7, 8, 9],
+    [1, 2, 3, 4, 0, 6, 7, 8, 9, 5],
+    [2, 3, 4, 0, 1, 7, 8, 9, 5, 6],
+    [3, 4, 0, 1, 2, 8, 9, 5, 6, 7],
+    [4, 0, 1, 2, 3, 9, 5, 6, 7, 8],
+    [5, 9, 8, 7, 6, 0, 4, 3, 2, 1],
+    [6, 5, 9, 8, 7, 1, 0, 4, 3, 2],
+    [7, 6, 5, 9, 8, 2, 1, 0, 4, 3],
+    [8, 7, 6, 5, 9, 3, 2, 1, 0, 4],
+    [9, 8, 7, 6, 5, 4, 3, 2, 1, 0],
+];
+// Permutation table
+const p = [
+    [0, 1, 2, 3, 4, 5, 6, 7, 8, 9],
+    [1, 5, 7, 6, 2, 8, 3, 0, 9, 4],
+    [5, 8, 0, 3, 7, 9, 6, 1, 4, 2],
+    [8, 9, 1, 6, 0, 4, 3, 5, 2, 7],
+    [9, 4, 5, 3, 1, 2, 6, 8, 7, 0],
+    [4, 2, 8, 6, 5, 7, 3, 9, 0, 1],
+    [2, 7, 9, 3, 8, 0, 6, 4, 1, 5],
+    [7, 0, 4, 6, 9, 1, 3, 2, 5, 8],
+];
+// Inverse table
+const inv = [0, 4, 3, 2, 1, 5, 6, 7, 8, 9];
+/**
+ * Calculates the Verhoeff check digit for a given numeric SCTID body.
+ * @param body Numeric string without the trailing check digit (1 to 17 digits).
+ * @returns The single check-digit string, or undefined if input is non-numeric.
+ */
+export function calculateSctidCheckDigit(body) {
+    if (typeof body !== "string")
+        return undefined;
+    const trimmed = body.trim();
+    if (!/^\d{1,17}$/.test(trimmed))
+        return undefined;
+    let c = 0;
+    const digits = [...trimmed].reverse();
+    for (let i = 0; i < digits.length; i++) {
+        const digitVal = Number(digits[i]);
+        const permuted = p[(i + 1) % 8][digitVal];
+        c = d[c][permuted];
+    }
+    return String(inv[c]);
+}
+/**
+ * Validates whether a full SCTID string is structurally valid with a correct Verhoeff check digit.
+ * SNOMED SCTIDs are 6 to 18 digits (or 2 to 18 digits for test vectors).
+ */
+export function isValidSctid(sctid) {
+    if (typeof sctid !== "string")
+        return false;
+    const trimmed = sctid.trim();
+    if (!/^\d{2,18}$/.test(trimmed))
+        return false;
+    const body = trimmed.slice(0, -1);
+    const checkDigit = trimmed.slice(-1);
+    return calculateSctidCheckDigit(body) === checkDigit;
+}

package/dist/validators/ucum.d.ts

@@ -0,0 +1,6 @@
+/**
+ * UCUM (Unified Code for Units of Measure) Syntax Validator.
+ * Validates whether a unit string adheres to conservative UCUM lexical syntax.
+ * Sourced from the UCUM specification (Regenstrief Institute).
+ */
+export declare const isValidUcumSyntax: (unit: string) => boolean;

package/dist/validators/ucum.js

@@ -0,0 +1,13 @@
+/**
+ * UCUM (Unified Code for Units of Measure) Syntax Validator.
+ * Validates whether a unit string adheres to conservative UCUM lexical syntax.
+ * Sourced from the UCUM specification (Regenstrief Institute).
+ */
+export const isValidUcumSyntax = (unit) => {
+    if (typeof unit !== "string")
+        return false;
+    const trimmed = unit.trim();
+    if (trimmed.length === 0 || trimmed.length > 64)
+        return false;
+    return /^[A-Za-z0-9\[\]{}().*\/^+\-_%'|]+$/.test(trimmed);
+};

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@peerbits/medical-terminology",
+  "version": "0.1.0",
+  "description": "Terminology system-URI registry and code format/checksum validation utilities — ships zero licensed terminology datasets (see docs/LICENSING.md)",
+  "license": "Apache-2.0",
+  "author": "PeerbitsSolution",
+  "homepage": "https://github.com/PeerbitsSolution/medical-terminology#readme",
+  "bugs": {
+    "url": "https://github.com/PeerbitsSolution/medical-terminology/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build",
+    "lint": "eslint .",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/PeerbitsSolution/medical-terminology.git"
+  },
+  "keywords": [
+    "healthcare",
+    "fhir",
+    "snomed",
+    "loinc",
+    "icd-10",
+    "rxnorm",
+    "cpt",
+    "ucum",
+    "typescript",
+    "terminology"
+  ],
+  "devDependencies": {
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0",
+    "eslint": "^9.0.0",
+    "@typescript-eslint/eslint-plugin": "^8.0.0",
+    "@typescript-eslint/parser": "^8.0.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}