# nazmul-nhb/nhb-toolbox architecture

> Architecture diagram of the GitHub repository nazmul-nhb/nhb-toolbox, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nazmul-nhb/nhb-toolbox
- Repository: https://github.com/nazmul-nhb/nhb-toolbox

## Overview

This repository is a **zero-dependency TypeScript utility library** published as **`nhb-toolbox`**. Architecturally, it is a **single package** with many independent utility subsystems, designed for **tree-shaken imports** and **cross-runtime use** in both Node.js and browser environments.

1. **Public entry surface**
   - `src/index.ts` is the main export hub.
   - Most feature areas also have their own module entry files, so consumers can import narrowly from domain folders.
   - `src/types/index.ts` centralizes shared type exports.

2. **Domain-oriented module layout**
   - The library is split into clear feature buckets: `array`, `colors`, `converter`, `date`, `dom`, `form`, `hash`, `http-status`, `number`, `object`, `pluralizer`, `string`, `stylog`, `utils`, `verbalizer`.
   - Each bucket usually contains:
     - a main class or facade when needed,
     - helper functions,
     - constants/types,
     - guards and utility functions.
   - This makes the codebase more like a catalog of small subsystems than one monolithic API.

3. **Date/time is the most complex subsystem**
   - `src/date/Chronos.ts` is the primary date engine, backed by helper files for parsing, guards, constants, timezone logic, seasons, and plugins.
   - Plugin files under `src/date/plugins/` add optional capabilities such as business-day logic, duration, relative time, rounding, zodiac, timezone, palindrome checks, and Bangla-specific behavior.
   - `src/date/BanglaCalendar.ts` is a separate calendar conversion subsystem, reflecting the repo’s split between Gregorian and Bangla date handling.
   - Data flow here is: input string/Date/value → parse/normalize → core Chronos or BanglaCalendar model → formatting/calculation/plugin output.

4. **Numeric and conversion utilities form a second major core**
   - `src/number/` contains arithmetic and domain helpers like currency, unit conversion, percent, prime, fibonacci, ranges, and number-to-words style conversion support.
   - `src/converter/` is a more structured measurement-conversion subsystem with categories such as length, mass, volume, area, time, temperature, and base conversion.
   - This split suggests two levels: “general number utilities” versus “dimension/unit conversion engine.”

5. **String, pluralization, and verbalization are language-oriented subsystems**
   - `src/string/` covers case transforms, anagrams, diffs, basic string utilities, and conversion helpers.
   - `src/pluralizer/` and `src/verbalizer/` are rule-based engines, each with dedicated rule/type files.
   - The README examples show these subsystems are meant to handle English-language transformations and human-readable formatting.

6. **Data shaping and validation utilities are a core architectural pattern**
   - `src/guards/`, `src/object/`, `src/form/`, and parts of `src/utils/` handle inspection, sanitization, and conversion of runtime values.
   - These modules likely underpin many of the higher-level utilities by normalizing inputs before transformation.
   - `src/form/convert.ts` and `src/object/sanitize.ts` indicate a strong emphasis on preparing objects for transport or safe use.

7. **Array, color, and DOM helpers are standalone utility clusters**
   - `src/array/` provides collection operations like search, filtering, sorting, deduplication, and transformation.
   - `src/colors/` handles color parsing, conversion, CSS color constants, random/initial-based palette generation, and utility math.
   - `src/dom/` is a small browser-facing boundary for querying, storage, and related helpers, implying the library is not Node-only.

8. **Hashing, IDs, and text codecs handle low-level encoding concerns**
   - `src/hash/` contains crypto-like helpers such as `Cipher`, `Signet`, `TextCodec`, UUID generation, and core helper logic.
   - These modules are isolated from the rest of the repo and represent a low-level utility boundary for encoding, signing, and identifier generation.

9. **Presentation utilities are separated from pure data utilities**
   - `src/stylog/` is a console styling subsystem that works in both Node and browser contexts.
   - Its dedicated constants/helpers suggest a wrapper layer around output formatting rather than a general-purpose logging framework.
   - This subsystem is user-facing but still self-contained, keeping UI-ish behavior out of the pure transformation modules.

10. **Cross-cutting support code is centralized**
   - Shared runtime checks live in `src/guards/`.
   - Shared constants live in `src/constants.ts` and feature-level constants files.
   - Shared utility code appears in `src/utils/` and similar `helpers.ts` files across folders.
   - This pattern keeps repeated logic out of the feature modules and helps preserve independent boundaries.

