Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/bjnstnkvc/js-local-storage
Simple wrapper for JavaScript Local Storage API.
https://github.com/bjnstnkvc/js-local-storage
javascript localstorage
Last synced: 17 days ago
JSON representation
Simple wrapper for JavaScript Local Storage API.
- Host: GitHub
- URL: https://github.com/bjnstnkvc/js-local-storage
- Owner: BJNSTNKVC
- License: mit
- Created: 2024-01-29T19:33:11.000Z (about 1 year ago)
- Default Branch: master
- Last Pushed: 2024-03-14T20:42:25.000Z (11 months ago)
- Last Synced: 2024-04-23T20:15:27.501Z (10 months ago)
- Topics: javascript, localstorage
- Language: TypeScript
- Homepage:
- Size: 22.5 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# LocalStorage
A class that provides a set of methods for interacting with the browser's local storage.
## Installation & setup
### NPM
You can install the package via npm:
```bash
npm install @bjnstnkvc/local-storage
````
and then import it into your project
```javascript
import { LocalStorage } from '@bjnstnkvc/local-storage';
```
### CDN
You can install the package via jsDelivr CDN:
```html
```
## Usage
### set
Set the value for a given key in the Local Storage.
#### Parameters
- **key** - String containing the name of the key.
- **value** - The value to be stored.
- **ttl** *(optional)* - Time to live in seconds for the key. Defaults to `null` (no expiration) or equal to [LocalStorage.ttl](#ttl) value.
#### Example
```javascript
LocalStorage.set('key', 'value', 60);
```
### get
Retrieve the value associated with the given key from the Local Storage.
#### Parameters
- **key** - String containing the name of the key.
- **fallback** *(optional)* - The fallback value in case the key does not exist. Defaults to `null`.
#### Example
```javascript
LocalStorage.get('key', 'default');
````
You can also pass a closure as the default value. If the specified item is not found in the Local Storage, the closure will be executed and its result returned.
This allows you to lazily load default values from other sources:
```javascript
LocalStorage.get('key', () => 'default');
````
>**Note:** When you attempt to retrieve a value using the `get` method, it checks if the item has expired based on its TTL (Time-To-Live). If the item has indeed expired, it is automatically removed from the LocalStorage, ensuring that your application only works with valid, up-to-date data.
### remember
Retrieve the value associated with the given key, or execute the given callback and store the result in the Local Storage.
#### Parameters
- **key** - String containing the name of the key.
- **fallback** - Function you want to execute.
- **ttl** *(optional)* - Time to live in seconds for the key. Defaults to `null` (no expiration) or equal to [LocalStorage.ttl](#ttl) value.
#### Example
```javascript
LocalStorage.remember('key', () => 'default', 60);
````
### all
Retrieve an object containing all keys and their associated values stored in the Local Storage.
#### Example
```javascript
LocalStorage.all();
```
### remove
Remove the key and its associated value from the Local Storage.
#### Parameters
- **key** - String containing the name of the key to be deleted.
#### Example
```javascript
LocalStorage.remove('key');
```
### clear
Clear all keys and their associated values from the Local Storage.
#### Example
```javascript
LocalStorage.clear();
```
### has
Check if a key exists in the Local Storage.
#### Parameters
- **key** - String containing the name of the key to be checked.
#### Example
```javascript
LocalStorage.has('key');
```
### hasAny
Check if any of the provided keys exist in the Local Storage.
#### Parameters
- **keys** - String or an array of strings containing the names of the keys to be checked.
#### Example
```javascript
LocalStorage.hasAny(['key1', 'key2']);
```
### isEmpty
Check if the Local Storage is empty.
#### Example
```javascript
LocalStorage.isEmpty();
```
### isNotEmpty
Check if the Local Storage is not empty.
#### Example
```javascript
LocalStorage.isNotEmpty();
```
### keys
Retrieve an array containing all keys stored in the Local Storage.
#### Example
```javascript
LocalStorage.keys();
```
### count
Retrieve the total number of items stored in the Local Storage.
#### Example
```javascript
LocalStorage.count();
```
### touch
Update the expiration time of a key in the Local Storage.
#### Parameters
- **key** - String containing the name of the key.
- **ttl** *(optional)* - Time to live in seconds for the key. Defaults to `null` (no expiration) or equal to [LocalStorage.ttl](#ttl) value.
#### Example
```javascript
LocalStorage.touch('key', 60);
```
### expiry
Retrieve the expiration date for a given key.
#### Parameters
- **key** - String containing the name of the key you want to check against
- **ttl** *(optional)* - If true, returns the expiration date as a Date object. Defaults to `false`.
#### Example
```javascript
LocalStorage.expiry('key');
```
You can also pass a boolean as the second parameter to return the expiration date as a Date object:
```javascript
LocalStorage.expiry('key', true);
```
### dump
Print the value associated with a key to the console.
#### Parameters
- **key** - String containing the name of the key.
#### Example
```javascript
LocalStorage.dump('key');
```
### ttl
Define a global Time-To-Live (TTL) in seconds for all items saved using the [LocalStorage.set](#set) or [LocalStorage.touch](#touch) method, without specifying a TTL for each item. This can be particularly useful for applications needing a consistent expiry policy for most stored data.
#### Example
```javascript
LocalStorage.ttl(7200);
```
If a default TTL has been set using `LocalStorage.ttl`, it will be applied to all items set without a specified TTL.