@depup/reduxjs__toolkit 2.12.0-depup.28

package/skills/model-redux-state/design-state-ownership/SKILL.md

@@ -0,0 +1,322 @@
+---
+name: model-redux-state/design-state-ownership
+description: >
+  Use this when deciding whether data belongs in Redux, component state, router
+  state, or another external source. Covers state ownership, authority
+  boundaries, slice sizing, and when to move or split data as the app evolves.
+type: core
+library: "@reduxjs/toolkit"
+library_version: "2.11.2"
+sources:
+  - "reduxjs/redux:docs/style-guide/style-guide.md"
+  - "reduxjs/redux:docs/tutorials/essentials/part-2-app-structure.md"
+  - "reduxjs/redux:docs/tutorials/essentials/part-4-using-data.md"
+---
+
+# Design State Ownership
+
+## Setup
+
+```tsx
+import { useState } from 'react'
+import { createSlice } from '@reduxjs/toolkit'
+import { useAppDispatch } from '../../app/hooks'
+
+const postsSlice = createSlice({
+  name: 'posts',
+  initialState: [] as { id: string; title: string; content: string }[],
+  reducers: {
+    postAdded(
+      state,
+      action: { payload: { id: string; title: string; content: string } },
+    ) {
+      state.push(action.payload)
+    },
+  },
+})
+
+const { postAdded } = postsSlice.actions
+
+export function AddPostForm() {
+  const [title, setTitle] = useState('')
+  const [content, setContent] = useState('')
+  const dispatch = useAppDispatch()
+
+  return (
+    <form
+      onSubmit={(event) => {
+        event.preventDefault()
+        dispatch(postAdded({ id: 'p1', title, content }))
+      }}
+    >
+      <input value={title} onChange={(event) => setTitle(event.target.value)} />
+      <textarea
+        value={content}
+        onChange={(event) => setContent(event.target.value)}
+      />
+      <button type="submit">Save</button>
+    </form>
+  )
+}
+```
+
+## Core Patterns
+
+### Keep editable form state local until the user commits it
+
+```tsx
+import { useState } from 'react'
+import { useAppDispatch } from '../../app/hooks'
+import { profileSaved } from './profileSlice'
+
+export function ProfileForm() {
+  const [displayName, setDisplayName] = useState('Lenz')
+  const dispatch = useAppDispatch()
+
+  return (
+    <form
+      onSubmit={(event) => {
+        event.preventDefault()
+        dispatch(profileSaved({ displayName }))
+      }}
+    >
+      <input
+        value={displayName}
+        onChange={(event) => setDisplayName(event.target.value)}
+      />
+      <button type="submit">Save</button>
+    </form>
+  )
+}
+```
+
+Prefer Redux for shared, durable app state, not every keystroke.
+
+### Keep URL state with the router and combine it at the edge
+
+```tsx
+import { createSelector } from '@reduxjs/toolkit'
+import { useSearchParams } from 'react-router-dom'
+import { useAppSelector } from '../../app/hooks'
+
+type RootState = {
+  posts: {
+    items: { id: string; title: string; published: boolean }[]
+  }
+}
+
+const selectPosts = (state: RootState) => state.posts.items
+
+const selectVisiblePosts = createSelector(
+  [selectPosts, (_state: RootState, filter: string) => filter],
+  (posts, filter) =>
+    filter === 'published'
+      ? posts.filter((post) => post.published)
+      : posts,
+)
+
+export function PostsList() {
+  const [searchParams] = useSearchParams()
+  const filter = searchParams.get('filter') ?? 'all'
+  const posts = useAppSelector((state) => selectVisiblePosts(state, filter))
+
+  return <div>{posts.length}</div>
+}
+```
+
+If the router already owns a piece of state, pass it into selectors or combine it in the component instead of syncing it into Redux.
+
+### Re-size slices when access patterns change
+
+```ts
+import { combineReducers, createSlice } from '@reduxjs/toolkit'
+
+const authSlice = createSlice({
+  name: 'auth',
+  initialState: { userId: null as string | null },
+  reducers: {},
+})
+
+const postsSlice = createSlice({
+  name: 'posts',
+  initialState: { items: [] as { id: string; title: string }[] },
+  reducers: {},
+})
+
+export const rootReducer = combineReducers({
+  auth: authSlice.reducer,
+  posts: postsSlice.reducer,
+})
+```
+
+Revisit slice size over time; unrelated data should split apart, and data constantly stitched together in every component may belong closer together.
+
+## Common Mistakes
+
+### MEDIUM Putting form editing state in Redux
+
+Wrong:
+
+```tsx
+import { useAppSelector } from '../../app/hooks'
+
+const selectDraftTitle = (state: { draft: { title: string } }) => state.draft.title
+
+const title = useAppSelector(selectDraftTitle)
+```
+
+Correct:
+
+```tsx
+const [title, setTitle] = useState('')
+
+<input value={title} onChange={(event) => setTitle(event.target.value)} />
+```
+
+Per-keystroke dispatching adds global complexity for data that usually lives in one component tree.
+
+Source: reduxjs/redux:docs/style-guide/style-guide.md
+
+### HIGH Synchronizing router or URL state into Redux
+
+Wrong:
+
+```tsx
+import { useEffect } from 'react'
+import { useSearchParams } from 'react-router-dom'
+import { useAppDispatch } from '../../app/hooks'
+
+function PostsPage() {
+  const [searchParams] = useSearchParams()
+  const dispatch = useAppDispatch()
+
+useEffect(() => {
+  dispatch(filterChanged(searchParams.get('filter') ?? 'all'))
+}, [dispatch, searchParams])
+
+  return null
+}
+```
+
+Correct:
+
+```tsx
+const filter = searchParams.get('filter') ?? 'all'
+const posts = useAppSelector((state) => selectVisiblePosts(state, filter))
+```
+
+URL state already has an authoritative owner; duplicating it into Redux creates two sources of truth.
+
+Source: maintainer interview
+
+### HIGH Naming state after components
+
+Wrong:
+
+```ts
+import { combineReducers } from '@reduxjs/toolkit'
+
+const loginReducer = (state = { open: false }) => state
+const postsReducer = (state = [] as { id: string; title: string }[]) => state
+
+const rootReducer = combineReducers({
+  loginScreen: loginReducer,
+  postsList: postsReducer,
+})
+```
+
+Correct:
+
+```ts
+import { combineReducers } from '@reduxjs/toolkit'
+
+const authReducer = (state = { userId: null as string | null }) => state
+const postsReducer = (state = [] as { id: string; title: string }[]) => state
+
+const rootReducer = combineReducers({
+  auth: authReducer,
+  posts: postsReducer,
+})
+```
+
+Store keys should describe data or domain concepts, not the current component tree.
+
+Source: reduxjs/redux:docs/style-guide/style-guide.md
+
+### MEDIUM Letting slice boundaries fossilize
+
+Wrong:
+
+```ts
+import { createSlice } from '@reduxjs/toolkit'
+
+type Post = { id: string; title: string }
+type AppNotification = { id: string; message: string }
+
+const appSlice = createSlice({
+  name: 'app',
+  initialState: {
+    auth: { userId: null as string | null },
+    posts: [] as Post[],
+    notifications: [] as AppNotification[],
+  },
+  reducers: {},
+})
+```
+
+Correct:
+
+```ts
+import { createSlice } from '@reduxjs/toolkit'
+
+type Post = { id: string; title: string }
+
+const authSlice = createSlice({
+  name: 'auth',
+  initialState: { userId: null as string | null },
+  reducers: {},
+})
+
+const postsSlice = createSlice({
+  name: 'posts',
+  initialState: [] as Post[],
+  reducers: {},
+})
+```
+
+When unrelated data is welded together, every change point gets noisier; split or merge slices as actual access patterns demand.
+
+Source: maintainer interview
+
+### HIGH Blindly spreading payloads into state
+
+Wrong:
+
+```ts
+const state = { id: '1', name: 'Lenz' }
+const action = { payload: { id: '2', name: 'Mark', ignored: true } }
+
+userLoggedIn(state, action) {
+  return { ...state, ...action.payload }
+}
+```
+
+Correct:
+
+```ts
+const state = { id: '1', name: 'Lenz' }
+const action = { payload: { id: '2', name: 'Mark', ignored: true } }
+
+userLoggedIn(state, action) {
+  state.id = action.payload.id
+  state.name = action.payload.name
+}
+```
+
+Reducers should own the slice shape instead of treating payloads as trusted state patches.
+
+Source: reduxjs/redux:docs/style-guide/style-guide.md
+
+## References
+
+- [State ownership heuristics](references/state-ownership.md)

