TypeScript FSA utilities for redux-saga

Common errors

• TypeError: (0 , typescript_fsa_1.actionCreatorFactory) is not a function

  cause Mismatched major versions between `typescript-fsa-redux-saga` and `typescript-fsa`. `typescript-fsa-redux-saga@2.x` requires `typescript-fsa@3.x`.
  fix Ensure `typescript-fsa` is installed at version `^3.0.0` or later (`npm install typescript-fsa@^3`).

• Error: Could not find type definition for 'redux-saga'

  cause `redux-saga` or its type definitions (`@types/redux-saga`) are not installed, or there's a version mismatch.
  fix Install `redux-saga` and its type definitions: `npm install redux-saga @types/redux-saga`.

Warnings

• breaking Version 2.0.0 upgraded the `typescript-fsa` dependency to `^3.0.0`. Users on `typescript-fsa` v2.x.x must upgrade their `typescript-fsa` package to version 3 or higher, or remain on `typescript-fsa-redux-saga` v1.x.x.
  Fix: Upgrade `typescript-fsa` to `^3.0.0` (`npm install typescript-fsa@^3`) or pin `typescript-fsa-redux-saga` to a version less than 2.0.0.
• gotcha Prior to v1.0.3, generator transpilation had inconsistencies across CommonJS and ES6 builds, sometimes using Babel. From v1.0.3 onwards, Babel was removed, and native TypeScript transpilation is used for generators. This might affect projects with highly customized Babel configurations or those relying on previous specific generator output.
  Fix: Ensure your TypeScript compiler (`tsconfig.json`) is correctly configured for generator transpilation, particularly `target` and `lib` settings, and remove any legacy Babel configurations specific to `typescript-fsa-redux-saga` if present.
• gotcha The `skipStartedAction` option (introduced in v1.1.0) changes the behavior of `bindAsyncAction` significantly. When `true`, the `started` action is *not* dispatched automatically but is expected to be manually dispatched as the trigger for the saga, with the saga then dispatching `done`/`failed`. Incorrect usage can lead to missing `started` actions or unexpected saga triggers.
  Fix: Carefully review the documentation for `skipStartedAction`. If you want automatic `started` action dispatch, do not set this option to `true`. If you use it as a trigger, ensure the `started` action is manually dispatched at the appropriate time.

Install

• npm install typescript-fsa-redux-saga npm
• yarn add typescript-fsa-redux-saga yarn
• pnpm add typescript-fsa-redux-saga pnpm

Imports

• bindAsyncAction
  wrong:

  import bindAsyncAction from 'typescript-fsa-redux-saga';

  correct:

  import { bindAsyncAction } from 'typescript-fsa-redux-saga';

  This is the primary named export for the library's core functionality.
• actionCreatorFactory
  wrong:

  import { actionCreatorFactory } from 'typescript-fsa';

  correct:

  import actionCreatorFactory from 'typescript-fsa';

  Essential for creating async action creators used by `bindAsyncAction`. It is a default export from the `typescript-fsa` library.
• SagaIterator
  wrong:

  import SagaIterator from 'redux-saga';

  correct:

  import { SagaIterator } from 'redux-saga';

  The primary return type for Redux Saga generators, commonly used when defining worker sagas wrapped by `bindAsyncAction`.

Quickstart

Demonstrates how to define an async action using `typescript-fsa` and then wrap a `redux-saga` worker with `bindAsyncAction` to automatically handle `started`, `done`, and `failed` dispatches, illustrating the type-safe flow.

import actionCreatorFactory from 'typescript-fsa';
import { SagaIterator } from 'redux-saga';
import { call } from 'redux-saga/effects';
import { bindAsyncAction } from 'typescript-fsa-redux-saga';

// actions.ts (excerpt)
const actionCreator = actionCreatorFactory('MY_APP');

export const doSomething =
  actionCreator.async<{foo: string},   // parameter type
                      {bar: number}    // result type
                     >('DO_SOMETHING');

// A mock API call function
async function fetchSomething(param: string): Promise<number> {
  console.log(`Simulating API call with: ${param}`);
  return new Promise(resolve => setTimeout(() => resolve(param.length * 10), 500));
}

// The worker saga wrapped by bindAsyncAction
const doSomethingWorker = bindAsyncAction(doSomething)(
  function* (params): SagaIterator<{bar: number}> {
    // `params` type is `{foo: string}`
    console.log(`Worker saga started with params:`, params);
    const result = yield call(fetchSomething, params.foo);
    console.log(`API call returned:`, result);
    return {bar: result};
  },
);

// A root saga that demonstrates calling the async worker
function* myRootSaga(): SagaIterator {
  console.log('Initiating doSomething action...');
  // Calling the worker directly. bindAsyncAction internally dispatches
  // doSomething.started, doSomething.done (or doSomething.failed if an error occurs).
  const result = yield call(doSomethingWorker, {foo: 'example_data'});
  console.log('doSomethingWorker completed with result:', result);

  try {
    console.log('Initiating another doSomething action (simulating potential error path)...');
    yield call(doSomethingWorker, {foo: 'error_case'}); // For demo, assuming this could lead to error
  } catch (e) {
    console.error('Caught an error in saga outside worker:', e); // Errors from worker are re-thrown by bindAsyncAction
  }
}

// To run this in a Redux Saga setup, you would typically pass `myRootSaga` to `sagaMiddleware.run`.
// Example (for conceptual understanding, not directly executable without Redux setup):
// import createSagaMiddleware from 'redux-saga';
// import { createStore, applyMiddleware } from 'redux';
// const sagaMiddleware = createSagaMiddleware();
// const store = createStore(() => ({}), applyMiddleware(sagaMiddleware));
// sagaMiddleware.run(myRootSaga);