# browser-keyval-stores

> The browser-keyval-stores package offers a clean and unified API to interact with browser storage mechanisms (localStorage, sessionStorage, and indexedDB) from your applications. It streamlines development and eliminates the need for browser-specific code

Latest version **1.1.0** (published 2026-03-21) · MIT license · 0 weekly downloads

## Install

```sh
npm install browser-keyval-stores
pnpm add browser-keyval-stores
yarn add browser-keyval-stores
bun add browser-keyval-stores
```

## Health

**Score 45/100 (D)** — status: stable.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

## Facts

| | |
|---|---|
| Version | 1.1.0 |
| Published | 2026-03-21 |
| First published | 2025-01-23 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Jesus Graterol |
| Maintainers | jesusgraterol |
| Keywords | browser, database, storage, localstorage, sessionstorage, indexeddb |

## Links

- npm: https://www.npmjs.com/package/browser-keyval-stores
- Repository: https://github.com/jesusgraterol/browser-keyval-stores
- Homepage: https://github.com/jesusgraterol/browser-keyval-stores#readme
- Issues: https://github.com/jesusgraterol/browser-keyval-stores/issues
- npm.io page: https://npm.io/package/browser-keyval-stores

## Alternatives

- [@opentelemetry/exporter-zipkin](https://npm.io/package/@opentelemetry/exporter-zipkin.md) — 14.8M weekly downloads
- [pusher-js](https://npm.io/package/pusher-js.md) — 2.0M weekly downloads
- [browserify](https://npm.io/package/browserify.md) — 1.7M weekly downloads
- [sqs-consumer](https://npm.io/package/sqs-consumer.md) — 1.7M weekly downloads
- [@sanity/eventsource](https://npm.io/package/@sanity/eventsource.md) — 930.8K weekly downloads

## Recent versions

- 1.1.0 (latest) — 2026-03-21
- 1.0.1 — 2025-07-17
- 1.0.0 — 2025-01-23

## README

# Browser KeyVal Stores

The `browser-keyval-stores` package offers a clean and unified API to interact with browser storage mechanisms ([`localStorage`](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage), [`sessionStorage`](https://developer.mozilla.org/en-US/docs/Web/API/Window/sessionStorage), and [`indexedDB`](https://developer.mozilla.org/en-US/docs/Web/API/Window/indexedDB)) from your applications. It streamlines development and eliminates the need for browser-specific code when working with client-side data storage.





</br>

## Getting Started

Install the package:
```bash
npm i -S browser-keyval-stores
```


### Usage

#### `localStorage` Store

```typescript
import { LocalStorageStore } from 'browser-keyval-stores';

type IUserPreferences = {
  language: string,
  theme: string
};

const store = new LocalStorageStore<IUserPreferences>('userPreferences');

const uid = '2d22df80-fc4b-498a-a4a7-734daa71c8dd';

store.get(uid);
// undefined

store.set(uid, { language: 'en', theme: 'dark' });
store.get(uid);
// { language: 'en', theme: 'dark' }

store.set(uid, { language: 'es', theme: 'light' });
store.get(uid);
// { language: 'es', theme: 'light' }

store.del(uid);
store.get(uid);
// undefined
```

#### `sessionStorage` Store

```typescript
import { SessionStorageStore } from 'browser-keyval-stores';

type IApplicationFormData = {
  fullName: string,
  passportNum: string,
};

const store = new SessionStorageStore<IApplicationFormData>('applicationForm');

store.get();
// undefined

store.set(undefined, { fullName: 'Jess Grateol', passportNum: 'P4366918' });
store.get();
// { fullName: 'Jess Grateol', passportNum: 'P4366918' }

store.set(undefined, { fullName: 'Jesus Graterol', passportNum: 'LA080402' });
store.get();
// { fullName: 'Jesus Graterol', passportNum: 'LA080402' }

store.del();
store.get();
// undefined
```

#### `indexedDB` Store

```typescript
import { IndexedDBStore } from 'browser-keyval-stores';

type IBlogPost = {
  id: number,
  title: string,
  content: string,
};

const store = new IndexedDBStore<IBlogPost>('blogPosts');

await store.set(1, { id: 1, title: 'Test title', content: 'This is the ...'});
await store.get(1);
// { id: 1, title: 'Test title', content: 'This is the ...'}

await store.del(1);
await store.get(1);
// undefined
```



### Types

<details>
  <summary><code>IStoreMechanism</code></summary>
  <br/>

  The supported browser storage mechanisms.

  ```typescript
  type IStoreMechanism = 'tempMemory' | 'localStorage' | 'sessionStorage' | 'indexedDB';
  ```
  <br/>
</details>

<details>
  <summary><code>IRecordID</code></summary>
  <br/>

  The identifier used to manage records. The store behaves differently based on the type:

  - `undefined`: the data will be stored at the root of the store
  - `string` | `number`: the value will be coerced into a string and can be used to locate the data
  ```typescript
  type IRecordID = undefined | string | number;
  ```
  <br/>
</details>

<details>
  <summary><code>IWebStorageStore<T></code></summary>
  <br/>

  Object in charge of interacting with the Browser's Storage API. This API is used by [`Window.localStorage`](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage) & [`Window.sessionStorage`](https://developer.mozilla.org/en-US/docs/Web/API/Window/sessionStorage).

  ```typescript
  interface IWebStorageStore<T> {
    // properties
    id: string;

    // methods
    isCompatible: () => boolean;
    get: (id?: IRecordID) => T | undefined;
    set: (id: IRecordID, data: T) => void;
    del: (id?: IRecordID) => void;
  }

  interface ILocalStorageStore<T> extends IWebStorageStore<T> {
    // ...
  }

  interface ISessionStorageStore<T> extends IWebStorageStore<T> {
    // ...
  }
  ```
  <br/>
</details>

<details>
  <summary><code>IIndexedDBStore<T></code></summary>
  <br/>

  Object in charge of charge of interacting with the Browser's `IndexedDB` implementation.
  ```typescript
  interface IIndexedDBStore<T> {
    // properties
    id: string;

    // methods
    isCompatible(): Promise<boolean>;
    get: (id?: IRecordID) => Promise<T | undefined>;
    set: (id: IRecordID, data: T) => Promise<void>;
    del: (id?: IRecordID) => Promise<void>;
  }
  ```
  <br/>
</details>





<br/>

## Built With

- TypeScript





<br/>

## Running the Tests

```bash
# unit and integration tests
npm run test

# integration tests
npm run test:integration

# unit tests
npm run test:unit
```





<br/>

## License

[MIT](https://choosealicense.com/licenses/mit/)

---
_Source: https://npm.io/package/browser-keyval-stores · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._