Cleaning up how the hooks diff args

Author: zackdotcomputer

README.md

@@ -22,7 +22,7 @@ That template is Copyright (c) 2018 Othneil Drew licensed under the MIT license.
   <h3 align="center">Suspension</h3>
 
   <p align="center">
-    A "hook in place" approach to easily integrating your existing Promise-based async data fetchers with React <pre><Suspense></pre> components.
+    A "hook in place" approach to easily integrating your existing Promises and async/await data fetchers with React <pre><Suspense></pre> components.
     <br />
     <a href="https://github.com/zackdotcomputer/suspension"><strong>Explore the docs »</strong></a>
     <br />
@@ -53,7 +53,7 @@ That template is Copyright (c) 2018 Othneil Drew licensed under the MIT license.
         <li><a href="#suspension-hooks">The Hooks</a></li>
       </ul>
     </li>
-    <li><a href="#usage-and-bits">Usage and bits</a></li>
+    <li><a href="#usage-and-details">Usage and Details</a></li>
     <li><a href="#roadmap">Roadmap</a></li>
     <li><a href="#contributing">Contributing</a></li>
     <li><a href="#license">License</a></li>
@@ -74,7 +74,9 @@ The core concept is to be as simple as possible. Add a "rig" high up in your app
 
 ### Built For
 
-At the moment, the library is built for the React web build and requires version 16.13 or newer. If you'd like a build for react-native, drop by [this Issue](https://github.com/zackdotcomputer/suspension/issues/1) and discuss.
+At the moment, the library is built for the React web build and requires version 16.13 or newer.
+
+A react-native build would be realistically possible as well, so if you'd like that please drop by [this Issue](https://github.com/zackdotcomputer/suspension/issues/1) and discuss.
 
 <!-- GETTING STARTED -->
 
