### Hoek ApplyToDefaults

Source: https://github.com/hapijs/hoek/blob/master/API.md

Applies source properties to a copy of the defaults object. Options include nullOverride (defaults to false) and shallow copying specific paths. This operation is non-destructive to the defaults.

```javascript
const Hoek = require('hoek');

const defaults = { host: "localhost", port: 8000 };
const source = { port: 8080 };

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

```javascript
const Hoek = require('hoek');

const defaults = { host: "localhost", port: 8000 };
const source = { host: null, port: 8080 };

const config = Hoek.applyToDefaults(defaults, source, { nullOverride: true });
// results in { host: null, port: 8080 }
```

```javascript
const Hoek = require('hoek');

const defaults = {
    db: {
        server: {
            host: "localhost",
            port: 8000
        },
        name: 'example'
    }
};

const source = { db: { server: { port: 8080 } } };

const config = Hoek.applyToDefaults(defaults, source, { shallow: ['db.server'] });
// results in { db: { server: { port: 8080 }, name: 'example' } }

const config2 = Hoek.applyToDefaults(defaults, source, { shallow: [['db', 'server']] });
// results in { db: { server: { port: 8080 }, name: 'example' } }
```

--------------------------------

### once: Create a function that runs only once

Source: https://github.com/hapijs/hoek/blob/master/API.md

Returns a new function that, when called multiple times, ensures the original function `fn` is executed only on the first invocation. Subsequent calls will return the result of the first call or undefined if no value was returned.

```javascript
const myFn = function () {
    console.log('Ran myFn');
};

const onceFn = Hoek.once(myFn);
onceFn(); // results in "Ran myFn"
onceFn(); // results in undefined
```

--------------------------------

### Hoek Clone Object/Array

Source: https://github.com/hapijs/hoek/blob/master/API.md

Clones an object or array, performing a deep copy by default. Supports cloning symbol properties and shallow copying specific paths or all properties via options.

```javascript
const Hoek = require('hoek');

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

const 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
```

```javascript
const Hoek = require('hoek');

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

const copy = Hoek.clone(nestedObj, { shallow: ['x'] });

copy.x.b = 100;

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

--------------------------------

### deepEqual: Deep comparison utility in JavaScript

Source: https://github.com/hapijs/hoek/blob/master/API.md

Performs a deep comparison of two values, supporting circular dependencies, prototypes, and enumerable properties. It offers options to control function comparison, partial matching, prototype skipping, key skipping, and symbol property handling.

```APIDOC
deepEqual(a, b, [options])
  Performs a deep comparison of two values.
  - a: The first value to compare.
  - b: The second value to compare.
  - options: Optional settings object.
    - deepFunction (boolean): When true, function values are deep compared using their source code and object properties. Defaults to false.
    - part (boolean): When true, allows a partial match where some of `b` is present in `a`. Defaults to false.
    - prototype (boolean): When false, prototype comparisons are skipped. Defaults to true.
    - skip (string[]): An array of key name strings to skip comparing. The keys can be found in any level of the object. Note that both values must contain the key - only the value comparison is skipped. Only applies to plain objects and deep functions. Defaults to no skipping.
    - symbols (boolean): When false, symbol properties are ignored. Defaults to true.

  Returns: boolean - True if the values are deeply equal, false otherwise.

  Examples:
  Hoek.deepEqual({ a: [1, 2], b: 'string', c: { d: true } }, { a: [1, 2], b: 'string', c: { d: true } }); // results in true
  Hoek.deepEqual(Object.create(null), {}, { prototype: false }); // results in true
  Hoek.deepEqual(Object.create(null), {}); // results in false
```

--------------------------------

### reachTemplate: Replace template string parameters

Source: https://github.com/hapijs/hoek/blob/master/API.md

Replaces string parameters in a template with corresponding object values using the reach() method. It takes an object for context, a template string with parameters like {name}, and optional reach() options. The function resolves nested properties within the template.

```javascript
const template = '1+{a.b.c}=2';
const obj = { a: { b: { c: 1 } } };

Hoek.reachTemplate(obj, template); // returns '1+1=2'
```

--------------------------------

### wait: Resolve a promise after a delay

