docs: Add control flow diagrams (#2244)

docs/graphql/api/Array.md

@@ -10,8 +10,8 @@ import TabItem from '@theme/TabItem';
 import LanguageTabs from '@site/src/components/LanguageTabs';
 import HooksPlayground from '@site/src/components/HooksPlayground';
 
-Creates a schema to normalize an array of schemas. If the input value is an `Object` instead of an `Array`,
-the normalized result will be an `Array` of the `Object`'s values.
+Creates a schema to normalize an array of schemas. If the input value is an [Object](./Object.md) instead of an `Array`,
+the normalized result will be an `Array` of the [Object](./Object.md)'s values.
 
 _Note: The same behavior can be defined with shorthand syntax: `[ mySchema ]`_
 
@@ -21,6 +21,12 @@ _Note: The same behavior can be defined with shorthand syntax: `[ mySchema ]`_
   _ `value`: The input value of the entity.
   _ `parent`: The parent object of the input array. \* `key`: The key at which the input array appears on the parent object.
 
+:::tip
+
+For unbounded collections with `string` keys, use [schema.Values](./Values.md)
+
+:::
+
 ## Instance Methods
 
 - `define(definition)`: When used, the `definition` passed in will be merged with the original definition passed to the `Array` constructor. This method tends to be useful for creating circular references in schema.
@@ -62,11 +68,15 @@ render(<UsersPage />);
 
 </HooksPlayground>
 
-### Dynamic entity types
+### Polymorphic types
 
 If your input data is an array of more than one type of entity, it is necessary to define a schema mapping.
 
-_Note: If your data returns an object that you did not provide a mapping for, the original object will be returned in the result and an entity will not be created._
+:::note
+
+If your data returns an object that you did not provide a mapping for, the original object will be returned in the result and an entity will not be created.
+
+:::
 
 #### string schemaAttribute
 

docs/graphql/api/Entity.md

@@ -60,8 +60,48 @@ each row represents an instance of the Entity.
 By defining a `pk()` member, Rest Hooks will normalize entities, ensuring consistency and improve performance
 by increasing cache hit rates.
 
-> For common REST patterns, inheriting from [Resource](/rest/api/resource) is recommended. However, for other cases
-> `Entity` is a great place to start.
+:::tip
+
+Entities are bound to Endpoints using [GQLEndpoint.schema](./GQLEndpoint.md#schema)
+
+:::
+
+## Data lifecycle
+
+```mermaid
+flowchart BT
+  subgraph getResponse
+    pk2("pk()")-->denormalize
+    subgraph denormalize
+      direction TB
+      validate2("validate()")---fromJS("fromJS()")
+      fromJS---denormNest("denormalize(this.schema)")
+    end
+  end
+  subgraph receive
+    direction TB
+    subgraph normalize
+      direction TB
+      process("process()")-->pk("pk()")
+      pk---validate("validate()")
+      process-->validate
+      validate---normNest("normalize(this.schema)")
+    end
+    process-->useincoming("useIncoming()")
+    useincoming-->merge("merge()")
+    process-->merge
+    process-->expiresAt("expiresAt()")
+  end
+  click process "#process"
+  click pk "#pk"
+  click pk2 "#pk"
+  click fromJS "#fromJS"
+  click validate "#validate"
+  click validate2 "#validate"
+  click expiresAt "#expiresat"
+  click useincoming "#useincoming"
+  click merge "#merge"
+```
 
 ## Methods
 

docs/graphql/api/Object.md

@@ -13,6 +13,12 @@ Define a plain object mapping that has values needing to be normalized into Enti
 - `definition`: **required** A definition of the nested entities found within this object. Defaults to empty object.
   You _do not_ need to define any keys in your object other than those that hold other entities. All other values will be copied to the normalized output.
 
+:::tip
+
+`Objects` have statically known members. For unbounded Objects (aribtrary `string` keys), use [schema.Values](./Values.md)
+
+:::
+
 #### Instance Methods
 
 - `define(definition)`: When used, the `definition` passed in will be merged with the original definition passed to the `Object` constructor. This method tends to be useful for creating circular references in schema.

docs/graphql/api/Union.md

@@ -8,7 +8,7 @@ title: schema.Union
 import LanguageTabs from '@site/src/components/LanguageTabs';
 import HooksPlayground from '@site/src/components/HooksPlayground';
 
-Describe a schema which is a union of multiple schemas. This is useful if you need the polymorphic behavior provided by `schema.Array` or `schema.Values` but for non-collection fields.
+Describe a schema which is a union of multiple schemas. This is useful if you need the polymorphic behavior provided by [schema.Array](./Array.md) or [schema.Values](./Values.md) but for non-collection fields.
 
 - `definition`: **required** An object mapping the definition of the nested entities found within the input array
 - `schemaAttribute`: **required** The attribute on each entity found that defines what schema, per the definition mapping, to use when normalizing.
@@ -23,7 +23,11 @@ Describe a schema which is a union of multiple schemas. This is useful if you ne
 
 ## Usage
 
-_Note: If your data returns an object that you did not provide a mapping for, the original object will be returned in the result and an entity will not be created._
+:::note
+
+If your data returns an object that you did not provide a mapping for, the original object will be returned in the result and an entity will not be created.
+
+:::
 
 <HooksPlayground groupId="schema" defaultOpen="y">
 

docs/graphql/api/Values.md

@@ -50,11 +50,15 @@ render(<ItemPage />);
 
 </HooksPlayground>
 
-### Dynamic entity types
+### Polymorphic types
 
-If your input data is an object that has values of more than one type of entity, but their schema is not easily defined by the key, you can use a mapping of schema, much like `schema.Union` and `schema.Array`.
+If your input data is an object that has values of more than one type of entity, but their schema is not easily defined by the key, you can use a mapping of schema, much like [schema.Union](./Union.md) and [schema.Array](./Array.md).
 
-_Note: If your data returns an object that you did not provide a mapping for, the original object will be returned in the result and an entity will not be created._
+:::note
+
+If your data returns an object that you did not provide a mapping for, the original object will be returned in the result and an entity will not be created.
+
+:::
 
 #### string schemaAttribute
 

docs/rest/api/Array.md

@@ -12,8 +12,8 @@ import LanguageTabs from '@site/src/components/LanguageTabs';
 import HooksPlayground from '@site/src/components/HooksPlayground';
 import { RestEndpoint } from '@rest-hooks/rest';
 
-Creates a schema to normalize an array of schemas. If the input value is an `Object` instead of an `Array`,
-the normalized result will be an `Array` of the `Object`'s values.
+Creates a schema to normalize an array of schemas. If the input value is an [Object](./Object.md) instead of an `Array`,
+the normalized result will be an `Array` of the [Object](./Object.md)'s values.
 
 _Note: The same behavior can be defined with shorthand syntax: `[ mySchema ]`_
 
@@ -23,6 +23,12 @@ _Note: The same behavior can be defined with shorthand syntax: `[ mySchema ]`_
   _ `value`: The input value of the entity.
   _ `parent`: The parent object of the input array. \* `key`: The key at which the input array appears on the parent object.
 
+:::tip
+
+For unbounded collections with `string` keys, use [schema.Values](./Values.md)
+
+:::
+
 ## Instance Methods
 
 - `define(definition)`: When used, the `definition` passed in will be merged with the original definition passed to the `Array` constructor. This method tends to be useful for creating circular references in schema.
@@ -70,11 +76,15 @@ render(<UsersPage />);
 
 </HooksPlayground>
 
-### Dynamic entity types
+### Polymorphic types
 
 If your input data is an array of more than one type of entity, it is necessary to define a schema mapping.
 
-_Note: If your data returns an object that you did not provide a mapping for, the original object will be returned in the result and an entity will not be created._
+:::note
+
+If your data returns an object that you did not provide a mapping for, the original object will be returned in the result and an entity will not be created.
+
+:::
 
 #### string schemaAttribute
 

docs/rest/api/Endpoint.md

@@ -104,6 +104,73 @@ or [getImage](/docs/guides/img-media#just-images) instead.
 
 :::
 
+## Lifecycle
+
+### Success
+
+```mermaid
+flowchart LR
+  subgraph Controller.fetch
+    direction TB
+    key--->dispatch("dispatch(FETCH)")
+  end
+  subgraph managers
+    NetworkManager-->endpoint("endpoint(...args)")
+    endpoint--resolves-->Controller.resolve
+    Controller.resolve(Controller.resolve)-->dispatchR("dispatch(RECEIVE)")
+  end
+  managers--FETCH-->reducer:FETCH
+  Controller.fetch--FETCH-->managers
+  subgraph reducer:FETCH
+    getOptimisticResponse("?getOptimisticResponse()")-->RECIEVE
+    subgraph RECIEVE
+      normalize(normalize)-->update("update()")
+    end
+  end
+  subgraph reducer:RECEIVE
+    normalize2(normalize)-->update2("update()")
+  end
+  managers--RECEIVE-->reducer:RECEIVE
+  click key "#key"
+  click NetworkManager /docs/api/NetworkManager
+  click getOptimisticResponse #getoptimisticresponse
+  click update #update
+  click update2 #update
+```
+
+### Error
+
+```mermaid
+flowchart LR
+  subgraph Controller.fetch
+    direction TB
+    key--->dispatch("dispatch(FETCH)")
+  end
+  subgraph managers
+    NetworkManager-->endpoint("endpoint(...args)")
+    endpoint--rejects-->Controller.resolve
+    Controller.resolve(Controller.resolve)-->dispatchR("dispatch(RECEIVE)")
+  end
+  managers--FETCH-->reducer:FETCH
+  Controller.fetch--FETCH-->managers
+  subgraph reducer:FETCH
+    getOptimisticResponse("?getOptimisticResponse()")-->RECIEVE
+    subgraph RECIEVE
+      normalize(normalize)-->update("update()")
+    end
+  end
+  subgraph reducer:reduceError
+    filterOptimistic(filterOptimistic)-->errorPolicy("errorPolicy()")
+  end
+  managers--RECEIVE:error-->reducer:reduceError
+  click key "#key"
+  click NetworkManager /docs/api/NetworkManager
+  click getOptimisticResponse #getoptimisticresponse
+  click update #update
+  click errorPolicy #errorpolicy
+```
+
+
 ## Endpoint Members
 
 Members double as options (second constructor arg). While none are required, the first few
@@ -350,9 +417,9 @@ console.log(user);
 
 ### Additional
 
-- [Pagination](/rest/guides/pagination)
-- [Mocking unfinished endpoints](/rest/guides/mocking-unfinished)
-- [Optimistic updates](/docs/guides/optimistic-updates)
+- [Pagination](../guides/pagination.md)
+- [Mocking unfinished endpoints](../guides/mocking-unfinished.md)
+- [Optimistic updates](../guides/optimistic-updates.md)
 
 ## Motivation
 

docs/rest/api/Entity.md

@@ -62,8 +62,49 @@ each row represents an instance of the Entity.
 By defining a `pk()` member, Rest Hooks will normalize entities, ensuring consistency and improve performance
 by increasing cache hit rates.
 
-> For common REST patterns, inheriting from [Resource](/rest/api/resource) is recommended. However, for other cases
-> `Entity` is a great place to start.
+:::tip
+
+Entities are bound to Endpoints using [createResource.schema](./createResource.md#schema) or
+[RestEndpoint.schema](./RestEndpoint.md#schema)
+
+:::
+
+## Data lifecycle
+
+```mermaid
+flowchart BT
+  subgraph getResponse
+    pk2("pk()")-->denormalize
+    subgraph denormalize
+      direction TB
+      validate2("validate()")---fromJS("fromJS()")
+      fromJS---denormNest("denormalize(this.schema)")
+    end
+  end
+  subgraph receive
+    direction TB
+    subgraph normalize
+      direction TB
+      process("process()")-->pk("pk()")
+      pk---validate("validate()")
+      process-->validate
+      validate---normNest("normalize(this.schema)")
+    end
+    process-->useincoming("useIncoming()")
+    useincoming-->merge("merge()")
+    process-->merge
+    process-->expiresAt("expiresAt()")
+  end
+  click process "#process"
+  click pk "#pk"
+  click pk2 "#pk"
+  click fromJS "#fromJS"
+  click validate "#validate"
+  click validate2 "#validate"
+  click expiresAt "#expiresat"
+  click useincoming "#useincoming"
+  click merge "#merge"
+```
 
 ## Methods
 
@@ -211,6 +252,8 @@ will block on fetching a result.
 By **default** does some basic field existance checks in development mode only. Override to
 disable or customize.
 
+[Using validation for summary endpoints](../guides/summary-list.md)
+
 ### static infer(args, indexes, recurse): pk? {#infer}
 
 Allows Rest Hooks to build a response without having to fetch if its entities can be found.

docs/rest/api/Object.md

@@ -15,6 +15,12 @@ Define a plain object mapping that has values needing to be normalized into Enti
 - `definition`: **required** A definition of the nested entities found within this object. Defaults to empty object.
   You _do not_ need to define any keys in your object other than those that hold other entities. All other values will be copied to the normalized output.
 
+:::tip
+
+`Objects` have statically known members. For unbounded Objects (aribtrary `string` keys), use [schema.Values](./Values.md)
+
+:::
+
 #### Instance Methods
 
 - `define(definition)`: When used, the `definition` passed in will be merged with the original definition passed to the `Object` constructor. This method tends to be useful for creating circular references in schema.

docs/rest/api/RestEndpoint.md

@@ -472,6 +472,8 @@ const getUser = new RestEndpoint({
 
 ## Endpoint Life-Cycles
 
+These are inherited from [Endpoint](./Endpoint.md#lifecycle)
+
 ### dataExpiryLength?: number {#dataexpirylength}
 
 Custom data cache lifetime for the fetched resource. Will override the value set in NetworkManager.

docs/rest/api/Union.md

@@ -9,7 +9,7 @@ import LanguageTabs from '@site/src/components/LanguageTabs';
 import HooksPlayground from '@site/src/components/HooksPlayground';
 import { RestEndpoint } from '@rest-hooks/rest';
 
-Describe a schema which is a union of multiple schemas. This is useful if you need the polymorphic behavior provided by `schema.Array` or `schema.Values` but for non-collection fields.
+Describe a schema which is a union of multiple schemas. This is useful if you need the polymorphic behavior provided by [schema.Array](./Array.md) or [schema.Values](./Values.md) but for non-collection fields.
 
 - `definition`: **required** An object mapping the definition of the nested entities found within the input array
 - `schemaAttribute`: **required** The attribute on each entity found that defines what schema, per the definition mapping, to use when normalizing.
@@ -22,9 +22,19 @@ Describe a schema which is a union of multiple schemas. This is useful if you ne
 
 - `define(definition)`: When used, the `definition` passed in will be merged with the original definition passed to the `Union` constructor. This method tends to be useful for creating circular references in schema.
 
+:::info Naming
+
+`Union` is named after the [set theory concept](https://en.wikipedia.org/wiki/Union_(set_theory)) just like [TypeScript Unions](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#union-types)
+
+:::
+
 ## Usage
 
-_Note: If your data returns an object that you did not provide a mapping for, the original object will be returned in the result and an entity will not be created._
+:::note
+
+If your data returns an object that you did not provide a mapping for, the original object will be returned in the result and an entity will not be created.
+
+:::
 
 <HooksPlayground groupId="schema" defaultOpen="y" fixtures={[
 {