@hapi/hoek

@hapi/hoek is a collection of utility methods designed for the hapi ecosystem. While it is optimized to work seamlessly with the hapi web framework and its components, it is a standalone module that can be used with any web framework or in general-purpose Node.js applications.

Note: If you are looking for a broad, general-purpose utility library, @lodash is recommended. @hapi/hoek is specifically curated as a central repository for methods used within the hapi ecosystem.

The behavior of contain(ref, values, options) depends on the type of ref:

Strings

Checks if the substrings in values exist within the ref string.

• If options.only is true, the string must consist solely of the provided substrings.
• Empty strings are handled specially: '' contains ''.

Arrays

Checks if the items in values are present in the ref array.

• If options.only is true, the ref array length must match the values array length.
• If options.once is true, each value can only be matched once.

Objects

• Array of keys: If values is an array, contain checks if the ref object contains all those keys.
• Key-Value pairs: If values is an object, contain checks if ref contains the same keys with matching values.
• Constraint: The once option cannot be used when ref is an object.

By default, reach() treats Set and Map objects as standard objects and will not traverse their internal entries. To traverse them, you must enable the iterables option.

• For Set: The path segment must be a number (or a numeric string) representing the index in the Set.
• For Map: The path segment is used as the key for the .get() method.

Note: If iterables is false (the default), reach() will return undefined when attempting to traverse a Set or Map via keys.

import { reach } from '@hapi/hoek';

const mySet = new Set(['apple', 'banana']);
const myMap = new Map([['key1', 'value1']]);

// Traversing a Set (requires iterables: true)
const setVal = reach({ s: mySet }, 's.1', { iterables: true }); // 'banana'

// Traversing a Map (requires iterables: true)
const mapVal = reach({ m: myMap }, 'm.key1', { iterables: true }); // 'value1'

The intersect() function can operate on any type that satisfies the IntersectArray<T> definition. This includes:

• Array<T>
• Set<T>
• Record<number, T>
• null (treated as an empty collection)

Use Hoek.intersect(array1, array2, [options]) to find the common unique items between two arrays.

Options:

• first: (boolean) If true, returns only the first intersecting item. Defaults to false.

const array1 = [1, 2, 3];
const array2 = [1, 4, 5];
const newArray = Hoek.intersect(array1, array2); // results in [1]

Use Hoek.reachTemplate(obj, template, [options]) to replace string parameters in the format {name} with their corresponding values from obj using the reach() method.

Parameters:

• obj: The context object used for key lookup.
• template: A string containing {} parameters.
• options: Accepts the same options as Hoek.reach().

const template = '1+{a.b.c}=2';
const obj = { a: { b: { c: 1 } } };
Hoek.reachTemplate(obj, template); // returns '1+1=2'

Use Hoek.stringify(...args) to convert an object to a string using JSON.stringify(). Unlike the standard method, Hoek.stringify catches errors (like circular references) and returns them as a string instead of throwing. This is useful for logging or displaying info in error messages.

const a = {};
a.b = a;
Hoek.stringify(a); // Returns '[Cannot display object: Converting circular structure to JSON]'

Use Hoek.escapeHeaderAttribute(attribute) to escape attribute values for safe use in HTTP headers.

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

Use Hoek.clone(obj, [options]) to create a deep copy of an object or an array. This method duplicates everything, including values that are objects and non-enumerable properties.

Options:

• symbols: (boolean) Whether to clone symbol properties. Defaults to true.
• shallow: (array of strings | boolean)
  • An array of dot-separated or array-based key paths to shallow copy from obj instead of deep.
  • true to shallow copy all object properties (useful for objects with non-enumerable properties and prototypes).

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

// Deep clone
const copy = Hoek.clone(nestedObj);

// Shallow clone specific keys
const shallowCopy = Hoek.clone(nestedObj, { shallow: ['x'] });