var-persist (1.0.1)
Installation
registry=npm install var-persist@1.0.1"var-persist": "1.0.1"About this package
var-persist
TypeScript: Sync variables with localStorage
Table of Contents
About
Var-Persist is an updated version of webstorage-decorators, a library which saves variables to local or session storage.
This library aims to improve upon the original's limitations by using the new Proxy Object. Improvements include:
- Supports both OOP & Decorator patterns
- Proxy object ensures all changes are tracked including impure functions
- [Proto]types and functions can be preserved by passing the
typeoption
Disclaimer: JavaScript's decorators are currently undergoing changes to the API overseen by TC39 and currently have no support for property decorators. Experimental decorators must be enabled to work properly.
Examples
Using objects:
import {Persist} from 'var-persist';
// Proxy Object (Always access/modify using `.value`):
let theme = new Persist<string>('theme', {default: 'os'});
console.log(theme.value) // Output: os
theme.value = 'light'; // Changes will be synced to localStorage['theme'];
Using decorators:
import {persist} from 'var-persist';
// Using decorators
class Theme {
@persist({key: 'theme', default: 'os'}) current!: string;
}
const theme = new Theme();
console.log(theme.current); // Output: light
theme.current = 'dark'; // You can ommit `.value` when using the decorator
Advanced uses:
import {Persist} from 'var-persist';
// Options are the same for both the persist decorator and object:
let example = new Persist<string[]>('example', {
storage: SessionStorage, // Use a different storage solution
default: [], // Default value if stored value === undefined
type: Array // Ensures [proto]type & methods are restored
});
// Callback when changes are made
example.watch(value => console.log(`Length - ${value.length}`));
example.value = [1, 2, 3];
// Output: Length - 3
example.value.pop(); // Impure changes are saved
// Output: Length - 2
Built With
Setup
Production
Prerequisites
Instructions
- Install persist:
npm i var-persist - Enable decorators inside
tsconfig.json:
{
"compilerOptions": {
"experimentalDecorators": true,
...
},
...
}
- Import & use, see examples above
Development
Prerequisites
Instructions
- Install the dependencies:
npm i - Build library & docs:
npm build - Run unit tests:
npm test
Documentation
Classes
Create a proxy object which wraps your data so any changes can be intercepted & synced with storage.
Your data is stored under the value property and should always be accessed/modified through it.
Example
import {Persist} from 'var-persist'
const theme = new Persist('theme.current', {default: 'os'});
console.log(theme.value); // Output: os
theme.value = 'light'; // Make sure you always use .value to access/modify data
location.reload(); // Simulate refresh
console.log(theme.value); // Output: light
Constructor
Persist<T>(key: string, options?: PersistOptions)
| Argument | Type | Description |
|---|---|---|
key |
string |
Primary key value will be stored under |
options |
PersistOptions<T> |
Configure using PersistOptions |
Properties
| Name | Type | Description |
|---|---|---|
key |
string |
Primary key value will be stored under |
options |
PersistOptions<T> |
Configure using PersistOptions |
value |
T |
Current value |
Methods
clear
Delete value from storage
clear(): void
load
Load value from storage
load(): void
save
Save current value to storage
save(): void
watch
Callback function which is run when there are changes
watch(fn: (value: T) => void): void
Parameters
| Name | Type | Description |
|---|---|---|
fn |
(value: T) => any |
Callback will run on each change; it's passed the next value & it's return is ignored |
Returns
() => void - Function which will unsubscribe the watch/callback when called
toString
Return value as JSON string
toString(): string
Returns
string - Stringified JSON object
valueOf
Current value
valueOf(): T
Returns
T - Current value
Decorators
Create a proxy object which wraps your data so any changes can be intercepted & synced with storage.
Your data is stored under the value property and should always be accessed/modified through it.
Example
import {Persist} from 'var-persist';
class Theme {
// This property will automatically sync with localStorage
@Persist({default: 'os'}) current!: string;
constructor() {
console.log(this.current); // Output: os
this.current == localStorage.getItem('Thene.current'); // True
this.current = 'light';
console.log(this.current); // Output: light
}
}
Constructor
persist(options?: {key?: string} & PersistOptions<T>)
| Argument | Type | Description |
|---|---|---|
options |
{key: string} & PersistOptions<T> |
Configure using PersistOptions. Storage key can also be ovverriden by passing key as an option |
Types
PersistOptions<T>
Configurable options to change persistence behavior
| Property | Type | Description |
|---|---|---|
default? |
T |
Default/Initial value if undefined |
storage? |
Storage |
Storage implementation, defaults to LocalStorage. Can also be used with SessionStorage |
type? |
any |
Force value to have [proto]type |
License
Copyright © 2023 Zakary Timson | Available under MIT Licensing
See the license for more information.
Dependencies
Development Dependencies
| ID | Version |
|---|---|
| @types/jest | ^29.5.11 |
| jest | ^29.7.0 |
| jest-junit | ^16.0.0 |
| ts-jest | ^29.1.1 |
| typedoc | ^0.25.4 |
| typescript | ^5.3.3 |