Add DataState info to README

Author: davidde

README.md

@@ -62,3 +62,70 @@ This project was started as a Next.js application with server-side rendering hos
 * If after all that you manage to get things to compile, you might notice you don't get **live data** everywhere, some pages simply don't update on reload... This is because those pages haven't been converted to client components yet! **When a server component gets compiled as static site, all server-side data fetching gets baked into the output!** This means you can refresh as much as you want, the data will always remain the same as what it was when the project was built. So, the solution?  
   **Convert everything to client components!**
 
+## DataState Library
+Since this project is handling a lot of async data that has to be fetched from API providers, I co-developed the DataState library to make all of this simpler, more intuitive, and without the usual bloat that comes with client-side data fetching.
+
+The library mainly consists of a `DataState` Algebraic Data Type, which always is in either of 3 states:
+- `LoadingState`: The data is still being fetched.
+- `ErrorState`: The fetching process ran into some kind of error. The `error` field contains the `Error` object.
+- `ValueState`: The fetch succeeded, and the resulting data is contained inside the `value` field of the DataState.
+
+More specifically, the DataState consists of a `Root`, which contains the actual data fields, and `DataStateMethods` that extend the `Root` object into a full `DataState`.
+
+Here are the `Root` definitions for reference:
+```ts
+export type LoadingRoot = {
+  status: 'loading';
+  value: undefined;
+  error: undefined | null;
+  loading: true;
+};
+export type ValueRoot<T> = {
+  status: 'value';
+  value: T;
+  error: undefined;
+  loading: false;
+};
+export type ErrorRoot = {
+  status: 'error';
+  value: undefined;
+  error: Error;
+  loading: false;
+};
+
+export type Root<T> = LoadingRoot | ValueRoot<T> | ErrorRoot;
+```
+
+### Usage
+A `DataState` is initialized with `useDataState()`, which takes a fetching function and its arguments as input. E.g.:
+```ts
+const blockData = useDataState<Block>({
+  fetcher: (alchemy, num) => alchemy.core.getBlock(num),
+  args: [alchemy, blockNumber],
+});
+```
+Once initialized, it can be used directly inside the JSX return statement of the component, e.g.:
+```tsx
+return (
+  <div>
+    <span>Recipient of block reward:</span>
+    <blockData.Render
+      className='w-[11rem]'
+      loadingPulseColor='bg-(--link-color)'
+    >
+      {
+        (data) =>
+          <PopoverLink
+            href={`/${props.network}/address?hash=${data.miner}`}
+            content={truncateAddress(data.miner, 20)}
+            popover={data.miner}
+            className='left-[-37%] top-[-2.6rem] w-78 py-1.5 px-2.5'
+          />
+      }
+    </blockData.Render>
+  </div>
+);
+```
+As shown above, every DataState has a `.Render()` function that receives the fetched data as input, allowing the use of the fetched data directly inside the JSX code:
+* Obviously, the Render function only renders the actual data when it is present. If not present, it will render either an `ErrorIndicator` indicating the error that occurred, or a `LoadingIndicator` or `LoadingPulse` component when the data is still being fetched.
+* All of this is very configurable; see the `RenderConfig` type in `src/lib/data-state/types/index.ts` on line 107. The `RenderConfig` only consists of optional fields to configure the `Render()` function's output. This means the `<blockData.Render>` component's props are all optional, and you can pick and choose only the ones that you need.

src/lib/data-state/types/index.ts

@@ -130,16 +130,17 @@ export type RenderConfig<T, K extends keyof T> = {
   // (`showFallback` takes precedence over both showLoading and showError!)
   showFallback?: boolean;
 
-  // Optional message to display while loading:
+  // Optionally display a LoadingIndicator with the following message:
   loadingMessage?: string;
   // Optional className for just the LoadingPulse component, e.g. for setting its color,
   // which it takes from currentcolor (i.e. text color) by default:
   // (The LoadingPulse component will only display when the above
-  // loadingMessage is NOT set, otherwise only the message will appear.)
+  // loadingMessage is NOT set, otherwise only the LoadingIndicator with message will appear.)
   loadingPulseColor?: string;
   // Optionally display a fallback component while loading:
   // (True by default, so you only need to provide the `loadingCallback()`
-  // function below to actually display it.)
+  // function below to actually display it. When false, the loadingCallback
+  // below will be ignored!)
   showLoadingCallback?: boolean;
   // Optionally display another component instead of the default LoadingIndicator:
   // (Can optionally use the `className` below, just like `children()`.)