[Feature] CRUD API Wrapper Implementation

[eslachance]

I've been working on a fresh new project and this gave me the benefit of being able to not only use redux-toolkit, but also the freedom to write a "builder" for our multiple CRUD endpoints.

After speaking with @markerikson , it became clear this might be something that's useful to a growing number of people. The basics of this is that the API endpoints we have are all similar in structure, and since CRUD operations usually have the same shape, I quickly ended up with a lot of duplicated code for each endpoint, where the only difference was the endpoint name.

So I made a function that creates all of the thunks using createAsyncThunk and the customReducer entries to make them work. This is then returned and used in configureStore or in the various components that require the data.

It's a little verbose as one might expect, but it works:

import { createSlice, createAsyncThunk } from '@reduxjs/toolkit';

export default ({
    baseUrl,
    name,
}) => {
    const fetchById = createAsyncThunk(
        `${name}/fetchByIdStatus`,
        id => fetch(`${baseUrl}/${id}`).then(r => r.json()),
    );

    const fetchAll = createAsyncThunk(
        `${name}/fetchAllStatus`,
        () =>  fetch(`${baseUrl}/`).then(r => r.json()),
    );

    const updateById = createAsyncThunk(
        `${name}/updateByIdStatus`,
        async ({id, data}) => {
            await fetch(`${baseUrl}/${id}`, {
                method: "UPDATE",
                headers: {
                    'Content-Type': 'application/json',
                },
                body: JSON.stringify(data),
            }).then(r => r.json());
            return data;
        },
    );

    const deleteById = createAsyncThunk(
        `${name}/deleteByIdStatus`,
        id =>  fetch(`${baseUrl}/${id}`, {
            method: 'DELETE',
        }).then(r => r.json()).then(() => id),
    );

    const createNew = createAsyncThunk(
        `${name}/createNewStatus`,
        data => fetch(`${baseUrl}`, {
            method: 'PUT',
            headers: {
                'Content-Type': 'application/json',
            },
            body: JSON.stringify(data),
        }),
    );

    const slice = createSlice({
        name,
        initialState: { entities: {}, loading: 'idle'},
        reducers: {},
        extraReducers: {
            [fetchById.fulfilled]: (state, action) => {
                state.entities[action.payload.id] = action.payload;
            },
            [fetchById.rejected]: (state, action) => {
                state.entities[action.payload.id] = action.payload;
            },
            [updateById.fulfilled]: (state, action) => {
                state.entities[action.payload.id] = action.payload;
            },
            [deleteById.fulfilled]: (state, action) => {
                delete state.entities[action.payload.id];
                return state;
            },
            [createNew.fulfilled]: (state, action) => {
                state.entities[action.payload.id] = action.payload;
            },
            [fetchAll.fulfilled]: (state, action) => {
                state.entities = {
                    ...state.entities,
                    ...action.payload,
                };
            },
        },
    });

    return {
        reducer: slice.reducer,
        fetchById,
        fetchAll,
        updateById,
        deleteById,
        createNew,
    };
};

