foldkit-sync 0.12.3 → 0.13.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 (82) hide show
  1. package/README.md +76 -24
  2. package/dist/diagnostics.d.ts +71 -0
  3. package/dist/diagnostics.d.ts.map +1 -0
  4. package/dist/diagnostics.js +67 -0
  5. package/dist/diagnostics.js.map +1 -0
  6. package/dist/{do.d.mts → do.d.ts} +12 -2
  7. package/dist/do.d.ts.map +1 -0
  8. package/dist/{do.mjs → do.js} +15 -9
  9. package/dist/do.js.map +1 -0
  10. package/dist/{entity.d.mts → entity.d.ts} +1 -1
  11. package/dist/entity.d.ts.map +1 -0
  12. package/dist/{entity.mjs → entity.js} +1 -1
  13. package/dist/entity.js.map +1 -0
  14. package/dist/errors.d.ts +91 -0
  15. package/dist/errors.d.ts.map +1 -0
  16. package/dist/errors.js +75 -0
  17. package/dist/errors.js.map +1 -0
  18. package/dist/ids.d.ts +30 -0
  19. package/dist/ids.d.ts.map +1 -0
  20. package/dist/ids.js +28 -0
  21. package/dist/ids.js.map +1 -0
  22. package/dist/index.d.ts +106 -0
  23. package/dist/index.d.ts.map +1 -0
  24. package/dist/index.js +77 -0
  25. package/dist/index.js.map +1 -0
  26. package/dist/indexedDb.d.ts +62 -0
  27. package/dist/indexedDb.d.ts.map +1 -0
  28. package/dist/indexedDb.js +128 -0
  29. package/dist/indexedDb.js.map +1 -0
  30. package/dist/{journal.d.mts → journal.d.ts} +29 -5
  31. package/dist/journal.d.ts.map +1 -0
  32. package/dist/{journal-D5h-jqXE.mjs → journal.js} +43 -32
  33. package/dist/journal.js.map +1 -0
  34. package/dist/lww.d.ts +76 -0
  35. package/dist/lww.d.ts.map +1 -0
  36. package/dist/lww.js +121 -0
  37. package/dist/lww.js.map +1 -0
  38. package/dist/make.d.ts +162 -0
  39. package/dist/make.d.ts.map +1 -0
  40. package/dist/make.js +153 -0
  41. package/dist/make.js.map +1 -0
  42. package/dist/mount.d.ts +138 -0
  43. package/dist/mount.d.ts.map +1 -0
  44. package/dist/mount.js +344 -0
  45. package/dist/mount.js.map +1 -0
  46. package/dist/presence.d.ts +116 -0
  47. package/dist/presence.d.ts.map +1 -0
  48. package/dist/presence.js +277 -0
  49. package/dist/presence.js.map +1 -0
  50. package/dist/{remote.d.mts → remote.d.ts} +2 -2
  51. package/dist/remote.d.ts.map +1 -0
  52. package/dist/{remote.mjs → remote.js} +1 -1
  53. package/dist/remote.js.map +1 -0
  54. package/dist/revalidate.d.ts +6 -0
  55. package/dist/revalidate.d.ts.map +1 -0
  56. package/dist/revalidate.js +10 -0
  57. package/dist/revalidate.js.map +1 -0
  58. package/dist/sync.d.ts +276 -0
  59. package/dist/sync.d.ts.map +1 -0
  60. package/dist/sync.js +512 -0
  61. package/dist/sync.js.map +1 -0
  62. package/dist/transport.d.ts +151 -0
  63. package/dist/transport.d.ts.map +1 -0
  64. package/dist/{transport-BZ6utYmB.mjs → transport.js} +20 -30
  65. package/dist/transport.js.map +1 -0
  66. package/package.json +24 -24
  67. package/dist/do.d.mts.map +0 -1
  68. package/dist/do.mjs.map +0 -1
  69. package/dist/entity.d.mts.map +0 -1
  70. package/dist/entity.mjs.map +0 -1
  71. package/dist/index.d.mts +0 -397
  72. package/dist/index.d.mts.map +0 -1
  73. package/dist/index.mjs +0 -1613
  74. package/dist/index.mjs.map +0 -1
  75. package/dist/journal-D5h-jqXE.mjs.map +0 -1
  76. package/dist/journal.d.mts.map +0 -1
  77. package/dist/journal.mjs +0 -1
  78. package/dist/make-DJ0Q1SSc.d.mts +0 -702
  79. package/dist/make-DJ0Q1SSc.d.mts.map +0 -1
  80. package/dist/remote.d.mts.map +0 -1
  81. package/dist/remote.mjs.map +0 -1
  82. package/dist/transport-BZ6utYmB.mjs.map +0 -1
