Skip to content

Commit a725050

Browse files
ntuckerntucker
committed
docs: Schema table reorganized to better find which schema to use
1 parent df6829c commit a725050

File tree

5 files changed

+83
-18
lines changed

5 files changed

+83
-18
lines changed

‎docs/core/concepts/expiry-policy.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -445,7 +445,7 @@ render(<Demo />);
445445

446446
Both [endpoints](/rest/api/Endpoint) and [entities](/rest/api/Entity) can be targetted to be invalidated.
447447

448-
### A specific endpoint
448+
### A specific endpoint {#invalidate-endpoint}
449449

450450
In this example we can see [invalidating the endpoint](../api/Controller.md#invalidate) shows the loading fallback since the data is not allowed to be displayed.
451451

@@ -544,7 +544,7 @@ render(<Demo />);
544544

545545
</HooksPlayground>
546546

547-
### Any endpoint with an entity
547+
### Any endpoint with an entity {#invalidate-entity}
548548

549549
Using the [Invalidate schema](/rest/api/Invalidate) allows us to invalidate _any_ endpoint that includes that relies on that [entity](/rest/api/Entity) in their
550550
response. If the endpoint uses the entity in an [Array](/rest/api/Array), it will simply be removed from that [Array](/rest/api/Array).

‎docs/core/shared/_schema_table.mdx‎

Lines changed: 75 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,75 @@
1-
| Schema | Description | Data Type | Mutable | [Queryable](/rest/api/schema#queryable) | Of A |
2-
| ---------------------------------- | ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | --------- | --------- |
3-
| [Entity](/rest/api/Entity) | single _unique_ object | [Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) | ✅ | ✅ | |
4-
| [Object](/rest/api/Object) | statically known keys | [Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) | 🛑 | 🛑 | |
5-
| [Array](/rest/api/Array) | lists of any size | [Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) | 🛑 | 🛑 | |
6-
| [Values](/rest/api/Values) | maps of any size | [Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) | 🛑 | 🛑 | |
7-
| [All](/rest/api/All) | list of all entities of a kind | [Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) | 🛑 | ✅ | |
8-
| [Collection](/rest/api/Collection) | enables adding new items | [Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) or [Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) | ✅ | ✅ | |
9-
| [Query](/rest/api/Query) | memoized custom transforms | any | ✅/🛑 | ✅ | Queryable |
10-
| [Union](/rest/api/Union) | one of many different types (`A \| B`) | Polymorphic [Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) | ✅ | ✅ | Entity |
11-
| [Invalidate](/rest/api/Invalidate) | [remove an entity](../concepts/expiry-policy.md#any-endpoint-with-an-entity) | [Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) | ✅ | 🛑 | Entity |
1+
<table>
2+
<thead>
3+
<tr>
4+
<th>Data Type</th>
5+
<th>Mutable</th>
6+
<th>Schema</th>
7+
<th>Description</th>
8+
<th>[Queryable](/rest/api/schema#queryable)</th>
9+
</tr>
10+
</thead>
11+
<tbody><tr>
12+
<td rowSpan={4}><a href="https://en.wikipedia.org/wiki/Object_(computer_science)">Object</a></td>
13+
<td align="center">✅</td>
14+
<td>[Entity](/rest/api/Entity)</td>
15+
<td>single <em>unique</em> object</td>
16+
<td align="center">✅</td>
17+
</tr>
18+
<tr>
19+
<td align="center">✅</td>
20+
<td>[Union(Entity)](/rest/api/Union)</td>
21+
<td>polymorphic objects (<code>A | B</code>)</td>
22+
<td align="center">✅</td>
23+
</tr>
24+
<tr>
25+
<td align="center">🛑</td>
26+
<td>[Object](/rest/api/Object)</td>
27+
<td>statically known keys</td>
28+
<td align="center">🛑</td>
29+
</tr>
30+
<tr>
31+
<td align="center"></td>
32+
<td>[Invalidate(Entity)](/rest/api/Invalidate)</td>
33+
<td>[delete an entity](../concepts/expiry-policy.md#invalidate-entity)</td>
34+
<td align="center">🛑</td>
35+
</tr>
36+
<tr>
37+
<td rowSpan={3}><a href="https://en.wikipedia.org/wiki/List_(abstract_data_type)">List</a></td>
38+
<td align="center">✅</td>
39+
<td>[Collection(Array)](/rest/api/Collection)</td>
40+
<td>growable lists</td>
41+
<td align="center">✅</td>
42+
</tr>
43+
<tr>
44+
<td align="center">🛑</td>
45+
<td>[Array](/rest/api/Array)</td>
46+
<td>immutable lists</td>
47+
<td align="center">🛑</td>
48+
</tr>
49+
<tr>
50+
<td align="center">✅</td>
51+
<td>[All](/rest/api/All)</td>
52+
<td>list of all entities of a kind</td>
53+
<td align="center">✅</td>
54+
</tr>
55+
<tr>
56+
<td rowSpan={2}><a href="https://en.wikipedia.org/wiki/Associative_array">Map</a></td>
57+
<td align="center">✅</td>
58+
<td>[Collection(Values)](/rest/api/Collection)</td>
59+
<td>growable maps</td>
60+
<td align="center">✅</td>
61+
</tr>
62+
<tr>
63+
<td align="center">🛑</td>
64+
<td>[Values](/rest/api/Values)</td>
65+
<td>immutable maps</td>
66+
<td align="center">🛑</td>
67+
</tr>
68+
<tr>
69+
<td>any</td>
70+
<td align="center"></td>
71+
<td>[Query(Queryable)](/rest/api/Query)</td>
72+
<td>memoized custom transforms</td>
73+
<td align="center">✅</td>
74+
</tr>
75+
</tbody></table>

‎docs/rest/api/Collection.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
title: schema.Collection - Entities of Arrays or Values
2+
title: schema.Collection - Mutable Lists and Maps
33
sidebar_label: schema.Collection
44
---
55

@@ -13,10 +13,10 @@ import { postFixtures,getInitialInterceptorData } from '@site/src/fixtures/posts
1313

1414
# schema.Collection
1515

16-
`Collections` are entities but for [Arrays](./Array.md) or [Values](./Values.md).
16+
`Collections` define mutable [Lists (Array)](./Array.md) or [Maps (Values)](./Values.md).
1717

18-
This makes them well suited at handling mutations. You can add to [Array](./Array.md) `Collections` with [.push](#push) or [.unshift](#unshift) and
19-
[Values](./Values.md) `Collections` with [.assign](#assign).
18+
This means they can grow and shrink. You can add to `Collection(Array)` with [.push](#push) or [.unshift](#unshift) and
19+
`Collections(Values)` with [.assign](#assign).
2020

2121
[RestEndpoint](./RestEndpoint.md) provides [.push](./RestEndpoint.md#push), [.unshift](./RestEndpoint.md#unshift), [.assign](./RestEndpoint.md#assign)
2222
and [.getPage](./RestEndpoint.md#getpage)/ [.paginated()](./RestEndpoint.md#paginated) extenders when using `Collections`

‎docs/rest/api/Invalidate.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ import EndpointPlayground from '@site/src/components/HTTP/EndpointPlayground';
1010
# schema.Invalidate
1111

1212
Describes entities to be marked as [INVALID](/docs/concepts/expiry-policy#invalid). This removes items from a
13-
collection, or [forces suspense](/docs/concepts/expiry-policy#any-endpoint-with-an-entity) for endpoints where the entity is required.
13+
collection, or [forces suspense](/docs/concepts/expiry-policy#invalidate-entity) for endpoints where the entity is required.
1414

1515
Constructor:
1616

‎docs/rest/api/schema.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
---
22
title: Thinking in Schemas
33
sidebar_label: Schema
4+
description: Declarative TypeScript data definitions. Mutable dynamic data applications without state management code.
45
---
56

67
import LanguageTabs from '@site/src/components/LanguageTabs';

0 commit comments

Comments
 (0)