https://github.com/fuhton/timedstorage
A library for storing and expiring objects in window.localstorage
https://github.com/fuhton/timedstorage
Last synced: about 2 months ago
JSON representation
A library for storing and expiring objects in window.localstorage
- Host: GitHub
- URL: https://github.com/fuhton/timedstorage
- Owner: fuhton
- Created: 2018-01-23T01:23:00.000Z (almost 8 years ago)
- Default Branch: master
- Last Pushed: 2018-09-28T18:59:39.000Z (over 7 years ago)
- Last Synced: 2025-11-04T17:19:26.935Z (2 months ago)
- Language: JavaScript
- Homepage:
- Size: 76.2 KB
- Stars: 4
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
- awesome-web-dev-resources - timedstorage
README
🕐 📁 timedstorage
> Disclaimer: This is a very stable project with a very focused use-case. This project is actively used and maintained (as needed).
# timedstorage
> A tiny library for storing and expiring objects in localstorage.
- **Small** ~650b footprint
- **Convenient** Similar API to window.localStorage
- **Useful** Storage objects that expire in localstorage
## Table of Contents
- [Install](#install)
- [Usage](#usage)
- [Examples](#examples)
- [API](#api)
- [License](#license)
## Install
This project uses [node](http://nodejs.org) and [npm](https://npmjs.com).
```sh
npm install --save timedstorage
```
Then with a module bundler like [webpack](https://webpack.js.org) or another bundling solution:
```js
import { deleteItem, getItem, setItem } from 'timedstorage';
```
The [UMD](https://github.com/umdjs/umd) build is also available. Pull the repo down locally and run `npm run build`.
You'll find the library on `window.timedstorage`.
### Usage
```js
import { deleteItem, getItem, setItem } from 'timedstorage';
// the time module gives helpful shortcuts for time in milliseconds
import * as time from 'timedstorage/time';
async function getUserData() {
// Retrieve the item from localstorage
let userData = getItem('user_key');
if (!userData) {
const response = await fetch('/user_endpoint');
// Set the item with your key
// `response` (the passed value to be saved) is expected to be an object
userData = setItem('user_key', response, time.HOUR);
}
return userData;
}
function deleteUserData() {
// Delete the item by key
return deleteItem('user_key');
}
```
### Debug
Pop open the console and access your data directly and confirm it is correct.
```js
console.log(window.localstorage.getItem('KEY_NAME'));
```
### Examples
Interactive example on CodeSandbox.io -
### API
##### Table of Contents
- [deleteItem](#deleteitem)
- [getItem](#getitem)
- [setItem](#setitem)
#### deleteItem
Removes an object by key from localstorage
**Parameters**
- `key` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** Key to remove
**Examples**
```javascript
return deleteItem('KEY');
```
Returns **[undefined](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/undefined)**
#### getItem
Get an item from localstorage by key. If it's expired or there is issue with any part of the
data object, delete the item and return null.
**Parameters**
- `key` **[string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)** Key to remove
**Examples**
```javascript
return getItem('KEY');
```
Returns **(null | [Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object))**
#### setItem
Set an object into localstorage by key. Requires value to be an object. Expected expiration to
be an int of milliseconds
**Parameters**
- `key` **Int** Length of time in milliseconds
- `value` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)** Object value to save
- `expiration`
**Examples**
```javascript
return setItem('KEY', { data: 'wow' }, time.HOUR)
```
Returns **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)**
### Reporting Issues
Found a problem? Want a new feature? Open a [clear and descriptive issue](../../issues/new).
### License
MIT © [Nicholas Smith](https://fuhton.com)