Unclear 'runSaga' options and subscribe field documentation

The documentation about runSaga options is very unclear.

First: options: Object : https://redux-saga.js.org/docs/api/index.html#runsagaoptions-saga-args

the function signature is runSaga(options, saga, ...args) But then where the rest of the fields belong to? dispatch(output), getState() ? Do they still belong to the options?

Second: subscribe field:

subscribe(callback): Function - A function which accepts a callback and returns an unsubscribe function

callback(input): Function - callback(provided by runSaga) used to subscribe to input events. subscribe must support registering multiple subscriptions.
input: any - argument passed by subscribe to callback (see Notes below)

I am having a really hard time to understand what this means, I suppose the function should look something like this.

subscribe: (callback) => {
    //Subscribe function
    callback(input);

    //Unsubscribe function
    return () => { //some code };
},

How can I use it to resolve a take effects for example?. Would be nice to have some examples also. In the testing section Testing the full Saga, there are some nice example, but without using the subscribe field

[Andarist]

I’ve updated docs around this API - https://github.com/redux-saga/redux-saga/commit/466c5a4f8e941fb0f30a6e6dfb40310883876856 . Keep in mind that it was adjusted to v1, which we are going to release soon.

Is this now clearer or do you feel something still could get improved?

[arnaudambro]

OK regarding my last comment, I improved my code a little bit, it is still not working yet : even if the event emitter works properly, the channel.put is called, but the action is never caught. I think there is a problem with the channel but I don’t see where…

Here is my code:

import { runSaga, channel as stdChannel, take, put, select } from 'redux-saga';
import EventEmitter from  'event-emitter';

const recordSaga = async (saga, initialAction, state, onReceiveSend = [], emitter = new EventEmitter()) => {
  const dispatched = [];
  let actionToEmit = 0;

  const channel = stdChannel()
  emitter.on("action", channel.put)

  const done = await runSaga(
    {
      channel,
      dispatch: action => {
        if (onReceiveSend.length &&
              (onReceiveSend.length <= actionToEmit + 1) &&
                onReceiveSend[actionToEmit].receive === action.type) {
          emitter.emit("action", { type: onReceiveSend[actionToEmit].send })
          actionToEmit++
        }
        dispatched.push(action)
      },
      getState: () => state,
    },
    saga,
    initialAction,
  ).done;

  return {
    dispatched,
    done,
  };
};

function* mySaga() {
  const needToSave = yield select(needToSaveDocument);
  if (needToSave) {
    yield put({ type: 'SAVE_DOCUMENT_REQUEST' } );
    yield take('SAVE_DOCUMENT_SUCCESS');
  }
  yield put(doSomethingElse())
}

describe('mySaga', async () => {
  it('test 1: no need to save', async () => {    
    const state = { needToSave: false }
    const { dispatched } = await recordSaga(mySaga, {}, state);
    expect(dispatched).toEqual([
      doSomethingElse()
    ])
  })
  it('test 2: need to save', async () => {
    const state = { needToSave: true }
    const onReceiveSend = [
      {
         receive: 'SAVE_DOCUMENT_REQUEST',
         send: 'SAVE_DOCUMENT_SUCCESS'
      }
    ]
    const { dispatched } = await recordSaga(mySaga, {}, state, onReceiveSend);
    expect(dispatched).toEqual([
      saveDocument(),
      doSomethingElse()
    ])
  })
})