Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/jesusgraterol/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 when working with client-side data storage.
https://github.com/jesusgraterol/browser-keyval-stores
browser database indexeddb localstorage sessionstorage storage
Last synced: 1 day ago
JSON representation
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 when working with client-side data storage.
- Host: GitHub
- URL: https://github.com/jesusgraterol/browser-keyval-stores
- Owner: jesusgraterol
- License: mit
- Created: 2025-01-15T12:45:50.000Z (27 days ago)
- Default Branch: main
- Last Pushed: 2025-02-06T18:17:33.000Z (5 days ago)
- Last Synced: 2025-02-06T19:29:47.377Z (5 days ago)
- Topics: browser, database, indexeddb, localstorage, sessionstorage, storage
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/browser-keyval-stores
- Size: 86.9 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
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.
## Getting Started
Install the package:
```bash
npm install -S browser-keyval-stores
```
### Usage
#### `localStorage` Store
```typescript
import { LocalStorageStore } from 'browser-keyval-stores';
type IUserPreferences = {
language: string,
theme: string
};
const store = new LocalStorageStore('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('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('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
IStoreMechanism
The supported browser storage mechanisms.
```typescript
type IStoreMechanism = 'tempMemory' | 'localStorage' | 'sessionStorage' | 'indexedDB';
```
IRecordID
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;
```
IWebStorageStore
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 {
// properties
id: string;
// methods
isCompatible: () => boolean;
get: (id?: IRecordID) => T | undefined;
set: (id: IRecordID, data: T) => void;
del: (id?: IRecordID) => void;
}
interface ILocalStorageStore extends IWebStorageStore {
// ...
}
interface ISessionStorageStore extends IWebStorageStore {
// ...
}
```
IIndexedDBStore
Object in charge of charge of interacting with the Browser's `IndexedDB` implementation.
```typescript
interface IIndexedDBStore {
// properties
id: string;
// methods
isCompatible(): Promise;
get: (id?: IRecordID) => Promise;
set: (id: IRecordID, data: T) => Promise;
del: (id?: IRecordID) => Promise;
}
```
## Built With
- TypeScript
## Running the Tests
```bash
# integration tests
npm run test:integration
# unit tests
npm run test:unit
```
## License
[MIT](https://choosealicense.com/licenses/mit/)
## Deployment
Install dependencies:
```bash
npm install
```
Build the library:
```bash
npm start
```
Publish to `npm`:
```bash
npm publish
```