persistme

localStorage on steroids 💉

persistme lets you namespace your localStorage across multiple applications even when they are hosted on the same domain. Store and retrieve data from different apps without worrying about name clashes and accidental overrides of the localStorage properties. Besides solving the namespace problem, it also comes with some nice goodies.

• Namespace multiple apps localStorage usage on the same domain
• Store/retrieve any primitive data types in their exact format -- string, boolean, number, object and array
• Uses LZ-based compression algorithm so you can squeeze more data in the given localStorage data limit
• Neat APIs and sugars with default fallbacks

Install

The library is available as a UMD package. If you prefer to use the traditional approach, you may download and include the persistme.min.js file directly in the script tag.

npm install --save persistme

Usage Examples

Check out the examples folder for some rudimentary multi-application setups.

Basic Usage

import { createStorage } from 'persistme';

// app 1
const MyAppStorage = createStorage('MY_AWESOME_APP');

MyAppStorage.set('user', 'Emad Alam');
MyAppStorage.get('user'); // Emad Alam

// app 2
const MyApp2Storage = createStorage('MY_AWESOME_APP2');

MyApp2Storage.set('user', 'Amina Dropic');
MyApp2Storage.get('user'); // Amina Dropic

Fallback Values

import { createStorage } from 'persistme';

const defaults = {
    name: 'Emad Alam',
    addr: {
        street: 'X Street',
        city: 'Berlin'
    }
};

const MyAppStorage = createStorage('MY_AWESOME_APP', defaults);

MyAppStorage.get('user'); // Emad Alam
MyAppStorage.get('addr'); // {street: 'X Street', city: 'Berlin'}

MyApp2Storage.set('user', 'Amina Dropic');
MyApp2Storage.get('user'); // Amina Dropic

Update Existing Values

import { createStorage } from 'persistme';

const defaults = {
    name: 'Emad Alam',
    addr: {
        street: 'X Street',
        city: 'Berlin'
    }
};

const MyAppStorage = createStorage('MY_AWESOME_APP', defaults);

MyAppStorage.get('addr'); // {street: 'X Street', city: 'Berlin'}

MyApp2Storage.update('addr', {country: 'DE'});
MyApp2Storage.get('addr'); // {street: 'X Street', city: 'Berlin', country: 'DE'}

Settings Factory

import { createStorage, createSetting } from 'persistme';

const storage = createStorage('MY_AWESOME_APP');

// optional config to map settings with unique keys
const configs = {
    showSomething: 'mymodule.show.something',
    showSomethingElse: 'mymodule.show.somethingelse',
};
// default settings fallback values
const defaults = {
    showSomething: true,
    showSomethingElse: false,
};
// create settings proxy object
const UserSettings = createSetting({storage, defaults, configs});
// use like a normal object notation
UserSettings.showSomething // true
UserSettings.showSomethingElse // false
// set some settings
UserSettings.showSomethingElse = true;
// after app reload, etc
UserSettings.showSomethingElse // true

API

Factories

createStorage(appName, defaults): Storage Instance

Returns the storage instance that has methods for set, get, update and remove operations on the application specific localStorage.

| param | type | required | description | | ------ | ----- | -------- | ----------- | | appName | String | yes | Name of the storage | | defaults | Object | optional | Map of fallback values |

createSetting(options): Proxy Object

Returns the proxy object that can be used to retrieve data from a previously created, application localStorage using simple object dot notation.

| param | type | required | description | | ------ | ----- | -------- | ----------- | | options | Object | | Options for the settings proxy (see below) | options.storage | Object | yes | Storage object that implements the get and set methods. Ideally you would just pass the previously created storage instance returned by the createStorage factory. | | options.defaults | Object | optional | Map of fallback values | | options.configs | Object | optional | Map of key configurations that will be used by the storage API while generating the item key. Defaults to the key used by the settings object to access the data. |

Storage instance methods

get(key): Mixed

Returns the app specific data stored for the given key, falls back to the default value if provided by the app specific defaults config map. Decompresses the data after retrieving from the localStorage.

| param | type | required | description | | ------ | ----- | -------- | ----------- | | key | String | yes | The item key |

set(key, value)

Stores the app specific data for the given key, compresses the data before storing in the localStorage.

| param | type | required | description | | ------ | ----- | -------- | ----------- | | key | String | yes | The item key | | value | Mixed | yes | The data to store |

update(key, value)

Similar to set method, but extends (shallow merges) the original stored value if it is one of type array or object.

Note: The data type of both stored as well as provided value should match in order for the update to work. Also the value should initially exist, otherwise the behavior is equivalent to set method.

| param | type | required | description | | ------ | ----- | -------- | ----------- | | key | String | yes | The item key | | value | Mixed | yes | The data to update |

remove(keys)

Completely removes the given key(s) and the associated app specific data from the localStorage.

| param | type | required | description | | ------ | ----- | -------- | ----------- | | keys | String, Array<String> | yes | The item key(s) to remove |

getKey(key): String

Returns the final namespaced property name that would be used in lieu of the given key for storing the app specific data in the localStorage.

| param | type | required | description | | ------ | ----- | -------- | ----------- | | key | String | yes | The actual item key |

LZString compression

The original lz-string compression library instance is exported as LZString. Refer to the original source docs for the available methods of the source library.

import { LZString } from 'persistme';
// or, if including directly from script tag
// const LZString = persistme.LZString

const { compress, decompress } = LZString;

const str = 'I am a very huge string data...';
const compressedValue = compress(str); // compressed string

console.log(decompress(compressedValue)); // I am a very huge string data...

Caveats

This library uses WeakMap and Proxy for its core implementations. If you plan to use this library on browsers that do not yet support these features, please also consider including polyfills for those browsers.

• WeakMap polyfill
• Proxy polyfill

Who's using it

• atvjs - Blazing fast Apple TV application development using pure JavaScript
• mesmerized - Transform your browser tabs

Built something cool using this? Submit a PR to add it to this section.

Contributions

• Fork the project
• Commit your enhancements and bug fixes
• Create a pull request describing the changes

npm start       # run example apps
npm run dev     # watch changes
npm run build   # create library builds
npm run test    # run tests

License

persistme is licensed under the MIT License