nazmul-nhb/nhb-toolbox

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.