diff --git a/.circleci/config.yml b/.circleci/config.yml index a6c48883..e8b7804d 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -18,89 +18,24 @@ checkout step for each job: &addWorkspace default config for js: &js_defaults <<: *defaults docker: - - image: circleci/node:8 + - image: circleci/node:10 -default config for macOS: &macos_defaults - <<: *defaults - resource_class: 'medium' - macos: - xcode: '10.1.0' - -default config for android apk builds: &android_defaults - <<: *defaults - docker: - - image: reactnativecommunity/react-native-android - resource_class: 'medium' - working_directory: ~/async_storage - environment: - - _JAVA_OPTIONS: '-XX:+UnlockExperimentalVMOptions -XX:+UseCGroupMemoryLimitForHeap -Xmx2048m' - - GRADLE_OPTS: '-Dorg.gradle.daemon=false -Dorg.gradle.jvmargs="-XX:+HeapDumpOnOutOfMemoryError -Xmx2048m"' - - BUILD_THREADS: 2 # ============================== # CACHE CONFIG # ============================== -# brew -save brew cache: &cache_save_brew - name: Saving Brew cache - paths: - - /usr/local/Homebrew - - ~/Library/Caches/Homebrew - key: v1-brew-cache-{{ arch }} - -restore brew cache: &cache_restore_brew - name: Restoring Brew cache - keys: - - v1-brew-cache-{{ arch }} - -save brew cache for android: &cache_save_brew_android - name: Saving Brew cache for android - paths: - - /usr/local/Homebrew - - ~/Library/Caches/Homebrew - key: v1-brew-cache-{{ arch }}-android - -restore brew cache for android: &cache_restore_brew_android - name: Restoring Brew cache for android - keys: - - v1-brew-cache-{{ arch }}-android - # yarn save yarn cache: &cache_save_yarn name: Saving Yarn cache paths: - ~/.cache/yarn - - ~/Library/Detox - key: v1-yarn-cache-{{ checksum "package.json" }}-{{ arch }} + key: yarn-cache-{{ checksum "package.json" }}-{{ arch }} restore yarn cache: &cache_restore_yarn name: Restoring Yarn cache keys: - - v1-yarn-cache-{{ checksum "package.json" }}-{{ arch }} - -# gradle -save gradle wrapper cache: &cache_save_gradle_wrapper - name: Saving Gradle Wrapper cache - paths: - - ~/.gradle/wrapper - key: gradle-wrapper-v1-{{ checksum "example/android/gradle/wrapper/gradle-wrapper.properties" }} - -save gradle build cache: &cache_save_gradle_build - name: Saving Gradle app/build cache - paths: - - ~/.gradle/caches - key: app-build-gradle-v1-{{ checksum "example/android/app/build.gradle" }} - -restore gradle wrapper cache: &cache_restore_gradle_wrapper - name: Restoring Gradle Wrapper cache - keys: - - gradle-wrapper-v1-{{ checksum "example/android/gradle/wrapper/gradle-wrapper.properties" }} - -restore gradle build cache: &cache_restore_gradle_build - name: Restoring Gradle app/build cache - keys: - - app-build-gradle-v1-{{ checksum "example/android/app/build.gradle" }} + - yarn-cache-{{ checksum "package.json" }}-{{ arch }} # ============================== @@ -134,163 +69,24 @@ jobs: steps: - *addWorkspace - run: - name: Type check - command: yarn test:types + name: Typescript check + command: yarn lerna run test:types "Test: unit": <<: *js_defaults steps: - *addWorkspace - run: - name: Unit tests run + name: Unit tests command: yarn test:unit - "Test: iOS e2e": - <<: *macos_defaults - steps: - - *addWorkspace - - restore-cache: *cache_restore_brew - - run: - name: Configure OSX Environment - command: | - HOMEBREW_NO_AUTO_UPDATE=1 brew install node@8 >/dev/null - HOMEBREW_NO_AUTO_UPDATE=1 brew tap wix/brew >/dev/null - HOMEBREW_NO_AUTO_UPDATE=1 brew install applesimutils >/dev/null - touch .watchmanconfig - node -v - - save-cache: *cache_save_brew - - restore-cache: *cache_restore_yarn - - run: - name: Installing Yarn dependencies - command: yarn --pure-lockfile --non-interactive --cache-folder ~/.cache/yarn - - save-cache: *cache_save_yarn - - run: - name: Build iOS app - command: yarn build:e2e:ios - - - run: - name: Run e2e tests - command: yarn test:e2e:ios - - "Build: Android release apk": - <<: *android_defaults - steps: - - *addWorkspace - - restore-cache: *cache_restore_yarn - - run: - name: Installing Yarn dependencies - command: yarn --pure-lockfile --non-interactive --cache-folder ~/.cache/yarn - - save-cache: *cache_save_yarn - - # Gradle - - restore-cache: *cache_restore_gradle_wrapper - - restore-cache: *cache_restore_gradle_build - - run: - name: Downloading Gradle dependencies - command: cd example/android && ./gradlew --max-workers 2 fetchDependencies - - save-cache: *cache_save_gradle_wrapper - - save-cache: *cache_save_gradle_build - - # Build and test - - run: - name: Build Android apk - command: cd example/android && ./gradlew assembleRelease assembleAndroidTest -DtestBuildType=release --max-workers 2 - - - persist_to_workspace: - root: ~/async_storage - paths: - - example/android/app/build/outputs/apk/* - - "Test: Android e2e": - <<: *macos_defaults - steps: - - *addWorkspace - - run: - name: Configure env variables - command: | - echo 'export ANDROID_HOME="/usr/local/share/android-sdk"' >> $BASH_ENV - echo 'export ANDROID_SDK_ROOT="/usr/local/share/android-sdk"' >> $BASH_ENV - echo 'export PATH="$ANDROID_SDK_ROOT/emulator:$ANDROID_SDK_ROOT/tools:$ANDROID_SDK_ROOT/platform-tools:$ANDROID_SDK_ROOT/tools/bin:$PATH"' >> $BASH_ENV - echo 'export QEMU_AUDIO_DRV=none' >> $BASH_ENV - echo 'export JAVA_HOME=/Library/Java/Home' >> $BASH_ENV - source $BASH_ENV - - # Android tools - - restore-cache: *cache_restore_brew_android - - run: - name: Install Android SDK tools - command: | - HOMEBREW_NO_AUTO_UPDATE=1 brew tap homebrew/cask >/dev/null - HOMEBREW_NO_AUTO_UPDATE=1 brew cask install android-sdk >/dev/null - HOMEBREW_NO_AUTO_UPDATE=1 brew cask install intel-haxm >/dev/null - HOMEBREW_NO_AUTO_UPDATE=1 brew install node@8 >/dev/null >/dev/null - - save-cache: *cache_save_brew_android - - - run: - name: Install Android emulator - shell: /bin/bash -e - command: | - yes | sdkmanager "platform-tools" "tools" >/dev/null - yes | sdkmanager "platforms;android-28" "system-images;android-21;google_apis;x86" >/dev/null - yes | sdkmanager "emulator" --channel=3 >/dev/null - yes | sdkmanager "build-tools;28.0.3" >/dev/null - yes | sdkmanager --licenses >/dev/null - yes | sdkmanager --list - - - run: - name: ADB start/stop - command: | - adb start-server - adb devices - adb kill-server - ls -la ~/.android - - - run: - name: Create emulator - command: | - avdmanager create avd \ - --force \ - -n "Emu_E2E" \ - -k "system-images;android-21;google_apis;x86" \ - -g "google_apis" \ - -d "Nexus 4" - - - - - run: - name: Start emulator in background - background: true - command: | - emulator -avd "Emu_E2E" \ - -cores 1 \ - -gpu auto \ - -accel on \ - -memory 1024 \ - -no-audio \ - -no-snapshot \ - -no-boot-anim \ - -no-window \ - -logcat '*:W' | grep -i "ReactNative" - - - run: - name: Wait for emulator to boot - command: yarn build:e2e:android - - - run: - name: Wake device - command: | - adb shell input keyevent 82 - - - run: - name: Run e2e tests - command: yarn test:e2e:android # ============================== # WORK FLOWS # ============================== workflows: version: 2 - build_and_test_wip: + "Basic tests": jobs: - "Setup environment" - "Test: lint": diff --git a/.circleci/scripts/run_android_e2e.sh b/.circleci/scripts/run_android_e2e.sh deleted file mode 100755 index bf4aa64c..00000000 --- a/.circleci/scripts/run_android_e2e.sh +++ /dev/null @@ -1,47 +0,0 @@ -#!/bin/bash - -# On CI, waits for emu to be booted -# Locally, builds apk - -ROOT_DIR=$PWD - -INTERVAL=5 # 5 secs between each check -MAX_RETRIES=60 # wait max 5 minutes for emu to boot - -build_apk() { - echo - echo "[Detox e2e] Building APK" - cd "example/android" - eval "./gradlew assembleRelease assembleAndroidTest -DtestBuildType=release" - cd ${ROOT_DIR} -} - -wait_for_emulator_to_boot() { - isBooted=$(adb shell getprop sys.boot_completed 2>&1 | tr -d '\r') - retriesLeft=${MAX_RETRIES} - - echo - echo "[Detox e2e] Checking if emulator is booted up." - - while [[ "$isBooted" != "1" ]]; do - - if [[ ${retriesLeft} -eq 0 ]]; then - echo "[Detox e2e] Seems like emulator could not be booted." 1>&2 - exit 125 - fi - - isBooted=$(adb shell getprop sys.boot_completed 2>&1 | tr -d '\r') - - retriesLeft=$((retriesLeft - 1)) - echo "[Detox e2e] $retriesLeft checks left." - sleep ${INTERVAL} - done - - echo "[Detox e2e] Emulator booted." -} - -if [[ -n $CIRCLECI ]]; then - wait_for_emulator_to_boot # Run it on CI -else - build_apk # Run locally -fi diff --git a/.circleci/scripts/run_ios_e2e.sh b/.circleci/scripts/run_ios_e2e.sh deleted file mode 100755 index f3d1b20d..00000000 --- a/.circleci/scripts/run_ios_e2e.sh +++ /dev/null @@ -1,81 +0,0 @@ -#!/bin/bash - -RESOURCE_DIR="$PWD/example/ios/build/Build/Products/Release-iphonesimulator/AsyncStorageExample.app" -ENTRY_FILE="example/index.js" -BUNDLE_FILE="$RESOURCE_DIR/main.jsbundle" -EXTRA_PACKAGER_ARGS="--entry-file=$ENTRY_FILE" - - -build_project() { - echo "[Detox e2e] Building iOS project" - eval "xcodebuild \ - -project example/ios/AsyncStorageExample.xcodeproj \ - -scheme AsyncStorageExample \ - -configuration Release \ - -sdk iphonesimulator \ - -derivedDataPath example/ios/build \ - -UseModernBuildSystem=NO \ - BUNDLE_FILE=$BUNDLE_FILE \ - EXTRA_PACKAGER_ARGS=$EXTRA_PACKAGER_ARGS" -} - -run_simulator() { - if [[ -n $1 ]]; then - deviceName=$1 - else - echo "[Detox e2e] Device name not passed!" >&2; - exit; - fi - - - if [[ $2 = "headless" ]]; then - runHeadless=1 - else - runHeadless=0 - fi - - # Find simulator - devDir=`xcode-select -p` - devDir=$devDir/Applications/Simulator.app - - # parse output - availableDevices=$( - eval "xcrun simctl list devices" |\ - eval "sed '/"$deviceName"/!d'" |\ - eval "sed '/unavailable/d'" |\ - eval "sed 's/(Shutdown)//; s/(Shutting Down)//; s/(Booted)//; s/ (/*/; s/)//'" - ) - - IFS='*' read -a deviceInfo <<< "$availableDevices" - - if [[ $deviceInfo == "" ]]; then - echo "[Detox e2e] Could not find device: $deviceName" >&2 - exit; - fi - - - deviceUUID=${deviceInfo[1]} - - echo "[Detox e2e] Booting up $deviceName (id: $deviceUUID)" - - # Booting emulator in headless mode - eval "open $devDir --args -CurrentDeviceUDID $deviceUUID" - - # Decide if should run headless or not - if [ "$runHeadless" -eq 0 ]; then - eval "xcrun instruments -w $deviceUUID" >/dev/null 2>&1 - else - echo "[Detox e2e] Running simulator in headless mode." - fi -} - - -build_project - -sleep 2 - -run_simulator "$1" "$2" - -sleep 10 - -exit 0 diff --git a/.github/ISSUE_TEMPLATE/02_feature_request.md b/.github/ISSUE_TEMPLATE/02_feature_request.md deleted file mode 100644 index 345fd1bc..00000000 --- a/.github/ISSUE_TEMPLATE/02_feature_request.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -name: '๐Ÿ”ง Feature request' -about: New functionality for Async Storage -label: 'Enhancement' ---- - -## Motivation - - - -## Description - - - -## New feature implementation - - \ No newline at end of file diff --git a/.github/ISSUE_TEMPLATE/03_question_discussion.md b/.github/ISSUE_TEMPLATE/03_question_discussion.md deleted file mode 100644 index d2c01e68..00000000 --- a/.github/ISSUE_TEMPLATE/03_question_discussion.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -name: '๐Ÿ—ฃ Have a question / start a discussion' -about: You want to ask or discuss something -label: 'Question/Discussion' ---- - -## You want to: - - -## Details: - \ No newline at end of file diff --git a/.github/ISSUE_TEMPLATE/01_bug_report.md b/.github/ISSUE_TEMPLATE/bug.md similarity index 74% rename from .github/ISSUE_TEMPLATE/01_bug_report.md rename to .github/ISSUE_TEMPLATE/bug.md index 6bb663d0..aafeb468 100644 --- a/.github/ISSUE_TEMPLATE/01_bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug.md @@ -1,24 +1,25 @@ --- -name: '๐Ÿ› Bug report' +name: Bug report about: Something not working as expected -label: 'Bug' +label: bug --- ## Current behavior - -## Expected behavior +## Expected behavior -## Repro steps +## Repro steps + ## Environment - **Async Storage version**: +- **Storage used**: - **React-Native version**: -- **Platform tested**: -- **Logs/Error that are relevant**: \ No newline at end of file +- **Platform tested**: +- **Logs/Error that are relevant**: diff --git a/.github/ISSUE_TEMPLATE/feature.md b/.github/ISSUE_TEMPLATE/feature.md new file mode 100644 index 00000000..b6c58f39 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature.md @@ -0,0 +1,17 @@ +--- +name: Feature request +about: I'd like to add/change functionality +label: feature +--- + +## Motivation + + + +## Details + + + +## Environment + + diff --git a/.github/ISSUE_TEMPLATE/help.md b/.github/ISSUE_TEMPLATE/help.md new file mode 100644 index 00000000..2c795f80 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/help.md @@ -0,0 +1,8 @@ +--- +name: Help +about: I need help with Async Storage +label: help +--- + +## Question + diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index e493ef7e..28a69817 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,11 +1,13 @@ -Summary: ---------- +## Summary: +Help us understand more of your work - you can explain what you did, post a link to an issue etc. +--> -Test Plan: ----------- - \ No newline at end of file +## Test Plan: + + diff --git a/README.md b/README.md index 51a49108..5bba2b6f 100644 --- a/README.md +++ b/README.md @@ -1,32 +1,41 @@ # Async Storage -A persistent data storage solution for your next mobile, web or desktop application. +A collection of persistent data storages, unified into a single API. ## Work in progress Async Storage v2 is under development. -If you're looking for published and operational Async Storage version, please check out [`LEGACY`](https://github.com/react-native-community/async-storage/tree/LEGACY) branch. - -If you'd like to see the progress of v2, [please visit Project page.](https://github.com/react-native-community/async-storage/projects/1) +If you're looking for published and operational Async Storage version, please check out [`LEGACY`](https://github.com/react-native-community/async-storage/tree/LEGACY) branch. ## Features -todo +- Unified API to consume any supported storage +- Different type of storage for different purpose, see [available storages](#available-storages) +- Extensible functionality, to leverage full storage potential +- Support for Mobile, Web and more -## Documentation -- [Creating a custom Storage backend](./packages/core/docs/Writing_Storage_Backend.md) +## Getting started + +Quick introduction to AsyncStorage can [be found here.](./packages/core/docs/Usage.md) + -## Available storage backends +## Available storages - [Legacy](./packages/storage-legacy/README.md) - [Web](./packages/storage-web/README.md) +## Documentation + +- [API documentation](./packages/core/docs/API.md) +- [Creating custom Storage backend](./packages/core/docs/Writing_Storage_Backend.md) + + ## License -MIT +MIT. diff --git a/docs/OLD/API.md b/docs/OLD/API.md deleted file mode 100644 index 6d474054..00000000 --- a/docs/OLD/API.md +++ /dev/null @@ -1,584 +0,0 @@ -# Async Storage API with examples. - - - -**Table of Contents** - - [getItem](#getItem) - - [setItem](#setItem) - - [mergeItem](#mergeItem) - - [removeItem](#removeItem) - - [getAllKeys](#getAllKeys) - - [multiGet](#multiGet) - - [multiSet](#multiSet) - - [multiMerge](#multiMerge) - - [multiRemove](#multiRemove) - - [clear](#clear) - - [flushGetRequests](#flushGetRequests) - - [useAsyncStorage](#useAsyncStorage) - -
- - - -## `getItem` - -Fetches a data for a given `key`, invokes (optional) callback once completed. - -**Signature**: - -```js -static getItem(key: string, [callback]: ?(error: ?Error, result: ?string) => void): Promise -``` - -**Returns**: - -`Promise` with data, if exists, `null` otherwise. - -**Example**: - -```js - -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**: - -```js -static setItem(key: string, value: string, [callback]: ?(error: ?Error) => void): Promise -``` - -**Returns**: - -`Promise` object. - -**Example**: - -```js - -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**: - -```js -static mergeItem(key: string, value: string, [callback]: ?(error: ?Error) => void): Promise -``` - -**Returns**: - -`Promise` with merged data, if exists, `null` otherwise. - -**Example**: - -```js -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**: - -```js -static removeItem(key: string, [callback]: ?(error: ?Error) => void): Promise -``` - -**Returns**: - -`Promise` object. - -**Example**: - -```js -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**: - -```js -static getAllKeys([callback]: ?(error: ?Error, keys: ?Array) => void): Promise -``` - -**Returns**: - -`Promise` object. - -**Example**: - -```js - -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**: - -```js -static multiGet(keys: Array, [callback]: ?(errors: ?Array, result: ?Array>) => void): Promise -``` - -**Returns**: - -`Promise` of array with coresponding key-value pairs found, stored as `[key, value]` array. - - -**Example**: - -```js - -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**: - -```js -static multiSet(keyValuePairs: Array>, [callback]: ?(errors: ?Array) => void): Promise -``` - -**Returns**: - -`Promise` object. - -**Example**: - -```js - -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**: - -```js -static multiMerge(keyValuePairs: Array>, [callback]: ?(errors: ?Array) => void): Promise -``` - -**Returns**: - -`Promise` object. - -**Example**: - -```js -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**: - -```js -static multiRemove(keys: Array, [callback]: ?(errors: ?Array) => void) -``` - -**Returns**: - -`Promise` object. - -**Example**: - -```js -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](#removeItem) or [multiRemove](#multiRemove) to clear only your App's keys. - -**Signature**: - -```js -static clear([callback]: ?(error: ?Error) => void): Promise -``` - -**Returns**: - -`Promise` object. - -**Example**: - -```js -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**: - -```js -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](https://github.com/react-native-community/react-native-async-storage/issues/32). - - -The `useAsyncStorage` returns an object that exposes all methods that allow you to interact with the stored value. - -**Signature**: - -```js -static useAsyncStorage(key: string): { - getItem: ( - callback?: ?(error: ?Error, result: string | null) => void, - ) => Promise, - setItem: ( - value: string, - callback?: ?(error: ?Error) => void, - ) => Promise, - mergeItem: ( - value: string, - callback?: ?(error: ?Error) => void, - ) => Promise, - removeItem: (callback?: ?(error: ?Error) => void) => Promise, -} -``` - -**Returns**: - -`object` - -**Specific Example**: - -You can replace your `App.js` with the following to see it in action. - -```jsx -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 ( - - Current value: {value} - - writeItemToStorage( - Math.random() - .toString(36) - .substr(2, 5) - ) - } - > - Update value - - - ); -} -``` - -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 diff --git a/docs/OLD/Jest-integration.md b/docs/OLD/Jest-integration.md deleted file mode 100644 index dda42a4d..00000000 --- a/docs/OLD/Jest-integration.md +++ /dev/null @@ -1,87 +0,0 @@ -# Jest integration - -Async Storage module is tighly coupled with its `NativeModule` part - it needs a running React Native application to work properly. In order to use it in tests, you have to provide its separate implementation. Follow those steps to add a mocked `Async Storage` module. - -## Using Async Storage mock - -You can use one of two ways to provide mocked version of `AsyncStorage`: - -### With __mocks__ directory - -1. In your project root directory, create `__mocks__/@react-native-community` directory. -2. Inside that folder, create `async-storage.js` file. -3. Inside that file, export `Async Storage` mock. - -```javascript -export default from '@react-native-community/async-storage/jest/async-storage-mock' -``` - -### With Jest setup file - -1. In your Jest config (probably in `package.json`) add setup files location: - -```json -"jest": { - "setupFiles": ["./path/to/jestSetupFile.js"] -} -``` - -2. Inside your setup file, set up Async Storage mocking: - -```javascript -import mockAsyncStorage from '@react-native-community/async-storage/jest/async-storage-mock'; - -jest.mock('@react-native-community/async-storage', () => mockAsyncStorage); -``` -## Testing with mock - -Each public method available from `Async Storage` is [a mock function](https://jestjs.io/docs/en/mock-functions), that you can test for certain condition, for example, if `.getItem` has been called with a specific arguments: - -```javascript -it('checks if Async Storage is used', async () => { - await asyncOperationOnAsyncStorage(); - - expect(AsyncStorage.getItem).toBeCalledWith('myKey'); -}) -``` - -## Overriding Mock logic - -You can override mock implementation, by replacing its inner functions: - -```javascript -// somewhere in your configuration files -import AsyncStorageMock from '@react-native-community/async-storage/jest/async-storage-mock'; - -AsyncStorageMock.multiGet = jest.fn(([keys], callback) => { - // do something here to retrieve data - callback([]); -}) - -export default AsyncStorageMock; -``` - -You can [check its implementation](../../storages/jestmock/index.js) to get more insight into methods signatures. - -## Troubleshooting - -### **`SyntaxError: Unexpected token export` in async-storage/lib/index.js** - -**Note:** In React Native 0.60+, all `@react-native-community` packages are transformed by default. - -You need to point Jest to transform this package. You can do so, by adding Async Storage path to `transformIgnorePatterns` setting in Jest's configuration. - - -```json -"jest": { - "transformIgnorePatterns": [src] -} -``` - -Optionally, you can transform whole scope for `react-native-community` and `react-native`: - -```json -"jest": { - "transformIgnorePatterns": ["node_modules/(?!(@react-native-community|react-native))"] -} -``` diff --git a/docs/OLD/Troubleshooting.md b/docs/OLD/Troubleshooting.md deleted file mode 100644 index 71e055a7..00000000 --- a/docs/OLD/Troubleshooting.md +++ /dev/null @@ -1,72 +0,0 @@ -# Troubleshooting - -## [iOS] CocoaPods issues - -1. Delete the `node_modules` folder(s) from your project -2. Run `yarn` or `npm install` -3. If you're using CocoaPods: - 1. Make sure your `Podfile` has this entry: - ```Podfile - pod 'RNCAsyncStorage', :path => '../node_modules/@react-native-community/async-storage' - ``` - 2. Make sure your `Podfile` does _not_ have an entry for `react-native-async-storage`. - 3. `pod install` - 4. `pod update RNCAsyncStorage` -4. Open your Xcode project -5. Press โ‡งโŒฅโŒ˜K to clean your build folder -6. Build and run your project - -> Note that every time `@react-native-community/async-storage` gets updated, you -> must also run `pod update RNCAsyncStorage` otherwise you'll still be using the -> previous version. - -## [iOS] fatal error: 'React/RCTBridgeModule.h' file not found - -``` -info In file included from /~/@react-native-community/async-storage/ios/RNCAsyncStorage.m:8: -/~/@react-native-community/async-storage/ios/RNCAsyncStorage.h:8:9: fatal error: 'React/RCTBridgeModule.h' file not found - -info #import - ^~~~~~~~~~~~~~~~~~~~~~~~~ - -info 1 error generated. -``` - -- Make sure that you've run `pod install` or `pod update RNCAsyncStorage` (see - also [CocoaPods issues](#ios-cocoapods-issues)). - -- If you've manually linked React Native, but use CocoaPods for AsyncStorage, - AsyncStorage will not be able to find React headers. You'll need to set header - search path, or also consume React Native via CocoaPods. - -- Make sure that `React` dependencies are _not_ removed from projects. Without - the target dependency set, Xcode may build things out of order and the React - headers will not be installed when AsyncStorage is built. - - ```Podfile - post_install do |installer| - installer.pods_project.targets.each do |target| - if target.name == "React" - target.remove_from_project - end - end - end - ``` - -- Try switching back to the legacy build system in Xcode. You can find it in - File > Project/Workspace Settings sheet. - -## [@RNC/AsyncStorage]: NativeModule: AsyncStorage is null - -### iOS - -This error means that AsyncStorage was unable to find its native module. This -occurs because AsyncStorage was not linked into the final app bundle. - -- Make sure that you've run `pod install` or `pod update RNCAsyncStorage` (see - also [CocoaPods issues](#ios-cocoapods-issues)). - -- If you have an Expo app, AsyncStorage will not work unless you eject the app. - After ejecting the app, you may have to - [manually link](Linking.md#project-linking) depending on whether you chose to - use Expo SDK. diff --git a/package.json b/package.json index 59e255df..148750d4 100644 --- a/package.json +++ b/package.json @@ -11,8 +11,7 @@ }, "version": "2.0.0", "description": "WIP", - "author": "Krzysztof Borowy ", - "contributors": [], + "author": "ReactNative Community", "homepage": "https://github.com/react-native-community/react-native-async-storage#readme", "repository": { "type": "git", diff --git a/packages/core/README.md b/packages/core/README.md index f23e990f..27ddd9f4 100644 --- a/packages/core/README.md +++ b/packages/core/README.md @@ -88,7 +88,7 @@ const storage = ASFactory.create(storageBackend); ### `IStorageBackend` In order to let `AsyncStorage` use a storage backend, it has to implement this interface. -Contains basic set method of methods to get, set and remove data, return already used keys or drop the whole storage. +Contains methods to get, set and remove data, return used keys or drop the whole storage. ```typescript diff --git a/packages/core/docs/API.md b/packages/core/docs/API.md new file mode 100644 index 00000000..c3bf5def --- /dev/null +++ b/packages/core/docs/API.md @@ -0,0 +1,138 @@ +# Async Storage API + +Async Storage provides a unified API for any underlying storage. +All + + +## Table of Content + +- [API](#api) + - [get](#get) + - [set](#set) + - [remove](#remove) + - [getMultiple](#getmultiple) + - [setMultiple](#setmultiple) + - [removeMultiple](#removemultiple) + - [getKeys](#getkeys) + - [clearStorage](#clearstorage) +- [Extensions](#extensions) + +## API + + +### `get` + +Returns a value (or `null`) for a `key` from a storage. + + +```typescript +// example.js + +const value = await storageInst.get('myKey'); +``` + + + +### `set` + +Stores a `value` for a `key` in storage. + +```typescript +// example.js + +const myValue = "Hello world!"; +await storageInst.set('myKey', myValue); +``` + +### `remove` + +Removes value for `key` from the storage. + +```typescript +// example.js + +await storageInst.remove('myKey'); +``` + + +### `getMultiple` + +Returns an object with `key/value` entries, read for given `keys`. + + +```typescript +//example.js + +const values = await storageInst.getMultiple(['key1', 'key2', 'key3']); +console.log(value); +/* + output: + { + key1: "value1", + key2: "value2", + key3: "value3" + } +*/ + +``` + +### `setMultiple` + +Stores multiple `key/value` pairs into storage. + +```typescript +// example.js + +const value1 = { key1: 'hello1' }; +const value2 = { + key2: { + name: 'jerry', + age: 25 + } +}; + +await storageInst.setMultiple([ value1, value2 ]) +``` + +### `removeMultiple` + +Removes multiple values stored under `keys`. + +```typescript +// example.js + +const deleteList = ['key1', 'key2', 'key3']; + +await storageInst.removeMultiple(deleteList); +``` + + +### `getKeys` + +Returns all keys used to store data in storage. + +```typescript + +const keys = await storageInst.getKeys(); +// output: ['key1', 'key2', 'key3']; + +``` + +### `clearStorage` + +Wipes whole data currently stored from storage. + +```typescript +// example.js + +await storageInst.clearStorage(); +```` + + +## Extensions + +Basic Async Storage can be extended by additional functions, if [used storage](https://github.com/react-native-community/async-storage/blob/master/README.md#available-storage-backends) provides any. + +You can access additional functionality through `.ext` property. + +[More info can be found in Writing Custom Storage section](./Writing_Storage_Backend.md#going-being-default-api) diff --git a/packages/core/docs/Usage.md b/packages/core/docs/Usage.md new file mode 100644 index 00000000..949bb7ab --- /dev/null +++ b/packages/core/docs/Usage.md @@ -0,0 +1,65 @@ +# Async Storage usage + +Async Storage is a collection of usable storage backends for your App. + +It comes in two parts: core and storage backend, you want to use. + +*Core* is a consumer of the storage, provides you a unified API to save and read data. + +*Storage backend* implements an interface that *core* API understands and uses. Its functionality depends on storage itself. + + +## Install necessary dependencies + +In this example, we'll be using [Legacy storage](https://github.com/react-native-community/async-storage/tree/master/packages/storage-legacy). + +```bash +# Install core +$ yarn add @react-native-community/async-storage + +# Install legacy backend storage +$ yarn add @react-native-community/async-storage-backend-legacy +``` + + +## Create an instance of AsyncStorage + +```typescript +// storage.ts + +import AsyncStorageFactory from '@react-native-community/async-storage'; +import LegacyStorage from '@react-native-community/async-storage-backend-legacy'; + +const legacyStorage = new LegacyStorage(); + +export type StorageModel = { + user: { + name: string + } +} + +const storage = AsyncStorageFactory.create(legacyStorage) + +export default storage; +``` + +## Use created instance + +Import previously exported AsyncStorage instance and use it. [See full API here.](https://github.com/react-native-community/async-storage/tree/master/packages/core/docs/API.md) + + +```typescript + +import storage from './storage.ts'; + + +async function saveItem() { + const myUser = { + name: 'test' + }; + + await storage.set('user', myUser); +} + +``` + diff --git a/packages/core/package.json b/packages/core/package.json index 22693d78..ef0ac801 100644 --- a/packages/core/package.json +++ b/packages/core/package.json @@ -3,8 +3,11 @@ "version": "2.0.0", "main": "build/index.js", "types": "types/index.d.ts", - "author": "Krzysztof Borowy ", + "author": "ReactNative Community", "license": "MIT", + "publishConfig": { + "access": "public" + }, "scripts": { "build": "babel src --root-mode upward --out-dir build/ --extensions .ts --ignore build/**/* --ignore types/* --source-maps inline", "clean": "rm build -rf", diff --git a/docs/OLD/Linking.md b/packages/storage-legacy/docs/Linking.md similarity index 81% rename from docs/OLD/Linking.md rename to packages/storage-legacy/docs/Linking.md index 9f3dcff1..69ffb4f4 100644 --- a/docs/OLD/Linking.md +++ b/packages/storage-legacy/docs/Linking.md @@ -1,13 +1,15 @@ # Manual Linking +Instruction on how to manually link this library **for React Native version < 60.0**. + ## iOS -#### Project linking +#### Linking via `.xcodeproj` 1. Open your project `.xcodeproj` on xcode. 2. Right click on the Libraries folder and select `Add files to "yourProjectName"`. -3. Add `RNCAsyncStorage.xcodeproj` (located at `node_modules/@react-native-community/async-storage/ios`) to your project Libraries. +3. Add `RNCAsyncStorage.xcodeproj` (located at `node_modules/@react-native-community/async-storage-backend-legacy/ios`) to your project Libraries. 3. Go to `Build Phases -> Link Binary with Libraries` and add: `libRNCAsyncStorage.a`. @@ -17,7 +19,7 @@ 2. Add this line to your `Podfile` just below the last pod (if you don't have one, you can create it by running `pod init`): ```diff -+ pod 'RNCAsyncStorage', :path => '../node_modules/@react-native-community/async-storage' ++ pod 'RNCAsyncStorage', :path => '../node_modules/@react-native-community/async-storage-backend-legacy' ``` 3. Run `pod install` @@ -31,14 +33,14 @@ rootProject.name = 'MyApp' include ':app' + include ':@react-native-community_async-storage' -+ project(':@react-native-community_async-storage').projectDir = new File(rootProject.projectDir, '../node_modules/@react-native-community/async-storage/android') ++ project(':@react-native-community_async-storage').projectDir = new File(rootProject.projectDir, '../node_modules/@react-native-community/async-storage-backend-legacy/android') ``` 2. In `android/app/build.gradle` add to dependencies: ```diff dependencies { ... -+ implementation project(':@react-native-community_async-storage') ++ implementation project(':@react-native-community_async-storage-backend-legacy') } ``` diff --git a/docs/OLD/advanced/BrownfieldIntegration.md b/packages/storage-legacy/docs/advanced/BrownfieldIntegration.md similarity index 100% rename from docs/OLD/advanced/BrownfieldIntegration.md rename to packages/storage-legacy/docs/advanced/BrownfieldIntegration.md diff --git a/docs/OLD/advanced/IncreaseDbSize.md b/packages/storage-legacy/docs/advanced/IncreaseDbSize.md similarity index 100% rename from docs/OLD/advanced/IncreaseDbSize.md rename to packages/storage-legacy/docs/advanced/IncreaseDbSize.md diff --git a/packages/storage-legacy/package.json b/packages/storage-legacy/package.json index d0c9d28d..7f5c5fc5 100644 --- a/packages/storage-legacy/package.json +++ b/packages/storage-legacy/package.json @@ -3,8 +3,11 @@ "version": "2.0.0", "main": "build/index.js", "types": "types/index.d.ts", - "author": "Krzysztof Borowy ", + "author": "ReactNative Community", "license": "MIT", + "publishConfig": { + "access": "public" + }, "scripts": { "build": "babel src --root-mode upward --out-dir build/ --extensions .ts --ignore build/**/* --ignore types/**/* --source-maps inline", "clean": "rm build -rf", @@ -13,7 +16,7 @@ "test:lint": "eslint ./**/*.ts" }, "dependencies": { - "@react-native-community/async-storage": "^2.0.0" + "@react-native-community/async-storage": "^2.0.0-rc0" }, "peerDependencies": { "react": "^16.0", diff --git a/packages/storage-legacy/src/index.ts b/packages/storage-legacy/src/index.ts index 006f1dd5..63ac2697 100644 --- a/packages/storage-legacy/src/index.ts +++ b/packages/storage-legacy/src/index.ts @@ -21,6 +21,28 @@ function convertErrors(errs?: Array | Error) { return Array.isArray(errs) ? errs.filter(e => !!e) : [errs]; } +function checkValidInput(usedKey: any, value?: any) { + const isValuePassed = arguments.length > 1; + + if (typeof usedKey !== 'string') { + console.warn( + `[AsyncStorageLegacy] Using "${typeof usedKey}" type for key is not supported. This can lead to unexpected behavior/errors. Use string instead.\nKey passed: ${usedKey}\n`, + ); + + if (isValuePassed && typeof value !== 'string') { + if (value == null) { + throw new Error( + `[AsyncStorageLegacy] Passing "null" or "undefined" as value is not supported. If you need to remove a value, use ".removeSingle" method instead.\nPassed value: ${value}\nPassed key: ${usedKey}\n`, + ); + } else { + console.warn( + `[AsyncStorageLegacy] The value for key "${usedKey}" is not a string. This can lead to unexpected behavior/errors. Consider stringifying it.\nPassed value: ${value}\nPassed key: ${usedKey}\n`, + ); + } + } + } +} + export default class LegacyAsyncStorage< T extends EmptyStorageModel = EmptyStorageModel > implements IStorageBackend { @@ -28,9 +50,7 @@ export default class LegacyAsyncStorage< constructor() { this._asyncStorageNativeModule = - NativeModules.RNC_AsyncSQLiteDBStorage || - NativeModules.RNCAsyncStorage || - NativeModules.PlatformLocalStorage; + NativeModules.RNC_AsyncSQLiteDBStorage || NativeModules.RNCAsyncStorage; if (!this._asyncStorageNativeModule) { throw new Error( @@ -46,6 +66,7 @@ export default class LegacyAsyncStorage< if (opts) { // noop } + checkValidInput(key); return new Promise((resolve, reject) => { this._asyncStorageNativeModule.multiGet([key], function( @@ -71,6 +92,7 @@ export default class LegacyAsyncStorage< if (opts) { // noop } + checkValidInput(key, value); return new Promise((resolve, reject) => { this._asyncStorageNativeModule.multiSet([[key, value]], function( @@ -93,6 +115,7 @@ export default class LegacyAsyncStorage< if (opts) { // noop } + keys.forEach(checkValidInput); return new Promise((resolve, reject) => { this._asyncStorageNativeModule.multiGet(keys, function( @@ -127,6 +150,11 @@ export default class LegacyAsyncStorage< if (opts) { // noop } + values.forEach(keyValue => { + (Object.keys(keyValue) as Array).forEach(key => { + checkValidInput(key, keyValue[key]); + }); + }); return new Promise((resolve, reject) => { const valuesArray = values.map(entry => { @@ -149,6 +177,7 @@ export default class LegacyAsyncStorage< if (opts) { // noop } + checkValidInput(key); return new Promise((resolve, reject) => { this._asyncStorageNativeModule.multiRemove([key], function( @@ -168,6 +197,7 @@ export default class LegacyAsyncStorage< if (opts) { // noop } + keys.forEach(checkValidInput); return new Promise((resolve, reject) => { this._asyncStorageNativeModule.multiRemove(keys, function( diff --git a/packages/storage-web/package.json b/packages/storage-web/package.json index 24e9dee5..312a42a3 100644 --- a/packages/storage-web/package.json +++ b/packages/storage-web/package.json @@ -3,8 +3,11 @@ "version": "2.0.0", "main": "build/index.js", "types": "types/index.d.ts", - "author": "Krzysztof Borowy ", + "author": "ReactNative Community", "license": "MIT", + "publishConfig": { + "access": "public" + }, "scripts": { "build": "babel src --root-mode upward --out-dir build/ --extensions .ts --ignore build/**/* --ignore types/**/* --source-maps inline", "clean": "rm build -rf", @@ -12,7 +15,7 @@ "test:types": "tsc" }, "dependencies": { - "@react-native-community/async-storage": "^2.0" + "@react-native-community/async-storage": "^2.0.0-rc0" }, "peerDependencies": { "react": "^16.0",