🌟 HBH-Nodes

A modern, dependency-light Node.js utility toolkit designed for developers who love clarity, control, and composability. Every module is intentional, transparent, and production-ready.

---

📦 What is HBH-Nodes?

HBH-Nodes is not a framework. It is a collection of carefully crafted utilities that solve common Node.js problems:

• 👁️ Observing object changes (deep & reactive)
• ⚙️ Controlling async concurrency
• 📂 Safe JSON & package.json handling
• 🧰 CLI bootstrapping
• 🧼 Sanitization
• 🧠 Function safety & control
• 📘 Auto documentation generation

Each utility is standalone, meaning you only use what you need.

---

🚀 Installation

          
            1npm install hbh-nodes
          
        

          
            1import * as HBH from 'hbh-nodes';
          
        

Or selective imports:

          
            1import { chokidar, ConcurrencyQueue } from 'hbh-nodes';
          
        

---

🧠 Core Philosophy

✨ Simple > Clever 🧩 Composable > Opinionated 🔍 Explicit > Magical

HBH-Nodes is ideal for:

• CLI tools
• Internal dev tooling
• Backend utilities
• Scripts that grow into systems

---

🔤 AlphabetNumberConverter

AlphabetNumberConverter is a utility that converts numbers, strings, and JavaScript objects into compact encoded strings using a configurable alphabet. All conversions are reversible and support BigInt for large values.

---

Installation

          
            1npm install hbh-nodes
          
        

---

Import

          
            1import { AlphabetNumberConverter } from "hbh-nodes";
          
        

(CommonJS)

          
            1const { AlphabetNumberConverter } = require("hbh-nodes");
          
        

---

Encode and Decode Numbers

          
            1const conv = new AlphabetNumberConverter();3const code = conv.encode(12345);4console.log(code);                5// Example output: "dnh"7console.log(conv.decode(code));   8// Example output: 12345n
          
        

---

Encode and Decode Strings

          
            1const encoded = conv.encodeString("hello@example.com");2console.log(encoded); 3// Example output: "gyTfA...something"5const decoded = conv.decodeToString(encoded);6console.log(decoded); 7// Output: "hello@example.com"
          
        

---

Encode and Decode Objects

          
            1const user = { id: 1, name: "Alice" };3const code = conv.encodeObject(user);4console.log(code);5// Example output: "bHdKfL..."7const obj = conv.decodeObject(code);8console.log(obj);9// Output: { id: 1, name: "Alice" }
          
        

---

Auto-Type Encode (number, string, object)

          
            1console.log(conv.encode(42));2// Example: "gG"4console.log(conv.encode("hello"));5// Example: "dfKsL..."7console.log(conv.encode({ a: 1 }));8// Example: "kLf92..."
          
        

---

Custom Alphabet

          
            1const custom = new AlphabetNumberConverter({2  chars: "0123456789abcdef",3  base: 164});6const code = custom.encode(255);7console.log(code);8// Example output: "ff"10console.log(custom.decode(code));11// Output: 255n
          
        

---

Count Possible Codes

          
            1console.log(conv.uniqueCodesCount(52, 5)); 2// Example output: 380204032n  (52^5)
          
        

---

Quick Example

          
            1const conv = new AlphabetNumberConverter();3console.log(conv.encode(2025));   4// Example: "kH"6console.log(conv.decode("kH"));   7// Output: 2025n9console.log(conv.encode("chatgpt"));10// Example: "fL2kA..."12console.log(conv.encode({ ok: true }));13// Example: "bKf92..."
          
        

---

🧮 applyCalc

applyCalc is a powerful utility for safely manipulating values, including numbers, strings, arrays, and objects. It supports advanced operations such as mathematical expressions, date adjustments, string transformations, and recursive object merging, all while providing safeguards against unsafe code execution.

Import

          
            1import { applyCalc } from "hbh-nodes";
          
        

All functions from this module are available under the applyCalc namespace.

---

Functions

1. applyCalc.applyCalc(oldVal, newVal, context = {})

Applies transformations to a value (oldVal) based on the input (newVal). Supports:

• Numbers: arithmetic, percentage changes, math expressions, increments/decrements.
• Dates: adding/subtracting days, months, years, hours, minutes, or seconds.
• Strings: modifiers like trim, upper/lowercase, capitalize, title case, reverse, append, prepend, slice, padding, repeat, and regex replacement.
• Objects & Arrays: recursive updates, deletion, merging, pushing/popping/shifting/unshifting array items, deduplication, and conditional fallback.

Example:

          
            1const oldVal = 10;2const newVal = "++5"; // increment by 53const result = applyCalc.applyCalc(oldVal, newVal);4console.log(result); // 15
          
        

          
            1const date = new Date("2025-01-01");2const newDate = applyCalc.applyCalc(date, "++10d");3console.log(newDate); // 2025-01-11
          
        

          
            1const str = "hello";2const modified = applyCalc.applyCalc(str, " | upper | reverse");3console.log(modified); // "OLLEH"
          
        

          
            1const obj = { a: 1, b: 2 };2const updated = applyCalc.applyCalc(obj, { b: "__DELETE__", c: 3 });3console.log(updated); // { a: 1, c: 3 }
          
        

---

2. applyCalc.safeMathEval(expr, val, context = {})

Safely evaluates mathematical expressions using only allowed operations. Prevents access to global objects, constructors, or dangerous code.

Example:

          
            1const result = applyCalc.safeMathEval("val * 2 + 5", 10);2console.log(result); // 25
          
        

---

3. applyCalc.interpolateString(str, context)

Replaces placeholders in a string with values from a context object. Placeholders use {{key}} syntax.

Example:

          
            1const text = "Hello {{name}}!";2const result = applyCalc.interpolateString(text, { name: "Alice" });3console.log(result); // "Hello Alice!"
          
        

---

4. applyCalc.applyStringModifiers(val, modifiers, context)

Applies a series of string transformations/modifiers to a value. Supports:

• trim, upper, lower, capitalize, title, reverse
• append:<text>, prepend:<text>
• slice:start:end, padStart:length:char, padEnd:length:char, repeat:count
• replace:from:to, replaceRegex:/pattern/flags:replacement
• Interpolation using {{key}}
• Special: __now__ → current ISO timestamp

Example:

          
            1const str = "  hello world  ";2const result = applyCalc.applyStringModifiers(str, ["trim", "title"]);3console.log(result); // "Hello World"
          
        

---

5. applyCalc.dateAdd(date, amount, unit)

Adds or subtracts units of time from a JavaScript Date object. Supported units: d (days), m (months), y (years), h (hours), min (minutes), s (seconds).

Example:

          
            1const newDate = applyCalc.dateAdd(new Date("2025-01-01"), 5, "d");2console.log(newDate); // 2025-01-06
          
        

---

Usage Example

          
            1import { applyCalc } from "hbh-nodes";3// Number increment4const num = applyCalc.applyCalc(100, "++10%");5console.log(num); // 1107// String transformation8const text = applyCalc.applyCalc("hello", "| upper | reverse");9console.log(text); // "OLLEH"11// Object update with deletion12const obj = { a: 1, b: 2 };13const updated = applyCalc.applyCalc(obj, { b: "__DELETE__", c: 3 });14console.log(updated); // { a: 1, c: 3 }16// Array merge and deduplicate17const arr = [{ id: 1 }, { id: 2 }];18const merged = applyCalc.applyCalc(arr, { __MERGE__: true, items: [{ id: 2 }, { id: 3 }], __UNIQUE__: true });19console.log(merged); // [{ id: 1 }, { id: 2 }, { id: 3 }]
          
        

