webStorage
A minimal Javascript library that improves the way you work with localStorage
or sessionStorage
.
Install
npm
$ npm install webStorage
Git
$ git clone https://github.com/georapbox/webStorage.git
A few words...
The purpose of this library is to allow the user to manipulate data to localStorage
or sessionStorage
accordingly using a namespace (default is "webStorage") as a prefix for each item's key. This is by design in order to avoid potential conflicts with other key/value pairs that are probably already saved to storage. So, for example, if the database name we provided is myApp
, calling clear()
will remove only the items with key prefix myApp
. The same principle applies to all available API methods of the library.
API methods
config([options]) => WebStorage
Set and persist webStorage options. This must be called before any other calls to webStorage are made.
Kind: instance method of WebStorage
Throws: TypeError
if options.name
is not a string or empty string.
Throws: TypeError
if options.keySeparator
is not a string or empty string.
Returns: WebStorage
- The WebStorage instance for chaining.
The following options can be set:
Option | Type | Description | Default value |
---|---|---|---|
driver | Object |
The preferred driver to use. Use one between localStorage and sessionStorage . |
localStorage |
name | String |
The name of the database. This is used as prefix for all keys stored in the offline storage. | webStorage |
keySeparator | String |
String that separates database name and key. | / |
createInstance([options]) => WebStorage
Creates a new instance of the webStorage. The options
can be the same as config(options)
.
Kind: instance method of WebStorage
Throws: TypeError
if options.name
is not a string or empty string.
Throws: TypeError
if options.keySeparator
is not a string or empty string.
Returns: WebStorage
- The WebStorage instance for chaining.
getItem(key) => *
Gets a saved item from storage by its key.
Kind: instance method of WebStorage
Returns: *
- The value of the saved item. If the key
does not exist, will return null
.
Param | Type | Default | Description |
---|---|---|---|
key | String |
The property name of the saved item |
setItem(key, [value]) => WebStorage
Saves an item to storage. You can store the following types of JavaScript objects:
- String
- Number
- Array
- Object
Kind: instance method of WebStorage
Returns: WebStorage
- The WebStorage instance for chaining.
Param | Type | Default | Description |
---|---|---|---|
key | String |
The property name of the item to save | |
[value] | * |
null |
The item to save to the selected storage. |
removeItem(key) => WebStorage
Removes the item for the specific key from the storage.
Kind: instance method of WebStorage
Returns: WebStorage
- The WebStorage instance for chaining.
Param | Type | Default | Description |
---|---|---|---|
key | String |
The property name of the item to remove |
clear() => WebStorage
Removes all saved items from storage.
Kind: instance method of WebStorage
Returns: WebStorage
- The WebStorage instance for chaining.
keys() => Array
Gets the list of all keys in the storage for a specific database.
Kind: instance method of WebStorage
Returns: Array
- An array of all the keys that belong to a specific database.
length() => Number
Gets the number of items saved in a specific database.
Kind: instance method of WebStorage
Returns: Number
- The number of items for a specific database.
iterate(iteratorCallback) => WebStorage
Iterate over all value/key pairs in datastore.
Kind: instance method of WebStorage
Returns: WebStorage
- The WebStorage instance for chaining.
Param | Type | Default | Description |
---|---|---|---|
iteratorCallback | Function |
A callabck function to be executed for each iteration |
iteratorCallback
is called once for each pair, with the following arguments:
Param | Type | Description |
---|---|---|
key | String |
The key of the saved item. |
value | * |
The value of the saved item. |
quota() => Object
Display (approximately) the size for each saved item in datastore and the total size of all items in MB.
Kind: instance method of WebStorage
Returns: Object<string,number>
- An object with two properties that display the size for each saved item and the total size in MB.
supported() => Boolean
Checks if the driver of choice (localStorage
or sessionStorage
) is supported by the browser. It may return false
if storage is full.
Kind: instance method of WebStorage
Returns: Boolean
- True if driver is supported; otherwise false.
Usage Example
const users = id: 1 name: 'John Doe' email: 'johndoe@gmail.com' id: 2 name: 'George Cooper' email: 'gcooper@outlook.com' id: 2 name: 'Tim Smith' email: 'smith_t@yahoo.com'; const companies = 'Google' 'Yahoo' 'Microsoft' 'Mozilla'; /* Saving some items with the default configuration */webStorage ; ; /* Create a new instance and save some items */const ls = webStorage; ls ; ; ; /* Retrieving saved items */webStorage; // -> Object { id: 1, name: "John Doe", email: "johndoe@gmail.com" }webStorage; // -> "Google" ls; // -> Object { id: 2, name: "George Cooper", email: "gcooper@outlook.com" }ls; // -> "Microsoft" /* Get length of datastores */webStoragelength; // -> 2lslength; // -> 3 /* Get datastores' keys */webStorage; // -> Array [ "company", "user" ]ls; // -> Array [ "dummyKey", "company", "user" ] /* Itereate over datastores */ls;// -> dummyKey : 100// -> company : Microsoft// -> user : Object { id: 2, name: "George Cooper", email: "gcooper@outlook.com" } /* Quota */ls;// -> Object { "total": 0.0001430511474609375, "items": { "MyApp/dummyKey": 0.0000057220458984375, "MyApp/company": 0.0000209808349609375, "MyApp/user": 0.0001163482666015625 } }" /* Removing items */webStorage;webStoragelength; // -> 1webStorage; // -> Array [ "company" ]lslength; // -> 3 (still same as before)lsclear; /* Clear only the "MyApp" datastore */lslength; // -> 0ls; // -> Array []
Events
webStorage instances emit custom events the user can subscribe on:
setItem
: When an item is saved in storage.setItemError
: When there is an error saving item to storage.getItem
: When an item is retrieved from storage.getItemError
: When there is an error retrieving an item from storage.removeItem
: When an item is removed from storage.removeItemError
: When there is an error removing an item from storage.clear
: When all items from a database are removed.
Example
const ls = webStorage; { // ...do something with event} // Subscribe to setItem eventls; // Unsubscribe to setItem eventls; // Check if the target object has a listener registered on for specific event typels;
Build for development
$ npm run dev
Build for production
$ npm run build
Test
$ npm test
Changelog
For API updates and breaking changes, check the CHANGELOG.