This is called simply by providing the baseUrl and the name (in our case the could be different so that's why we had to split those 2 arguments):

export const cascades = builder({
    baseUrl: `${baseUrl}/cascade-blocks`,
    name: 'cascades',
});

export const groups = builder({
    baseUrl: `${baseUrl}/groups`,
    name: 'groups',
});

And then I imported those into our configureStore, combining them as a root reducer:

import { cascades, groups } from './slices';
const rootReducer = combineReducers( {
  cascades: cascades.reducer,
  groups: groups.reducer,
} );

export default store = configureStore({ reducer: rootReducer });

The only thing missing from the above is my next step, which is to provide some selector functions that can getById, getAll, getIDs, and other useful related things.

After adding the selectors I'll consider this to be a fairly self-contained, re-usable module that I'm sure we'll start using internally. Hopefully, it can be of service for Redux-Toolkit also!

[dalechyn]

Hey!

That definitely looks cool and useful, but what if a developer wants to have other routes URL or he handles them differently?
I think that having routes property would make your idea richer, so it's like:

type CRUDReducerBuilderProps = {
  baseUrl: string
  name: string,
  routes?: {
    fetchById?: string
    fetchAll?: string
    // and so on
  }

And then fetch those routes if they are given.

Although I think CRUD operations may be very different, as you can talk not via HTTP but via other protocols (i.e. Redis), so maybe people won't use it and it wouldn't worth package space.

[markerikson]

Yep, thanks for filing this issue and putting that example together. This is a topic that's been on my mind for a while, and is an obvious next step after releasing createAsyncThunk and createEntityAdapter individually.

First, a couple suggestions on the code.

The reducers, as currently written, can all be replaced by use of createEntityAdapter. The example can be simplified down to:

const adapter = createEntityAdapter();

const slice = createSlice({
  name,
  initialState: adapter.getInitialState(),
  reducers: {},
  extraReducers: {
    [fetchById.fulfilled]: adapter.upsertOne,
    [fetchById.rejected]: adapter.upsertOne,
    [updateById.fulfilled]: adapter.upsertOne,
    [deleteById.fulfilled]: adapter.removeOne,
    [createNew.fulfilled]: adapter.upsertOne,
    [fetchAll.fulfilled]: adapter.upsertMany
  }
})

That said, I'm actually confused a bit as to why you're inserting an item for the fetchById.rejected case. Typo, or intentional?

Moving on and addressing the concept in general:

The biggest complications for a generic fetching + loading API like this come from the numerous various in how things could get fetched and loaded. For example, how would we want to represent loading state? For the entire slice, or on a per-item / request basis? How do we allow the user to specify the overall endpoint? Do we do the actual fetch() call ourselves, or still try to delegate and allow the user to make the call using whatever API lib they're using?

There's lots of existing other libs out there in the "data fetching wrapper" space. To point to some immediately relevant examples:

• https://github.com/vercel/swr
• https://github.com/tannerlinsley/react-query
• https://github.com/coinbase/rest-hooks
• since I'm working on an AngularJS app atm (eep!), there's https://docs.angularjs.org/api/ngResource/service/$resource
• and for more Redux-specific cases, https://github.com/markerikson/redux-ecosystem-links/blob/master/entity-collection-management.md

[markerikson]

@h0tw4t3r RTK aims to solve the most common 80% use cases, so I'm not at all worried about trying to handle anything that's not HTTP.

[eslachance]

Thank you Mark, I've updated my own code to use the Adapter, it's definitely cleaner that way. I was trying to get an idea of how to work the flow when something gets rejected, so yeah the upsert doesn't belong there at all, that's leftover code I hadn't handled correctly yet. There's definitely a lot more that could be done to this so it's generic enough to help anyone, but I feel it's a decent foundation to start building upon.

[markerikson]

So since this issue is open, I'd like to refocus it a bit to discuss the broader ideas of:

• What some kind of an "RTK data fetching abstraction" API might look like
• How we can take inspiration from the libs I listed above
• What kind of constraints and use cases we would need to deal with
• How something like Suspense might fit in

vs just the specific code snippets listed so far.

[panigrah]

@eslachance are you okay to share the code with the adapter please? I like this pattern and am trying to avoid duplicating code like you. I am trying to use your pattern but with the following changes:

• include a error and loading state at the entity level
• use axios instead of fetch
• typescript

But not sure how to work with the variable types. My code looks something like the below. Struggling with the types required for typescript and what changes I can make to the below to support a loading state per slice + a way to cancel the request if needed

@markerikson - in this example I am using loading state per entity slice type. Although my app also requires loading state per entity in a few places which I am currently handling separately. Prior to coming across this post - I had been just copying the same code multiple times for each entity.

export default ({
    baseUrl,
    name,
    initialState
}) => {

    type EntityStateType = typeof initialState & {
      loading: string,
      error?: any,
     currentRequestId?: string
    })

    const fetchById = createAsyncThunk(
        `${name}/fetchByIdStatus`,
        async ( { id }, { getState, requestId }) => {
            const { currentRequestId, loading } = getState()[name]
            if( loading !== 'pending'  || requestId !== currentRequestId ) {
              return
            }
            return axios.get(`${baseUrl}/${id}`) 
        }
    )

    const fetchAll = createAsyncThunk(
        `${name}/fetchAllStatus`,
        async( { page = 0, filters }, { getState, requestId }) => {
            const { currentRequestId, loading } = getState()[name]
            if( loading !== 'pending'  || requestId !== currentRequestId ) {
              return
            }
            return axios.get(`${baseUrl}`, { params: { query: { page, filters }}}) 
        }
    )

    const updateById = createAsyncThunk(
        `${name}/updateByIdStatus`,
        async () => {
        }
    )

    const deleteById = createAsyncThunk(
        `${name}/deleteByIdStatus`,
        async () => {
        }
    )

    const createNew = createAsyncThunk(
        `${name}/createNewStatus`,
        data => {}
    )

    const entityAdapter = createEntityAdapter({
        ...initialState,
        loading: 'idle',
        currentRequestId: undefined,
        error: undefined
    })

    const slice = createSlice({
        name,
        initialState: { entities: {}, loading: 'idle'},
        reducers: {},
        extraReducers: builder => {

            const pendingActionHandler = (state:EntityStateType, action:any) => {
                if( state.loading === 'idle') {
                    state.loading = 'pending'
                    state.error = undefined
                    state.currentRequestId = action.meta.requestId
                }
            }

            const rejectActionHandler = (state:EntityStateType, action:any) => {
                if (state.loading === 'pending' && state.currentRequestId === action.meta.requestId) {
                    state.loading = 'idle'
                    state.currentRequestId = undefined
                    state.error = action.error
                }
            }

            builder
            .addCase(fetchById.fulfilled,  (state:EntityStateType, action:any) => {
                if(state.loading === 'pending' && state.currentRequestId === action.meta.requestId) {
                    state.loading = 'idle'
                    state.currentRequestId = undefined
                    entityAdapter.upsertOne(state, action.payload.data)
                }
            })
            .addCase(fetchById.rejected, rejectActionHandler)
            .addCase(fetchById.pending, pendingActionHandler)
            .addCase(fetchAll.fulfilled,  (state:EntityStateType, action:any) => {
                if(state.loading === 'pending' && state.currentRequestId === action.meta.requestId) {
                    state.loading = 'idle'
                    state.currentRequestId = undefined
                    entityAdapter.setAll(state, action.payload.data)
                }
            })
            .addCase(fetchAll.rejected, rejectActionHandler)
            .addCase(fetchAll.pending, pendingActionHandler)
        },
    })

    return {
        reducer: slice.reducer,
        fetchById,
        fetchAll,
        updateById,
        deleteById,
        createNew,
        entityAdapter
    }
}

[dalechyn]

How something like Suspense might fit in

@markerikson Not a very long time I created a small fetching library for Suspense.

Basically it is a little helper for building an object with read() function for Suspense.

https://github.com/h0tw4t3r/react-redux-fetcher/blob/487332255dce77789068df059235e0c579f91af2/src/actions.js#L3-L32

Internally, dispatched actions look somewhat similar to AsyncAction actions created by async thunk.

Two main tasks that I see here are:

1. We need to add fetching reducer, so should it be written in the library, or let users write it themselves? If first, how should we call it?
2. Should there be a separate function or should it be a result of createAsyncThunk with .read() property?

[eslachance]

Here are some thoughts I have on implementation and usage.

• Data normalization both ways (we use normalizr for this at the moment), which I guess presumes schema configurations, would be great. There's a danger here of falling into ORM patterns, which to me is counterproductive, though.
• Built-in support for query statuses. The examples set an "idle" option in the state but I'm not sure how to use it.

The use case, for me, should be a relatively standard CRUD interface. If it can work out of the box with https://jsonplaceholder.typicode.com/ for example, that would make prototyping things faster. Would people build APIs around this? Yes, I think they might, so good care should be placed in the contract that we're establishing here. Perhaps even making an example OpenAPI/Swagger file might be useful to drive some standardized pattern adoption.

I'd love to see Suspense built-in, that links back to supporting query statuses I guess.

I find that there's a super common pattern when dealing with APIs, which is essentially useEffect + fetch + loading status + error handling, and all this could be handled by the toolkit with something like a hook?

[eslachance]

@panigrah you (and anyone else) are free to use this code any way you see fit. I'm releasing it as public domain, as far as I'm concerned I just put patterns together to push the cause slightly forward so please, feel free to whatever! <3

[mbullington]

So since this issue is open, I'd like to refocus it a bit to discuss the broader ideas of:

• What some kind of an "RTK data fetching abstraction" API might look like
• How we can take inspiration from the libs I listed above
• What kind of constraints and use cases we would need to deal with
• How something like Suspense might fit in

vs just the specific code snippets listed so far.

Not sure if I have enough domain knowledge in Redux to contribute much, but we recently started a React Native application using RTK and ended up with a similar pattern (focusing on the R in CRUD for now).

We have a helper at the slice level that has the following state structure, and creates a fetch thunk that will update these states accordingly:

interface AsyncData<T> {
    loading: boolean
    data: T | null | undefined
    error: any
}

fetch thunk can take up to one parameter and is protocol-agnostic, each slice is required to provide its own implementation. Right now they all use REST, but in the future I feel these options should be left open-ended.

There is also a mergePolicy function which allows data to be merged together, in cases of (for example) an infinite loading list or hashmap.

Combined with redux-persist and a tiny React hook, it feels somewhat similar to vercel/swr but in Redux-land.

Problems I can see with our approach:

1. If a generic URL-response cache is tried with the above approach, loading and error would be very non-descriptive. Maybe having loading & error from AsyncData at the entity-level is better somehow?

[Gilbert1391]

@eslachance are you okay to share the code with the adapter please? I like this pattern and am trying to avoid duplicating code like you. I am trying to use your pattern but with the following changes:

• include a error and loading state at the entity level
• use axios instead of fetch
• typescript

But not sure how to work with the variable types. My code looks something like the below. Struggling with the types required for typescript and what changes I can make to the below to support a loading state per slice + a way to cancel the request if needed

@markerikson - in this example I am using loading state per entity slice type. Although my app also requires loading state per entity in a few places which I am currently handling separately. Prior to coming across this post - I had been just copying the same code multiple times for each entity.

export default ({
    baseUrl,
    name,
    initialState
}) => {

    type EntityStateType = typeof initialState & {
      loading: string,
      error?: any,
     currentRequestId?: string
    })

    const fetchById = createAsyncThunk(
        `${name}/fetchByIdStatus`,
        async ( { id }, { getState, requestId }) => {
            const { currentRequestId, loading } = getState()[name]
            if( loading !== 'pending'  || requestId !== currentRequestId ) {
              return
            }
            return axios.get(`${baseUrl}/${id}`) 
        }
    )

    const fetchAll = createAsyncThunk(
        `${name}/fetchAllStatus`,
        async( { page = 0, filters }, { getState, requestId }) => {
            const { currentRequestId, loading } = getState()[name]
            if( loading !== 'pending'  || requestId !== currentRequestId ) {
              return
            }
            return axios.get(`${baseUrl}`, { params: { query: { page, filters }}}) 
        }
    )

    const updateById = createAsyncThunk(
        `${name}/updateByIdStatus`,
        async () => {
        }
    )

    const deleteById = createAsyncThunk(
        `${name}/deleteByIdStatus`,
        async () => {
        }
    )

    const createNew = createAsyncThunk(
        `${name}/createNewStatus`,
        data => {}
    )

    const entityAdapter = createEntityAdapter({
        ...initialState,
        loading: 'idle',
        currentRequestId: undefined,
        error: undefined
    })

    const slice = createSlice({
        name,
        initialState: { entities: {}, loading: 'idle'},
        reducers: {},
        extraReducers: builder => {

            const pendingActionHandler = (state:EntityStateType, action:any) => {
                if( state.loading === 'idle') {
                    state.loading = 'pending'
                    state.error = undefined
                    state.currentRequestId = action.meta.requestId
                }
            }

            const rejectActionHandler = (state:EntityStateType, action:any) => {
                if (state.loading === 'pending' && state.currentRequestId === action.meta.requestId) {
                    state.loading = 'idle'
                    state.currentRequestId = undefined
                    state.error = action.error
                }
            }

            builder
            .addCase(fetchById.fulfilled,  (state:EntityStateType, action:any) => {
                if(state.loading === 'pending' && state.currentRequestId === action.meta.requestId) {
                    state.loading = 'idle'
                    state.currentRequestId = undefined
                    entityAdapter.upsertOne(state, action.payload.data)
                }
            })
            .addCase(fetchById.rejected, rejectActionHandler)
            .addCase(fetchById.pending, pendingActionHandler)
            .addCase(fetchAll.fulfilled,  (state:EntityStateType, action:any) => {
                if(state.loading === 'pending' && state.currentRequestId === action.meta.requestId) {
                    state.loading = 'idle'
                    state.currentRequestId = undefined
                    entityAdapter.setAll(state, action.payload.data)
                }
            })
            .addCase(fetchAll.rejected, rejectActionHandler)
            .addCase(fetchAll.pending, pendingActionHandler)
        },
    })

    return {
        reducer: slice.reducer,
        fetchById,
        fetchAll,
        updateById,
        deleteById,
        createNew,
        entityAdapter
    }
}

