var-persist/README.md

Persist

Typescript Library to Sync Variables with LocalStorage

---

Release Notes • Report a Bug • Request a Feature

---

Table of Contents

• Persist
  • About
    • Examples
    • Built With
  • Setup
    • Production
    • Development
  • Documentation
    • Classes
    • Decorators
    • Types
  • License

About

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 objects & decorators
• Proxy object ensures all changes are tracked including impure functions
• [Proto]types and functions can be preserved by passing the type option

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 'ztimson/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 'ztimson/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 'ztimson/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 ztimson/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 'ztimson/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

Register callback to listen for changes

watch(fn: (value: T) => void): void

Parameters

Name	Type
fn	(value: T) => any

toString

Return value as JSON string

toString(): string

Returns

string - Stringified JSON object

valueOf

Return current value

valueOf(): T

Returns

T - Current value

Decorators

persist(options?: {key?: string} & PersistOptions<T>)

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.