doc improvements for saga vs thunk, handling simple cases

[ghost]

This seems like some low hanging fruit that would aid newcomers.

When reading the docs it's not immediately clear to me how to use a saga in "the simplest case". By simplest case I mean there is a view button that triggers a callback, and that callback has async behavior. In a redux-thunk implementation, that callback would be a bound action creator with some middleware to handle the async nature of the callback:

<button onClick={this.props.login} />

...

mapDispatchToProps(dispatch) {
    return bindActionCreators(actionCreators, dispatch)
}

...

let actionCreators = {
    login() {
        return (dispatch, getState) => {
            dispatch({
                type: LOGIN_REQUEST
            })

            return xhr({
                method: 'POST'
                , url: api.login
            })
            .then((res) => {
                if (res.statusCode === 200) {
                    dispatch({
                        type: LOGIN_SUCCESS
                    })
                }
            })
        }
    }
}

The docs say redux-saga is a replacement/alternative for redux-thunk or other middlewares, and neatly explains how sagas are a much more powerful construct, especially when dealing with longer running sequences of events. However, it's not immediately clear whether the use case of "one event, one action" also falls under a saga's domain, or how we might implement that case. This is how I would do it, but I'm open to suggestions:

let actionCreators = {
    login({ username, password }) {
        return {
            username
            , password
            , type: LOGIN
        }
    }
    , loginRequest() {
        return {
            type: actions.DO_LOGIN_REQUEST
        }
    }
    , loginError() {
        return {
            type: actions.DO_LOGIN_ERROR
        }
    }
    , loginFailure() {
        return {
            type: actions.DO_LOGIN_FAilURE
        }
    }
    , loginSuccess(response) {
        return {
            response
            , type: actions.DO_LOGIN_SUCCESS
        }
    }
}

function* watchForLogin() {
    while (true) {
        const { username, password } = yield take(actions.LOGIN)
        yield call(login, { username, password })
    }
}

function* login({ username, password }) {
    yield put(actionCreators.loginRequest())
    let { statusCode, body } = yield call(doLogin, { username, password })

    if (statusCode > 499) {
        yield put(actionCreators.loginError())
        return
    }

    if (statusCode > 399) {
        yield put(actionCreators.loginFailure())
        return
    }

    yield put(actionCreators.loginSuccess(body))
}

function* doLogin({ username, password }) {
    const b64 = btoa(`${username}:${password}`)
    return xhr({
        method: 'POST'
        , url: api.login
        , headers: {
            'authorization': `Basic ${b64}`
        }
    })
}

First, is this the "right way" to make a one-to-one, or is there a cleaner approach than having an explicit "start this saga" action creator callback? Second, do you think this is something that should appear in the docs?

[ghost]

@aft-luke I like the one-to-one comparison. Using a login example highlights the differences between redux-thunk and redux-saga quite well.

I'm just starting out with redux-saga and getting familiar with it so I can't answer your first question.

Should it appear in the docs? As a new user I think it would help to have a one-to-one example from redux-thunk considering most people using redux will be familiar with it.

If it would be a welcome addition, I wouldn't mind working on a PR to use gitbook for documentation. The cost would be harder upkeep of the docs (e.g. making sure these types of examples still work, etc). There is a certain beauty about keeping all the documentation in a single README.md, but by using something like gitbook these additional examples can be added in without worrying about bloat.

[yelouafi]

Sagas that milmics the thunk callbacks are generally wrapped inside a while(true). the examples dir re-implement some of the original redux/thunk examples so I don't think there is a lack on this side. although I agree there is a lack on the docs side: step by step tutorials; showcase of complex flow implementations; handling common concurrency concerns...)

@trevorsenior

If it would be a welcome addition, I wouldn't mind working on a PR to use gitbook for documentation

Didn't work with gitbook before; but from the site docs, it seems like publishing gitbooks isn't done in the Github repo but instead on the gitbook site https://github.com/GitbookIO/gitbook#publish-your-book.

Of course any contribution is welcome

[gaearon]

Didn't work with gitbook before; but from the site docs, it seems like publishing gitbooks isn't done in the Github repo but instead on the gitbook site https://github.com/GitbookIO/gitbook#publish-your-book.

The site is optional, you can totally make it work with Github Pages. You can check out docs:publish in package.json of Redux to get an idea.

[danscan]

I'm new to redux-saga and checking out the Readme with no prior knowledge. The one thing I'm really puzzled by is the difference between take, put, etc. Even a bulleted list of the API methods with one-liners would be very helpful.

[yelouafi]

@danscan yeap; API docs is terribly lacking; hope to do it soon.

[yelouafi]

opened #70 to centralize feedback

[yelouafi]

also will close this; feel free to add your suggestions to #70

[yelouafi]

@danscan there is a new section for API docs

http://yelouafi.github.io/redux-saga/docs/api/index.html

Will be adding more content later