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:

npm install @bjnstnkvc/local-storage

and then import it into your project

import { LocalStorage } from '@bjnstnkvc/local-storage';

CDN

You can install the package via jsDelivr CDN:

<script src="https://cdn.jsdelivr.net/npm/@bjnstnkvc/local-storage/lib/main.min.js"></script>

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 value.

Example

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) - Fallback value if the key does not exist. Can be provided as a string or an object with the following properties:
  • value - The fallback value to be used if the key does not exist.
  • ttl - Time to live in seconds for the fallback key if it needs to be set. Defaults to null (no expiration) or equal to LocalStorage.ttl value.
  • persist (optional) - Boolean indicating whether the fallback value should be persisted in the Local Storage. Defaults to false.

Example

LocalStorage.get('key', 'default');

LocalStorage.get('key', { value: 'default', ttl: 60, persist: true });

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.

all

Retrieve an object containing all keys and their associated values stored in the Local Storage.

Example

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

LocalStorage.remove('key');

clear

Clear all keys and their associated values from the Local Storage.

Example

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

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

LocalStorage.hasAny(['key1', 'key2']);

isEmpty

Check if the Local Storage is empty.

Example

LocalStorage.isEmpty();

isNotEmpty

Check if the Local Storage is not empty.

Example

LocalStorage.isNotEmpty();

keys

Retrieve an array containing all keys stored in the Local Storage.

Example

LocalStorage.keys();

count

Retrieve the total number of items stored in the Local Storage.

Example

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 value.

Example

LocalStorage.touch('key', 60);

dump

Print the value associated with a key to the console.

Parameters

• key - String containing the name of the key.

Example

LocalStorage.dump('key');

ttl

Define a global Time-To-Live (TTL) for all items saved using the LocalStorage.set or LocalStorage.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

LocalStorage.ttl(7200); // Set a default TTL of 2 hours (7200 seconds)

If a default TTL has been set using LocalStorage.ttl, it will be applied to all items set without a specified TTL.