From bf27a461e8594eb09f2586b910fe5b7b88a8b525 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Eray=20Hano=C4=9Flu?= Date: Tue, 14 Apr 2026 11:04:46 +0300 Subject: [PATCH 1/5] chore: update project configuration --- package-lock.json | 12 ++++++------ packages/dictionary/README.md | 4 ++-- packages/hl7v2/test/tsconfig.json | 3 ++- packages/net/README.md | 2 +- packages/net/test/tsconfig.json | 3 ++- tsconfig-test.json | 9 ++------- 6 files changed, 15 insertions(+), 18 deletions(-) diff --git a/package-lock.json b/package-lock.json index fb6d22d..e3b17fe 100644 --- a/package-lock.json +++ b/package-lock.json @@ -6367,7 +6367,7 @@ }, "packages/dictionary": { "name": "hl7v2-dictionary", - "version": "1.8.0", + "version": "1.8.1", "license": "MIT", "dependencies": { "@jsopen/objects": "^2.2.1", @@ -6383,7 +6383,7 @@ } }, "packages/hl7v2": { - "version": "1.8.0", + "version": "1.8.1", "license": "MIT", "dependencies": { "@jsopen/objects": "^2.2.1", @@ -6402,12 +6402,12 @@ "node": ">=20.0" }, "peerDependencies": { - "hl7v2-dictionary": "^1.8.0" + "hl7v2-dictionary": "^1.8.1" } }, "packages/net": { "name": "hl7v2-net", - "version": "1.8.0", + "version": "1.8.1", "license": "MIT", "dependencies": { "@jsopen/objects": "^2.2.1", @@ -6429,8 +6429,8 @@ "node": ">=20.0" }, "peerDependencies": { - "hl7v2": "^1.8.0", - "hl7v2-dictionary": "^1.8.0" + "hl7v2": "^1.8.1", + "hl7v2-dictionary": "^1.8.1" } } } diff --git a/packages/dictionary/README.md b/packages/dictionary/README.md index 8bc3d53..af6aa71 100644 --- a/packages/dictionary/README.md +++ b/packages/dictionary/README.md @@ -27,8 +27,8 @@ HL7v2 is available under [MIT](LICENSE) license. [npm-url]: https://npmjs.org/package/hl7v2-dictionary [ci-test-image]: https://github.com/panates/hl7v2/actions/workflows/test.yml/badge.svg [ci-test-url]: https://github.com/panates/hl7v2/actions/workflows/test.yml -[coveralls-image]: https://img.shields.io/coveralls/panates/hl7v2-dictionary/master.svg -[coveralls-url]: https://coveralls.io/r/panates/hl7v2-dictionary +[coveralls-image]: https://img.shields.io/coveralls/panates/hl7v2/master.svg +[coveralls-url]: https://coveralls.io/github/panates/hl7v2 [downloads-image]: https://img.shields.io/npm/dm/hl7v2-dictionary.svg [downloads-url]: https://npmjs.org/package/hl7v2-dictionary [gitter-image]: https://badges.gitter.im/panates/hl7v2-dictionary.svg diff --git a/packages/hl7v2/test/tsconfig.json b/packages/hl7v2/test/tsconfig.json index 6caabd0..dbb3252 100644 --- a/packages/hl7v2/test/tsconfig.json +++ b/packages/hl7v2/test/tsconfig.json @@ -1,3 +1,4 @@ { - "extends": ["../tsconfig.json", "../../../tsconfig-test.json"] + "extends": "../../../tsconfig-test.json", + "include": ["."], } diff --git a/packages/net/README.md b/packages/net/README.md index 7608ba0..c8779aa 100644 --- a/packages/net/README.md +++ b/packages/net/README.md @@ -28,7 +28,7 @@ HL7v2 is available under [MIT](LICENSE) license. [ci-test-image]: https://github.com/panates/hl7v2/actions/workflows/test.yml/badge.svg [ci-test-url]: https://github.com/panates/hl7v2/actions/workflows/test.yml [coveralls-image]: https://img.shields.io/coveralls/panates/hl7v2/master.svg -[coveralls-url]: https://coveralls.io/r/panates/hl7v2 +[coveralls-url]: https://coveralls.io/github/panates/hl7v2 [downloads-image]: https://img.shields.io/npm/dm/hl7v2.svg [downloads-url]: https://npmjs.org/package/hl7v2 [gitter-image]: https://badges.gitter.im/panates/hl7v2.svg diff --git a/packages/net/test/tsconfig.json b/packages/net/test/tsconfig.json index 6caabd0..dbb3252 100644 --- a/packages/net/test/tsconfig.json +++ b/packages/net/test/tsconfig.json @@ -1,3 +1,4 @@ { - "extends": ["../tsconfig.json", "../../../tsconfig-test.json"] + "extends": "../../../tsconfig-test.json", + "include": ["."], } diff --git a/tsconfig-test.json b/tsconfig-test.json index a2e0534..0e6bc3d 100644 --- a/tsconfig-test.json +++ b/tsconfig-test.json @@ -1,16 +1,11 @@ { + "extends": "./tsconfig-base.json", "compilerOptions": { "types": ["node", "mocha"], - "sourceMap": true, "paths": { "hl7v2": ["./packages/hl7v2/src/index.js"], "hl7v2-net": ["./packages/net/src/index.js"], "hl7v2-dictionary": ["./packages/dictionary/src/index.js"] } - }, - "references": [ - { "path": "./packages/dictionary" }, - { "path": "./packages/hl7v2" }, - { "path": "./packages/net" } - ] + } } From 0733d24d79f2333ba38195d9831866be862edbdb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Eray=20Hano=C4=9Flu?= Date: Tue, 14 Apr 2026 11:28:05 +0300 Subject: [PATCH 2/5] docs: improve README with detailed usage examples and API documentation --- packages/dictionary/README.md | 196 ++++++++++++++- packages/hl7v2/README.md | 433 +++++++++++++++++++++++++++++++++- packages/net/README.md | 301 +++++++++++++++++++++-- 3 files changed, 898 insertions(+), 32 deletions(-) diff --git a/packages/dictionary/README.md b/packages/dictionary/README.md index af6aa71..719f8b1 100644 --- a/packages/dictionary/README.md +++ b/packages/dictionary/README.md @@ -1,4 +1,4 @@ -# HL7v2 Dictionary +# hl7v2-dictionary [![NPM Version][npm-image]][npm-url] [![NPM Downloads][downloads-image]][downloads-url] @@ -7,7 +7,7 @@ ## About -HL7 v2.x dictionaries +HL7 v2.x dictionary for Node.js. This package provides version-specific definitions for segments, data types, and messages, supporting versions from 2.1 to 2.8. It is used by the `hl7v2` parser and serializer to understand message structures. ## Installation @@ -15,11 +15,191 @@ HL7 v2.x dictionaries $ npm install hl7v2-dictionary --save ``` +## Usage Example + +### Accessing a Dictionary + +```typescript +import { dictionaries, HL7Version } from 'hl7v2-dictionary'; + +const dict25 = dictionaries[HL7Version.v2_5]; + +console.log('Version:', dict25.version); +console.log('PID Segment definition:', dict25.segments['PID']); +``` + +### Extending a Dictionary + +```typescript +import { dictionaries, HL7Version } from 'hl7v2-dictionary'; + +const customDict = dictionaries[HL7Version.v2_5].extend({ + version: '2.5-custom' as any, + segments: { + Z01: { + desc: 'Custom Segment', + fields: { + 1: { type: 'ST', desc: 'Custom Field 1', opt: 'R' } + } + } + } +}); + +console.log('Custom Segment:', customDict.segments['Z01']); +``` + +## API + +### HL7Dictionary + +The `HL7Dictionary` class holds definitions for a specific HL7 version. + +#### Properties + +- `version: HL7Version` - The HL7 version this dictionary represents. +- `segments: Record` - Segment definitions. +- `types: Record` - Data type definitions. +- `messages: Record` - Message structure definitions. + +#### Methods + +##### .extend() +Creates a new dictionary by extending the current one with new or overridden definitions. +`extend(args: { version?: HL7Version; segments?: Record>; types?: Record>; messages?: Record; }): HL7Dictionary` + +example +```typescript +const extendedDict = dict.extend({ + segments: { + PID: { + fields: { + 1: { desc: 'Overridden Description' } + } + } + } +}); +``` + +##### .overwriteSegments() +Merges new segment definitions into the current dictionary. +`overwriteSegments(segmentsDefs: Record>): void` + +example +```typescript +dict.overwriteSegments({ + PID: { + fields: { + 1: { desc: 'New Description' } + } + } +}); +``` + +##### .overwriteTypes() +Merges new data type definitions into the current dictionary. +`overwriteTypes(typeDefs: Record>): void` + +example +```typescript +dict.overwriteTypes({ + ST: { + desc: 'String Data Type' + } +}); +``` + +### Utility Functions + +##### .findNearestHL7Version() +Finds the nearest available HL7 version in the dictionary for a given version string. +`findNearestHL7Version(version: HL7Version): HL7Version` + +example +```typescript +import { findNearestHL7Version, HL7Version } from 'hl7v2-dictionary'; + +const nearest = findNearestHL7Version('2.5.2' as any); +// Returns HL7Version.v2_5 +``` + +##### .toHL7Date() +Formats a Date or string into an HL7 date string (YYYYMMDD). +`toHL7Date(value: Date | string): string` + +example +```typescript +import { toHL7Date } from 'hl7v2-dictionary'; + +const dateStr = toHL7Date(new Date('2023-10-27')); +// Returns "20231027" +``` + +##### .toHL7DateTime() +Formats a Date or string into an HL7 date-time string (YYYYMMDDHHMMSS). +`toHL7DateTime(value: Date | string): string` + +example +```typescript +import { toHL7DateTime } from 'hl7v2-dictionary'; + +const dateTimeStr = toHL7DateTime(new Date('2023-10-27T10:30:00')); +// Returns "20231027103000" +``` + +##### .toHL7Time() +Formats a Date or string into an HL7 time string (HHMMSS). +`toHL7Time(value: Date | string): string` + +example +```typescript +import { toHL7Time } from 'hl7v2-dictionary'; + +const timeStr = toHL7Time(new Date('2023-10-27T10:30:00')); +// Returns "103000" +``` + +### Interfaces + +#### HL7SegmentDefinition +- `desc?: string` - Description of the segment. +- `fields: Record` - Map of field index to field definition. + +#### HL7FieldDefinition +- `type: string` - The data type of the field. +- `desc?: string` - Description of the field. +- `opt?: HL7DatatypeOptional` - Optionality ('R', 'O', 'S', 'C', 'B'). +- `rep?: HL7DatatypeRepetition` - Repetition (number or 'infinite'). +- `len?: number` - Maximum length. +- `table?: number` - Associated table number. + +#### HL7DataTypeDefinition +- `desc?: string` - Description of the data type. +- `fields?: Record` - Components of the data type (if complex). + +#### HL7MessageDefinition +- `desc?: string` - Description of the message. +- `segments?: Record` - Message structure definition. + +### Enums + +#### HL7Version +- `v2_1 = '2.1'` +- `v2_2 = '2.2'` +- `v2_3 = '2.3'` +- `v2_3_1 = '2.3.1'` +- `v2_4 = '2.4'` +- `v2_5 = '2.5'` +- `v2_5_1 = '2.5.1'` +- `v2_6 = '2.6'` +- `v2_7 = '2.7'` +- `v2_7_1 = '2.7.1'` +- `v2_8 = '2.8'` + ## Node Compatibility -- node >= 18.x +- node >= 20.x -### License +## License HL7v2 is available under [MIT](LICENSE) license. @@ -31,11 +211,3 @@ HL7v2 is available under [MIT](LICENSE) license. [coveralls-url]: https://coveralls.io/github/panates/hl7v2 [downloads-image]: https://img.shields.io/npm/dm/hl7v2-dictionary.svg [downloads-url]: https://npmjs.org/package/hl7v2-dictionary -[gitter-image]: https://badges.gitter.im/panates/hl7v2-dictionary.svg -[gitter-url]: https://gitter.im/panates/hl7v2-dictionary?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge -[dependencies-image]: https://david-dm.org/panates/hl7v2-dictionary/status.svg -[dependencies-url]: https://david-dm.org/panates/hl7v2-dictionary -[devdependencies-image]: https://david-dm.org/panates/hl7v2-dictionary/dev-status.svg -[devdependencies-url]: https://david-dm.org/panates/hl7v2-dictionary?type=dev -[quality-image]: http://npm.packagequality.com/shield/hl7v2-dictionary.png -[quality-url]: http://packagequality.com/#?package=hl7v2-dictionary diff --git a/packages/hl7v2/README.md b/packages/hl7v2/README.md index b0f8bb5..3de8898 100644 --- a/packages/hl7v2/README.md +++ b/packages/hl7v2/README.md @@ -7,7 +7,7 @@ ## About -HL7 v2.x parser, serializer and validator +HL7 v2.x parser, serializer and validator for Node.js. ## Installation @@ -15,27 +15,456 @@ HL7 v2.x parser, serializer and validator $ npm install hl7v2 --save ``` +## Usage Example + +```typescript +import { HL7Message } from 'hl7v2'; + +const hl7String = 'MSH|^~\\&|SENDING_APP|SENDING_FACILITY|RECEIVING_APP|RECEIVING_FACILITY|202305101000||ADT^A01|123|P|2.5\r' + + 'PID|||PATIENT_ID||DOE^JOHN'; + +const message = HL7Message.parse(hl7String); + +// Access segments +const pid = message.getSegment('PID'); +console.log(pid.field(5).getValue()); // { familyName: 'DOE', givenName: 'JOHN' } + +// Create new message +const msg = new HL7Message('2.5'); +const msh = msg.header; +msh.field(3).setValue('MY_APP'); +msg.addSegment('PID').field(5).setValue({ familyName: 'SMITH', givenName: 'JANE' }); + +console.log(msg.toHL7String()); +``` + +## API Reference + +### HL7Message + +The root object representing an HL7 message. + +#### Properties + +- `version: string`: HL7 version (e.g., '2.5'). +- `segments: HL7Segment[]`: Array of all segments in the message. +- `header: HL7Segment`: The MSH segment of the message. +- `fieldSeparator: string`: Character used to separate fields (default `|`). +- `componentSeparator: string`: Character used to separate components (default `^`). +- `repetitionSeparator: string`: Character used to separate repetitions (default `~`). +- `escapeCharacter: string`: Character used for escaping (default `\`). +- `subComponentSeparator: string`: Character used to separate sub-components (default `&`). + +#### Methods + +##### .parse() + +Parses an HL7 string into an `HL7Message` object. +`static parse(input: string, options?: HL7MessageParseOptions): HL7Message` +example + +```typescript +const message = HL7Message.parse('MSH|^~\\&|SENDING_APP|...'); +``` + +##### .addSegment() + +Adds a new segment to the message. +`addSegment(segmentType: string, index?: number): HL7Segment` +example + +```typescript +const pid = message.addSegment('PID'); +``` + +##### .getSegment() + +Finds a segment by type. +`getSegment(segmentType: string, indexOrAfter?: number | HL7Segment): HL7Segment | undefined` +example + +```typescript +const msh = message.getSegment('MSH'); +const firstObx = message.getSegment('OBX'); +const secondObx = message.getSegment('OBX', 1); // Get second OBX +const nextObx = message.getSegment('OBX', firstObx); // Get OBX after firstObx +``` + +##### .toHL7String() + +Serializes the message back to an HL7 string. +`toHL7String(options?: HL7MessageSerializeOptions): string` +example + +```typescript +const hl7 = message.toHL7String(); +``` + +##### .createAck() + +Creates an ACK message for the current message. +`createAck(ackCode?: string, textMessage?: string): HL7Message` +example + +```typescript +const ack = message.createAck('AA', 'Message accepted'); +``` + +##### .createNak() + +Creates a NAK message for the current message. +`createNak(errors: HL7Error[]): HL7Message` +example + +```typescript +const error = new HL7Error('Invalid field value', { hl7ErrorCode: 102 }); +const nak = message.createNak([error]); +``` + +--- + +### HL7Segment + +Represents a single segment (e.g., PID, MSH) within an HL7 message. + +#### Properties + +- `segmentType: string`: The 3-character segment type (e.g., 'PID'). +- `fields: HL7Field[]`: Array of fields in the segment. +- `message: HL7Message`: Reference to the parent message. + +#### Methods + +##### .field() + +Returns the field at the specified position (1-indexed). +`field(position: number): HL7Field` +example + +```typescript +const patientName = pid.field(5); +``` + +##### .toHL7String() + +Serializes the segment to an HL7 string. +`toHL7String(options?: Hl7SegmentSerializeOptions): string` +example + +```typescript +const hl7 = pid.toHL7String(); +``` + +--- + +### HL7Field + +Represents a field within a segment. Fields can contain one or more repetitions. + +#### Properties + +- `position: number`: The position of the field within the segment (1-indexed). +- `repetitions: HL7Repetition[]`: Array of repetitions for this field. +- `segment: HL7Segment`: Reference to the parent segment. + +#### Methods + +##### .repetition() + +Returns the repetition at the specified index (0-indexed). +`repetition(index?: number): HL7Repetition` +example + +```typescript +const firstRep = field.repetition(0); +``` + +##### .rep() + +Alias for `repetition()`. +`rep(index?: number): HL7Repetition` +example + +```typescript +const firstRep = field.rep(0); +``` + +##### .component() + +Shortcut to access a component in the first repetition. +`component(position: number): Hl7Component` +example + +```typescript +const comp1 = field.component(1); +``` + +##### .comp() + +Alias for `component()`. +`comp(position: number): Hl7Component` +example + +```typescript +const comp1 = field.comp(1); +``` + +##### .getValue() + +Gets the value of the field. +`getValue(component?: number, subComponent?: number): any` +example + +```typescript +const value = field.getValue(); +const compValue = field.getValue(1); +const subCompValue = field.getValue(1, 1); +``` + +##### .setValue() + +Sets the value of the field. +`setValue(value: any, component?: number, subComponent?: number): void` +example + +```typescript +field.setValue('DOE^JOHN'); +field.setValue('DOE', 1); +field.setValue('JOHN', 1, 1); +``` + +##### .toHL7String() + +Serializes the field to an HL7 string. +`toHL7String(options?: Hl7FieldSerializeOptions): string` +example + +```typescript +const hl7 = field.toHL7String(); +``` + +--- + +### HL7Repetition + +Represents a single repetition of a field. + +#### Properties + +- `components: Hl7Component[]`: Array of components in this repetition. +- `field: HL7Field`: Reference to the parent field. + +#### Methods + +##### .component() + +Returns the component at the specified position (1-indexed). +`component(position: number): Hl7Component` +example + +```typescript +const comp = repetition.component(1); +``` + +##### .comp() + +Alias for `component()`. +`comp(position: number): Hl7Component` +example + +```typescript +const comp = repetition.comp(1); +``` + +##### .getValue() + +Gets the value. +`getValue(component?: number, subComponent?: number): any` +example + +```typescript +const value = repetition.getValue(); +const subValue = repetition.getValue(1, 1); +``` + +##### .setValue() + +Sets the value. +`setValue(value: any, component?: number, subComponent?: number): this` +example + +```typescript +repetition.setValue('DOE', 1); +``` + +--- + +### Hl7Component + +Represents a component within a field repetition. + +#### Properties + +- `position: number`: Position within the repetition (1-indexed). +- `subComponents: Hl7SubComponent[]`: Array of sub-components. + +#### Methods + +##### .subComponent() + +Returns the sub-component at the specified position (1-indexed). +`subComponent(position: number): Hl7SubComponent` +example + +```typescript +const sub = component.subComponent(1); +``` + +##### .subcomp() + +Alias for `subComponent()`. +`subcomp(position: number): Hl7SubComponent` +example + +```typescript +const sub = component.subcomp(1); +``` + +##### .getValue() + +Gets the value. +`getValue(subComponent?: number): any` +example + +```typescript +const value = component.getValue(); +const subValue = component.getValue(1); +``` + +##### .setValue() + +Sets the value. +`setValue(value: any, subComponent?: number): this` +example + +```typescript +component.setValue('JOHN', 1); +``` + +--- + +### Hl7SubComponent + +The smallest unit of data in an HL7 message. + +#### Properties + +- `position: number`: Position within the component (1-indexed). +- `value: any`: The actual data value. + +--- + +### HL7MessageNode + +Used for representing the hierarchical structure of a message (groups and segments). + +#### Methods + +##### .getSegment() + +Searches for a segment within this node. +`getSegment(segmentType: string, indexOrAfter?: number | HL7Segment): HL7Segment | undefined` +example + +```typescript +const seg = node.getSegment('PID'); +``` + +##### .getNode() + +Searches for a child node by name. +`getNode(nodeName: string, indexOrAfter?: number | HL7MessageNode): HL7MessageNode | undefined` +example + +```typescript +const childNode = node.getNode('PATIENT_RESULT'); +``` + +--- + +### HL7Error + +Custom error class for HL7-related errors. + +#### Properties + +- `hl7ErrorCode?: number`: HL7 standard error code. +- `severity?: 'E' | 'W' | 'I'`: Error severity (Error, Warning, Information). +- `segmentType?: string`: Segment where the error occurred. +- `fieldPosition?: number`: Field position where the error occurred. + +--- + +##### .hl7Escape() + +Escapes a string for use in an HL7 message. +`hl7Escape(value: string, message?: HL7Message): string` +example + +```typescript +const escaped = hl7Escape('DOE^JOHN'); // "DOE\S\JOHN" +``` + +#### Methods + +##### .hl7UnEscape() + +Unescapes an HL7 string. +`hl7UnEscape(value: string, message?: HL7Message): string | Buffer | null` +example + +```typescript +const unescaped = hl7UnEscape('DOE\\S\\JOHN'); // "DOE^JOHN" +``` + +--- + ## Node Compatibility -- node >= 18.x +- node >= 20.x ### License HL7v2 is available under [MIT](LICENSE) license. [npm-image]: https://img.shields.io/npm/v/hl7v2.svg + [npm-url]: https://npmjs.org/package/hl7v2 + [ci-test-image]: https://github.com/panates/hl7v2/actions/workflows/test.yml/badge.svg + [ci-test-url]: https://github.com/panates/hl7v2/actions/workflows/test.yml + [coveralls-image]: https://img.shields.io/coveralls/panates/hl7v2/master.svg + [coveralls-url]: https://coveralls.io/r/panates/hl7v2 + [downloads-image]: https://img.shields.io/npm/dm/hl7v2.svg + [downloads-url]: https://npmjs.org/package/hl7v2 + [gitter-image]: https://badges.gitter.im/panates/hl7v2.svg + [gitter-url]: https://gitter.im/panates/hl7v2?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge + [dependencies-image]: https://david-dm.org/panates/hl7v2/status.svg + [dependencies-url]: https://david-dm.org/panates/hl7v2 + [devdependencies-image]: https://david-dm.org/panates/hl7v2/dev-status.svg + [devdependencies-url]: https://david-dm.org/panates/hl7v2?type=dev + [quality-image]: http://npm.packagequality.com/shield/hl7v2.png + [quality-url]: http://packagequality.com/#?package=hl7v2 diff --git a/packages/net/README.md b/packages/net/README.md index c8779aa..556ca0a 100644 --- a/packages/net/README.md +++ b/packages/net/README.md @@ -1,4 +1,4 @@ -# HL7v2 +# hl7v2-net [![NPM Version][npm-image]][npm-url] [![NPM Downloads][downloads-image]][downloads-url] @@ -7,35 +7,300 @@ ## About -HL7 v2.x TCP Client/Server for NodeJS +HL7 v2.x MLLP server and client for Node.js. This package provides a high-level API for building HL7 servers and clients using TCP or TLS. ## Installation ```bash -$ npm install hl7v2 --save +$ npm install hl7v2-net --save ``` +## Usage Example + +### Server Example + +```typescript +import { HL7Server } from 'hl7v2-net'; + +const server = HL7Server.createServer(); + +// Middleware to handle incoming messages +server.use(async (req, res) => { + console.log('Received message:', req.message.toHL7String()); + // res.message is already initialized with an ACK + // You can modify it or just let the server send it automatically +}); + +server.listen(12345, () => { + console.log('HL7 Server listening on port 12345'); +}); +``` + +### Client Example + +```typescript +import { Hl7Client } from 'hl7v2-net'; +import { HL7Message } from 'hl7v2'; + +const client = Hl7Client.createClient({ host: 'localhost', port: 12345 }); + +async function send() { + await client.connect(); + + const msg = new HL7Message(); + msg.header.field(9).setValue('ORU^R01'); + msg.addSegment('PID').field(5).setValue('DOE^JOHN'); + + const response = await client.sendMessageWaitAck(msg); + console.log('Received ACK:', response.toHL7String()); + + await client.close(); +} + +send().catch(console.error); +``` + +## API Reference + +### HL7Server + +The `HL7Server` class is used to create an HL7 MLLP server. + +#### Methods + +##### .createServer() + +Creates a new `HL7Server` instance for TCP connections. +`static createServer(listenerOptions?: net.ListenOptions, options?: HL7Server.Options): HL7Server` +example + +```typescript +const server = HL7Server.createServer(); +``` + +##### .createTlsServer() + +Creates a new `HL7Server` instance for TLS connections. +`static createTlsServer(listenerOptions?: tls.TlsOptions, options?: HL7Server.Options): HL7Server` +example + +```typescript +const server = HL7Server.createTlsServer({ + key: fs.readFileSync('server-key.pem'), + cert: fs.readFileSync('server-cert.pem') +}); +``` + +##### .listen() + +Starts the server listening for connections. +`listen(port?: number, hostname?: string, backlog?: number): Promise` +example + +```typescript +await server.listen(12345); +``` + +##### .close() + +Stops the server from accepting new connections and closes existing ones. +`close(waitRunningHandlers?: number): Promise` +example + +```typescript +await server.close(5000); // Wait up to 5s for running handlers +``` + +##### .use() + +Adds a middleware handler to the server. +`use(handler: HL7Middleware | HL7Router, priority?: number): void` +example + +```typescript +server.use((req, res, next) => { + // Do something + next(); +}); +``` + +--- + +### Hl7Client + +The `Hl7Client` class is used to create an HL7 MLLP client. + +#### Properties + +- `connected: boolean`: Whether the client is currently connected. +- `readyState: string`: The state of the underlying socket. + +#### Methods + +##### .createClient() + +Creates a new `Hl7Client` instance for TCP connections. +`static createClient(options: Hl7Client.NetConnectOptions): Hl7Client` +example + +```typescript +const client = Hl7Client.createClient({ host: 'localhost', port: 12345 }); +``` + +##### .createTlsClient() + +Creates a new `Hl7Client` instance for TLS connections. +`static createTlsClient(options: Hl7Client.TlsConnectOptions): Hl7Client` +example + +```typescript +const client = Hl7Client.createTlsClient({ host: 'localhost', port: 12345, rejectUnauthorized: false }); +``` + +##### .connect() + +Connects to the server. +`connect(): Promise` +example + +```typescript +await client.connect(); +``` + +##### .close() + +Closes the connection. +`close(): Promise` +example + +```typescript +await client.close(); +``` + +##### .sendMessage() + +Sends an HL7 message without waiting for an acknowledgment. +`sendMessage(message: HL7Message | string): Promise` +example + +```typescript +await client.sendMessage(msg); +``` + +##### .sendMessageWaitAck() + +Sends an HL7 message and waits for an acknowledgment. +`sendMessageWaitAck(message: HL7Message | string): Promise` +example + +```typescript +const ack = await client.sendMessageWaitAck(msg); +``` + +--- + +### HL7Socket + +Represents an HL7 MLLP socket connection. + +#### Properties + +- `connected: boolean`: Whether the socket is connected. +- `remoteAddress: string`: The remote IP address. +- `remotePort: number`: The remote port. + +#### Methods + +##### .sendMessage() + +Sends an HL7 message. +`sendMessage(message: HL7Message | string): Promise` +example + +```typescript +await socket.sendMessage(msg); +``` + +##### .sendMessageWaitAck() + +Sends an HL7 message and waits for an acknowledgment. +`sendMessageWaitAck(message: HL7Message | string): Promise` +example + +```typescript +const ack = await socket.sendMessageWaitAck(msg); +``` + +--- + +### HL7Router + +Provides routing capabilities for HL7 messages based on middleware. + +#### Methods + +##### .use() + +Adds a middleware or another router to this router. +`use(handler: HL7Middleware | HL7Router, priority?: number): void` +example + +```typescript +const router = new HL7Router(); +router.use((req, res) => { ... }); +server.use(router); +``` + +--- + +### HL7Request + +Represents an incoming HL7 request. + +#### Properties + +- `socket: HL7Socket`: The socket the request was received on. +- `message: HL7Message`: The received HL7 message. + +--- + +### HL7Response + +Represents the response to an HL7 request. + +#### Properties + +- `request: HL7Request`: The corresponding request. +- `message: HL7Message`: The HL7 message to be sent as a response (defaults to an ACK). +- `finished: boolean`: Whether the response has been sent. + +#### Methods + +##### .failed() + +Marks the request as failed and sets the response to a NAK message. +`failed(error: Error): void` +example + +```typescript +res.failed(new Error('Processing failed')); +``` + +--- + ## Node Compatibility -- node >= 18.x +- node >= 20.x ### License -HL7v2 is available under [MIT](LICENSE) license. +hl7v2-net is available under [MIT](LICENSE) license. -[npm-image]: https://img.shields.io/npm/v/hl7v2.svg -[npm-url]: https://npmjs.org/package/hl7v2 +[npm-image]: https://img.shields.io/npm/v/hl7v2-net.svg +[npm-url]: https://npmjs.org/package/hl7v2-net [ci-test-image]: https://github.com/panates/hl7v2/actions/workflows/test.yml/badge.svg [ci-test-url]: https://github.com/panates/hl7v2/actions/workflows/test.yml [coveralls-image]: https://img.shields.io/coveralls/panates/hl7v2/master.svg -[coveralls-url]: https://coveralls.io/github/panates/hl7v2 -[downloads-image]: https://img.shields.io/npm/dm/hl7v2.svg -[downloads-url]: https://npmjs.org/package/hl7v2 -[gitter-image]: https://badges.gitter.im/panates/hl7v2.svg -[gitter-url]: https://gitter.im/panates/hl7v2?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge -[dependencies-image]: https://david-dm.org/panates/hl7v2/status.svg -[dependencies-url]: https://david-dm.org/panates/hl7v2 -[devdependencies-image]: https://david-dm.org/panates/hl7v2/dev-status.svg -[devdependencies-url]: https://david-dm.org/panates/hl7v2?type=dev -[quality-image]: http://npm.packagequality.com/shield/hl7v2.png -[quality-url]: http://packagequality.com/#?package=hl7v2 +[coveralls-url]: https://coveralls.io/r/panates/hl7v2 +[downloads-image]: https://img.shields.io/npm/dm/hl7v2-net.svg +[downloads-url]: https://npmjs.org/package/hl7v2-net From 462b6717528c15d27eb19ec63ef5a5507174beec Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Eray=20Hano=C4=9Flu?= Date: Tue, 14 Apr 2026 11:28:29 +0300 Subject: [PATCH 3/5] 1.8.2 --- packages/dictionary/package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/dictionary/package.json b/packages/dictionary/package.json index 91ed4b6..9a6477e 100644 --- a/packages/dictionary/package.json +++ b/packages/dictionary/package.json @@ -1,7 +1,7 @@ { "name": "hl7v2-dictionary", "description": "HL7 v2 parser, serializer, validator for NodeJS", - "version": "1.8.1", + "version": "1.8.2", "author": "Panates", "license": "MIT", "private": true, From 7bb71db27dc27c488450b972a2b86c3dcb7d0720 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Eray=20Hano=C4=9Flu?= Date: Tue, 14 Apr 2026 11:28:29 +0300 Subject: [PATCH 4/5] 1.8.2 --- packages/hl7v2/package.json | 4 ++-- packages/net/package.json | 6 +++--- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/packages/hl7v2/package.json b/packages/hl7v2/package.json index 86329d5..644f6bd 100644 --- a/packages/hl7v2/package.json +++ b/packages/hl7v2/package.json @@ -1,7 +1,7 @@ { "name": "hl7v2", "description": "HL7 v2 parser, serializer, validator for NodeJS", - "version": "1.8.1", + "version": "1.8.2", "author": "Panates", "license": "MIT", "private": true, @@ -16,7 +16,7 @@ "uid": "^2.0.2" }, "peerDependencies": { - "hl7v2-dictionary": "^1.8.1" + "hl7v2-dictionary": "^1.8.2" }, "devDependencies": { "expect": "^30.3.0" diff --git a/packages/net/package.json b/packages/net/package.json index 2c2920c..382e9e7 100644 --- a/packages/net/package.json +++ b/packages/net/package.json @@ -1,7 +1,7 @@ { "name": "hl7v2-net", "description": "HL7 v2 server/client for NodeJS", - "version": "1.8.1", + "version": "1.8.2", "author": "Panates", "license": "MIT", "private": true, @@ -18,8 +18,8 @@ "uid": "^2.0.2" }, "peerDependencies": { - "hl7v2": "^1.8.1", - "hl7v2-dictionary": "^1.8.1" + "hl7v2": "^1.8.2", + "hl7v2-dictionary": "^1.8.2" }, "devDependencies": { "@types/reconnect-core": "^1.3.5", From b2355d001d1271f0d581a6972bfd676221bb24df Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Eray=20Hano=C4=9Flu?= Date: Tue, 14 Apr 2026 11:38:52 +0300 Subject: [PATCH 5/5] docs: expand README with package descriptions and badges cleanup --- README.md | 35 +++++++++++++++++++++++++++++++++-- 1 file changed, 33 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index ce89222..7622f9d 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,5 @@ -# HL7v2 +# HL7 v2.x Javascript + HL7 v2 parser, serializer, validator and tcp client/server for NodeJS [![NPM Version][npm-image]][npm-url] @@ -6,30 +7,60 @@ HL7 v2 parser, serializer, validator and tcp client/server for NodeJS [![CI Tests][ci-test-image]][ci-test-url] [![Test Coverage][coveralls-image]][coveralls-url] + +## [hl7v2](./packages/hl7v2/README.md) + +HL7 v2 parser, serializer, validator for NodeJS + +## [hl7v2-net](./packages/net/README.md) + +HL7 v2 server/client for NodeJS + +## [hl7v2-dictionary](./packages/dictionary/README.md) + +HL7 v2 dictionary for message parsing and serialization + ## Support + You can report bugs and discuss features on the [GitHub issues](https://github.com/panates/hl7v2/issues) page When you open an issue please provide the version of the NodeJS. ## Node Compatibility -- node >= 18.x +- node >= 18.x ### License + HL7v2 is available under [MIT](LICENSE) license. [npm-image]: https://img.shields.io/npm/v/hl7v2.svg + [npm-url]: https://npmjs.org/package/hl7v2 + [ci-test-image]: https://github.com/panates/hl7v2/actions/workflows/test.yml/badge.svg + [ci-test-url]: https://github.com/panates/hl7v2/actions/workflows/test.yml + [coveralls-image]: https://img.shields.io/coveralls/panates/hl7v2/master.svg + [coveralls-url]: https://coveralls.io/r/panates/hl7v2 + [downloads-image]: https://img.shields.io/npm/dm/hl7v2.svg + [downloads-url]: https://npmjs.org/package/hl7v2 + [gitter-image]: https://badges.gitter.im/panates/hl7v2.svg + [gitter-url]: https://gitter.im/panates/hl7v2?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge + [dependencies-image]: https://david-dm.org/panates/hl7v2/status.svg + [dependencies-url]:https://david-dm.org/panates/hl7v2 + [devdependencies-image]: https://david-dm.org/panates/hl7v2/dev-status.svg + [devdependencies-url]:https://david-dm.org/panates/hl7v2?type=dev + [quality-image]: http://npm.packagequality.com/shield/hl7v2.png + [quality-url]: http://packagequality.com/#?package=hl7v2