localit, a better Storage API

Alejandro Mayol — Sun, 24 Oct 2021 00:15:11 +0000

The Web Storage API is a good example of a simple-yet-powerful feature, but while using it, I found myself repeating JSON.stringify() while saving objects and that was frustrating. Add to it the absence of a way to set when you want your local data to expire and you'll have all the ingredients that led me to create localit.

A simple example of how easy it is to use localit:

import { localit } from "localit";

localit.set("article", "localit 101", "3h");

console.log(localit.get("article"));
//  "localit 101"

The basics

localit's core methods are the same you would use while saving and retrieving data from localStorage.

`set()`, `get()` and `remove()`

These methods wrap and replace the logic behind setItem, getItem and removeItem(), removing the need to use JSON.stringify() and JSON.parse(), which I think is the main pain point while using localStorage.

There's no magic to them, since they work as you'd expect the actual Storage API to work.

Advanced feature

My favourite feature, and propably the reason why you may chose localit over the native Storage API, is its expiration date feature.

With this, it's easy to set when a given value should be deleted from the Storage.

localit.set('short', 'period of time', '3h')

By passing a third parameter, we are setting the 'short' key with a value of 'period of time' for three hours. If we try to get('short') after three hours have passed, we will get null, just like we never stored it in the first place. Notice that localStorage also returns null if we retrieve a non-existing key.

We can specify that time in seconds, minutes, hours and days:

localit.set('key1', 'value 1', '20s')
localit.set('key2', 'value 2', '50m')
localit.set('key3', 'value 3', '7h')
localit.set('key4', 'value 4', '2d')

The icing on the cake

Now, let's imagine we have multiple teams working on the same app, and all of them use localStorage. It may be possible that, at some point, someone uses a key that is already being used by another team for a different feature. We'd have a key replacing another existing key, and, thus, an unwanted side effect.

That's why localit implements a domain system, where all keys will be automatically prefixed:

localit.setDomain("feature1");
localit.set("state", {})

localit.setDomain("feature2");
localit.set("state", {})

console.log(localStorage);
/*
Storage:{
    length: 2,
    feature1_state: "{}",
    feature2_state: "{}"
}
*/

We can, of course, change the domain at any point to retrieve its keys or even delete all Storage values of a given domain:

localit.clearDomain("feature1")
console.log(localStorage);
/*
Storage:{
    length: 1,
    feature2_state: "{}"
}
*/

Final notes

localit has more in store for you (pun intended), since it wraps the behaviour of the native Storage API. Please, refer to the docs for more info.

Also, since localit is written in TypeScript, you'll get declarations out of the box! Try them out and more advanced examples in this demo:
https://codesandbox.io/s/localit-example-bldi3

P.S. localit is participating in 2021's Hacktoberfest, so feel free to submit your PR or open a new issue to help the world with its storage problem! 🥳