fhir.js

JavaScript client for FHIR

Goals:

• Support FHIR CRUD operations
• Friendly and expressive query syntax
• Support for adapters that provide idiomatic interfaces in angular, jQuery, extjs, etc
• Support for access control (HTTP basic, OAuth2)
• ...

Development

Node.js is required for build.

We recommend installling Node.js using nvm

Build & test:

git clone https://github.com/FHIR/fhir.js
cd fhir.js
npm install
`npm bin`/bower install

# buld fhir.js
`npm bin`/grunt

# run all tests
node_modules/karma/bin/karma start --single-run

# watch tests while development
node_modules/karma/bin/karma start

# run integration tests
`npm bin`/bower install
node_modules/karma/bin/karma start karma-itegration.conf.js --single-run

API

Create instance of the FHIR client

To communicate with concrete FHIR server, you can create instance of the FHIR client, passing a configuration object & adapter object. Adapters are implemented for concrete frameworks/libs (see below).

var cfg = {
  // FHIR server base url
  baseUrl: 'http://myfhirserver.com',
  auth: {
     bearer: 'tocken',
     // OR for basic auth
     user: 'user',
     pass: 'secret'
  }
}

myClient = fhir(cfg, adapter)

Adapter implementation

Currently each adapter must implement an http(requestObj) function:

Structure of requestObj:

• method - http method (GET|POST|PUT|DELETE)
• url - url for request
• headers - object with headers (i.e. {'Category': 'term; scheme="sch"; label="lbl"'}
• success - success callback, which should be called with (data, status, headersFn, config)
  • data - parsed body of responce
  • status - responce HTTP status
  • headerFn - function to get header, i.e. headerFn('Content')
  • config - initial requestObj passed to http
• error - error callback, which should be called with (data, status, headerFn, config)

Here are implementations for:

• AngularJS adapter
• jQuery adapter
• Node adapter

Conformance & Profiles

Resource's CRUD

To create a FHIR resource, call myClient.create(entry, callback, errback), passing an object that contains the following propperties:

• content (required) - resource in FHIR json
• tags (opttional) - list of categories (see below)

In case of success,the callback function will be invoked with an object that contains the following attributes:

• id - url of created resource
• content - resource json
• category - list of tags

var entry = {
  category: [{term: 'TAG term', schema: 'TAG schema', label: 'TAG label'}, ...]
  content: {
    resourceType: 'Patient',
    //...
  }
}

myClient.create(entry,
 function(entry){
    console.log(entry.id)
 },
 function(error){
   console.error(error)
 }
)

Tags Operations

Search

fhir.search('Patient', queryObject, callback, errback) function is used for FHIR resource's search.

If success callback will be called with resulting bundle.

For queryObject syntax fhir.js adopts mongodb-like query syntax (see):

{name: 'maud'}
//=> name=maud

{name: {$exact: 'maud'}}
//=> name:exact=maud

{name: {$or: ['maud','dave']}}
//=> name=maud,dave

{name: {$and: ['maud',{$exact: 'dave'}]}}
//=> name=maud&name:exact=Dave

{birthDate: {$gt: '1970', $lte: '1980'}}
//=> birthDate=>1970&birthDate=<=1980

{subject: {$type: 'Patient', name: 'maud', birthDate: {$gt: '1970'}}}
//=> subject:Patient.name=maud&subject:Patient.birthDate=>1970

{'subject.name': {$exact: 'maud'}}
//=> subject.name:exact=maud

For more information see tests

AngularJS adapter: ng-fhir

AngularJS adapter after grunt build can be found at dist/ngFhir.js

Usage:

angular.module('app', ['ng-fhir'])
  # configure base url
  .config ($fhirProvider)->
     $fhirProvider.baseUrl = 'http://try-fhirplace.hospital-systems.com'
  .controller 'mainCtrl', ($scope, $fhir)->
     $fhir.search('Patient', {name: {$exact: 'Maud'}})
       .error (error)->
         $scope.error = error
       .success (bundle)->
         $scope.patients = bundle.entry

jQuery adapter: jqFhir

jQuery build can be found at dist/jqFhir.js

Usage:

<script src="./jquery-???.min.js"> </script>
<script src="./jqFhir.js"> </script>

// create fhir instance
var fhir = jqFhir({
    baseUrl: 'https://ci-api.fhir.me',
    auth: {user: 'client', pass: 'secret'}
})

fhir.search('Patient', {name: 'maud'})
.then(function(bundle){
  console.log('Search patients', bundle)
})

Node.js adapter: npm install fhir.ns

Via NPM you can npm install fhir.js. (If you want to work on the source code, you can compile coffee to js via npm install, and use ./lib/adapters/node as an entrypoint.)

var mkFhir = require('fhir.js');

var client = mkFhir({
  baseUrl: 'http://try-fhirplace.hospital-systems.com'
});

client.search( 'Patient', { 'birthdate': '1974' }, function(err, bundle) {
  var count = (bundle.entry && bundle.entry.length) || 0;
  console.log("# Patients born in 1974: ", count); 
});

TODO

• npm package
• bower package

Contribute

Join us by github issues or pull-requests