foldkit-sync 0.8.0 → 0.9.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.
package/README.md CHANGED
@@ -213,8 +213,13 @@ What each call does, and does not do:
213
213
  Reload the page: the todos come back from the outbox and the committed
214
214
  snapshot, the selection does not. That is the shared/local line, visible.
215
215
 
216
- `mounted` also exposes `model()`, `subscribe`, `observe`, `committed`, and
217
- `dispose()`, which waits for in-flight persists and leaves the replica open.
216
+ `mounted` also exposes `model()`, `subscribe`, `observe`, `committed`,
217
+ `settled()`, and `dispose()`, which waits for in-flight persists and leaves the
218
+ replica open. `settled()` resolves once the Model has caught up with the
219
+ replica: every dispatched Message applied, no persist unanswered, and every
220
+ replica status applied. It waits for no frame and no I/O, so a test pairs it
221
+ with `Frames.track` from `foldkit-mixins/testing`: `await
222
+ frames.settle(mounted)`.
218
223
  Close the replica with its own scope.
219
224
 
220
225
  ## The server
@@ -225,24 +230,52 @@ commits what it accepts, and returns what the replica is missing. With
225
230
  snapshot, reducer, and any [authorization](#authorize-on-the-server):
226
231
 
227
232
  ```ts
228
- import { ActorId, DocumentId, Journal, OpId } from 'foldkit-durable'
233
+ import { Effect } from 'effect'
234
+ import { ActorId, Journal, OpId } from 'foldkit-durable'
235
+ import type { SocketLike } from 'foldkit-sync'
236
+ import { serveJournal } from 'foldkit-sync/journal'
229
237
 
230
238
  type Principal = { readonly actorId: string }
231
239
 
232
- const journal = yield* Journal.make({
233
- ...TodoSync.journalContract(),
234
- file: 'todos.sqlite',
235
- opId: operation => OpId.make(operation.opId),
236
- actorId: (principal: Principal) => ActorId.make(principal.actorId),
240
+ const server = Effect.gen(function* () {
241
+ const journal = yield* Journal.make({
242
+ ...TodoSync.journalContract(),
243
+ file: 'todos.sqlite',
244
+ opId: operation => OpId.make(operation.opId),
245
+ actorId: (principal: Principal) => ActorId.make(principal.actorId),
246
+ })
247
+ // One accepted socket, as the principal its authentication established.
248
+ return (socket: SocketLike, principal: Principal) =>
249
+ serveJournal(socket, { sync: TodoSync, journal, principal })
237
250
  })
238
251
  ```
239
252
 
240
- The exchange handler itself is yours: it calls `journal.append` for each
241
- pending operation, `journal.read` for what follows the cursor, and serves the
242
- result on a socket with `Sync.transport.serve`. [The replicated state
243
- guide](../../docs/replication.md#3-the-server-an-exchange-over-the-journal) shows
244
- the whole handler in one page, and [`examples/sync`](../../examples/sync) runs
245
- it over `ws`.
253
+ `foldkit-sync/journal` is the exchange over the journal (`foldkit-durable`,
254
+ an optional peer of this package):
255
+
256
+ - **`serveJournal(socket, options)`** answers one socket's exchanges and sends
257
+ a notice after each commit, so its replica hears of others' edits.
258
+ `journalExchange(options)` is the same exchange as a `TransportClient`, for
259
+ `Sync.transport.fromPromise` in process; `journalChanges` the notice alone.
260
+ - **What cannot be taken is rejected by its id, not left to fail the
261
+ exchange.** An operation whose message does not decode, that names another
262
+ document, that `authorize` or `validate` refuses, or that reuses an id for
263
+ other content fails the same way on every retry, so the replica drops it
264
+ and the edits behind it still go. Only an entry with no id, a cursor ahead
265
+ of the journal's, or the journal failing fails the exchange.
266
+ - **`refuse(operation)`** rejects before the journal reads it, by what the
267
+ transport established (a principal that may only read); a rule about the
268
+ document belongs in `authorize`.
269
+ - **`settle`** runs after each exchange's appends: apply what committed to
270
+ another store, through `journal.recover`. It runs every exchange, so a
271
+ write that failed is tried again.
272
+ - The reply carries what committed since the cursor, a page at a time
273
+ (`limit`, `more`), a checkpoint when that history was compacted, and the
274
+ journal's epoch: a replica of a reset journal is answered from the start.
275
+
276
+ [The replicated state guide](../../docs/replication.md#3-the-server-an-exchange-over-the-journal)
277
+ says why each rule is there, and [`examples/sync`](../../examples/sync) writes
278
+ the exchange by hand, with an effect policy per committed operation.
246
279
 
247
280
  A server that is not Durable implements the same [exchange](#the-exchange).
248
281
 
@@ -296,20 +329,28 @@ error names why: `ReplayError` for a Message that cannot be durable,
296
329
 
297
330
  ```ts
298
331
  const status = yield* replica.status
299
- // { pending: number, cursor: Sequence, lastError: string | undefined, rejected: ReadonlyArray<OpId> }
332
+ // { pending: number, cursor: Sequence, lastError: string | undefined, rejected: ReadonlyArray<Rejection> }
300
333
  ```
301
334
 
302
335
  `pending` above zero means edits the server has not confirmed; `lastError` is
303
336
  the last failed exchange, cleared by the next success; `rejected` lists recent
304
- edits the server refused. `replica.statusChanges` is a Stream of the same,
305
- emitted after every submit and exchange; `replica.changes` pairs it with the
306
- optimistic `shared` value so one subscription sees both.
337
+ edits the server refused, most recent first, each `{ opId, reason, operation }`,
338
+ where `reason` is an `Option` of the server's words for the person and
339
+ `operation` is the refused operation itself, which the replica has dropped
340
+ from the outbox, so a page reads what it changed from here. `replica.statusChanges` is a Stream of the same,
341
+ emitted now and after every submit and exchange (subscribed before its first
342
+ read, so a subscriber slow to take one misses no change); `replica.changes`
343
+ pairs it with the optimistic `shared` value so one subscription sees both.
307
344
 
308
345
  **A refused edit** arrives as a rejection on the next exchange, not as an
309
346
  error. The replica drops it and replays the rest; the mount re-installs the
310
347
  shared slice, and the field the user edited reverts. `onPersistenceFailure`
311
348
  does not run for this, since the local save succeeded. Watch `rejected` to
312
- explain the revert.
349
+ explain the revert: `journalExchange` gives each rejection a reason, the
350
+ `authorize` rule's own when it gave one, and otherwise a fixed sentence
351
+ ("Not a valid operation"). It never sends an error's message, which may carry
352
+ internals, so a rule a person should read about belongs in `authorize` with a
353
+ `reason`, not in `validate`.
313
354
 
314
355
  **Waiting for the server.** The Model shows an edit before the server has it.
315
356
  Something that must not report success until the edit is committed, an agent
@@ -375,6 +416,9 @@ const Board = Authorized.make({
375
416
  })
376
417
  ```
377
418
 
419
+ A rule returns `true`, `false`, or `{ allowed: false, reason }`; the reason
420
+ is sent to the replica whose edit it was, as its rejection's `reason`.
421
+
378
422
  `message` is exactly that variant, `shared` is the authoritative snapshot, and
379
423
  `principal` is whatever the server's transport established for the connection;
380
424
  it is never read from the operation. A variant without a rule is allowed. A key
@@ -384,6 +428,42 @@ that is not a durable variant is a type error. The rules ride in
384
428
  An edit the policy refuses still shows at once on the client, then comes back
385
429
  as a rejection, as [above](#what-to-show-the-user).
386
430
 
431
+ ### Stamp what only the commit decides
432
+
433
+ A fact carries its own nondeterminism, but a client cannot know where its
434
+ operation lands in the server's order. A stamp writes it in, on the server, as
435
+ the journal commits:
436
+
437
+ ```ts
438
+ const Message = defineMessageUnion({
439
+ // `at` is absent on what a client sends: the server's sequence once committed.
440
+ PriceEdited: { id: Schema.String, cents: Schema.Number, at: Schema.optionalKey(Schema.Number) },
441
+ })
442
+
443
+ const Prices = Sync.forApplication(App).make({
444
+ documentId: DocumentId.make('prices'),
445
+ shared: Projection.pick(App.model.prices),
446
+ durable: MessageSet.make(App, [Message.PriceEdited]),
447
+ stamp: {
448
+ PriceEdited: ({ id, cents }, { sequence }) => Message.PriceEdited({ id, cents, at: sequence }),
449
+ },
450
+ })
451
+ ```
452
+
453
+ The rule gets that variant and `{ sequence, actorId, replicaId }` (the
454
+ replica that sent it, which tells one person's tabs apart), and returns the same
455
+ variant; a key that is not durable is a type error, and a rule that returns
456
+ another variant has its operation rejected. It rides in `journalContract()` as
457
+ Durable's `stamp`, so the journal stores, reduces and sends the stamped
458
+ Message. A replica shows what it sent until the exchange, then replays the
459
+ stamped Message in its place, the same on every replica. A retry is still
460
+ recognized by what was sent.
461
+
462
+ Use it for what a reader compares with the server's order: a read model that
463
+ records the last sequence it applied can tell which edits it holds by comparing
464
+ the two. A client that sends the stamped field itself is claiming a commit it
465
+ did not get; refuse it in the journal's `validate`.
466
+
387
467
  ### Coalesce a burst of typing
388
468
 
389
469
  Typing makes one durable Message per keystroke. `coalesce(last, next)` is
@@ -417,10 +497,45 @@ See [`examples/todo-app`](../../examples/todo-app) for both.
417
497
  ### Carry local state across a reinstall
418
498
 
419
499
  When an exchange or a failed persist replaces the shared slice outside
420
- `update`, `onReinstall(next, previous)` returns the transition instead. Use it
421
- to keep a selection that points into the slice, or to return a Command that
422
- patches a DOM the change has to reach. Omitted, the Model is simply `next`. It
423
- is not called for a status that changed nothing the Model shows.
500
+ `update`, `onReinstall(next, previous, { reset })` returns the transition
501
+ instead. Use it to keep a selection that points into the slice, or to return a
502
+ Command that patches a DOM the change has to reach. Omitted, the Model is
503
+ simply `next`. It is not called for a status that changed nothing the Model
504
+ shows. `reset` is true when the server's history is a new one (a new
505
+ `status.epoch`: the server was reset), so whatever the application derived
506
+ from the old one, such as reads keyed by commit sequence, is to be read again.
507
+
508
+ ### Edit rows a server owns
509
+
510
+ When rows are too many to replicate but edits to them must survive offline,
511
+ let the journal own the edits and the table be its read model, each row
512
+ carrying the highest sequence it has applied (`revision`). `foldkit-sync/entity`
513
+ keeps such edits one per cell and lays them over the rows Remote reads:
514
+
515
+ ```text
516
+ cell shown = the row's value, unless an edit of that cell is pending,
517
+ or committed after the row's revision (at > row.revision)
518
+ ```
519
+
520
+ `EditableEntity.make(Product, { members: ['description', 'cents'] })` gives
521
+ the schemas (`Change` on the wire, `Edit` in the slice, the Message fields
522
+ `edited` and `absorbed`) and pure functions for `update`, the stamp
523
+ (`stamped`) and `onReinstall`: `merge`, `absorb`, `overlay` (for
524
+ `RowModel.map`), `held` and `settled` (an edit the journal absorbed, kept until
525
+ a read of its row reaches it), `replaced` (a cell of this tab's that another's
526
+ later commit took), `cellsOf` (what a refusal undid) and `changeAt` (what a
527
+ row holds in a member, as the change that sets it: an undo's value). It owns no state and
528
+ does no I/O. On the server, `editsJournal` from `foldkit-sync/journal` keeps
529
+ the table: its `settle` (for `journalExchange`) applies each committed change
530
+ through your `apply` as a recovery intent, from the journal's floor and keyed
531
+ by its epoch, and its `absorb` (on a clock) records what the table holds and
532
+ compacts behind it. It refuses to settle a table whose `tableRevision` is past
533
+ the journal's cursor (`TableAheadOfJournalError`: the table outlived a reset of
534
+ the journal), and an edit to a row the table lacks is the journal's `validate`
535
+ to refuse. [Editing server data through a
536
+ journal](../../docs/editing-server-data.md) explains the pattern, its failure
537
+ cases and its limits; [`examples/registry`](../../examples/registry) is the
538
+ whole of it.
424
539
 
425
540
  ## Testing without a browser or a server
426
541
 
@@ -540,6 +655,7 @@ request cursor
540
655
  answer operations committed after the cursor, contiguous
541
656
  acknowledged ids the server accepted without repeating them
542
657
  rejected ids the server refused
658
+ reasons? [{ opId, reason }]: why, for some of rejected; at most 500 characters each
543
659
  checkpoint? { cursor, model } when the history is gone
544
660
  more? true when another page follows
545
661
  epoch? the server's history
@@ -559,10 +675,18 @@ replica validates every field; see [when things go wrong](#when-things-go-wrong)
559
675
  `maxRetries` (5) consecutive failed connections fails queued work and fails
560
676
  new exchanges fast until a socket is healthy again. `maxQueue` (64) bounds
561
677
  the queue.
678
+ Instead of a `url`, pass `makeSocket: () => SocketLike` to connect over
679
+ something else; it is called again on each reconnect.
562
680
  - `Sync.transport.serve(socket, { exchange, changes? })`: the server side of one
563
681
  accepted socket. With `changes`, a subscription to the document's commits, it
564
682
  sends a notice after each; the client's loop exchanges on every notice, so a
565
683
  tab that is only reading still sees others' edits without polling.
684
+ - `Sync.transport.portSocket(port, { signal? })`: a socket over a
685
+ `MessagePort`, for a server in a worker or in the page. A port tells
686
+ neither end when the other goes, so its `onClose` fires on `close()` or when
687
+ `signal` aborts: a host aborts it when the pane it serves is gone, and
688
+ `serve` stops. A client opens one per connection:
689
+ `Sync.transport.socket({ makeSocket: () => Sync.transport.portSocket(open()) })`.
566
690
  - `Sync.transport.loopback(handler)`, `fromPromise(client)`, `toPromise(shape)`,
567
691
  and `nativeSocket` for the platform `WebSocket`.
568
692
 
@@ -0,0 +1,231 @@
1
+ import { Option, Schema } from "effect";
2
+ //#region src/entity.d.ts
3
+ /** Who committed an edit: the actor, shown in words, and the replica (a tab), which says whose it is. */
4
+ export declare const Author: Schema.Struct<{
5
+ readonly actor: Schema.String;
6
+ readonly replica: Schema.String;
7
+ }>;
8
+ export type Author = typeof Author.Type;
9
+ /** What `make` reads of an Entity: each member's schema, `id` among them. */
10
+ export interface EntityFields {
11
+ readonly fields: {
12
+ readonly id: {
13
+ readonly schema: Schema.Top;
14
+ };
15
+ } & {
16
+ readonly [member: string]: {
17
+ readonly schema: Schema.Top;
18
+ };
19
+ };
20
+ }
21
+ /** The members an edit can change: every field but `id`. */
22
+ export type Member<E extends EntityFields> = Exclude<keyof E['fields'] & string, 'id'>;
23
+ type ValueOf<E extends EntityFields, K extends Member<E>> = E['fields'][K]['schema']['Type'];
24
+ type IdOf<E extends EntityFields> = E['fields']['id']['schema']['Type'];
25
+ /** One cell's new value: the member and a value of that member's type, together. */
26
+ export type Change<E extends EntityFields, Ms extends Member<E>> = { readonly [K in Ms]: {
27
+ readonly id: IdOf<E>;
28
+ readonly member: K;
29
+ readonly value: ValueOf<E, K>;
30
+ }; }[Ms];
31
+ /** A cell's edit as the slice keeps it: committed `at` by `by`, or, with neither, pending. */
32
+ export type CellEdit<E extends EntityFields, Ms extends Member<E>> = { readonly [K in Ms]: {
33
+ readonly id: IdOf<E>;
34
+ readonly member: K;
35
+ readonly value: ValueOf<E, K>;
36
+ readonly at: Option.Option<number>;
37
+ readonly by: Option.Option<Author>;
38
+ }; }[Ms];
39
+ /** A row an overlay draws on: its id, the revision the table read it at, and its members. */
40
+ export type RowOf<E extends EntityFields, Ms extends Member<E>> = {
41
+ readonly id: IdOf<E>;
42
+ readonly revision: number;
43
+ } & { readonly [K in Ms]: ValueOf<E, K>; };
44
+ /** A cell this replica last wrote that a later edit replaced: its edit, and what the cell holds now. */
45
+ export interface Replaced<Edit> {
46
+ readonly edit: Edit;
47
+ /** The later edit's author, when the slice still says; none once the journal absorbed it. */
48
+ readonly by: Option.Option<Author>;
49
+ }
50
+ declare const make: <E extends EntityFields, const Ms extends ReadonlyArray<Member<E>>>(entity: E, options: {
51
+ readonly members: Ms;
52
+ }) => {
53
+ members: Ms;
54
+ /** The members, as a schema: what names a cell. */
55
+ Member: Schema.Literals<Ms>;
56
+ /** One cell's change, on the wire: its member's value, by that member's schema. */
57
+ Change: Schema.Codec<Change<E, Ms[number]>, unknown, never, never>;
58
+ /** One cell's edit as the slice keeps it; `null` on the wire where it has no `at` or `by`. */
59
+ Edit: Schema.Codec<CellEdit<E, Ms[number]>, unknown, never, never>;
60
+ /** The durable Message that edits cells: its fields, for the application's own tag. */
61
+ edited: {
62
+ changes: Schema.$Array<Schema.Codec<Change<E, Ms[number]>, unknown, never, never>>;
63
+ /** The journal's: absent on what a replica sends, stamped at commit. */
64
+ at: Schema.optionalKey<Schema.Number>;
65
+ by: Schema.optionalKey<Schema.Struct<{
66
+ readonly actor: Schema.String;
67
+ readonly replica: Schema.String;
68
+ }>>;
69
+ };
70
+ /** The server's durable Message: the table holds every edit committed through `through`. */
71
+ absorbed: {
72
+ through: Schema.Number;
73
+ };
74
+ /** What the stamp writes into an edit: the sequence and the author. */
75
+ stamped: (commit: {
76
+ readonly sequence: number;
77
+ readonly actorId: string;
78
+ readonly replicaId: string;
79
+ }) => {
80
+ at: number;
81
+ by: {
82
+ actor: string;
83
+ replica: string;
84
+ };
85
+ };
86
+ /** The edits with `changes` laid over them, each cell's latest kept. */
87
+ merge: (edits: ReadonlyArray<CellEdit<E, Ms[number]>>, changes: ReadonlyArray<Change<E, Ms[number]>>, at: Option.Option<number>, by: Option.Option<Author>) => ReadonlyArray<CellEdit<E, Ms[number]>>;
88
+ /** The edits less those committed through `through`; the same array when none was. */
89
+ absorb: (edits: ReadonlyArray<CellEdit<E, Ms[number]>>, through: number) => ReadonlyArray<CellEdit<E, Ms[number]>>;
90
+ /** Whether any edit is committed through `through`: whether an absorb would drop one. */
91
+ holdsThrough: (edits: ReadonlyArray<CellEdit<E, Ms[number]>>, through: number) => boolean;
92
+ /** Whether the row, read at `revision`, does not hold the edit yet: shown over it. */
93
+ shows: (edit: CellEdit<E, Ms[number]>, revision: number) => boolean;
94
+ /**
95
+ * The rows as shown: each with the edits it has not absorbed laid over it.
96
+ * Built once per `edits`, for `RowModel.map`, which caches by its identity.
97
+ */
98
+ overlay: <R extends RowOf<E, Ms[number]>>(edits: ReadonlyArray<CellEdit<E, Ms[number]>>) => ((row: R) => R);
99
+ /**
100
+ * Of `edits`, the committed ones that `next` no longer holds, whose row is
101
+ * cached below them: what the row would otherwise show stale. A row not
102
+ * cached keeps nothing; its next read has the table's value.
103
+ */
104
+ held: (edits: ReadonlyArray<CellEdit<E, Ms[number]>>, next: ReadonlyArray<CellEdit<E, Ms[number]>>, revisionOf: (id: IdOf<E>) => Option.Option<number>) => ReadonlyArray<CellEdit<E, Ms[number]>>;
105
+ /** Whether `after` holds a committed cell `before` did not: one just taken from the slice. */
106
+ newlyHeld: (before: ReadonlyArray<CellEdit<E, Ms[number]>>, after: ReadonlyArray<CellEdit<E, Ms[number]>>) => boolean;
107
+ /**
108
+ * The held edits a read of their rows has reached, let go; of those,
109
+ * `replica`'s own that the row shows another value for, as replaced: the
110
+ * table applies in order, so a row at or past an edit that holds another
111
+ * value took a later one, whose author the journal has absorbed. With
112
+ * nothing reached, `held` comes back as it was given.
113
+ */
114
+ settled: (held: ReadonlyArray<CellEdit<E, Ms[number]>>, rowOf: (id: IdOf<E>) => Option.Option<RowOf<E, Ms[number]>>, replica: string) => {
115
+ readonly held: ReadonlyArray<CellEdit<E, Ms[number]>>;
116
+ readonly replaced: ReadonlyArray<Replaced<CellEdit<E, Ms[number]>>>;
117
+ };
118
+ /**
119
+ * What the slice replaced that `replica` had written: each cell whose
120
+ * edit was its own, and now holds another replica's commit with another
121
+ * value, though it be the same person's in another tab.
122
+ */
123
+ replaced: (previous: ReadonlyArray<CellEdit<E, Ms[number]>>, next: ReadonlyArray<CellEdit<E, Ms[number]>>, replica: string) => ReadonlyArray<Replaced<CellEdit<E, Ms[number]>>>;
124
+ /** The cells a set of changes names: what a refusal of them undid. */
125
+ cellsOf: (changes: ReadonlyArray<Change<E, Ms[number]>>) => ReadonlyArray<{
126
+ readonly id: IdOf<E>;
127
+ readonly member: Ms[number];
128
+ }>;
129
+ /**
130
+ * What a row holds in one member, as the change that would set it: the
131
+ * value an undo puts back.
132
+ */
133
+ changeAt: (row: RowOf<E, Ms[number]>, member: Ms[number]) => Change<E, Ms[number]>;
134
+ /** The edit of one cell, if the edits hold one. */
135
+ editOf: (edits: ReadonlyArray<CellEdit<E, Ms[number]>>, row: IdOf<E>, member: Ms[number]) => Option.Option<CellEdit<E, Ms[number]>>;
136
+ mine: (edit: CellEdit<E, Ms[number]>, replica: string) => boolean;
137
+ };
138
+ /** Edits to an Entity's members, kept per cell in a replicated slice and laid over its rows. */
139
+ export declare const EditableEntity: {
140
+ make: <E extends EntityFields, const Ms extends ReadonlyArray<Member<E>>>(entity: E, options: {
141
+ readonly members: Ms;
142
+ }) => {
143
+ members: Ms;
144
+ /** The members, as a schema: what names a cell. */
145
+ Member: Schema.Literals<Ms>;
146
+ /** One cell's change, on the wire: its member's value, by that member's schema. */
147
+ Change: Schema.Codec<Change<E, Ms[number]>, unknown, never, never>;
148
+ /** One cell's edit as the slice keeps it; `null` on the wire where it has no `at` or `by`. */
149
+ Edit: Schema.Codec<CellEdit<E, Ms[number]>, unknown, never, never>;
150
+ /** The durable Message that edits cells: its fields, for the application's own tag. */
151
+ edited: {
152
+ changes: Schema.$Array<Schema.Codec<Change<E, Ms[number]>, unknown, never, never>>;
153
+ /** The journal's: absent on what a replica sends, stamped at commit. */
154
+ at: Schema.optionalKey<Schema.Number>;
155
+ by: Schema.optionalKey<Schema.Struct<{
156
+ readonly actor: Schema.String;
157
+ readonly replica: Schema.String;
158
+ }>>;
159
+ };
160
+ /** The server's durable Message: the table holds every edit committed through `through`. */
161
+ absorbed: {
162
+ through: Schema.Number;
163
+ };
164
+ /** What the stamp writes into an edit: the sequence and the author. */
165
+ stamped: (commit: {
166
+ readonly sequence: number;
167
+ readonly actorId: string;
168
+ readonly replicaId: string;
169
+ }) => {
170
+ at: number;
171
+ by: {
172
+ actor: string;
173
+ replica: string;
174
+ };
175
+ };
176
+ /** The edits with `changes` laid over them, each cell's latest kept. */
177
+ merge: (edits: ReadonlyArray<CellEdit<E, Ms[number]>>, changes: ReadonlyArray<Change<E, Ms[number]>>, at: Option.Option<number>, by: Option.Option<Author>) => ReadonlyArray<CellEdit<E, Ms[number]>>;
178
+ /** The edits less those committed through `through`; the same array when none was. */
179
+ absorb: (edits: ReadonlyArray<CellEdit<E, Ms[number]>>, through: number) => ReadonlyArray<CellEdit<E, Ms[number]>>;
180
+ /** Whether any edit is committed through `through`: whether an absorb would drop one. */
181
+ holdsThrough: (edits: ReadonlyArray<CellEdit<E, Ms[number]>>, through: number) => boolean;
182
+ /** Whether the row, read at `revision`, does not hold the edit yet: shown over it. */
183
+ shows: (edit: CellEdit<E, Ms[number]>, revision: number) => boolean;
184
+ /**
185
+ * The rows as shown: each with the edits it has not absorbed laid over it.
186
+ * Built once per `edits`, for `RowModel.map`, which caches by its identity.
187
+ */
188
+ overlay: <R extends RowOf<E, Ms[number]>>(edits: ReadonlyArray<CellEdit<E, Ms[number]>>) => ((row: R) => R);
189
+ /**
190
+ * Of `edits`, the committed ones that `next` no longer holds, whose row is
191
+ * cached below them: what the row would otherwise show stale. A row not
192
+ * cached keeps nothing; its next read has the table's value.
193
+ */
194
+ held: (edits: ReadonlyArray<CellEdit<E, Ms[number]>>, next: ReadonlyArray<CellEdit<E, Ms[number]>>, revisionOf: (id: IdOf<E>) => Option.Option<number>) => ReadonlyArray<CellEdit<E, Ms[number]>>;
195
+ /** Whether `after` holds a committed cell `before` did not: one just taken from the slice. */
196
+ newlyHeld: (before: ReadonlyArray<CellEdit<E, Ms[number]>>, after: ReadonlyArray<CellEdit<E, Ms[number]>>) => boolean;
197
+ /**
198
+ * The held edits a read of their rows has reached, let go; of those,
199
+ * `replica`'s own that the row shows another value for, as replaced: the
200
+ * table applies in order, so a row at or past an edit that holds another
201
+ * value took a later one, whose author the journal has absorbed. With
202
+ * nothing reached, `held` comes back as it was given.
203
+ */
204
+ settled: (held: ReadonlyArray<CellEdit<E, Ms[number]>>, rowOf: (id: IdOf<E>) => Option.Option<RowOf<E, Ms[number]>>, replica: string) => {
205
+ readonly held: ReadonlyArray<CellEdit<E, Ms[number]>>;
206
+ readonly replaced: ReadonlyArray<Replaced<CellEdit<E, Ms[number]>>>;
207
+ };
208
+ /**
209
+ * What the slice replaced that `replica` had written: each cell whose
210
+ * edit was its own, and now holds another replica's commit with another
211
+ * value, though it be the same person's in another tab.
212
+ */
213
+ replaced: (previous: ReadonlyArray<CellEdit<E, Ms[number]>>, next: ReadonlyArray<CellEdit<E, Ms[number]>>, replica: string) => ReadonlyArray<Replaced<CellEdit<E, Ms[number]>>>;
214
+ /** The cells a set of changes names: what a refusal of them undid. */
215
+ cellsOf: (changes: ReadonlyArray<Change<E, Ms[number]>>) => ReadonlyArray<{
216
+ readonly id: IdOf<E>;
217
+ readonly member: Ms[number];
218
+ }>;
219
+ /**
220
+ * What a row holds in one member, as the change that would set it: the
221
+ * value an undo puts back.
222
+ */
223
+ changeAt: (row: RowOf<E, Ms[number]>, member: Ms[number]) => Change<E, Ms[number]>;
224
+ /** The edit of one cell, if the edits hold one. */
225
+ editOf: (edits: ReadonlyArray<CellEdit<E, Ms[number]>>, row: IdOf<E>, member: Ms[number]) => Option.Option<CellEdit<E, Ms[number]>>;
226
+ mine: (edit: CellEdit<E, Ms[number]>, replica: string) => boolean;
227
+ };
228
+ };
229
+ export type EditableEntity<E extends EntityFields, Ms extends ReadonlyArray<Member<E>>> = ReturnType<typeof make<E, Ms>>;
230
+ //#endregion
231
+ //# sourceMappingURL=entity.d.mts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"entity.d.mts","names":[],"sources":["../src/entity.ts"],"mappings":"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"}