docs: Add subscriptions to colocate (#1175)

Author: ntucker

docs/api/Delete.md

@@ -82,7 +82,7 @@ function MyTable() {
 }
 ```
 
-### Usage with useResource()
+### Impact on useResource()
 
 When entities are deleted in a result currently being presented in React, useResource()
 will consider them invalid

docs/api/Endpoint.md

@@ -84,7 +84,7 @@ Package: [@rest-hooks/endpoint](https://www.npmjs.com/package/@rest-hooks/endpoi
 Members double as options (second constructor arg). While none are required, the first few
 have defaults.
 
-### key: (params) => string
+### key: (params) => string {#key}
 
 Serializes the parameters. This is used to build a lookup key in global stores.
 
@@ -94,13 +94,13 @@ Default:
 `${this.fetch.name} ${JSON.stringify(params)}`;
 ```
 
-### sideEffect: true | undefined
+### sideEffect: true | undefined {#sideeffect}
 
 Used to indicate endpoint might have side-effects (non-idempotent). This restricts it
 from being used with [useResource()](./useresource) or [useRetrieve()](useRetrieve) as those can hit the
 endpoint an unpredictable number of times.
 
-### schema: Schema
+### schema: Schema {#schema}
 
 Declarative definition of how to [process responses](./schema)
 
@@ -126,7 +126,7 @@ const UserDetail = new Endpoint(
 );
 ```
 
-### extend(EndpointOptions): Endpoint
+### extend(EndpointOptions): Endpoint {#extend}
 
 Can be used to further customize the endpoint definition
 

docs/api/Entity.md

@@ -110,12 +110,12 @@ pk() {
 }
 ```
 
-### static get key(): string
+### static get key(): string {#key}
 
 This defines the key for the Entity itself, rather than an instance. This needs to be a globally
 unique value.
 
-### static merge(existing, incoming): mergedValue
+### static merge(existing, incoming): mergedValue {#merge}
 
 ```typescript
 static merge<T extends typeof SimpleRecord>(existing: InstanceType<T>, incoming: InstanceType<T>) => InstanceType<T>
@@ -149,7 +149,7 @@ class LatestPriceEntity extends Entity {
 }
 ```
 
-### static indexes?: (keyof this)[]
+### static indexes?: (keyof this)[]  {#indexes}
 
 Indexes enable increased performance when doing lookups based on those parameters. Add
 fieldnames (like `slug`, `username`) to the list that you want to send as params to lookup
@@ -223,7 +223,7 @@ Nested below:
 const price = useCache(LatestPrice, { symbol: 'BTC' });
 ```
 
-### static schema: { [k: keyof this]: Schema }
+### static schema: { [k: keyof this]: Schema }  {#schema}
 
 Set this to [define entities nested](../guides/nested-response) inside this one.
 

docs/api/Manager.md

@@ -78,14 +78,35 @@ this.middleware = ({ dispatch, getState }) => (next) => async (action) => {
 ### Middleware data stream
 
 ```typescript
+import type { Manager } from '@rest-hooks/core';
 import { createReceive } from '@rest-hooks/core';
 
-this.middleware = ({ dispatch, getState }) => {
-  this.websocket.onmessage = (event) => {
-    dispatch(
-      createReceive(event.data, { schema: this.Schemas[event.type] })
-    );
+export default class StreamManager implements Manager
+{
+  protected declare middleware: Middleware;
+  protected declare websocket: Websocket;
+
+  constructor(url: string) {
+    this.websocket = new Websocket(url);
+
+    // highlight-start
+    this.middleware = ({ dispatch, getState }) => {
+      this.websocket.onmessage = (event) => {
+        dispatch(
+          createReceive(event.data, { schema: this.Schemas[event.type] })
+        );
+      }
+      return (next) => async (action) => next(action);
+    }
+    // highlight-end
+  }
+
+  cleanup() {
+    this.websocket.close();
+  }
+
+  getMiddleware<T extends StreamManager>(this: T) {
+    return this.middleware;
   }
-  return (next) => async (action) => next(action);
 }
 ```

docs/getting-started/data-dependency.md

@@ -182,3 +182,70 @@ export default function TodoDetail({ id }: { id: number }) {
 ```
 
 Read more about [useStatefulResource](../guides/no-suspense)
+
+## Subscriptions
+
+When data is likely to change due to external factor; [useSubscription()](../api/useSubscription.md)
+ensures continual updates while a component is mounted.
+
+<Tabs
+defaultValue="Single"
+values={[
+{ label: 'Single', value: 'Single' },
+{ label: 'List', value: 'List' },
+]}>
+<TabItem value="Single">
+
+```tsx
+import { useResource } from 'rest-hooks';
+// local directory for API definitions
+import { todoDetail } from 'endpoints/todo';
+
+export default function TodoDetail({ id }: { id: number }) {
+  const todo = useResource(todoDetail, { id });
+  // highlight-next-line
+  useSubscription(todoDetail, { id });
+  return <div>{todo.title}</div>;
+}
+```
+
+</TabItem>
+<TabItem value="List">
+
+```tsx
+import { useResource } from 'rest-hooks';
+// local directory for API definitions
+import { todoList } from 'endpoints/todo';
+
+export default function TodoList() {
+  const todos = useResource(todoList, {});
+  // highlight-next-line
+  useSubscription(todoList, {});
+  return (
+    <section>
+      {todos.map(todo => (
+        <div key={todo.id}>{todo.title}</div>
+      ))}
+    </section>
+  );
+}
+```
+
+</TabItem>
+</Tabs>
+
+Subscriptions are orchestrated by [Managers](../api/Manager.md). Out of the box,
+polling based subscriptions can be used by adding [pollFrequency](../api/Endpoint.md#pollfrequency-number) to an endpoint.
+For pushed based networking protocols like websockets, see the [example websocket stream manager](../api/Manager.md#middleware-data-stream).
+
+```typescript
+const fetchTodoDetail = ({ id }) =>
+  fetch(`https://jsonplaceholder.typicode.com/todos/${id}`).then(res =>
+    res.json(),
+  );
+const todoDetail = new Endpoint(
+  fetchTodoDetail,
+  // highlight-next-line
+  { pollFrequency: 1000 },
+);
+```

docs/getting-started/entity.md

@@ -2,6 +2,7 @@
 title: Entity and Data Normalization
 sidebar_label: Entity
 ---
+
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 import LanguageTabs from '@site/src/components/LanguageTabs';
@@ -103,12 +104,24 @@ export function PresentationsPage() {
 </TabItem>
 </Tabs>
 
+Extracting entities from a response is known as `normalization`. Accessing a response reverses
+the process via `denormalization`.
+
+:::info Global Referential Equality
+
 Using entities expands Rest Hooks' global referential equality guarantee beyond the granularity of
 an entire endpoint response.
 
+:::
+
 ## Mutations and Dynamic Data
 
-Be sure to include *any* data that has changed in your response.
+When an endpoint changes data, this is known as a [side effect](../guides/rpc.md). Marking an endpoint with [sideEffect: true](../api/Endpoint.md#sideeffect)
+tells Rest Hooks that this endpoint is not idempotent, and thus should not be allowed in hooks
+that may call the endpoint an arbitrary number of times like [useResource()](../api/useResource.md) or [useRetrieve()](../api/useRetrieve.md)
+
+By including the changed data in the endpoint's response, Rest Hooks is able to able to update
+any entities it extracts by specifying the schema.
 
 <Tabs
 defaultValue="Create"
@@ -223,8 +236,11 @@ export default function TodoWithDelete({ todo }: { todo: Todo }) {
 </TabItem>
 </Tabs>
 
+:::info
+
 Mutations automatically update the normalized cache, resulting in consistent and fresh data.
 
+:::
 
 ## Schema
 
@@ -234,24 +250,100 @@ Schemas are a declarative definition of how to [process responses](./schema)
 - Classes to [deserialize fields](../guides/network-transform#deserializing-fields)
 
 ```typescript
-import { Endpoint, Entity } from '@rest-hooks/endpoint';
+import { Endpoint } from '@rest-hooks/endpoint';
+
+const fetchTodoList = (params: any) =>
+  fetch(`https://jsonplaceholder.typicode.com/todos/`).then(res => res.json());
+
+const todoList = new Endpoint(fetchTodoList, {
+  // highlight-next-line
+  schema: [Todo],
+  sideEffect: true,
+});
+```
+
+Placing our [Entity](../api/Entity.md) `Todo` in an array, tells Rest Hooks to expect
+an array of `Todos`.
+
+Aside from array, there are a few more 'schemas' provided for various patterns. The first two (Object and Array)
+have shorthands of using object and array literals.
+
+- [Object](../api/Object.md): maps with known keys
+- [Array](../api/Array.md): variably sized arrays
+- [Union](../api/Union.md): select from many different types
+- [Value](../api/Value.md): maps with any keys - variably sized
+- [Delete](../api/Delete.md): remove an entity
+
+[Learn more](../api/schema.md)
+
+### Nesting
+
+Additionally, [Entities](../api/Entity.md) themselves can specify [nested](../guides/nested-response.md) [Entities](../api/Entity.md)
+by specifying a [static schema](../api/Entity.md#schema) member.
+
+```typescript
+import { Entity } from '@rest-hooks/endpoint';
 
 class Todo extends Entity {
   readonly id: number = 0;
-  readonly userId: number = 0;
+  readonly user: User = User.fromJS({});
   readonly title: string = '';
   readonly completed: boolean = false;
 
   pk() {
     return `${this.id}`;
   }
+
+  // highlight-start
+  static schema = {
+    user: User,
+  };
+  // highlight-end
 }
 
-const TodoDetail = new Endpoint(
-    ({ id }) ⇒ fetch(`https://jsonplaceholder.typicode.com/todos/${id}`),
-    { schema: Todo }
-);
+class User extends Entity {
+  readonly id: number = 0;
+  readonly username: string = '';
+
+  pk() {
+    return `${this.id}`;
+  }
+}
 ```
 
+[Learn more](../guides/nested-response.md)
+
+### Data Representations
+
+Additionally, any `newable` class that has a toJSON() method, can be [used as a schema](../guides/network-transform#deserializing-fields). This will simply construct the object during denormalization.
+This might be useful with representations like [bignumber](https://mikemcl.github.io/bignumber.js/)
+
+```ts
+import { Entity } from '@rest-hooks/endpoint';
+
+class Todo extends Entity {
+  readonly id: number = 0;
+  readonly user: User = User.fromJS({});
+  readonly title: string = '';
+  readonly completed: boolean = false;
+  // highlight-next-line
+  readonly createdAt: Date = new Date(0);
+
+  pk() {
+    return `${this.id}`;
+  }
+
+  static schema = {
+    user: User,
+    // highlight-next-line
+    createdAt: Date,
+  };
+}
+```
+
+:::info
+
+Due to the global referential equality guarantee - construction of members only occurs once
+per update.
 
-<!-- nesting -->
+:::

docs/guides/auth.md

@@ -1,6 +1,7 @@
 ---
 title: Authentication
 ---
+
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 
@@ -21,7 +22,7 @@ values={[
 
 ```typescript
 class AuthdResource extends Resource {
-  static getFetchInit = (init: RequestInit) => ({
+  static getFetchInit = (init: RequestInit): RequestInit => ({
     ...init,
     credentials: 'same-origin',
   });
@@ -32,10 +33,12 @@ class AuthdResource extends Resource {
 <TabItem value="superagent">
 
 ```typescript
-import { Request } from 'rest-hooks';
+import { Resource } from 'rest-hooks';
+import type { SuperAgentRequest } from 'superagent';
 
 class AuthdResource extends Resource {
-  static fetchPlugin = (request: Request) => request.withCredentials();
+  static fetchPlugin = (request: SuperAgentRequest) =>
+    request.withCredentials();
 }
 ```
 
@@ -55,17 +58,16 @@ class AuthdResource extends Resource {
   static useFetchInit = (init: RequestInit) => {
     const accessToken = useAuthContext();
     return {
-    ...init,
+      ...init,
       headers: {
         ...init.headers,
         'Access-Token': accessToken,
       },
-    }
+    };
   };
 }
 ```
 
-
 ## Code organization
 
 If much of your `Resources` share a similar auth mechanism, you might