Using promises and exports in an atom

[erictompkins]

We have an atom that needs to make an AJAX request to get the data for the store. This isn't a problem as there are plenty of examples in the documentation about how to do this.

However, we also need to have function exports that can update the store data. I didn't see any examples in the documentation for this scenario.

First I tried using injectPromise and having the export functions update the store with promise.store.setState() but that didn't seem to propagate the updates. We also need to test the current value against the submitted value to the function to determine if the store should be updated because we also make an AJAX post to save the update in our API.

Here is what we're doing now. Is this a good approach? Do you see any problems or have any suggestions for improvements?

export const uiAtom = atom('uiAtom', () => {
    const store = injectStore<UiData>(
        {
            ready: false,
            section: 'unknown',
            sidebarOpen: true,
            sidebarTheme: 'nileBlue',
            theme: 'saphire',
        },
        { subscribe: false },
    );

    const promise = injectMemo(() => {
        const path = window.location.pathname;

        return new Promise<void>((resolve) => {
            // Default minimal state that the UI data will be merged into
            let stateData: UiData = {
                ready: false,
                section: 'unknown',
                sidebarOpen: true,
                sidebarTheme: 'nileBlue',
                theme: 'saphire',
            };
            if (['/login', '/password'].includes(path)) {
                // No need to get navigation data for the login pages
                stateData.ready = true;
                stateData.section = 'login';
                store.setState((state) => ({
                    ...state,
                    ...stateData,
                }));
                resolve();
            }
            // This is one of the main pages in the app or a site page
            axios
                .get(`${getMainApiUrl()}/ui?p=${window.location.pathname}`)
                .then((res) => {
                    if (isStringWithValue(res.data.section)) {
                        stateData.ready = true;
                        stateData = {...stateDate, ...res.data}
                        
                        store.setState((state) => ({
                            ...state,
                            ...stateData,
                        }));
                    } else {
                        toastError(
                            'Could not load initial UI configuration. Please refresh the page to try again. If the problem persists please contact support.',
                        );
                    }
                    resolve();
                })
                .catch((error) => {
                    handleRequestError(error);
                    resolve();
                });
        });
    }, []);

    // Set the default theme on initialization
    injectEffect(() => {
        setTheme('saphire', 'na');
    }, []);

    // Set up the atom exports.
    const exports = {
       
        /**
         * Set the site name
         *
         * @param {string} siteName The site name
         */
        setSiteName: (siteName: string) => {
            store.setState((state) => ({
                ...state,
                siteName,
            }));
        },

        /**
         * Set the theme value
         * This will update the theme value in the UI and save it for the user
         *
         * @param {string} theme The theme value
         * @param {string} source Where the updated data came from. 'user' or 'broadcast' are expected values
         */
        setTheme: (theme: string, source: string = 'user') => {
            // Don't do anything if the current value is the same as the new value.
            // This can happen with the BroadcastChannel in page/Sidebar.tsx
            // const oldState = promiseApi.store.getState();
            const oldState = store.getState();
            if (oldState.theme !== theme) {
                // Update the uiAtom state
                store.setState((state: UiData) => ({
                    ...state,
                    theme,
                }));

                // Set the theme on the body tag
                setTheme(theme, oldState?.theme);

                if (source !== 'broadcast') {
                    // Post a message to the BroadcastChannel with the new theme value
                    themeChannel.postMessage(theme);

                    // Save the theme for the user
                    axios
                        .post(`${getApiUrl()}/ui/update-theme`, {
                            theme,
                        })
                        .catch((error) => {
                            handleRequestError(error);
                        });
                }
            }
        },

        /**
         * Set the user data
         * The data should include the user's name and email.
         *
         * @param {UiUser} user The user data - name and email
         */
        setUser: (user: UiUser) => {
            store.setState((state) => ({
                ...state,
                user,
            }));
        },
    };

    return api(store).setExports(exports).setPromise(promise);
});

Thank you for any feedback you have.

[bowheart]

Hey @erictompkins Your code looks fine to me. There's nothing wrong necessarily with kicking off promises in injectMemo. Assuming consumers wait for the set promise before using uiAtom, there wouldn't be a race condition between the promise and the exports.

You're right, I don't see an example in the docs of using exports to manipulate the store returned by injectPromise. Here's how I would have written your code using injectPromise:

const initialState: UiData = {
  section: 'unknown',
  sidebarOpen: true,
  sidebarTheme: 'nileBlue',
  theme: 'saphire',
}

