@peerbits/medical-terminology 1.0.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,137 @@
+# @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. Quick Start
+
+```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/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@peerbits/medical-terminology",
+  "version": "1.0.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",
+    "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"
+  }
+}