@minca/core 0.1.17 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (120) hide show
  1. package/README.md +2 -1
  2. package/dist/files/space-files.d.ts +2 -2
  3. package/dist/files/space-files.d.ts.map +1 -1
  4. package/dist/files/space-files.js +7 -5
  5. package/dist/files/space-files.js.map +1 -1
  6. package/dist/inbox/names.d.ts +1 -1
  7. package/dist/inbox/names.js +1 -1
  8. package/dist/index.d.ts +3 -1
  9. package/dist/index.d.ts.map +1 -1
  10. package/dist/index.js +2 -0
  11. package/dist/index.js.map +1 -1
  12. package/dist/node/actions.d.ts +3 -0
  13. package/dist/node/actions.d.ts.map +1 -1
  14. package/dist/node/actions.js.map +1 -1
  15. package/dist/node/api.d.ts +1 -0
  16. package/dist/node/api.d.ts.map +1 -1
  17. package/dist/node/api.js +1 -0
  18. package/dist/node/api.js.map +1 -1
  19. package/dist/node/carrier.js +1 -1
  20. package/dist/node/carrier.js.map +1 -1
  21. package/dist/node/index.d.ts +1 -1
  22. package/dist/node/index.d.ts.map +1 -1
  23. package/dist/node/node-contacts.d.ts.map +1 -1
  24. package/dist/node/node-contacts.js +1 -0
  25. package/dist/node/node-contacts.js.map +1 -1
  26. package/dist/node/node-records.d.ts.map +1 -1
  27. package/dist/node/node-records.js +6 -1
  28. package/dist/node/node-records.js.map +1 -1
  29. package/dist/node/node.d.ts.map +1 -1
  30. package/dist/node/node.js +13 -1
  31. package/dist/node/node.js.map +1 -1
  32. package/dist/node/remote.d.ts.map +1 -1
  33. package/dist/node/remote.js +7 -1
  34. package/dist/node/remote.js.map +1 -1
  35. package/dist/node/space-runtime.d.ts +5 -3
  36. package/dist/node/space-runtime.d.ts.map +1 -1
  37. package/dist/node/space-runtime.js +3 -1
  38. package/dist/node/space-runtime.js.map +1 -1
  39. package/dist/node/types.d.ts +112 -36
  40. package/dist/node/types.d.ts.map +1 -1
  41. package/dist/node/watch-notifications.d.ts +6 -0
  42. package/dist/node/watch-notifications.d.ts.map +1 -1
  43. package/dist/node/watch-notifications.js +47 -9
  44. package/dist/node/watch-notifications.js.map +1 -1
  45. package/dist/query/types.d.ts +1 -0
  46. package/dist/query/types.d.ts.map +1 -1
  47. package/dist/query/types.js.map +1 -1
  48. package/dist/records/contract-builder.d.ts +22 -6
  49. package/dist/records/contract-builder.d.ts.map +1 -1
  50. package/dist/records/contract-builder.js.map +1 -1
  51. package/dist/schemas/automations.d.ts +6 -2
  52. package/dist/schemas/automations.d.ts.map +1 -1
  53. package/dist/schemas/automations.js.map +1 -1
  54. package/dist/schemas/connectors.d.ts +4 -3
  55. package/dist/schemas/connectors.d.ts.map +1 -1
  56. package/dist/schemas/connectors.js +4 -3
  57. package/dist/schemas/connectors.js.map +1 -1
  58. package/dist/schemas/library/media.js +1 -1
  59. package/dist/schemas/library/media.js.map +1 -1
  60. package/dist/session/account-hint.d.ts +2 -2
  61. package/dist/session/account-hint.d.ts.map +1 -1
  62. package/dist/session/account-hint.js +3 -3
  63. package/dist/session/account-hint.js.map +1 -1
  64. package/dist/session/auth.d.ts +7 -3
  65. package/dist/session/auth.d.ts.map +1 -1
  66. package/dist/session/auth.js.map +1 -1
  67. package/dist/session/connection.d.ts +18 -0
  68. package/dist/session/connection.d.ts.map +1 -1
  69. package/dist/session/connection.js +11 -0
  70. package/dist/session/connection.js.map +1 -1
  71. package/dist/session/index.d.ts +2 -2
  72. package/dist/session/index.d.ts.map +1 -1
  73. package/dist/session/index.js +2 -2
  74. package/dist/session/index.js.map +1 -1
  75. package/dist/storage/blob-store.d.ts +3 -0
  76. package/dist/storage/blob-store.d.ts.map +1 -1
  77. package/dist/types.d.ts +11 -2
  78. package/dist/types.d.ts.map +1 -1
  79. package/dist/types.js.map +1 -1
  80. package/docs/README.md +86 -93
  81. package/docs/actions.md +213 -152
  82. package/docs/agents.md +198 -167
  83. package/docs/automations.md +296 -204
  84. package/docs/blueprints-and-guides.md +405 -311
  85. package/docs/bots.md +208 -134
  86. package/docs/building-an-app.md +86 -159
  87. package/docs/collections.md +248 -328
  88. package/docs/computed.md +112 -89
  89. package/docs/contacts.md +151 -112
  90. package/docs/contracts.md +299 -120
  91. package/docs/direct-messages.md +80 -65
  92. package/docs/inbox.md +138 -93
  93. package/docs/node.md +1081 -996
  94. package/docs/permissions.md +142 -0
  95. package/docs/proposing-collections.md +74 -55
  96. package/docs/query-format.md +150 -126
  97. package/docs/records-and-queries.md +205 -126
  98. package/docs/sign-in.md +487 -416
  99. package/docs/spaces.md +261 -246
  100. package/docs/standard-library.md +487 -526
  101. package/docs/storage.md +325 -348
  102. package/docs/usernames.md +164 -97
  103. package/docs/warrants.md +100 -67
  104. package/package.json +1 -6
  105. package/dist/elements/auth-styles.d.ts +0 -18
  106. package/dist/elements/auth-styles.d.ts.map +0 -1
  107. package/dist/elements/auth-styles.js +0 -206
  108. package/dist/elements/auth-styles.js.map +0 -1
  109. package/dist/elements/dom.d.ts +0 -29
  110. package/dist/elements/dom.d.ts.map +0 -1
  111. package/dist/elements/dom.js +0 -91
  112. package/dist/elements/dom.js.map +0 -1
  113. package/dist/elements/index.d.ts +0 -13
  114. package/dist/elements/index.d.ts.map +0 -1
  115. package/dist/elements/index.js +0 -11
  116. package/dist/elements/index.js.map +0 -1
  117. package/dist/elements/minca-auth.d.ts +0 -55
  118. package/dist/elements/minca-auth.d.ts.map +0 -1
  119. package/dist/elements/minca-auth.js +0 -768
  120. package/dist/elements/minca-auth.js.map +0 -1
