docs: Add Action examples

reactive · Dec 22, 2024 · 0c39da0 · 0c39da0
1 parent 113b2c9
commit 0c39da0
Show file tree

Hide file tree

Showing 3 changed files with 189 additions and 14 deletions.
diff --git a/docs/core/api/Actions.md b/docs/core/api/Actions.md
@@ -1,13 +1,18 @@
 ---
-title: Flux Actions
+title: Actions communicate UI events to store updates
 sidebar_label: Actions
 ---
 
+import Grid from '@site/src/components/Grid';
+
 # Actions
 
-Actions are minimal descriptions of something that happened in the application.
+Actions are minimal descriptions of store updates.
 
-They can be [read and consumed by Manager middleware](./Manager.md#reading-and-consuming-actions).
+They are [dispatched by Controller methods](./Controller.md#action-dispatchers) ->
+[read and consumed by Manager middleware](./Manager.md#reading-and-consuming-actions) -> 
+processed by [reducers](https://react.dev/reference/react/useReducer) registered with [DataProvider](./DataProvider.md)
+to update the store's state.
 
 Many actions use the same meta information:
 
@@ -21,6 +26,8 @@ interface ActionMeta {
 
 ## FETCH
 
+<Grid wrap>
+
 ```ts
 interface FetchMeta {
   fetchedAt: number;
@@ -38,11 +45,36 @@ interface FetchAction {
 }
 ```
 
-Comes from [Controller.fetch()](./Controller.md#fetch), [Controller.fetchIfStale()](./Controller.md#fetchIfStale),
+```js
+{
+  type: 'rdc/fetch',
+  key: 'GET https://jsonplaceholder.typicode.com/todos?userId=1',
+  args: [
+    {
+      userId: 1
+    }
+  ],
+  endpoint: Endpoint('User.getList'),
+  meta: {
+    fetchedAt: '5:09:41.975 PM',
+    resolve: function (){},
+    reject: function (){},
+    promise: {}
+  }
+}
+```
+
+</Grid>
+
+Sent by [Controller.fetch()](./Controller.md#fetch), [Controller.fetchIfStale()](./Controller.md#fetchIfStale),
 [useSuspense()](./useSuspense.md), [useDLE()](./useDLE.md), [useLive()](./useLive.md), [useFetch()](./useFetch.md)
 
+Read by [NetworkManager](./NetworkManager.md)
+
 ## SET
 
+<Grid wrap>
+
 ```ts
 interface SetAction {
   type: typeof actionTypes.SET;
@@ -53,10 +85,37 @@ interface SetAction {
 }
 ```
 
-Comes from [Controller.set()](./Controller.md#set)
+```js
+{
+  type: 'rdc/set',
+  value: {
+    userId: 1,
+    id: 1,
+    title: 'delectus aut autem',
+    completed: true
+  },
+  args: [
+    {
+      id: 1
+    }
+  ],
+  schema: Todo,
+  meta: {
+    fetchedAt: '5:18:26.394 PM',
+    date: '5:18:26.636 PM',
+    expiresAt: '6:18:26.636 PM'
+  }
+}
+```
+
+</Grid>
+
+Sent by [Controller.set()](./Controller.md#set)
 
 ## SET_RESPONSE
 
+<Grid wrap>
+
 ```ts
 interface SetResponseAction {
   type: typeof actionTypes.SET_RESPONSE;
@@ -69,21 +128,68 @@ interface SetResponseAction {
 }
 ```
 
-Comes from [Controller.setResponse()](./Controller.md#setResponse), [NetworkManager](./NetworkManager.md)
+```js
+{
+  type: 'rdc/setresponse',
+  key: 'PATCH https://jsonplaceholder.typicode.com/todos/1',
+  response: {
+    userId: 1,
+    id: 1,
+    title: 'delectus aut autem',
+    completed: true
+  },
+  args: [
+    {
+      id: 1
+    },
+    {
+      completed: true
+    }
+  ],
+  endpoint: Endpont('Todo.partialUpdate'),
+  meta: {
+    fetchedAt: '5:18:26.394 PM',
+    date: '5:18:26.636 PM',
+    expiresAt: '6:18:26.636 PM'
+  },
+  error: false
+}
+```
+
+</Grid>
+
+Sent by [Controller.setResponse()](./Controller.md#setResponse), [NetworkManager](./NetworkManager.md)
+
+Read by [NetworkManager](./NetworkManager.md), [LogoutManager](./LogoutManager.md)
 
 ## RESET
 
+<Grid wrap>
+
 ```ts
 interface ResetAction {
   type: typeof actionTypes.RESET;
   date: number;
 }
 ```
 
-Comes from [Controller.resetEntireStore()](./Controller.md#resetEntireStore)
+```js
+{
+  type: 'rdc/reset',
+  date: '5:09:41.975 PM',
+}
+```
+
+</Grid>
+
+Sent by [Controller.resetEntireStore()](./Controller.md#resetEntireStore)
+
+Read by [NetworkManager](./NetworkManager.md)
 
 ## SUBSCRIBE
 
+<Grid wrap>
+
 ```ts
 interface SubscribeAction {
   type: typeof actionTypes.SUBSCRIBE;
@@ -93,10 +199,29 @@ interface SubscribeAction {
 }
 ```
 
-Comes from [Controller.subscribe()](./Controller.md#subscribe), [useSubscription()](./useSubscription.md), [useLive()](./useLive.md)
+```js
+{
+  type: 'rdc/subscribe',
+  key: 'GET https://api.exchange.coinbase.com/products/BTC-USD/ticker',
+  args: [
+    {
+      product_id: 'BTC-USD'
+    }
+  ],
+  endpoint: Endpoint('https://api.exchange.coinbase.com/products/:product_id/ticker'),
+}
+```
+
+</Grid>
+
+Sent by [Controller.subscribe()](./Controller.md#subscribe), [useSubscription()](./useSubscription.md), [useLive()](./useLive.md)
+
+Read by [SubscriptionManager](./SubscriptionManager.md)
 
 ## UNSUBSCRIBE
 
+<Grid wrap>
+
 ```ts
 interface UnsubscribeAction {
   type: typeof actionTypes.UNSUBSCRIBE;
@@ -106,38 +231,88 @@ interface UnsubscribeAction {
 }
 ```
 
-Comes from [Controller.unsubscribe()](./Controller.md#unsubscribe), [useSubscription()](./useSubscription.md), [useLive()](./useLive.md)
+```js
+{
+  type: 'rdc/unsubscribe',
+  key: 'GET https://api.exchange.coinbase.com/products/BTC-USD/ticker',
+  args: [
+    {
+      product_id: 'BTC-USD'
+    }
+  ],
+  endpoint: Endpoint('https://api.exchange.coinbase.com/products/:product_id/ticker'),
+}
+```
+
+</Grid>
+
+Sent by [Controller.unsubscribe()](./Controller.md#unsubscribe), [useSubscription()](./useSubscription.md), [useLive()](./useLive.md)
+
+Read by [SubscriptionManager](./SubscriptionManager.md)
 
 ## INVALIDATE
 
+<Grid wrap>
+
 ```ts
 interface InvalidateAction {
   type: typeof actionTypes.INVALIDATE;
   key: string;
 }
 ```
 
-Comes from [Controller.invalidate()](./Controller.md#invalidate)
+```js
+{
+  type: 'rdc/invalidate',
+  key: 'GET https://jsonplaceholder.typicode.com/todos?userId=1',
+}
+```
+
+</Grid>
+
+Sent by [Controller.invalidate()](./Controller.md#invalidate)
 
 ## INVALIDATEALL
 
+<Grid wrap>
+
 ```ts
 interface InvalidateAllAction {
   type: typeof actionTypes.INVALIDATEALL;
   testKey: (key: string) => boolean;
 }
 ```
 
-Comes from [Controller.invalidateAll()](./Controller.md#invalidateAll)
+```js
+{
+  type: 'rdc/invalidateall',
+  testKey: Endpoint('User.getList'),
+}
+```
+
+</Grid>
+
+Sent by [Controller.invalidateAll()](./Controller.md#invalidateAll)
 
 ## EXPIREALL
 
+<Grid wrap>
+
 ```ts
 interface ExpireAllAction {
   type: typeof actionTypes.EXPIREALL;
   testKey: (key: string) => boolean;
 }
 ```
 
-Comes from [Controller.expireAll()](./Controller.md#expireAll)
+```js
+{
+  type: 'rdc/expireall',
+  testKey: Endpoint('User.getList'),
+}
+```
+
+</Grid>
+
+Sent by [Controller.expireAll()](./Controller.md#expireAll)
 
diff --git a/docs/core/api/Controller.md b/docs/core/api/Controller.md
@@ -497,7 +497,7 @@ Gets the (globally referentially stable) response for a given endpoint/args pair
 
 The denormalize response data. Guarantees global referential stability for all members.
 
-#### expiryStatus
+#### [expiryStatus](../concepts/expiry-policy.md#expiry-status)
 
 ```ts
 export enum ExpiryStatus {

diff --git a/docs/core/api/Snapshot.md b/docs/core/api/Snapshot.md
@@ -57,7 +57,7 @@ Gets the (globally referentially stable) response for a given endpoint/args pair
 
 The denormalize response data. Guarantees global referential stability for all members.
 
-#### expiryStatus
+#### [expiryStatus](../concepts/expiry-policy.md#expiry-status)
 
 ```ts
 export enum ExpiryStatus {