diff --git a/Libraries/Storage/AsyncStorage.js b/Libraries/Storage/AsyncStorage.js index f1ed35c3c..df570bc11 100644 --- a/Libraries/Storage/AsyncStorage.js +++ b/Libraries/Storage/AsyncStorage.js @@ -105,6 +105,30 @@ var AsyncStorage = { /** * Merges existing value with input value, assuming they are stringified json. * Returns a `Promise` object. Not supported by all native implementations. + * + * Example: + * ```javascript + * let UID123_object = { + * name: 'Chris', + * age: 30, + * traits: {hair: 'brown', eyes: 'brown'}, + * }; + + // need only define what will be added or updated + * let UID123_delta = { + * age: 31, + * traits: {eyes: 'blue', shoe_size: 10} + * }; + + * AsyncStorage.setItem(store_key, 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'}} + * }); + * }); + * }); + * ``` */ mergeItem: function( key: string, @@ -144,6 +168,8 @@ var AsyncStorage = { /** * Gets *all* keys known to the app, for all callers, libraries, etc. Returns a `Promise` object. + * + * Example: see multiGet for example */ getAllKeys: function(callback?: ?(error: ?Error, keys: ?Array) => void): Promise { return new Promise((resolve, reject) => { @@ -201,6 +227,19 @@ var AsyncStorage = { * matches the input format of multiSet. Returns a `Promise` object. * * multiGet(['k1', 'k2'], cb) -> cb([['k1', 'val1'], ['k2', 'val2']]) + * + * Example: + * ```javascript + * 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]; + * }); + * }); + * }); + * ``` */ multiGet: function( keys: Array, @@ -243,6 +282,8 @@ var AsyncStorage = { * the output of multiGet, e.g. Returns a `Promise` object. * * multiSet([['k1', 'val1'], ['k2', 'val2']], cb); + * + * Example: see multiMerge for an example */ multiSet: function( keyValuePairs: Array>, @@ -263,6 +304,15 @@ var AsyncStorage = { /** * Delete all the keys in the `keys` array. Returns a `Promise` object. + * + * Example: + * ```javascript + * 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, @@ -286,6 +336,52 @@ var AsyncStorage = { * json. Returns a `Promise` object. * * Not supported by all native implementations. + * + * Example: + * ```javascript + // 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); + * // => 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>,