---

👀 chokidar

The chokidar function provides a reactive object watcher. It wraps any JavaScript object, array, Map, or Set with a Proxy and emits events whenever the data changes. This allows you to listen to changes like additions, updates, deletions, or structural mutations.

---

Import

          
            1import { chokidar } from "hbh-nodes";
          
        

---

Function

chokidar(obj, path = '')

Wraps an object and returns a proxied version that emits events on changes. Supports:

• Plain objects
• Arrays
• Maps
• Sets

Parameters:

• obj – The object, array, Map, or Set to watch.
• path – Optional string indicating the root path (useful for nested structures).

Returns:

A proxied version of obj that emits events for any changes.

---

Events

The returned proxied object supports .on(event, callback) using an internal EventEmitter.

Supported Events

Notes:

• For nested objects, path automatically represents the full path (e.g., user.address.city).
• Arrays emit update events for structural methods (push, pop, shift, unshift, splice, sort, reverse) with the updated array state.
• Maps emit events for set, delete, and clear.
• Sets emit events for add, delete, and clear.

---

Example Usage

          
            1import { chokidar } from "hbh-nodes";3const data = {4  user: { name: "Alice", age: 25 },5  items: [1, 2, 3],6  settings: new Map([['theme', 'dark']])7};9const watched = chokidar(data);11// Listen to updates12watched.user.on('update', (path, oldVal, newVal) => {13  console.log(`Updated ${path}:`, oldVal, '→', newVal);14});16watched.user.name = "Bob"; 17// Console: Updated user.name: Alice → Bob19// Listen to array changes20watched.items.on('update', (path, oldVal, newVal) => {21  console.log(`Array updated at ${path}:`, oldVal, '→', newVal);22});24watched.items.push(4); 25// Console: Array updated at items: [1,2,3] → [1,2,3,4]27// Listen to Map changes28watched.settings.on('add', (path, _, newVal) => {29  console.log(`Added to ${path}:`, newVal);30});32watched.settings.set('language', 'en'); 33// Console: Added to settings.get(language): en
          
        

---

Features

1. Deep Observation: Nested objects, arrays, Maps, and Sets are automatically wrapped with proxies.
2. Full Event Coverage: Supports add, update, delete, and clear operations for all types.
3. Path Tracking: Full paths are emitted for changes, even in deeply nested structures.
4. Array Method Support: Emits events for mutating methods (push, pop, etc.).
5. Map/Set Support: Monitors additions, deletions, and clearing operations.

---

Notes

• This implementation uses Proxy objects; thus, it requires modern JavaScript environments.
• Event listeners are attached via the .on() method.
• Useful for reactive data structures, state management, and change tracking in complex objects.

---

🚦 ConcurrencyQueue

The ConcurrencyQueue class provides a simple concurrency limiter for asynchronous functions. It ensures that only a specified number of async operations run simultaneously, queuing the rest.

---

Import

          
            1import { ConcurrencyQueue } from "hbh-nodes";
          
        

---

Class: ConcurrencyQueue

new ConcurrencyQueue(limit = 5)

Creates a new concurrency queue.

Parameters:

• limit – Maximum number of concurrent async operations. Default is 5.

Properties:

• limit – Maximum concurrency limit.
• activeCount – Current number of running operations.
• queue – Internal queue of waiting promises.

---

Method: run(fn)

Executes an asynchronous function within the concurrency queue.

Parameters:

• fn – An async function (or function returning a promise) to execute.

Returns:

A promise resolving to the result of fn.

Behavior:

1. If the number of currently running operations is below limit, fn executes immediately.
2. If the limit is reached, the function waits in a queue until a slot is available.
3. After fn finishes, the next function in the queue starts automatically.

---

Example Usage

          
            1import { ConcurrencyQueue } from "hbh-nodes";3const queue = new ConcurrencyQueue(2);5async function task(id, delay) {6  console.log(`Task ${id} started`);7  await new Promise(r => setTimeout(r, delay));8  console.log(`Task ${id} finished`);9  return id;10}12// Run multiple tasks concurrently but limited to 2 at a time13const results = await Promise.all([14  queue.run(() => task(1, 1000)),15  queue.run(() => task(2, 500)),16  queue.run(() => task(3, 700)),17  queue.run(() => task(4, 300))18]);20console.log(results); // [1, 2, 3, 4]
          
        

---

Features

1. Concurrency Limit: Only limit async operations run simultaneously.
2. Queueing: Additional calls wait in a FIFO queue.
3. Automatic Execution: As soon as one task finishes, the next in queue starts automatically.
4. Simple API: run(fn) is all that’s needed to schedule tasks.

---

Notes

• Useful for limiting network requests, API calls, file operations, or any asynchronous workloads that must be throttled.
• Supports any async function, including ones returning promises.
• If no limit is specified, defaults to 5.

---

🔄 convertObject

The convertObject function provides a flexible way to transform, filter, and traverse objects. It supports multiple output formats, deep flattening, filtering, mapping, and sorting.

---

Import

          
            1import { convertObject } from "hbh-nodes";
          
        

---

Function: convertObject(obj, options = {})

Converts or extracts data from an object according to specified rules.

Parameters:

• obj – The object to transform.
• options – Optional settings:

---

Output Formats

1. flat – Returns a flat array of values (or [key, value] pairs).
2. tree – Returns a nested tree of nodes: { key, value, children }.
3. nestedKeys – Returns nested keys only.
4. simple – Returns direct keys or mapped values of the object.

Additional helper walkers are included for specialized tasks:

• keysOnly – Extract only keys.
• valuesOnly – Extract only values.
• pathsOnly – Extract full paths.
• groupByType – Group keys by value type.
• countValues – Count occurrences of values/arrays.
• filterAndMap – Apply filter and map recursively.

---

Examples

Flat output with mapping

          
            1import { convertObject } from "hbh-nodes";3const data = {4  user: { name: "Alice", age: 25 },5  settings: { theme: "dark" }6};8const result = convertObject(data, {9  outputFormat: 'flat',10  mapFn: (v, k) => String(v).toUpperCase()11});13console.log(result);14// ["ALICE", "25", "DARK"]
          
        

Tree output with filtering

          
            1const tree = convertObject(data, {2  outputFormat: 'tree',3  filterFn: (val, key) => typeof val === 'string'4});6console.log(tree);7// [8//   { key: 'user', children: [{ key: 'name', value: 'Alice' }] },9//   { key: 'settings', children: [{ key: 'theme', value: 'dark' }] }10// ]
          
        

Nested keys output

          
            1const keys = convertObject(data, { outputFormat: 'nestedKeys' });2console.log(keys);3// [["user", ["name", "age"]], ["settings", ["theme"]]]
          
        

---

Features

• Supports deep traversal and flattening.
• Custom filters via props or filterFn.
• Value transformations using mapFn.
• Flexible output formats (flat, tree, nestedKeys).
• Optional key/value inclusion, sorting, and strict mode.
• Traversal can start from a nested path using prefix.

---

📄 generateDocs

Generates documentation for an API map. It analyzes each function in the provided map and extracts a description. This can be used to automatically build your docs site or README.

---

string – A formatted string listing each function with its description.

---

1. Check description property: If a function has a description property, that is used first.

2. Check JSDoc-style comment: If no description property exists, it tries to extract a JSDoc comment from the function string.

3. Fallback: If neither exists, it returns "No description available." for that function.

