storage-utils
A set of functions that makes caching using the Storage interface (localStorage, sessionStorage) easy. It's extremely lightweight, well tested, and comes with top-notch TypeScript definitions out of the box. Documentation generated from source found here.
Features
- New Reach hook for seamless caching
- Invalidation of cached items after a period of time when specified (simple using the conversion functions that are included)
- Stale data is passed back to the getData callback so that only 'new' data needs to be fetched over the network
getHighlyAvailableallows using a function that will optionally resolve twice. Once with the cached data, and then with the fetched data (if the cache has expired).
API
Examples
Barebones
getOrAdd(
localStorage,
"someUniqueKey",
fetchItems,
convertMinutesToMilliseconds(5) // considered valid for 5 minutes
).then((items) => {
// data here is either coming from the cache or the fetch we provided
console.log(items);
});React Caching Hook
import React from "react";
import { useCache, convertMinutesToMilliseconds } from "storage-utils";
import { get } from "./RestClient"; // not in this library
const url = "/api/name";
const fetchName = () => get<string>(url);
export function Name() {
let name = useCache(
localStorage, // localStorage will save across browser sessions
url, // using the url as a cache key, but this depends on the use
fetchName, // can be anything that returns a promise of something
0, // immediately consider this value dirty
true // use an expired value from the cache if it exists
);
// loading will only ever be shown the very first time
// since we are using the option to use the expired
// value from cache while the fetch processes in the
// background and eventually causes a re-render
if (name === undefined) return <div>Loading</div>;
return <div>{name}</div>;
}Index
Functions
convertDaysToMilliseconds
-
Parameters
-
days: number
Returns number
-
convertHoursToMilliseconds
-
Parameters
-
hours: number
Returns number
-
convertMinutesToMilliseconds
-
Parameters
-
minutes: number
Returns number
-
convertSecondsToMilliseconds
-
Parameters
-
seconds: number
Returns number
-
getHighlyAvailable
-
Type parameters
-
T
Parameters
-
storage: Storage
storage to use. i.e. localStorage, sessionStorage
-
key: string
unique string used as cache key to storage
-
getData: (expiredData?: T) => Promise<T>
returns a promise used to fetch the data
-
-
Parameters
-
Optional expiredData: T
Returns Promise<T>
-
-
-
-
ttl: number
Max time to live in milliseconds
-
resolve: (data: T) => any
function called with the value from the fetch if expired
-
-
Parameters
-
data: T
Returns any
-
-
-
Returns T | undefined
The data from the cache, whether it's expired or not. undefined if it wasn't in the cache at all
-
getOrAdd
-
Type parameters
-
T
Parameters
-
storage: Storage
storage to use. i.e. localStorage, sessionStorage
-
key: string
unique string used as cache key to storage
-
getData: (expiredData?: T) => Promise<T>
returns a promise used to fetch the data from if it's not in cache
-
-
Parameters
-
Optional expiredData: T
Returns Promise<T>
-
-
-
-
Optional ttl: undefined | number
Max time to live in milliseconds
-
Optional useExpired: undefined | false | true
If true, will return expired items from cache while updating in the background.
Returns Promise<T>
-
useCache
-
Hook to easily enable caching to an async call. Implemented in a way such that when reading from cache, there is no 'bad' value initially acted on as that bit of state. This means when reading from the cache, you won't have a double render
Type parameters
-
T
Parameters
-
storage: Storage
storage to use. i.e. localStorage, sessionStorage
-
key: string
unique string used as cache key to storage
-
getData: (t: T | undefined) => Promise<T>
returns a promise used to fetch the data
-
-
Parameters
-
t: T | undefined
Returns Promise<T>
-
-
-
-
ttl: number
Time until expired in milliseconds
-
Default value useExpired: boolean = true
if true, the data will be set to the expired value from the cache until getData completes
Returns T | undefined
State that is populated from cache, fetch or both
-
Generated using TypeDoc