qpc-database / ion-hash-js

A JavaScript implementation of Amazon Ion Hash.

Amazon Ion Hash JavaScript

An implementation of Amazon Ion Hash in JavaScript.

Getting Started

This library is designed to work with Node 8/ES5/CommonJS.

Node

1. Add dependencies for ion-hash-js and its peerDependencies:

   npm install --save ion-hash-js ion-js jsbi
   

2. Note the examples below assume the availability of the following utility method:

   function toHexString(byteArray) {
       let sb = '';
       byteArray.forEach(b => {
           if (sb != '') { sb += ' ' }
           sb += ('0' + (b & 0xFF).toString(16)).slice(-2);
       });
       return sb;
   }

3. Use the library to generate the Ion hash of any value:

   let ionHash = require('ion-hash-js');
   
   let digest = ionHash.digest([1, 2, 3], 'md5');
   console.log('digest: ' + toHexString(digest));

   produces:

   digest: 8f 3b f4 b1 93 5c f4 69 c9 c1 0c 31 52 4b 26 25

4. Use cases for which a more efficient API is preferable should consider using the low-level HashReader API to generate an Ion hash:

   let ion = require('ion-js');
   let ionHash = require('ion-hash-js');
   
   let ionStr = '[1, 2, 3]';
   let hashReader = ionHash.makeHashReader(
       ion.makeReader(ionStr),
       ionHash.cryptoHasherProvider('md5'));
   hashReader.next();
   hashReader.next();
   
   let digest = hashReader.digest();
   console.log('digest: ' + toHexString(digest));

   produces:

   digest: 8f 3b f4 b1 93 5c f4 69 c9 c1 0c 31 52 4b 26 25

5. A low-level HashWriter API may be used to generate an Ion hash while writing Ion data:

   let ion = require('ion-js');
   let ionHash = require('ion-hash-js');
   
   let hashWriter = ionHash.makeHashWriter(
       ion.makeTextWriter(),
       ionHash.cryptoHasherProvider('md5'));
   hashWriter.stepIn(ion.IonTypes.LIST);
   hashWriter.writeInt(1);
   hashWriter.writeInt(2);
   hashWriter.writeInt(3);
   hashWriter.stepOut();
   
   let digest = hashWriter.digest();
   console.log('digest: ' + toHexString(digest));

   produces:

   digest: 8f 3b f4 b1 93 5c f4 69 c9 c1 0c 31 52 4b 26 25

Development

This repository contains a git submodule called ion-hash-test, which holds test data used by ion-hash-js's unit tests.

The easiest way to clone the ion-hash-js repository and initialize its ion-hash-test submodule is to run the following command:

$ git clone --recursive https://github.com/amzn/ion-hash-js.git ion-hash-js

Alternatively, the submodule may be initialized independently from the clone by running the following commands:

$ git submodule init
$ git submodule update

Known Issues

Any tests commented out in tests/ion_hash_tests.ion are not expected to work at this time.

License

This library is licensed under the Apache 2.0 License.