diff --git a/AsyncStorage.js b/AsyncStorage.js index 0ba87ed..fb54d6b 100644 --- a/AsyncStorage.js +++ b/AsyncStorage.js @@ -21,45 +21,11 @@ const RCTAsyncStorage = NativeModules.AsyncRocksDBStorage || NativeModules.AsyncLocalStorage; /** - * @class - * @description - * `AsyncStorage` is a simple, unencrypted, asynchronous, persistent, key-value storage - * system that is global to the app. It should be used instead of LocalStorage. - * - * It is recommended that you use an abstraction on top of `AsyncStorage` - * instead of `AsyncStorage` directly for anything more than light usage since - * it operates globally. - * - * On iOS, `AsyncStorage` is backed by native code that stores small values in a - * serialized dictionary and larger values in separate files. On Android, - * `AsyncStorage` will use either [RocksDB](http://rocksdb.org/) or SQLite - * based on what is available. - * - * The `AsyncStorage` JavaScript code is a simple facade that provides a clear - * JavaScript API, real `Error` objects, and simple non-multi functions. Each - * method in the API returns a `Promise` object. - * - * Persisting data: - * ``` - * try { - * await AsyncStorage.setItem('@MySuperStore:key', 'I like to save it.'); - * } catch (error) { - * // Error saving data - * } - * ``` - * - * Fetching data: - * ``` - * try { - * const value = await AsyncStorage.getItem('@MySuperStore:key'); - * if (value !== null){ - * // We have data!! - * console.log(value); - * } - * } catch (error) { - * // Error retrieving data - * } - * ``` + * `AsyncStorage` is a simple, unencrypted, asynchronous, persistent, key-value + * storage system that is global to the app. It should be used instead of + * LocalStorage. + * + * See http://facebook.github.io/react-native/docs/asyncstorage.html */ var AsyncStorage = { _getRequests: ([]: Array), @@ -68,11 +34,8 @@ var AsyncStorage = { /** * Fetches an item for a `key` and invokes a callback upon completion. - * Returns a `Promise` object. - * @param key Key of the item to fetch. - * @param callback Function that will be called with a result if found or - * any error. - * @returns A `Promise` object. + * + * See http://facebook.github.io/react-native/docs/asyncstorage.html#getitem */ getItem: function( key: string, @@ -95,11 +58,8 @@ var AsyncStorage = { /** * Sets the value for a `key` and invokes a callback upon completion. - * Returns a `Promise` object. - * @param key Key of the item to set. - * @param value Value to set for the `key`. - * @param callback Function that will be called with any error. - * @returns A `Promise` object. + * + * See http://facebook.github.io/react-native/docs/asyncstorage.html#setitem */ setItem: function( key: string, @@ -121,10 +81,8 @@ var AsyncStorage = { /** * Removes an item for a `key` and invokes a callback upon completion. - * Returns a `Promise` object. - * @param key Key of the item to remove. - * @param callback Function that will be called with any error. - * @returns A `Promise` object. + * + * See http://facebook.github.io/react-native/docs/asyncstorage.html#removeitem */ removeItem: function( key: string, @@ -145,38 +103,11 @@ var AsyncStorage = { /** * Merges an existing `key` value with an input value, assuming both values - * are stringified JSON. Returns a `Promise` object. + * are stringified JSON. * * **NOTE:** This is not supported by all native implementations. * - * @param key Key of the item to modify. - * @param value New value to merge for the `key`. - * @param callback Function that will be called with any error. - * @returns A `Promise` object. - * - * @example Example - * let UID123_object = { - * name: 'Chris', - * age: 30, - * traits: {hair: 'brown', eyes: 'brown'}, - * }; - * // You only need to define what will be added or updated - * let UID123_delta = { - * age: 31, - * traits: {eyes: 'blue', shoe_size: 10} - * }; - * - * AsyncStorage.setItem('UID123', JSON.stringify(UID123_object), () => { - * AsyncStorage.mergeItem('UID123', JSON.stringify(UID123_delta), () => { - * AsyncStorage.getItem('UID123', (err, result) => { - * console.log(result); - * }); - * }); - * }); - * - * // Console log result: - * // => {'name':'Chris','age':31,'traits': - * // {'shoe_size':10,'hair':'brown','eyes':'blue'}} + * See http://facebook.github.io/react-native/docs/asyncstorage.html#mergeitem */ mergeItem: function( key: string, @@ -197,11 +128,11 @@ var AsyncStorage = { }, /** - * Erases *all* `AsyncStorage` for all clients, libraries, etc. You probably + * Erases *all* `AsyncStorage` for all clients, libraries, etc. You probably * don't want to call this; use `removeItem` or `multiRemove` to clear only - * your app's keys. Returns a `Promise` object. - * @param callback Function that will be called with any error. - * @returns A `Promise` object. + * your app's keys. + * + * See http://facebook.github.io/react-native/docs/asyncstorage.html#clear */ clear: function(callback?: ?(error: ?Error) => void): Promise { return new Promise((resolve, reject) => { @@ -218,11 +149,8 @@ var AsyncStorage = { /** * Gets *all* keys known to your app; for all callers, libraries, etc. - * Returns a `Promise` object. - * @param callback Function that will be called the keys found and any error. - * @returns A `Promise` object. * - * Example: see the `multiGet` example. + * See http://facebook.github.io/react-native/docs/asyncstorage.html#getallkeys */ getAllKeys: function(callback?: ?(error: ?Error, keys: ?Array) => void): Promise { return new Promise((resolve, reject) => { @@ -247,7 +175,11 @@ var AsyncStorage = { * indicate which key caused the error. */ - /** Flushes any pending requests using a single batch call to get the data. */ + /** + * Flushes any pending requests using a single batch call to get the data. + * + * See http://facebook.github.io/react-native/docs/asyncstorage.html#flushgetrequests + * */ flushGetRequests: function(): void { const getRequests = this._getRequests; const getKeys = this._getKeys; @@ -278,30 +210,9 @@ var AsyncStorage = { /** * 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. - * - * @param keys Array of key for the items to get. - * @param callback Function that will be called with a key-value array of - * the results, plus an array of any key-specific errors found. - * @returns A `Promise` object. - * - * @example Example - * - * AsyncStorage.getAllKeys((err, keys) => { - * AsyncStorage.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]; - * }); - * }); - * }); + * key-value pairs found. + * + * See http://facebook.github.io/react-native/docs/asyncstorage.html#multiget */ multiGet: function( keys: Array, @@ -341,19 +252,9 @@ var AsyncStorage = { /** * 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: + * the operation completes you'll get a single callback with any errors. * - * ``` - * multiSet([['k1', 'val1'], ['k2', 'val2']], cb); - * ``` - * - * The method returns a `Promise` object. - * - * @param keyValuePairs Array of key-value array for the items to set. - * @param callback Function that will be called with an array of any - * key-specific errors found. - * @returns A `Promise` object. - * Example: see the `multiMerge` example. + * See http://facebook.github.io/react-native/docs/asyncstorage.html#multiset */ multiSet: function( keyValuePairs: Array>, @@ -373,20 +274,9 @@ var AsyncStorage = { }, /** - * Call this to batch the deletion of all keys in the `keys` array. Returns - * a `Promise` object. - * - * @param keys Array of key for the items to delete. - * @param callback Function that will be called an array of any key-specific - * errors found. - * @returns A `Promise` object. - * - * @example Example - * let keys = ['k1', 'k2']; - * AsyncStorage.multiRemove(keys, (err) => { - * // keys k1 & k2 removed, if they existed - * // do most stuff after removal (if you want) - * }); + * Call this to batch the deletion of all keys in the `keys` array. + * + * See http://facebook.github.io/react-native/docs/asyncstorage.html#multiremove */ multiRemove: function( keys: Array, @@ -407,61 +297,11 @@ var AsyncStorage = { /** * Batch operation to merge in existing and new values for a given set of - * keys. This assumes that the values are stringified JSON. Returns a - * `Promise` object. - * + * keys. This assumes that the values are stringified JSON. + * * **NOTE**: This is not supported by all native implementations. - * - * @param keyValuePairs Array of key-value array for the items to merge. - * @param callback Function that will be called with an array of any - * key-specific errors found. - * @returns A `Promise` object. - * - * @example Example - * // first user, initial values - * let UID234_object = { - * name: 'Chris', - * age: 30, - * traits: {hair: 'brown', eyes: 'brown'}, - * }; - * - * // first user, delta values - * let UID234_delta = { - * age: 31, - * traits: {eyes: 'blue', shoe_size: 10}, - * }; - * - * // second user, initial values - * let UID345_object = { - * name: 'Marge', - * age: 25, - * traits: {hair: 'blonde', eyes: 'blue'}, - * }; - * - * // second user, delta values - * let UID345_delta = { - * age: 26, - * traits: {eyes: 'green', shoe_size: 6}, - * }; - * - * let multi_set_pairs = [['UID234', JSON.stringify(UID234_object)], ['UID345', JSON.stringify(UID345_object)]] - * let multi_merge_pairs = [['UID234', JSON.stringify(UID234_delta)], ['UID345', JSON.stringify(UID345_delta)]] - * - * AsyncStorage.multiSet(multi_set_pairs, (err) => { - * AsyncStorage.multiMerge(multi_merge_pairs, (err) => { - * AsyncStorage.multiGet(['UID234','UID345'], (err, stores) => { - * stores.map( (result, i, store) => { - * let key = store[i][0]; - * let val = store[i][1]; - * console.log(key, val); - * }); - * }); - * }); - * }); - * - * // Console log results: - * // => UID234 {"name":"Chris","age":31,"traits":{"shoe_size":10,"hair":"brown","eyes":"blue"}} - * // => UID345 {"name":"Marge","age":26,"traits":{"shoe_size":6,"hair":"blonde","eyes":"green"}} + * + * See http://facebook.github.io/react-native/docs/asyncstorage.html#multimerge */ multiMerge: function( keyValuePairs: Array>,