ttl-localstorage ================ API for Browser localStorage and Node contexts. Installation ------------ npm i ttl-localstorage Browser localStorage --------------------- The subtle quirks of HTML5's localStorage are replaced with a simple API that is intuitive to use and just gets the job done. You may be wondering: Isn't localStorage's native interface already simple to use? Why do I need to use ttl-localstorage at all? You certainly can use the native API, but if you do, you'll quickly discover that: - native localStorage has no optional timeout - native localStorage can only store strings ttl-localstorage fixes these limitations. Node.js Context ---------------- Sometimes we want an ultra simple way to store and retrieve objects on the back end in Node, without having to set up yet another db or key-value store. ttl-localstorage can be used in a pure Node environment, without a browser. Examples below demonstrate how this is done. Usage and Examples ------------------ __Use LocalStorage for Browser, MemoryStorage for Node__ Whereas the browser can use either the LocalStorage or the MemoryStorage module, Node contexts can only use the MemoryStorage module. The following examples use the LocalStorage module, but MemoryStorage can use the same methods. ```javascript import { LocalStorage } from 'ttl-localstorage'; OR import { MemoryStorage } from 'ttl-localstorage'; // store const data = { a: 1, b: true, stuff: { n: [2, 3, 5], composer: 'Stravinsky' } }; LocalStorage.put('myKey', data); // retrieve const data = LocalStorage.get('myKey'); ``` __More About Retrieving Stored Data__ Inspired by Python's get() method, an optional 2nd arg is available. ```javascript import { LocalStorage } from 'ttl-localstorage'; // Retrieve a key which does not exist: const data = LocalStorage.get('badKey'); // data => null // Retrieve a key which does not exist using an optional 2nd arg LocalStorage.get('badKey', { a: 1, b: 2 }); // data => { "a": 1, "b": 2 } ``` TTL: Setting Timeouts ===================== Standard localStorage data remains available until it is manually deleted by the user. We fixed that so the developer gets back in control. ttl-localstorage allows a timeout to be set globally for all keys. This timeout mechanism works for both LocalStorage and MemoryStorage usage. __Global Timeout for All Keys__ Just set the timeout once before put operations. Granularity has been kept to seconds instead of finer, impractical time units. ```javascript import { LocalStorage } from 'ttl-localstorage'; LocalStorage.timeoutInSeconds = 300; LocalStorage.put(myKey, data); // myKey can't access the stored data after 5 minutes has elapsed. ``` The global timeout is disabled by default (timeoutInSeconds is initialized to null). __Key Level Timeout__ Set a timeout on a per-key basis. If a global timeout had already been set, the key level timeout takes priority. ```javascript import { LocalStorage } from 'ttl-localstorage'; // key will expire in 10 minutes (optional third argument) LocalStorage.put(ephemeralKey, data, 600); // key will expire in 1 day LocalStorage.put(dailyKey, data, 86400); ``` __Utilities__ `keyExists(key)` behaves thusly: If no timeout is set (the default), then the method resolves to true if key exists, false otherwise. However, if a timeout has been set, then `keyExists()` method behaves slightly differently. If no key found, resolves to false. If key exists and the timeout has not yet expired, resolves to true; if key exists and timeout indicates this key has expired, then the key is removed and then resolves to false. ```javascript const result = LocalStorage.keyExists(key); // result => boolean ``` `removeKey(key)`, as its name suggests, merely removes the key if it exists. If the key does not exist, it's a no-op. ```javascript LocalStorage.removeKey(key); // key has been removed ``` `clear()` removes all keys and data. `keys()` returns a list of keys. ```javascript const keyList = LocalStorage.keys(); ``` `isLocalStorageAvailable()` detects if localStorage is available. This can happen, for example, if iPhone's Safari browser is in private mode, in which case you can either alert the user to turn off private mode or just use MemoryStorage instead of LocalStorage. ```javascript const isAvailable = LocalStorage.isLocalStorageAvailable(); isAvailable => boolean ``` __The Cleaner: Optional Garbarge Collection__ ttl-localstorage lazily removes keys if not explicitly removed via \#removeKey; if a key is accessed either via #get or #keyExists, the key is automatically removed if a timeout indicates the key has expired. There is no garbage collector mechanism always running to periodically clean things up. However, if you don't want expired keys lying around, just execute runGarbageCollector() to manually clean up all keys that haven't been lazily deleted. ```javascript const removedKeys = LocalStorage.runGarbageCollector(); ``` Credits ------- Gerry Gold June December 2021 Have fun!

ttl-localstorage

Downloads in past1 Month3 Months6 Months1 Year2 Years5 YearsAll time

Stats

Sick of boring JavaScript newsletters?

Downloads in past