saga-toolkit 2.1.1 → 2.2.1

package/README.md

@@ -1,135 +1,149 @@
 # Saga Toolkit
 
-An extension for [redux-toolkit][redux-toolkit] that allows sagas to resolve async thunk actions. 🌝
+**Seamlessly integrate Redux Toolkit with Redux Saga.**
 
-## install
+`saga-toolkit` acts as a bridge between Redux Toolkit's `createAsyncThunk` and Redux Saga. It allows you to dispatch actions that trigger Sagas, while retaining the ability to `await` the result (promise) directly in your components or thunks.
 
-`npm i saga-toolkit`
+If you love the "fire-and-forget" nature of Sagas for complex flows but miss the convenience of `await dispatch(action)` for simple request/response patterns (like form submissions), this library is for you.
 
-## example - takeEveryAsync
+## Features
 
-With `takeEveryAsync` each saga action dispatched runs their saga.
+- 🤝 **Bridge Pattern**: Connects `createAsyncThunk` (RTK) with `takeEvery` / `takeLatest` (Saga).
+- 🔄 **Promise Support**: `await` your Saga actions in React components.
+- ⚡ **Reduce Boilerplate**: Easily handle loading/success/error states in slices using standard RTK patterns.
+- 🛑 **Cancellation**: Propagates cancellation from the promise to the Saga.
 
-`slice.js`
-```js
+## Installation
+
+```bash
+npm install saga-toolkit
+# or
+yarn add saga-toolkit
+```
+
+*Peer Dependencies: `@reduxjs/toolkit`, `redux-saga`*
+
+## Usage Guide
+
+### 1. Create a "Saga Action"
+
+Instead of `createAsyncThunk` or standard standard action creators, use `createSagaAction`. This creates a thunk that returns a promise which your Saga will resolve or reject.
+
+```javascript
+/* slice.js */
 import { createSlice } from '@reduxjs/toolkit'
-import { createSagaAction  } from 'saga-toolkit'
+import { createSagaAction } from 'saga-toolkit'
+
+const name = 'users'
 
-const name = 'example'
+// Define the action
+export const fetchUser = createSagaAction(`${name}/fetchUser`)
 
 const initialState = {
-  started: false,
-  result: null,
+  data: null,
   loading: false,
   error: null,
 }
 
