https://github.com/vitorluizc/persistence
💾 Persistence provides a pretty easy API to handle Storage's implementations.
https://github.com/vitorluizc/persistence
ava bili indexeddb javascript localstorage sessionstorage storage storage-engine typescript
Last synced: 6 months ago
JSON representation
💾 Persistence provides a pretty easy API to handle Storage's implementations.
- Host: GitHub
- URL: https://github.com/vitorluizc/persistence
- Owner: VitorLuizC
- License: mit
- Created: 2019-01-16T20:31:00.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2021-08-11T04:33:05.000Z (about 4 years ago)
- Last Synced: 2025-04-09T06:35:46.309Z (6 months ago)
- Topics: ava, bili, indexeddb, javascript, localstorage, sessionstorage, storage, storage-engine, typescript
- Language: TypeScript
- Homepage:
- Size: 612 KB
- Stars: 19
- Watchers: 2
- Forks: 1
- Open Issues: 9
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# `@vitorluizc/persistence`
[](https://travis-ci.org/VitorLuizC/persistence)
[](./LICENSE)
[](https://bundlephobia.com/result?p=@vitorluizc/persistence)
[](https://bundlephobia.com/result?p=@vitorluizc/persistence)
Persistence provides a pretty easy API to handle Storage's implementations.
- :zap: Pretty fast and **smaller than 0.3KB** (minified + gzipped ESM);
- :label: Type definitions to TS developers and IDE/Editors autocomplete/intellisense;
- :package: ESM, CommonJS and UMD distributions (CDN uses UMD as default);
## Installation
This library is published in the NPM registry and can be installed using any compatible package manager.
```sh
npm install @vitorluizc/persistence --save
# For Yarn, use the command below.
yarn add @vitorluizc/persistence
```
### Installation from CDN
This module has an UMD bundle available through JSDelivr and Unpkg CDNs.
```html
// module will be available through `persistence` function.
var name = persistence('name', { placeholder: 'Unknown' });
name.get();
//=> 'Unknown'
```
## Usage
It exports a factory function to create persistence. A persistence can easily `set`, `get` and `delete` JSON parseable values to any `Storage` implementation (ex. `SessionStorage` and `LocalStorage`).
```ts
import createPersistence from '@vitorluizc/persistence';
const persistence = createPersistence('Name', {
timeout: 1000 * 60 * 60 * 24, // A day in milliseconds
storage: window.sessionStorage,
placeholder: ''
});
// Setups field's value as a persistent state on session.
const field = document.querySelector('input[name="name"]');
field.value = persistence.get();
field.addEventListener('input', () => persistence.set(field.value));
```
## API
- **`createPersistence`**
The default exported factory function. It receives storage's key and, optionally, **`PersistenceOptions`** as arguments and returns a **`Persistence`**.
```js
import createPersistence from '@vitorluizc/persistence';
const persistence = createPersistence('Storage\'s key', { placeholder: 'None' });
```
TypeScript type definitions.
```ts
declare const createPersistence: {
(
name: string,
options: PersistenceOptions & {
placeholder: U;
}
): Persistence;
(
name: string,
options?: PersistenceOptions
): Persistence;
};
export default createPersistence;
```
- **`PersistenceOptions`**
Options used as second argument on **`createPersistence`** to set timeout, storage and placeholder value to **`Persistence`**.
```ts
import createPersistence, { PersistenceOptions } from '@vitorluizc/persistence';
const options: PersistenceOptions = {
timeout: 1000 * 60 * 60, // 1 hour in milliseconds.
placeholder: false
};
const persistence = createPersistence('isSignedIn', options);
```
TypeScript type definitions.
```ts
export interface PersistenceOptions {
storage?: IStorage;
timeout?: number;
placeholder?: T;
}
```
- **`Persistence`**
An object with a pretty easy API to handle a Storage implementation.
- **`get`**: Get value from persistent storage.
- **`set`**: Set a value to a persistent storage.
- **`delete`**: Delete value from persistent storage.
```tsx
import createPersistence, { Persistence } from '@vitorluizc/persistence';
// ...
type SignUpFormState = { nickname: string, };
const state: Persistence = createPersistence('state@name', {
timeout: 1000 * 60 * 60 * 24, // A day in milliseconds
placeholder: {
nickname: ''
},
});
$nickname.value = state.get().nickname;
$nickname.on('keydown', (e) => state.set({ nickname: e.target.value }));
$signUpForm.on('submit', (e) => {
services.signUp(state.get());
state.delete();
});
```
TypeScript type definitions.
```ts
export interface Persistence {
get (): T | U;
set (value: T): void;
delete (): void;
}
```
## License
Released under [MIT License](./LICENSE).