Storing data with localStorage and Lockr

Published: January 20, 2017  •  Updated: June 19, 2017  •  database, javascript

localStorage is one of the options an application has if it needs to store data on the client side. It is a key/value store and provides a very simple api. All modern browsers support it (IE since version 8).

localStorage

setItem stores a value with a certain key. First argument is the name of the key and the second argument is the value. A key can only exists once. Calling setItem multiple times with the same key overwrites the previous entry. Key and value must be a string and setItem will automatically convert a non-string value to a string. This is a problem for objects because they get converted to the string "[object Object]". To solve that an application has to convert objects to a string before it calls setItem. One way to do it is with the JSON.stringify function.

localStorage.setItem('one', '1');
localStorage.setItem('two', 2);  // automatically converts 2 to the string "2"

const myObj = {firstName: 'John', lastName: 'Doe', age: 36};
localStorage.setItem('123', JSON.stringify(myObj));

getItem retrieves the value for a specific key. The function returns null when the key does not exists.

const a = localStorage.getItem('one'); // "1"
const b = localStorage.getItem('two'); // "2"
const obj = JSON.parse(localStorage.getItem('123')); // {firstName: 'John', lastName: 'Doe', age: 36}

Another possibility to set and get values is by directly accessing the key like a property on the localStorage object.

localStorage.one = '1'; // same as localStorage.setItem('one', '1');
const c = localStorage.one; // same as const c = localStorage.getItem('one');

It's possible to mix both approaches.

localStorage.two = '2'
const t = localStorage.getItem('two');  // "2"

There is one subtle difference in the behaviour when the key does not exist. getItem returns null and the property access returns undefined

const x = localStorage.getItem('xyz'); // null
const y = localStorage.xyz; // undefined

When the key is not a valid name for a property the application needs to use the ['property'] syntax (or setItem and getItem).

localStorage['11'] = 'eleven';
const e = localStorage['11']; // "eleven"

removeItem removes the entry for a specific key.

localStorage.removeItem('one');

clear removes all key/value pairs.

localStorage.clear();

Another related storage option is sessionStorage. It provides exactly the same functions as localStorage. The big difference is that data stored in localStorage survives a browser restart, data in sessionStorage does not. But even the data survives a browser restart, an application should not depend on the prospect that the data is stored and available forever. The data in a localStorage can be erased at anytime either by the user or browser. iOS for example removes data from the localStorage when it runs low on storage.

Lockr

In the examples above we saw that keys and values need to be strings. When the application stores a number localStorage automatically converts it to a string and getItem returns a string. An application can solve that by converting the value with JSON.stringify and JSON.parse.

Lockr is a thin wrapper around localStorage. This library does the conversion to JSON behind the scenes and makes your application's code more concise. This example stores a number and a boolean and returns the values with the same type.

Lockr.set('four', 4);
Lockr.set('five', true);
const f = Lockr.get('four');  // 4
const v = Lockr.get('five'); // true

Lockr has a size of 3000 bytes (version 0.8.4) in minified form and can be installed with bower, npm or with a simple script tag in the html page. In a npm project you can install it with the following command

npm install lockr

And if you work with TypeScript you can install the TypeScript definition file like this:

npm install @types/lockr --save-dev


set and get support storing and retrieving objects.

Lockr.set('anObject', {firstName: 'John', lastName: 'Doe', age: 36});
const anObject = Lockr.get('anObject'); // {age:36, firstName:"John", lastName:"Doe"}

The get function supports an optional second argument that specifies a default value that is returned when the key does not exist.

const s = Lockr.get('six', 0); // 0

The rm function removes a key/value entry.

Lockr.rm('four');

Lockr.flush() removes everything in the localStorage. It will also delete key/value entries that are stored directly with the localStorage object.



Lockr does not only wrap existing localStorage function it also adds some useful functionality on top of localStorage.

getAll() returns an array with all the stored values.

Lockr.set('1', 'one');
Lockr.set('2', 2);
Lockr.set('3', {name:'John', age: 36});
const values = Lockr.getAll(); // ["one", 2, {age:36,name:"John"}]

The following functions are inspired by Redis and allow an application to manage a set like structure with a specific key.

sadd adds a value to a set. If the application tries to add the same value multiple times sadd will ignore the call.

Lockr.sadd('bond', 'Daniel'); // ["Daniel"]
Lockr.sadd('bond', 'Sean'); // ["Daniel", "Sean"]
Lockr.sadd('bond', 'Daniel'); // ["Daniel", "Sean"]

smembers returns the values of a set as an array.

Lockr.sadd('bond', 'Pierce');
Lockr.sadd('bond', 'Roger');
Lockr.smembers('bond'); // ["Pierce", "Roger"]

sismember returns true when the value exists in the set otherwise false.

Lockr.sadd('bond', 'Daniel');
Lockr.sadd('bond', 'Roger');
Lockr.sismember('bond', 'Daniel'); // true
Lockr.sismember('bond', 'Jack'); // false

srem removes a value from a set.

Lockr.sadd('bond', 'Pierce');
Lockr.sadd('bond', 'Jack');
Lockr.srem('bond', 'Jack');
Lockr.smembers('bond'); // ["Pierce"]