🌟 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

npm install hbh-nodes

import * as HBH from 'hbh-nodes';

Or selective imports:

import { 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

👁️ chokidar — Deep Object Change Observer

⚠️ Important: This is NOT a filesystem watcher.

chokidar in HBH-Nodes is a reactive state observer built using JavaScript Proxy.

✨ What it Observes

✅ Objects ✅ Arrays ✅ Maps ✅ Sets

Nested structures are automatically tracked.

📡 Supported Events

| Event | Description | | --------- | ------------------------- | | set | Property added or updated | | delete | Property deleted | | push | Array push | | pop | Array pop | | shift | Array shift | | unshift | Array unshift | | splice | Array splice | | clear | Map / Set cleared |

Each event provides:

• 📍 Full path (user.profile.name)
• 📥 New value
• 📦 Old value

🧪 Example

import { chokidar } from 'hbh-nodes';

const state = chokidar({ user: { name: 'Ali' } });

state.on('set', (path, newVal, oldVal) => {
  console.log(`${path}:`, oldVal, '→', newVal);
});

state.user.name = 'Ahmed';

💡 Use Cases

• Reactive state
• Debugging mutations
• Data validation layers
• Form/state watchers

⚙️ ConcurrencyQueue — Controlled Async Execution

Execute async tasks with a maximum concurrency limit.

🧪 Example

const queue = new ConcurrencyQueue(2);

queue.add(async () => taskA());
queue.add(async () => taskB());
queue.add(async () => taskC());

✨ Features

• FIFO queue
• Promise-based
• Automatic execution
• Prevents overload

🔢 AlphabetNumberConverter

Convert between numbers and alphabetic sequences (Excel-style columns).

AlphabetNumberConverter.toAlphabet(28); // AB
AlphabetNumberConverter.toNumber('AB'); // 28

💡 Use Cases

• Spreadsheet columns
• Human-readable IDs
• Indexing systems

🧮 applyCalc — Math Helpers

Lightweight arithmetic utilities.

applyCalc.add(2, 3);
applyCalc.subtract(10, 4);
applyCalc.multiply(3, 5);
applyCalc.divide(20, 4);

🔄 convertObject — Object Transformer

Safely transform object keys and values.

convertObject(
  { a: 1, b: 2 },
  (key, value) => [key.toUpperCase(), value * 2]
);

📘 generateDocs — Documentation Generator

Automatically generates documentation by analyzing JavaScript files.

generateDocs('./src');

💡 Perfect For

• Internal APIs
• Libraries
• Fast documentation drafts

📣 EventEmitter

Minimal, fast event system.

const emitter = new EventEmitter();

emitter.on('ready', () => console.log('Ready'));
emitter.emit('ready');

🎭 FunctionWrapper — Function Control Utilities

Protect and control function execution.

FunctionWrapper.tryCatch(fn);
FunctionWrapper.once(fn);
FunctionWrapper.debounce(fn, 300);

✨ Features

• Error safety
• Single-run functions
• Rate control

🚦 isMain & runIfMain

Detect if a file is executed directly.

const { runIfMain } = require("./mainCheck");

function main() {
  console.log("Running directly as a script!");
}

runIfMain(null, module, require.main, main);

📂 JsonManager — Safe JSON File Manager

Read/write JSON files safely.

const jm = new JsonManager('data.json');

jm.read();
jm.write({ a: 1 });

✨ Features

• Auto file creation
• Safe parsing
• Clean API

🧵 micromatch (Wrapper)

Simple glob-style pattern matching.

micromatch.isMatch('index.js', '*.js');

📡 P2PMD — Peer-to-Peer Markdown Utilities

Tools for syncing and managing markdown content across systems.

import { P2PMD } from "hbh-nodes";
const { Project2MD } = P2PMD;
await Project2MD({
  exclude: ['package.json', 'node_modules'],
  input: './myProject',
})

📦 JPM — package.json Manager

Read & modify package.json programmatically.

JPM.read();
JPM.bumpPatch();
JPM.bumpMinor();

🧼 Sanitizers

Clean and sanitize input data.

Sanitizers.trim(input);
Sanitizers.escapeHTML(input);
Sanitizers.removeSpecialChars(input);

🗜️ StringCompressor

Compress and decompress strings.

const compressed = StringCompressor.compress('hello world');
const original = StringCompressor.decompress(compressed);

🧺 StringArrayManager (USAM)

Advanced string-array manipulation.

StringArrayManager.unique(['a', 'a', 'b']);
StringArrayManager.sortAsc(['c', 'a', 'b']);

🧰 wrapCLI — CLI Wrapper

Wrap CLI logic with safety and consistency.

wrapCLI(() => {
  console.log('CLI running');
});

✨ Features

• Error handling
• Clean exits
• Perfect for scripts

⏱️ TrackTimeWrapper — Time Utilities

Measure execution time and format durations with ease.

🕒 TrackTimeWrapper.formatDuration(ms)

Convert milliseconds into a human-readable duration string.

import { TrackTimeWrapper } from 'hbh-nodes';

TrackTimeWrapper.formatDuration(65000);    // "1 min 5 sec"
TrackTimeWrapper.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.

import { TrackTimeWrapper } from 'hbh-nodes';

async function task() {
  await new Promise(res => setTimeout(res, 1200));
  return 'Done';
}

const { result, duration } =
  await TrackTimeWrapper.Wrapper(task);

console.log(result);   // "Done"
console.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

🧪 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 ✨