EventEmitter abstraction on top the React-Native AsyncStorage API
npm install storage-engineThe 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.
The package is released in the public npm registry and can be installed
by running:
``sh`
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:
`sh`
npm install --save @react-native-community/async-storage
react-native link @react-native-community/async-storage
- Installation
- Usage
- before
- after
- plugin
- Plugin API
- destroy
- api
- getItem
- setItem
- removeItem
- mergeItem
- clear
- getAllKeys
- flushGetRequests
- multiGet
- multiSet
- multiMerge
- multiRemove
- License
`js`
import storage, { StorageEngine } from 'storage-engine';
We export a pre-initialized StorageEngine class by default so you can useStorageEngine
the API directly when you import the module. If you wish, you can create your
own instance by initializing a new class.
The storage instance has the following methods:
- before
- after
- plugin
- destroy
- api
Enhanced AsyncStorage methods:
- getItem
- setItem
- removeItem
- mergeItem
- clear
- getAllKeys
- flushGetRequests
- multiGet
- multiSet
- multiMerge
- multiRemove
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.
`js
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:
- key A pattern of keys that would need to trigger the assigned beforekey1, key1, another-key
method. It can be or use the * wildcard for allkey, another-key, bar
keys, or even a combination , which would matchkey1
, key0afaf, another-key, foobar, bbar etc.methods
- An object where the key's are the names of the methods you(async)function
would like to pre-process, and the value the that would(async)function
handle the pre-processing. If you supply a instead of anoptions
object, it would be called for all available methods.
- Additional options:order
- : Allows you control the order of execution of your function, placing100
before or after other added methods in the execution chain. The order is
set by default to if no option is provided. The higher value, the9000
important it is to execute this function early. So a will be executed100
before a order and an order of 0 would be executed last.
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.
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.
`js
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:
- pattern The key pattern that it should be triggered on.plugin
- The actual plugin which can be an async or normal JavaScriptoptions
function that will be executed with our Plugin API.
- Additional 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.
- before Reference to the before method, but prefixed by defaultpattern
with the that was supplied to the plugin.after
- Reference to the after method, but prefixed by defaultpattern
with the that was supplied to the plugin.enabled
- Function that checks if the passed key argument is enabled byenabled(key)
the pattern that was supplied to the plugin, returns a boolean, .destroy
- Function that allows you to register a (async) clean-up callbackpattern
which is executed when the destroy method is called.
- The pattern that was supplied to the plugin as firstengine
argument.
- Reference to the initialized storage instance.options
- The options that was supplied to the plugin as third
argument.
Destroy the initialized storage instance by removing all plugins, before,destroy
and after hooks. This will call any hook that are defined by plugins
but it does not trigger the clear method, so the data that you stored is
untouched.
`js
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
`
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.
`js
import storage from 'storage-engine';
await storage.api('setItem', 'foo', 'bar');
`
The method accepts the following arguments:
- method The name of the method that needs to be executed....args
- The 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:
---
The getItem allows you to retrieve a previously stored value. When the valuenull
does not exist, a will be returned instead.
`js`
const value = await storage.getItem('key');
console.log(value); // key
- key The key of the value you want to retrieve.
Stores a new item. Yup, that's it.
`js`
await storage.setItem('key', 'value');
- key The key where the value will be stored at.value
- The contents that needs to be stored, should be string, unless
a plugin allows you to use a different format.
Removes the previously stored value.
`js`
await storage.removeItem('key');
- key The key of the value you want to remove.
Merge the contents of the key, with the supplied value.
`js`
await storage.mergeItem('key', '{"json": "here"}');
- key The key of the value you want to update.value
- A stringified JSON object that will be merged with the existing value
Removes all the data that you've stored. Everything. Gone. Forever. Like
it never existed. This method is officially approved by Thanos.
`js`
await storage.clear();
Retrieve all keys that are stored in the AsyncStorage.
`js`
const keys = await storage.getAllKeys();
Does anyone actually this method? Why am I even documenting this.
`js`
await storage.flushGetRequests();
Retrieves multiple values at once.
`js
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, and value property.
Store multiple values at once.
`js
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, and value property.
Merge multiple values at once.
`js
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, and value property.
Thanos multiple keys at once.
`js`
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, and value` property.