# imshihab/esmls architecture

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

- Interactive diagram: https://gitdiagram.com/imshihab/esmls
- Repository: https://github.com/imshihab/esmls

## Overview

1. **Repository shape**
   - This is a very small, single-purpose **TypeScript library**.
   - The entire runtime surface appears to live in `src/index.ts`, with no app, server, or multi-package structure.
   - The package is published/consumed as an **npm module** (`esmls`).

2. **Primary responsibility**
   - The library is a thin abstraction over the browser’s **`localStorage`** API.
   - Its job is to provide a safer, more ergonomic key/value store with automatic serialization, deserialization, and change notifications.

3. **Public API boundary**
   - The documented exports are `get`, `set`, `has`, `del`, and `onChange`.
   - These form the only meaningful external interface; everything else is internal implementation detail.
   - Architecturally, this is a **utility layer** between application code and browser storage.

4. **Data flow: write path**
   - Application code calls `set(key, value)`.
   - The library serializes the value into a string form suitable for `localStorage`.
   - The string is written to the browser storage backend under the given key.

5. **Data flow: read path**
   - Application code calls `get(key, options?)`.
   - The library reads the raw stored string from `localStorage`.
   - It then deserializes/parses the string back into the original JavaScript type where possible.
   - The README shows support for strings, numbers, booleans, dates, arrays, objects, and nested structures.

6. **Defaulting and derived state**
   - `get` can supply a default value when a key is missing.
   - It can also persist that default back into storage when requested.
   - The optional `withSetter` mode returns a value plus a setter closure, which is a convenience boundary for state-like usage.

7. **Change propagation**
   - `onChange(key, callback)` is the reactive subsystem.
   - It listens for storage updates and is explicitly intended to work **across browser tabs/windows**.
   - The cleanup function it returns indicates listener lifecycle management is part of the design.

8. **Storage semantics**
   - `has` and `del` are simple key-level utilities around presence checking and removal.
   - Together with `get`/`set`, they make the library a complete localStorage façade rather than just a serializer.

9. **Runtime and environment boundary**
   - This is a **browser-only** library because it depends on `localStorage` and the `storage` event.
   - It is not designed as a server-side component, and SSR would need guarding around access to `window`/`localStorage`.

10. **Integration style**
   - The README shows direct vanilla JS usage and a React example, but React is not a dependency of the library itself.
   - That means the architecture is framework-agnostic: it can be embedded into any client code that runs in a browser.

11. **Build/package tooling**
   - The presence of `tsconfig.json` and lockfile indicates a TypeScript-based package build/publish workflow.
   - No separate infrastructure, API service, or database is part of the architecture.

12. **Diagramming takeaway**
   - The clean architecture view is:
     - **App code** on one side,
     - **esmLS library** in the middle,
     - **browser localStorage + storage events** as the backing platform on the other side.
   - The library’s core value is serialization, typed retrieval, default handling, and cross-tab change observation.