const uiAtom = atom('uiAtom', () => {
  const promiseApi = injectPromise<UiData>(
    async () => {
      const path = window.location.pathname

      // Default minimal state that the UI data will be merged into
      let stateData = { ...initialState }

      if (['/login', '/password'].includes(path)) {
        // No need to get navigation data for the login pages
        stateData.section = 'login'

        return stateData // <- NOTE you didn't `return` here. Possible bug
      }
      // This is one of the main pages in the app or a site page
      return axios
        .get(`${getMainApiUrl()}/ui?p=${window.location.pathname}`)
        .then(res => {
          if (isStringWithValue(res.data.section)) {
            stateData = { ...stateData, ...res.data } // <- NOTE you had `stateDate`. I'm guessing it's just not your exact code.
          } else {
            const errorMessage =
              'Could not load initial UI configuration. Please refresh the page to try again. If the problem persists please contact support.'

            toastError(errorMessage)

            throw new Error(errorMessage)
          }
          return stateData
        })
        .catch(error => {
          handleRequestError(error)
          throw error
        })
    },
    [],
    { initialState }
  )

  // Set the default theme on initialization
  injectEffect(() => {
    setTheme('saphire', 'na')
  }, [])

  // Set up the atom exports.
  const exports = {
    /**
     * Set the site name
     *
     * @param {string} siteName The site name
     */
    setSiteName: (siteName: string) =>
      promiseApi.store.setStateDeep({ data: { siteName } }),

    /**
     * Set the theme value
     * This will update the theme value in the UI and save it for the user
     *
     * @param {string} theme The theme value
     * @param {string} source Where the updated data came from. 'user' or 'broadcast' are expected values
     */
    setTheme: (theme: string, source = 'user') => {
      // Don't do anything if the current value is the same as the new value.
      // This can happen with the BroadcastChannel in page/Sidebar.tsx
      const oldState = promiseApi.store.getState()
      if (oldState.data?.theme !== theme) {
        // Update the uiAtom state
        promiseApi.store.setStateDeep({ data: { theme } })

        // Set the theme on the body tag
        setTheme(theme, oldState.data?.theme)

        if (source !== 'broadcast') {
          // Post a message to the BroadcastChannel with the new theme value
          themeChannel.postMessage(theme)

          // Save the theme for the user
          axios
            .post(`${getApiUrl()}/ui/update-theme`, {
              theme,
            })
            .catch(error => {
              handleRequestError(error)
            })
        }
      }
    },

    /**
     * Set the user data
     * The data should include the user's name and email.
     *
     * @param {UiUser} user The user data - name and email
     */
    setUser: (user: UiUser) =>
      promiseApi.store.setStateDeep({ data: { user } }),
  }

  return promiseApi.setExports(exports)
})

I left two notes in there. I also got rid of the ready state property, letting injectPromise handle it. I plugged this into a sandbox, mocking axios and all the other extraneous functions, and it looks like it works as expected. Example React usage:

function Ui() {
  const [state, { setTheme }] = useAtomState(uiAtom)

  return (
    <div>
      Ui state: <pre>{JSON.stringify(state, null, 2)}</pre>
      <button onClick={() => setTheme('new-theme')}>Set Theme</button>
    </div>
  )
}

function App() {
  return (
    <Suspense fallback={<div>Loading Ui...</div>}>
      <Ui />
    </Suspense>
  )
}

Can you see any points where your implementation with injectPromise varied from this? If no, it sounds like a possible bug. If yes, I'd love to know what wasn't clear so I can improve the docs.

[erictompkins]

Here is what the code used to be when I was trying to use injectPromise.