---

          
            1function add(a, b) {2  /** Adds two numbers together and returns the result */3  return a + b;4}6function multiply(a, b) {7  return a * b;8}9multiply.description = "Multiplies two numbers.";11const apiMap = { add, multiply };13console.log(generateDocs(apiMap));
          
        

Output:

- `add`: Adds two numbers together and returns the result
- `multiply`: Multiplies two numbers.

---

1. Function without description or JSDoc:

          
            1function noop() {}2const apiMap = { noop };3console.log(generateDocs(apiMap));
          
        

Output:

- `noop`: No description available.

2. Function with multiline JSDoc:

          
            1function complex(a, b) {2  /**3   * Performs a complex operation.4   * Returns a transformed value.5   */6  return a + b;7}8const apiMap = { complex };9console.log(generateDocs(apiMap));
          
        

Output:

- `complex`: Performs a complex operation. Returns a transformed value.

3. Function with leading * in JSDoc:

          
            1function example() {2  /**3   * Example function4   * with multiple lines5   */6  return true;7}8const apiMap = { example };9console.log(generateDocs(apiMap));
          
        

Output:

- `example`: Example function with multiple lines

4. Non-function values in map – will skip properly because .toString() works on anything, but best practice is to provide only functions.

---

• The function works best when the apiMap only contains functions. Non-function values may produce unexpected results.
• Leading/trailing whitespace in JSDoc is automatically trimmed.
• Multi-line JSDoc comments are flattened into a single line for readability.

---

📣 EventEmitter

A lightweight event emitter class that supports standard event handling patterns including on, once, off, and emit. Ideal for creating reactive systems or handling custom events in JavaScript.

Import

          
            1import { EventEmitter } from "hbh-nodes";
          
        

---

Methods

on(eventName, listener)

Registers a listener for a given event. Multiple listeners can be registered for the same event.

Parameters:

• eventName (string) – Name of the event to listen to.
• listener (function) – Callback function to execute when the event is emitted.

Returns: The EventEmitter instance (supports chaining).

Example:

          
            1const emitter = new EventEmitter();3emitter.on("data", (msg) => {4  console.log("Received:", msg);5});7emitter.emit("data", "Hello World"); // Logs: Received: Hello World
          
        

Edge Cases:

• Multiple listeners can be attached to the same event; all will be called in order of registration.
• Chaining allows multiple on calls in sequence: emitter.on("a", fn1).on("b", fn2).

---

once(eventName, listener)

Registers a one-time listener that will be automatically removed after the first invocation.

Parameters:

• eventName (string) – Event name.
• listener (function) – Callback function.

Returns: The EventEmitter instance (supports chaining).

Example:

          
            1emitter.once("connect", () => console.log("Connected!"));3emitter.emit("connect"); // Logs: Connected!4emitter.emit("connect"); // No output
          
        

Edge Cases:

• The listener is removed immediately after execution.
• Safe to attach multiple once listeners to the same event.

---

emit(eventName, ...args)

Triggers an event, calling all registered listeners with the provided arguments.

Parameters:

• eventName (string) – Event to trigger.
• ...args – Any number of arguments to pass to listeners.

Returns: The EventEmitter instance (supports chaining).

Example:

          
            1emitter.on("update", (oldVal, newVal) => {2  console.log(`Changed from ${oldVal} to ${newVal}`);3});5emitter.emit("update", 1, 2); // Logs: Changed from 1 to 2
          
        

Edge Cases:

• If no listeners exist for the event, emit does nothing.
• Errors in one listener do not prevent other listeners from executing; they are logged to console.

---

off(eventName, listener)

Removes a specific listener for an event. If no listener is provided, all listeners for that event are removed.

Parameters:

• eventName (string) – Event name.
• listener (function, optional) – Specific listener to remove.

Returns: The EventEmitter instance (supports chaining).

Example:

          
            1const fn = (msg) => console.log(msg);2emitter.on("data", fn);3emitter.off("data", fn); // Removes fn
          
        

Edge Cases:

• Calling off with no listener removes all listeners for the event.
• Safe to call off on an event that has no listeners; does nothing.

---

removeAll(eventName)

Utility method to remove all listeners for a specific event.

Parameters:

• eventName (string) – Event name.

Returns: The EventEmitter instance (supports chaining).

Example:

          
            1emitter.on("x", () => {});2emitter.removeAll("x"); // All listeners for "x" removed
          
        

---

listeners(eventName)

Returns an array of all registered listeners for an event.

Parameters:

• eventName (string) – Event name.

Returns: Array of functions.

Example:

          
            1emitter.on("msg", () => {});2console.log(emitter.listeners("msg").length); // 1
          
        

Edge Cases:

• Returns an empty array if no listeners are registered.

---

🎁 FunctionWrapper

FunctionWrapper is a highly versatile utility class for JavaScript/TypeScript functions that allows you to enhance, monitor, transform, and control functions with a rich set of composable decorators. It extends a Logger base class to provide optional logging capabilities.

With FunctionWrapper, you can chain multiple function transformations, handle retries, measure performance, debounce or throttle calls, enforce validations, create undoable operations, and much more—all in a highly modular and chainable manner.

---

Features

FunctionWrapper provides over 80+ static methods to extend and wrap functions. Some of the core capabilities include:

• Logging and Monitoring

  • log(fn): Logs function calls and results.
  • time(fn): Measures execution duration.
  • profile(fn): Logs execution stats with timestamp.
  • stats(fn): Tracks call count and average execution time.

• Control Flow Enhancements

  • retry(fn, retries, delayMs): Automatically retries a function on failure.
  • once(fn), oncePerArgs(fn): Execute only once globally or per argument set.
  • after(fn, n), before(fn, n): Control execution after or before a number of calls.
  • limit(fn, max): Limits total number of calls.
  • lock(fn): Prevents concurrent execution.

• Asynchronous Handling

  • debounce(fn, wait): Delays execution until idle.
  • throttle(fn, wait): Limits execution frequency.
  • delayFn(fn, delay), delayResult(fn, ms), delayEach(fn, ms): Flexible delayed execution.
  • cancelable(fn): Creates cancelable promises.
  • queue(fn): Serializes asynchronous calls.

• Data Manipulation

  • memo(fn): Caches results for identical arguments.
  • transformOutput(fn, transformer): Post-process function results.
  • mask(fn, masker): Preprocess arguments before calling the function.
  • randomizeArgs(fn): Shuffles arguments randomly.
  • randomBehavior(fn, behaviors): Introduces probabilistic behaviors.

• Validation and Safety

  • validate(fn, validator): Validates arguments.
  • ensure(fn, validator): Validates output.
  • catch(fn, onError, fallback): Graceful error handling.
  • sandbox(fn, timeout): Safe execution with error handling and time limit.
  • safeJson(fn): Safe JSON parsing and handling.

• Functional Utilities

  • chain(fn): Chain multiple transformations in a fluent interface.
  • pipe(...fns): Compose functions in a pipeline.
  • tap(fn, tapFn): Tap into function results without affecting output.
  • hook(fn, { before, after }): Run pre- and post-execution hooks.
  • feedback(fn, logger): Collect input/output logs.

• Simulation and Testing

  • simulate(fn, options): Simulate failures, delays, and data corruption.
  • test(fn, testCases): Run predefined tests on a function.
  • predict(fn, modelFn): Attach predictive models to results.

