@nhealth/fhir-terminology 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nhealthorg
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,159 @@
+# @nhealth/fhir-terminology
+
+Terminology module for Nuxt applications using FHIR resources.
+
+`@nhealth/fhir-terminology` helps teams manage terminology packages from source files to generated FHIR artifacts and server import workflows.
+
+## Features
+
+- Parse common terminology source formats (for example ICD-10, LOINC, OPS, SNOMED CT)
+- Generate FHIR R4 terminology resources (CodeSystem and ValueSet)
+- Incremental rebuild behavior for local terminology sources
+- Package discovery and package-level metadata/indexing
+- Import and dry-run workflows for connected FHIR servers
+- Optional terminology UI app for exploration and operations
+
+## Installation
+
+```bash
+pnpm add @nhealth/fhir-terminology
+```
+
+Usually paired with:
+
+```bash
+pnpm add @nhealth/fhir
+```
+
+Optional (only if your setup requires workflow execution):
+
+```bash
+pnpm add nvent
+```
+
+## Minimal Setup
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  modules: [
+    '@nhealth/fhir',
+    '@nhealth/fhir-terminology',
+  ],
+
+  fhir: {
+    client: {
+      serverUrl: 'http://localhost:8103',
+      basePath: '/fhir/R4',
+    },
+  },
+
+  fhirTerminology: {
+    sourceDirs: ['./terminology'],
+    app: true,
+    appRoutePath: '/_terminology',
+  },
+})
+```
+
+Create terminology packages under:
+
+```text
+terminology/<package>/
+  terminology.manifest.json
+  <source files>
+```
+
+Then run:
+
+```bash
+pnpm dev
+# or
+pnpm build
+```
+
+## Quick Workflow
+
+1. Create a package folder under `terminology/`.
+2. Add `terminology.manifest.json` and source files.
+3. Start the app (`pnpm dev`) to generate artifacts.
+4. Open the terminology app (for example `/_terminology`).
+5. Run dry-run/import and validate results with terminology operations.
+
+Example package layout:
+
+```text
+terminology/
+  icd10/
+    terminology.manifest.json
+    icd10gm2026syst-meta.zip
+```
+
+Example manifest:
+
+```json
+{
+  "id": "icd10-2026",
+  "name": "ICD-10 2026",
+  "version": "2026",
+  "system": "http://fhir.de/CodeSystem/bfarm/icd10",
+  "format": "auto",
+  "sources": ["icd10gm2026syst-meta.zip"],
+  "resources": ["CodeSystem", "ValueSet"],
+  "hierarchical": true
+}
+```
+
+## What You Can Do with the Module
+
+- Build CodeSystem/ValueSet artifacts from local source files
+- Browse generated packages and concepts in the optional app
+- Run terminology operations against your configured FHIR server
+- Import generated resources with progress tracking
+
+## Supported Source Formats
+
+| Format | Typical use |
+|--------|-------------|
+| `auto` | Recommended default (auto-detect parser) |
+| `bfarm-icd10-csv` | ICD-10 BfArM sources |
+| `bfarm-ops-csv` | OPS BfArM sources |
+| `loinc-csv` | LOINC sources |
+| `snomed-rf2-zip` | SNOMED CT RF2 releases |
+| `fhir-json` | Prebuilt FHIR resources |
+| `generic-csv` | Custom CSV-based terminologies |
+
+## Key Module Options
+
+| Option | Type | Default | Purpose |
+|--------|------|---------|---------|
+| `sourceDirs` | `string[]` | `['./terminology']` | Terminology package discovery |
+| `app` | `boolean` | `false` | Enable bundled terminology app |
+| `appRoutePath` | `string` | module default | Route for terminology app |
+| `appLayout` | `string \| false` | `false` | Use a Nuxt layout for app pages |
+
+## API Surface (High Level)
+
+The module exposes server routes for:
+
+- package listing and package details
+- package resource inspection
+- import and dry-run workflows
+- task/progress retrieval
+
+Exact route usage is documented in the guides below.
+
+## Documentation
+
+- [Getting Started](./docs/getting-started.md)
+- [Manifest Reference](./docs/manifest-reference.md)
+- [Terminology UI Guide](./docs/terminology-server-ui.md)
+
+Internal engineering specs:
+
+- [Design Notes](./specs/DESIGN_NOTES.md)
+- [Hierarchy Navigation](./specs/HIERARCHY_NAVIGATION.md)
+
+## License
+
+MIT

package/dist/module.d.mts

@@ -0,0 +1,62 @@
+import * as nuxt_schema from 'nuxt/schema';
+
+type ModuleOptions = {
+    /**
+     * Directory that contains terminology source packages.
+     * Each sub-directory is treated as one package when it contains a
+     * `terminology.manifest.json` file.
+     * May be an absolute path or relative to the Nuxt project root.
+     * @default 'terminology'
+     */
+    sourcesDir?: string;
+    /**
+     * Storage mount used for generated terminology FHIR artifacts.
+     * Artifacts are generated into `.nuxt/fhir/terminology` during local build.
+      * @default 'fhir-terminology-generated'
+     */
+    generatedStorageBase?: string;
+    /**
+     * Automatically check and import missing/changed terminology packages on
+     * every server startup.
+     *
+     * RECOMMENDATION: Keep this `false` in production.
+     * Large terminologies (ICD-10: ~15 k codes, LOINC: ~100 k codes) can
+     * significantly delay startup. Use the admin API to trigger imports
+     * explicitly after deployments.
+     *
+     * @default false
+     */
+    autoSync?: boolean;
+    /**
+     * Maximum number of concepts per FHIR batch-bundle transaction.
+     * Reduce this value when upstream timeout errors occur on large imports.
+     * @default 500
+     */
+    batchSize?: number;
+    /**
+     * Register nvent iii workflow functions (upload/import/audit helpers) via
+     * `nvent:functions:extend` hook.
+     * @default true
+     */
+    nventWorkflows?: boolean;
+    /**
+     * Enable bundled terminology admin app route powered by nutils.
+     * @default false
+     */
+    app?: boolean;
+    /**
+     * Route path for the bundled terminology app.
+     * @default '/_terminology'
+     */
+    appRoutePath?: string;
+    /**
+     * Layout to use for the bundled app route.
+     * Set to false for standalone page.
+     * @default false
+     */
+    appLayout?: string | false;
+};
+declare const _default: nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;
+
+export { _default as default };
+export type { ModuleOptions };

package/dist/module.json

@@ -0,0 +1,9 @@
+{
+  "name": "@nhealth/fhir-terminology",
+  "version": "0.1.0",
+  "configKey": "fhirTerminology",
+  "builder": {
+    "@nuxt/module-builder": "1.0.2",
+    "unbuild": "unknown"
+  }
+}