A tiny (< 1kb) localStorage
and sessionStorage
helper library.
It automatically parses objects and arrays into strings (and back). It also let's you validate and expire localStorage
data after a set period of time.
Installation | API | Browser Compatibility | License
Vanilla JS Pocket Guides or join the Vanilla JS Academy and level-up as a web developer. 🚀
Want to learn how to write your own vanilla JS libraries? Check out myInstallation
The CDN is the fastest and simplest way to get started, but you can use importable modules or a direct download if you’d prefer.
<!-- Get the latest major version -->
<script src="https://cdn.jsdelivr.net/npm/storagebinjs@1/dist/bin.min.js"></script>
Bin uses semantic versioning. You can grab a major, minor, or patch version from the CDN with the @1.2.3
syntax. You can find all available versions under releases.
ES Modules
Bin also supports modern browsers and module bundlers (like Rollup, Webpack, Snowpack, and so on) using the ES modules import syntax. Use the .es
version.
import Bin from 'https://cdn.jsdelivr.net/npm/storagebinjs@1/dist/bin.es.min.js';
NPM
You can also use NPM (or your favorite package manager). First, install with NPM.
npm install storagebinjs --save
Then import the package.
import Bin from 'storagebinjs';
CommonJS
If you use NodeJS, you can import bin using the require()
method with the .cjs
version.
let Bin = require('https://cdn.jsdelivr.net/npm/storagebinjs@1/dist/bin.cjs.min.js');
AMD
If you use RequireJS, SystemJS, and other AMD formats, you can import bin with the .amd
version.
requirejs(['https://cdn.jsdelivr.net/npm/storagebinjs@1/dist/bin.amd.min.js'], function (Bin) {
//...
});
Direct Download
You can download the files directly from GitHub.
Compiled and production-ready code can be found in the dist
directory. The src
directory contains development code.
<script src="path/to/bin.min.js"></script>
API
Before working with Bin, you need to instantiate a new instance. Pass in the ID you would like to use for your localStorage
/sessionStorage
data as an argument.
Bin defaults to localStorage
. You can optionally pass in true
as a second argument to use sessionStorage
instead.
// Instantiate a new localStorage instance
var myBin = new Bin('myBinID');
// Instantiate a new sessionStorage instance
var myBinSession = new Bin('myBinSessionID', true);
set()
Save data to storage.
Pass in your data as an argument. It can be an object, array, string, number—any valid JavaScript object type. Bin will automatically convert it to a string for storage.
// Store an object
myBin.set({
sandwich: 'turkey',
drink: 'soda',
chips: true
});
// Store an array
myBin.set([
'turkey',
'tuna',
'pb&j'
]);
// Store a string
myBin.set('I love Cape Cod potato chips!');
// Store a number
myBin.set(42);
If you would like your data to expire, pass in the amount of time in seconds that the data is good for.
// expires in one week
// 60 seconds x 60 minutes x 24 hours x 7 days
myBin.set('Temporary value', 60 * 60 * 24 * 7);
get()
Get data from storage. You can optionally pass in a fallback to use if no data is found.
// Get data from storage
myBin.get();
// Use a fallback object
myBin.get({});
// Use a fallback array
myBin.get([]);
// Use a fallback string
myBin.get('');
// Use a fallback number
myBin.get(0);
If the data has expired, it will be removed and null
will be returned. To get the actual data event if it has expired, pass in true
as a second argument.
myBin.get('Temporary value', true);
isValid()
Check if data has expired based on the expiration
you set when defining it.
// 1 hour
myBin.isValid();
// 1 day
myBin.isValid();
// 1 week
myBin.isValid();
// 1 year
myBin.isValid();
// 15 minutes
myBin.isValid();
// 2 days
myBin.isValid();
remove()
Remove data from storage. The instance will remain available, but the data will be wiped from localStorage
/sessionStorage
.
myBin.remove();
Browser Compatibility
Bin works in all modern browsers, and IE 8 and above.
License
The code is available under the MIT License.