var-persist/README.md

var-persist

TypeScript: Sync variables with localStorage

---

Release Notes • Report a Bug • Request a Feature

---

Table of Contents

• var-persist
  • About
    • Examples
    • Built With
  • Setup
    • Production
    • Development
  • Documentation
    • Classes
    • Decorators
    • Types
  • License

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 type option

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

• Node.js

Instructions

1. Install persist: npm i var-persist
2. Enable decorators inside tsconfig.json:

{
	"compilerOptions": {
		"experimentalDecorators": true,
		...
	},
	...
}

3. Import & use, see examples above

Development

Prerequisites

• Node.js

Instructions

1. Install the dependencies: npm i
2. Build library & docs: npm build
3. 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.