• Batching and History

  • batch(fn, chunkSize, cb): Execute functions in batches.
  • history(fn): Track inputs and outputs with getHistory and clearHistory.
  • watch(fn): Subscribe to function call results.
  • changelog(fn): Track changes in object outputs.

• Advanced Features

  • undoable(fn, inverseFn): Support undo operations.
  • locale(fn, formatter): Apply locale-based input/output formatting.
  • smartIdle(fn, options): Execute during idle periods with cancellation.
  • eventual(fn, checkFn, interval): Poll until a condition is met.
  • timeLimit(fn, timeout): Force a maximum execution duration.

---

Installation

          
            1npm install hbh-nodes
          
        

Or using yarn:

          
            1yarn add hbh-nodes
          
        

---

Import

          
            1import { FunctionWrapper as FW } from "hbh-nodes";2const { FunctionWrapper } = FW;
          
        

---

Usage

1. Basic Function Wrapping

          
            1const add = (a, b) => a + b;2const loggedAdd = FunctionWrapper.log(add);4console.log(loggedAdd(2, 3));5// Logs: Calling add [2, 3]6// Logs: Result from add 5
          
        

2. Chaining Transformations

          
            1const multiply = (a, b) => a * b;3const enhancedFn = FunctionWrapper.chain(multiply)4  .log()5  .time()6  .memo()7  .value();9console.log(enhancedFn(5, 6));
          
        

3. Debounce / Throttle

          
            1const save = (data) => console.log('Saved:', data);2const debouncedSave = FunctionWrapper.debounce(save, 500);3const throttledSave = FunctionWrapper.throttle(save, 1000);
          
        

4. Retry with Delay

          
            1const unstable = () => {2  if (Math.random() < 0.7) throw new Error('Fail');3  return 'Success';4};6const reliable = FunctionWrapper.retry(unstable, 5, 100);7reliable().then(console.log).catch(console.error);
          
        

5. Undoable Functions

          
            1let counter = 0;2const increment = () => ++counter;3const decrement = () => --counter;5const undoableIncrement = FunctionWrapper.undoable(increment, decrement);6undoableIncrement(); // counter = 17undoableIncrement.undo(); // counter = 0
          
        

