Add controller.expireAll() that sets all responses to *STALE*

Author: ntucker

.changeset/cool-dryers-change.md

@@ -0,0 +1,5 @@
+---
+'@data-client/react': patch
+---
+
+Update README examples to have more options configured

.changeset/many-pears-explain.md

@@ -0,0 +1,18 @@
+---
+'@data-client/react': minor
+'@data-client/core': minor
+'@rest-hooks/core': minor
+'@rest-hooks/react': minor
+---
+
+Add controller.expireAll() that sets all responses to *STALE*
+
+```ts
+controller.expireAll(ArticleResource.getList);
+```
+
+This is like controller.invalidateAll(); but will continue showing
+stale data while it is refetched.
+
+This is sometimes useful to trigger refresh of only data presently shown
+when there are many parameterizations in cache.

README.md

@@ -73,11 +73,16 @@ class Article extends Entity {
 const UserResource = createResource({
   path: '/users/:id',
   schema: User,
+  optimistic: true,
 });
 
 const ArticleResource = createResource({
   path: '/articles/:id',
   schema: Article,
+  searchParams: {} as
+    | { beginAt?: string; endAt?: string; author?: string }
+    | undefined,
+  optimistic: true,
 });
 ```
 
@@ -86,12 +91,12 @@ const ArticleResource = createResource({
 ```tsx
 const article = useSuspense(ArticleResource.get, { id });
 return (
-  <>
+  <article>
     <h2>
       {article.title} by {article.author.username}
     </h2>
     <p>{article.body}</p>
-  </>
+  </article>
 );
 ```
 

docs/core/api/Controller.md

@@ -24,7 +24,7 @@ class Controller {
   subscribe(endpoint, ...args): Promise<void>;
   unsubscribe(endpoint, ...args): Promise<void>;
   /*************** Data Access ***************/
-  getResponse(endpoint, ...args, state): { data, expiryStatus, expiresAt };
+  getResponse(endpoint, ...args, state): { data; expiryStatus; expiresAt };
   getError(endpoint, ...args, state): ErrorTypes | undefined;
   snapshot(state: State<unknown>, fetchedAt?: number): SnapshotInterface;
   getState(): State<unknown>;
@@ -56,7 +56,9 @@ function CreatePost() {
 
   return (
     <form
-      onSubmit={e => ctrl.fetch(PostResource.getList.push, new FormData(e.target))}
+      onSubmit={e =>
+        ctrl.fetch(PostResource.getList.push, new FormData(e.target))
+      }
     >
       {/* ... */}
     </form>
@@ -141,6 +143,44 @@ post.pk();
 - Identical requests are deduplicated globally; allowing only one inflight request at a time.
   - To ensure a _new_ request is started, make sure to abort any existing inflight requests.
 
+## expireAll({ testKey }) {#expireAll}
+
+Sets all responses' [expiry status](../concepts/expiry-policy.md) matching `testKey` to [Stale](../concepts/expiry-policy.md#stale).
+
+This is sometimes useful to trigger refresh of only data presently shown
+when there are many parameterizations in cache.
+
+```tsx
+import { type Controller, useController } from '@data-client/react';
+
+const createTradeHandler = (ctrl: Controller) => async trade => {
+  await ctrl.fetch(TradeResource.getList.push({ user: user.id }, trade));
+  // highlight-start
+  ctrl.expireAll(AccountResource.get);
+  ctrl.expireAll(AccountResource.getList);
+  // highlight-end
+};
+
+function CreateTrade({ id }: { id: string }) {
+  const handleTrade = createTradeHandler(useController());
+
+  return (
+    <Form onSubmit={handleTrade}>
+      <FormField name="ticker" />
+      <FormField name="amount" type="number" />
+      <FormField name="price" type="number" />
+    </Form>
+  );
+}
+```
+
+:::tip
+
+To reduce load, improve performance, and improve state consistency; it can often be
+better to [include mutation sideeffects in the mutation response](/rest/guides/rpc).
+
+:::
+
 ## invalidate(endpoint, ...args) {#invalidate}
 
 Forces refetching and suspense on [useSuspense](./useSuspense.md) with the same Endpoint
@@ -162,7 +202,7 @@ function ArticleName({ id }: { id: string }) {
 
 :::tip
 
-To refresh while continuing to display stale data - [Controller.fetch](#fetch) instead.
+To refresh while continuing to display stale data - [Controller.fetch](#fetch).
 
 :::
 
@@ -176,7 +216,7 @@ For REST try using [Resource.delete](/rest/api/createResource#delete)
 // deletes MyResource(5)
 // this will resuspend MyResource.get({id: '5'})
 // and remove it from MyResource.getList
-controller.setResponse(MyResource.delete, { id: '5' }, { id: '5' })
+controller.setResponse(MyResource.delete, { id: '5' }, { id: '5' });
 ```
 
 :::
@@ -199,6 +239,12 @@ function ArticleName({ id }: { id: string }) {
 }
 ```
 
+:::tip
+
+To refresh while continuing to display stale data - [Controller.expireAll](#expireAll) instead.
+
+:::
+
 Here we clear only GET endpoints using the test.com domain. This means other domains remain in cache.
 
 ```tsx
@@ -227,7 +273,7 @@ const managers = [
       // call custom unAuth function we defined
       unAuth();
       // still reset the store
-      controller.invalidateAll({ testKey })
+      controller.invalidateAll({ testKey });
     },
   }),
   ...CacheProvider.defaultProps.managers,
