initial commit

.gitignore

@@ -1,11 +1,4 @@
-# Build and Release Folders
-bin/
-bin-debug/
-bin-release/
-
-# Other files and folders
-.settings/
-
-# Project files, i.e. `.project`, `.actionScriptProperties` and `.flexProperties`
-# should NOT be excluded as they contain compiler settings and other important
-# information for Eclipse / Flash Builder.
+node_modules/
+_book/
+npm-debug.log
+.idea

README.md

@@ -1,2 +1,236 @@
-# redux-saga-in-chinese
-Redux-saga 中文文档
+# [Redux-saga 中文文档](https://github.com/superRaytin/redux-saga-in-chinese)
+
+文档版本号：0.9.5
+
+> 在线 Gitbook 地址：http://superRaytin.github.io/redux-saga
+>
+> 英文原版：http://yelouafi.github.io/redux-saga
+
+[![Join the chat at https://gitter.im/yelouafi/redux-saga](https://badges.gitter.im/yelouafi/redux-saga.svg)](https://gitter.im/yelouafi/redux-saga?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
+
+An alternative Side Effects middleware (aka Asynchronous Actions) for Redux applications.
+Instead of dispatching Thunks which get handled by the `redux-thunk` middleware, you
+create *Sagas* to gather all your Side Effects logic in a central place.
+
+This means application logic lives in 2 places:
+
+- Reducers are responsible for handling state transitions between actions.
+
+- Sagas are responsible for orchestrating complex/asynchronous operations.
+
+Sagas are created using Generator functions. If you're not familiar with them you may find
+[some useful links here](http://yelouafi.github.io/redux-saga/docs/ExternalResources.html)
+
+Unlike Thunks which get invoked on every action by Action Creators, Sagas are fired only
+once at the start of the application (but startup Sagas may fire other Sagas dynamically).
+They can be seen as Processes running in the background. Sagas watch the actions dispatched
+to the Store, then decide what to do based on dispatched actions: Either making an asynchronous
+call (like an AJAX request), dispatching other actions to the Store, or even starting other
+Sagas dynamically.
+
+In `redux-saga` all the above tasks are achieved by yielding **Effects**. Effects are simply
+JavaScript Objects containing instructions to be executed by the Saga middleware (As an analogy,
+you can see Redux actions as Objects containing instructions to be executed by the Store).
+`redux-saga` provides Effect creators for various tasks like calling an asynchronous function,
+dispatching an action to the Store, starting a background task or waiting for a future action
+that satisfies a certain condition.
+
+Using Generators, `redux-saga` allows you to write your asynchronous code in a simple
+synchronous style. Just like you can do with `async/await` functions. But Generators
+allow some things that aren't possible with `async` functions.
+
+The fact that Sagas yield plain Objects makes it easy to test all the logic inside your Generator
+by simply iterating over the yielded Objects and doing simple equality tests.
+
+Furthermore, tasks started in `redux-saga` can be cancelled at any moment either manually
+or automatically by putting them in a race with other Effects.
+
+# Getting started
+
+## Install
+
+```
+npm install --save redux-saga
+```
+
+Alternatively, you may use the provided UMD builds directly in the `<script>` tag of
+an HTML page. See [this section](#using-umd-build-in-the-browser)
+
+## Usage Example
+
+Suppose we have an UI to fetch some user data from a remote server when a button is clicked
+(For brevity, we'll just show the action triggering code).
+
+```javascript
+class UserComponent extends React.Component {
+  ...
+  onSomeButtonClicked() {
+    const { userId, dispatch } = this.props
+    dispatch({type: 'USER_FETCH_REQUESTED', payload: {userId}})
+  }
+  ...
+}
+```
+
+The Component dispatches a plain Object action to the Store. We'll create a Saga that
+watches for all `USER_FETCH_REQUESTED` actions and triggers an API call to fetch the
+user data
+
+#### `sagas.js`
+```javascript
+import { takeEvery, takeLatest } from 'redux-saga'
+import { call, put } from 'redux-saga/effects'
+import Api from '...'
+
+// worker Saga : will be fired on USER_FETCH_REQUESTED actions
+function* fetchUser(action) {
+   try {
+      const user = yield call(Api.fetchUser, action.payload.userId);
+      yield put({type: "USER_FETCH_SUCCEEDED", user: user});
+   } catch (e) {
+      yield put({type: "USER_FETCH_FAILED", message: e.message});
+   }
+}
+
+/*
+  starts fetchUser on each dispatched `USER_FETCH_REQUESTED` action
+  Allow concurrent fetches of user
+*/
+function* mySaga() {
+  yield* takeEvery("USER_FETCH_REQUESTED", fetchUser);
+}
+
+/*
+  Alternatively you may use takeLatest
+
+  Do not allow concurrent fetches of user, If "USER_FETCH_REQUESTED" gets
+  dispatched while a fetch is already pending, that pending fetch is cancelled
+  and only the latest one will be run
+*/
+function* mySaga() {
+  yield* takeLatest("USER_FETCH_REQUESTED", fetchUser);
+}
+```
+
+To run our Saga, we'll have to connect it to the Redux Store using the `redux-saga` middleware
+
+#### `main.js`
+```javascript
+import { createStore, applyMiddleware } from 'redux'
+import createSagaMiddleware from 'redux-saga'
+
+import reducer from './reducers'
+import mySaga from './sagas'
+
+const sagaMiddleware = createSagaMiddleware(mySaga)
+const store = createStore(
+  reducer,
+  applyMiddleware(sagaMiddleware)
+)
+
+// render the application
+```
+
+# Documentation
+
+- [Introduction](http://yelouafi.github.io/redux-saga/docs/introduction/index.html)
+- [Basic Concepts](http://yelouafi.github.io/redux-saga/docs/basics/index.html)
+- [Advanced Concepts](http://yelouafi.github.io/redux-saga/docs/advanced/index.html)
+- [Recipes](http://yelouafi.github.io/redux-saga/docs/recipes/index.html)
+- [External Resources](http://yelouafi.github.io/redux-saga/docs/ExternalResources.html)
+- [Troubleshooting](http://yelouafi.github.io/redux-saga/docs/Troubleshooting.html)
+- [Glossary](http://yelouafi.github.io/redux-saga/docs/Glossary.html)
+- [API Reference](http://yelouafi.github.io/redux-saga/docs/api/index.html)
+
+# Using umd build in the browser
+
+There's also an **umd** build of `redux-saga` available in the `dist/` folder. When using the umd build
+`redux-saga` is available as `ReduxSaga` in the window object.
+
+The umd version is useful if you don't use Webpack or Browserify. You can access it directly from [npmcdn](npmcdn.com).
+
+The following builds are available:
+
+- [https://npmcdn.com/redux-saga/dist/redux-saga.js](https://npmcdn.com/redux-saga/dist/redux-saga.js)
+- [https://npmcdn.com/redux-saga/dist/redux-saga.min.js](https://npmcdn.com/redux-saga/dist/redux-saga.min.js)
+
+**Important!** If the browser you are targeting doesn't support _es2015 generators_ you must provide a valid polyfill,
+for example the one provided by *babel*:
+[browser-polyfill.min.js](https://cdnjs.cloudflare.com/ajax/libs/babel-core/5.8.25/browser-polyfill.min.js).
+The polyfill must be imported before **redux-saga**.
+
+```javascript
+import 'babel-polyfill'
+// then
+import sagaMiddleware from 'redux-saga'
+```
+
+# Building examples from sources
+
+```
+git clone https://github.com/yelouafi/redux-saga.git
+cd redux-saga
+npm install
+npm test
+```
+
+Below are the examples ported (so far) from the Redux repos
+
+### Counter examples
+
+There are 3 counter examples
+
+#### counter-vanilla
+
+Demo using vanilla JavaScript and UMD builds. All source is inlined in `index.html`
+
+To launch the example, just open `index.html` in your browser
+
+>Important
+Your browser must support Generators. Latest versions of Chrome/Firefox/Edge are suitable.
+
+
+#### counter
+
+Demo using webpack and high level API `takeEvery`
+
+```
+npm run counter
+
+// test sample for the generator
+npm run test-counter
+```
+
+#### cancellable-counter
+
+Demo using low level API. Demonstrate task cancellation
+
+```
+npm run cancellable-counter
+```
+
+### Shopping Cart example
+
+```
+npm run shop
+
+// test sample for the generator
+npm run test-shop
+```
+
+### async example
+
+```
+npm run async
+
+//sorry, no tests yet
+```
+
+### real-world example (with webpack hot reloading)
+
+```
+npm run real-world
+
+//sorry, no tests yet
+```
+

book.json

@@ -0,0 +1,16 @@
+{
+  "gitbook": "2.3.3",
+  "structure": {
+    "summary": "docs/README.md"
+  },
+  "plugins": ["edit-link", "prism", "ga"],
+  "pluginsConfig": {
+    "edit-link": {
+      "base": "https://github.com/superRaytin/redux-saga-in-chinese/tree/master",
+      "label": "开始纠错"
+    },
+    "ga": {
+      "token": "UA-58588801-2"
+    }
+  }
+}

docs/ExternalResources.md

@@ -0,0 +1,22 @@
+# External Resources
+
+### Articles on Generators
+
+- [The Basics Of ES6 Generators](https://davidwalsh.name/es6-generators) By Kyle Simpson
+- [ES6 generators in depth](http://www.2ality.com/2015/03/es6-generators.html) By Axel Rauschmayer
+
+### Articles on redux-saga
+
+- [Redux nowadays : From actions creators to sagas](http://riadbenguella.com/from-actions-creators-to-sagas-redux-upgraded/)
+By Riad Benguella
+- [Managing Side Effects In React + Redux Using Sagas](http://jaysoo.ca/2016/01/03/managing-processes-in-redux-using-sagas/)
+By Jack Hsu
+- [Using redux-saga To Simplify Your Growing React Native Codebase](https://medium.com/infinite-red/using-redux-saga-to-simplify-your-growing-react-native-codebase-2b8036f650de#.7wl4wr1tk)
+By Steve Kellock
+- [Master Complex Redux Workflows with Sagas](http://konkle.us/master-complex-redux-workflows-with-sagas/)
+By Brandon Konkle
+- [Handling async in Redux with Sagas](http://wecodetheweb.com/2016/01/23/handling-async-in-redux-with-sagas/)
+By Niels Gerritsen
+- [Tips to handle Authentication in Redux](https://medium.com/@MattiaManzati/tips-to-handle-authentication-in-redux-2-introducing-redux-saga-130d6872fbe7#.g49x2gj1g) By Mattia Manzati
+
+- [Build an Image Gallery Using React, Redux and redux-saga](http://joelhooks.com/blog/2016/03/20/build-an-image-gallery-using-redux-saga/?utm_content=bufferbadc3&utm_medium=social&utm_source=twitter.com&utm_campaign=buffer) By Joel Hooks

docs/Glossary.md

@@ -0,0 +1,71 @@
+# Glossary
+
+This is a glossary of the core terms in Redux Saga.
+
+### Effect
+
+An effect is a plain JavaScript Object containing some instructions to be executed by the saga middleware.
+
+You create effects using factory functions provided by the redux-saga library. For example you use
+`call(myfunc, 'arg1', 'arg2')` to instruct the middleware to invoke `myfunc('arg1', 'arg2')` and return
+the result back to the Generator that yielded the effect
+
+### Task
+
+A task is like a process running in background. In a redux-saga based application there can be
+multiple tasks running in parallel. You create tasks by using the `fork` function
+
+```javascript
+function* saga() {
+  ...
+  const task = yield fork(otherSaga, ...args)
+  ...
+}
+```
+
+### Blocking/Non-blocking call
+
+A Blocking call means that the Saga yielded an Effect and will wait for the outcome of its execution before
+resuming to the next instruction inside the yielding Generator.
+
+A Non-blocking call means that the Saga will resume immediately after yielding the Effect.
+
+For example
+
+```javascript
+function* saga() {
+  yield take(ACTION)              // Blocking: will wait for the action
+  yield call(ApiFn, ...args)      // Blocking: will wait for ApiFn (If ApiFn returns a Promise)
+  yield call(otherSaga, ...args)  // Blocking: will wait for otherSaga to terminate
+
+  yied put(...)                   // Blocking: will dispatch asynchronously (using Promis.then)
+
+  const task = yield fork(otherSaga, ...args)  // Non-blocking: will not wait for otherSaga
+  yield cancel(task)                           // Non-blocking: will resume immediately
+  // or
+  yield join(task)                              // Blocking: will wait for the task to terminate
+}
+```
+
+### Watcher/Worker
+
+refers to a way of organizing the control flow using two separate Sagas
+
+- The watcher: will watch for dispatched actions and fork a worker on every action
+
+- The worker: will handle the action and terminate
+
+example
+
+```javascript
+function* watcher() {
+  while(true) {
+    const action = yield take(ACTION)
+    yield fork(worker, action.paylaod)
+  }
+}
+
+function* worker(paylaod) {
+  // ... do some stuff
+}
+```

docs/README.md

@@ -0,0 +1,28 @@
+## Table of Contents
+
+* [Read Me](/README.md)
+* [Introduction](/docs/introduction/README.md)
+  * [BeginnerTutorial](/docs/introduction/BeginnerTutorial.md)
+  * [Saga background](/docs/introduction/SagaBackground.md)
+* [Basic Concepts](/docs/basics/README.md)
+  * [Using Saga Helpers](/docs/basics/UsingSagaHelpers.md)
+  * [Declarative Effects](/docs/basics/DeclarativeEffects.md)
+  * [Dispatching actions](/docs/basics/DispatchingActions.md)
+  * [Error handling](/docs/basics/ErrorHandling.md)
+  * [A common abstraction: Effect](/docs/basics/Effect.md)
+* [Advanced Concepts](/docs/advanced/README.md)
+  * [Pulling future actions](/docs/advanced/FutureActions.md)
+  * [Non blocking calls](/docs/advanced/NonBlockingCalls.md)
+  * [Running tasks in parallel](/docs/advanced/RunningTasksInParallel.md)
+  * [Starting a race between multiple Effects](/docs/advanced/RacingEffects.md)
+  * [Sequencing Sagas using yield*](/docs/advanced/SequencingSagas.md)
+  * [Composing Sagas](/docs/advanced/ComposingSagas.md)
+  * [Task cancellation](/docs/advanced/TaskCancellation.md)
+  * [Common Concurrency Patterns](/docs/advanced/Concurrency.md)
+  * [Examples of Testing Sagas](/docs/advanced/Testing.md)
+  * [Connecting Sagas to external Input/Output](/docs/advanced/UsingRunSaga.md)
+* [Recipes](/docs/recipes/README.md)
+* [External Resources](/docs/ExternalResources.md)
+* [Troubleshooting](/docs/Troubleshooting.md)
+* [Glossary](/docs/Glossary.md)
+* [API Reference](/docs/api/README.md)