@@ -112,7 +114,7 @@ function MyApp() {
 
 ### Suspension Hooks
 
-Now that your app is rigged, your ready to use suspenseful loads! The key feature of `suspension` is that it makes using your existing Promises as easy as a hook. Here is an example in Typescript:
+Now that your app is rigged, your ready to use the hooks! The key feature of `suspension` is that it makes using your existing Promises with Suspense as easy as a hook. Here is an example in Typescript:
 
 ```tsx
 function UserProfile() {
@@ -138,87 +140,100 @@ function UserProfile() {
 
 <!-- USAGE EXAMPLES -->
 
-## Usage and bits
+## Usage and Details
 
 There are three main pieces to `suspension`:
 
-### `<SuspensionRig>` - Cache and fallback
+### `<SuspensionRig>` - Your cache and fallback
 
 `<SuspensionRig>` is a safety net for your suspension calls to fall back on. Because
 suspense uses `throw` to interrupt the render process, anything that was stored in state
 from that point up to the last `<Suspense>` component will be destroyed. `<SuspensionRig>`
-gives a safe space **above** the last `<Suspense>` for the hooks to store their data. It
-serves three main purposes in that way:
+gives a safe space **above** the last `<Suspense>` for the hooks to store their data. In addition
+to just being a landing space for Promises, the rig has three other roles:
 
 1. **It is a cache**. The rig is responsible for caching all the data about the promises
-   linked to hooks beneath it. There is no limit, though, on the number of rigs you place in
-   your tree and any hooks you call will use the nearest ancestor rig. So, if you have a page
-   that loads in a lot of data using Suspense hooks, consider your router wrap that page in its
-   own rig so that the data is cleaned up when the page is unmounted.
-
-2. **It is the ulimate `<Suspense>`**. Because the rig needs a `Suspense` barrier between it
-   and its hooks (otherwise it would be swept away by the loading event as well), it was a common
-   pattern from day one to make the rig's first child a Suspense. So, that's just built-in now.
-   If you want the `SuspenseRig` to behave as both a cache and a fallback `Suspense`, you just
-   need to give it the same `fallback` prop you would give a `Suspense`.
-
-3. **It is your Error Boundary**. Similarly to how you can pass the `fallback` prop to your rig to
-   have it act as a Suspense, you can also pass an `errorBoundary` prop to have it act as your Error
-   Boundary. Under the hood, this feature uses [react-error-boundary](https://github.com/bvaughn/react-error-boundary)
-   to implement the error boundary. You can pass anything in the `errorBoundary` object that you
-   would pass as a prop to that library. If the object is present at all, the rig will insert
-   a boundary below itself and above the Suspense (if included) and children.
+   linked to hooks beneath it. There is no limit on the number of rigs you place in
+   your tree. Suspension hooks will use their nearest ancestor rig. So, if you have a single
+   component that loads in a lot of data, consider your router wrap that page in its own rig
+   so that the data is cleaned up when the rig is unmounted.
+
+2. **It is your fallback `<Suspense>`**. Because the rig needs a `Suspense` barrier between it
+   and its hooks (otherwise it would be swept away by the loading throw as well), it was a common
+   pattern from day one to make the rig's first child a Suspense. So, I built that in.
+   If you give the `SuspenseRig` the same `fallback` prop as you would give a `Suspense`, the
+   right will automatically create a `Suspense` wall below it with that fallback.
+
+3. **It is your Error Boundary**. Similarly you can also pass an `errorBoundary` prop to have it
+   act as your Error Boundary. Under the hood, this feature uses
+   [react-error-boundary](https://github.com/bvaughn/react-error-boundary).
+   You can pass anything in the `errorBoundary` object that you can pass as a prop to that library.
+   If the prop is present, the rig will insert a boundary below itself and above its other children.
 
 ### `useSuspension` - The ready-to-go hook
 
-`useSuspension(generator, cacheKey, args, options)` is the primary hook for accessing suspension.
-It takes a parameter-free generator function that returns a Promise and a cache key that uniquely
-identifies this call's purpose (see below).
+`useSuspension` is the primary hook for accessing suspension. It has a slightly different form
+depending on whether your data generator function takes arguments or not, but both forms share
+the need for a generator, a cacheKey that identifies this call's purpose (see below), and an
+optional object with configuration options. If your generator takes args, you can pass those
+as an array as well.
+
+```typescript
+// With a generator that takes args:
+useSuspension(generator, cacheKey, argsArray, options);
+
+// With a generator that doesn't:
+useSuspension(generator, cacheKey, options);
+```
 
-As soon as you call this hook, it will start your generator going and interrupt the render cycle
-at that point. (Note: even if your generator returns a resolved promise, React will always do at
+The first time you call this hook it will immediately start your generator and interrupt the
+render cycle. (Note: even if your generator returns a pre-resolved promise, React will always do at
 least one render update falling back to the `<Suspense>`.) Once the Promise has resolved, the tree
 under the nearest Suspense will be reloaded and the hook will **then** either provide you with the
-result of the `Promise` or throw the `Error` for your nearest ErrorBoundary if the Promise was
+result of your generator or throw the `Error` for your nearest ErrorBoundary if the Promise was
 rejected.
 
-This construction means that your render function will never proceed beyond this call unless it can
-return to you the successfully resolved value from your `Promise`. No more needing to deal with
-`undefined` loading values.
+This means that your render function will never proceed beyond this call unless it can return
+the resolved value from your `Promise`. No more needing to deal with `undefined` loading values.
 
-### `useLazySuspension` - For those asynchronous asynchronous cases
+### `useLazySuspension` - For a bit more finesse
 
-`useLazySuspension(generator, cacheKey, options)` is your friend for calls where the arguments to your
-generator might change between render cycles, or where you might need to delay your generator. It takes
-a generator function which can now take any number of parameters but still must return a Promise. It
-also still takes that same cache key that uniquely identifies this call's purpose (still see below).
+`useLazySuspension(generator, cacheKey, options)` is for calls where you need more control over
+when or whether your generator is called. This hook takes the same parameters as `useSuspension`
+except that you never pass the args to the hook.
 
-When you call this hook you will get back an array. The first element is your result and it will start
-as `undefined`. The second element is your trigger function. It will have the same parameter expectations
-as your generators. Whenever you want to start a new call, call the trigger function with the args.
+This hook returns an array with two elements. The first element is your lazy reader function. It takes
+the args for your generator and will return the resolved value if it has one for those args, undefined
+if it doesn't, or will throw an error if the Promise was rejected. If the promise is still in progress,
+this reader will throw the pending promise to trigger Suspense.
 
-The trigger function also uses a bit of trickery to trigger a re-render of your component, so as soon
-as you call it the host component will redraw and disappear from screen, falling back to the nearest
-`<Suspense>` until the load is complete. Once the Promise has resolved, the tree under that Suspense
-will be rerendered. At that point this hook will do one of two things. If the Promise resolved, the hook
-will return the same array but now the first element will be the resolved value from the Promise. If
-the hook was rejected, the hook will throw a `SuspensionResolutionFailedError`, which can be caught
-by an ErrorBoundary. This error will have the underlying failure as well as a `retryFunction` that can
-be used to retry the generator with the same args.
+The second element is your suspenseful loading function. It also should be called with the args for your
+generator. This function will always return the resolved value for those args, or it will throw a Promise
+if it does not yet have them. **Note** this function will never throw an Error on failure. If you call
+it and the most recent Promise was rejected, this function will start a new call.
+
+### Failures and `SuspensionResolutionFailedError`
+
+If the `useSuspension` hook's promise is rejected or if the lazy reader is used to access a value that
+most recently was rejected, those calls will throw a `SuspensionResolutionFailedError`.
+This error can be caught by an ErrorBoundary and will contain the underlying error from the Promise
+as well as a `retryFunction` that can be used to retry the generator with the same args.
 
 ### Caching
 
-When you call the `useSuspension` hook or the `useLazySuspension` trigger function the Rig will check
-if results are already cached. It will do this based on your supplied cache key and the args array you
-provide. If the args array is the same (by default determined by walking the args array with a `===`
-check) and the last Promise is loading or resolved, then it will not start a new call. If the last call
-was rejected or the args array appears to be new, then the previous results will be discarded and a new
-call started from your generator.
+When you call the `useSuspension` hook or call the functions returned by `useLazySuspension` the
+Rig will check if results are already cached.
+
+It will do this based on your supplied cache key and the args list you provide. By default the args
+lists are compared using the `===` comparison. You can override this using the options object's
+`shouldRefreshData` property, which should be a function that takes two arrays of arguments and returns
+whether they are different enough to merit a refresh.
 
 ### Cache Keys
 
-Because the hooks work by hanging their Promises and generators in the rig while they resolve, you need
-to provide the hooks with a cache-key that describes their _purpose._
+Because the hooks work by hanging their Promises and results in the rig, you need to provide a
+cache-key that describes each hook's _purpose._ This is to avoid collisions between two accesses
+of the same data source with different parameters.
 
 For example, let's imagine a simple social app. Consider the following four suspensions involved in rendering a profile page:
 
@@ -227,7 +242,7 @@ For example, let's imagine a simple social app. Consider the following four susp
 3. Fetching the target profile to be displayed.
 4. Fetching the posts owned by the target profile to be displayed.
 
-In this sample case, we should use 3 unique cache keys: a shared one for 1 and 2, and then unique ones for 3 and 4. This is because suspensions 1 and 2 will always make the same data request with **the same parameters**, so they will always return the same data. Suspensions 2 and 3, though, might use different parameters if you're viewing someone else's profile page, so they should use distinct cacheKeys so they don't overwrite each others' values. Finally, even though suspensions 3 and 4 will probably have the same parameters (`{target: targetUserId}`), they are fetching different kinds of data. So, they should have different cacheKeys from each other as well.
+In this sample case, we should use 3 unique cache keys: a shared one for 1 and 2, and then unique ones for 3 and 4. This is because suspensions 1 and 2 will always make the same data request with **the same parameters**, so they will always return the same data. Suspensions 2 and 3, though, might use different parameters if you're viewing someone else's profile page, so they should use distinct cacheKeys to avoid overwriting each others' values. Finally, even though suspensions 3 and 4 will probably have the same parameters (`{target: targetUserId}`), they are fetching different kinds of data. So, they should have different cacheKeys from each other as well.
 
 <!-- _For more examples, please refer to the [Documentation](https://example.com)_ -->
 
@@ -281,6 +296,7 @@ Project Link: [https://github.com/zackdotcomputer/suspension](https://github.com
 - [Best Readme Template](https://github.com/othneildrew/Best-README-Template)
 - [Img Shields](https://shields.io)
 - [Prettycons](https://thenounproject.com/andrei.manolache7/)
+- Though not a fork, Suspension is nonetheless building on the conceptual foundation laid by the [use-async-resource](https://github.com/andreiduca/use-async-resource) package and I'd be remiss not to acknolwedge that project.
 
 <!-- MARKDOWN LINKS & IMAGES -->
 <!-- https://www.markdownguide.org/basic-syntax/#reference-style-links -->

example/index.tsx

@@ -33,8 +33,14 @@ const PokeInfo = ({ pokemonNumber }: { pokemonNumber: number }) => {
   );
 };
 
-const PokeForm = ({ onDoLoad }: { onDoLoad: (no: number) => void }) => {
-  const [pokeNumber, setPokeNumber] = React.useState<number>(25);
+const PokeForm = ({
+  initialPokeNumber,
+  onDoLoad
+}: {
+  initialPokeNumber?: number;
+  onDoLoad: (no: number) => void;
+}) => {
+  const [pokeNumber, setPokeNumber] = React.useState<number>(initialPokeNumber ?? 25);
 
   return (
     <div>
@@ -98,7 +104,10 @@ const App = () => {
       >
         <PokeInfo pokemonNumber={renderedPokeNumber} />
         <br />
-        <PokeForm onDoLoad={(n) => setRenderedPokeNumber(n)} />
+        <PokeForm
+          onDoLoad={(n) => setRenderedPokeNumber(n)}
+          initialPokeNumber={renderedPokeNumber}
+        />
       </SuspensionRig>
     </main>
   );

src/@types/LazySuspendableResult.ts

@@ -0,0 +1,16 @@
+import FunctionWithArgs from "./FunctionWithArgs";
+
+/**
+ * The result of a lazy suspension call is an array with two elements.
+ * - The first one is your lazy reader function. It will return the value if it has
+ *   been cached successfully with the provided args, undefined if it hasn't been,
+ *   or it will throw a promise or error if the attempt is in a loading or error
+ *   state.
+ * - The second element is the active reader function. It is the same as the lazy
+ *   reader except that the unstarted and failed cases (undefined and thrown Error)
+ *   will instead start a new call to your generator and throw the resulting promise.
+ */
+export type LazySuspensionReaders<Result, Args extends any[] = []> = [
+  FunctionWithArgs<Args, Result | undefined>,
+  FunctionWithArgs<Args, Result>
+];

src/@types/LazySuspensionReaders.ts

@@ -7,5 +7,5 @@ export type {
   UnstartedCallState
 } from "./CallState";
 export type { default as FunctionWithArgs } from "./FunctionWithArgs";
-export type { LazySuspendableResult } from "./LazySuspendableResult";
+export type { LazySuspensionReaders } from "./LazySuspensionReaders";
 export type { Suspendable, SuspendableWithArgs } from "./Suspendable";

src/@types/index.ts

@@ -56,11 +56,9 @@ export default function SuspensionRig({ children, fallback, errorBoundary }: Pro
     children
   );
 
-  console.debug("Error", errorBoundary);
   const errorWrapping =
     errorBoundary !== undefined ? (
       <>
-        <div>errrrrr</div>
         <ErrorBoundary {...errorBoundary}>{suspenseWrapping}</ErrorBoundary>
       </>
     ) : (