diff --git a/Libraries/Storage/AsyncStorage.js b/Libraries/Storage/AsyncStorage.js index 01d76748d..471c5304c 100644 --- a/Libraries/Storage/AsyncStorage.js +++ b/Libraries/Storage/AsyncStorage.js @@ -9,6 +9,7 @@ * @providesModule AsyncStorage * @noflow * @flow-weak + * @jsdoc */ 'use strict'; @@ -21,18 +22,45 @@ var RCTAsyncFileStorage = NativeModules.AsyncLocalStorage; var RCTAsyncStorage = RCTAsyncRocksDBStorage || RCTAsyncSQLiteStorage || RCTAsyncFileStorage; /** - * AsyncStorage is a simple, asynchronous, persistent, key-value storage + * @class + * @description + * `AsyncStorage` is a simple, 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. + * 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 or SQLite based on what is available. This JS code is a simple facade that - * provides a clear JS API, real Error objects, and simple non-multi functions. Each - * method returns a `Promise` object. + * 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 + * } + * ``` */ var AsyncStorage = { _getRequests: ([]: Array), @@ -40,8 +68,12 @@ var AsyncStorage = { _immediate: (null: ?number), /** - * Fetches `key` and passes the result to `callback`, along with an `Error` if - * there is any. Returns a `Promise` object. + * 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. */ getItem: function( key: string, @@ -63,8 +95,12 @@ var AsyncStorage = { }, /** - * Sets `value` for `key` and calls `callback` on completion, along with an - * `Error` if there is any. Returns a `Promise` object. + * 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. */ setItem: function( key: string, @@ -85,7 +121,11 @@ 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. */ removeItem: function( key: string, @@ -105,32 +145,39 @@ var AsyncStorage = { }, /** - * Merges existing value with input value, assuming they are stringified json. - * Returns a `Promise` object. Not supported by all native implementations. + * Merges an existing `key` value with an input value, assuming both values + * are stringified JSON. Returns a `Promise` object. * - * Example: - * ```javascript + * **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'}, * }; - - // need only define what will be added or updated + * // 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); - * // => {'name':'Chris','age':31,'traits':{'shoe_size':10,'hair':'brown','eyes':'blue'}} * }); * }); * }); - * ``` + * + * // Console log result: + * // => {'name':'Chris','age':31,'traits': + * // {'shoe_size':10,'hair':'brown','eyes':'blue'}} */ mergeItem: function( key: string, @@ -151,9 +198,11 @@ var AsyncStorage = { }, /** - * Erases *all* AsyncStorage for all clients, libraries, etc. You probably - * don't want to call this - use removeItem or multiRemove to clear only your - * own keys instead. Returns a `Promise` object. + * 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. */ clear: function(callback?: ?(error: ?Error) => void): Promise { return new Promise((resolve, reject) => { @@ -169,9 +218,12 @@ var AsyncStorage = { }, /** - * Gets *all* keys known to the app, for all callers, libraries, etc. Returns a `Promise` object. + * 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 multiGet for example + * Example: see the `multiGet` example. */ getAllKeys: function(callback?: ?(error: ?Error, keys: ?Array) => void): Promise { return new Promise((resolve, reject) => { @@ -196,7 +248,7 @@ var AsyncStorage = { * indicate which key caused the error. */ - /** Flushes any pending requests using a single multiget */ + /** Flushes any pending requests using a single batch call to get the data. */ flushGetRequests: function(): void { const getRequests = this._getRequests; const getKeys = this._getKeys; @@ -225,13 +277,23 @@ var AsyncStorage = { }, /** - * multiGet invokes callback with an array of key-value pair arrays that - * matches the input format of multiSet. Returns a `Promise` object. + * 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']]) + * ``` + * 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 * - * Example: - * ```javascript * AsyncStorage.getAllKeys((err, keys) => { * AsyncStorage.multiGet(keys, (err, stores) => { * stores.map((result, i, store) => { @@ -241,7 +303,6 @@ var AsyncStorage = { * }); * }); * }); - * ``` */ multiGet: function( keys: Array, @@ -280,12 +341,20 @@ var AsyncStorage = { }, /** - * multiSet and multiMerge take arrays of key-value array pairs that match - * the output of multiGet, e.g. Returns a `Promise` object. + * 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: * - * multiSet([['k1', 'val1'], ['k2', 'val2']], cb); + * ``` + * multiSet([['k1', 'val1'], ['k2', 'val2']], cb); + * ``` * - * Example: see multiMerge for an example + * 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. */ multiSet: function( keyValuePairs: Array>, @@ -305,16 +374,20 @@ var AsyncStorage = { }, /** - * Delete all the keys in the `keys` array. Returns a `Promise` object. + * Call this to batch the deletion of all keys in the `keys` array. Returns + * a `Promise` object. * - * Example: - * ```javascript + * @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) * }); - * ``` */ multiRemove: function( keys: Array, @@ -334,42 +407,47 @@ var AsyncStorage = { }, /** - * Merges existing values with input values, assuming they are stringified - * json. Returns a `Promise` object. + * 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. * - * Not supported by all native implementations. + * **NOTE**: This is not supported by all native implementations. * - * Example: - * ```javascript - // first user, initial values + * @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) => { @@ -377,13 +455,14 @@ var AsyncStorage = { * let key = store[i][0]; * let val = store[i][1]; * console.log(key, val); - * // => 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"}} * }); * }); * }); * }); - * ``` + * + * // 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"}} */ multiMerge: function( keyValuePairs: Array>, diff --git a/website/layout/AutodocsLayout.js b/website/layout/AutodocsLayout.js index 1f514a6cf..f85016b6e 100644 --- a/website/layout/AutodocsLayout.js +++ b/website/layout/AutodocsLayout.js @@ -650,7 +650,7 @@ var Method = React.createClass({ || ''} {this.props.name} - ({this.props.params + ({this.props.params && this.props.params.length && this.props.params .map((param) => { var res = param.name; res += param.optional ? '?' : '';