TypeScript HL7 Client (and future HL7/FHIR Interface Engine)

Using this library you can decode, encode, and extract data from HL7 messages.

Decoding a HL7 Message will return a JSON object

import Msg from './src/'
import fs from 'fs'

const HL7 = fs.readFileSync('./sample.hl7', 'utf8')

const msg = new Msg(HL7)

console.log(msg.raw())

Encoding a HL7 Message JSON object will return a HL7 string

import Msg from './src/'
import fs from 'fs'

const msg = new Msg([
  {
    encodingCharacters: {
      fieldSep: '|',
      componentSep: '^',
      subComponentSep: '&',
      repetitionSep: '~',
      escapeChar: '\\',
    },
  },
  [
    ['MSH', '|', '^~\\&', 'HL7REG', 'UH', 'HL7LAB', 'CH', '200702280700', , ['PMU', 'B01', 'PMU_B01'], 'MSGID003', 'P', '2.5.1'],
    ['EVN','B01,','200702280700'],
    [
      'STF',
      ,
      [
        { rep: true },
        ['U2246',,,'PLW'],
        ['111223333',,,'USSSA','SS']
      ],
      ['HIPPOCRATES','HAROLD','H','JR','DR','M.D.'],
      'P',
      'M',
      '19511004',
      'A',
      [,'ICU'],
      [,'MED'],
      [
        {rep:true},
        ['(555)555-1003X345','C','O'],
        ['(555)555-3334','C','H'],
        ['(555)555-1345X789','C','B'],
      ],[
        {rep:true},
        ['1003 HEALTHCARE DRIVE','SUITE 200','ANNARBOR','MI','98199','H'],
        ['3029 HEALTHCARE DRIVE', ,'ANNARBOR','MI','98198','O']
      ],
      ['19890125',['DOCTORSAREUS MEDICAL SCHOOL','L01']],
      ,
      'PMF88123453334',
      '[email protected]',
      'B'
    ],
    [
      'PRA',
      ,
      [,'HIPPOCRATES FAMILY PRACTICE'],
      'ST',
      'I',
      ['OB/GYN','STATE BOARD OF OBSTETRICS AND GYNECOLOGY','C','19790123'],
      [
        {rep:true},
        ['1234887609','UPIN'],
        ['1234987','CTY','MECOSTA'],
        ['223987654','TAX'],
        ['1234987757','DEA'],
        ['12394433879','MDD','CA']
      ],
      [
        {rep:true},
        [['ADMIT',,'ADT'],['MED',,'L2'],'19941231'],
        [['DISCH',,'ADT'],['MED',,'L2'],'19941231']
    [
      'AFF',
      '1',
      'AMERICAN MEDICAL ASSOCIATION',
      ['123 MAIN STREET',,'OUR TOWN','CA','98765','U.S.A.','M']
      ,'19900101'
    ]
    [
      'LAN',
      '1',
      ['ESL','SPANISH','ISO639'],
      ['1','READ','HL70403'],
      ['1','EXCELLENT','HL70404']
    ]
    [
      'LAN',
      '2',
      ['ESL','SPANISH','ISO639'],
      ['2','WRITE','HL70403'],
      ['2','GOOD','HL70404']
    ]
    [
      'LAN',
      '3',
      ['FRE','FRENCH','ISO639'],
      ['3','SPEAK','HL70403'],
      ['3','FAIR','HL70404']
    ]
    [
      'EDU',
      '1',
      ['BA','BACHELOR OF ARTS','HL70360'],
      ['19810901','19850601'],
      ['YALE UNIVERSITY','L'],
      ['U','HL70402'],
      ['456 CONNECTICUT AVENUE',,'NEW HAVEN','CO','87654','U.S.A.','M']
    ]
    [
      'EDU',
      '2',
      ['MD','DOCTOR OF MEDICINE','HL70360'],
      ['19850901','19890601'],
      ['HARVARD MEDICAL SCHOOL','L'],
      ['M','HL70402'],
      ['123 MASSACHUSETTS AVENUE','CAMBRIDGE','MA','76543','U.S.A.','M'],
    ]
    [
      'ZZZ',
      'Source',
      [
        'HL7 Version 2.5.1 Standard',
        ['Chapter','15','Personnel Management'],
        ['Section','5','Example Transactions'],
        ['Page','15-40','Date','200704']
      ]
    ]
  ],
])

console.log(msg.toString())

Extracting data from a HL7 Message

import Msg from './src/'
import fs from 'fs'

const HL7 = fs.readFileSync('./sample.hl7', 'utf8')

const msg = new Msg(HL7)

console.log(
  'Name:',
  `${msg.get('STF-3.4')} ${msg.get('STF-3.2')} ${msg.get('STF-3.3')} ${msg.get(
    'STF-3.1'
  )}, ${msg.get('SFT-3.6')}`
)

The get method input takes a string which can comprised of the following:

Segment Name
Segment Repition Index
Field Index
Field Repition Index
Component Index
Sub-Component Index

Repition Indexes are optional and can be omitted. If omitted on a repeating segment/field, then an array of values will be returned.

For example to get all LAN segments you can use the get path LAN.

If you wanted just one of the segments, you would add in the repition index, for example LAN[2] would return the second LAN segment.

Repition Indexes are always syntactically wrapped in square brackets. e.g. [2]

Field, Component, and Sub-Component are optional and can be omitted. If omitted and the field/component is made up of smaller units, then an array of values will be returned.

For example to get all the components of the language codes in the 1st LAN segment you can use the get path LAN[1]-2

Field, Component, and Sub-Component are always prefixed with either a dot or a hyphen. e.g. .2 or -2

If you if there is only a single larger component, then the smaller divisions can be omitted, but if you specify the 1st smaller division, then it will return the larger component itself.

For example, EVN-1.1.1 will return the same as EVN-1.1 or EVN-1

Fields can also be repetitive and can be accessed by using the field repetition index. For example, STF-10[1] will return the 1st repetition of the 10th field in the SFT segment.

Compare how these different extracted paths compare:

import Msg from './src/'
import fs from 'fs'

const HL7 = fs.readFileSync('./sample.hl7', 'utf8')

const msg = new Msg(HL7)

console.log('STF-10[1].1:', msg.get('STF-10[1].1'))
console.log('STF[1]-10[1]:', msg.get('STF[1]-10[1]'))
console.log('STF-10[1]:', msg.get('STF-10[1]'))
console.log('STF-10.1:', msg.get('STF-10.1'))
console.log('STF.10.1:', msg.get('STF.10.1'))
console.log('LAN:', msg.get('LAN'))
console.log('LAN-2.1:', msg.get('LAN-2.1'))
console.log('LAN[1]-2.1:', msg.get('LAN[1]-2.1'))
console.log('LAN-2:', msg.get('LAN-2'))
console.log('ZZZ-2.2', msg.get('ZZZ-2.2'))
console.log('ZZZ-2.2.1', msg.get('ZZZ-2.2.1'))

Unless a path is fully defined including all repetition indexes, then the type returned could be an array or a string.

Transforming an HL7 Message

The Msg class has built methods for transforming the message. This package currently supports transformation scenarios:

Restricting the Message down to only a subset Segments, Fields, Components, and SubComponents using object notation. (msg.transform({ restrict: { ... } }))
Removing specified Segments, Fields, Components, and SubComponents using object notation. (msg.transform({ remove: { ... } }))
Adding new Segment strings. (msg.addSegment(...))
Setting HL7 path with encoded string. (msg.set('LAN-2', 'ENG^ENGLISH^ISO639'))
Setting HL7 path with decoded JSON. (msg.setJSON('LAN-4', ['3', 'FAIR', 'HL70404']))
Copy from HL7 path to a new HL7 path. (msg.copy('ZZZ-1', 'ZZZ-3'))
Delete value at HL7 path. (msg.delete('ZZZ-2'))
Move from HL7 path to a new HL7 path. Sets origin to undefined. (msg.move('ZZZ-3', 'ZZZ-4'))
Dictionary Map an HL7 path using a key-value object. (msg.map('LAN-2.2', { ENGLISH: 'English' }))
Integer Map an HL7 path using an array. Array is treated as 1-based indexed. (msg.map('LAN-4.1', ['Excellent', 'Fair', 'Poor']))
Function Map an HL7 path using a custom defined function that receives the original value and returns the new value. (msg.map('ZZZ-1', (orig) => orig.toUpperCase()))
Iteration Map an iterated HL7 path using an array. (msg.setIteration('LAN-1', ['A', 'B', 'C']))
Iteration Map an iterated HL7 path using an custom defined function that received the original value, and the iteration key and returns the new value. Useful for renumbering segments. (msg.setIteration('LAN-1', (_v, i) => i.toString()))

The Transformer functions return the class itself allowing for the transformers to be chained in sequence. (msg.addSegment('ZZZ||').set('ZZZ.1', '1').copy('ZZZ.1', 'ZZZ.2'))

For the gofer Engine, a channel's config accepts a transformer function that receives the Msg class, and should return the transformed class. Example:

import Msg from './src/'

export const MyTransformer = (msg: Msg): Msg =>
  msg
    .transform({
      restrict: {
        MSH: () => true, // if function equates to true, keep whole segment
        LAN: 3, // an integer keeps only the nth iteration of the segment (LAN[3])
        ZZZ: { // an object keeps only certain fields of the segment
          1: true, // true keeps the entire field as is (ZZZ-1)
          2: [1, 5] // an array keeps only certain components of the field (ZZZ-2.1, ZZZ-2.5)
        },
        STF: {
          2: [1, 4],
          3: [], // an empty array keeps no components, same as if key was undefined
          4: [2],
          5: true,
          10: 1, // an integer keeps only the nth repeition of the field
          11: (f) => f?.[5] === 'O' // f is 0-indexed. This is keeping only the repetition that has STF-11.6 === 'O'
        },
        EDU: true, // if true, keep whole segment as is
        // Any segments not specifically listed in a `restrict` object are removed.
      },
      remove: {
        LAN: 2,
        EDU: {
          1: true, // deletes EDU-1
          2: [3], // deletes EDU-2.3
          3: (f) => {
            if (Array.isArray(f) && typeof f[0] === 'string')
              return f[0] > '19820000'
            return false
          }, // A function deletes when returns true. This is deleting EDU-3 when EDU-3.1 is greater than the year 1982
          4: 2 // deletes EDU-4[2]
        }
      }
    })
    .addSegment('ZZZ|Engine|gofer')
    .copy('ZZZ-2', 'MSH-3')
    .set('ZZZ-1', 'Developer')
    .set('ZZZ-2', 'amaster507')
    .delete('LAN')
    .addSegment('LAN|1|ESL^SPANISH^ISO639|1^READ^HL70403~1^EXCELLENT^HL70404|')
    .addSegment('LAN|1|ESL^SPANISH^ISO639|2^WRITE^HL70403~2^GOOD^HL70404|')
    .addSegment('LAN|1|FRE^FRENCH^ISO639|3^SPEAK^HL70403~3^FAIR^HL70404|')
    .setIteration<string>('LAN-1', (_v, i) => i.toString())
    .move('LAN[1]-3[2]', 'LAN[1]-4')
    .move('LAN[2]-3[2]', 'LAN[2]-4')
    .move('LAN[3]-3[2]', 'LAN[3]-4')
    .map('LAN-4.2', {
      EXCELLENT: 'BEST',
      GOOD: 'BETTER',
      FAIR: 'GOOD',
    })

Name		Name	Last commit message	Last commit date
Latest commit History 30 Commits
.vscode		.vscode
config		config
img		img
src		src
tests		tests
tools		tools
.editorconfig		.editorconfig
.eslintignore		.eslintignore
.eslintrc.js		.eslintrc.js
.gitignore		.gitignore
.npmignore		.npmignore
.prettierrc.js		.prettierrc.js
README.md		README.md
hl7-json.code-workspace		hl7-json.code-workspace
jest.config.ts		jest.config.ts
package-lock.json		package-lock.json
package.json		package.json
sample.hl7		sample.hl7
sample.json		sample.json
sample2.hl7		sample2.hl7
tsconfig.json		tsconfig.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

TypeScript HL7 Client (and future HL7/FHIR Interface Engine)

Decoding a HL7 Message will return a JSON object

Encoding a HL7 Message JSON object will return a HL7 string

Extracting data from a HL7 Message

Transforming an HL7 Message

Roadmap

About

Releases

Packages

Languages

amaster507/ts-hl7

Folders and files

Latest commit

History

Repository files navigation

TypeScript HL7 Client (and future HL7/FHIR Interface Engine)

Decoding a HL7 Message will return a JSON object

Encoding a HL7 Message JSON object will return a HL7 string

Extracting data from a HL7 Message

Transforming an HL7 Message

Roadmap

About

Resources

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages