@amatiasq/client-storage v3.0.3

Client Storage

This library manages stores like localStorage, sessionStorage or localforage

Installation

Install with npm i --save @amatiasq/client-storage.

Usage

import { ClientStorage } from 'https://unpkg.com/@amatiasq/client-storage';

const lang = new ClientStorage<string>('my-app-language', {
  // default 'localStorage', also accepts export value of `localforage`;
  store: 'sessionStorage'
  // default 0
  version: 1,
  // required if <type> is not nullable
  default: 'en',
});

main();

async function main() {
  // will trigger a load and return default
  console.log(lang.cache); // 'en'

  // get the value from cache if cached or load it otherwise
  console.log(await lang.get()); // 'fr'

  // fetch the value from the store
  console.log(await lang.load()); // 'fr'

  lang.set('it');

  console.log(lang.cache) // 'it'
  console.log(await lang.get()) // 'it'

  const stored = lang.clear();
  console.log(stored); // 'it';
  console.log(lang.get()) // 'en'
}

JSON serialisation

When setting store = 'localStorage' (default) or store = 'sessionStorage' serialization / deserialization is managed automatically by JSON.stringify / JSON.parse.

Versioning

This class will store a version number next to the stored value. If the stored version number does not match the current one, it will remove the stored value. This prevents an updated application to receive legacy formats and removes the need to ask the clients to wipe site data.

import { ClientStorage } from 'https://unpkg.com/@amatiasq/client-storage';

const first = new ClientStorage<string>('test', { version: 0 });
first.set('this is a test');
console.log(first.get()); // 'this is a test'

const second = new ClientStorage<string>('test', { version: 1 });
console.log(second.get()); // null

console.log(first.get()); // null

Transform

You can add a transformer to convert the stored value into something else and back:

import { ClientStorage, IClientStorage } from 'https://unpkg.com/@amatiasq/client-storage';

const friendId = new ClientStorage<string>('friend-ids', { default: 12 });

class Friend {
  constructor(id: string) {}
  toString() {
    return `Friend(${this.id})`
  }
}

const friend: IClientStorage = friendId.transform<Friend>({
  apply: id => new Friend(id),
  revert: friend => friendfriend.id;
  // required if `apply` returns a promise (not in this case)
  // default: [],
});

friendId.set(25);

console.log(friend.cache.toString()) // Friend(25)
console.log((await friend.get()).toString()) // Friend(25)
console.log(friend.cache.toString()) // Friend(25)

friend.set(new Friend(42));

console.log(friendId.cache); // 42
console.log((await friendId.get()).toString()); // 42
console.log(friendId.cache); // 42

const friendToString = friend.transform<string>({
  friend => friend.toString(),
  text => new Friend(parseInt(text.substr(7, -1))),
});

console.log(friendToString.cache) // Friend(42)

friendId.reset();

console.log(friend.cache.toString()) // Friend(12)
console.log((await friend.get()).toString()) // Friend(12)
console.log(friendToString.cache) // Friend(12)