11. **Testing mirrors the module structure**
   - `__tests__/` is organized by feature area, matching the source layout closely.
   - This indicates the package is tested as a set of independent utility contracts rather than through a single application flow.
   - The presence of many date, string, array, color, hash, number, and stylog tests confirms each subsystem is meant to be consumed directly.

12. **Build, quality, and release pipeline**
   - The repo uses **TypeScript** with multiple tsconfig targets: `tsconfig.esm.json`, `tsconfig.cjs.json`, and `tsconfig.dts.json`, indicating separate ESM, CommonJS, and type-definition outputs.
   - `jest.config.ts` drives testing, while `biome.json` suggests lint/format enforcement.
   - `.husky/pre-commit` implies pre-commit checks.
   - `.github/workflows/publish.yml` is the release pipeline for publishing to **npm**, so GitHub Actions is the main CI/CD boundary.

13. **Non-production and archival areas**
   - `__dump__/` and `__ideas__/` contain historical data, experiments, scrapers, and discarded implementations.
   - These folders are useful for understanding provenance and roadmap, but they are not part of the main runtime architecture.
   - For diagramming, they should be treated as excluded reference material.

Overall, the architecture is best drawn as a **single published utility package** with many **independent feature modules**, shared guard/helper layers, a **rich date/time plugin system**, and a **TypeScript build/test/release pipeline** around it.

