@lowlysre/icd-10-cm 3.0.0 → 3.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/README.md +78 -13
  2. package/dist/index.cjs +6 -1
  3. package/dist/index.d.cts +6 -0
  4. package/dist/index.d.mts +2 -2
  5. package/dist/index.mjs +1 -1
  6. package/package.json +29 -6
package/README.md CHANGED
@@ -5,16 +5,18 @@
5
5
  </p>
6
6
 
7
7
  [![NPM Version](https://img.shields.io/npm/v/%40lowlysre%2Ficd-10-cm)](https://www.npmjs.com/package/@lowlysre/icd-10-cm)
8
+ [![downloads](https://img.shields.io/npm/dm/@lowlysre/icd-10-cm)](https://npm-stat.com/charts.html?package=@lowlysre/icd-10-cm)
9
+ [![jsDelivr](https://data.jsdelivr.com/v1/stats/packages/npm/@lowlysre/icd-10-cm/badge?style=rounded)](https://www.jsdelivr.com/package/npm/@lowlysre/icd-10-cm)
8
10
  [![Test](https://github.com/lowlysre/icd-10-cm/actions/workflows/test.yml/badge.svg)](https://github.com/lowlysre/icd-10-cm/actions/workflows/test.yml)
9
11
  [![sustainable-npm](https://img.shields.io/badge/sustainable--npm-🌱-blue?style=flat)](https://github.com/lowlysre/sustainable-npm)
10
- [![immutable releases](https://img.shields.io/badge/immutable%20releases-active-green?logo=github)](https://github.com/lowlysre/icd-10-cm/releases)
11
12
 
12
- A data package containing the latest ICD-10 CM codes and descriptions, types included!
13
+ A data package containing the FY2027 ICD-10-CM diagnosis codes and descriptions (effective October 1, 2026), types included!
13
14
 
14
15
  - ⚡ Fast, lookups via dictionary of minified json
15
16
  - 🔒 Secure, a zero dependency package with provenance
16
17
  - ⚛️ Small, limited to CM (Clinical Modification) data and less than 1MB compressed
17
18
  - 🔏 Immutable, GitHub releases are locked and cannot be altered or replaced after publishing
19
+ - 🔌 Offline, the full code set ships inside the package: no API keys, no rate limits, and no calls to government servers at runtime. It runs inside closed-loop healthcare systems that block outbound traffic or require a vendor review for every external API
18
20
 
19
21
  ## Install
20
22
 
@@ -41,26 +43,89 @@ if (!maybeDescription) {
41
43
  const normalized = normalizeICD10Code(" a00.1 "); // "A001"
42
44
  ```
43
45
 
44
- ## Data Source
46
+ CommonJS works too:
47
+
48
+ ```js
49
+ const { getICD10Description } = require("@lowlysre/icd-10-cm");
50
+ ```
51
+
52
+ ### Checking which release is bundled
53
+
54
+ `ICD10_CM_RELEASE` describes the code set shipped in the installed version, so an app can log it, show it, or fail fast when it expects a different year:
55
+
56
+ ```ts
57
+ import { ICD10_CM_RELEASE } from "@lowlysre/icd-10-cm";
45
58
 
46
- [www.cdc.gov/nchs](https://www.cdc.gov/nchs/icd/icd-10-cm/files.html)
59
+ ICD10_CM_RELEASE.fiscalYear; // 2027
60
+ ICD10_CM_RELEASE.effectiveDate; // "2026-10-01"
61
+ ICD10_CM_RELEASE.codeCount; // 74879
62
+ ```
63
+
64
+ ### Using with AI
65
+
66
+ - Grounding AI output. Language models describe ICD-10-CM codes from memory, so they get laterality and severity wrong and invent descriptions for codes that don't exist. Check each model-produced code against the official set before showing or storing it.
67
+ - Agent tools. Expose `getICD10Description` as a tool or function call, so an agent reads the official description instead of recalling one.
68
+
69
+ ```ts
70
+ import { getICD10Description } from "@lowlysre/icd-10-cm";
71
+
72
+ const modelCodes = ["E11.9", "H40.1131", "E11.99"];
73
+
74
+ const checked = modelCodes.map((code) => ({
75
+ code,
76
+ description: getICD10Description(code) ?? null,
77
+ }));
78
+ // [
79
+ // { code: "E11.9", description: "Type 2 diabetes mellitus without complications" },
80
+ // { code: "H40.1131", description: "Primary open-angle glaucoma, bilateral, mild stage" },
81
+ // { code: "E11.99", description: null }, // not a real code
82
+ // ]
83
+ ```
47
84
 
48
- ## Development
85
+ ## API
86
+
87
+ - `getICD10Description(code)` (also the default export) returns the description for a code, or `undefined` when the code isn't in the bundled release. Input is normalized first.
88
+ - `normalizeICD10Code(code)` trims whitespace, strips dots, and uppercases, matching the dataset keys.
89
+ - `ICD10_CM_RELEASE` is a frozen object with the bundled release's `fiscalYear`, `effectiveDate`, and `codeCount`.
90
+ - `ensureICD10DatasetLoaded(data)` returns `data`, or throws when it's empty or missing.
91
+ - Types: `ICD10Dictionary`, `ICD10CMRelease`.
92
+
93
+ The package supports Node.js 22 or later.
94
+
95
+ ## Raw data via CDN
96
+
97
+ The dataset is a flat JSON object of normalized code to description. Browsers and other runtimes can fetch it straight from jsDelivr without installing anything:
98
+
99
+ ```js
100
+ const res = await fetch(
101
+ "https://cdn.jsdelivr.net/npm/@lowlysre/icd-10-cm@3/data/icd10.min.json",
102
+ );
103
+ const codes = await res.json();
104
+ codes["A000"]; // "Cholera due to Vibrio cholerae 01, biovar cholerae"
105
+ ```
106
+
107
+ Pin the major version in the URL so the code set only changes when you choose to upgrade.
108
+
109
+ ## Versioning
110
+
111
+ Each new ICD-10-CM release (the annual October 1 update, and any April 1 update) ships as a new major version. A release can delete or redefine codes, so a caret range like `^3.0.0` never silently changes the code set underneath an app. Upgrade the major version deliberately to pick up a new year.
112
+
113
+ Minor and patch versions contain code and tooling changes only; the data stays the same.
114
+
115
+ ## Data Source
49
116
 
50
- For regenerating `data/icd10.min.json` via `npm run parse-icd`, use Node.js v22+ (required for `--experimental-strip-types`).
117
+ ICD-10-CM is maintained by the CDC's National Center for Health Statistics (NCHS), which publishes the code files for free public use: [ICD-10-CM files](https://www.cdc.gov/nchs/icd/icd-10-cm/files.html). The MIT license covers this package's code.
51
118
 
52
- ### Updating the ICD-10-CM data
119
+ This package is not affiliated with or endorsed by the CDC, NCHS, or CMS.
53
120
 
54
- CDC/NCHS publishes a new code set annually (effective October 1) and occasionally a mid-year update (effective April 1). Check the [CDC files page](https://www.cdc.gov/nchs/icd/icd-10-cm/files.html) or the [CMS ICD-10 page](https://www.cms.gov/medicare/coding-billing/icd-10-codes) for the latest "Code Descriptions in Tabular Order" archive.
121
+ ## Contributing
55
122
 
56
- 1. Download the latest Code Descriptions in Tabular Order zip
57
- 2. Extract `icd10cm_codes_<year>.txt` and save it as `scripts/icd10cm.txt` (format: code, whitespace, description per line)
58
- 3. Run `npm run parse-icd` to regenerate `data/icd10.min.json`
59
- 4. Run `npm test` and verify the reported code count matches the addenda
60
- 5. Bump the package version and publish
123
+ See [CONTRIBUTING.md](.github/CONTRIBUTING.md) for setup and the yearly data update steps.
61
124
 
62
125
  ## Versions
63
126
 
127
+ - v3.1.1 - README AI use cases (output grounding, agent tools), closed-loop offline use, `ai`, `llm`, and `offline` npm keywords
128
+ - v3.1.0 - `ICD10_CM_RELEASE` export with the bundled fiscal year, effective date, and code count. Node.js 22+ declared in `engines`, `package.json` exported, expanded npm keywords. API, CDN, and versioning docs, plus contributing and security guides
64
129
  - v3.0.0 - Data updated to the October 1, 2026 ICD-10-CM release (74,879 codes, from the FY2027 set)
65
130
  - v2.0.0 - Data updated to the April 1, 2026 ICD-10-CM release (74,719 codes, from the FY2024 set). TypeScript 7 (native compiler) toolchain, ESLint replaced with oxlint + Prettier, dropped tsup for plain tsc (zero-bundler dual ESM/CJS), dataset shipped once and lazy-loaded (~50% smaller install, faster imports), fixed broken `require()` entry point
66
131
  - v1.1.5 - Dependency and toolchain maintenance
package/dist/index.cjs CHANGED
@@ -1,8 +1,13 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
- exports.getICD10Description = exports.normalizeICD10Code = exports.ensureICD10DatasetLoaded = void 0;
3
+ exports.getICD10Description = exports.normalizeICD10Code = exports.ensureICD10DatasetLoaded = exports.ICD10_CM_RELEASE = void 0;
4
4
  const node_fs_1 = require("node:fs");
5
5
  const node_path_1 = require("node:path");
6
+ exports.ICD10_CM_RELEASE = Object.freeze({
7
+ fiscalYear: 2027,
8
+ effectiveDate: "2026-10-01",
9
+ codeCount: 74879,
10
+ });
6
11
  const ensureICD10DatasetLoaded = (data) => {
7
12
  const datasetHasEntries = data && Object.keys(data).length > 0;
8
13
  if (!datasetHasEntries) {
package/dist/index.d.cts CHANGED
@@ -1,6 +1,12 @@
1
1
  export type ICD10Dictionary = {
2
2
  [code: string]: string;
3
3
  };
4
+ export type ICD10CMRelease = {
5
+ readonly fiscalYear: number;
6
+ readonly effectiveDate: string;
7
+ readonly codeCount: number;
8
+ };
9
+ export declare const ICD10_CM_RELEASE: ICD10CMRelease;
4
10
  export declare const ensureICD10DatasetLoaded: (data: ICD10Dictionary) => ICD10Dictionary;
5
11
  export declare const normalizeICD10Code: (code: string) => string;
6
12
  export declare const getICD10Description: (code: string) => string | undefined;
package/dist/index.d.mts CHANGED
@@ -1,4 +1,4 @@
1
1
  import { getICD10Description } from "./index.cjs";
2
- export { getICD10Description, ensureICD10DatasetLoaded, normalizeICD10Code, } from "./index.cjs";
3
- export type { ICD10Dictionary } from "./index.cjs";
2
+ export { getICD10Description, ensureICD10DatasetLoaded, normalizeICD10Code, ICD10_CM_RELEASE, } from "./index.cjs";
3
+ export type { ICD10Dictionary, ICD10CMRelease } from "./index.cjs";
4
4
  export default getICD10Description;
package/dist/index.mjs CHANGED
@@ -1,3 +1,3 @@
1
1
  import { getICD10Description } from "./index.cjs";
2
- export { getICD10Description, ensureICD10DatasetLoaded, normalizeICD10Code, } from "./index.cjs";
2
+ export { getICD10Description, ensureICD10DatasetLoaded, normalizeICD10Code, ICD10_CM_RELEASE, } from "./index.cjs";
3
3
  export default getICD10Description;
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@lowlysre/icd-10-cm",
3
- "version": "3.0.0",
4
- "description": "ICD-10-CM (Clinical Modification) data for use in the US healthcare system",
3
+ "version": "3.1.1",
4
+ "description": "FY2027 ICD-10-CM diagnosis codes and descriptions (CDC/NCHS, effective October 1, 2026) with TypeScript types and zero dependencies",
5
5
  "main": "./dist/index.cjs",
6
6
  "module": "./dist/index.mjs",
7
7
  "types": "./dist/index.d.cts",
@@ -23,9 +23,13 @@
23
23
  "types": "./dist/index.d.cts",
24
24
  "default": "./dist/index.cjs"
25
25
  }
26
- }
26
+ },
27
+ "./package.json": "./package.json"
27
28
  },
28
29
  "sideEffects": false,
30
+ "engines": {
31
+ "node": ">=22"
32
+ },
29
33
  "author": "John McCall",
30
34
  "license": "MIT",
31
35
  "files": [
@@ -38,7 +42,12 @@
38
42
  "tag": "latest"
39
43
  },
40
44
  "repository": {
41
- "url": "https://github.com/lowlysre/icd-10-cm"
45
+ "type": "git",
46
+ "url": "git+https://github.com/lowlysre/icd-10-cm.git"
47
+ },
48
+ "homepage": "https://github.com/lowlysre/icd-10-cm#readme",
49
+ "bugs": {
50
+ "url": "https://github.com/lowlysre/icd-10-cm/issues"
42
51
  },
43
52
  "keywords": [
44
53
  "icd",
@@ -46,10 +55,24 @@
46
55
  "icd-code",
47
56
  "icd10",
48
57
  "icd-10-cm",
58
+ "icd10cm",
59
+ "icd-10-cm-codes",
60
+ "diagnosis",
61
+ "diagnosis-codes",
49
62
  "medical",
63
+ "medical-coding",
64
+ "medical-billing",
50
65
  "healthcare",
51
- "diagnosis",
52
- "who"
66
+ "health-data",
67
+ "cdc",
68
+ "nchs",
69
+ "cms",
70
+ "fhir",
71
+ "ai",
72
+ "llm",
73
+ "offline",
74
+ "fy2027",
75
+ "typescript"
53
76
  ],
54
77
  "devDependencies": {
55
78
  "@types/node": "^26.1.1",