-export const appStart = createSagaAction(`${name}/appStart`)
-export const fetchThings = createSagaAction(`${name}/fetchThings`)
-
 const slice = createSlice({
   name,
   initialState,
-  extraReducers: {
-    [fetchThings.pending]: state => ({
-      ...state,
-      loading: true,
-    }),
-    [fetchThings.fulfilled]: (state, { payload }) => ({
-      ...state,
-      result: payload,
-      loading: false,
-    }),
-    [fetchThings.rejected]: (state, { error }) => ({
-      ...state,
-      error,
-      loading: false,
-    }),
-    [appStart.fulfilled]: state => {
-      state.started = true // immer allows this
-      return state
-    },
+  extraReducers: (builder) => {
+    builder
+      .addCase(fetchUser.pending, (state) => {
+        state.loading = true
+        state.error = null
+      })
+      .addCase(fetchUser.fulfilled, (state, { payload }) => {
+        state.loading = false
+        state.data = payload
+      })
+      .addCase(fetchUser.rejected, (state, { error }) => {
+        state.loading = false
+        state.error = error
+      })
   },
 })
 
 export default slice.reducer
 ```
 
-`sagas.js`
-```js
-import { put, call } from 'redux-saga/effects'
-import { takeEveryAsync, putAsync } from 'saga-toolkit'
-import API from 'hyper-super-api'
-import * as actions from './slice'
-
-function* appStart() {
-  const promise = yield put(fetchThings({ someArg: 'example' }))
-  try {
-    const fetchThingsActionFulfulled = yield promise // optionally we can wait for an action to finish and get its result
-  } catch(error) {
-    // we can handle error to avoid appStart to get rejected if we want
-  }
-  return result
-}
+### 2. Connect to a Saga
 
-// or using putAsync
-function* appStart() {
-  try {
-    const payload = yield putAsync(fetchThings({ someArg: 'example' }))
-  } catch(error) {
-    // handle uncatched error from saga
-  }
-  return result
-}
+Use `takeEveryAsync` (or `takeLatestAsync`, etc.) to listen for the action. The return value of your saga becomes the `fulfilled` payload. Throwing an error becomes the `rejected` payload.
+
+```javascript
+/* sagas.js */
+import { call } from 'redux-saga/effects'
+import { takeEveryAsync } from 'saga-toolkit'
+import { fetchUser } from './slice'
+import API from './api'
 
-function* fetchThings({ meta }) {
-  const { someArg } = meta
-  const result = yield call(() => API.get('/things', { body: someArg }))
-  return result
+function* fetchUserSaga({ meta }) {
+  // meta.arg contains the argument passed to the dispatch
+  const userId = meta.arg
+  
+  // The return value here resolves the promise!
+  const user = yield call(API.getUser, userId)
+  return user 
 }
 
-export default [
-  takeEveryAsync(actions.appStart.type, appStart),
-  takeEveryAsync(actions.fetchThings.type, fetchThings),
-]
+export default function* rootSaga() {
+  yield takeEveryAsync(fetchUser.type, fetchUserSaga)
+}
 ```
 
-`SomeComponent.js`
-```js
-// import things
+### 3. Dispatch and Await in Component
+
+Now you can treat the Saga logic as if it were a simple async function.
 
-const SomeComponent() {
+```javascript
+/* UserComponent.jsx */
+import { useDispatch } from 'react-redux'
+import { useEffect } from 'react'
+import { fetchUser } from './slice'
+
+const UserComponent = ({ id }) => {
   const dispatch = useDispatch()
 
-  useEffect(() => {
-    const promise = dispatch(appStart()) // dispatch action from component
-    promise.then(...).catch(...) // optionally do something with promise
-  }, [])
+  const handleFetch = async () => {
+    try {
+      // This waits for the Saga to finish!
+      const user = await dispatch(fetchUser(id)).unwrap() 
+      console.log('Got user:', user)
+    } catch (error) {
+      console.error('Failed to fetch:', error)
+    }
+  }
 
-  return (
-    ...
-  )
+  return <button onClick={handleFetch}>Load User</button>
 }
 ```
 
-## example2 - takeLatestAsync
+## API Reference
 
-With `takeLatestAsync` the latter saga cancels the previous one in case that has not finished running. Action will be rejected with error message 'Saga cancelled'.
+### `createSagaAction(typePrefix)`
+Creates a Redux Toolkit Async Thunk that is specially designed to work with the effects below.
+- **Returns**: An enhanced thunk action creator.
 
-```js
-export default [
-  takeLatestAsync(actions.fetchThings.type, fetchThings),
-]
-```
+### `takeEveryAsync(pattern, saga, ...args)`
+Spawns a `saga` on each action dispatched to the Store that matches `pattern`.
+- Automatically resolves the promise associated with the action when the saga returns.
+- Automatically rejects the promise if the saga errors.
 
-## example3 - takeAggregateAsync
+### `takeLatestAsync(pattern, saga, ...args)`
+Same as `takeEveryAsync`, but cancels any previous running task if a new matching action is dispatched.
+- **Note**: Cancelled tasks will reject the promise with an "Aborted" error (or similar).
 
-With `takeAggregateAsync` the underlying promise that is created by the first action dispatch will be used and shared accross all subsequent actions. Each subsequent action will be resolved / rejected with the result of the first action. In other words, one single saga runs at a time that is passed to this effect.
+### `takeAggregateAsync(pattern, saga, ...args)`
+Wait for the saga to finish for the first action. If subsequent actions with the same pattern are dispatched *while only one is running*, they will all share the **same promise result** as the first one.
+- Useful for de-duplicating identical requests (e.g., multiple components requesting "load config" simultaneously).
 
-```js
-export default [
-  takeAggregateAsync(actions.fetchThings.type, fetchThings),
-]
-```
+### `putAsync(action)`
+Dispatches an action to the store and waits for the result.
+- Useful when you want to call another saga-action from within a saga and wait for it (composition).
+- **Example**: `const result = yield putAsync(otherAction())`
+
+## License
 
-[redux-toolkit]: https://redux-toolkit.js.org/ "redux-toolkit"
+ISC

package/coverage/base.css

@@ -0,0 +1,224 @@
+body, html {
+  margin:0; padding: 0;
+  height: 100%;
+}
+body {
+    font-family: Helvetica Neue, Helvetica, Arial;
+    font-size: 14px;
+    color:#333;
+}
+.small { font-size: 12px; }
+*, *:after, *:before {
+  -webkit-box-sizing:border-box;
+     -moz-box-sizing:border-box;
+          box-sizing:border-box;
+  }
+h1 { font-size: 20px; margin: 0;}
+h2 { font-size: 14px; }
+pre {
+    font: 12px/1.4 Consolas, "Liberation Mono", Menlo, Courier, monospace;
+    margin: 0;
+    padding: 0;
+    -moz-tab-size: 2;
+    -o-tab-size:  2;
+    tab-size: 2;
+}
+a { color:#0074D9; text-decoration:none; }
+a:hover { text-decoration:underline; }
+.strong { font-weight: bold; }
+.space-top1 { padding: 10px 0 0 0; }
+.pad2y { padding: 20px 0; }
+.pad1y { padding: 10px 0; }
+.pad2x { padding: 0 20px; }
+.pad2 { padding: 20px; }
+.pad1 { padding: 10px; }
+.space-left2 { padding-left:55px; }
+.space-right2 { padding-right:20px; }
+.center { text-align:center; }
+.clearfix { display:block; }
+.clearfix:after {
+  content:'';
+  display:block;
+  height:0;
+  clear:both;
+  visibility:hidden;
+  }
+.fl { float: left; }
+@media only screen and (max-width:640px) {
+  .col3 { width:100%; max-width:100%; }
+  .hide-mobile { display:none!important; }
+}
+
+.quiet {
+  color: #7f7f7f;
+  color: rgba(0,0,0,0.5);
+}
+.quiet a { opacity: 0.7; }
+
+.fraction {
+  font-family: Consolas, 'Liberation Mono', Menlo, Courier, monospace;
+  font-size: 10px;
+  color: #555;
+  background: #E8E8E8;
+  padding: 4px 5px;
+  border-radius: 3px;
+  vertical-align: middle;
+}
+
+div.path a:link, div.path a:visited { color: #333; }
+table.coverage {
+  border-collapse: collapse;
+  margin: 10px 0 0 0;
+  padding: 0;
+}
+
+table.coverage td {
+  margin: 0;
+  padding: 0;
+  vertical-align: top;
+}
+table.coverage td.line-count {
+    text-align: right;
+    padding: 0 5px 0 20px;
+}
+table.coverage td.line-coverage {
+    text-align: right;
+    padding-right: 10px;
+    min-width:20px;
+}
+
+table.coverage td span.cline-any {
+    display: inline-block;
+    padding: 0 5px;
+    width: 100%;
+}
+.missing-if-branch {
+    display: inline-block;
+    margin-right: 5px;
+    border-radius: 3px;
+    position: relative;
+    padding: 0 4px;
+    background: #333;
+    color: yellow;
+}
+
+.skip-if-branch {
+    display: none;
+    margin-right: 10px;
+    position: relative;
+    padding: 0 4px;
+    background: #ccc;
+    color: white;
+}
+.missing-if-branch .typ, .skip-if-branch .typ {
+    color: inherit !important;
+}
+.coverage-summary {
+  border-collapse: collapse;
+  width: 100%;
+}
+.coverage-summary tr { border-bottom: 1px solid #bbb; }
+.keyline-all { border: 1px solid #ddd; }
+.coverage-summary td, .coverage-summary th { padding: 10px; }
+.coverage-summary tbody { border: 1px solid #bbb; }
+.coverage-summary td { border-right: 1px solid #bbb; }
+.coverage-summary td:last-child { border-right: none; }
+.coverage-summary th {
+  text-align: left;
+  font-weight: normal;
+  white-space: nowrap;
+}
+.coverage-summary th.file { border-right: none !important; }
+.coverage-summary th.pct { }
+.coverage-summary th.pic,
+.coverage-summary th.abs,
+.coverage-summary td.pct,
+.coverage-summary td.abs { text-align: right; }
+.coverage-summary td.file { white-space: nowrap;  }
+.coverage-summary td.pic { min-width: 120px !important;  }
+.coverage-summary tfoot td { }
+
+.coverage-summary .sorter {
+    height: 10px;
+    width: 7px;
+    display: inline-block;
+    margin-left: 0.5em;
+    background: url(sort-arrow-sprite.png) no-repeat scroll 0 0 transparent;
+}
+.coverage-summary .sorted .sorter {
+    background-position: 0 -20px;
+}
+.coverage-summary .sorted-desc .sorter {
+    background-position: 0 -10px;
+}
+.status-line {  height: 10px; }
+/* yellow */
+.cbranch-no { background: yellow !important; color: #111; }
+/* dark red */
+.red.solid, .status-line.low, .low .cover-fill { background:#C21F39 }
+.low .chart { border:1px solid #C21F39 }
+.highlighted,
+.highlighted .cstat-no, .highlighted .fstat-no, .highlighted .cbranch-no{
+  background: #C21F39 !important;
+}
+/* medium red */
+.cstat-no, .fstat-no, .cbranch-no, .cbranch-no { background:#F6C6CE }
+/* light red */
+.low, .cline-no { background:#FCE1E5 }
+/* light green */
+.high, .cline-yes { background:rgb(230,245,208) }
+/* medium green */
+.cstat-yes { background:rgb(161,215,106) }
+/* dark green */
+.status-line.high, .high .cover-fill { background:rgb(77,146,33) }
+.high .chart { border:1px solid rgb(77,146,33) }
+/* dark yellow (gold) */
+.status-line.medium, .medium .cover-fill { background: #f9cd0b; }
+.medium .chart { border:1px solid #f9cd0b; }
+/* light yellow */
+.medium { background: #fff4c2; }
+
+.cstat-skip { background: #ddd; color: #111; }
+.fstat-skip { background: #ddd; color: #111 !important; }
+.cbranch-skip { background: #ddd !important; color: #111; }
+
+span.cline-neutral { background: #eaeaea; }
+
+.coverage-summary td.empty {
+    opacity: .5;
+    padding-top: 4px;
+    padding-bottom: 4px;
+    line-height: 1;
+    color: #888;
+}
+
+.cover-fill, .cover-empty {
+  display:inline-block;
+  height: 12px;
+}
+.chart {
+  line-height: 0;
+}
+.cover-empty {
+    background: white;
+}
+.cover-full {
+    border-right: none !important;
+}
+pre.prettyprint {
+    border: none !important;
+    padding: 0 !important;
+    margin: 0 !important;
+}
+.com { color: #999 !important; }
+.ignore-none { color: #999; font-weight: normal; }
+
+.wrapper {
+  min-height: 100%;
+  height: auto !important;
+  height: 100%;
+  margin: 0 auto -48px;
+}
+.footer, .push {
+  height: 48px;
+}

package/coverage/block-navigation.js

@@ -0,0 +1,87 @@
+/* eslint-disable */
+var jumpToCode = (function init() {
+    // Classes of code we would like to highlight in the file view
+    var missingCoverageClasses = ['.cbranch-no', '.cstat-no', '.fstat-no'];
+
+    // Elements to highlight in the file listing view
+    var fileListingElements = ['td.pct.low'];
+
+    // We don't want to select elements that are direct descendants of another match
+    var notSelector = ':not(' + missingCoverageClasses.join('):not(') + ') > '; // becomes `:not(a):not(b) > `
+
+    // Selector that finds elements on the page to which we can jump
+    var selector =
+        fileListingElements.join(', ') +
+        ', ' +
+        notSelector +
+        missingCoverageClasses.join(', ' + notSelector); // becomes `:not(a):not(b) > a, :not(a):not(b) > b`
+
+    // The NodeList of matching elements
+    var missingCoverageElements = document.querySelectorAll(selector);
+
+    var currentIndex;
+
+    function toggleClass(index) {
+        missingCoverageElements
+            .item(currentIndex)
+            .classList.remove('highlighted');
+        missingCoverageElements.item(index).classList.add('highlighted');
+    }
+
+    function makeCurrent(index) {
+        toggleClass(index);
+        currentIndex = index;
+        missingCoverageElements.item(index).scrollIntoView({
+            behavior: 'smooth',
+            block: 'center',
+            inline: 'center'
+        });
+    }
+
+    function goToPrevious() {
+        var nextIndex = 0;
+        if (typeof currentIndex !== 'number' || currentIndex === 0) {
+            nextIndex = missingCoverageElements.length - 1;
+        } else if (missingCoverageElements.length > 1) {
+            nextIndex = currentIndex - 1;
+        }
+
+        makeCurrent(nextIndex);
+    }
+
+    function goToNext() {
+        var nextIndex = 0;
+
+        if (
+            typeof currentIndex === 'number' &&
+            currentIndex < missingCoverageElements.length - 1
+        ) {
+            nextIndex = currentIndex + 1;
+        }
+
+        makeCurrent(nextIndex);
+    }
+
+    return function jump(event) {
+        if (
+            document.getElementById('fileSearch') === document.activeElement &&
+            document.activeElement != null
+        ) {
+            // if we're currently focused on the search input, we don't want to navigate
+            return;
+        }
+
+        switch (event.which) {
+            case 78: // n
+            case 74: // j
+                goToNext();
+                break;
+            case 66: // b
+            case 75: // k
+            case 80: // p
+                goToPrevious();
+                break;
+        }
+    };
+})();
+window.addEventListener('keydown', jumpToCode);