or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

array-operations.mdasync-promise-utilities.mddata-utilities.mdfunction-utilities.mdindex.mdobject-operations.mdpath-operations.mdperformance-benchmarking.mdstring-utilities.mdvalidation-assertions.md
tile.json

tessl/npm-hapi--hoek

General purpose node utilities providing object manipulation, array operations, string utilities, data validation, async utilities, and path operations for the hapi ecosystem.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@hapi/hoek@11.0.x

To install, run

npx @tessl/cli install tessl/npm-hapi--hoek@11.0.0

index.mddocs/

@hapi/hoek

@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.

Package Information

  • Package Name: @hapi/hoek
  • Package Type: npm
  • Language: JavaScript with TypeScript definitions
  • Installation: npm install @hapi/hoek

Core Imports

import * 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");

Basic Usage

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>");

Architecture

@hapi/hoek is organized around several key functional areas:

  • Object Operations: Deep cloning, merging, and comparison utilities with configurable options
  • Array Operations: Intersection, containment testing, and flattening for data manipulation
  • Path Operations: Object property traversal and template string replacement using dot notation
  • String Utilities: Security-focused escaping for HTML, JSON, RegExp, and HTTP headers
  • Validation System: Lightweight assertion utilities with custom error types
  • Async Utilities: Promise-based timing and detection utilities for async workflows
  • Performance Tools: High-resolution benchmarking for performance measurement

Capabilities

Object Operations

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;
  }
}

Object Operations

Array Operations

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;
  }
}

Array Operations

Path Operations

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;
  }
}

Path Operations

String Utilities

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;

String Utilities

Validation and Assertions

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';
}

Validation and Assertions

Function Utilities

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;

Function Utilities

Async and Promise Utilities

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;

Async and Promise Utilities

Performance and Benchmarking

High-resolution benchmarking tools for performance measurement using Node.js hrtime.

class Bench {
  constructor();
  ts: number;
  elapsed(): number;
  reset(): void;
  static now(): number;
}

Performance and Benchmarking

Data Utilities

Safe data serialization utilities with error handling for JSON conversion operations.

function stringify(value: any, replacer?: any, space?: string | number): string;

Data Utilities

TypeScript Support

@hapi/hoek includes comprehensive TypeScript definitions with:

  • Generic type parameters for type-safe cloning and merging operations
  • Assertion type guards for runtime type checking
  • Namespace declarations for complex option interfaces
  • Full IntelliSense support for all functions and their parameters
namespace ts {
  type XOR<T, U> = (T | U) extends object ? (internals.Without<T, U> & U) | (internals.Without<U, T> & T) : T | U;
}