{"id":16427578,"url":"https://github.com/cferdinandi/bin","last_synced_at":"2025-07-21T04:07:53.243Z","repository":{"id":34287958,"uuid":"154345831","full_name":"cferdinandi/bin","owner":"cferdinandi","description":"A tiny (\u003c1kb) localStorage and sessionStorage helper library.","archived":false,"fork":false,"pushed_at":"2022-06-23T11:20:06.000Z","size":121,"stargazers_count":85,"open_issues_count":4,"forks_count":7,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-06-28T10:05:18.471Z","etag":null,"topics":["javascript","javascript-library","localstorage","sessionstorage","vanilla-javascript","vanilla-js"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cferdinandi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/contributing.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-10-23T14:47:22.000Z","updated_at":"2024-08-22T04:15:18.000Z","dependencies_parsed_at":"2022-08-26T23:23:14.611Z","dependency_job_id":null,"html_url":"https://github.com/cferdinandi/bin","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/cferdinandi/bin","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cferdinandi%2Fbin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cferdinandi%2Fbin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cferdinandi%2Fbin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cferdinandi%2Fbin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cferdinandi","download_url":"https://codeload.github.com/cferdinandi/bin/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cferdinandi%2Fbin/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266236921,"owners_count":23897288,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["javascript","javascript-library","localstorage","sessionstorage","vanilla-javascript","vanilla-js"],"created_at":"2024-10-11T08:13:24.930Z","updated_at":"2025-07-21T04:07:53.228Z","avatar_url":"https://github.com/cferdinandi.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Bin [![Build Status](https://travis-ci.org/cferdinandi/bin.svg)](https://travis-ci.org/cferdinandi/bin)\nA tiny (\u003c 1kb) `localStorage` and `sessionStorage` helper library.\n\nIt 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.\n\n[Installation](#installation) | [API](#api) | [Browser Compatibility](#browser-compatibility) | [License](#license)\n\n\u003chr\u003e\n\n### Want to learn how to write your own vanilla JS libraries? Check out my [Vanilla JS Pocket Guides](https://vanillajsguides.com/) or join the [Vanilla JS Academy](https://vanillajsacademy.com) and level-up as a web developer. 🚀\n\n\u003chr\u003e\n\n\n## Installation\n\n[The CDN is the fastest and simplest way to get started](https://cdn.jsdelivr.net/npm/storagebinjs/dist/), but you can use importable modules or a direct download if you’d prefer.\n\n```html\n\u003c!-- Get the latest major version --\u003e\n\u003cscript src=\"https://cdn.jsdelivr.net/npm/storagebinjs@1/dist/bin.min.js\"\u003e\u003c/script\u003e\n```\n\nBin 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](https://github.com/cferdinandi/bin/releases).\n\n**ES Modules**\n\nBin also supports modern browsers and module bundlers (like Rollup, Webpack, Snowpack, and so on) using the ES modules import syntax. Use the `.es` version.\n\n```js\nimport Bin from 'https://cdn.jsdelivr.net/npm/storagebinjs@1/dist/bin.es.min.js';\n```\n\n**NPM**\n\nYou can also use NPM (or your favorite package manager). First, install with NPM.\n\n```bash\nnpm install storagebinjs --save\n```\n\nThen import the package.\n\n```js\nimport Bin from 'storagebinjs';\n```\n\n**CommonJS**\n\nIf you use NodeJS, you can import bin using the `require()` method with the `.cjs` version.\n\n```js\nlet Bin = require('https://cdn.jsdelivr.net/npm/storagebinjs@1/dist/bin.cjs.min.js');\n```\n\n**AMD**\n\nIf you use RequireJS, SystemJS, and other AMD formats, you can import bin with the `.amd` version.\n\n```js\nrequirejs(['https://cdn.jsdelivr.net/npm/storagebinjs@1/dist/bin.amd.min.js'], function (Bin) {\n  //...\n});\n```\n\n**Direct Download**\n\nYou can download the files directly from GitHub.\n\nCompiled and production-ready code can be found in the `dist` directory. The `src` directory contains development code.\n\n```html\n\u003cscript src=\"path/to/bin.min.js\"\u003e\u003c/script\u003e\n```\n\n\n\n## API\n\nBefore 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.\n\nBin defaults to `localStorage`. You can optionally pass in `true` as a second argument to use `sessionStorage` instead.\n\n```js\n// Instantiate a new localStorage instance\nvar myBin = new Bin('myBinID');\n\n// Instantiate a new sessionStorage instance\nvar myBinSession = new Bin('myBinSessionID', true);\n```\n\n### `set()`\n\nSave data to storage.\n\nPass in your data as an argument. It can be an object, array, string, number\u0026mdash;any valid JavaScript object type. Bin will automatically convert it to a string for storage.\n\n```js\n// Store an object\nmyBin.set({\n\tsandwich: 'turkey',\n\tdrink: 'soda',\n\tchips: true\n});\n\n// Store an array\nmyBin.set([\n\t'turkey',\n\t'tuna',\n\t'pb\u0026j'\n]);\n\n// Store a string\nmyBin.set('I love Cape Cod potato chips!');\n\n// Store a number\nmyBin.set(42);\n```\n\nIf you would like your data to expire, pass in the amount of time in seconds that the data is good for.\n\n```js\n// expires in one week\n// 60 seconds x 60 minutes x 24 hours x 7 days\nmyBin.set('Temporary value', 60 * 60 * 24 * 7);\n```\n\n### `get()`\n\nGet data from storage. You can optionally pass in a fallback to use if no data is found.\n\n```js\n// Get data from storage\nmyBin.get();\n\n// Use a fallback object\nmyBin.get({});\n\n// Use a fallback array\nmyBin.get([]);\n\n// Use a fallback string\nmyBin.get('');\n\n// Use a fallback number\nmyBin.get(0);\n```\n\nIf 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.\n\n```js\nmyBin.get('Temporary value', true);\n```\n\n### `isValid()`\n\nCheck if data has expired based on the `expiration` you set when defining it.\n\n```js\n// 1 hour\nmyBin.isValid();\n\n// 1 day\nmyBin.isValid();\n\n// 1 week\nmyBin.isValid();\n\n// 1 year\nmyBin.isValid();\n\n// 15 minutes\nmyBin.isValid();\n\n// 2 days\nmyBin.isValid();\n```\n\n### `remove()`\n\nRemove data from storage. The instance will remain available, but the data will be wiped from `localStorage`/`sessionStorage`.\n\n```js\nmyBin.remove();\n```\n\n\n\n## Browser Compatibility\n\nBin works in all modern browsers, and IE 8 and above.\n\n\n\n## License\n\nThe code is available under the [MIT License](LICENSE.md).","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcferdinandi%2Fbin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcferdinandi%2Fbin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcferdinandi%2Fbin/lists"}