hoek

What is hoek?

The hoek package is a utility library that offers a variety of functions for object manipulation, array manipulation, type checking, and encoding. It is designed to provide developers with tools to simplify common tasks in JavaScript programming.

What are hoek's main functionalities?

Object cloning

This feature allows for deep cloning of objects, ensuring that nested objects are cloned properly rather than just copying references.

const hoek = require('hoek');
const obj = { a: 1 };
const clone = hoek.clone(obj);

Merge objects

Merge two objects into one, where the second object's properties are added to the first object. This is useful for combining configurations or settings.

const hoek = require('hoek');
const target = { a: 1 };
const source = { b: 2 };
hoek.merge(target, source);

Assert

Provides a simple assertion utility to validate conditions. If the condition is false, it throws an error with the provided message.

const hoek = require('hoek');
hoek.assert(1 === 1, 'This will not throw');
hoek.assert(1 === 2, 'This will throw an error');

Reach

Allows for safely reaching into an object for a nested property. This helps in avoiding errors when accessing deeply nested properties.

const hoek = require('hoek');
const obj = { a: { b: { c: 1 } } };
const value = hoek.reach(obj, 'a.b.c');

Other packages similar to hoek

lodash

Lodash is a comprehensive utility library offering a wide range of functions for tasks including object manipulation, array manipulation, string manipulation, and more. It is more extensive than hoek but can be bulkier due to its size.

underscore

Underscore is another utility library similar to lodash but with a smaller footprint. It provides many of the same functionalities as hoek but lacks some of the more specialized functions found in hoek.

ramda

Ramda focuses on functional programming, offering utilities that make it easier to apply functional paradigms in JavaScript. It provides similar functionalities for object and array manipulation but from a functional programming perspective, which is different from hoek's more general utility approach.

README

General purpose node utilities

Table of Contents

• Introduction
• Object
  • clone
  • merge
  • applyToDefaults
  • unique
  • mapToObject
  • intersect
  • matchKeys
  • flatten
  • removeKeys
  • reach
  • inheritAsync
  • rename
• Timer
• Bench
• Binary Encoding/Decoding
  • base64urlEncode
  • base64urlDecode
• Escaping Characters
  • escapeHtml
  • escapeHeaderAttribute
  • escapeRegex
• Errors
  • assert
  • abort
  • displayStack
  • callStack
  • toss
• Load files
  • loadPackage
  • loadDirModules
• Streams
  • readStream

Introduction

The Hoek general purpose node utilities library is used to aid in a variety of manners. It comes with useful methods for Arrays (clone, merge, applyToDefaults), Objects (removeKeys, copy), Asserting and more.

For example, to use Hoek to set configuration with default options:

var Hoek = require('hoek');

var default = {url : "www.github.com", port : "8000", debug : true}

var config = Hoek.applyToDefaults(default, {port : "3000", admin : true});

// In this case, config would be { url: 'www.github.com', port: '3000', debug: true, admin: true }

Under each of the sections (such as Array), there are subsections which correspond to Hoek methods. Each subsection will explain how to use the corresponding method. In each js excerpt below, the var Hoek = require('hoek') is omitted for brevity.

Object

Hoek provides several helpful methods for objects and arrays.

clone(obj)

This method is used to clone an object or an array. A deep copy is made (duplicates everything, including values that are objects).

var nestedObj = {
        w: /^something$/ig,
        x: {
            a: [1, 2, 3],
            b: 123456,
            c: new Date()
        },
        y: 'y',
        z: new Date()
    };

var copy = Hoek.clone(nestedObj);

copy.x.b = 100;

console.log(copy.y)        // results in 'y'
console.log(nestedObj.x.b) // results in 123456
console.log(copy.x.b)      // results in 100

merge(target, source, isNullOverride, isMergeArrays)

isNullOverride, isMergeArrays default to true

Merge all the properties of source into target, source wins in conflic, and by default null and undefined from source are applied

var target = {a: 1, b : 2}
var source = {a: 0, c: 5}
var source2 = {a: null, c: 5}

var targetArray = [1, 2, 3];
var sourceArray = [4, 5];

var newTarget = Hoek.merge(target, source);     // results in {a: 0, b: 2, c: 5}
newTarget = Hoek.merge(target, source2);        // results in {a: null, b: 2, c: 5}
newTarget = Hoek.merge(target, source2, false); // results in {a: 1, b: 2, c: 5}

newTarget = Hoek.merge(targetArray, sourceArray)              // results in [1, 2, 3, 4, 5]
newTarget = Hoek.merge(targetArray, sourceArray, true, false) // results in [4, 5]

applyToDefaults(defaults, options)

Apply options to a copy of the defaults

var defaults = {host: "localhost", port: 8000};
var options = {port: 8080};

var config = Hoek.applyToDefaults(defaults, options); // results in {host: "localhost", port: 8080};

unique(array, key)

Remove duplicate items from Array

var array = [1, 2, 2, 3, 3, 4, 5, 6];

var newArray = Hoek.unique(array); // results in [1,2,3,4,5,6];

array = [{id: 1}, {id: 1}, {id: 2}];

newArray = Hoek.unique(array, "id") // results in [{id: 1}, {id: 2}]

mapToObject(array, key)

Convert an Array into an Object

var array = [1,2,3];
var newObject = Hoek.mapToObject(array); // results in [{"1": true}, {"2": true}, {"3": true}]

array = [{id: 1}, {id: 2}];
newObject = Hoek.mapToObject(array, "id") // results in [{"id": 1}, {"id": 2}]

