memorystorage _^v0.12.0

Memory-backed storage that implements the Web Storage API, making it a drop-in replacement for localStorage and sessionStorage in environments where these are not available. Project website

^{_{^_.}}

logo

^{_{^_.}}

Installation

For Node

npm install --save memorystorage

For browsers

Include on your page

memorystorage can be used directly from CDN, from a local script file, or from a module loader.

CDN

This is by far the easiest method and gives good performance to boost. Use this if you are in doubt.

<script src="https://cdn.rawgit.com/download/memorystorage/0.12.0/dist/memorystorage.min.js"></script>

Local script file

Download memorystorage.min.js, place it in a folder lib in the root of your website and include it like this:

<script src="lib/memorystorage.min.js"></script>

Download

memorystorage.umd.js (~4kB, commented)
memorystorage.min.js (~2kB, minified)
memorystorage.min.js.map (~2kB, debug map file)

Module loaders

Memorystorage implements the Universal Module Pattern and as such, is available to be consumed from Node modules as well as via an AMD loader such as RequireJS.

Node

var MemoryStorage = require('memorystorage');
// here, the MemoryStorage function is available
var myStorage = new MemoryStorage('my-app');

AMD

define(['memorystorage'], function(MemoryStorage){
    // here, the MemoryStorage function is available
    var myStorage = new MemoryStorage('my-app');
});

To be able to load MemoryStorage from CDN as an AMD module, configure the CDN url like so (note the absence of .js in the url):

require.config({
    paths: {
        'memorystorage': 'https://cdn.rawgit.com/download/memorystorage/0.12.0/dist/memorystorage.min'
    }
});

ES2015

import MemoryStorage from 'memorystorage'
// here, the MemoryStorage function is available
const myStorage = new MemoryStorage('my-app');

Create a memory storage object

The MemoryStorage function creates (or returns) a storage object implementing the W3C Web Storage API. By default, scripts share a global storage object, so scripts can access and mutate each other's store object. To have MemoryStorage create a storage object that is isolated from other scripts, you pass in a unique ID which acts as a namespace:

var isolated = new MemoryStorage('my-app'); // isolated from other scripts, recommended.

If you don't pass in an ID, or use the ID 'global', you get a globally shared storage object:

var global = new MemoryStorage(); // will default to a globally shared storage object.
var global2 = new MemoryStorage('global'); // effectively same as above

For your convenience, the constructor permits new-less invocation:

var store = MemoryStorage('my-store');
var global = MemoryStorage();

Instances of MemoryStorage expose an immutable id property that is set to the id the store was created with:

alert(store.id); // alerts 'my-store'
alert(global.id); // alerts 'global'

Use it

store.setItem('myString', 'Hello MemoryStorage!');
store.myObject = JSON.stringify({my: 'object'}));
alert(store.getItem('My string')); // alerts 'Hello MemoryStorage!'
alert(store['My string']); // alerts 'Hello MemoryStorage!'
alert(store.length); // alerts '2'
alert(store.key(1)); // alerts 'My object'
store.removeItem('My string');
alert(store.length); // alerts '1'
store.clear();
alert(store.length); // alerts '0'

Staying within the Web Storage API

The Web Storage API is pretty small. For discovering which key-value pairs are available within the storage object, you basically only have the length property and the key(idx) function. The same applies to reading, writing and removing keys. You have the functions getItem, setItem and removeItem and there is clear but that pretty much sums it up.

In practice there are many other ways to interact with storage objects, such as store[myKey] = myValue, or delete store[myKey] or Object.keys(store) etc, but please remember that when you use these constructs, you venture outside the interface provided by the Web Storage API and run the risk of incompatibility.

This project is committed to be as compatible as possible with the localStorage object present in real-life browsers, but due to inherent limitations to the Javascript language, it's impossible to guarantee the same behavior in all instances if you go beyond the Web Storage API.

Example of going outside of the API

Here is some code to print all the keys and values in the store object that does not limit itself to the Web Storage API:

var keys = Object.keys(store);
for (var i=0; i<keys.length; i++) {
    var key = keys(i);
    var value = store[key];
    console.info(key + ': ' + value);
}

Example of staying within the API

Here is the same code, rewritten to stay within the API:

for (var i=0; i<store.length; i++) {
    var key = store.key(i);
    var value = store.getItem(key);
    console.info(key + ': ' + value);
}

Beyond the Web Storage API

MemoryStorage is type-agnostic; it doesn't care about the type of data you store. If you want to remain within the Web Storage API, you should only read and write strings, however if you want you can store other types just as well:

store.myObject = {my: 'object'};
alert(store.myObject.my); // alerts 'object'
var tree = {
    nested: {
        objects: {
            working: 'Sure!'
        }
    }
}
store.setItem('tree', tree);
alert(store.tree.nested.objects.working); // alerts 'Sure!'

Contributors

I'd like to draw your attention to the people that contributed to this project with bug reports, documentation, pull requests or other forms of support.

Stafford Brunk
- Push v0.9.10 to NPM #1 (reported issue)
Matthias Seemann:
- Items with store API key names are considered by key() #3 (code contribution)
- getItem should return null for not-existing keys #4 (code contribution)
Chris Smola
- Add npm install to README #5 (reported issue)
Corentin Minne
- Invalid exports in package.json #14 (code contribution)

Copyright

License

Licensed under the Creative Commons Attribution 4.0 International (CC-BY-4.0) Open Source license.

memorystorage

memorystorage v0.12.0