Hi, I am looking exactly for something like this, I tried your code but it's not working as expected. What are you passing as the initialState parameter in the builder function? i.e:

export const signIn = builder({
  baseUrl: 'https://api.deslindate.com/deslindate' + endpoints.auth.signIn,
  name: 'auth',
  initialState: { loading: '', error: false, currentRequestId: '' },
});

I keep getting the rejected type with the following error:
Cannot read property 'currentRequestId' of undefined at

this is the post method:

const post = createAsyncThunk(`${name}/postStatus`, (data, { getState, requestId }) => {
    const { currentRequestId, loading } = getState()[name];
    console.log('state', getState()[name]);
    console.log('cur', currentRequestId);
    if (loading !== 'pending' || requestId !== currentRequestId) {
      return;
    }
    return axios.post(baseUrl, data);
  });

How can I make this work?

[markerikson]

@Gilbert1391 that getState()[name] call will only work if your reducers also happen to be storing relevant data in the store in a field matching what's in the name variable. In other words, it's up to you to write the reducer code that makes that getState() line work.

[Gilbert1391]

@Gilbert1391 that getState()[name] call will only work if your reducers also happen to be storing relevant data in the store in a field matching what's in the name variable. In other words, it's up to you to write the reducer code that makes that getState() line work.

I'm not sure what you mean, I'm new to RTK so please bear with me. I followed @eslachance approach with @panigrah code.

So I have the builder file which contains the code from @panigrah , then I have a slice called authSlice which contains the following function:

export const signIn = builder({
  baseUrl: 'https://api.deslindate.com/deslindate' + endpoints.auth.signIn,
  name: 'auth',
});

The builder takes in a third parameter, I think here is where I'm at loss, I am not sure exactly what to pass here, I tried passing an empty object and some other things but no luck so far.

Then in my reducer file:

import { combineReducers } from 'redux';
import uiSlice from './uiSlice';
import { signIn } from './authSlice';

export default combineReducers({
  ui: uiSlice,
  signIn: signIn.reducer,
});

Finally, i dispatch the action in my component:
dispatch(signIn.post(user));

What am i missing? I'd really appreciate some guidance here.

[markerikson]

You're missing a state.auth in there :) In other words, you need something like:

export default combineReducers({
  ui: uiReducer,
  signIn: signInReducer,
  auth: authReducer
})

or something along those lines.

The key point here is that the builder function is taking a name string, and then trying to look up getState()[name]. So, whatever 'someName' is being passed into the builder, must also exist as state.someName, as defined in your root reducer setup.