Source: https://github.com/hapijs/hoek/blob/master/API.md

Creates a promise that resolves after a specified timeout period in milliseconds. It can optionally resolve with a specific return value. This is useful for simulating delays or coordinating asynchronous operations.

```javascript
await Hoek.wait(2000); // waits for 2 seconds
const timeout = Hoek.wait(1000, 'timeout'); // resolves after 1s with 'timeout'
```

--------------------------------

### assert: Assert a condition and throw an error

Source: https://github.com/hapijs/hoek/blob/master/API.md

Asserts that a given condition is true, throwing an error with a specified message if it is false. It can also throw a pre-existing Error object. This is useful for validating inputs or states within code.

```javascript
const a = 1, b = 2;

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

Hoek.assert(a === b, new Error('a should equal b')); // Throws the given error object
```

--------------------------------

### Hoek Merge Objects/Arrays

Source: https://github.com/hapijs/hoek/blob/master/API.md

Merges properties from a source object into a target object. Supports options for null overrides, array merging (appending by default), and symbol property cloning. Merge is destructive to the target.

```javascript
const Hoek = require('hoek');

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

Hoek.merge(target, source);
// results in {a: 0, b: 2, c: 5}

Hoek.merge(target, source2);
// results in {a: null, b: 2, c: 5}

Hoek.merge(target, source2, { nullOverride: false} );
// results in {a: 1, b: 2, c: 5}
```

```javascript
const Hoek = require('hoek');

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

Hoek.merge(targetArray, sourceArray);
// results in [1, 2, 3, 4, 5]

Hoek.merge(targetArray, sourceArray, { mergeArrays: false });
// results in [4, 5]
```

--------------------------------

### reach: Traverse object chains in JavaScript

Source: https://github.com/hapijs/hoek/blob/master/API.md

Safely traverses an object using a key chain string or array to retrieve a nested value. It supports custom separators, default values, strict mode, and traversal through functions or iterables.

```APIDOC
reach(obj, chain, [options])
  Converts an object key chain string or array to reference.
  - obj: The object to traverse.
  - chain: A string representing the key chain (e.g., 'a.b.c') or an array of keys (e.g., ['a', 'b', 'c']). Negative numbers in the chain work like negative indices on an array.
  - options: Optional settings object.
    - separator (string): String to split chain path on. Defaults to '.'.
    - default (any): Value to return if the path or value is not present. Defaults to undefined.
    - strict (boolean): If true, will throw an error on missing member. Defaults to false.
    - functions (boolean): If true, allows traversing functions for properties. If false, throws an error if a function is part of the chain. Defaults to true.
    - iterables (boolean): If true, allows traversing Set and Map objects. If false, returns undefined if the chain contains any Set or Map objects. Defaults to false.

  Returns: any - The value found at the end of the chain, or the default value if not found (and not in strict mode).

  Notes:
  - If chain is null, undefined, or false, the object itself will be returned.

  Examples:
  const chain = 'a.b.c';
  const obj = {a : {b : { c : 1}}};
  Hoek.reach(obj, chain); // returns 1

  const chain2 = ['a', 'b', -1];
  const obj2 = {a : {b : [2,3,6]}};
  Hoek.reach(obj2, chain2); // returns 6
```

--------------------------------

### isPromise: Check if an item is a promise

Source: https://github.com/hapijs/hoek/blob/master/API.md

Determines whether a given item is a Promise object. It checks for the presence of a 'then' function, which is characteristic of Promise-like objects.

```javascript
// Assuming 'promise' is a variable that might hold a promise
if (Hoek.isPromise(promise)) {
    console.log('It is a promise');
}
```

--------------------------------

### stringify: Convert object to string with error handling

Source: https://github.com/hapijs/hoek/blob/master/API.md

Converts an object to a JSON string using JSON.stringify(), but safely catches and reports any conversion errors. This is useful for displaying object information in console logs or error messages without crashing due to circular structures or invalid data.

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

--------------------------------

### escapeJson: Escape characters for JSON/JSONP contexts

Source: https://github.com/hapijs/hoek/blob/master/API.md

Escapes characters like '<', '>', '&', and line/paragraph separators for safe embedding in JSON or JSONP responses. This prevents older browsers from misinterpreting JSON as HTML and handles JSONP context requirements.

