# asif-mahmud/js-utils architecture

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

- Interactive diagram: https://gitdiagram.com/asif-mahmud/js-utils
- Repository: https://github.com/asif-mahmud/js-utils

## Overview

1. **Repository type**
   - This is a small **TypeScript utility library**, not an application server or frontend app.
   - Its main output is a published npm package: **`@gswag/js-utils`**.

2. **Primary responsibility**
   - The library provides a few focused helpers:
     - `flatten`
     - `unflatten`
     - `numberToBanglaWords`
     - `ObjectType`
   - The README frames it as a general-purpose “collection of some utility functions for javascript/typescript.”

3. **Source-of-truth layer**
   - All authored code lives under **`src/`**.
   - Each utility has its own implementation file, and the package root is wired through **`src/index.ts`** as the public export surface.
   - Tests are colocated in the same folder with `*.spec.ts` files.

4. **Core functional subsystems**
   - **Object structure utilities**: `flatten.ts` and `unflatten.ts` transform nested objects to/from flattened key paths.
   - **Localization/formatting utility**: `number-to-bangla-words.ts` converts numeric values into Bangla words.
   - **Shared typing support**: `object-type.ts` likely defines internal or exported type helpers used by the other modules.

5. **Public API boundary**
   - The package consumer should import from the module entrypoint rather than individual internals.
   - The built entrypoint is mirrored in **`lib/esm/index.js`** and **`lib/esm/index.d.ts`**, which expose the compiled runtime and type definitions.

6. **Build output layer**
   - Compiled artifacts are checked into **`lib/esm/`**.
   - This indicates the repository ships a prebuilt **ES module** distribution, with both JavaScript and `.d.ts` type declarations.
   - The `lib/tsconfig.tsbuildinfo` file suggests TypeScript incremental build caching is used during compilation.

7. **Testing and verification flow**
   - Tests are written with **Jest** and live beside the source in `src/*.spec.ts`.
   - The repository includes **`jest.config.js`**, and the GitHub Actions workflow `test-and-check-coverage.yml` runs tests plus coverage validation.
   - This creates a clear quality gate before changes are accepted.

8. **Documentation generation**
   - The `docs/` directory contains a generated static site with HTML pages for functions and types.
   - `typedoc.json` strongly suggests the docs are produced with **TypeDoc** from the TypeScript sources.
   - The docs are suitable for GitHub Pages hosting, reinforced by the presence of `.nojekyll`.

9. **Package distribution model**
   - `package.json` and `package-lock.json` define the npm package metadata and dependency resolution.
   - The repo is structured to support publishing a library rather than deploying a service: source, tests, generated docs, and precompiled distribution are all present.

10. **Architecture at a glance**
   - Flow is roughly: **TypeScript source in `src/` → test/verify with Jest → compile to `lib/esm/` → publish as npm package → generate static API docs into `docs/`**.
   - GitHub Actions provides CI, and GitHub Pages appears to host the docs.