Main entry points: [`src/index.ts`](https://github.com/imshihab/esmls/blob/main/src/index.ts) (src/index.ts), [`README.md`](https://github.com/imshihab/esmls/blob/main/README.md) (README.md), [`package.json`](https://github.com/imshihab/esmls/blob/main/package.json) (package.json), [`tsconfig.json`](https://github.com/imshihab/esmls/blob/main/tsconfig.json) (tsconfig.json)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Consumers"]
  node_app["App code<br/>consumer"]
end

subgraph group_library["esmLS"]
  node_module["src/index.ts<br/>entry module<br/>[index.ts]"]
  node_get(("get<br/>read api<br/>[index.ts]"))
  node_set(("set<br/>write api<br/>[index.ts]"))
  node_hasdel(("has/del<br/>key api<br/>[index.ts]"))
  node_onchange(("onChange<br/>reactive api<br/>[index.ts]"))
  node_codec{{"Serialize/parse<br/>codec<br/>[index.ts]"}}
  node_defaults{{"Defaults<br/>state helper<br/>[index.ts]"}}
  node_adapter["Storage adapter<br/>backend adapter<br/>[index.ts]"]
end

subgraph group_platform["Browser"]
  node_localstorage[("localStorage<br/>browser store")]
  node_storageevent(("storage event<br/>browser event"))
end

subgraph group_tooling["Package"]
  node_readme["README.md<br/>docs<br/>[README.md]"]
  node_packagejson["package.json<br/>package manifest<br/>[package.json]"]
  node_tsconfig["tsconfig.json<br/>ts config<br/>[tsconfig.json]"]
end

node_app -->|"read"| node_get
node_app -->|"write"| node_set
node_app -->|"check/remove"| node_hasdel
node_app -->|"subscribe"| node_onchange
node_get -->|"uses"| node_module
node_set -->|"uses"| node_module
node_hasdel -->|"uses"| node_module
node_onchange -->|"uses"| node_module
node_module -->|"calls"| node_codec
node_module -->|"calls"| node_defaults
node_module -->|"delegates"| node_adapter
node_adapter -->|"reads/writes"| node_localstorage
node_onchange -->|"listens"| node_storageevent
node_storageevent -.->|"reflects"| node_localstorage
node_readme -.->|"documents"| node_get
node_readme -.->|"documents"| node_set
node_readme -.->|"documents"| node_onchange
node_packagejson -.->|"exports"| node_module
node_tsconfig -.->|"builds"| node_module

click node_module "https://github.com/imshihab/esmls/blob/main/src/index.ts"
click node_get "https://github.com/imshihab/esmls/blob/main/src/index.ts"
click node_set "https://github.com/imshihab/esmls/blob/main/src/index.ts"
click node_hasdel "https://github.com/imshihab/esmls/blob/main/src/index.ts"
click node_onchange "https://github.com/imshihab/esmls/blob/main/src/index.ts"
click node_codec "https://github.com/imshihab/esmls/blob/main/src/index.ts"
click node_defaults "https://github.com/imshihab/esmls/blob/main/src/index.ts"
click node_adapter "https://github.com/imshihab/esmls/blob/main/src/index.ts"
click node_readme "https://github.com/imshihab/esmls/blob/main/README.md"
click node_packagejson "https://github.com/imshihab/esmls/blob/main/package.json"
click node_tsconfig "https://github.com/imshihab/esmls/blob/main/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_app toneBlue
class node_module,node_get,node_set,node_hasdel,node_onchange,node_codec,node_defaults,node_adapter toneAmber
class node_localstorage,node_storageevent toneMint
class node_readme,node_packagejson,node_tsconfig toneRose
```

## Components

### Consumers

Application code that imports and uses the library.

- **App code**: consumer · Any browser-side application using the package.

### esmLS

The TypeScript module exposing the storage API and internal helpers.

- [src/index.ts](https://github.com/imshihab/esmls/blob/main/src/index.ts): entry module · Single runtime entry point for the library. · `src/index.ts`
- [get](https://github.com/imshihab/esmls/blob/main/src/index.ts): read api · Reads a key, optionally applying defaults or returning a setter helper. · `src/index.ts`
- [set](https://github.com/imshihab/esmls/blob/main/src/index.ts): write api · Serializes and stores a value under a key. · `src/index.ts`
- [has/del](https://github.com/imshihab/esmls/blob/main/src/index.ts): key api · Checks presence and removes stored keys. · `src/index.ts`
- [onChange](https://github.com/imshihab/esmls/blob/main/src/index.ts): reactive api · Subscribes to storage updates and returns an unsubscribe cleanup. · `src/index.ts`
- [Serialize/parse](https://github.com/imshihab/esmls/blob/main/src/index.ts): codec · Converts between JavaScript values and string storage form. · `src/index.ts`
- [Defaults](https://github.com/imshihab/esmls/blob/main/src/index.ts): state helper · Applies missing-key defaults and optional persistence/withSetter behavior. · `src/index.ts`
- [Storage adapter](https://github.com/imshihab/esmls/blob/main/src/index.ts): backend adapter · Thin boundary around browser storage operations. · `src/index.ts`

### Browser

Browser storage primitives the library wraps.

- **localStorage**: browser store · String key/value persistence backend.
- **storage event**: browser event · Cross-tab/window change notification channel.

### Package

Repository metadata and build configuration.

- [README.md](https://github.com/imshihab/esmls/blob/main/README.md): docs · Documents the public API and usage patterns. · `README.md`
- [package.json](https://github.com/imshihab/esmls/blob/main/package.json): package manifest · NPM package metadata and entry configuration. · `package.json`
- [tsconfig.json](https://github.com/imshihab/esmls/blob/main/tsconfig.json): ts config · TypeScript compilation settings for the library build. · `tsconfig.json`

## Connections

- App code → get: read · Application code requests stored values.
- App code → set: write · Application code persists values.
- App code → has/del: check/remove · Application code inspects or deletes keys.
- App code → onChange: subscribe · Application code listens for updates.
- get → src/index.ts: uses · Public API is implemented in the entry module.
- set → src/index.ts: uses · Public API is implemented in the entry module.
- has/del → src/index.ts: uses · Public API is implemented in the entry module.
- onChange → src/index.ts: uses · Public API is implemented in the entry module.
- src/index.ts → Serialize/parse: calls · Entry module encodes and decodes values.
- src/index.ts → Defaults: calls · Entry module handles missing keys and helper state.
- src/index.ts → Storage adapter: delegates · Entry module delegates storage operations.
- Storage adapter → localStorage: reads/writes · Stores and retrieves string values from browser storage.
- onChange → storage event: listens · Subscribes to browser storage updates.
- storage event → localStorage: reflects · Change notifications correspond to storage mutations.
- README.md → get: documents · README describes read behavior and options.
- README.md → set: documents · README describes write behavior.
- README.md → onChange: documents · README describes cross-tab listeners.
- package.json → src/index.ts: exports · Package entry points to the library module.
- tsconfig.json → src/index.ts: builds · TypeScript compiles the entry module.