Main entry points: [`src/index.ts`](https://github.com/nazmul-nhb/nhb-toolbox/blob/main/src/index.ts) (Index), [`src/date/Chronos.ts`](https://github.com/nazmul-nhb/nhb-toolbox/blob/main/src/date/Chronos.ts) (Date), [`src/types/index.ts`](https://github.com/nazmul-nhb/nhb-toolbox/blob/main/src/types/index.ts) (Types), [`src/string/basics.ts`](https://github.com/nazmul-nhb/nhb-toolbox/blob/main/src/string/basics.ts) (String)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_public["Public API"]
  node_src_index["Index<br/>export hub<br/>[index.ts]"]
  node_src_types_index["Types<br/>[index.ts]"]
end

subgraph group_core["Core Utilities"]
  node_src_utils_index["Utils<br/>utility hub<br/>[index.ts]"]
  node_src_array["Array<br/>collection utils<br/>[basics.ts]"]
  node_src_object["Object<br/>[basics.ts]"]
  node_src_form["Form<br/>[convert.ts]"]
  node_src_number["Number<br/>numeric utils<br/>[basics.ts]"]
  node_src_converter["Converter<br/>unit engine<br/>[Converter.ts]"]
  node_src_colors["Colors<br/>color utils<br/>[Color.ts]"]
  node_src_hash["Hash<br/>encoding tools<br/>[index.ts]"]
  node_src_http["HTTP Status<br/>status catalog<br/>[HttpStatus.ts]"]
end

subgraph group_time["Date & Time"]
  node_src_date["Date<br/>chronos engine<br/>[Chronos.ts]"]
  node_src_date_bangla["Bangla Cal<br/>calendar conversion<br/>[BanglaCalendar.ts]"]
  node_src_date_plugins["Plugins"]
end

subgraph group_lang["Language Tools"]
  node_src_string["String<br/>text utils<br/>[basics.ts]"]
  node_src_pluralizer["Pluralizer<br/>rule engine<br/>[Pluralizer.ts]"]
  node_src_verbalizer["Verbalizer<br/>text engine<br/>[Verbalizer.ts]"]
end

subgraph group_platform["Platform & Build"]
  node_src_dom["DOM<br/>browser boundary<br/>[index.ts]"]
  node_build_ci{{"Build & CI<br/>toolchain"}}
end

node_src_index -->|"exports"| node_src_types_index
node_src_index -->|"exports"| node_src_utils_index
node_src_index -->|"exports"| node_src_array
node_src_index -->|"exports"| node_src_object
node_src_index -->|"exports"| node_src_form
node_src_index -->|"exports"| node_src_number
node_src_index -->|"exports"| node_src_converter
node_src_index -->|"exports"| node_src_colors
node_src_index -->|"exports"| node_src_hash
node_src_index -->|"exports"| node_src_http
node_src_index -->|"exports"| node_src_date
node_src_index -->|"exports"| node_src_string
node_src_index -->|"exports"| node_src_pluralizer
node_src_index -->|"exports"| node_src_verbalizer
node_src_index -->|"exports"| node_src_dom
node_src_date -->|"uses"| node_src_date_bangla
node_src_date -->|"extends"| node_src_date_plugins
node_src_date -.->|"shared types"| node_src_types_index
node_src_colors -.->|"shared types"| node_src_types_index
node_src_hash -.->|"shared types"| node_src_types_index
node_src_number -.->|"overlaps"| node_src_converter
node_src_object -.->|"feeds"| node_src_form
node_src_string -.->|"text rules"| node_src_pluralizer
node_src_string -.->|"text rules"| node_src_verbalizer
node_src_dom -.->|"browser runtime"| node_build_ci
node_build_ci -->|"package"| node_src_index

click node_src_index "https://github.com/nazmul-nhb/nhb-toolbox/blob/main/src/index.ts"
click node_src_types_index "https://github.com/nazmul-nhb/nhb-toolbox/blob/main/src/types/index.ts"
click node_src_utils_index "https://github.com/nazmul-nhb/nhb-toolbox/blob/main/src/utils/index.ts"
click node_src_array "https://github.com/nazmul-nhb/nhb-toolbox/blob/main/src/array/basics.ts"
click node_src_object "https://github.com/nazmul-nhb/nhb-toolbox/blob/main/src/object/basics.ts"
click node_src_form "https://github.com/nazmul-nhb/nhb-toolbox/blob/main/src/form/convert.ts"
click node_src_number "https://github.com/nazmul-nhb/nhb-toolbox/blob/main/src/number/basics.ts"
click node_src_converter "https://github.com/nazmul-nhb/nhb-toolbox/blob/main/src/converter/Converter.ts"
click node_src_colors "https://github.com/nazmul-nhb/nhb-toolbox/blob/main/src/colors/Color.ts"
click node_src_hash "https://github.com/nazmul-nhb/nhb-toolbox/blob/main/src/hash/index.ts"
click node_src_http "https://github.com/nazmul-nhb/nhb-toolbox/blob/main/src/http-status/HttpStatus.ts"
click node_src_date "https://github.com/nazmul-nhb/nhb-toolbox/blob/main/src/date/Chronos.ts"
click node_src_date_bangla "https://github.com/nazmul-nhb/nhb-toolbox/blob/main/src/date/BanglaCalendar.ts"
click node_src_date_plugins "https://github.com/nazmul-nhb/nhb-toolbox/tree/main/src/date/plugins"
click node_src_string "https://github.com/nazmul-nhb/nhb-toolbox/blob/main/src/string/basics.ts"
click node_src_pluralizer "https://github.com/nazmul-nhb/nhb-toolbox/blob/main/src/pluralizer/Pluralizer.ts"
click node_src_verbalizer "https://github.com/nazmul-nhb/nhb-toolbox/blob/main/src/verbalizer/Verbalizer.ts"
click node_src_dom "https://github.com/nazmul-nhb/nhb-toolbox/blob/main/src/dom/index.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_src_index,node_src_types_index toneBlue
class node_src_utils_index,node_src_array,node_src_object,node_src_form,node_src_number,node_src_converter,node_src_colors,node_src_hash,node_src_http toneAmber
class node_src_date,node_src_date_bangla,node_src_date_plugins toneMint
class node_src_string,node_src_pluralizer,node_src_verbalizer toneRose
class node_src_dom,node_build_ci toneIndigo
```

## Components

### Public API

Package entry points and shared exports

- [Index](https://github.com/nazmul-nhb/nhb-toolbox/blob/main/src/index.ts): export hub · Main package entry surface that re-exports the library APIs · `src/index.ts`
- [Types](https://github.com/nazmul-nhb/nhb-toolbox/blob/main/src/types/index.ts): shared types · Central shared type exports · `src/types/index.ts`

### Core Utilities

General-purpose data, numeric, encoding, and text helpers

- [Utils](https://github.com/nazmul-nhb/nhb-toolbox/blob/main/src/utils/index.ts): utility hub · Shared utility entry with paginator and extra helpers · `src/utils/index.ts`
- [Array](https://github.com/nazmul-nhb/nhb-toolbox/blob/main/src/array/basics.ts): collection utils · Array search, filtering, sorting, deduping, and transforms · `src/array/basics.ts`
- [Object](https://github.com/nazmul-nhb/nhb-toolbox/blob/main/src/object/basics.ts): object utils · Object shaping, conversion, sanitization, and country helpers · `src/object/basics.ts`
- [Form](https://github.com/nazmul-nhb/nhb-toolbox/blob/main/src/form/convert.ts): value transform · Normalization and conversion helpers for form-like data · `src/form/convert.ts`
- [Number](https://github.com/nazmul-nhb/nhb-toolbox/blob/main/src/number/basics.ts): numeric utils · Arithmetic, ranges, primes, currency, and number helpers · `src/number/basics.ts`
- [Converter](https://github.com/nazmul-nhb/nhb-toolbox/blob/main/src/converter/Converter.ts): unit engine · Structured measurement conversion across units and bases · `src/converter/Converter.ts`
- [Colors](https://github.com/nazmul-nhb/nhb-toolbox/blob/main/src/colors/Color.ts): color utils · Color parsing, conversion, CSS colors, and palette helpers · `src/colors/Color.ts`
- [Hash](https://github.com/nazmul-nhb/nhb-toolbox/blob/main/src/hash/index.ts): encoding tools · Cipher, signing, text codec, and UUID helpers · `src/hash/index.ts`
- [HTTP Status](https://github.com/nazmul-nhb/nhb-toolbox/blob/main/src/http-status/HttpStatus.ts): status catalog · HTTP status constants and lookup helpers · `src/http-status/HttpStatus.ts`

### Date & Time

Chronos engine, calendar conversion, and plugins

- [Date](https://github.com/nazmul-nhb/nhb-toolbox/blob/main/src/date/Chronos.ts): chronos engine · Main date/time subsystem with parsing, formatting, and plugins · `src/date/Chronos.ts`
- [Bangla Cal](https://github.com/nazmul-nhb/nhb-toolbox/blob/main/src/date/BanglaCalendar.ts): calendar conversion · Bangla calendar conversion and date model · `src/date/BanglaCalendar.ts`
- [Plugins](https://github.com/nazmul-nhb/nhb-toolbox/tree/main/src/date/plugins): date plugins · Optional date capabilities such as business days, duration, timezone, and zodiac · `src/date/plugins`

### Language Tools

String, pluralization, and verbalization helpers

- [String](https://github.com/nazmul-nhb/nhb-toolbox/blob/main/src/string/basics.ts): text utils · Case transforms, diffs, anagrams, and string conversion helpers · `src/string/basics.ts`
- [Pluralizer](https://github.com/nazmul-nhb/nhb-toolbox/blob/main/src/pluralizer/Pluralizer.ts): rule engine · Pluralization rules and inflection logic · `src/pluralizer/Pluralizer.ts`
- [Verbalizer](https://github.com/nazmul-nhb/nhb-toolbox/blob/main/src/verbalizer/Verbalizer.ts): text engine · Rule-based human-readable verbalization helpers · `src/verbalizer/Verbalizer.ts`

### Platform & Build

Browser boundary plus TypeScript build and release pipeline

- [DOM](https://github.com/nazmul-nhb/nhb-toolbox/blob/main/src/dom/index.ts): browser boundary · Browser-oriented query and storage helpers · `src/dom/index.ts`
- **Build & CI**: toolchain · TypeScript outputs, testing, linting, hooks, and publish workflow

## Connections

- Index → Types: exports · Main entry re-exports shared types
- Index → Utils: exports · Main entry exposes general utilities
- Index → Array: exports · Public array utilities
- Index → Object: exports · Public object utilities
- Index → Form: exports · Public form helpers
- Index → Number: exports · Public numeric utilities
- Index → Converter: exports · Public unit conversion APIs
- Index → Colors: exports · Public color utilities
- Index → Hash: exports · Public encoding and ID helpers
- Index → HTTP Status: exports · Public HTTP status catalog
- Index → Date: exports · Public date/time engine
- Index → String: exports · Public string utilities
- Index → Pluralizer: exports · Public pluralization engine
- Index → Verbalizer: exports · Public verbalization engine
- Index → DOM: exports · Public browser helpers
- Date → Bangla Cal: uses · Separate calendar conversion path
- Date → Plugins: extends · Optional date behaviors are layered onto the core engine
- Date → Types: shared types · Date subsystem shares central types
- Colors → Types: shared types · Color subsystem shares central types
- Hash → Types: shared types · Hash subsystem shares central types
- Number → Converter: overlaps · General number helpers complement structured unit conversion
- Object → Form: feeds · Object shaping and form conversion are adjacent normalization layers
- String → Pluralizer: text rules · String helpers support inflection and case manipulation
- String → Verbalizer: text rules · String helpers support human-readable wording
- DOM → Build & CI: browser runtime · Browser-facing boundary within the package build
- Build & CI → Index: package · Build and publish pipeline produces the library surface