package/dist/sync.d.ts ADDED
@@ -0,0 +1,276 @@
1
+ import { Effect, Metric, Option, Schema, Stream } from "effect";
2
+ import { Transport, TransportError } from "./transport.js";
3
+ import { Storage } from "./indexedDb.js";
4
+ import { DocumentId, LocalSequence, OpId, ReplicaId, Sequence } from "./ids.js";
5
+ import { ReplicaError } from "./errors.js";
6
+ /** Wire and persisted-format versions. A bump must handle the older value explicitly. */
7
+ declare const PROTOCOL_VERSION = 1;
8
+ declare const SCHEMA_VERSION = 1;
9
+ /** A client-authored operation envelope. `message` is the application's encoded Message. */
10
+ declare const OperationSchema: Schema.Struct<{
11
+ readonly protocolVersion: Schema.Literal<1>;
12
+ readonly schemaVersion: Schema.Literal<1>;
13
+ readonly documentId: Schema.brand<Schema.NonEmptyString, "@foldkit-sync/DocumentId">;
14
+ readonly replicaId: Schema.brand<Schema.NonEmptyString, "@foldkit-sync/ReplicaId">;
15
+ readonly localSequence: Schema.brand<Schema.Number, "@foldkit-sync/LocalSequence">;
16
+ readonly opId: Schema.brand<Schema.NonEmptyString, "@foldkit-sync/OpId">;
17
+ readonly baseCursor: Schema.brand<Schema.Number, "@foldkit-sync/Sequence">;
18
+ readonly message: Schema.Unknown;
19
+ }>;
20
+ export type Operation = typeof OperationSchema.Type;
21
+ /** An operation the server committed, with its authoritative order and actor. */
22
+ declare const CommittedSchema: Schema.Struct<{
23
+ readonly protocolVersion: Schema.Literal<1>;
24
+ readonly schemaVersion: Schema.Literal<1>;
25
+ readonly documentId: Schema.brand<Schema.NonEmptyString, "@foldkit-sync/DocumentId">;
26
+ readonly replicaId: Schema.brand<Schema.NonEmptyString, "@foldkit-sync/ReplicaId">;
27
+ readonly localSequence: Schema.brand<Schema.Number, "@foldkit-sync/LocalSequence">;
28
+ readonly opId: Schema.brand<Schema.NonEmptyString, "@foldkit-sync/OpId">;
29
+ readonly baseCursor: Schema.brand<Schema.Number, "@foldkit-sync/Sequence">;
30
+ readonly message: Schema.Unknown;
31
+ readonly serverSequence: Schema.brand<Schema.Number, "@foldkit-sync/Sequence">;
32
+ readonly actorId: Schema.NonEmptyString;
33
+ }>;
34
+ /** Named to avoid colliding with `foldkit-durable`'s `Committed`. */
35
+ export type CommittedOperation = typeof CommittedSchema.Type;
36
+ /** Counters and a histogram an application can scrape. */
37
+ export declare const syncMetrics: {
38
+ exchanges: Metric.Counter<number>;
39
+ applied: Metric.Counter<number>;
40
+ checkpoints: Metric.Counter<number>;
41
+ exchangePending: Metric.Histogram<number>;
42
+ };
43
+ export interface Checkpoint<Shared> {
44
+ readonly cursor: Sequence;
45
+ readonly model: Shared;
46
+ }
47
+ export interface Exchange<Shared> {
48
+ /** Server-committed operations as they arrived; validated against `CommittedOperation` on adoption. */
49
+ readonly operations: ReadonlyArray<unknown>;
50
+ readonly rejected: ReadonlyArray<OpId>;
51
+ /**
52
+ * Why some of `rejected` were refused, in words the server chose for a person:
53
+ * a policy's reason, never an internal error. One without a reason is still rejected.
54
+ */
55
+ readonly reasons?: ReadonlyArray<{
56
+ readonly opId: OpId;
57
+ readonly reason: string;
58
+ }> | undefined;
59
+ /** Sends from the request that are durably committed, so the replica can drop them. */
60
+ readonly acknowledged?: ReadonlyArray<OpId> | undefined;
61
+ /** The snapshot a replica predating compaction adopts in place of the log. */
62
+ readonly checkpoint?: Checkpoint<Shared> | undefined;
63
+ /** The server sent only part of what is after the cursor; the replica asks again. */
64
+ readonly more?: boolean | undefined;
65
+ /**
66
+ * The identity of the server's history. The replica sends back the one it last saw; a
67
+ * server that finds another answers from the start of its own history, and the replica,
68
+ * seeing a new epoch, rebuilds its committed state from that answer and keeps its outbox.
69
+ */
70
+ readonly epoch?: string | undefined;
71
+ }
72
+ export interface ReplicaState<Shared> {
73
+ readonly protocolVersion: typeof PROTOCOL_VERSION;
74
+ readonly schemaVersion: typeof SCHEMA_VERSION;
75
+ readonly documentId: DocumentId;
76
+ readonly replicaId: ReplicaId;
77
+ readonly revision: number;
78
+ readonly nextLocalSequence: LocalSequence;
79
+ readonly cursor: Sequence;
80
+ readonly committed: Shared;
81
+ readonly committedIds: ReadonlyArray<string>;
82
+ readonly pending: ReadonlyArray<Operation>;
83
+ /** The server history `cursor` points into, once an exchange has named one. */
84
+ readonly epoch?: string;
85
+ }
86
+ /**
87
+ * What the promise-based edge adapter consumes; the Effect `Transport` service
88
+ * is the primary seam.
89
+ */
90
+ export interface TransportClient {
91
+ /** `epoch` is the server history the replica's cursor points into, when it knows one. */
92
+ exchange(cursor: Sequence, pending: ReadonlyArray<Operation>, epoch?: string | undefined): Promise<unknown>;
93
+ }
94
+ /** A redacted view of a replica's state, for a UI to explain and recover. */
95
+ export interface ReplicaStatus {
96
+ readonly pending: number;
97
+ readonly cursor: Sequence;
98
+ /** The last exchange failure, cleared by a successful exchange. */
99
+ readonly lastError: string | undefined;
100
+ /** Operations the server refused, most recent first, with its reason when it gave one. */
101
+ readonly rejected: ReadonlyArray<Rejection>;
102
+ /**
103
+ * The server history the cursor points into, once a server named one. A new
104
+ * one means the server was reset: what the replica had committed is gone.
105
+ */
106
+ readonly epoch: Option.Option<string>;
107
+ }
108
+ /**
109
+ * An operation the server refused, and why, when it said. It carries the
110
+ * operation itself: the replica drops it from the outbox in the same step,
111
+ * so what it changed can be read from here rather than looked up in time.
112
+ */
113
+ export interface Rejection {
114
+ readonly opId: OpId;
115
+ readonly reason: Option.Option<string>;
116
+ readonly operation: Operation;
117
+ }
118
+ /**
119
+ * A consistent status and optimistic-shared pair, read from one replica state.
120
+ * `Replica.changes` emits it so a UI can hold a single subscription.
121
+ */
122
+ export interface ReplicaSnapshot<Shared> {
123
+ readonly status: ReplicaStatus;
124
+ readonly shared: Shared;
125
+ /** The server-confirmed state the optimistic `shared` is built on. */
126
+ readonly committed: Shared;
127
+ /**
128
+ * The local sequence the next submitted operation takes. Only a successful
129
+ * submit moves it, so a caller that submits one Message at a time can tell
130
+ * from one snapshot whether `shared` already holds it.
131
+ */
132
+ readonly nextLocalSequence: LocalSequence;
133
+ }
134
+ export interface Replica<Message, Shared> {
135
+ /** The id this replica's operations carry, one per tab: what its commits are stamped with. */
136
+ readonly replicaId: ReplicaId;
137
+ /** The optimistic projection: committed state with pending operations replayed. */
138
+ readonly shared: Effect.Effect<Shared>;
139
+ /**
140
+ * The server-confirmed state through `cursor`, with no pending operation
141
+ * applied. A pending edit reaches it only once the server commits it, and a
142
+ * rejected one never does.
143
+ */
144
+ readonly committed: Effect.Effect<Shared>;
145
+ readonly pending: Effect.Effect<ReadonlyArray<Operation>>;
146
+ readonly cursor: Effect.Effect<Sequence>;
147
+ /**
148
+ * Waiting/recovery information without exposing Messages or the Model. It is a
149
+ * snapshot; `statusChanges` re-emits it after every submit and exchange.
150
+ */
151
+ readonly status: Effect.Effect<ReplicaStatus>;
152
+ /** The status, re-emitted after every submit and exchange. */
153
+ readonly statusChanges: Stream.Stream<ReplicaStatus>;
154
+ /**
155
+ * The status and the optimistic shared value together, re-emitted after every
156
+ * submit and exchange, so a UI can subscribe once instead of to both.
157
+ */
158
+ readonly changes: Stream.Stream<ReplicaSnapshot<Shared>>;
159
+ /** The status, `shared`, `committed` and next local sequence, read from one replica state. */
160
+ readonly snapshot: Effect.Effect<ReplicaSnapshot<Shared>>;
161
+ /** Records a durable Message in the outbox and applies it optimistically. */
162
+ submit(message: Message): Effect.Effect<void, ReplicaError>;
163
+ /** Reconciles against the server. The `Transport` service must be provided. */
164
+ readonly synchronize: Effect.Effect<void, ReplicaError | TransportError, Transport>;
165
+ /**
166
+ * The exchange loop: exchanges once, then after every `submit` and every
167
+ * notice on the transport's `changes`, until the replica closes or the fiber
168
+ * is interrupted. A failed exchange is recorded
169
+ * in `status.lastError` and retried on a backoff (from 0.5 s, doubling up to
170
+ * 30 s), or at once on the next `submit`, so the fiber never fails. Fork it
171
+ * with `Effect.forkScoped` and provide `Transport`.
172
+ */
173
+ readonly start: Effect.Effect<void, never, Transport>;
174
+ readonly close: Effect.Effect<void>;
175
+ }
176
+ export interface SyncDefinition<Message, Shared, MessageEncoded, SharedEncoded> {
177
+ readonly documentId: DocumentId;
178
+ readonly message: Schema.Codec<Message, MessageEncoded, never, never>;
179
+ readonly shared: Schema.Codec<Shared, SharedEncoded, never, never>;
180
+ readonly empty: Shared;
181
+ readonly durable: (message: Message) => boolean;
182
+ readonly replay: (shared: Shared, message: Message) => Shared;
183
+ /**
184
+ * Optional. Merges a durable Message into the one submitted before it, while that one
185
+ * has not been sent: one operation instead of two, for a burst of typing. Replaying the
186
+ * result must equal replaying `last` then `next`. Undefined keeps them apart.
187
+ */
188
+ readonly coalesce?: ((last: Message, next: Message) => Message | undefined) | undefined;
189
+ /**
190
+ * Optional. Writes what the server's commit decided into a durable Message, on the
191
+ * server only: the journal stores, reduces and sends the stamped Message, so every
192
+ * replica replays the same one in place of what it sent.
193
+ */
194
+ readonly stamp?: ((message: Message, commit: CommitStamp) => Message) | undefined;
195
+ }
196
+ /**
197
+ * What a commit decided, for `stamp`: the operation's place in the order, who
198
+ * committed it, and from which replica. `actorId` is the principal, shared by
199
+ * every tab a person has open; `replicaId` tells those tabs apart.
200
+ */
201
+ export interface CommitStamp {
202
+ readonly sequence: number;
203
+ readonly actorId: string;
204
+ readonly replicaId: string;
205
+ }
206
+ /**
207
+ * A document's protocol. `Durable` is what a replica's `submit` takes: the
208
+ * durable subset for a contract from `Sync.forApplication(App).make`, every
209
+ * Message for one from `Sync.define`, which checks `durable` when called.
210
+ */
211
+ export interface Sync<Message, Shared, Durable = Message> {
212
+ readonly documentId: DocumentId;
213
+ /** Whether a Message is one the replica records and replays. */
214
+ readonly durable: (message: Message) => boolean;
215
+ /**
216
+ * Low-level wire codecs for adapters and the transport. Most applications use
217
+ * `journalContract` and `openReplica`; these are exposed for a custom
218
+ * transport or a server that must speak the operation envelope directly.
219
+ */
220
+ readonly codec: {
221
+ readonly normalizeOperation: (input: unknown) => Operation;
222
+ readonly operationFrom: (input: unknown, documentId: DocumentId) => Operation;
223
+ readonly committedFrom: (input: unknown, documentId: DocumentId) => CommittedOperation;
224
+ readonly decodeExchange: (input: unknown) => Exchange<Shared>;
225
+ };
226
+ /** The codecs and pure reducer `foldkit-durable`'s `makeJournal` consumes. */
227
+ readonly journalContract: () => JournalContract<Operation, Shared>;
228
+ /**
229
+ * Opens the replica a store holds. Its id is the store's: read back, or minted
230
+ * when the store is empty, so two stores never share one. In a browser the
231
+ * store is `Sync.tabStorage(name)`, one per tab.
232
+ */
233
+ readonly openReplica: (storage: Storage, options?: OpenReplicaOptions) => Effect.Effect<Replica<Durable, Shared>, ReplicaError>;
234
+ }
235
+ export interface OpenReplicaOptions {
236
+ /**
237
+ * The id the store must hold, for a test asserting operation ids or a replica
238
+ * a server names. It names one store, never a person: operation ids are
239
+ * `replicaId:localSequence`, so two stores under one id (a person's second
240
+ * browser) reuse ids the journal refuses.
241
+ */
242
+ readonly replicaId?: ReplicaId | undefined;
243
+ }
244
+ /** Structural match for `foldkit-durable`'s journal options; Sync stays independent. */
245
+ export interface JournalContract<Operation, Shared> {
246
+ /** The replica each operation came from, which Durable binds to its first committer. */
247
+ readonly replicaId: (operation: Operation) => string;
248
+ /** Sync's operation id includes the replica, even after Durable compacts its payload. */
249
+ readonly legacyReplicaId: (opId: string) => string;
250
+ readonly operation: {
251
+ /** Operations are stored in their encoded form, so this is the identity. */
252
+ readonly encode: (operation: Operation) => Operation;
253
+ readonly decode: (input: unknown) => Operation;
254
+ };
255
+ readonly snapshot: {
256
+ readonly encode: (snapshot: Shared) => unknown;
257
+ readonly decode: (input: unknown) => Shared;
258
+ };
259
+ readonly empty: () => Shared;
260
+ readonly reduce: (snapshot: Shared, operation: Operation) => Shared;
261
+ /** Present when the definition stamps: Durable's `stamp`, over the operation's Message. */
262
+ readonly stamp?: (operation: Operation, commit: {
263
+ readonly sequence: number;
264
+ readonly actorId: string;
265
+ }) => Operation;
266
+ }
267
+ /**
268
+ * Binds the replicated-state protocol to one application contract.
269
+ *
270
+ * The returned codecs decide what is a valid operation and what the shared
271
+ * projection means; the replica owns the local outbox, optimistic projection,
272
+ * and reconciliation as Effects, and never runs a second reducer.
273
+ */
274
+ export declare const defineSync: <Message, Shared, MessageEncoded, SharedEncoded>(definition: SyncDefinition<Message, Shared, MessageEncoded, SharedEncoded>) => Sync<Message, Shared>;
275
+ export {};
276
+ //# sourceMappingURL=sync.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"sync.d.ts","names":[],"sources":["../src/sync.ts"],"mappings":";;;;;;cAyCM;cACA;;cAGA,iBAAe,OAAA;;;;;;;;;;YAUT,mBAAmB,gBAAgB;;cAGzC,iBAAe,OAAA;;;;;;;;;;;;;YAMT,4BAA4B,gBAAgB;;qBAiB3C;EACX,WAAS,OAAA;EACT,SAAO,OAAA;EACP,aAAW,OAAA;EACX,iBAAe,OAAA;;iBAKA,WAAW;WACjB,QAAQ;WACR,OAAO;;iBAGD,SAAS;;WAEf,YAAY;WACZ,UAAU,cAAc;;;;;WAKxB,UAAU;aAAyB,MAAM;aAAe;;;WAExD,eAAe,cAAc;;WAE7B,aAAa,WAAW;;WAExB;;;;;;WAMA;;iBAGM,aAAa;WACnB,wBAAwB;WACxB,sBAAsB;WACtB,YAAY;WACZ,WAAW;WACX;WACA,mBAAmB;WACnB,QAAQ;WACR,WAAW;WACX,cAAc;WACd,SAAS,cAAc;;WAEvB;;;;;;iBAOM;;EAEf,SACE,QAAQ,UACR,SAAS,cAAc,YACvB,6BACC;;;iBAIY;WACN;WACA,QAAQ;;WAER;;WAEA,UAAU,cAAc;;;;;WAKxB,OAAO,OAAO;;;;;;;iBAQR;WACN,MAAM;WACN,QAAQ,OAAO;WACf,WAAW;;;;;;iBAOL,gBAAgB;WACtB,QAAQ;WACR,QAAQ;;WAER,WAAW;;;;;;WAMX,mBAAmB;;iBAGb,QAAQ,SAAS;;WAEvB,WAAW;;WAEX,QAAQ,OAAO,OAAO;;;;;;WAMtB,WAAW,OAAO,OAAO;WACzB,SAAS,OAAO,OAAO,cAAc;WACrC,QAAQ,OAAO,OAAO;;;;;WAKtB,QAAQ,OAAO,OAAO;;WAEtB,eAAe,OAAO,OAAO;;;;;WAK7B,SAAS,OAAO,OAAO,gBAAgB;;WAEvC,UAAU,OAAO,OAAO,gBAAgB;;EAIjD,OAAO,SAAS,UAAU,OAAO,aAAa;;WAErC,aAAa,OAAO,aAAa,eAAe,gBAAgB;;;;;;;;;WAShE,OAAO,OAAO,oBAAoB;WAClC,OAAO,OAAO;;iBAGR,eAAe,SAAS,QAAQ,gBAAgB;WACtD,YAAY;WACZ,SAAS,OAAO,MAAM,SAAS;WAC/B,QAAQ,OAAO,MAAM,QAAQ;WAC7B,OAAO;WACP,UAAU,SAAS;WACnB,SAAS,QAAQ,QAAQ,SAAS,YAAY;;;;;;WAM9C,aAAa,MAAM,SAAS,MAAM,YAAY;;;;;;WAM9C,UAAU,SAAS,SAAS,QAAQ,gBAAgB;;;;;;;iBAQ9C;WACN;WACA;WACA;;;;;;;iBAQM,KAAK,SAAS,QAAQ,UAAU;WACtC,YAAY;;WAEZ,UAAU,SAAS;;;;;;WAMnB;aACE,qBAAqB,mBAAmB;aACxC,gBAAgB,gBAAgB,YAAY,eAAe;aAC3D,gBAAgB,gBAAgB,YAAY,eAAe;aAC3D,iBAAiB,mBAAmB,SAAS;;;WAG/C,uBAAuB,gBAAgB,WAAW;;;;;;WAMlD,cACP,SAAS,SACT,UAAU,uBACP,OAAO,OAAO,QAAQ,SAAS,SAAS;;iBAG9B;;;;;;;WAON,YAAY;;;iBAIN,gBAAgB,WAAW;;WAEjC,YAAY,WAAW;;WAEvB,kBAAkB;WAClB;;aAEE,SAAS,WAAW,cAAc;aAClC,SAAS,mBAAmB;;WAE9B;aACE,SAAS,UAAU;aACnB,SAAS,mBAAmB;;WAE9B,aAAa;WACb,SAAS,UAAU,QAAQ,WAAW,cAAc;;WAEpD,SACP,WAAW,WACX;aAAmB;aAA2B;QAC3C;;;;;;;;;qBAUM,aAAc,SAAS,QAAQ,gBAAgB,eAAa,YAC3D,eAAe,SAAS,QAAQ,gBAAgB,mBAC3D,KAAK,SAAS"}