@@ -1,181 +1,260 @@
1
1
  # Records and queries
2
2
 
3
- A record is a JSON body in a collection of a space, signed by whoever wrote
4
- it. Its `key` stays the same across edits, and links point at the key. Every
5
- edit is a new version.
3
+ A record is one piece of your app's data: a to-do, a vote, a message. This
4
+ page shows how to write records, change them, delete them, and find them
5
+ again with a query that stays live as they change.
6
6
 
7
- ## Writing
7
+ The examples use the `todos` collection from [Building an app](building-an-app.md).
8
+
9
+ ## Writing a record
10
+
11
+ `put` makes a new record and gives it back:
12
+
13
+ ```typescript
14
+ const todo = await node.records.put(space.id, todos, { text: 'Buy milk', done: false });
15
+ todo.key; // 'akthxqofxox3iszhpi5j3zhl6a.mfrggzdfmztwq2lknnwg23tpoa'
16
+ ```
17
+
18
+ The record gets a fresh `key`. The key stays the same for the record's whole
19
+ life, so it is what you keep, read by and link to.
20
+
21
+ Pass the collection's definition, as here, and TypeScript checks the body as
22
+ you write it. You can also pass a collection's name as a string, and the body
23
+ is untyped.
24
+
25
+ ## Editing a record
26
+
27
+ `update` writes the record's next version:
8
28
 
9
29
  ```typescript
10
- const todo = await node.records.put(space.id, todos, { text: 'milk', done: false });
30
+ await node.records.update(space.id, todo.key, { text: 'Buy milk', done: true });
31
+ ```
32
+
33
+ It takes the whole new body, not a patch. Every edit is a new version, and it
34
+ syncs to everyone in the space.
35
+
36
+ ## Deleting a record
11
37
 
