Git Product home page Git Product logo

react-native-storage's Introduction

react-native-storage Build Status npm version

This is a local storage wrapper for both react-native(AsyncStorage) and browser(localStorage). ES6 syntax, promise for async load, fully tested with jest.

查看中文文档请点击README-CHN.md

Install

npm install react-native-storage --save

Usage

Config

For Web

You need to use webpack and babel to enable es6 modules for web development.
You should add the following lines to your webpack config:

  // ...
  module: {
    loaders: [
      // ...
        {
          test: /\.js?$/,
          include: [
            // path.join(__dirname, 'your-own-js-files'),
            // path.join(__dirname, 'node_modules/some-other-lib-that-needs-babel'),
            path.join(__dirname, 'node_modules/react-native-storage')
          ],
          loader: 'babel',
          query: {
            cacheDirectory: true,
            presets: ['es2015', 'stage-1', 'react'],
            plugins: ['transform-runtime']
          }
        }
    ]
  }

For React Native

You don't have to configure anything(but require react native version >= 0.13).

Import

import Storage from 'react-native-storage';

Do not use require('react-native-storage'), which would cause error in react native version >= 0.16.

Init

import Storage from 'react-native-storage';
import { AsyncStorage } from 'react-native';

var storage = new Storage({
	// maximum capacity, default 1000 
	size: 1000,

	// Use AsyncStorage for RN, or window.localStorage for web.
	// If not set, data would be lost after reload.
	storageBackend: AsyncStorage,
	
	// expire time, default 1 day(1000 * 3600 * 24 milliseconds).
	// can be null, which means never expire.
	defaultExpires: 1000 * 3600 * 24,
	
	// cache data in the memory. default is true.
	enableCache: true,
	
	// if data was not found in storage or expired,
	// the corresponding sync method will be invoked and return 
	// the latest data.
	sync : {
		// we'll talk about the details later.
	}
})	

// I suggest you have one(and only one) storage instance in global scope.

// for web
// window.storage = storage;

// for react native
// global.storage = storage;

Save & Load & Remove

// Save something with key only. 
// Something more unique, and constantly being used.
// They are permanently stored unless you remove.
storage.save({
	key: 'loginState',   // Note: Do not use underscore("_") in key!
	data: { 
		from: 'some other site',
		userid: 'some userid',
		token: 'some token'
	},
	
	// if not specified, the defaultExpires will be applied instead.
	// if set to null, then it will never expire.
	expires: 1000 * 3600
});

// load
storage.load({
	key: 'loginState',
	
	// autoSync(default true) means if data not found or expired,
	// then invoke the corresponding sync method
	autoSync: true,
	
	// syncInBackground(default true) means if data expired,
	// return the outdated data first while invoke the sync method.
	// It can be set to false to always return data provided by sync method when expired.(Of course it's slower)
	syncInBackground: true,
	
	// you can pass extra params to sync method
	// see sync example below for example
	syncParams: {
	  extraFetchOptions: {
	    // blahblah
	  },
	  someFlag: true,
	},
}).then(ret => {
	// found data go to then()
	console.log(ret.userid);
}).catch(err => {
	// any exception including data not found 
	// goes to catch()
	console.warn(err.message);
	switch (err.name) {
	    case 'NotFoundError':
	        // TODO;
	        break;
        case 'ExpiredError':
            // TODO
            break;
	}
})

// --------------------------------------------------

// Save something with key and id. Something of the same type(key). 
// There is a quota over "key-id" data(the size parameter you pass in constructor).
// By default the 1001th data will overwrite the 1st data. 
// If you then load the 1st data, a catch(NotFoundError) or sync will be invoked.
var userA = {
	name: 'A',
	age: 20,
	tags: [
		'geek',
		'nerd',
		'otaku'
	]
};

storage.save({
	key: 'user',  // Note: Do not use underscore("_") in key!
	id: '1001',	  // Note: Do not use underscore("_") in id!	
	data: userA,
	expires: 1000 * 60	 
});

// load
storage.load({
	key: 'user',
	id: '1001'
}).then(ret => {
	// found data goes to then()
	console.log(ret.userid);
}).catch(err => {
	// any exception including data not found 
	// goes to catch()
	console.warn(err.message);
	switch (err.name) {
	    case 'NotFoundError':
	        // TODO;
	        break;
        case 'ExpiredError':
            // TODO
            break;
	}
});

