money-clip
v3.0.5
Published
For managing your client side cache. Tiny wrapper over IndexedDB supporting versioning and max age.
Downloads
8,651
Readme
money-clip
For managing your client side cache. Tiny wrapper over Jake Archibald's tiny IndexedDB wrapper, idb-keyval adding support for versioning and max age.
Designed for use in PWAs that need to cache data fetched from APIs and such.
It exposes mostly the same cache API with a few extras:
getAll
added by this libgetConfiguredCache
lets you pre-apply optionsget
set
keys
clear
del
These will all swallow errors because it's designed to work as an enhancement to a PWA. If something fails you simply don't start with a primed cache of data for your app. Nothing lost.
Clientside caching of user data is great, but can also be treacherous. We need some way to version our data, make sure we don't populate our app with really stale data, or populate the app with data from a previous session.
This library provides a way to deal with these issues. On every write or read, you can provide a version number (usually a version number stored in a config in your app). In addition to storing the data itself, this library will also store a timestamp and the version number (if provided).
When trying to read the cache when your application starts, if the data is too stale, or there's a version number mismatch, the previous entry is just deleted, and null
is returned. In this way, you can throw away potentially problematic cached data by bumping a version number in your config.
If you want to ensure you don't inflate cached data from another user, you can combine a version number in your config with some identifier of the user's session to build a version string. This means that if a different session is used when opening the app, it will lead to a version mismatch and the existing cached will be deleted.
install
npm install money-clip
API
note: All methods take the same optional options:
const options = {
version: 1, // this can be any string or number
maxAge: Infinity, // in number of milliseconds
}
getAll(options)
Returns promise that will resolve to an object of all values or {}
. Any single key that fails the version/age check will be deleted and not included. Never throws errors.
get(key, options)
Returns Promise that will resolve to value at key, or null
. If it fails version checks or age checks, it will be deleted. Never throws errors.
set(key, options)
Returns promise sets value at key. Never throws.
keys()
Returns promise that resolve to object keys
del(key)
Returns promise but deletes content of key.
clear()
Returns promise and clears everything in cache.
getConfiguredCache(options)
Returns an object with all the methods listed above, but with pre-populated options. So if you prefer you can configure version and max age once, then just use get
/set
without passing options.
This function also takes one additional option: name
which lets you name the database / store. This can be useful if you need to create different caches for different categories of data.
example
If you're using Redux, you could, for example combine this with redux-persist-middleware to lazily cache content of certain reducers when certain action types occur.
import { h, render } from 'preact'
import { Provider } from 'preact-redux'
import { getConfiguredCache } from 'money-clip'
import { createStore, applyMiddleware } from 'redux'
import ms from 'milliseconds'
import rootReducer from './somewhere'
import RootComponent from './components/root'
import getPersistMiddleware from 'redux-persist-middleware'
import config from './my-config'
// get a version of the cache lib with options pre-applied
const cache = getConfiguredCache({
version: config.cacheVersion,
maxAge: ms.days(30),
name: 'user-data',
})
cache.getAll().then(data => {
const store = createStore(
rootReducer,
data,
applyMiddleware(getPersistMiddleware(cache.set))
)
render(
<Provider store={store}>
<RootComponent />
</Provider>,
document.getElementById('app')
)
})
Change log
3.0.5
: Updated to fix issue w/ update that involved changed exports fromidb-keyval
during upgrade, sorry!3.0.4
: Updated dependencies to get Safari fix added toidb-keyval
lib. Thanks @rickharris!3.0.3
: Export keyval lib itself3.0.2
: FixedconfiguredCache.del
to actually work3.0.1
: doc fix3.0.0
: idb-keyval was not being transpiled to es5 causingclass
to be used in the final bundle of some of my apps. Turns off compression and minification of build, that's a concern for final packaging.2.1.0
: Added support for passingname
option to.getConfiguredCache()
to name the IDB database.2.0.2
: Updated to latestidb-keyval
, no API change in this lib.2.0.1
: Fixed bug whereclear
was not being exported after build.2.0.0
: added.getConfiguredCache()
renamed methods to more closely align withidb-keyval
. Exportkeys
,del
, andclear
directly. Tests, example, readme.1.0.0
: initial release
credits
If you like this follow @HenrikJoreteg on twitter.