capsule

A lightweight wrapper for better, typed localStorage interactions.

Installation

Install using npm/yarn

npm i @yootil/capsule

Usage

import { Capsule } from '@yootil/capsule';

const capsule = new Capsule('my-app', {
    myValue: 'initial value if not yet in localStorage',
});

capsule.get('myValue'); // 'initial value if not yet in localStorage'

capsule.set('myValue', 'another string!'); // is now 'another string!'

// Keys do not conflict across namespaced capsules
const otherCapsule = new Capsule('my-other-app', {
    myValue: 'a different value for a different app',
});

capsule.get('myValue'); // is still 'another string!'
otherCapsule.get('myOtherCapsule'); // 'a different value for a different app'

// Can save and retreieve POJOs
capsule.set('myMap', {
  foo: 'bar',
  list: [123, { value: 456 }, false],
  time: new Date(),
});

capsule.get('myMap');
/*
{
  foo: 'bar',
  list: [123, { value: 456 }, false],
  time: "2022-07-07T12:54:30.740Z", // Note that Dates do not currently re-hydrate
}
*/

// Can be given types
capsule.get<number>('foo'); // typescript now treats return type as 'number'

type User = { name, /* ... */ };
type MyCapsuleType = {
  foo: string,
  count: number,
  users: User[],
}

const typedCapsule = new Capsule<MyCapsuleType>('typed-capsule');

const users = typedCapsule.get('users'); // users is type User[]

// raises: TS2345: Argument of type '"notAkey"' is not assignable to parameter of type 'keyof MyCapsuleType'.
typedCapsule.set('notAkey', 'foo');

If no type is given in the constructor type params new Capsule<YourType>(), then the type will be inferred from the initialData argument.

If no initialArgument is given, the types will all be unknown, and all keys will be allowed.

If you wish to provide initial data without hard type checking, provide new Capsule<any>() or new Capsule<Record<string, unknown>>()