12
- await node.records.update(space.id, todo.key, { text: 'milk', done: true }); // the whole body, not a patch
38
+ ```typescript
13
39
  await node.records.delete(space.id, todo.key);
14
40
  ```
15
41
 
16
- - `put` makes a new record at a fresh key of your account's, unless you name
17
- one (`{ key: 'settings' }`), which suits a record there is one of per
18
- account by nature. Under `onePer` the key is derived for you. See
19
- [keys](#keys).
20
- - `update` takes the whole next body. Links carry over unless you pass new
21
- ones.
22
- - `delete` writes a version marked deleted, which syncs like any other.
23
- - Pass a definition made with `collection(…)` instead of a name, and the body
24
- is type-checked as you write it.
25
- - A write this account isn't allowed to make throws, with the reason in plain
26
- words. Nothing is signed. `node.records.can(space, 'edit', key)` asks first.
27
-
28
- Which version wins is decided by `seq` (one higher each edit), then by version
29
- id, never by a clock. Two devices that edited apart agree on the same winner.
30
- Merging edits inside one record is not built yet, so design records so that
31
- people edit different ones: one record per vote, per card, per reaction.
42
+ A delete is a version too, marked deleted, and it syncs like any other.
32
43
 
33
- ## Keys
44
+ ## Who may write
34
45
 
35
- A record's key says whose it is. Every key an account creates starts with its
36
- owner part, a hash of the account, so no one else can create a record there:
37
- every peer refuses a first version at a key the writer doesn't own, however
38
- it got there ([spec 02 §4.1](https://github.com/leifriksheim/minca/blob/main/spec/02-records.md)).
46
+ A write your account isn't allowed to make throws, with the reason in plain
47
+ words, and nothing is signed. To ask first, for example to hide a button:
39
48
 
40
49
  ```typescript
41
- const fresh = await node.records.put(space.id, todos, { text: 'milk' });
42
- fresh.key; // 'akthxqofxox3iszhpi5j3zhl6a.mfrggzdfmztwq2lknnwg23tpoa'
43
-
44
- await node.records.put(space.id, 'app.settings', { theme: 'dark' }, { key: 'settings' });
45
- const mine = await node.records.keyFor(space.id, 'settings'); // 'akthxqofxox3iszhpi5j3zhl6a.settings'
46
- const hers = await node.records.keyFor(space.id, 'settings', aliceDid); // Alice's, if she wrote one
47
- await node.records.get(space.id, hers);
50
+ const mayEdit = await node.records.can(space.id, 'edit', todo.key);
48
51
  ```
49
52
 
50
- - A name you choose goes in your account's namespace, so two accounts
51
- choosing `settings` get two records. Names are 1–101 characters of a–z,
52
- 0–9 and `: . _ -`. Give a whole key only when it is already yours, to write
53
- it again after a delete.
54
- - Read and link records by their whole `key`, as `put` returns it; a name is
55
- only a name in someone's namespace.
56
- - Your name is the same key in every collection, and a record keeps its
57
- collection for life, so `put` refuses a name you already hold in another
58
- collection, deleted or not. Choose names that include the collection
59
- (`app.todo.settings`), so two apps of yours never pick the same one. A
60
- name of the form `one:<hex>` is refused outside a `onePer` collection, as
61
- every peer would refuse it.
62
- - Under `onePer`, the node derives the key from the parts the rules name
63
- (`node.records.onePerKey`). With `@author` it is the writer's; without, it
64
- is a shared `one:…` key ([collections](collections.md#rules)). In a private
65
- space it is keyed with the space's key, so it says nothing to someone who
66
- can't read the space.
67
- - An account's line in a collection, for contracts, has the key
68
- `lineKey(account, collection)` (exported by `@minca/core`), an
69
- owned key of the account's.
70
-
71
- _Source: `packages/core/src/records/key.ts`, `packages/core/src/node/space-writing.ts` (`keyToWrite`, `keepsCollection`, `put`, `onePerKey`), `packages/core/src/node/space-runtime.ts` (`keyFor`). Tests: `packages/core/tests/record-keys.test.ts`, `packages/core/tests/versions.test.ts` ("a deleted key can be written again…")._
53
+ The action is `'create'`, `'edit'` or `'delete'`. For `'create'`, name the
54
+ collection instead of a key. In React, `useCan(space, action, target)` gives
55
+ the same answer.
56
+
57
+ Who may write what is set by the collection's rules and the space's roles. See
58
+ [Collections](collections.md#rules).
72
59
 
73
60
  ## Links
74
61
 
62
+ A record can point at other records. Here a vote points at the poll it is
63
+ about, and `linked` finds what points at the poll:
64
+
75
65
  ```typescript
76
- await node.records.put(
77
- space.id,
78
- votes,
79
- { choice: 0 },
80
- {
81
- links: [{ rel: 'about', to: poll.key }],
82
- },
83
- );
66
+ const poll = await node.records.put(space.id, 'app.poll', { question: 'Where to?' });
67
+ await node.records.put(space.id, 'app.vote', { choice: 0 }, { links: [{ rel: 'about', to: poll.key }] });
84
68
 
85
- const all = await node.records.linked(space.id, poll.key, { rel: 'about' });
69
+ const votes = await node.records.linked(space.id, poll.key, { rel: 'about' });
86
70
  ```
87
71
 
88
- The roles a record may carry are declared on its collection
89
- ([collections.md](collections.md)).
72
+ `rel` is the link's role. The roles a record may carry are declared on its
73
+ collection ([Collections](collections.md)).
90
74
 
91
- ## What a record looks like
75
+ `update` keeps a record's links unless you pass new ones.
76
+
77
+ ## Querying
78
+
79
+ A query asks for the records of one collection, filtered and sorted:
80
+
81
+ ```typescript
82
+ const { records } = await node.records.query(space.id, {
83
+ collection: todos,
84
+ where: { done: false },
85
+ sort: { '@createdAt': 'desc' },
86
+ limit: 20,
87
+ });
88
+ ```
89
+
90
+ A query is plain JSON, so you can store it, send it, or have an agent write
91
+ it. A malformed query throws, saying what to fix.
92
+
93
+ ## Filters
94
+
95
+ `where` names fields and what they must be. A bare value means "equals":
92
96
 
93
97
  ```typescript
94
- {
95
- key, version, seq, space, collection,
96
- body, // null when encrypted and this node has no key
97
- links, // [{ rel, to }]
98
- root, // the account that wrote this version
99
- createdBy, // the account that created the record
100
- createdAt, updatedAt, // the writer's clock: for display only
101
- verified, // signature, delegation and shape check out
102
- conforms, // fits the collection's schema (null when there is none)
103
- recordsOnly, // true when written under a note that can't define collections
104
- }
98
+ await node.records.query(space.id, {
99
+ collection: todos,
100
+ where: { done: false, text: { $contains: 'milk' } },
101
+ });
105
102
  ```
106
103
 
107
- A query's records also have `computed`, what the collection's
108
- [computed fields](computed.md) work out for each on this device (`{}`
109
- without any), and `included`, what its `include` found.
104
+ - A plain name is a field of the body (`text`, `address.city`), or one of the
105
+ collection's [computed fields](computed.md).
106
+ - A name starting with `@` is about the record itself: `@key`, `@author`,
107
+ `@root`, `@createdBy`, `@createdAt`, `@updatedAt`, `@seq`.
108
+ - `link:<role>` is where the record's first link of that role points.
109
+
110
+ The operators are `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$in`, `$nin`,
111
+ `$exists` and `$contains`. Combine filters with `$and`, `$or` and `$not`.
112
+ `$ne` is true for a missing field. `$contains` is a case-insensitive
113
+ substring, or an element of a list. It is not full-text search.
110
114
 
111
- Show `root` or `createdBy` as the author, not `author`, which is the session
112
- key that signed. `node.spaces.profiles(space)` maps accounts to names.
115
+ Every operator and field is in [The query format](query-format.md).
113
116
 
114
- ## Queries
117
+ ## Sorting and paging
115
118
 
116
- A query is plain JSON, so an agent can write one, and it can cross a wire.
119
+ `sort` takes several fields, applied in order. Ties break on the key.
120
+
121
+ When there are more records than `limit`, the result has a `cursor`. Pass it
122
+ back to get the next page. It is `null` on the last one.
117
123
 
118
124
  ```typescript
119
- const { records, cursor, complete } = await node.records.query(space.id, {
120
- collection: polls,
121
- where: { closed: { $ne: true }, question: { $contains: 'may' } },
122
- sort: { '@createdAt': 'desc' },
125
+ const page1 = await node.records.query(space.id, { collection: todos, limit: 20 });
126
+ const page2 = await node.records.query(space.id, {
127
+ collection: todos,
123
128
  limit: 20,
129
+ cursor: page1.cursor ?? undefined,
130
+ });
131
+ ```
132
+
133
+ ## Following links
134
+
135
+ `include` brings related records along with each result. Here each poll comes
136
+ with its votes, and the number of reactions to it:
137
+
138
+ ```typescript
139
+ const { records } = await node.records.query(space.id, {
140
+ collection: 'app.poll',
124
141
  include: {
125
- votes: { rel: 'about', from: votes }, // records linking to each poll
142
+ votes: { rel: 'about', from: 'app.vote' },
126
143
  reactions: { rel: 'about', from: 'std.reaction', count: true },
127
144
  },
128
145
  });
146
+ records[0]?.included.votes;
129
147
  ```
130
148
 
131
- - **Fields.** A bare name is a field of the body (`question`,
132
- `address.city`), or one of the collection's [computed fields](computed.md)
133
- (`done`), which never share a name. A name starting with `@` is about the
134
- record: `@key`, `@author`, `@root`, `@createdBy`, `@createdAt`,
135
- `@updatedAt`, `@seq`. `link:<role>` is where its first link of that role
136
- points.
137
- - **Operators.** `$eq`, `$ne` (true for a missing field too), `$gt`, `$gte`,
138
- `$lt`, `$lte`, `$in`, `$nin`, `$exists`, `$contains` (a case-insensitive
139
- substring, or an element of a list). Combine with `$and`, `$or`, `$not`. A
140
- bare value means `$eq`.
141
- - **Sort** by several fields in order. Ties break on the key.
142
- - **Paging.** Pass the `cursor` back to get the next page. It is null on the
143
- last one.
144
- - **Include** follows links. `direction: 'in'` (the default) finds records
145
- linking to this one, `'out'` the ones it links to. Each include takes its own
146
- `where`, `limit`, nested `include`, or `count: true` for just the number.
147
- What it finds is on each record's `included`.
148
- - Name collections by their definitions and the results are typed, includes
149
- and computed fields too, and so are `where` and `sort`: a field the
150
- collection doesn't have, or a value of the wrong type, is a compile error.
151
- A collection named as a bare string is untyped.
152
- - `complete` is false while a node that holds only part of a space is still
153
- fetching a collection the query needs. Show "Loading…", not "Nothing here".
154
- - A malformed query throws, saying what to fix.
155
-
156
- This is not full-text search: `$contains` is a substring match.
157
-
158
- ## Watching
149
+ By default an include finds records that link to this one
150
+ (`direction: 'in'`). `direction: 'out'` finds the ones this record links to.
151
+ Each include takes its own `where`, `limit` and nested `include`, or
152
+ `count: true` for just the number.
153
+
154
+ ## Typed results
155
+
156
+ Name collections by their definitions, in `collection` and `from`, and the
157
+ results are typed: bodies, includes and computed fields. `where` and `sort`
158
+ are typed too, so a field the collection doesn't have, or a value of the wrong
159
+ type, is a compile error. A collection named by a string is untyped.
160
+
161
+ ## While a space loads
162
+
163
+ The result's `complete` is false while a node that holds only part of a
164
+ space is still fetching a collection the query needs. Show "Loading…", not
165
+ "Nothing here".
166
+
167
+ ## Live results
168
+
169
+ `watch` runs a query now, and again whenever the space's records change, here
170
+ or on someone else's device:
159
171
 
160
172
  ```typescript
161
- const stop = node.records.watch(space.id, query, (result) => render(result));
173
+ const stop = node.records.watch(space.id, { collection: todos }, (result) => {
174
+ console.log(result.records.length, 'to-dos');
175
+ });
162
176
  stop();
163
177
  ```
164
178
 
165
- It runs now and again whenever the space's records change, here or from a
166
- peer. In React, `useQuery(space, query)` does the same.
179
+ In React, `useQuery(space, query)` does the same. `useRecord(space, key)`
180
+ keeps one record current, and `useLinked(space, key, { rel })` what links to
181
+ it.
167
182
 
168
183
  For anything else, subscribe to the node's events:
169
184
 
170
185
  ```typescript
171
186
  const unsubscribe = node.subscribe((event) => {
172
- if (event.type === 'records') reload(event.space);
187
+ if (event.type === 'records') console.log('records changed in', event.space);
173
188
  });
174
189
  ```
175
190
 
191
+ ## What a record looks like
192
+
193
+ Every record the node gives you is a
194
+ [`NodeRecord`](https://minca.dev/api/core/interfaces/NodeRecord/): its `key`,
195
+ its `body`, its `links`, who wrote it and whether it checks out.
196
+
197
+ A query gives each as a
198
+ [`QueryRecord`](https://minca.dev/api/core/interfaces/QueryRecord/), which
199
+ adds what the collection's [computed fields](computed.md) work out on this
200
+ device and what its `include` found.
201
+
202
+ Show `root` or `createdBy` as the author. `author` is the app's key that
203
+ signed, not the person. `node.spaces.profiles(space)` maps accounts to names.
204
+
205
+ ## Keys
206
+
207
+ A record's key says whose it is. Every key starts with its owner's part, a
208
+ hash of the account, so no one else can create a record there.
209
+
210
+ Most records just take the fresh key `put` gives them. Some records there is
211
+ one of per account, like settings. For those, pass a name:
212
+
213
+ ```typescript
214
+ await node.records.put(space.id, 'app.settings', { theme: 'dark' }, { key: 'settings' });
215
+
216
+ const mine = await node.records.keyFor(space.id, 'settings'); // 'akthxqofxox3iszhpi5j3zhl6a.settings'
217
+ const theirs = await node.records.keyFor(space.id, 'settings', did); // someone else's, if they wrote one
218
+ await node.records.get(space.id, theirs);
219
+ ```
220
+
221
+ - The name goes in your account's namespace, so two accounts that both
222
+ choose `settings` get two records.
223
+ - Names are 1–101 characters of `a`–`z`, `0`–`9` and `: . _ -`.
224
+ - Read and link records by their whole `key`, as `put` gives it, not by the
225
+ name.
226
+ - A name is the same key in every collection, and a record keeps its
227
+ collection for life. So `put` refuses a name you already hold in another
228
+ collection, deleted or not. Put the collection in the name
229
+ (`app.todo.settings`) so two of your apps never clash.
230
+ - Writing a deleted key brings the record back. Pass the whole key when it is
231
+ already yours.
232
+ - A name of the form `one:<hex>` is refused outside a `onePer` collection.
233
+
234
+ In a collection with a `onePer` rule, the node works out the key for you
235
+ from the parts the rule names, and `node.records.onePerKey` tells you what it
236
+ is. With `@author` the key is the writer's. Without, it is a shared `one:…`
237
+ key ([Collections](collections.md#rules)). In a private space it is keyed with
238
+ the space's key, so it says nothing to someone who can't read the space.
239
+
240
+ An account's line in a collection, for contracts, has the key
241
+ `lineKey(account, collection)`, exported by `@minca/core`.
242
+
243
+ Every peer refuses a first version at a key the writer doesn't own. The rule
244
+ is in [spec 02 §4.1](https://github.com/leifriksheim/minca/blob/main/spec/02-records.md).
245
+
246
+ ## When two devices edit at once
247
+
248
+ Each edit raises the record's `seq` by one. The version with the higher `seq`
249
+ wins. On a tie, the version id decides. Clocks play no part, so two devices
250
+ that edited apart agree on the same winner.
251
+
252
+ Edits inside one record are not merged. Design records so that people edit
253
+ different ones: one record per vote, per card, per reaction.
254
+
176
255
  ## History
177
256
 
178
257
  `node.records.history(space, key)` gives the versions this node keeps whole,
179
- newest first: the current one, or every one in a collection defined with
180
- `history: 'all'`. What an earlier version said is otherwise forgotten once
181
- it is superseded; only a stub of it is kept, to check the next one.
258
+ newest first. That is the current one, or every one in a collection defined
259
+ with `history: 'all'`. Otherwise an earlier version's body is forgotten once
260
+ it is replaced.