package/skills/model-redux-state/design-state-ownership/references/state-ownership.md

@@ -0,0 +1,28 @@
+# State Ownership Heuristics
+
+## Choose the owner, then the tool
+
+| Kind of state | Default owner | Typical tool |
+| --- | --- | --- |
+| Editable form fields | Component | `useState` |
+| Shared mutable app data | Redux | Slice state |
+| Server cache | RTK Query | `createApi` |
+| URL, pathname, search params | Router | Router APIs plus selector inputs |
+| Browser-only authority like `localStorage` | External source | Read at boundaries, then dispatch events |
+
+## Good reasons to move data into Redux
+
+- Multiple distant parts of the UI need the same mutable data.
+- You need time-travel debugging or a stable action history.
+- The reducer should own transitions because they mix old store state with new inputs.
+
+## Reasons to keep data out of Redux
+
+- Another system already owns it, such as the router.
+- It only matters during editing inside one component tree.
+- It is server cache and RTK Query fits the use case better.
+
+## Re-evaluate slice size
+
+- If data is constantly stitched together outside reducers, it may belong closer together.
+- If unrelated updates keep touching the same slice, split the slice by domain ownership.

package/skills/orchestrate-side-effects/handle-side-effects/SKILL.md

@@ -0,0 +1,271 @@
+---
+name: orchestrate-side-effects/handle-side-effects
+description: >
+  Use this when choosing between RTK Query, createAsyncThunk, handwritten
+  thunks, and createListenerMiddleware. Covers imperative versus reactive
+  workflows, listener middleware setup, and keeping side effects out of
+  reducers and UI components.
+type: core
+library: "@reduxjs/toolkit"
+library_version: "2.11.2"
+requires:
+  - build-modern-redux-apps/redux-dataflow
+sources:
+  - "reduxjs/redux-toolkit:docs/api/createAsyncThunk.mdx"
+  - "reduxjs/redux-toolkit:docs/api/createListenerMiddleware.mdx"
+  - "reduxjs/redux:docs/style-guide/style-guide.md"
+  - "reduxjs/redux:docs/tutorials/essentials/part-5-async-logic.md"
+---
+
+# Handle Side Effects
+
+## Setup
+
+```ts
+import {
+  configureStore,
+  createListenerMiddleware,
+  createSlice,
+} from '@reduxjs/toolkit'
+
+const docsSlice = createSlice({
+  name: 'docs',
+  initialState: { status: 'idle' as 'idle' | 'saved' },
+  reducers: {
+    saveStarted(state) {
+      state.status = 'idle'
+    },
+    saveFinished(state) {
+      state.status = 'saved'
+    },
+  },
+})
+
+const listenerMiddleware = createListenerMiddleware()
+
+export const store = configureStore({
+  reducer: {
+    docs: docsSlice.reducer,
+  },
+  middleware: (getDefaultMiddleware) =>
+    getDefaultMiddleware().prepend(listenerMiddleware.middleware),
+})
+
+export type RootState = ReturnType<typeof store.getState>
+export type AppDispatch = typeof store.dispatch
+
+export const startAppListening =
+  listenerMiddleware.startListening.withTypes<RootState, AppDispatch>()
+```
+
+## Core Patterns
+
+### Use RTK Query for server cache by default
+
+```ts
+import { createApi, fetchBaseQuery } from '@reduxjs/toolkit/query/react'
+
+type Post = { id: string; title: string }
+
+export const api = createApi({
+  reducerPath: 'api',
+  baseQuery: fetchBaseQuery({ baseUrl: '/api' }),
+  tagTypes: ['Post'],
+  endpoints: (build) => ({
+    getPosts: build.query<Post[], void>({
+      query: () => 'posts',
+      providesTags: ['Post'],
+    }),
+  }),
+})
+```
+
+If the problem is server data that should be cached and re-used, start with RTK Query instead of a thunk.
+
+### Use `createAsyncThunk` for imperative workflows
+
+```ts
+import { createAsyncThunk, createSlice } from '@reduxjs/toolkit'
+
+type Draft = { title: string }
+
+export const draftSaved = createAsyncThunk(
+  'drafts/save',
+  async (draft: Draft) => {
+    const response = await fetch('/api/drafts', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(draft),
+    })
+
+    return (await response.json()) as { id: string; title: string }
+  },
+)
+
+const draftsSlice = createSlice({
+  name: 'drafts',
+  initialState: { status: 'idle' as 'idle' | 'pending' | 'failed' },
+  reducers: {},
+  extraReducers: (builder) => {
+    builder
+      .addCase(draftSaved.pending, (state) => {
+        state.status = 'pending'
+      })
+      .addCase(draftSaved.fulfilled, (state) => {
+        state.status = 'idle'
+      })
+      .addCase(draftSaved.rejected, (state) => {
+        state.status = 'failed'
+      })
+  },
+})
+```
+
+Use a thunk when you need one imperative async workflow with `dispatch` and `getState`.
+
+### Use listener middleware for reactive workflows
+
+```ts
+import { createListenerMiddleware, createSlice } from '@reduxjs/toolkit'
+
+const docsSlice = createSlice({
+  name: 'docs',
+  initialState: { status: 'idle' as 'idle' | 'saved' },
+  reducers: {
+    saveFinished(state) {
+      state.status = 'saved'
+    },
+  },
+})
+
+const notificationsSlice = createSlice({
+  name: 'notifications',
+  initialState: [] as string[],
+  reducers: {
+    notificationQueued(state, action: { payload: string }) {
+      state.push(action.payload)
+    },
+  },
+})
+
+const listenerMiddleware = createListenerMiddleware()
+
+listenerMiddleware.startListening({
+  actionCreator: docsSlice.actions.saveFinished,
+  effect: async (_action, listenerApi) => {
+    listenerApi.dispatch(
+      notificationsSlice.actions.notificationQueued('Document saved'),
+    )
+  },
+})
+```
+
+Listeners fit workflows that react to future actions or state changes over time instead of driving one imperative request from a single callsite.
+
+## Common Mistakes
+
+### CRITICAL Running side effects inside reducers
+
+Wrong:
+
+```ts
+const todosSlice = createSlice({
+  name: 'todos',
+  initialState: [] as { id: string }[],
+  reducers: {
+    todoSaved(state, action: { payload: { id: string } }) {
+      fetch('/api/todos', { method: 'POST' })
+      state.push(action.payload)
+    },
+  },
+})
+```
+
+Correct:
+
+```ts
+import { createAsyncThunk } from '@reduxjs/toolkit'
+
+const todoSaved = createAsyncThunk('todos/save', async (todo: { id: string }) => {
+  await fetch('/api/todos', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(todo),
+  })
+  return todo
+})
+```
+
+Reducers must stay pure even when Immer is available.
+
+Source: reduxjs/redux:docs/style-guide/style-guide.md
+
+### HIGH Using thunks to watch future state changes
+
+Wrong:
+
+```ts
+export const waitForSave = () => async (
+  _dispatch: unknown,
+  getState: () => { docs: { status: string } },
+) => {
+  while (getState().docs.status !== 'saved') {
+    await new Promise((resolve) => setTimeout(resolve, 100))
+  }
+}
+```
+
+Correct:
+
+```ts
+startAppListening({
+  predicate: (_action, currentState) => currentState.docs.status === 'saved',
+  effect: async () => {
+    console.log('Document saved')
+  },
+})
+```
+
+Polling inside thunks fights the architecture; listener middleware is the reactive tool.
+
+Source: reduxjs/redux-toolkit:docs/api/createListenerMiddleware.mdx
+
+### HIGH Appending listener middleware after the default checks
+
+Wrong:
+
+```ts
+import { configureStore, createListenerMiddleware } from '@reduxjs/toolkit'
+
+const reducer = (state = { ready: true }) => state
+const listenerMiddleware = createListenerMiddleware()
+
+const store = configureStore({
+  reducer,
+  middleware: (getDefaultMiddleware) =>
+    getDefaultMiddleware().concat(listenerMiddleware.middleware),
+})
+```
+
+Correct:
+
+```ts
+import { configureStore, createListenerMiddleware } from '@reduxjs/toolkit'
+
+const reducer = (state = { ready: true }) => state
+const listenerMiddleware = createListenerMiddleware()
+
+const store = configureStore({
+  reducer,
+  middleware: (getDefaultMiddleware) =>
+    getDefaultMiddleware().prepend(listenerMiddleware.middleware),
+})
+```
+
+Listener add and remove actions may carry functions, so the listener middleware needs to run before serializability checks.
+
+Source: reduxjs/redux-toolkit:docs/api/createListenerMiddleware.mdx
+
+## References
+
+- [Listener helpers and decision heuristics](references/listener-workflows.md)