6. Monitoring and Stats

          
            1const slowFn = (x) => new Promise(res => setTimeout(() => res(x * 2), 100));2const profiled = FunctionWrapper.stats(slowFn);4profiled(2).then(() => {5  console.log(profiled.stats); // { calls: 1, avgTime: '100.00ms' }6});
          
        

---

API Reference

Each static method of FunctionWrapper can be used independently to wrap any function. Refer to the method list in the Features section for full capabilities.

Chaining Example

          
            1const fn = (x) => x * 2;2const chained = FunctionWrapper.chain(fn)3  .debounce(200)4  .log()5  .memo()6  .time()7  .value();9chained(5);
          
        

FunctionWrapper API Reference

FunctionWrapper is an advanced utility class that provides 80+ higher-order function decorators and wrappers for logging, timing, retrying, caching, debouncing, throttling, validating, transforming, and managing functions in versatile ways.

---

---

---

---

---

---

---

---

---

---

---

Perfect! Let’s make a detailed mental map / diagram of the entire FunctionWrapper class and its methods. I’ll structure it clearly so you can either visualize it or later draw it on paper/software.

---

• Provides wrappers/enhancements for functions

• Key capabilities:

  • Logging, timing, retry, caching
  • Control execution (debounce, throttle, lock, once)
  • Transform input/output
  • Error handling and safety
  • Composition and chaining

---

A. Logging & Monitoring

• log(fn) → logs calls and results
• time(fn) → measures execution time
• profile(fn) → detailed table of duration
• changelog(fn) → logs changes in object outputs
• stats(fn) → tracks number of calls, avg time
• watch(fn) → subscribe to outputs
• feedback(fn, logger) → logs input/output

B. Execution Control

• once(fn) → runs only once
• after(fn, n) → runs after n calls
• before(fn, n) → runs at most n times
• limit(fn, max) → limits number of calls
• lock(fn) → prevents concurrent execution
• oncePerArgs(fn) → runs once per argument combo
• queue(fn) → sequential execution
• delayFn(fn, delay) → delay execution
• delayResult(fn, ms) → delay return value
• delayEach(fn, delayMs) → sequential with delay
• afterIdle(fn, timeout) → browser idle execution
• smartIdle(fn, options) → idle execution with cancel

C. Error Handling & Safety

• catch(fn, onError, fallback) → error catch
• sandbox(fn, timeout) → safe execution with error handling
• safeJson(fn) → catches JSON parsing errors
• timeLimit(fn, timeout) → rejects after timeout
• cancelable(fn) → cancel in-flight promise

D. Input/Output Transformation

• validate(fn, validator) → validate arguments
• mask(fn, masker) → transform arguments
• restrict(fn, isAllowed) → allow/disallow call
• tap(fn, tapFn) → side effect without affecting return
• transformOutput(fn, transformer) → change output
• locale(fn, formatter) → format input/output
• unit(fn, unit) → wraps output with value/unit/timestamp

E. Caching & Memoization

• memo(fn) → caches results
• replay(fn) → returns cached result for identical args

F. Functional Composition

• pipe(...fns) → left-to-right composition
• chainable(fn) → chain calls, collect results

G. Retry & Simulation

• retry(fn, retries, delayMs) → retry failing fn
• simulate(fn, options) → simulate failure/delay/corruption
• randomBehavior(fn, behaviors) → random behavior
• randomizeArgs(fn) → shuffle arguments

H. Undo & History

• undoable(fn, inverseFn) → supports undo
• history(fn) → tracks args/results

I. Conditional Execution

• ensure(fn, validator) → ensures output passes
• filterArgs(fn, filterFn) → executes only if condition passes
• delayIf(fn, condition, delayMs) → delays conditionally
• alertOn(fn, condition) → logs alerts if condition true
• warnOnArgs(fn, warningFn) → warns on suspicious input
• predict(fn, modelFn) → adds prediction based on output
• eventual(fn, checkFn, interval) → polls until condition true

J. Repeat & Batch

• repeat(fn, n) → repeat function n times
• batch(fn, chunkSize, cb) → executes in chunks

K. Miscellaneous

• hook(fn, {before, after}) → pre/post hooks
• evolve(fn, evolver) → mutate or extend output

---

FunctionWrapper
│
├─ Logging & Monitoring
│   ├─ log()
│   ├─ time()
│   ├─ profile()
│   ├─ changelog()
│   ├─ stats()
│   ├─ watch()
│   └─ feedback()
│
├─ Execution Control
│   ├─ once()
│   ├─ after()
│   ├─ before()
│   ├─ limit()
│   ├─ lock()
│   ├─ oncePerArgs()
│   ├─ queue()
│   ├─ delayFn()
│   ├─ delayResult()
│   ├─ delayEach()
│   ├─ afterIdle()
│   └─ smartIdle()
│
├─ Error Handling & Safety
│   ├─ catch()
│   ├─ sandbox()
│   ├─ safeJson()
│   ├─ timeLimit()
│   └─ cancelable()
│
├─ Input/Output Transformation
│   ├─ validate()
│   ├─ mask()
│   ├─ restrict()
│   ├─ tap()
│   ├─ transformOutput()
│   ├─ locale()
│   └─ unit()
│
├─ Caching & Memoization
│   ├─ memo()
│   └─ replay()
│
├─ Functional Composition
│   ├─ pipe()
│   └─ chainable()
│
├─ Retry & Simulation
│   ├─ retry()
│   ├─ simulate()
│   ├─ randomBehavior()
│   └─ randomizeArgs()
│
├─ Undo & History
│   ├─ undoable()
│   └─ history()
│
├─ Conditional Execution
│   ├─ ensure()
│   ├─ filterArgs()
│   ├─ delayIf()
│   ├─ alertOn()
│   ├─ warnOnArgs()
│   ├─ predict()
│   └─ eventual()
│
├─ Repeat & Batch
│   ├─ repeat()
│   └─ batch()
│
└─ Miscellaneous
    ├─ hook()
    └─ evolve()

FunctionWrapper
├─ Logging & Monitoring
│  ├─ log(fn)
│  ├─ time(fn)
│  ├─ profile(fn)
│  ├─ changelog(fn)
│  ├─ feedback(fn, logger)
│  └─ watch(fn)
│
├─ Execution Control
│  ├─ once(fn)
│  ├─ after(fn, n)
│  ├─ before(fn, n)
│  ├─ lock(fn)
│  ├─ queue(fn)
│  ├─ repeat(fn, n)
│  ├─ delayFn(fn, delay)
│  ├─ timeLimit(fn, timeout)
│  ├─ sandbox(fn, timeout)
│  ├─ afterIdle(fn, timeout)
│  └─ smartIdle(fn, options)
│
├─ Error Handling & Safety
│  ├─ catch(fn, onError, fallback)
│  ├─ safeJson(fn)
│  ├─ undoable(fn, inverseFn)
│  ├─ cancelable(fn)
│  ├─ ensure(fn, validator)
│  └─ restrict(fn, isAllowed)
│
├─ Input/Output Transformation
│  ├─ tap(fn, tapFn)
│  ├─ mask(fn, masker)
│  ├─ transformOutput(fn, transformer)
│  ├─ evolve(fn, evolver)
│  ├─ locale(fn, formatter)
│  ├─ randomizeArgs(fn)
│  ├─ randomBehavior(fn, behaviors)
│  └─ predict(fn, modelFn)
│
├─ Caching & Memoization
│  ├─ memo(fn)
│  ├─ replay(fn)
│  └─ oncePerArgs(fn)
│
├─ Functional Composition
│  ├─ chainable(fn)
│  ├─ pipe(...fns)
│  └─ hook(fn, {before, after})
│
├─ Retry & Simulation
│  ├─ retry(fn, retries, delayMs)
│  └─ simulate(fn, {failRate, corrupt, delay})
│
├─ Conditional Execution
│  ├─ delayIf(fn, condition, delayMs)
│  ├─ eventual(fn, checkFn, interval)
│  ├─ filterArgs(fn, filterFn)
│  ├─ warnOnArgs(fn, warningFn)
│  └─ alertOn(fn, condition)
│
├─ Repeat & Batch
│  ├─ batch(fn, chunkSize, cb)
│  └─ delayEach(fn, delayMs)
│
└─ Unit & Stats
   ├─ unit(fn, unit)
   └─ stats(fn)

---

🏁 isMain & runIfMain

hbh-nodes provides utility functions to detect if a module is the main entry point and to execute code only when the module is run directly, not when imported. This is especially useful for libraries that can be both imported and executed as scripts.

---

Import

CommonJS

          
            1const { isMain, runIfMain } = require("hbh-nodes");
          
        

ES Modules

          
            1import { isMain, runIfMain } from "hbh-nodes";
          
        

---

isMain(importMetaUrl, cjsModule, mainModule)

Determines if the current module is being executed as the main script.

Parameters

Returns

• true → If the module is the main entry point.
• false → If the module is imported or parameters are invalid.

Behavior

1. CommonJS Detection:

             
               1if (typeof mainModule !== "undefined" && cjsModule === mainModule) {2    return require.main === mainModule;3}
             
           

   Checks if the current module is the main script.

2. ES Module Detection:

             
               1const filename = fileURLToPath(importMetaUrl);2return filename === process.argv[1];
             
           

   Converts import.meta.url to a path and compares with the Node.js entry file.

3. Safe Fallback: Returns false for unknown or invalid inputs.

Example

          
            1const { isMain } = require("./mainCheck");3if (isMain(null, module, require.main)) {4  console.log("This module is running directly!");5}
          
        

Edge Cases

• Works for both ES modules and CommonJS.
• Returns false when the module is imported.
• Handles invalid inputs gracefully.
• In ESM, require is unavailable, so CommonJS checks are skipped.

---

runIfMain(importMetaUrl, cjsModule, mainModule, fn)

Executes a function only if the current module is the main script.

Parameters

Returns

• Returns the result of fn() if executed.
• Returns undefined if the module is imported.

Behavior

• Calls isMain() internally to determine if the module is the main entry point.
• Executes the provided function fn() only when the module is running directly.
• Safe for mixed ESM + CommonJS environments.

Example

CommonJS

          
            1const { runIfMain } = require("./mainCheck");3function main() {4  console.log("Running directly as a script!");5}7runIfMain(null, module, require.main, main);
          
        

ES Module

          
            1import { runIfMain } from "./mainCheck.mjs";3runIfMain(import.meta.url, null, null, () => {4  console.log("Running directly in ESM!");5});
          
        

Edge Cases

• Does nothing if the module is imported.
• Safely handles invalid inputs.
• Useful for CLI scripts or libraries with optional initialization.

---

Best Practices

1. Always pass the correct module references in CommonJS (module and require.main).
2. For ESM, pass import.meta.url and null for the CommonJS parameters.
3. Wrap all startup code or CLI logic inside runIfMain to avoid side effects on import.
4. Use isMain if you need conditional checks without running a function.

---

Advanced / Deep Dive Usage

Example: CLI Script with Arguments

          
            1runIfMain(import.meta.url, module, require.main, () => {2  const args = process.argv.slice(2);3  console.log("CLI arguments:", args);4  // Start your CLI logic here5});
          
        

---

🗂️ JsonManager

A utility class for managing JSON data in memory and on disk. Supports loading, saving, reading, updating, and deleting nested keys using dot-separated paths.

Import

          
            1import { JsonManager } from "hbh-nodes";
          
        

---

constructor(initialData = {})

Creates a new JsonManager instance with optional initial data.

Parameters:

• initialData (object, optional) – Starting JSON data. Defaults to an empty object.

Example:

          
            1const jm = new JsonManager({ user: { name: "Alice" } });
          
        

---

static async loadFromFile(filePath)

Loads JSON data from a file and returns a JsonManager instance.

Parameters:

• filePath (string) – Path to the JSON file.

Returns: Promise<JsonManager> – A new instance containing the loaded data.

Example:

          
            1const jm = await JsonManager.loadFromFile("./data.json");
          
        

Edge Cases:

• Throws an error if the file does not exist or contains invalid JSON.

---

async saveToFile(filePath)

Saves the current JSON data to a file.

Parameters:

• filePath (string) – Path where the JSON should be written.

Returns: Promise<void>

Example:

          
            1await jm.saveToFile("./data.json");
          
        

Edge Cases:

• Overwrites the file if it already exists.
• Throws an error if the write operation fails.

---

get(path)

Retrieves a value from nested JSON using a dot-separated path.

Parameters:

• path (string) – Dot-separated key path (e.g., "user.name").

Returns: The value at the given path or undefined if not found.

Example:

          
            1const name = jm.get("user.name"); // "Alice"
          
        

---

set(path, value)

Sets a value in nested JSON using a dot-separated path. Creates intermediate objects if needed.

Parameters:

• path (string) – Dot-separated key path.
• value – Value to set.

Example:

          
            1jm.set("user.age", 25);
          
        

---

delete(path)

Deletes a key in nested JSON using a dot-separated path.

Parameters:

• path (string) – Dot-separated key path.

Example:

          
            1jm.delete("user.age");
          
        

---

print()

Pretty-prints the current JSON data to the console.

Example:

          
            1jm.print();2/*3{4  "user": {5    "name": "Alice"6  }7}8*/
          
        

---

🎯 micromatch

A minimal utility for matching strings against glob patterns. Supports standard wildcards (*, **, ?) and character ranges ([a-z]). Can also negate patterns using !.

Import

          
            1import { micromatch } from "hbh-nodes";
          
        

---

escapeRegex(str)

Escapes special regex characters in a string.

Parameters:

• str (string) – Input string.

Returns: Escaped string safe for regex.

Example:

          
            1const escaped = micromatch.escapeRegex("file?.txt"); // "file\?.txt"
          
        

---

globToRegex(pattern)

Converts a glob pattern to a JavaScript RegExp.

Parameters:

• pattern (string) – Glob pattern (e.g., "*.js" or "src/**/index.js").

Returns: RegExp – Equivalent regex for matching.

Example:

          
            1const regex = micromatch.globToRegex("src/**/*.js");2console.log(regex.test("src/app/index.js")); // true
          
        

Edge Cases:

• * matches any sequence except /.
• ** matches any sequence including /.
• ? matches any single character except /.
• Character ranges like [a-z] are preserved.

---

micromatch(list, pattern)

Filters a list of strings based on a glob pattern. Supports negation with a leading !.

Parameters:

• list (string[]) – Array of strings to match.
• pattern (string) – Glob pattern.

Returns: Array of matched strings.

Example:

          
            1const files = ["index.js", "style.css", "app.js"];2console.log(micromatch.micromatch(files, "*.js")); // ["index.js", "app.js"]3console.log(micromatch.micromatch(files, "!*.js")); // ["style.css"]
          
        

---

matchGlob(pattern, str)

Tests if a single string matches a glob pattern.

Parameters:

• pattern (string) – Glob pattern.
• str (string) – String to test.

Returns: boolean – true if the string matches the pattern.

Example:

          
            1console.log(micromatch.matchGlob("*.js", "index.js")); // true2console.log(micromatch.matchGlob("*.js", "style.css")); // false
          
        

---

📝 Project2MD

Overview

The Project2MD function converts a project directory into a single Markdown (.md) file. It recursively walks through the directory tree, reads file contents, and appends them to a Markdown file with optional formatting. It also generates a summary table of all processed files.

This is useful for creating project documentation, code snapshots, or sharing projects as a single Markdown file.

---

Installation

          
            1npm install hbh-nodes
          
        

Or using yarn:

          
            1yarn add hbh-nodes
          
        

---

Usage

          
            1import { P2PMD } from 'hbh-nodes';3const { Project2MD, SimpleExclude } = P2PMD;5await Project2MD({6  input: './my-project',7  output: './docs/project.md',8  concurrency: 10,9  onprogress: ({ index, relPath }) => {10    console.log(`Processed file #${index}: ${relPath}`);11  },12  onEnd: ({ total }) => {13    console.log(`Finished! Total files processed: ${total}`);14  },15});
          
        

---

Function Signature

          
            1async function Project2MD(opts?: Project2MDOptions): Promise<void>
          
        

Parameters

opts – An optional object of type Project2MDOptions.

Options

---

Predefined Exclude

SimpleExclude is provided to skip common Node.js project files and directories:

          
            1SimpleExclude.Node = ['node_modules', 'package-lock.json', '.gitignore', 'package.json'];
          
        

---

How It Works

1. Resolve Paths Converts input and output to absolute paths and ensures the output file itself is excluded.

2. Directory Walk Recursively walks directories sequentially to avoid concurrency deadlocks.

   • Directories are traversed first.
   • Files are processed concurrently, respecting the concurrency limit.

3. File Processing For each file:

   • Skips if hidden, excluded, or exceeds maxFileSize.
   • Reads file contents (utf-8).
   • Generates a Markdown header using filenameFormatter.
   • Wraps the content in a fenced code block with language derived from the file extension.
   • Appends content to the output Markdown file.
   • Calls onprogress callback.

4. Summary Generation After all files are processed:

   • Calls summaryFormatter with the list of processed files.
   • Appends the generated summary to the Markdown file.

5. Error Handling

   • Wraps file system operations in safeRun to catch errors without stopping execution unless stopOnError is true.
   • Logs warnings and errors for files that fail to process.

---

Example Output

Assuming a directory structure:

src/
 ├─ index.js
 ├─ utils.js
README.md

Generated output.md could look like:

          
            1###### `src/index.js`3```js4console.log('Hello World');
          
        

src/utils.js

          
            1export function add(a, b) { return a + b; }
          
        

README.md

          
            1# My Project2This is my project.
          
        

---

Notes

• Files larger than maxFileSize are skipped.
• Hidden files/directories are ignored if ignoreHidden is true.
• Concurrency ensures faster processing but directory traversal is always sequential.
• Markdown language blocks are derived from file extensions; fallback to no language if unknown.
• onprogress and onEnd allow progress tracking or UI updates.

---

This function is designed for Node.js environments and uses ESM imports (fs/promises, path).

---

📦 packageJson

A set of functions to programmatically create and manage package.json files for Node.js projects, including batch creation in subdirectories and automated publishing.

---

Import

          
            1import { JPM } from "hbh-nodes";2const { createPackageJson, createPackagesInSubdirs, publishAllPackages } = JPM;
          
        

---

createPackageJson(dirPath, newJson)

Creates a package.json file in the specified directory. If the file already exists, it will not overwrite it.

Parameters:

• dirPath (string) – Path to the directory where package.json should be created.
• newJson (object, optional) – Overrides or additional fields for the package.json.

Returns:

• JSON string of the final package content.

Example:

          
            1createPackageJson("./my-lib", {2  name: "my-lib",3  version: "1.0.0",4  author: "HBH"5});
          
        

Edge Cases:

• If a package.json already exists, it is not overwritten.
• Default fields are merged with any custom fields provided.

---

createPackagesInSubdirs(parentDir, defaultJsonOverrides)

Creates package.json files in all subdirectories of a given directory.

Parameters:

• parentDir (string) – Directory containing multiple package folders.
• defaultJsonOverrides (object, optional) – Fields to override default values for all packages.

Example:

          
            1createPackagesInSubdirs("./packages", {2  license: "MIT",3  author: "HBH"4});
          
        

Edge Cases:

• Uses the folder name as the package name by default.
• Only directories are processed; files are ignored.
• Existing package.json files are preserved.

---

publishAllPackages(parentDir)

Publishes all Node.js packages in subdirectories under a specified directory using npm publish.

Parameters:

• parentDir (string) – Directory containing multiple package folders with valid package.json.

Example:

          
            1publishAllPackages("./packages");
          
        

Behavior:

• Runs npm publish --access public in each subdirectory.
• Logs success or failure for each package.

Edge Cases:

• Subdirectories without package.json are skipped.
• Errors in publishing one package do not stop publishing of others.
• Output of npm publish is displayed in the console.

---

🧼 Sanitizers

A comprehensive utility to sanitize strings, objects, and arrays by removing or masking sensitive data such as emails, paths, IPs, URLs, credit cards, and more.

---

Import

          
            1import { Sanitizers as SZ } from "hbh-nodes";2const { Sanitizers, deepSanitize, applySanitizers, sanitizeAll, capitalize, getSanitizerNames } = SZ;
          
        

---

Sanitizers

An object containing individual sanitization functions automatically generated from common sensitive patterns.

Example Functions:

• sanitizeEmail(str) – Masks emails.
• sanitizePath(str) – Masks file paths.
• sanitizeIp(str) – Masks IPv4/IPv6 addresses.
• sanitizeCreditCard(str) – Masks credit card numbers.
• sanitizeHtml(str) – Strips HTML tags.
• sanitizeJwt(str) – Masks JWT tokens.

Usage:

          
            1const dirty = "User email: test@example.com";2const clean = Sanitizers.sanitizeEmail(dirty);3console.log(clean); // User email: [SANITIZED:email]
          
        

---

deepSanitize(obj, sanitizerFns = [], sanitizeKeys = false)

Recursively sanitizes strings in objects or arrays using provided sanitizer functions.

Parameters:

• obj – Object, array, or string to sanitize.
• sanitizerFns – Array of sanitizer functions to apply.
• sanitizeKeys (boolean) – If true, also sanitizes object keys.

Example:

          
            1const data = {2  user: {3    email: "test@example.com",4    password: "1234"5  }6};8const clean = deepSanitize(data, [Sanitizers.sanitizeEmail]);9console.log(clean);10// { user: { email: '[SANITIZED:email]', password: '1234' } }
          
        

---

applySanitizers(value, sanitizers = [])

Applies an array of sanitizer functions to a single string safely.

Example:

          
            1const dirty = "My email is test@example.com";2const clean = applySanitizers(dirty, [Sanitizers.sanitizeEmail]);3console.log(clean); // My email is [SANITIZED:email]
          
        

---

sanitizeAll(str, options = {})

Convenience function to apply multiple sanitizers with filtering and custom replacements.

Options:

• only – Array of sanitizer names to apply exclusively.
• exclude – Array of sanitizer names to skip.
• replacements – Custom replacement strings for specific sanitizers.

Example:

          
            1const dirty = "Contact me at test@example.com or 123 Main St";2const clean = sanitizeAll(dirty, { exclude: ["sanitizePath"] });3console.log(clean); // Contact me at [SANITIZED:email] or 123 Main St
          
        

---

capitalize(str)

Utility to capitalize the first letter of a string, mainly used for dynamically naming sanitizer functions.

Example:

          
            1console.log(capitalize("email")); // Email
          
        

---

getSanitizerNames()

Returns an array of all generated sanitizer function names.

Example:

          
            1console.log(getSanitizerNames());2// ["sanitizePath", "sanitizeEmail", "sanitizeIp", ...]
          
        

---

Edge Cases & Notes:

• Sanitizers operate safely on non-string values by returning them unchanged.
• deepSanitize can handle nested arrays and objects of arbitrary depth.
• Custom replacements allow flexible masking beyond default [SANITIZED:<type>].

---

🗜️ StringCompressor

A utility class for compressing and decompressing strings using a dictionary-based approach. Frequently occurring words can be replaced with short keys to reduce string size. Supports customizable flags, automatic dictionary generation, and statistics on compression efficiency.

---

Import

          
            1import { StringCompressor } from "hbh-nodes";
          
        

---

Class: StringCompressor

Constructor

          
            1new StringCompressor(dictionary = {}, flag = '$')
          
        

Parameters:

• dictionary – Optional initial dictionary mapping original strings to compressed keys. Defaults to {}.
• flag – Prefix for compressed keys. Defaults to $.

Example:

          
            1const compressor = new StringCompressor({}, '#');
          
        

---

setDictionary(dictionary)

Sets a new dictionary and automatically generates a reverse dictionary for decompression.

Parameters:

• dictionary – Object mapping original strings to short keys.

Example:

          
            1compressor.setDictionary({ hello: '$a', world: '$b' });
          
        

---

compress(str, dictionary = null)

Compresses a string using the current dictionary. Optionally, a new dictionary can be passed.

Parameters:

• str – The string to compress.
• dictionary – Optional dictionary to override current one.

Example:

          
            1const compressed = compressor.compress("hello world hello");2// "$a $b $a"
          
        

---

decompress(str, dictionary = null)

Decompresses a string using the current reverse dictionary. Optionally, a new dictionary can be passed.

Parameters:

• str – The string to decompress.
• dictionary – Optional dictionary to override current one.

Example:

          
            1const decompressed = compressor.decompress("$a $b $a");2// "hello world hello"
          
        

---

generateMap(str, minLength = 4, minFreq = 2, flag)

Generates a compression dictionary automatically based on word frequency in the input string.

Parameters:

• str – Input string.
• minLength – Minimum length of words to consider. Defaults to 4.
• minFreq – Minimum frequency of words to include. Defaults to 2.
• flag – Optional flag prefix for keys. Defaults to the instance flag.

Returns: Dictionary object mapping words to short keys.

Example:

          
            1const map = compressor.generateMap("hello world hello world", 3, 2);2// { hello: '$a', world: '$b' }
          
        

---

generateAndSetDictionary(str, minLength = 4, minFreq = 2, flag)

Generates a frequency-based dictionary and sets it as the current dictionary.

Returns: Dictionary object.

Example:

          
            1compressor.generateAndSetDictionary("hello world hello world");2// Dictionary now set: { hello: '$a', world: '$b' }
          
        

---

stats(originalStr, compressedStr)

Provides statistics on compression efficiency.

Parameters:

• originalStr – Original string.
• compressedStr – Compressed string.

Returns: Object with:

• originalLength – Length of original string.
• compressedLength – Length of compressed string.
• saved – Number of characters saved.
• percentSaved – Percentage reduction as string.

Example:

          
            1const stats = compressor.stats("hello world hello", "$a $b $a");2console.log(stats);3// { originalLength: 17, compressedLength: 9, saved: 8, percentSaved: '47.06%' }
          
        

---

replace(str, map)

Replaces occurrences of keys in a string based on a mapping object.

Example:

          
            1compressor.replace("hello world", { hello: '$a', world: '$b' });2// "$a $b"
          
        

---

Edge Cases & Notes:

• Supports Unicode words via \p{L} regex.
• Generates short keys using patterns like a, b, ..., z, aa, ab.
• Words shorter than minLength or below frequency threshold are ignored.
• Safe to use on strings without dictionary; returns original string unchanged if mapping is empty.

---

⏱️ TrackTimeWrapper — Time Utilities

Measure execution time and format durations with ease.

---

🕒 TrackTimeWrapper.formatDuration(ms)

Convert milliseconds into a human-readable duration string.

          
            1import { TrackTimeWrapper } from 'hbh-nodes';3TrackTimeWrapper.formatDuration(65000);    // "1 min 5 sec"4TrackTimeWrapper.formatDuration(3600000);  // "1 hr 0 sec"
          
        

✨ Features

• Converts milliseconds to weeks, days, hours, minutes, seconds
• Clean output for logs & CLIs
• Zero dependencies

---

⏱️ TrackTimeWrapper.Wrapper(asyncFn, ...args)

Wrap any async function and return its execution time.

          
            1import { TrackTimeWrapper } from 'hbh-nodes';3async function task() {4  await new Promise(res => setTimeout(res, 1200));5  return 'Done';6}8const { result, duration } =9  await TrackTimeWrapper.Wrapper(task);11console.log(result);   // "Done"12console.log(duration); // "1 sec"
          
        

✨ Features

• Measures async function runtime
• Returns { result, duration }
• Internally uses TrackTimeWrapper.formatDuration
• Ideal for benchmarking & performance logs

---

💡 When to Use

• CLI tools
• Performance measurement
• Async task monitoring
• Developer debugging

---

📚 StringArrayManager

A robust class for managing arrays of strings with full support for validation, undo/redo, event handling, logging, and utility operations like search, pagination, and merging. It enforces uniqueness and optional case-insensitivity.

---

Import

          
            1import { StringArrayManager } from "hbh-nodes";
          
        

---

Constructor

          
            1new StringArrayManager(initialArray = [], options = {})
          
        

Parameters:

• initialArray – Optional array of strings to initialize.
• options – Optional configuration object:

Example:

          
            1const manager = new StringArrayManager(["apple", "banana"], { caseInsensitive: true });
          
        

---

Events

Subscribe to events emitted during operations:

          
            1manager.on("add", ({ value }) => console.log("Added:", value));2manager.on("remove", ({ value }) => console.log("Removed:", value));3manager.off("add", callback); // Remove listener
          
        

Available events include: add, remove, replace, delete, clear, reset, sort, undo, redo, merge, addBulk, removeBulk.

---

Adding & Removing Strings

add(value)

Adds a single string if valid, unique, and within limits.

          
            1manager.add("orange");
          
        

addBulk(values)

Adds multiple strings with detailed results for added and skipped items.

          
            1manager.addBulk(["kiwi", "pear", "apple"]);
          
        

remove(value) / removeBulk(values)

Remove single or multiple strings.

          
            1manager.remove("banana");2manager.removeBulk(["kiwi", "apple"]);
          
        

replace(oldValue, newValue)

Replace a string with a new one (valid & unique).

          
            1manager.replace("apple", "grape");
          
        

delete(index)

Remove by index.

          
            1manager.delete(0);
          
        

---

Array Utilities

sortManual(compareFn)

Sort array manually, optionally using a comparator.

          
            1manager.sortManual(); // Default lexicographical2manager.sortManual((a, b) => a.length - b.length);
          
        

search(pattern)

Search strings using a substring or regex.

          
            1manager.search("app");         // substring search2manager.search(/^g/);          // regex search
          
        

clear() / reset(initialArray)

Clear all strings or reset to a new array.

          
            1manager.clear();2manager.reset(["pear", "melon"]);
          
        

getAll() / length() / stats()

Retrieve array, length, or statistics (longest, shortest, average length).

          
            1manager.getAll();2manager.length();3manager.stats();
          
        

---

Undo / Redo

          
            1manager.undo();2manager.redo();
          
        

Supports undoing any change with full history up to maxHistory.

---

Logging

          
            1manager.enableLogging(true);2manager.getLog();
          
        

Tracks operations with timestamps and details.

---

Validation

Custom validation function:

          
            1manager.setValidation(val => val.length > 3 && /^[a-z]+$/.test(val));
          
        

---

JSON Serialization

          
            1const json = manager.toJSON();2manager.fromJSON(json);
          
        

---

Utility Methods

• has(value) – Check if value exists.
• get(index) – Get value by index.
• indexOf(value) – Find index of value.
• clone() – Create a new instance with same array and options.
• diff(prevArray) – Compare current array with a previous array (added/removed).
• merge(values) – Merge multiple strings with duplicate/limit handling.
• getPage(pageNum, pageSize) – Paginate array.

---

Example Usage

          
            1const manager = new StringArrayManager(["apple", "banana"], { caseInsensitive: true });3// Add strings4manager.add("Cherry");5manager.addBulk(["Date", "Fig"]);7// Remove strings8manager.remove("banana");10// Replace strings11manager.replace("apple", "Apricot");13// Undo / Redo14manager.undo();15manager.redo();17// Search18manager.search(/a/i);20// Pagination21manager.getPage(1, 2);23// Stats24manager.stats();26// Event listening27manager.on("add", ({ value }) => console.log("Added:", value));29// Logging30manager.enableLogging(true);31console.log(manager.getLog());
          
        

---

StringArrayManager is ideal for managing dynamic lists of strings with full control, safe operations, history tracking, and extensibility.

---

🖥️ wrapCLI

A lightweight wrapper for creating CLI (Command-Line Interface) commands in Node.js, with automatic argument parsing, type conversion, help support, and async handling.

---

Overview

wrapCLI allows you to wrap a regular JavaScript function and run it as a CLI command. It:

• Parses command-line arguments (process.argv).
• Supports positional and named arguments.
• Automatically converts argument strings to boolean, number, or string.
• Provides built-in help functionality with aliases.
• Handles async functions and errors gracefully.

---

Functions

1. tryParseValue(value)

Converts string values to their appropriate types.

          
            1tryParseValue("true");    // → true2tryParseValue("false");   // → false3tryParseValue("123.5");   // → 123.54tryParseValue("hello");   // → "hello"
          
        

• Booleans (true / false)
• Numbers (parseFloat) if numeric
• Strings otherwise

---

2. parseArgs(argv)

Parses an array of CLI arguments into positional and named arguments.

Example:

          
            1node cli.js foo bar --count 3 --verbose true
          
        

Output:

          
            1{2  positional: ["foo", "bar"],3  named: { count: 3, verbose: true }4}
          
        

Behavior:

• --key value becomes named[key] = value.
• Multiple values after a flag become an array.
• Flag with no value → true.
• Single-value arrays are simplified to a single value.

---

3. showHelp(meta)

Displays a help message using a metadata object.

          
            1const meta = {2  description: "Example CLI tool",3  args: [{ name: "input", type: "string", required: true }],4  named: [{ name: "verbose", type: "boolean" }]5};7showHelp(meta);
          
        

Output:

📘 Example CLI tool

Positional arguments:
  input (required) <string> — 

Named options:
  --verbose <boolean> — 

Use "--help" to show this message.

---

4. wrapCLI(fn, meta, aliases)

Wraps a JavaScript function fn as a CLI command.

          
            1import { wrapCLI } from 'hbh-nodes';3function greet(name, options) {4  const prefix = options?.loud ? "HELLO" : "Hello";5  return `${prefix} ${name}!`;6}8const cli = wrapCLI(greet, {9  description: "Greet someone",10  args: [{ name: "name", type: "string", required: true }],11  named: [{ name: "loud", type: "boolean" }]12});14cli(); // Run from Node.js
          
        

Features:

• Checks for help flags (--help or -h) via aliases.
• Spreads positional arguments to the function.
• Optionally passes named arguments as the last object.
• Handles async functions automatically.
• Catches exceptions and logs errors.

---

Example Usage

          
            1# Positional argument2node cli.js Alice4# Named argument5node cli.js Alice --loud true7# Help8node cli.js --help9node cli.js -h
          
        

---

Notes

• Named arguments repeated are collected as arrays.
• tryParseValue automatically converts numeric and boolean strings.
• Help output is fully customizable via the meta object.

---

This wrapper is perfect for lightweight CLI tools without installing external dependencies like yargs or commander.

It keeps argument parsing simple, type-safe, and easy to extend with aliases or async handlers.

---

🧪 Environment Support

• Node.js 18+
• ES Modules only

---

📄 License

ISC

---

✍️ Author

HBH

---

💖 Final Words

HBH-Nodes is built for developers who value control, readability, and long-term maintainability.

If you like tools that stay out of your way, this package is for you ✨