README.md

remember-js

remember-js is used to remember some program operations and redo those if needed.

Installing

Use via npm:

$ npm install remember-js

const Remember = require('remember-js');

// Use es6 import
import Remember from 'remember-js';

Use in browser:

Scripts for browser is under build directory, use remember.js for development environment(contains inline source maps), use remember.min.js for production. The references in browser is window.Remember.

Conventions

Remember is the main class of remember-js package and remember is an instance of Remember. An action type is a unique string identifying a callback that doing some program operations. An action is a call of an action type.

A common problem

Suppose you have an app running in browser and it needs to send user produced information to server by ajax requests, you hope your app can work even when the network is off. To solve this problem your app should remember the request that is failed because of network error, and resend it when the network is on or even when the user reload your app next time. Using remember-js can solve this problem, and let's write an example:

First, we will create a Remember instance and register some remember action types, and the file name is remember.js.

import Remember from 'remember-js';
import axios from 'axios'; // A promise based HTTP client, you can google and learn more about it.

const remember = new Remember({
    storage: window.localStorage,
    storageId: 'my-app-remember-id'
  });

export const SAVE_USERNAME = 'SAVE_USERNAME';

remember.registerAction(SAVE_USERNAME, function (remember, userId, username) {
  return axios({
    method: "patch",
    url: `/api/users/${userId}`,
    data: {action: 'update', path: 'username', value: username}
  }).catch(function(err){
    if(err.data === 'undefined'){
      // If this error is caused by a network error instead of a server side error, remember this action.
      // This is a special checking method for axios, for other HTTP client like jQuery.ajax please
      // look for a right way to identify that it's a network error.
      remember();
    }
  });
});

// Here, we simply run consume method every 5 seconds to redo remembered actions.
setInterval(function(){
  remember.consume();
}, 5000);

export default remember;

Second, use the registered remember action types. The file name is test.js and it has the same directory with remember.js.

import remember, { SAVE_USERNAME } from './remember.js';

remember.do(SAVE_USERNAME, 'userId', 'username');

Examples

Using MemoryStorage (it's the default storage) to process actions sequentially.

// Instantiate a Remember instance
import Remember from 'remember-js';

const remember = new Remember({
    inSequence: true, // Pay attention to this option, it's different from the 'A common problem' example.
    storageId: 'my-app-remember-id'
  });

// Register and export some action types
export const FIRST_ACTION = 'FIRST_ACTION';
export const SECOND_ACTION = 'SECOND_ACTION';

remember.registerAction(FIRST_ACTION, function(next, param1, param2){
  // Do something with params
  next();
});

remember.registerAction(SECOND_ACTION, function(next){
  // Do something
  next();
});

// Do actions: FIRST_ACTION and then SECOND_ACTION.
// If FIRST_ACTION call is failed(the next callback is not called for some reasons), the consuming will stop with FIRST_ACTION call and SECOND_ACTION call stored in storage.
// Under the hood, every time remember does an action it will store this action first and then consume.
remember.do(FIRST_ACTION, 'param1', 'param2');
remember.do(SECOND_ACTION);

Constructor and methods

Remember(options)

Option	Description	type	default
inSequence	If it's true, the remember will make sure that all the actions is completed in the order they are called.	Boolean	false
storageId	The storage identity to use to store the action, you should provide your own if you are going to use more than one remembers.	String	'#REMEMBER_JS_REMEMBER_QUEUE'
storage	The storage used to store actions. It's required to provide two methods: getItem(key) and setItem(key, value), you can use localStorage or sessionStorage directly in browser context.	Object	MemoryStorage.
onConsumingComplete	If the inSequence parameter is true and the stored actions is not empty, this callback will be called when stored actions are all completed.	Function	undefined

The inSequence option can define two different types of remember. If it's true, the callback of remember.registerAction will be passed a next parameter which is used to tell remember that the current action is completed and do next action please. If it's false, the callback of remember.registerAction will be passed a remember parameter which is used to tell remember that the current action is failed and store it please.

remember.registerAction(name, callback)

Param	Description	type	default
name	The name to identify an action type.	String	undefined
callback	The callback to do some operations when this action type is called.	Function	undefined

remember.do(name, a, b, c, d, e, f)

Param	Description	type	default
name	The action type to use.	String	undefined
a, b, c, d, e, f	Parameters that will be passed to action type callback.	Any type	undefined

remember.set(options)

This method is used to set remember options, parameter options is the same with Remember's.

remember.consume()

This method is used to consume stored actions.

remember.clear()

This method is used to remove all stored actions.

License

MIT