```javascript
const lineSeparator = String.fromCharCode(0x2028);
const a = Hoek.escapeJson('I said <script>confirm(&).' + lineSeparator);  //returns I said \u003cscript\u003econfirm(\u0026).\u2028
```

--------------------------------

### contain: Test value containment in JavaScript

Source: https://github.com/hapijs/hoek/blob/master/API.md

Tests if a reference value (string, array, or object) contains the provided values. Supports deep comparison, single/multiple values, and various matching options like 'only', 'part', and 'once'.

```APIDOC
contain(ref, values, [options])
  Tests if the reference value contains the provided values.
  - ref: The reference string, array, or object.
  - values: A single or array of values to find within the `ref` value. If `ref` is an object, `values` can be a key name, an array of key names, or an object with key-value pairs to compare.
  - options: Optional settings object.
    - deep (boolean): If true, performs a deep comparison of the values. Defaults to false.
    - once (boolean): If true, allows only one occurrence of each value. Defaults to false.
    - only (boolean): If true, does not allow values not explicitly listed. Defaults to false.
    - part (boolean): If true, allows partial match of the values (at least one must always match). Defaults to false.
    - symbols (boolean): Clone symbol properties. Defaults to true.

  Returns: boolean - True if the reference contains the values according to the options, false otherwise.

  Notes:
  - Comparing a string to overlapping values will result in failed comparison (e.g. `contain('abc', ['ab', 'bc'])`).
  - If an object key's value does not match the provided value, `false` is returned even when `part` is specified.

  Examples:
  Hoek.contain('aaa', 'a', { only: true }); // true
  Hoek.contain([{ a: 1 }], [{ a: 1 }], { deep: true }); // true
  Hoek.contain([1, 2, 2], [1, 2], { once: true }); // false
  Hoek.contain({ a: 1, b: 2, c: 3 }, { a: 1, d: 4 }, { part: true }); // true
```

--------------------------------

### intersect: Find common items in arrays in JavaScript

Source: https://github.com/hapijs/hoek/blob/master/API.md

Finds the common unique items between two arrays. It can optionally return only the first intersecting item found.

```APIDOC
intersect(array1, array2, [options])
  Finds the common unique items between two arrays.
  - array1: The first array.
  - array2: The second array.
  - options: Optional settings object.
    - first (boolean): If true, return only the first intersecting item. Defaults to false.

  Returns: any[] - An array containing the common unique items.

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

--------------------------------

### escapeRegex: Escape string for Regex construction

Source: https://github.com/hapijs/hoek/blob/master/API.md

Escapes special characters within a string that have meaning in regular expressions. This allows the string to be safely used as a literal pattern within a regex, ensuring characters like '.', '*', '+', '?', etc., are treated as literals.

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

--------------------------------

### escapeHtml: Escape HTML special characters

Source: https://github.com/hapijs/hoek/blob/master/API.md

Escapes HTML special characters within a string to prevent rendering issues or cross-site scripting vulnerabilities. It replaces characters like '&', '<', '>', '"', "'", and '`' with their corresponding HTML entities.

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

--------------------------------

### flatten: Flatten arrays in JavaScript

Source: https://github.com/hapijs/hoek/blob/master/API.md

Flattens an array into a single-level array. It can also merge the flattened array into a target array.

```APIDOC
flatten(array, [target])
  Flattens an array.
  - array: The array to flatten.
  - target: An optional array to merge the flattened elements into. If not provided, a new array is created.

  Returns: any[] - The flattened array.

  Examples:
  const array = [1, [2, 3]];
  const flattenedArray = Hoek.flatten(array); // results in [1, 2, 3]

  const array2 = [1, [2, 3]];
  const target = [4, [5]];
  const flattenedArray2 = Hoek.flatten(array2, target); // results in [4, [5], 1, 2, 3]
```

--------------------------------

### escapeHeaderAttribute: Escape HTTP header attribute values

Source: https://github.com/hapijs/hoek/blob/master/API.md

Escapes a string value intended for use within an HTTP header attribute. This ensures that special characters within the attribute value do not break the header's syntax or cause parsing errors.

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

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.