@hapi/hoek is a comprehensive collection of general-purpose utility methods specifically designed for the hapi ecosystem and Node.js applications. It provides essential utility functions including object manipulation, array operations, string utilities, data validation and assertion tools, async utilities, and object path operations optimized for performance and reliability.
npm install @hapi/hoekimport * as Hoek from "@hapi/hoek";
import { clone, merge, assert, wait } from "@hapi/hoek";For CommonJS:
const Hoek = require("@hapi/hoek");
const { clone, merge, assert, wait } = require("@hapi/hoek");Individual module imports (CommonJS only):
const clone = require("@hapi/hoek/clone");
const merge = require("@hapi/hoek/merge");import { clone, merge, assert, reach, escapeHtml } from "@hapi/hoek";
// Deep clone objects
const original = { a: { b: [1, 2, 3] }, c: new Date() };
const copy = clone(original);
// Merge objects
const target = { a: 1, b: 2 };
const source = { a: 0, c: 5 };
merge(target, source); // target becomes { a: 0, b: 2, c: 5 }
// Assertions
assert(copy !== original, "Clone should create new object");
// Path traversal
const data = { user: { profile: { name: "Alice" } } };
const name = reach(data, "user.profile.name"); // "Alice"
// String escaping
const safeHtml = escapeHtml("<script>alert('test')</script>");@hapi/hoek is organized around several key functional areas:
Core object manipulation functions including deep cloning, merging, and equality comparison with support for complex data types and circular references.
function clone<T>(obj: T, options?: clone.Options): T;
function merge<T1, T2>(target: T1, source: T2, options?: merge.Options): T1 & T2;
function applyToDefaults<T>(defaults: Partial<T>, source: Partial<T> | boolean | null, options?: applyToDefaults.Options): Partial<T>;
function deepEqual(obj: any, ref: any, options?: deepEqual.Options): boolean;
namespace clone {
interface Options {
readonly prototype?: boolean;
readonly symbols?: boolean;
readonly shallow?: string[] | string[][] | boolean;
}
}
namespace merge {
interface Options {
readonly nullOverride?: boolean;
readonly mergeArrays?: boolean;
readonly symbols?: boolean;
}
}
namespace applyToDefaults {
interface Options {
readonly nullOverride?: boolean;
readonly shallow?: string[] | string[][];
}
}
namespace deepEqual {
interface Options {
readonly deepFunction?: boolean;
readonly part?: boolean;
readonly prototype?: boolean;
readonly skip?: (string | symbol)[];
readonly symbols?: boolean;
}
}Array manipulation utilities for finding intersections, testing containment, and flattening nested structures.
function intersect<T1, T2>(array1: intersect.Array<T1>, array2: intersect.Array<T2>, options?: intersect.Options): Array<T1 | T2>;
function contain(ref: string, values: string | string[], options?: contain.Options): boolean;
function contain(ref: any[], values: any, options?: contain.Options): boolean;
function contain(ref: object, values: string | string[] | object, options?: Omit<contain.Options, 'once'>): boolean;
function flatten<T>(array: ArrayLike<T | ReadonlyArray<T>>, target?: ArrayLike<T | ReadonlyArray<T>>): T[];
namespace intersect {
type Array<T> = ArrayLike<T> | Set<T> | null;
interface Options {
readonly first?: boolean;
}
}
namespace contain {
interface Options {
readonly deep?: boolean;
readonly once?: boolean;
readonly only?: boolean;
readonly part?: boolean;
readonly symbols?: boolean;
}
}Object property traversal and template replacement utilities using dot notation and bracket syntax for nested data access.
function reach(obj: object | null, chain: string | (string | number)[] | false | null | undefined, options?: reach.Options): any;
function reachTemplate(obj: object | null, template: string, options?: reach.Options): string;
namespace reach {
interface Options {
readonly separator?: string;
readonly default?: any;
readonly strict?: boolean;
readonly functions?: boolean;
readonly iterables?: boolean;
}
}Security-focused string escaping utilities for HTML, JSON, RegExp, and HTTP header contexts to prevent injection attacks.
function escapeHtml(string: string): string;
function escapeJson(string: string): string;
function escapeRegex(string: string): string;
function escapeHeaderAttribute(attribute: string): string;Lightweight assertion utilities with custom error types for runtime validation and error handling.
function assert(condition: any, error: Error): asserts condition;
function assert(condition: any, ...args: any): asserts condition;
class AssertError extends Error {
name: 'AssertError';
}Function wrapper utilities for controlling execution patterns and providing no-op functionality.
function once<T extends Function>(method: T): T;
function ignore(...args: any): void;Promise-based utilities for timing control, blocking, and promise detection in async workflows.
function wait<T>(timeout?: number, returnValue?: T): Promise<T>;
function block(): Promise<void>;
function isPromise(promise: any): boolean;High-resolution benchmarking tools for performance measurement using Node.js hrtime.
class Bench {
constructor();
ts: number;
elapsed(): number;
reset(): void;
static now(): number;
}Safe data serialization utilities with error handling for JSON conversion operations.
function stringify(value: any, replacer?: any, space?: string | number): string;@hapi/hoek includes comprehensive TypeScript definitions with:
namespace ts {
type XOR<T, U> = (T | U) extends object ? (internals.Without<T, U> & U) | (internals.Without<U, T> & T) : T | U;
}