@@ -240,7 +286,6 @@ ReactDOM.createRoot(document.body).render(
 );
 ```
 
-
 ## resetEntireStore() {#resetEntireStore}
 
 Resets/clears the entire Reactive Data Client cache. All inflight requests will not resolve.

packages/core/src/actionTypes.ts

@@ -8,4 +8,5 @@ export const SUBSCRIBE_TYPE = 'rest-hooks/subscribe' as const;
 export const UNSUBSCRIBE_TYPE = 'rest-hook/unsubscribe' as const;
 export const INVALIDATE_TYPE = 'rest-hooks/invalidate' as const;
 export const INVALIDATEALL_TYPE = 'rest-hooks/invalidateall' as const;
+export const EXPIREALL_TYPE = 'rest-hooks/expireall' as const;
 export const GC_TYPE = 'rest-hooks/gc' as const;

packages/core/src/controller/Controller.ts

@@ -19,6 +19,7 @@ import {
 } from '@data-client/normalizr';
 import { inferResults, validateInference } from '@data-client/normalizr';
 
+import createExpireAll from './createExpireAll.js';
 import createFetch from './createFetch.js';
 import createInvalidate from './createInvalidate.js';
 import createInvalidateAll from './createInvalidateAll.js';
@@ -136,10 +137,19 @@ export default class Controller<
   /**
    * Forces refetching and suspense on useSuspense on all matching endpoint result keys.
    * @see https://resthooks.io/docs/api/Controller#invalidateAll
+   * @returns Promise that resolves when invalidation is commited.
    */
   invalidateAll = (options: { testKey: (key: string) => boolean }) =>
     this.dispatch(createInvalidateAll((key: string) => options.testKey(key)));
 
+  /**
+   * Sets all matching endpoint result keys to be STALE.
+   * @see https://dataclient.io/docs/api/Controller#expireAll
+   * @returns Promise that resolves when expiry is commited. *NOT* fetch promise
+   */
+  expireAll = (options: { testKey: (key: string) => boolean }) =>
+    this.dispatch(createExpireAll((key: string) => options.testKey(key)));
+
   /**
    * Resets the entire Rest Hooks cache. All inflight requests will not resolve.
    * @see https://resthooks.io/docs/api/Controller#resetEntireStore

packages/core/src/controller/createExpireAll.ts

@@ -0,0 +1,11 @@
+import { EXPIREALL_TYPE } from '../actionTypes.js';
+import type { ExpireAllAction } from '../types.js';
+
+export default function createExpireAll(
+  testKey: (key: string) => boolean,
+): ExpireAllAction {
+  return {
+    type: EXPIREALL_TYPE,
+    testKey,
+  };
+}

packages/core/src/newActions.ts

@@ -14,6 +14,7 @@ import type {
   GC_TYPE,
   OPTIMISTIC_TYPE,
   INVALIDATEALL_TYPE,
+  EXPIREALL_TYPE,
 } from './actionTypes.js';
 import type { EndpointUpdateFunction } from './controller/types.js';
 
@@ -112,6 +113,12 @@ export interface UnsubscribeAction<
   };
 }
 
+/* EXPIRY */
+export interface ExpireAllAction {
+  type: typeof EXPIREALL_TYPE;
+  testKey: (key: string) => boolean;
+}
+
 /* INVALIDATE */
 export interface InvalidateAllAction {
   type: typeof INVALIDATEALL_TYPE;
@@ -146,5 +153,6 @@ export type ActionTypes =
   | UnsubscribeAction
   | InvalidateAction
   | InvalidateAllAction
+  | ExpireAllAction
   | ResetAction
   | GCAction;

packages/core/src/state/reducer/createReducer.ts

@@ -1,3 +1,4 @@
+import { expireReducer } from './expireReducer.js';
 import { fetchReducer } from './fetchReducer.js';
 import { invalidateReducer } from './invalidateReducer.js';
 import { setReducer } from './setReducer.js';
@@ -9,6 +10,7 @@ import {
   GC_TYPE,
   OPTIMISTIC_TYPE,
   INVALIDATEALL_TYPE,
+  EXPIREALL_TYPE,
 } from '../../actionTypes.js';
 import type Controller from '../../controller/Controller.js';
 import type { ActionTypes, State } from '../../types.js';
@@ -43,6 +45,9 @@ export default function createReducer(controller: Controller): ReducerType {
       case INVALIDATE_TYPE:
         return invalidateReducer(state, action);
 
+      case EXPIREALL_TYPE:
+        return expireReducer(state, action);
+
       case RESET_TYPE:
         return { ...initialState, lastReset: action.date };
 

packages/core/src/state/reducer/expireReducer.ts

@@ -0,0 +1,20 @@
+import type { State, ExpireAllAction } from '../../types.js';
+
+export function expireReducer(state: State<unknown>, action: ExpireAllAction) {
+  const meta = { ...state.meta };
+
+  Object.keys(meta).forEach(key => {
+    if (action.testKey(key)) {
+      meta[key] = {
+        ...meta[key],
+        // 1 instead of 0 so we can do 'falsy' checks to see if it is set
+        expiresAt: 1,
+      };
+    }
+  });
+
+  return {
+    ...state,
+    meta,
+  };
+}