AsyncStorageWithKeyScope
AsyncStorage
, which was created as a React Native API. Amazon will deprecate the AsyncStorage
API in a future release. Kepler version 0.8 introduces the react-native-async-storage
library. Use the react-native-async-storage
library for any apps built with Kepler version 0.8 or later.AsyncStorageWithKeyScope
is an abstraction built on top of AsyncStorage
for Kepler. It implements the same API with some restrictions: It adds a clearScope()
method to be used instead of the clear()
method and Kepler's removeValuesForKeysWithPrefix()
method.
AsyncStorage
is an unencrypted, asynchronous, persistent, key-value storage system that is global to the app. It should be used instead of LocalStorage.
AsyncStorageWithKeyScope
allows you to create instances with a scope prefix string you define. The instance will then transparently prepend all keys with that scope prefix followed by an _
when you make calls to the instance's APIs and remove the prepended prefix and underscore when returning results.
The AsyncStorageWithKeyScope
JavaScript code is a facade that provides a clear JavaScript API, real Error
objects, and non-multi functions. Each method in the API returns a Promise
object.
Importing the AsyncStorageWithKeyScope
library:
import {AsyncStorageWithKeyScope} from '@amzn/react-native-kepler';
Persisting data:
const scopedAsyncStore = new AsyncStorageWithKeyScope("MyAppVideoSettings");
_storeData = async () => {
try {
await scopedAsyncStore.setItem(
'description',
'I like to save it.',
);
} catch (error) {
// Error saving data
}
};
Fetching data:
const scopedAsyncStore = new AsyncStorageWithKeyScope("MyAppVideoSettings");
_retrieveData = async () => {
try {
const value = await scopedAsyncStore.getItem('description');
if (value !== null) {
// We have data!!
console.log(value);
}
} catch (error) {
// Error retrieving data
}
};
Reference
Methods
constructor()
constructor(scopePrefix)
Constructs a AsyncStorageWithKeyScope instance with a designated scope prefix string.
Parameters:
Name | Type | Required | Description |
---|---|---|---|
scopePrefix | string | Yes | A non empty string to transparently prefix store keys with |
getItem()
getItem(key: string, [callback]: ?(error: ?Error, result: ?string) => void)
Fetches an item for a key
and invokes a callback upon completion. Returns a Promise
object.
Parameters:
Name | Type | Required | Description |
---|---|---|---|
key | string | Yes | Key of the item to fetch. |
callback | ?(error: ?Error, result: ?string) => void |
No | Function that will be called with a result if found or any error. |
setItem()
setItem(key: string, value: string, [callback]: ?(error: ?Error) => void)
Sets the value for a key
and invokes a callback upon completion. Returns a Promise
object.
Note: Ensure your keys are determinate or you may not be able to get or remove them later. Keys with timestamps or other variable information may be difficult to identify later and could result in wasted storage.
Parameters:
Name | Type | Required | Description |
---|---|---|---|
key | string | Yes | Key of the item to set. |
value | string | Yes | Value to set for the key . |
callback | ?(error: ?Error) => void |
No | Function that will be called with any error. |
removeItem()
removeItem(key: string, [callback]: ?(error: ?Error) => void)
Removes an item for a key
and invokes a callback upon completion. Returns a Promise
object.
Parameters:
Name | Type | Required | Description |
---|---|---|---|
key | string | Yes | Key of the item to remove. |
callback | ?(error: ?Error) => void |
No | Function that will be called with any error. |
clearScope()
clearScope([callback]: ?(error: ?Error) => void)
Remove all values in the store whose keys are prefixed with the scope prefix + '_'.
Parameters:
Name | Type | Required | Description |
---|---|---|---|
callback | ?(error: ?Error) => void |
No | Function that will be called with any error. |
multiGet()
multiGet(keys: Array<string>, [callback]: ?(errors: ?Array<Error>, result: ?Array<Array<string>>) => void)
This allows you to batch the fetching of items given an array of key
inputs. Your callback will be invoked with an array of corresponding key-value pairs found:
multiGet(['k1', 'k2'], cb) -> cb([['k1', 'val1'], ['k2', 'val2']])
The method returns a Promise
object.
Parameters:
Name | Type | Required | Description |
---|---|---|---|
keys | Array<string> |
Yes | Array of key for the items to get. |
callback | ?(errors: ?Array<Error>, result: ?Array<Array<string>>) => void |
No | Function that will be called with a key-value array of the results, plus an array of any key-specific errors found. |
Example:
const scopedAsyncStore = new AsyncStorageWithKeyScope("MyAppUserSettings");
const keys = ['key1', 'key2', 'key3'];
scopedAsyncStore.multiGet(keys, (err, stores) => {
stores.map((result, i, store) => {
// get at each store's key/value so you can work with it
let key = store[i][0];
let value = store[i][1];
});
});
multiSet()
multiSet(keyValuePairs: Array<Array<string>>, [callback]: ?(errors: ?Array<Error>) => void)
Use this as a batch operation for storing multiple key-value pairs. When the operation completes you'll get a single callback with any errors.
Note: Ensure your keys are determinate or you may not be able to get or remove them later. Keys with timestamps or other variable information may be difficult to identify later and could result in wasted storage.
multiSet([['k1', 'val1'], ['k2', 'val2']], cb);
The method returns a Promise
object.
Parameters:
Name | Type | Required | Description |
---|---|---|---|
keyValuePairs | Array<Array<string>> |
Yes | Array of key-value array for the items to set. |
callback | ?(errors: ?Array<Error>) => void |
No | Function that will be called with an array of any key-specific errors found. |
multiRemove()
multiRemove(keys: Array<string>, [callback]: ?(errors: ?Array<Error>) => void)
Call this to batch the deletion of all keys in the keys
array. Returns a Promise
object.
Parameters:
Name | Type | Required | Description |
---|---|---|---|
keys | Array<string> |
Yes | Array of key for the items to delete. |
callback | ?(errors: ?Array<Error>) => void |
No | Function that will be called an array of any key-specific errors found. |
Example:
const scopedAsyncStore = new AsyncStorageWithKeyScope("MyAppUserSettings");
let keys = ['k1', 'k2'];
scopedAsyncStore.multiRemove(keys, err => {
// keys k1 & k2 removed, if they existed
// do most stuff after removal (if you want)
});
Last updated: Sep 30, 2025