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

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/amazon-ion/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.