@civet/core 1.2.7 → 1.3.1

package/src/{Resource.js → Resource.jsx}

@@ -1,38 +1,39 @@
 import PropTypes from 'prop-types';
-import React from 'react';
-
-import { ResourceContext } from './context';
 import { dataProviderPropType } from './DataProvider';
+import { ResourceContext } from './context';
 import useResource from './useResource';
 
 const propTypes = {
-  /** DataProvider to be used for requests */
+  /** DataProvider to be used for requests - must not be changed */
   dataProvider: dataProviderPropType,
   /** Resource name */
   name: PropTypes.string.isRequired,
-  /** Query */
+  /** Query instructions */
   query: PropTypes.any,
-  /** Whether to prevent fetching data */
+  /** Disables fetching data, resulting in an empty data array */
   empty: PropTypes.bool,
-  /** DataProvider options for requests */
+  /** Query options for requests */
   options: PropTypes.object,
-  /** Whether stale data should be retained during the next request - this only applies if neither dataProvider nor name have changed, unless set to "very" */
+  /** Whether stale data should be retained during the next request - this only applies if name did not change, unless set to "very" */
   persistent: PropTypes.oneOfType([PropTypes.bool, PropTypes.oneOf(['very'])]),
   children: PropTypes.node,
 };
 
 /**
- * Makes data from an DataProvider available to its descendants using React's context API.
- * If not explicitly specified, necessary configuration is taken from the nearest <ConfigProvider>.
- * The provided DataProvider must not be replaced.
+ * Provides data based on the given request details and DataProvider.
+ * Context provider for the ResourceContext.
+ *
+ * Necessary configuration that is not directly specified is taken from the ConfigContext.
+ *
+ * The provided DataProvider must not be changed.
  */
 function Resource({ dataProvider, name, query, empty, options, persistent, children, ...rest }) {
-  const context = useResource({ dataProvider, name, query, empty, options, persistent });
+  const context = useResource({ dataProvider, name, query, empty, options, persistent, ...rest });
 
   return context.dataProvider.uiPlugins.reduceRight(
-    (next, Plugin) => (result) =>
-      (
-        // eslint-disable-next-line react/jsx-props-no-spreading
+    (next, Plugin) =>
+      // eslint-disable-next-line react/display-name
+      (result) => (
         <Plugin {...rest} context={result}>
           {next}
         </Plugin>

package/src/context.js

@@ -1,11 +1,11 @@
-import React from 'react';
+import { createContext, useContext } from 'react';
 
 const noop = () => {};
 
-export const ConfigContext = React.createContext({});
+export const ConfigContext = createContext({});
 ConfigContext.displayName = 'ConfigContext';
-export const useConfigContext = () => React.useContext(ConfigContext);
+export const useConfigContext = () => useContext(ConfigContext);
 
-export const ResourceContext = React.createContext({ data: [], notify: noop });
+export const ResourceContext = createContext({ data: [], notify: noop });
 ResourceContext.displayName = 'ResourceContext';
-export const useResourceContext = () => React.useContext(ResourceContext);
+export const useResourceContext = () => useContext(ResourceContext);

package/src/createPlugin.js

@@ -4,7 +4,6 @@ function createPlugin(plugin) {
   if (typeof plugin !== 'function') throw new Error('No valid plugin definition specified');
   return (dataProviderClass) => {
     if (!Object.prototype.isPrototypeOf.call(DataProvider, dataProviderClass)) {
-      // eslint-disable-next-line no-console
       console.error(
         'A plugin should be given a derivative of the DataProvider class as its first parameter',
       );

package/src/index.js

@@ -4,12 +4,12 @@ export const { Consumer: ConfigConsumer } = ConfigContext;
 export const { Provider: ResourceProvider, Consumer: ResourceConsumer } = ResourceContext;
 export { default as AbortSignal } from './AbortSignal';
 export { default as ChannelNotifier } from './ChannelNotifier';
-export { default as compose } from './compose';
 export { default as ConfigProvider } from './ConfigProvider';
-export { default as createPlugin } from './createPlugin';
-export { dataProviderPropType, default as DataProvider, isDataProvider } from './DataProvider';
+export { default as DataProvider, dataProviderPropType, isDataProvider } from './DataProvider';
 export { default as Meta } from './Meta';
 export { default as Notifier } from './Notifier';
 export { default as Resource } from './Resource';
+export { default as compose } from './compose';
+export { default as createPlugin } from './createPlugin';
 export { default as useResource } from './useResource';
 export { useConfigContext, useResourceContext };

package/src/useResource.js

@@ -1,55 +1,198 @@
-import React from 'react';
-
+import { useCallback, useEffect, useMemo, useReducer, useState } from 'react';
 import AbortSignal from './AbortSignal';
 import Meta from './Meta';
 import { useConfigContext } from './context';
 import uniqueIdentifier from './uniqueIdentifier';
 
 /**
- * Makes data from an DataProvider available.
- * If not explicitly specified, necessary configuration is taken from the nearest <ConfigProvider>.
- * The provided DataProvider must not be replaced.
+ * Appends a new requestInstruction to the state, causing the resource to fetch data.
+ **/
+function createRequestInstruction(state) {
+  return {
+    ...state,
+    requestInstruction: {
+      dataProvider: state.dataProvider,
+      requestDetails: state.requestDetails,
+      request: state.request,
+      revision: state.revision,
+      value: state.value,
+    },
+  };
+}
+
+/**
+ * State reducer for the resource.
+ */
+function reducer(state, action) {
+  switch (action.type) {
+    // Creates a new request and instructs the resource to fetch data.
+    case 'next-request': {
+      const { requestDetails: nextRequestDetails, persistent: nextPersistent } = action;
+      const nextRequest = uniqueIdentifier(state.request);
+      const nextRevision = uniqueIdentifier(state.revision);
+      let isPersistent = false;
+      if (state.persistent === 'very' && nextPersistent === 'very') {
+        isPersistent = 'very';
+      } else if (state.persistent && nextPersistent) {
+        isPersistent = true;
+      }
+      const shouldValuePersist =
+        !nextRequestDetails.empty &&
+        state.dataProvider.shouldPersist(
+          nextRequestDetails,
+          state.requestDetails,
+          isPersistent,
+          state.value,
+        );
+      return createRequestInstruction({
+        dataProvider: state.dataProvider,
+        requestDetails: nextRequestDetails,
+        request: nextRequest,
+        revision: nextRevision,
+        isLoading: !nextRequestDetails.empty,
+        value: shouldValuePersist
+          ? state.value
+          : {
+              name: nextRequestDetails.name,
+              query: nextRequestDetails.query,
+              options: nextRequestDetails.options,
+              request: nextRequest,
+              revision: nextRevision,
+              data: [],
+              meta: {},
+              error: undefined,
+              isEmpty: !!nextRequestDetails.empty,
+              isIncomplete: !nextRequestDetails.empty,
+              isInitial: !nextRequestDetails.empty,
+            },
+        persistent: nextPersistent,
+      });
+    }
+
+    // Creates a new revision for the current request and instructs the resource to fetch data.
+    case 'next-revision': {
+      const { notify } = action;
+      const nextRevision = uniqueIdentifier(state.revision);
+      notify({ request: state.request, revison: nextRevision });
+      return createRequestInstruction({
+        ...state,
+        revision: nextRevision,
+        isLoading: !state.requestDetails.empty,
+      });
+    }
+
+    // Sets a new persistence level.
+    case 'set-persistence': {
+      const { persistent: nextPersistent } = action;
+      return {
+        ...state,
+        persistent: nextPersistent,
+      };
+    }
+
+    // Updates the current request's data.
+    case 'update-data': {
+      const { request, revision, value } = action;
+      if (request !== state.request || revision !== state.revision) return state;
+      return {
+        ...state,
+        isLoading: value.isIncomplete,
+        value,
+      };
+    }
+  }
+
+  return state;
+}
+
+/**
+ * Starts fetching data and updates the resource when new data is available.
+ */
+function fetchData(requestInstruction, instance, abortSignal, dispatch) {
+  const { dataProvider, requestDetails, request, revision, value } = requestInstruction;
+
+  const meta = new Meta({ ...value.meta }, instance);
+
+  let promise = Promise.resolve(value);
+
+  const callback = (error, done, data) => {
+    promise = promise.then((prevValue) => {
+      try {
+        let nextValue;
+        if (error != null) {
+          nextValue = { ...prevValue, error, isIncomplete: false };
+        } else {
+          const context = {
+            name: requestDetails.name,
+            query: requestDetails.query,
+            options: requestDetails.options,
+            request,
+            revision,
+            data,
+            meta: meta.commit(prevValue.meta),
+            error: undefined,
+            isEmpty: false,
+            isIncomplete: !done,
+            isInitial: !!prevValue.isInitial && !done,
+          };
+          context.data = dataProvider.transition(context, prevValue);
+          context.data = dataProvider.recycleItems(context, prevValue);
+          nextValue = context;
+        }
+
+        dispatch({ type: 'update-data', request, revision, value: nextValue });
+
+        return nextValue;
+      } catch {
+        return prevValue;
+      }
+    });
+  };
+
+  dataProvider.continuousGet(
+    requestDetails.name,
+    requestDetails.query,
+    requestDetails.options,
+    meta,
+    callback,
+    abortSignal,
+  );
+}
+
+/**
+ * Provides data based on the given request details and DataProvider.
+ *
+ * Necessary configuration that is not directly specified is taken from the ConfigContext.
+ *
+ * The provided DataProvider must not be changed.
  */
 function useResource({
+  /** DataProvider to be used for requests - must not be changed */
   dataProvider: dataProviderProp,
+  /** Resource name */
   name: nextName,
+  /** Query instructions */
   query: nextQuery,
+  /** Disables fetching data, resulting in an empty data array */
   empty: nextEmpty,
+  /** Query options for requests */
   options: nextOptions,
+  /** Whether stale data should be retained during the next request - this only applies if name did not change, unless set to "very" */
   persistent: nextPersistent,
   ...rest
 }) {
   const configContext = useConfigContext();
   const currentDataProvider = dataProviderProp || configContext.dataProvider;
-  const [dataProvider] = React.useState(currentDataProvider);
-  if (dataProvider == null) {
-    throw new Error(
-      'Unmet requirement: The DataProvider for the useResource hook is missing - Check your ConfigContext provider and the dataProvider property',
-    );
-  }
-  if (dataProvider !== currentDataProvider) {
-    throw new Error(
-      'Constant violation: The DataProvider provided to the useResource hook must not be replaced - Check your ConfigContext provider and the dataProvider property',
-    );
-  }
 
-  const [instance, setInstance] = React.useState();
-  React.useEffect(() => {
-    const i = dataProvider.createInstance();
-    setInstance(i ?? {});
-    return () => {
-      dataProvider.releaseInstance(i);
-    };
-  }, []);
-
-  const nextRequestDetails = React.useMemo(
+  const nextRequestDetails = useMemo(
     () => ({ name: nextName, query: nextQuery, empty: nextEmpty, options: nextOptions }),
     [nextName, nextQuery, nextEmpty, nextOptions],
   );
-  const [state, setState] = React.useState(() => {
+  const [state, dispatch] = useReducer(reducer, undefined, () => {
     const request = uniqueIdentifier();
     const revision = uniqueIdentifier();
-    return {
+    return createRequestInstruction({
+      dataProvider: currentDataProvider,
       requestDetails: nextRequestDetails,
       request,
       revision,
@@ -68,165 +211,96 @@ function useResource({
         isInitial: !nextRequestDetails.empty,
       },
       persistent: nextPersistent,
-    };
+    });
   });
-  const { requestDetails, request, revision, isLoading, value, persistent } = state;
+  const {
+    dataProvider,
+    requestDetails,
+    request,
+    revision,
+    isLoading,
+    value,
+    persistent,
+    requestInstruction,
+  } = state;
+
+  if (dataProvider == null) {
+    throw new Error(
+      'Unmet requirement: The DataProvider for the useResource hook is missing - Check your ConfigContext provider and the dataProvider property',
+    );
+  }
+  if (dataProvider !== currentDataProvider) {
+    throw new Error(
+      'Constant violation: The DataProvider provided to the useResource hook must not be replaced - Check your ConfigContext provider and the dataProvider property',
+    );
+  }
+
+  const [instance, setInstance] = useState();
+  useEffect(() => {
+    const i = dataProvider.createInstance();
+    setInstance(i ?? {});
+    return () => {
+      dataProvider.releaseInstance(i);
+    };
+  }, [dataProvider]);
 
   if (
     requestDetails !== nextRequestDetails &&
     !dataProvider.compareRequests(nextRequestDetails, requestDetails)
   ) {
-    setState((prevState) => {
-      const nextRequest = uniqueIdentifier(prevState.request);
-      const nextRevision = uniqueIdentifier(prevState.revision);
-      let isPersistent = false;
-      if (prevState.persistent === 'very' && nextPersistent === 'very') {
-        isPersistent = 'very';
-      } else if (prevState.persistent && nextPersistent) {
-        isPersistent = true;
-      }
-      const shouldValuePersist =
-        !nextRequestDetails.empty &&
-        dataProvider.shouldPersist(
-          nextRequestDetails,
-          prevState.requestDetails,
-          isPersistent,
-          prevState.value,
-        );
-      return {
-        requestDetails: nextRequestDetails,
-        request: nextRequest,
-        revision: nextRevision,
-        isLoading: !nextRequestDetails.empty,
-        value: shouldValuePersist
-          ? prevState.value
-          : {
-              name: nextRequestDetails.name,
-              query: nextRequestDetails.query,
-              options: nextRequestDetails.options,
-              request: nextRequest,
-              revision: nextRevision,
-              data: [],
-              meta: {},
-              error: undefined,
-              isEmpty: !!nextRequestDetails.empty,
-              isIncomplete: !nextRequestDetails.empty,
-              isInitial: !nextRequestDetails.empty,
-            },
-        persistent: nextPersistent,
-      };
+    dispatch({
+      type: 'next-request',
+      requestDetails: nextRequestDetails,
+      persistent: nextPersistent,
     });
   } else if (persistent !== nextPersistent) {
-    setState((prevState) => ({ ...prevState, persistent: nextPersistent }));
+    dispatch({ type: 'set-persistence', persistent: nextPersistent });
   }
 
-  const notify = React.useCallback(
+  const notify = useCallback(
     async () =>
       new Promise((resolve) => {
-        setState((currentState) => {
-          const nextRevision = uniqueIdentifier(currentState.revision);
-          resolve({ request: currentState.request, revision: nextRevision });
-          return { ...currentState, isLoading: true, revision: nextRevision };
-        });
+        dispatch({ type: 'next-revision', notify: resolve });
       }),
     [],
   );
 
   // DataProvider events
-  React.useEffect(() => {
+  useEffect(() => {
     if (requestDetails.empty) return undefined;
 
     const unsubscribe = dataProvider.subscribe(requestDetails.name, notify);
     return unsubscribe;
   }, [requestDetails.empty, dataProvider, requestDetails.name, notify]);
 
-  React.useEffect(() => {
-    if (requestDetails.empty || instance == null) return undefined;
+  // Fetch data when instructed
+  useEffect(() => {
+    if (instance == null || requestInstruction.requestDetails.empty) return undefined;
 
     const abortSignal = new AbortSignal();
 
-    const meta = new Meta({ ...value.meta }, instance);
-
-    let promise = Promise.resolve(state);
-
-    const callback = (error, done, data) => {
-      promise = promise.then((prevState) => {
-        try {
-          let nextState;
-
-          if (error != null) {
-            nextState = {
-              ...prevState,
-              isLoading: false,
-              value: {
-                ...prevState.value,
-                error,
-                isIncomplete: false,
-              },
-            };
-          } else {
-            const context = {
-              name: requestDetails.name,
-              query: requestDetails.query,
-              options: requestDetails.options,
-              request,
-              revision,
-              data,
-              meta: meta.commit(prevState.value.meta),
-              error: undefined,
-              isEmpty: false,
-              isIncomplete: !done,
-              isInitial: !!prevState.isInitial && !done,
-            };
-            context.data = dataProvider.transition(context, prevState.value);
-            context.data = dataProvider.recycleItems(context, prevState.value);
-
-            nextState = {
-              ...prevState,
-              isLoading: !done,
-              value: context,
-            };
-          }
-
-          setState((otherState) => {
-            if (request !== otherState.request || revision !== otherState.revision) {
-              return otherState;
-            }
-
-            return nextState;
-          });
-
-          return nextState;
-        } catch {
-          return prevState;
-        }
-      });
-    };
-
-    dataProvider.continuousGet(
-      requestDetails.name,
-      requestDetails.query,
-      requestDetails.options,
-      meta,
-      callback,
-      abortSignal,
-    );
+    // Start fetching data.
+    fetchData(requestInstruction, instance, abortSignal, dispatch);
 
     return () => {
+      // Abort fetching data when another request is pending or the React component is unmounted.
       abortSignal.abort();
     };
-  }, [instance, request, revision]);
+  }, [instance, requestInstruction]);
 
   const isStale = revision !== value.revision;
-  const next = React.useMemo(
-    () => (isStale ? { request, revision } : { request: value.request, revision: value.revision }),
-    [isStale, request, revision, value.request, value.revision],
+  const nextRequest = isStale ? request : value.request;
+  const nextRevision = isStale ? revision : value.revision;
+  const next = useMemo(
+    () => ({ request: nextRequest, revision: nextRevision }),
+    [nextRequest, nextRevision],
   );
-  const context = React.useMemo(
+  const context = useMemo(
     () => ({ ...value, dataProvider, isLoading, isStale, next, notify }),
     [value, dataProvider, isLoading, isStale, next, notify],
   );
 
+  // Apply context plugins and return the final context.
   return dataProvider.contextPlugins.reduce((result, fn) => fn(result, rest), context);
 }