package/skills/orchestrate-side-effects/handle-side-effects/references/listener-workflows.md

@@ -0,0 +1,34 @@
+# Listener Workflows
+
+## Decision table
+
+| Need | Reach for |
+| --- | --- |
+| Cached server data | RTK Query |
+| One imperative async workflow with `dispatch` / `getState` | `createAsyncThunk` or a thunk |
+| React to later actions or state transitions | `createListenerMiddleware` |
+
+A good app often mixes imperative and reactive workflows. The split is by job, not by ideology.
+
+## Useful listener helpers
+
+- `predicate`: react to any action when a state condition becomes true
+- `condition`: wait until a condition becomes true before continuing
+- `take`: wait for the next matching action
+- `cancelActiveListeners`: cancel older instances of the same workflow
+- `fork`: start a child task
+
+## Example: cancel stale work
+
+```ts
+startAppListening({
+  actionCreator: searchRequested,
+  effect: async (action, listenerApi) => {
+    listenerApi.cancelActiveListeners()
+    await listenerApi.delay(250)
+    listenerApi.dispatch(searchStarted(action.payload))
+  },
+})
+```
+
+This is the kind of long-lived reactive behavior that does not fit a thunk well.

package/src/actionCreatorInvariantMiddleware.ts

@@ -0,0 +1,34 @@
+import type { Middleware } from 'redux'
+import { isActionCreator as isRTKAction } from './createAction'
+
+export interface ActionCreatorInvariantMiddlewareOptions {
+  /**
+   * The function to identify whether a value is an action creator.
+   * The default checks for a function with a static type property and match method.
+   */
+  isActionCreator?: (action: unknown) => action is Function & { type?: unknown }
+}
+
+export function getMessage(type?: unknown) {
+  const splitType = type ? `${type}`.split('/') : []
+  const actionName = splitType[splitType.length - 1] || 'actionCreator'
+  return `Detected an action creator with type "${
+    type || 'unknown'
+  }" being dispatched.
+Make sure you're calling the action creator before dispatching, i.e. \`dispatch(${actionName}())\` instead of \`dispatch(${actionName})\`. This is necessary even if the action has no payload.`
+}
+
+export function createActionCreatorInvariantMiddleware(
+  options: ActionCreatorInvariantMiddlewareOptions = {},
+): Middleware {
+  if (process.env.NODE_ENV === 'production') {
+    return () => (next) => (action) => next(action)
+  }
+  const { isActionCreator = isRTKAction } = options
+  return () => (next) => (action) => {
+    if (isActionCreator(action)) {
+      console.warn(getMessage(action.type))
+    }
+    return next(action)
+  }
+}