// --------------------------------------------------

// get all ids for "key-id" data under a key but not "key-only" data
storage.getIdsForKey('user').then(ids => {
    console.log(ids);
});

// get all "key-id" data under a key but not "key-only" data
storage.getAllDataForKey('user').then(users => {
    console.log(users);
});

// !! clear all "key-id" data under a key but keep the "key-only" data
storage.clearMapForKey('user');


// --------------------------------------------------  

// remove a single record
storage.remove({
	key: 'lastPage'
});
storage.remove({
	key: 'user',
	id: '1001'
});

// !! clear map and remove all "key-id" data but keep the "key-only" data
storage.clearMap();

Sync remote data(refresh)

You can pass sync methods as one object parameter to the storage constructor, but also you can add it any time.

storage.sync = {

	// The name of the sync method must be the same of the data's key
	// And the passed params will be an all-in-one object.
	// You can use promise here. 
	// Or plain callback function with resolve/reject, like:
	user(params){
		let { id, resolve, reject, syncParams: { extraFetchOptions, someFlag } } = params;
		fetch('user/', {
			method: 'GET',
			body: 'id=' + id,
		    ...extraFetchOptions,
		}).then(response => {
			return response.json();
		}).then(json => {
			// console.log(json);
			if(json && json.user){
				storage.save({
					key: 'user',
					id,
					data: json.user
				});
				
				if (someFlag) {
				  // do something for this extra param
				}
				
				// Call resolve() when succeed
				resolve && resolve(json.user);
			}
			else{
				// Call reject() when failed
				reject && reject(new Error('data parse error'));
			}
		}).catch(err => {
			console.warn(err);
			reject && reject(err);
		});
	}
}

With this example sync method, when you invoke:

storage.load({
	key: 'user',
	id: '1002'
}).then(...)

If there is no user 1002 stored currently, then storage.sync.user would be invoked to fetch remote data and returned.

Load batch data

// Load batch data with the same parameters as storage.load, but in an array.
// It will invoke sync methods on demand, 
// and finally return them all in an ordered array.

storage.getBatchData([
	{ key: 'loginState' },
	{ key: 'checkPoint', syncInBackground: false },
	{ key: 'balance' },
	{ key: 'user', id: '1009' }
])
.then(results => {
	results.forEach(result => {
		console.log(result); 
	})
})

// Load batch data with one key and an array of ids.
storage.getBatchDataWithIds({
	key: 'user', 
	ids: ['1001', '1002', '1003']
})
.then( ... )

There is a notable difference between the two methods except the arguments. getBatchData will invoke different sync methods(since the keys may be different) one by one when corresponding data is missing. However, getBatchDataWithIds will collect missing data, push their ids to an array, then pass the array to the corresponding sync method(to avoid too many requests) once, so you need to implement array query on server end and handle the parameters of sync method properly(cause the id parameter can be a single string or an array of strings).

You are welcome to ask any question in the issues page.

Changelog

0.2.2

  1. check key availability in clearMapForKey

0.2.0

  1. rawData is now deprecated, use "data" instead!
  2. Upgrade jest to 19.0.0

0.1.5

  1. Now you can pass extra params to sync method.
  2. Fix clearMap

0.1.4

  1. Now you can check error type (NotFoundError and ExpiredError) in catch
  2. Optimize cache strategy

0.1.3

  1. Now you need to specify storageBackend(AsyncStorage or window.localStorage), otherwise the data would not be persisted.

0.1.2

  1. Now when load() failed to find data, it will throw an Error with message instead of undefined.

0.1.1

  1. defaultExpires can be null now, which means never expire.

0.1.0

  1. add getIdsForKey, getAllDataForKey, clearMapForKey methods
  2. fix some expires logic
  3. refactor unit tests

0.0.16

  1. getBatchDataWithIds now won't invoke sync if everything is ready in storage.

0.0.15

  1. Fix bugs in promise chain.
  2. Can be used without any storage backend.(Use in-memory map)

0.0.10

  1. All methods except remove and clearMap are now totally promisified. Even custom sync methods can be promise. So you can chain them now.
  2. Adjust map structure.
  3. Improved some test cases.

react-native-storage's People

Contributors

chriswong avatar henninghall avatar hi-rube avatar infinityblue avatar iwebdev1 avatar nielsswinkels avatar sunnylqm avatar wangshijun avatar xwartz avatar

Watchers

 avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.