README
cabinet.js
A simple interface for accessing local and session storage.
Installation
npm install cabinet-storage
Implementation Example
// import the Cabinet module
import Cabinet from "cabinet-storage"
Methods
Cabinet uses local storage by default. Access session storage under the Cabinet.session
namespace.
Cabinet.set(key, val[, metadata])
Creates an item inside local storage
Parameters
key
(String | Number)val
(Any)metadata
(Object: optional)
Examples
Cabinet.set("dog", "Scooby") // returns "Scooby"
Cabinet.set("total", 50/(10-5)) // 10
Cabinet.set("person", {name: "Michael", age: 26, gender: "Male"}); // storing objects
Cabinet.set("animals", ["lion", "tiger", "bear"]); // storing arrays
Cabinet.set("friends", [{name: "Stan"}, {name: "Wendy"}]); // storing collection
Cabinet.set("check", true); // true
Cabinet.set("reminder", new Date(Date.now() + 1000)); // Mon Feb 26 2018 21:47:15 GMT-0800 (Pacific Standard Time)
Working with expirations
// set an expiration using a new Date instance
Cabinet.set("reminder", "Thanks a ton", {
expires: new Date(Date.now() + 300000000)
})
// set an expiration to 30 days from now
Cabinet.set("partyime", "It's time to party", {
expires: {value: 30, unit: "day"} // returns "It's time to party"
})
Cabinet.set("dueDate", "Project due", {
expires: {value: 3, unit: "hour"}
})
// time units: "day", "hour", "minute", "second"
Cabinet.get(key[, defaultVal])
Retrieves an item from local storage if it exists
Parameters
key
(String | Number)defaultVal
(Any: optional)
Examples
Cabinet.get("friends") // returns [{name: "Stan"}, {name: "Wendy"}]
// items that don't exist return null
Cabinet.get("doesntExist") // null
// iterating through a collection
Cabinet.get("friends").map(item => {
let name = item.name
})
Default Values
// If the item doesn't exist in local storage and a default value is provided, Cabinet will call the set method
Cabinet.get("todos", []) // returns []
Cabinet.get("nameField", "Enter Your Name") // "Enter Your Name"
Cabinet.getAll()
Retrieves all items from local storage
Examples
// returns an array containing all of the values in local storage
Cabinet.getAll() // ["reminder", 123, [], {name: "Stan"}]
// filter out numbers
Cabinet.getAll().filter(val => typeof val === "number") // filtered array
Cabinet.remove(key)
Removes an item from local storage if it exists
Parameters
key
(String | Number)
Examples
// returns true if the item was successfully removed
Cabinet.remove("reminder") // true
// returns null if the item doesn't exist
Cabinet.remove("doesntExist") // null
Cabinet.removeAll()
Removes all items from local storage
Examples
Cabinet.removeAll() // returns true
Cabinet.getMetadata(key)
Retrieves a set of attributes that Cabinet stores with an item inside local storage
Parameters
key
(String | Number)
Examples
// readable properties
const friends = Cabinet.getMetadata("friends") // returns the metadata object {}
friends.dateCreated // date string
friends.expires // date string or null (if not provided)
friends.source // "CABINET_STORAGE"
friends.type // datatype (string)
friends.val // the stored value
// retrieve the expiration date
let expires = new Date(Cabinet.getMetadata("reminder").expires) // Thu Mar 08 2018 21:40:24 GMT-0800 (Pacific Standard Time)
// check if the item came from Cabinet
if (Cabinet.getMetadata("reminder").source === "CABINET_STORAGE") {
// do stuff...
}
Cabinet.removeExpired()
Removes all expired items from local storage
Examples
// returns an array containing the keys of the removed items
Cabinet.removeExpired() // ["key1", "key2", "key3"]
// no expired items
Cabinet.removeExpired() // null
Cabinet.count()
Returns a count of the number of items saved in local storage
Examples
Cabinet.count() // 3
Cabinet.keys()
Returns an array containing all of the keys in local storage
Examples
Cabinet.keys() // ["key1", "key2", "key3"]
Session Storage Usage
Cabinet.session.methodName()
Access session storage under the Cabinet.session namespace.
Cabinet.session.get(key)
Cabinet.session.set(key, val)
Cabinet.session.getAll()
Cabinet.session.remove(key)
Cabinet.session.removeAll()
Cabinet.session.getMetadata()
Cabinet.session.removeExpired()
Cabinet.session.keys()
Cabinet.session.count()
Development Build
# install dependencies
npm install --save-dev
# run demo build
npm run demo
Next, open /demo/dist/index.html
in your browser.
Interact with the module from /demo/src/demo.js
. You can log output to the console or render output to the examples index page.
Production Build
npm run build
production build is output to /dist/main.js