Skip to content

Latest commit

 

History

History
584 lines (401 loc) · 10.5 KB

API.md

File metadata and controls

584 lines (401 loc) · 10.5 KB
Raw

Async Storage API with examples.

Table of Contents


getItem

Fetches a data for a given key, invokes (optional) callback once completed.

Signature:

static getItem(key: string, [callback]: ?(error: ?Error, result: ?string) => void): Promise

Returns:

Promise with data, if exists, null otherwise.

Example:

getMyValue = async () => {
  try {
    const value = await AsyncStorage.getItem('@MyApp_key')
  } catch(e) {
    // read error
  }

  console.log('Done'.)

}


setItem

Stores a value for the key, invokes (optional) callback once completed.

Signature:

static setItem(key: string, value: string, [callback]: ?(error: ?Error) => void): Promise

Returns:

Promise object.

Example:

setValue = async () => {
  try {
    await AsyncStorage.setItem('@MyApp_key', 'my secret value')
  } catch(e) {
    // save error
  }

  console.log('Done.')
}


mergeItem

Merges an existing value stored under key, with new value, assuming both values are stringified JSON. NOTE: This is not supported by all native implementations.

Signature:

static mergeItem(key: string, value: string, [callback]: ?(error: ?Error) => void): Promise

Returns:

Promise with merged data, if exists, null otherwise.

Example:

const USER_1 = {
  name: 'Tom',
  age: 20,
  traits: {
    hair: 'black'
    eyes: 'blue'
  }
}

const USER_2 = {
  name: 'Sarah',
  age: 21,
  hobby: 'cars',
  traits: {
    eyes: 'green',
  }
}


mergeUsers = async () => {
  try {
    //save first user
    await AsyncStorage.setItem('@MyApp_user', JSON.stringify(USER_1))

    // merge USER_2 into saved USER_1
    await AsyncStorage.mergeItem('@MyApp_user', JSON.stringify(USER_2))

    // read merged item
    const currentUser = await AsyncStorage.getItem('@MyApp_user')

    console.log(currentUser)

    // console.log result:
    // {
    //   name: 'Sarah',
    //   age: 21,
    //   traits: {
    //     eyes: 'green',
    //     hair: 'black'
    //   }
    // }
  }
}


removeItem

Removes item for a key, invokes (optional) callback once completed.

Signature:

static removeItem(key: string, [callback]: ?(error: ?Error) => void): Promise

Returns:

Promise object.

Example:

removeValue = async () => {
  try {
    await AsyncStorage.removeItem('@MyApp_key')
  } catch(e) {
    // remove error
  }

  console.log('Done.')
}


getAllKeys

Returns all keys known to your App, for all callers, libraries, etc. Once completed, invokes callback with errors (if any) and array of keys.

Signature:

static getAllKeys([callback]: ?(error: ?Error, keys: ?Array<string>) => void): Promise

Returns:

Promise object.

Example:

getAllKeys = async () => {
  let keys = []
  try {
    keys = await AsyncStorage.getAllKeys()
  } catch(e) {
    // read key error
  }

  console.log(keys)
  // example console.log result:
  // ['@MyApp_user', '@MyApp_key']
}


multiGet

Fetches multiple key-value pairs for given array of keys in a batch. Once completed, invokes callback with errors (if any) and results.

Signature:

static multiGet(keys: Array<string>, [callback]: ?(errors: ?Array<Error>, result: ?Array<Array<string>>) => void): Promise

Returns:

Promise of array with coresponding key-value pairs found, stored as [key, value] array.

Example:

getMultiple = async () => {

  let values
  try {
    values = await AsyncStorage.multiGet(['@MyApp_user', '@MyApp_key'])
  } catch(e) {
    // read error
  }
  console.log(values)

  // example console.log output:
  // [ ['@MyApp_user', 'myUserValue'], ['@MyApp_key', 'myKeyValue'] ]
}


multiSet

Stores multiple key-value pairs in a batch. Once completed, callback with any errors will be called.

Signature:

static multiSet(keyValuePairs: Array<Array<string>>, [callback]: ?(errors: ?Array<Error>) => void): Promise

Returns:

Promise object.

Example:

multiSet = async () => {
  const firstPair = ["@MyApp_user", "value_1"]
  const secondPair = ["@MyApp_key", "value_2"]
  try {
    await AsyncStorage.multiSet([firstPair, secondPair])
  } catch(e) {
    //save error
  }

  console.log("Done.")
}


multiMerge

Multiple merging of existing and new values in a batch. Assumes that values are stringified JSON. Once completed, invokes callback with errors (if any). NOTE: This is not supported by all native implementations.

Signature:

static multiMerge(keyValuePairs: Array<Array<string>>, [callback]: ?(errors: ?Array<Error>) => void): Promise

