hookney

Hookney

Hookney is a helper around self-referencing JSON objects for Node.js and the Browser. Hookney supports reading from and writing to files. JSON files may contain comments. This makes Hookney ideal for handling configuration files.

Getting started

Node.js

Install hookney using npm.

npm install hookney --save

Then require it into any module.

const Hookney = require('hookney');

Browser

Hookney has a single dependency to lodash, which must be loaded before using Hookney.

You can download the latest release from the repository

• hookney.js unminified, including comments
• hookney.min.js minified version

Load lodash from a CDN or any other source.

<script src="https://cdn.jsdelivr.net/npm/lodash@4.17.5/lodash.min.js"></script>

<!-- Alternative CDN -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/lodash.js/4.17.5/lodash.min.js"></script>

<!-- Load from local node module -->
<script src="node_modules/lodash/lodash.min.js"></script>

Use a script tag to directly add Hookney to the global scope.

<script src="hookney.min.js"></script>

Usage

const json = {
  custom: {
    tableName: 'users-table-${self:provider.stage}'
  },

  provider: {
    stage: 'dev'
  },

  environment: {
    USERS_TABLE: '${self:custom.tableName}'
  },

  configOptions: [
    {
      // Scenario 'high'
      limit: '1mb',
      strict: true,
      extended: true
    },
    {
      // Scenario 'mid'
      limit: '500kb',
      strict: true,
      extended: false
    },
    {
      // Scenario 'low'
      limit: '10kb',
      strict: false,
      extended: false
    }
  ],

  config: '${self:configOptions[1]}'
};

const config = new Hookney(json).resolveReferences().json();

// => result:
config === {
  custom: {
    tableName: 'users-table-dev'
  },

  provider: {
    stage: 'dev'
  },

  environment: {
    USERS_TABLE: 'users-table-dev'
  },

  configOptions: [
    {
      limit: '1mb',
      strict: true,
      extended: true
    },
    {
      limit: '500kb',
      strict: true,
      extended: false
    },
    {
      limit: '10kb',
      strict: false,
      extended: false
    }
  ],

  config: {
    limit: '500kb',
    strict: true,
    extended: false
  }  
}

Examples

Use given JSON object and resolve references.

const json = { a: 1, b: "str", c: '${self:a}' };

const config = Hookney.from(json).resolveReferences().json();

// is equivalent to:

const config = new Hookney(json).resolveReferences().json();

// => config === { a: 1, b: "str", c: 1 }

// Given JSON object is not touched, instead a deep clone is created.
// => json === { a: 1, b: "str", c: '${self:a}' }

Create JSON object from text and resolve references. Text may contain comments.

const text = '{ "a": 1, "b": "str", "c": "${self:a}" }';

const config = Hookney.fromString(text).resolveReferences().json();

// => config === { a: 1, b: "str", c: 1 }

Load JSON object from file and resolve references. JSON file may contain comments.

// Synchronous
const config = Hookney.fromFileSync("/path/to/file.json").resolveReferences().json();

// Asynchronous
Hookney.fromFile("/path/to/file.json", function(err, hookney)
{
  if (err)
  {
    // Handle error.
    return;
  }

  const config = hookney.resolveReferences().json();
});

Hookney.fromFile() and Hookney.fromFileSync() support an optional 'options' parameter.

const options = {
  encoding: 'utf8', // Default encoding
  flag: 'r',        // Default flag

  reviver: null     // Default is no reviver
};

hookney.fromFileSync("/path/to/file.json", options);

Hookney.fromFile("/path/to/file.json", options, function(err, hookney)
{
});

For details on the 'options' parameter, please refer to the Node.js documentation.

In addition to the options described there, 1 additional parameter 'reviver' is supported. Please refer to the JSON.parse() documentation for details.

Hookney.fromFile() and Hookney.fromFileSync() are not available in the browser.

Write JSON object to file.

const hookney = new Hookney({ a: 1, b: "str", c: true });

// Synchronous
hookney.writeFileSync("/path/to/file.json");

// Asynchronous
Hookney.writeFile("/path/to/file.json", function(err)
{
  if (err)
  {
    // Handle error.
  }
});

writeFile() and writeFileSync() support an optional 'options' parameter.

const options = {
  encoding: 'utf8', // Default encoding
  mode: 0o666,      // Default mode
  flag: 'w'         // Default flag

  replacer: null,   // Default is no replacer
  space: null       // Default is no space
};

hookney.writeFileSync("/path/to/file.json", options);

Hookney.writeFile("/path/to/file.json", options, function(err)
{
});

For details on the 'options' parameter, please refer to the Node.js documentation.

In addition to the options described there, 2 additional parameters 'replacer' and 'space' are supported. Please refer to the JSON.stringify() documentation for details.

writeFile() and writeFileSync() are not available in the browser.

More examples

Please refer to the test spec for more examples.

Testing

We are using Jasmine testing framework and Istanbul test coverage framework.

• Clone or download the repository.
• Change into project directory.
• Use npm install to install all development dependencies.
• Use npm test to run the tests.
• The output should display successful execution results and a code coverage map.

Build

• Clone or download the repository.
• Change into project directory.
• Use grunt in project directory to build hookney.min.js from hookney.js.

Contribution

Please use Github issues for requests.

Pull requests are welcome.

Issues

We use GitHub issues to track bugs. Please ensure your bug description is clear and has sufficient instructions to be able to reproduce the issue.

The absolute best way to report a bug is to submit a pull request including a new failing test which describes the bug. When the bug is fixed, your pull request can then be merged.

The next best way to report a bug is to provide a reduced test case on jsFiddle or jsBin or produce exact code inline in the issue which will reproduce the bug.

Support

• Send us an email: [e-mail]
• Follow us on Twitter: @belexos

Changelog

v1.0.0

• Initial public release

License

Copyright (c) 2016-present, Belexos GmbH. Hookney is licensed under the MIT License.