Typed Local and Session Storage Adapter (tlssa).

Typed Local and Session Storage Adapter (TLSSA) - A Strictly typed Local and Session Storage Adapter for Typescript that uses JSON format when saving to actual storage.

Quick start

npm i tlssa

Define the schema of entities you want to store to local or session storage. Create an instance of TypedStorageAdapter with the schema as type parameter, and storage instance (localStorage or sessionStorage) and prefix of key name as constructor parameters. Then, you can load and store entities using typed getItem and setItem methods. Namespace-like behavior with key prefix and getOrCreateItem, removeItem, keys, length, clear methods are also available.

// TypedStorageAdapter needs a type parameter as the schmema of the stored items,
// and storage instance and key prefix as constructor parameters.
// Actual key to access the storage is "myapp.key". If key prefix is not provided,
// the actual key is just "key".
const storage = new TypedStorageAdapter<{id: string; name: string}>(localStorage, "myapp");

// getOrCreateItem returns the stored value or "000" with storing it
// if "myapp.id" is not stored.
storage.getOrCreateItem("id", "000");
// returns the stored value or execution result of supplied function with storing
// it to the storage if "myapp.id" is not stored.
storage.getOrCreateItem("id", (_key)=>"000");

// getItem() returns the stored value or "000" if not stored.
storage.getItem("id", "000");
// returns the stored value or execution result of supplied function if not stored.
storage.getItem("id", (_key)=>"000");
// returns the stored value or null if not stored.
storage.getItem("id");

// setItem() stores the value to the storage with key generated by concatenating
// prefix and the given key.
storage.setItem("name", "000");

// removeItem() removes the stored value.
storage.removeItem("name");

// keys() returns all keys. If key prefix is valid, this method only returns
// the key string after prefix string (i.e. returns "name" when the actual
// key is "myapp.name").
const allKeys = storage.keys();

// clear() clears all entries that has the key `${prefix}.*`.
// If the prefix is not supplied or empty, this method clears all entries.
storage.clear();

Type checking

const storage = new TypedStorageAdapter<{id: string; name: string}>(localStorage, "myapp");

storage.getOrCreateItem("id", "000");  // OK
storage.getOrCreateItem("id", 0);  // NG
storage.getOrCreateItem("id", true);  // NG
storage.getOrCreateItem("name", (_key)=>"000");  // OK
storage.getOrCreateItem("name", ()=>"000");  // OK
storage.getOrCreateItem("name", ()=>true);  // NG
storage.getOrCreateItem("name");  // NG
storage.getOrCreateItem("age", 20);  // NG

storage.getItem("id", "000");  // OK
storage.getItem("id", (_key)=>"000");  // OK
storage.getItem("name");  // OK
storage.getItem("name", 20);  // NG
storage.getItem("age"); // NG

storage.setItem("id", "000");
storage.setItem("name", 20);  // NG

storage.removeItem("id");  // OK
storage.removeItem("age");  // NG