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 +147 -23
- package/dist/entity.d.mts +231 -0
- package/dist/entity.d.mts.map +1 -0
- package/dist/entity.mjs +204 -0
- package/dist/entity.mjs.map +1 -0
- package/dist/index.d.mts +51 -485
- package/dist/index.d.mts.map +1 -1
- package/dist/index.mjs +132 -331
- package/dist/index.mjs.map +1 -1
- package/dist/journal.d.mts +132 -0
- package/dist/journal.d.mts.map +1 -0
- package/dist/journal.mjs +204 -0
- package/dist/journal.mjs.map +1 -0
- package/dist/sync-CP5UGs4r.d.mts +547 -0
- package/dist/sync-CP5UGs4r.d.mts.map +1 -0
- package/dist/transport-hlEQpHIv.mjs +359 -0
- package/dist/transport-hlEQpHIv.mjs.map +1 -0
- package/package.json +21 -4
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`,
|
|
217
|
-
`dispose()`, which waits for in-flight persists and leaves the
|
|
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 {
|
|
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
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
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
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
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<
|
|
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
|
|
305
|
-
|
|
306
|
-
|
|
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
|
|
421
|
-
to keep a selection that points into the slice, or to return a
|
|
422
|
-
patches a DOM the change has to reach. Omitted, the Model is
|
|
423
|
-
is not called for a status that changed nothing the Model
|
|
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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"}
|