Main entry points: [`src/index.ts`](https://github.com/asif-mahmud/js-utils/blob/master/src/index.ts) (Public API), [`src`](https://github.com/asif-mahmud/js-utils/tree/master/src) (Specs), [`src/object-type.ts`](https://github.com/asif-mahmud/js-utils/blob/master/src/object-type.ts) (ObjectType), [`package.json`](https://github.com/asif-mahmud/js-utils/blob/master/package.json) (Package manifest)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_source["Source"]
  node_src_index["Public API<br/>ts entrypoint<br/>[index.ts]"]
  node_src_flatten["Flatten<br/>ts util<br/>[flatten.ts]"]
  node_src_unflatten["Unflatten<br/>ts util<br/>[unflatten.ts]"]
  node_src_words["Bangla words<br/>ts util"]
  node_src_object_type["ObjectType<br/>ts types<br/>[object-type.ts]"]
  node_src_tests(("Specs"))
end

subgraph group_distribution["Distribution"]
  node_lib_index["ESM entry<br/>built entrypoint<br/>[index.js]"]
  node_lib_flatten["Built utils<br/>esm modules<br/>[flatten.js]"]
  node_lib_types["Type defs<br/>d.ts bundle<br/>[index.d.ts]"]
  node_build_cache["Build cache<br/>ts incremental"]
end

subgraph group_docs["Docs"]
  node_docs_index["Docs site<br/>typedoc site<br/>[index.html]"]
  node_docs_funcs["Function docs<br/>typedoc pages<br/>[flatten.html]"]
  node_docs_types["Type docs<br/>typedoc pages<br/>[ObjectType.html]"]
  node_typedoc_cfg["TypeDoc config<br/>docs config<br/>[typedoc.json]"]
end

subgraph group_quality["Quality"]
  node_jest_cfg["Jest config<br/>test config<br/>[jest.config.js]"]
  node_ci_workflow["CI workflow<br/>github actions"]
end

subgraph group_package["Package"]
  node_pkg_manifest["Package manifest<br/>npm metadata<br/>[package.json]"]
  node_pkg_lock["Lockfile<br/>[package-lock.json]"]
  node_tsconfig["TS config<br/>[tsconfig.json]"]
end

node_src_index -->|"exports"| node_src_flatten
node_src_index -->|"exports"| node_src_unflatten
node_src_index -->|"exports"| node_src_words
node_src_index -->|"exports"| node_src_object_type
node_src_flatten -->|"uses"| node_src_object_type
node_src_unflatten -->|"uses"| node_src_object_type
node_src_tests -.->|"tests"| node_src_flatten
node_src_tests -.->|"tests"| node_src_unflatten
node_src_tests -.->|"tests"| node_src_words
node_src_tests -.->|"covers"| node_src_object_type
node_src_index -->|"builds to"| node_lib_index
node_src_flatten -->|"builds to"| node_lib_flatten
node_src_unflatten -->|"builds to"| node_lib_flatten
node_src_words -->|"builds to"| node_lib_flatten
node_src_object_type -->|"builds to"| node_lib_types
node_typedoc_cfg -->|"generates"| node_docs_index
node_src_index -->|"documents"| node_docs_funcs
node_src_object_type -->|"documents"| node_docs_types
node_jest_cfg -->|"runs"| node_src_tests
node_ci_workflow -->|"uses"| node_jest_cfg
node_ci_workflow -.->|"verifies"| node_src_tests
node_pkg_manifest -->|"publishes"| node_src_index
node_pkg_manifest -->|"packages"| node_lib_index
node_pkg_manifest -->|"packages"| node_lib_types
node_pkg_manifest -->|"pins"| node_pkg_lock
node_tsconfig -->|"compiles"| node_src_index
node_tsconfig -.->|"caches"| node_build_cache

click node_src_index "https://github.com/asif-mahmud/js-utils/blob/master/src/index.ts"
click node_src_flatten "https://github.com/asif-mahmud/js-utils/blob/master/src/flatten.ts"
click node_src_unflatten "https://github.com/asif-mahmud/js-utils/blob/master/src/unflatten.ts"
click node_src_words "https://github.com/asif-mahmud/js-utils/blob/master/src/number-to-bangla-words.ts"
click node_src_object_type "https://github.com/asif-mahmud/js-utils/blob/master/src/object-type.ts"
click node_src_tests "https://github.com/asif-mahmud/js-utils/tree/master/src"
click node_lib_index "https://github.com/asif-mahmud/js-utils/blob/master/lib/esm/index.js"
click node_lib_flatten "https://github.com/asif-mahmud/js-utils/blob/master/lib/esm/flatten.js"
click node_lib_types "https://github.com/asif-mahmud/js-utils/blob/master/lib/esm/index.d.ts"
click node_build_cache "https://github.com/asif-mahmud/js-utils/blob/master/lib/tsconfig.tsbuildinfo"
click node_docs_index "https://github.com/asif-mahmud/js-utils/blob/master/docs/index.html"
click node_docs_funcs "https://github.com/asif-mahmud/js-utils/blob/master/docs/functions/flatten.html"
click node_docs_types "https://github.com/asif-mahmud/js-utils/blob/master/docs/types/ObjectType.html"
click node_typedoc_cfg "https://github.com/asif-mahmud/js-utils/blob/master/typedoc.json"
click node_jest_cfg "https://github.com/asif-mahmud/js-utils/blob/master/jest.config.js"
click node_ci_workflow "https://github.com/asif-mahmud/js-utils/blob/master/.github/workflows/test-and-check-coverage.yml"
click node_pkg_manifest "https://github.com/asif-mahmud/js-utils/blob/master/package.json"
click node_pkg_lock "https://github.com/asif-mahmud/js-utils/blob/master/package-lock.json"
click node_tsconfig "https://github.com/asif-mahmud/js-utils/blob/master/tsconfig.json"

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_flatten,node_src_unflatten,node_src_words,node_src_object_type,node_src_tests toneBlue
class node_lib_index,node_lib_flatten,node_lib_types,node_build_cache toneAmber
class node_docs_index,node_docs_funcs,node_docs_types,node_typedoc_cfg toneMint
class node_jest_cfg,node_ci_workflow toneRose
class node_pkg_manifest,node_pkg_lock,node_tsconfig toneIndigo
```

## Components

### Source

Authored TypeScript utilities and test colocations.

- [Public API](https://github.com/asif-mahmud/js-utils/blob/master/src/index.ts): ts entrypoint · Main export surface for package consumers. · `src/index.ts`
- [Flatten](https://github.com/asif-mahmud/js-utils/blob/master/src/flatten.ts): ts util · Transforms nested objects into flattened key paths. · `src/flatten.ts`
- [Unflatten](https://github.com/asif-mahmud/js-utils/blob/master/src/unflatten.ts): ts util · Rebuilds nested objects from flattened paths. · `src/unflatten.ts`
- [Bangla words](https://github.com/asif-mahmud/js-utils/blob/master/src/number-to-bangla-words.ts): ts util · Converts numbers into Bangla words. · `src/number-to-bangla-words.ts`
- [ObjectType](https://github.com/asif-mahmud/js-utils/blob/master/src/object-type.ts): ts types · Shared object typing helpers used by the utilities. · `src/object-type.ts`
- [Specs](https://github.com/asif-mahmud/js-utils/tree/master/src): jest specs · Colocated test files validating the utility behavior. · `src`

### Distribution

Prebuilt ESM package artifacts checked into the repo.

- [ESM entry](https://github.com/asif-mahmud/js-utils/blob/master/lib/esm/index.js): built entrypoint · Compiled runtime entrypoint for package consumers. · `lib/esm/index.js`
- [Built utils](https://github.com/asif-mahmud/js-utils/blob/master/lib/esm/flatten.js): esm modules · Compiled JavaScript implementations of the utilities. · `lib/esm/flatten.js`
- [Type defs](https://github.com/asif-mahmud/js-utils/blob/master/lib/esm/index.d.ts): d.ts bundle · Compiled declaration files published with the ESM build. · `lib/esm/index.d.ts`
- [Build cache](https://github.com/asif-mahmud/js-utils/blob/master/lib/tsconfig.tsbuildinfo): ts incremental · TypeScript incremental build metadata. · `lib/tsconfig.tsbuildinfo`

### Docs

Generated TypeDoc site for public API reference.

- [Docs site](https://github.com/asif-mahmud/js-utils/blob/master/docs/index.html): typedoc site · Generated static documentation site. · `docs/index.html`
- [Function docs](https://github.com/asif-mahmud/js-utils/blob/master/docs/functions/flatten.html): typedoc pages · API reference pages for exported functions. · `docs/functions/flatten.html`
- [Type docs](https://github.com/asif-mahmud/js-utils/blob/master/docs/types/ObjectType.html): typedoc pages · API reference page for exported types. · `docs/types/ObjectType.html`
- [TypeDoc config](https://github.com/asif-mahmud/js-utils/blob/master/typedoc.json): docs config · Configuration used to generate the static docs. · `typedoc.json`

### Quality

Test and CI configuration for verification.

- [Jest config](https://github.com/asif-mahmud/js-utils/blob/master/jest.config.js): test config · Jest setup for running the source specs. · `jest.config.js`
- [CI workflow](https://github.com/asif-mahmud/js-utils/blob/master/.github/workflows/test-and-check-coverage.yml): github actions · Runs tests and coverage checks in GitHub Actions. · `.github/workflows/test-and-check-coverage.yml`

### Package

Repository-level build and release metadata.

- [Package manifest](https://github.com/asif-mahmud/js-utils/blob/master/package.json): npm metadata · Package metadata and dependency definitions. · `package.json`
- [Lockfile](https://github.com/asif-mahmud/js-utils/blob/master/package-lock.json): npm lockfile · Pinned dependency resolution for the package. · `package-lock.json`
- [TS config](https://github.com/asif-mahmud/js-utils/blob/master/tsconfig.json): ts config · Compiler configuration for the library build. · `tsconfig.json`

## Connections

- Public API → Flatten: exports · Public entrypoint re-exports flatten.
- Public API → Unflatten: exports · Public entrypoint re-exports unflatten.
- Public API → Bangla words: exports · Public entrypoint re-exports number-to-bangla-words.
- Public API → ObjectType: exports · Public entrypoint re-exports shared types.
- Flatten → ObjectType: uses · Flatten relies on shared object typing.
- Unflatten → ObjectType: uses · Unflatten relies on shared object typing.
- Specs → Flatten: tests · Specs validate flatten behavior.
- Specs → Unflatten: tests · Specs validate unflatten behavior.
- Specs → Bangla words: tests · Specs validate number-to-Bangla-words behavior.
- Specs → ObjectType: covers · Tests indirectly exercise shared typing contracts.
- Public API → ESM entry: builds to · Source entrypoint compiles into the published ESM entry.
- Flatten → Built utils: builds to · Source utility compiles into ESM output.
- Unflatten → Built utils: builds to · Source utility compiles into ESM output.
- Bangla words → Built utils: builds to · Source utility compiles into ESM output.
- ObjectType → Type defs: builds to · Source types compile into declaration files.
- TypeDoc config → Docs site: generates · TypeDoc configuration produces the static docs site.
- Public API → Function docs: documents · TypeDoc renders function API pages from source exports.
- ObjectType → Type docs: documents · TypeDoc renders type reference pages.
- Jest config → Specs: runs · Jest configuration drives the colocated specs.
- CI workflow → Jest config: uses · CI invokes the Jest test setup.
- CI workflow → Specs: verifies · Workflow runs the test suite and coverage checks.
- Package manifest → Public API: publishes · Package manifest exposes the library entrypoint.
- Package manifest → ESM entry: packages · npm package ships the compiled ESM entry.
- Package manifest → Type defs: packages · npm package ships declaration files.
- Package manifest → Lockfile: pins · Lockfile fixes dependency resolution for installs.
- TS config → Public API: compiles · TypeScript configuration drives library compilation.
- TS config → Build cache: caches · Incremental build metadata is produced by the compiler.