Possible to mix up API endpoint matchers and "onQueryStarted" life-cycle logic?

[dggsax]

For this discussion, I'm curious to explore whether the use of RTK-Query endpoint matchers in API slices and the life-cycle manipulation of the onQueryStarted method can be inter-mingled. Right now, I believe the answer to this is no due to cyclic references, but for the sake of discussion, I want to hear what others think about which option is subjectively "better".

The Context

For context, at work I am converting a site to use Redux-Toolkit and RTK-Query from old-school redux and redux-saga. This application depends on the ability to dynamically change the baseUrl utilized for API requests based on user-defined/data-defined inputs to communicate with different "environments" hosting the same API service. I already have a pretty good solution for handling switching the base URL (that I hope to share later this week), but am thinking about how to track which environment was used for mutations. For the sake of my example code, we have an "OnPrem" and a "Cloud" version of the API.

Right now, I'm setting up the API to perform a mutation (PUT) and want to track the environment input for the request as well as the result in a slice I have created to store the result of a mutation.

The Code

Let's say I have an API:

type PerformMutationParams = {
  environmentToUse: "OnPrem" | "Cloud",
  dataToPut: string
}

export const myApi = createApi({
  reducerPath: "api",
  baseQuery: customBaseQuery,
  endpoints: (b) => ({
    performMutation: b.mutation<string, PerformMutationParams>({
      query: (p) => ({
        method: "PUT",
        url: "api/data/upload",
        body: p.dataToPut,
        environment: p.environmentToUse,
      }),
      async onQueryStarted(args, { dispatch }) {
        // When the query starts, I want to tell my slice which environment the mutation was for
        dispatch(setEnvironmentUsed(args.environmentToUse));
      }
    }),
  }),
});

And a slice:

const initialState = {
  environmentUsed: "OnPrem", // other option is "Cloud"
  mutationResponse: undefined
}

const mySlice = createSlice({
  name: "myslice",
  initialState: initialState,
  reducers: {
    setEnvironmentUsed(state, action: PayloadAction<"OnPrem" | "Cloud">) {
      state.environmentUsed = action.payload;
    }
  },
  extraReducers: (builder) => {
    // I want to store the result of the mutation in my store 
    builder.addMatcher(myApi.endpoints.performMutation.matchFulfilled, (state, { payload }) => {
      state.mutationResponse = payload;
    });
  },
});

Example invocation

const [ performMutation ] = usePerformMutation();

performMutation({
  environmentToUse: "Cloud",
  dataToPut: "Hi my name is Gonzo"
});

What I've done here is two things:

1. Whenever the mutation API starts, I define onQueryStarted for performMutation() to have it dispatch the action setEnvironmentUsed as a way of telling my slice, "hey, a mutation request has started for the following environment"
2. Added an endpoint watcher for myApi.endpoints.performMutation.matchFulfilled so that upon fulfillment of the mutation request, I can store the result in my slice for use in other components.

This compiles fine, however as you can imagine when I try to run the site, I get the following runtime error: TypeError: Cannot read properties of undefined (reading 'endpoints') which originates from my builder in extraReducers for mySlice. This makes sense, because (I think) that I've introduced a cyclic reference here by defining an API that depends on an action creator from a slice, and then trying to use an endpoint matcher for that API within that slice. This leads me to the following conclusion: in my case, I can only use one or the other:

1. Use the onQueryStarted method in conjunction with actions that I create to track the initiation, progress, and result/failure of the mutation (e.g. setEnvironmentUsed, mutationSuccess, mutationFailure), OR...
2. I can use the API Endpoint Matchers for the extraReducers in my slice to track "matchPending", "matchSuccess", or "matchFailure" as well as the environment information I'm curious about

The Question

Which is "better"? On the one hand, I can see the argument that by going with the first approach of dispatching actions from onQueryStarted to track the initialization, progress, and result of a mutation request, it makes it easier to understand how the utilization of this particular mutation affects that slice of my state. On the other, by going with the 2nd approach to use just the endpoint matchers, then I set a clear contract for how the results/outcomes of a mutation are affect the rest of my application.

I feel like both options are equally valid, but think my question can be answered based on the philosophies of RTK-Query. What do you think? Is one better than the other? Am I over-thinking? Thanks in advance, and I look forward to learning from this 🙂

[dggsax]

Of course as soon as I post this I realize another (probably easier) way to accomplish what I want to do 😁

extraReducers: (builder) => {
  builder.addMatcher(myApi.endpoints.performMutation.matchFulfilled, (state, { payload, meta }) => {
    // I can use `meta` to access the original args that were provided to the mutation
    state.environmentUsed = meta.arg.originalArgs.environment;
    state.mutationResponse = payload;
  });
},

Still curious to see what others thing regarding the original question, though.

[phryneas]

Personally I'd prefer the api endpoint matchers, since they will take place more early (the lifecycle might be a tick behind due to promises) and you don't dispatch another action, which will at least re-run all of your selectors and maybe even add another render.

[dggsax]

Right, I didn't think about how dispatching actions from onQueryStarted would cause a re-render for each time. I guess then the answer here is to think of utilizing the onQueryStarted for things that affect the life-cycle of the user experience and then to use the api endpoint matchers in a case like mine where I'm just trying to do internal "book-keeping" for my slice of state. That makes a lot of sense, thank you!