TypeScript: Sync variables with localStorage https://www.npmjs.com/package/webstorage-decorators
Go to file
2021-02-02 00:05:08 -05:00
lib Added some extra null checks & prototype casting 2021-02-01 23:37:49 -05:00
src Added some extra null checks & prototype casting 2021-02-01 23:37:49 -05:00
tests Fixed some bugs 2021-01-28 15:18:32 -05:00
.gitignore Updated to 2.0 2021-01-28 10:24:11 -05:00
jest.config.js Updated to 2.0 2021-01-28 10:24:11 -05:00
package.json Updated docs 2021-02-02 00:05:08 -05:00
README.md Updated docs 2021-02-02 00:05:08 -05:00
tsconfig.json Fixed some bugs 2021-01-28 15:18:32 -05:00

WebStorage Decorators

A Javascript library that adds property decorators to sync a class property with the local or session storage. Useful for persisting themes or local settings over reloads or maintaining filters/search options in the current user session.

Quick Setup

  1. Install with: npm install --save webstorage-decorators
  2. Add the decorator to your property and use as normal!
import {LocalStorage, SessionStorage} from 'webstorage-decorators';

export class MyCustomClass {
   @LocalStorage('light_theme', {key: 'site_theme'}) theme: string;
   @SessionStorage(null, {encryptWith: config.entryptionKey}) thisUser: User;
   @SessionStorage() searchBar: string;
    
   constructor() {
       console.log(this.theme, localStorage.getItem('theme')); // Output: 'light_theme', 'light_theme'
       console.log(this.user, localStorage.getItem('user')); // Output: null, undefined
       user = {first: 'John', last: 'Smith', ...}
       console.log(this.user, localStorage.getItem('user')); // Output: {first: 'John', last: 'Smith', ...}, **Some encrypted value**
   }
}

Documentation

Decorators

Decorator Description
@LocalStorage(defaultValue: any, options: WebStorageOptions) Syncs property to LocalStorage item under the same name
@SessionStorage(defaultValue: any, options: WebStorageOptions) Syncs property to SessionStorage item under the same name

WebStorageOptions

Options Description
default Default value, same as decorator's first argument
encryptWith Secret key to encrypt stored values with
key Key to reference value inside local/session storage (Defaults to the property name)

Caveats

Custom Functions

You can technically store anything inside local/session storage however everything is serialized using javascript's JSON, so anything extra (prototypes, functions, etc) will be lost. However if you provide a default value, it will be copied & the data injected, giving you a workaround to accessing static properties (Does not work with arrays).

class Person {
    constructor(public first: string, public last: string) { }
    fullName() { return `${this.last}, ${this.first}`; }
}

LocalStorage.setItem('example', '{"first": "John", "last": "Smith"}');
@LocalStorage(null) example!: Person;
console.log(example.fullName()) // ERROR: fullName function doesn't exist

LocalStorage.setItem('example2', '{"first": "John", "last": "Smith"}');
@LocalStorage(new Person(null, null)) example2!: Person;
console.log(example2.fullName()) // Works because we have a default object to copy type from

Impure Functions

Impure functions don't use the Object's setter preventing the storage from being updated. To prevent this use a pure function or save it manually by reading the variable. (Reading triggers change detection & save if there are differences)

@LocalStorage([1, 2]) example: number[];
example.push(3) // Impure & won't update storage
console.log(localStorage.getItem('example')) // Output: [1, 2];
example; // Trigger save
console.log(localStorage.getItem('example')) // Output: [1, 2, 3];

// OR

example = example.concat([3]); // Pure function requires you to use the setter triggering automatic saving