Returns:

Promise object.

Example:

const USER_1 = {
  name: 'Tom',
  age: 30,
  traits: {hair: 'brown'},
};

const USER_1_DELTA = {
  age: 31,
  traits: {eyes: 'blue'},
};

const USER_2 = {
  name: 'Sarah',
  age: 25,
  traits: {hair: 'black'},
};

const USER_2_DELTA = {
  age: 26,
  traits: {hair: 'green'},
};


const multiSet = [
  ["@MyApp_USER_1", JSON.stringify(USER_1)],
  ["@MyApp_USER_2", JSON.stringify(USER_2)]
]

const multiMerge = [
  ["@MyApp_USER_1", JSON.stringify(USER_1_DELTA)],
  ["@MyApp_USER_2", JSON.stringify(USER_2_DELTA)]
]


mergeMultiple = async () => {
  let currentlyMerged

  try {
    await AsyncStorage.multiSet(multiSet)
    await AsyncStorage.multiMerge(multiMerge)
    currentlyMerged = await AsyncStorage.multiGet(['@MyApp_USER_1', '@MyApp_USER_2'])
  } catch(e) {
    // error
  }

  console.log(currentlyMerged)
  // console.log output:
  // [
  //   [
  //     'USER_1',
  //     {
  //       name:"Tom",
  //       age:30,
  //       traits: {
  //         hair: 'brown'
  //         eyes: 'blue'
  //       }
  //     }
  //   ],
  //   [
  //     'USER_2',
  //     {
  //       name:'Sarah',
  //       age:26,
  //       traits: {
  //         hair: 'green'
  //       }
  //     }
  //   ]
  // ]
}


multiRemove

Clears multiple key-value entries for given array of keys in a batch. Once completed, invokes a callback with errors (if any).

Signature:

static multiRemove(keys: Array<string>, [callback]: ?(errors: ?Array<Error>) => void)

Returns:

Promise object.

Example:

removeFew = async () => {
  const keys = ['@MyApp_USER_1', '@MyApp_USER_2']
  try {
    await AsyncStorage.multiRemove(keys)
  } catch(e) {
    // remove error
  }

  console.log('Done')
}


clear

Removes whole AsyncStorage data, for all clients, libraries, etc. You probably want to use removeItem or multiRemove to clear only your App's keys.

Signature:

static clear([callback]: ?(error: ?Error) => void): Promise

Returns:

Promise object.

Example:

clearAll = async () => {
  try {
    await AsyncStorage.clear()
  } catch(e) {
    // clear error
  }

  console.log('Done.')
}


flushGetRequests

Flushes any pending requests using a single batch call to get the data.

Signature:

static flushGetRequests(): void

Returns:

undefined

useAsyncStorage

Note: A hooks-like interface that we're experimenting with. This will change in the nearest future to fully leverage Hooks API, so feel free to follow this discussion to learn more.

The useAsyncStorage returns an object that exposes all methods that allow you to interact with the stored value.

Signature:

static useAsyncStorage(key: string): {
  getItem: (
    callback?: ?(error: ?Error, result: string | null) => void,
  ) => Promise<string | null>,
  setItem: (
    value: string,
    callback?: ?(error: ?Error) => void,
  ) => Promise<null>,
  mergeItem: (
    value: string,
    callback?: ?(error: ?Error) => void,
  ) => Promise<null>,
  removeItem: (callback?: ?(error: ?Error) => void) => Promise<null>,
}

Returns:

object

Specific Example:

You can replace your App.js with the following to see it in action.

import React, { useState, useEffect } from 'react';
import { View, Text, TouchableOpacity } from 'react-native';
import { useAsyncStorage } from '@react-native-community/async-storage';

export default function App() {
  const [value, setValue] = useState('value');
  const { getItem, setItem } = useAsyncStorage('@storage_key');

  const readItemFromStorage = async () => {
    const item = await getItem();
    setValue(item);
  };

  const writeItemToStorage = async newValue => {
    await setItem(newValue);
    setValue(newValue);
  };

  useEffect(() => {
    readItemFromStorage();
  }, []);

  return (
    <View style={{ margin: 40 }}>
      <Text>Current value: {value}</Text>
      <TouchableOpacity
        onPress={() =>
          writeItemToStorage(
            Math.random()
              .toString(36)
              .substr(2, 5)
          )
        }
      >
        <Text>Update value</Text>
      </TouchableOpacity>
    </View>
  );
}

In this example:

  1. On mount, we read the value at @storage_key and save it to the state under value
  2. When pressing on "update value", a new string gets generated, saved to async storage, and to the component state
  3. Try to reload your app - you'll see that the last value is still being read from async storage