(And you're right, the "stateDate" misspelling was because I was trying to shorten our actual code. There is a lot more that we do with the result, I was trying to shorten the code.)

export const uiAtom = atom('uiAtom', () => {
    const promiseApi = injectPromise<UiData>(
        () => {
            const path = window.location.pathname;

            return new Promise((resolve) => {
                let stateData: UiData = {
                    ready: false,
                    section: 'unknown',
                    sidebarOpen: true,
                    sidebarTheme: 'nileBlue',
                    theme: 'saphire',
                };
                if (['/login', '/password'].includes(path)) {
                    // No need to get navigation data for the login pages
                    stateData.ready = true;
                    stateData.section = 'login';
                    resolve(stateData);
                }
                // This is one of the main pages in the app or a site page
                axios
                    .get(`${getMainApiUrl()}/ui?p=${window.location.pathname}`)
                    .then((res) => {
                        if (isStringWithValue(res.data.section)) {
                            stateData.ready = true;
                            stateData = { ...stateData, ...res.data };
                        } else {
                            toastError(
                                'Could not load initial UI configuration. Please refresh the page to try again. If the problem persists please contact support.',
                            );
                        }
                        resolve(stateData);
                    })
                    .catch((error) => {
                        handleRequestError(error);
                        resolve(stateData);
                    });
            });
        },
        [],
        {
            initialState: {
                ready: false,
                section: 'unknown',
                sidebarOpen: true,
                sidebarTheme: 'nileBlue',
                theme: 'saphire',
            },
        },
    );

    // Set the default theme on initialization
    injectEffect(() => {
        setTheme('saphire', 'na');
    }, []);

    // Set up the atom exports.
    const exports = {
        /**
         * Set the site name
         *
         * @param {string} siteName The site name
         */
        setSiteName: (siteName: string) => {
            promiseApi.store.setState((state) => ({
                ...state,
                siteName,
            }));
        },

        /**
         * Set the theme value
         * This will update the theme value in the UI and save it for the user
         *
         * @param {string} theme The theme value
         * @param {string} source Where the updated data came from. 'user' or 'broadcast' are expected values
         */
        setTheme: (theme: string, source: string = 'user') => {
            // Don't do anything if the current value is the same as the new value.
            // This can happen with the BroadcastChannel in page/Sidebar.tsx
            // const oldState = promiseApi.store.getState();
            const oldState = promiseApi.store.getState();
            console.log('OldState: ', oldState?.data?.theme);
            if (oldState?.data?.theme !== theme) {
                // Update the uiAtom state
                promiseApi.store.setState((state) => ({
                    ...state,
                    theme,
                }));

                // Set the theme on the body tag
                setTheme(theme, oldState?.data?.theme);

                if (source !== 'broadcast') {
                    // Post a message to the BroadcastChannel with the new theme value
                    themeChannel.postMessage(theme);

                    // Save the theme for the user
                    axios
                        .post(`${getApiUrl()}/ui/update-theme`, {
                            theme,
                        })
                        .catch((error) => {
                            handleRequestError(error);
                        });
                }
            }
        },

        /**
         * Set the user data
         * The data should include the user's name and email.
         *
         * @param {UiUser} user The user data - name and email
         */
        setUser: (user: UiUser) => {
            promiseApi.store.setState((state) => ({
                ...state,
                user,
            }));
        },
    };

    return api(promiseApi).setExports(exports);
});

And then updating the theme value (abbreviated code)

const uiData = useAtomInstance(uiAtom);
uiData.exports.setTheme(colorKey);

[erictompkins]

I noticed that you used const [state, { setTheme }] = useAtomState(uiAtom).
If we're only wanting to use the exports which approach is better?

const [, { setTheme }] = useAtomState(uiAtom)
setTheme('value');

or

const uiData = useAtomInstance(uiAtom);
uiData.exports.setTheme('value');

[bowheart]

setStateDeep vs setState shouldn't matter. I used setStateDeep because the setState call started looking very verbose after switching to using injectPromise's nested data property.

You can still use setState, but like this:

promiseApi.store.setState((state) => ({
  ...state,
  data: {
    ...state.data,
    theme,
  }
}));

injectPromise nests the promise's result data inside the data property. This is patterned after React Query. It's also why I got rid of the ready property in my example - injectPromise tracks the promise's readiness by default.

promiseApi.store.getState() // { data: <your custom state>, isLoading: true, isError: false, isSuccess: false, status: 'loading' }

You can prevent this by passing dataOnly: true to injectPromise. That removes all the extra state Zedux tracks and un-nests the data property:

const promiseApi = injectPromise(
  () => ...,
  [],
  { dataOnly: true, initialState },
);

promiseApi.store.getState() // <your custom state>

If we're only wanting to use the exports which approach is better?

The latter. I rarely use useAtomState in practice, it's just super convenient in examples. If you only need access to exports, useAtomInstance is better since it doesn't subscribe the current component to state updates.

[erictompkins]

Your explanation on setStateDeep vs setState and the data value makes sense. Thank you very much for your quick replies.

We're converting from Recoil to zedux and the ready value is a carry over from what we had there. We're still refactoring and eventually that'll be gone from our code too.

If we want to use the promise with Suspense, should we not use dataOnly: true?

I noticed that in the atom you returned with:

return promiseApi.setExports(exports)

Is that different or better than this?

return api(promiseApi).setExports(exports);

[bowheart]

If you're using with suspense, you absolutely can use dataOnly: true - Zedux will simply pass the promise along to let React handle its ready state. There may still be a use for reading the promise's state from other atoms, but they can also await getInstance(uiAtom).promise.

My code

return promiseApi.setExports(exports)

isn't necessarily better. It prevents another AtomApi from being created, but it does so by mutating the AtomApi returned from injectPromise. I do that 'cause .. I know I can 😄 . But really, your code's better practice in general.

[erictompkins]

Thank you very much for your advice and help!

[bowheart]

Thanks for asking. I'd love to hear how the migration from Recoil goes.

This discussion actually highlighted a few things I want to improve with injectPromise. I've created #220 for this. @erictompkins If you have input on the proposed changes, I'd love to hear it