intersect(array1, array2)

Find the common unique items in two arrays

var array1 = [1, 2, 3];
var array2 = [1, 4, 5];

var newArray = Hoek.intersect(array1, array2) // results in [1]

matchKeys(obj, keys)

Find which keys are present

var obj = {a: 1, b: 2, c: 3};
var keys = ["a", "e"];

Hoek.matchKeys(obj, keys) // returns ["a"]

flatten(array, target)

Flatten an array

var array = [1, 2, 3];
var target = [4, 5];

var flattenedArray = Hoek.flatten(array, target) // results in [4, 5, 1, 2, 3];

removeKeys(object, keys)

Remove keys

var object = {a: 1, b: 2, c: 3, d: 4};

var keys = ["a", "b"];

Hoek.removeKeys(object, keys) // object is now {c: 3, d: 4}

reach(obj, chain)

Converts an object key chain string to reference

var chain = 'a.b.c';
var obj = {a : {b : { c : 1}}};

Hoek.reach(obj, chain) // returns 1

inheritAsync(self, obj, keys)

Inherits a selected set of methods from an object, wrapping functions in asynchronous syntax and catching errors

var targetFunc = function () { };

var proto = {
                a: function () {
                    return 'a!';
                },
                b: function () {
                    return 'b!';
                },
                c: function () {
                    throw new Error('c!');
                }
            };

var keys = ['a', 'c'];

Hoek.inheritAsync(targetFunc, proto, ['a', 'c']);

var target = new targetFunc();

target.a(function(err, result){console.log(result)}  // returns 'a!'

target.c(function(err, result){console.log(result)}  // returns undefined

target.b(function(err, result){console.log(result)}  // gives error: Object [object Object] has no method 'b'

rename(obj, from, to)

Rename a key of an object

var obj = {a : 1, b : 2};

Hoek.rename(obj, "a", "c");     // obj is now {c : 1, b : 2}

Timer

A Timer object. Initializing a new timer object sets the ts to the number of milliseconds elapsed since 1 January 1970 00:00:00 UTC.

var timerObj = new Hoek.Timer();
console.log("Time is now: " + timerObj.ts)
console.log("Elapsed time from initialization: " + timerObj.elapsed() + 'milliseconds')

Bench

Same as Timer with the exception that ts stores the internal node clock which is not related to Date.now() and cannot be used to display human-readable timestamps. More accurate for benchmarking or internal timers.

Binary Encoding/Decoding

base64urlEncode(value)

Encodes value in Base64 or URL encoding

base64urlDecode(value)

Decodes data in Base64 or URL encoding.

Escaping Characters

Hoek provides convenient methods for escaping html characters. The escaped characters are as followed:

internals.htmlEscaped = {
    '&': '&',
    '<': '&lt;',
    '>': '&gt;',
    '"': '&quot;',
    "'": '&#x27;',
    '`': '&#x60;'
};

escapeHtml(string)

var string = '<html> hey </html>';
var escapedString = Hoek.escapeHtml(string); // returns &lt;html&gt; hey &lt;/html&gt;

escapeHeaderAttribute(attribute)

Escape attribute value for use in HTTP header

var a = Hoek.escapeHeaderAttribute('I said "go w\\o me"');  //returns I said \"go w\\o me\"

escapeRegex(string)

Escape string for Regex construction

var a = Hoek.escapeRegex('4^f$s.4*5+-_?%=#!:@|~\\/`"(>)[<]d{}s,');  // returns 4\^f\$s\.4\*5\+\-_\?%\=#\!\:@\|~\\\/`"\(>\)\[<\]d\{\}s\,

Errors

assert(message)

var a = 1, b =2;

Hoek.assert(a === b, 'a should equal b');  // ABORT: a should equal b

abort(message)

First checks if process.env.NODE_ENV === 'test', and if so, throws error message. Otherwise, displays most recent stack and then exits process.

displayStack(slice)

Displays the trace stack

var stack = Hoek.displayStack();
console.log(stack) // returns something like:

[ 'null (/Users/user/Desktop/hoek/test.js:4:18)',
  'Module._compile (module.js:449:26)',
  'Module._extensions..js (module.js:467:10)',
  'Module.load (module.js:356:32)',
  'Module._load (module.js:312:12)',
  'Module.runMain (module.js:492:10)',
  'startup.processNextTick.process._tickCallback (node.js:244:9)' ]

callStack(slice)

Returns a trace stack array.

var stack = Hoek.callStack();
console.log(stack)  // returns something like:

[ [ '/Users/user/Desktop/hoek/test.js', 4, 18, null, false ],
  [ 'module.js', 449, 26, 'Module._compile', false ],
  [ 'module.js', 467, 10, 'Module._extensions..js', false ],
  [ 'module.js', 356, 32, 'Module.load', false ],
  [ 'module.js', 312, 12, 'Module._load', false ],
  [ 'module.js', 492, 10, 'Module.runMain', false ],
  [ 'node.js',
    244,
    9,
    'startup.processNextTick.process._tickCallback',
    false ] ]

toss(condition)

toss(condition /*, [message], callback */)

Return an error as first argument of a callback

Load Files

loadPackage(dir)

Load and parse package.json process root or given directory

var pack = Hoek.loadPackage();  // pack.name === 'hoek'

loadDirModules(path, excludeFiles, target)

Loads modules from a given path; option to exclude files (array).

Streams

readStream

Read an entire stream buffer into a string

readStream(inputStream, function (outputString) {
    ...
});