JarCastingstorage-engine
The storage-engine module is an high level abstraction for React-Native's AsyncStorage. It allows you to easily customize the AsyncStorage using plugins. These plugins can be applied to all keys, or just specific key patterns giving you immense flexibility in the storage layer that you're creating.
Installation
The package is released in the public npm registry and can be installed by running:
npm install --save storage-engine
The AsyncStorage API has been moved to the React-Native Community as part of their lean-core initiative and should now be installed as separate package:
npm install --save @react-native-community/async-storage
react-native link @react-native-community/async-storage
Table of Contents
Usage
import storage, { StorageEngine } from 'storage-engine';
We export a pre-initialized StorageEngine class by default so you can use the API directly when you import the module. If you wish, you can create your own instance by initializing a new StorageEngine class.
The storage instance has the following methods:
Enhanced AsyncStorage methods:
- getItem
- setItem
- removeItem
- mergeItem
- clear
- getAllKeys
- flushGetRequests
- multiGet
- multiSet
- multiMerge
- multiRemove
before
The before method allows you to pre-process any AsyncStorage API call. You can intercept the request, change values, or even change keys. Want to merge data with an remote data source? We gotchu, want to cancel a request, hell yeah.
import storage from 'storage-engine';
storage.before('key*, another, more*', {
setItem: function ({ key, value, method }) {
console.log(method); // setItem
console.log(key); // key-here
console.log(value); // bar
return {
value: 'Completely different value'
}
}
});
storage.after('*', {
setItem: function ({ key, value, method }) {
console.log(method); // setItem
console.log(key); // key-here
console.log(value); // Completely different value
},
getItem: function ({ key, value, method }) {
console.log(method); // getItem
console.log(key); // key-here
console.log(value); // undefined
}
})
await storage.setItem('key-here', 'bar');
const value = await storage.getItem('key-here');
console.log(value); // Completely different value
In the example above, we've added a before hook that is triggered when the setItem api is called. We can see which key is used, and which value would be assigned. We've then returned a completely different value from the hook which would be stored instead of the original provided value.
The before method accepts the following arguments:
keyA pattern of keys that would need to trigger the assignedbeforemethod. It can bekey1, key1, another-keyor use the*wildcard for all keys, or even a combinationkey*, another-key, *bar, which would matchkey1,key0afaf,another-key,foobar,bbaretc.methodsAn object where the key's are the names of the methods you would like to pre-process, and the value the(async)functionthat would handle the pre-processing. If you supply a(async)functioninstead of an object, it would be called for all available methods.optionsAdditional options:order: Allows you control the order of execution of your function, placing before or after other added methods in the execution chain. The order is set by default to100if no option is provided. The higher value, the important it is to execute this function early. So a9000will be executed before a order100and an order of0would be executed last.
After
Exactly the same interface as before, but instead of pre processing this method allows you to post process the response of the AsyncStorage API call.
See before for API and example.
plugin
The plugin API allows you to load any custom plugin that can enhance your storage instance. A plugin is basically an (async) function that is executed with a bunch of plugin helper functions.
import storage from 'storage-engine';
import { expire } from 'storage-modifiers';
storage.use('token*', expire, {
duration: '30 minutes'
});
storage.use('pattern*', async function example(plugin) {
const { before, after, destroy, options } = plugin;
//
// Main difference here is that plugins don't need to prefix before and
// after functions with the pattern, this is done automatically.
//
before({
getItem: () => {}
});
destroy(function () {
//
// Called when `storage.destroy()` is invoked.
//
});
console.log(options); // { options: 'here'}
}, {
options: 'here'
});
The plugin API accepts the following arguments:
patternThe key pattern that it should be triggered on.pluginThe actual plugin which can be anasyncor normal JavaScript function that will be executed with our Plugin API.optionsAdditional options for the plugin.
Please note, we do offer default plugins which are available in a separate module, storage-modifiers which provides useful features such as:
- json: Automatic encoding, and decoding of values
- emit: Emits an event when a given key, or method is accessed (configurable)
- expire: Expires key/values based on a given TTL
- encrypt: Adds an additional layer of protection by encrypting the data you store.
Plugin API
When the plugin is executed by the plugin it will be executed with an object that contains the following properties and helper functions.
beforeReference to the before method, but prefixed by default with thepatternthat was supplied to the plugin.afterReference to the after method, but prefixed by default with thepatternthat was supplied to the plugin.enabledFunction that checks if the passedkeyargument is enabled by the pattern that was supplied to the plugin, returns a boolean,enabled(key).destroyFunction that allows you to register a (async) clean-up callback which is executed when the destroy method is called.patternThe pattern that was supplied to the plugin as first argument.engineReference to the initialized storage instance.optionsThe options that was supplied to the plugin as third argument.
destroy
Destroy the initialized storage instance by removing all plugins, before, and after hooks. This will call any destroy hook that are defined by plugins but it does not trigger the clear method, so the data that you stored is untouched.
import storage from 'storage-engine';
storage.before('*', {
setItem: () => ({
value: 'all your values are this now, lol'
})
});
await storage.setItem('foo', 'bar');
await storage.getItem('foo') // all your values are this now, lol
await storage.destroy();
await storage.setItem('foo', 'bar');
await storage.getItem('foo') // bar
api
Provides direct access to the AsyncStorage API that we're wrapping. This API will not execute any of the plugins or before/after modifications that are registered. This is the API we use internally to communicate with AsyncStorage.
import storage from 'storage-engine';
await storage.api('setItem', 'foo', 'bar');
The method accepts the following arguments:
methodThe name of the method that needs to be executed....argsThe args that you would have normally passed into the original API.
The rest of the API methods are the API methods that exist on the AsyncStorage API that is provided by React-Native / React-Native Community. Some of the API have been enhanced to allow a more sensible argument or return format. For example, we only allow the async/await interface instead of an additional 3rd callback argument. We're just gonna go briefly over this API and make the assumption that you already have prior knowledge of the existing React-Native AsyncStorage API:
getItem
The getItem allows you to retrieve a previously stored value. When the value does not exist, a null will be returned instead.
const value = await storage.getItem('key');
console.log(value); // key
keyThe key of the value you want to retrieve.
setItem
Stores a new item. Yup, that's it.
await storage.setItem('key', 'value');
keyThe key where the value will be stored at.valueThe contents that needs to be stored, should be string, unless a plugin allows you to use a different format.
removeItem
Removes the previously stored value.
await storage.removeItem('key');
keyThe key of the value you want to remove.
mergeItem
Merge the contents of the key, with the supplied value.
await storage.mergeItem('key', '{"json": "here"}');
keyThe key of the value you want to update.valueA stringified JSON object that will be merged with the existing value
clear
Removes all the data that you've stored. Everything. Gone. Forever. Like it never existed. This method is officially approved by Thanos.
await storage.clear();
getAllKeys
Retrieve all keys that are stored in the AsyncStorage.
const keys = await storage.getAllKeys();
flushGetRequests
Does anyone actually this method? Why am I even documenting this.
await storage.flushGetRequests();
multiGet
Retrieves multiple values at once.
const [one, two] = await storage.multiGet(['one', 'two']);
// one: { key: one, value: ... }
// two: { key: two, value: ... }
The data that is returned by the multi API is slightly different, as we've wrapped each item in an object which has
key, andvalueproperty.
multiSet
Store multiple values at once.
await storage.multiSet([
['one', 'value'],
['two', 'another value']
]);
//
// Also supported:
//
await storage.multiSet([
{ key: 'one', value: 'value' },
{ key: 'two', value, 'another value' }
]);
The data that is returned by the multi API is slightly different, as we've wrapped each item in an object which has
key, andvalueproperty.
multiMerge
Merge multiple values at once.
await storage.multiMerge([
['key', '{"json": "blob"}'],
['another', '{"cow": "moo"}']
]);
//
// Also supported:
//
await storage.multiMerge([
{ key: 'key', value: '{"json": "blob"}'},
{ key: 'another', value: '{"cow":"moo"}'}
]);
The data that is returned by the multi API is slightly different, as we've wrapped each item in an object which has
key, andvalueproperty.
multiRemove
Thanos multiple keys at once.
await storage.multiRemove(['one', 'two']);
The data that is returned by the multi API is slightly different, as we've wrapped each item in an object which has
key, andvalueproperty.