foldkit-sync 0.1.0 → 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.
- package/README.md +30 -13
- package/dist/index.d.mts +113 -62
- package/dist/index.d.mts.map +1 -1
- package/dist/index.mjs +317 -183
- package/dist/index.mjs.map +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -4,6 +4,12 @@ A local-first replica of a shared Foldkit projection. The application's Message
|
|
|
4
4
|
union and `update` stay authoritative; sync wraps them rather than introducing a
|
|
5
5
|
second reducer.
|
|
6
6
|
|
|
7
|
+
It is the **client half** of [replicated Foldkit state](https://github.com/doeixd/foldkit-plus/blob/main/docs/replication.md).
|
|
8
|
+
Reach for it when clients must keep working offline and converge later, with
|
|
9
|
+
`foldkit-durable` (or any server that orders operations) as the authority. The
|
|
10
|
+
[guide](https://github.com/doeixd/foldkit-plus/blob/main/docs/replication.md) covers the mental model and when not to use
|
|
11
|
+
it.
|
|
12
|
+
|
|
7
13
|
```ts
|
|
8
14
|
import { Effect } from 'effect'
|
|
9
15
|
import { defineSync, indexedDb, layerFromPromise } from 'foldkit-sync'
|
|
@@ -11,7 +17,10 @@ import { defineSync, indexedDb, layerFromPromise } from 'foldkit-sync'
|
|
|
11
17
|
const Sync = defineSync({ ... })
|
|
12
18
|
|
|
13
19
|
const replica = await Effect.runPromise(
|
|
14
|
-
|
|
20
|
+
Effect.gen(function* () {
|
|
21
|
+
const storage = yield* indexedDb('todos-tab-1')
|
|
22
|
+
return yield* Sync.openReplica('tab-1', storage)
|
|
23
|
+
}),
|
|
15
24
|
)
|
|
16
25
|
await Effect.runPromise(
|
|
17
26
|
replica.submit(Message.CreatedTodo({ id: crypto.randomUUID(), title: 'Milk' })),
|
|
@@ -30,15 +39,20 @@ const shared = Effect.runSync(replica.shared)
|
|
|
30
39
|
- Reconciliation: committed operations are replayed in order, acknowledged or
|
|
31
40
|
refused pending entries are dropped, and a checkpoint replaces the compacted
|
|
32
41
|
prefix.
|
|
42
|
+
- A redacted status (`replica.status`): the pending count, the cursor, the last
|
|
43
|
+
exchange failure, and the operations the server refused — enough for a UI to
|
|
44
|
+
explain and recover without exposing Messages or the Model.
|
|
33
45
|
- Strict decoding: an operation is always validated with the application's
|
|
34
46
|
Message schema, and a Message the contract does not call durable is refused.
|
|
35
47
|
- Presence (`createPresence`): an ephemeral, TTL'd peer registry, deliberately
|
|
36
48
|
outside the durable log. A peer that stops refreshing is dropped, not
|
|
37
|
-
replayed.
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
—
|
|
49
|
+
replayed. It is an Effect driven by the `Clock` (so a `TestClock` makes the
|
|
50
|
+
TTL deterministic), peers live in a `Ref`, and the channel is a `PubSub`.
|
|
51
|
+
Every value is decoded through the required `decodeValue` before it is stored,
|
|
52
|
+
so a hostile peer cannot inject a value your `Update` type does not describe.
|
|
53
|
+
Presence can travel over a socket — `socketPresenceChannel` on the client and
|
|
54
|
+
`servePresence` fanning through a `createPresenceHub` on the server — or
|
|
55
|
+
in-process via `loopbackPresenceChannel`.
|
|
42
56
|
- The transport seam (`Transport`): an Effect service with a loopback layer, a
|
|
43
57
|
bridge to and from the promise client the replica speaks, and a WebSocket
|
|
44
58
|
client layer. The socket reconnects on an exponential, jittered backoff and
|
|
@@ -96,18 +110,21 @@ write cannot cause timestamp reuse after reload:
|
|
|
96
110
|
import { Effect } from 'effect'
|
|
97
111
|
import { indexedDb, openLwwClock } from 'foldkit-sync'
|
|
98
112
|
|
|
99
|
-
const clock = await
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
})
|
|
113
|
+
const clock = await Effect.runPromise(
|
|
114
|
+
Effect.gen(function* () {
|
|
115
|
+
const storage = yield* indexedDb('todos-tab-a-clock')
|
|
116
|
+
return yield* openLwwClock({ documentId: 'todos', replicaId: 'tab-a', storage })
|
|
117
|
+
}),
|
|
118
|
+
)
|
|
104
119
|
try {
|
|
105
|
-
const stamp = await
|
|
120
|
+
const stamp = await Effect.runPromise(
|
|
121
|
+
clock.next(Effect.runSync(replica.shared).title.stamp.counter),
|
|
122
|
+
)
|
|
106
123
|
await Effect.runPromise(
|
|
107
124
|
replica.submit({ _tag: 'Renamed', title: { stamp, value: 'Milk' } }),
|
|
108
125
|
)
|
|
109
126
|
} finally {
|
|
110
|
-
await clock.close
|
|
127
|
+
await Effect.runPromise(clock.close)
|
|
111
128
|
}
|
|
112
129
|
```
|
|
113
130
|
|
package/dist/index.d.mts
CHANGED
|
@@ -1,14 +1,4 @@
|
|
|
1
|
-
import { Context, Duration, Effect, Layer, Metric, Schema } from "effect";
|
|
2
|
-
//#region src/indexedDb.d.ts
|
|
3
|
-
/** Persists a replica's state with compare-and-swap on its revision. */
|
|
4
|
-
interface Storage<State = unknown> {
|
|
5
|
-
load(): Promise<unknown>;
|
|
6
|
-
save(state: State, expectedRevision: number | null): Promise<void>;
|
|
7
|
-
close(): void;
|
|
8
|
-
}
|
|
9
|
-
/** One database per document/replica; CAS prevents two tabs from sharing a writer identity. */
|
|
10
|
-
export declare const indexedDb: <State = unknown>(name: string, factory?: IDBFactory) => Promise<Storage<State>>;
|
|
11
|
-
//#endregion
|
|
1
|
+
import { Clock, Config, Context, Duration, Effect, Layer, Metric, PubSub, Schema, Scope } from "effect";
|
|
12
2
|
//#region src/errors.d.ts
|
|
13
3
|
declare const StorageError_base: Schema.Class<StorageError, Schema.TaggedStruct<"StorageError", {
|
|
14
4
|
readonly message: Schema.String;
|
|
@@ -16,6 +6,12 @@ declare const StorageError_base: Schema.Class<StorageError, Schema.TaggedStruct<
|
|
|
16
6
|
}>, import("effect/Cause").YieldableError>;
|
|
17
7
|
/** The persisted storage could not be read or written. */
|
|
18
8
|
export declare class StorageError extends StorageError_base {}
|
|
9
|
+
declare const UnsupportedClockVersionError_base: Schema.Class<UnsupportedClockVersionError, Schema.TaggedStruct<"UnsupportedClockVersionError", {
|
|
10
|
+
readonly schemaVersion: Schema.NullOr<Schema.Number>;
|
|
11
|
+
readonly message: Schema.String;
|
|
12
|
+
}>, import("effect/Cause").YieldableError>;
|
|
13
|
+
/** The stored clock state targets a schema version this build does not support. */
|
|
14
|
+
export declare class UnsupportedClockVersionError extends UnsupportedClockVersionError_base {}
|
|
19
15
|
declare const WrongReplicaStorageError_base: Schema.Class<WrongReplicaStorageError, Schema.TaggedStruct<"WrongReplicaStorageError", {
|
|
20
16
|
readonly documentId: Schema.String;
|
|
21
17
|
readonly replicaId: Schema.String;
|
|
@@ -59,33 +55,72 @@ declare const ReplicaClosedError_base: Schema.Class<ReplicaClosedError, Schema.T
|
|
|
59
55
|
}>, import("effect/Cause").YieldableError>;
|
|
60
56
|
/** The replica was closed while work was still being submitted. */
|
|
61
57
|
export declare class ReplicaClosedError extends ReplicaClosedError_base {}
|
|
62
|
-
|
|
58
|
+
declare const UnsupportedReplicaVersionError_base: Schema.Class<UnsupportedReplicaVersionError, Schema.TaggedStruct<"UnsupportedReplicaVersionError", {
|
|
59
|
+
readonly protocolVersion: Schema.NullOr<Schema.Number>;
|
|
60
|
+
readonly schemaVersion: Schema.NullOr<Schema.Number>;
|
|
61
|
+
readonly message: Schema.String;
|
|
62
|
+
}>, import("effect/Cause").YieldableError>;
|
|
63
|
+
/** The stored replica state targets a protocol or schema version this build does not support. */
|
|
64
|
+
export declare class UnsupportedReplicaVersionError extends UnsupportedReplicaVersionError_base {}
|
|
65
|
+
type ReplicaError = StorageError | WrongReplicaStorageError | InvalidReplicaHistoryError | UnsupportedReplicaVersionError | InvalidOutboxError | CheckpointRegressionError | CommittedOrderError | ForeignRejectionError | ReplicaClosedError;
|
|
66
|
+
//#endregion
|
|
67
|
+
//#region src/indexedDb.d.ts
|
|
68
|
+
/** Persists a replica's state with compare-and-swap on its revision. */
|
|
69
|
+
interface Storage<State = unknown> {
|
|
70
|
+
load: () => Effect.Effect<unknown, StorageError>;
|
|
71
|
+
save: (state: State, expectedRevision: number | null) => Effect.Effect<void, StorageError>;
|
|
72
|
+
/** Idempotent; the caller closes the connection explicitly. */
|
|
73
|
+
close: Effect.Effect<void>;
|
|
74
|
+
}
|
|
75
|
+
/** One database per document/replica; CAS prevents two tabs from sharing a writer identity. */
|
|
76
|
+
export declare const indexedDb: <State = unknown>(name: Config.Config<string> | string, factory?: IDBFactory) => Effect.Effect<Storage<State>, StorageError, Scope.Scope>;
|
|
77
|
+
//#endregion
|
|
78
|
+
//#region src/ids.d.ts
|
|
79
|
+
/** Identifies the replicated document a replica or operation belongs to. */
|
|
80
|
+
export declare const DocumentId: Schema.brand<Schema.NonEmptyString, "@foldkit-sync/DocumentId">;
|
|
81
|
+
export type DocumentId = typeof DocumentId.Type;
|
|
82
|
+
/** Identifies one replica (writer identity) within a document. */
|
|
83
|
+
export declare const ReplicaId: Schema.brand<Schema.NonEmptyString, "@foldkit-sync/ReplicaId">;
|
|
84
|
+
export type ReplicaId = typeof ReplicaId.Type;
|
|
85
|
+
/** The stable identity of one operation within a document. */
|
|
86
|
+
export declare const OpId: Schema.brand<Schema.NonEmptyString, "@foldkit-sync/OpId">;
|
|
87
|
+
export type OpId = typeof OpId.Type;
|
|
88
|
+
export declare const documentId: (value: string) => DocumentId;
|
|
89
|
+
export declare const replicaId: (value: string) => ReplicaId;
|
|
90
|
+
export declare const opId: (value: string) => OpId;
|
|
63
91
|
//#endregion
|
|
64
92
|
//#region src/lww.d.ts
|
|
65
93
|
/** A logical write time; replica ids break concurrent ties using UTF-16 order. */
|
|
66
94
|
declare const Stamp: Schema.Struct<{
|
|
67
95
|
readonly counter: Schema.Number;
|
|
68
|
-
readonly replicaId: Schema.NonEmptyString
|
|
96
|
+
readonly replicaId: Schema.brand<Schema.NonEmptyString, "@foldkit-sync/ReplicaId">;
|
|
69
97
|
}>;
|
|
70
98
|
declare const ClockState: Schema.Struct<{
|
|
71
99
|
readonly schemaVersion: Schema.Literal<1>;
|
|
72
|
-
readonly documentId: Schema.NonEmptyString
|
|
73
|
-
readonly replicaId: Schema.NonEmptyString
|
|
100
|
+
readonly documentId: Schema.brand<Schema.NonEmptyString, "@foldkit-sync/DocumentId">;
|
|
101
|
+
readonly replicaId: Schema.brand<Schema.NonEmptyString, "@foldkit-sync/ReplicaId">;
|
|
74
102
|
readonly revision: Schema.Number;
|
|
75
103
|
}>;
|
|
76
104
|
type LwwClockState = typeof ClockState.Type;
|
|
77
105
|
interface LwwClock {
|
|
78
106
|
/** Persists a timestamp beyond the saved counter and supplied observation. */
|
|
79
|
-
next(observedCounter?: number)
|
|
80
|
-
/** Drains accepted allocations
|
|
81
|
-
close
|
|
107
|
+
next: (observedCounter?: number) => Effect.Effect<typeof Stamp.Type, StorageError>;
|
|
108
|
+
/** Drains accepted allocations, then closes storage. Repeated calls no-op. */
|
|
109
|
+
close: Effect.Effect<void>;
|
|
82
110
|
}
|
|
83
|
-
/**
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
111
|
+
/**
|
|
112
|
+
* Opens a durable clock over the caller's storage.
|
|
113
|
+
*
|
|
114
|
+
* Allocations are serialized through a `SynchronizedRef` and each persists before
|
|
115
|
+
* its stamp is returned. A crash after the save may skip a timestamp but never
|
|
116
|
+
* reuse one. Storage is owned by the caller; a failed open closes it so a partial
|
|
117
|
+
* initialization does not leak the connection.
|
|
118
|
+
*/
|
|
119
|
+
export declare const openLwwClock: (options: {
|
|
120
|
+
readonly documentId: DocumentId;
|
|
121
|
+
readonly replicaId: ReplicaId;
|
|
87
122
|
readonly storage: Storage<LwwClockState>;
|
|
88
|
-
}) =>
|
|
123
|
+
}) => Effect.Effect<LwwClock, StorageError | UnsupportedClockVersionError>;
|
|
89
124
|
/**
|
|
90
125
|
* A schema and reducer helper for a last-writer-wins register.
|
|
91
126
|
* Allocate a unique stamp per write before dispatch, and retain it in the Message.
|
|
@@ -95,40 +130,43 @@ export declare const lwwRegister: <Value, Encoded, RD, RE>(value: Schema.Codec<V
|
|
|
95
130
|
schema: Schema.Struct<{
|
|
96
131
|
readonly stamp: Schema.Struct<{
|
|
97
132
|
readonly counter: Schema.Number;
|
|
98
|
-
readonly replicaId: Schema.NonEmptyString
|
|
133
|
+
readonly replicaId: Schema.brand<Schema.NonEmptyString, "@foldkit-sync/ReplicaId">;
|
|
99
134
|
}>;
|
|
100
135
|
readonly value: Schema.Codec<Value, Encoded, RD, RE>;
|
|
101
136
|
}>;
|
|
102
137
|
merge: (left: {
|
|
103
138
|
readonly stamp: {
|
|
104
139
|
readonly counter: number;
|
|
105
|
-
readonly replicaId: string
|
|
140
|
+
readonly replicaId: string & import("effect/Brand").Brand<"@foldkit-sync/ReplicaId">;
|
|
106
141
|
};
|
|
107
142
|
readonly value: Value;
|
|
108
143
|
}, right: {
|
|
109
144
|
readonly stamp: {
|
|
110
145
|
readonly counter: number;
|
|
111
|
-
readonly replicaId: string
|
|
146
|
+
readonly replicaId: string & import("effect/Brand").Brand<"@foldkit-sync/ReplicaId">;
|
|
112
147
|
};
|
|
113
148
|
readonly value: Value;
|
|
114
149
|
}) => {
|
|
115
150
|
readonly stamp: {
|
|
116
151
|
readonly counter: number;
|
|
117
|
-
readonly replicaId: string
|
|
152
|
+
readonly replicaId: string & import("effect/Brand").Brand<"@foldkit-sync/ReplicaId">;
|
|
118
153
|
};
|
|
119
154
|
readonly value: Value;
|
|
120
155
|
};
|
|
121
156
|
};
|
|
122
157
|
//#endregion
|
|
123
158
|
//#region src/sync.d.ts
|
|
159
|
+
/** Wire and persisted-format versions. A bump must handle the older value explicitly. */
|
|
160
|
+
declare const PROTOCOL_VERSION = 1;
|
|
161
|
+
declare const SCHEMA_VERSION = 1;
|
|
124
162
|
/** A client-authored operation envelope. `message` is the application's encoded Message. */
|
|
125
163
|
declare const OperationSchema: Schema.Struct<{
|
|
126
164
|
readonly protocolVersion: Schema.Literal<1>;
|
|
127
165
|
readonly schemaVersion: Schema.Literal<1>;
|
|
128
|
-
readonly documentId: Schema.NonEmptyString
|
|
129
|
-
readonly replicaId: Schema.NonEmptyString
|
|
166
|
+
readonly documentId: Schema.brand<Schema.NonEmptyString, "@foldkit-sync/DocumentId">;
|
|
167
|
+
readonly replicaId: Schema.brand<Schema.NonEmptyString, "@foldkit-sync/ReplicaId">;
|
|
130
168
|
readonly localSequence: Schema.Number;
|
|
131
|
-
readonly opId: Schema.NonEmptyString
|
|
169
|
+
readonly opId: Schema.brand<Schema.NonEmptyString, "@foldkit-sync/OpId">;
|
|
132
170
|
readonly baseCursor: Schema.Number;
|
|
133
171
|
readonly message: Schema.Unknown;
|
|
134
172
|
}>;
|
|
@@ -139,10 +177,10 @@ declare const CommittedSchema: Schema.Struct<{
|
|
|
139
177
|
readonly actorId: Schema.NonEmptyString;
|
|
140
178
|
readonly protocolVersion: Schema.Literal<1>;
|
|
141
179
|
readonly schemaVersion: Schema.Literal<1>;
|
|
142
|
-
readonly documentId: Schema.NonEmptyString
|
|
143
|
-
readonly replicaId: Schema.NonEmptyString
|
|
180
|
+
readonly documentId: Schema.brand<Schema.NonEmptyString, "@foldkit-sync/DocumentId">;
|
|
181
|
+
readonly replicaId: Schema.brand<Schema.NonEmptyString, "@foldkit-sync/ReplicaId">;
|
|
144
182
|
readonly localSequence: Schema.Number;
|
|
145
|
-
readonly opId: Schema.NonEmptyString
|
|
183
|
+
readonly opId: Schema.brand<Schema.NonEmptyString, "@foldkit-sync/OpId">;
|
|
146
184
|
readonly baseCursor: Schema.Number;
|
|
147
185
|
readonly message: Schema.Unknown;
|
|
148
186
|
}>;
|
|
@@ -160,15 +198,15 @@ interface Checkpoint<Shared> {
|
|
|
160
198
|
}
|
|
161
199
|
interface Exchange<Shared> {
|
|
162
200
|
readonly operations: ReadonlyArray<unknown>;
|
|
163
|
-
readonly rejected: ReadonlyArray<
|
|
201
|
+
readonly rejected: ReadonlyArray<OpId>;
|
|
164
202
|
/** Sends from the request that are durably committed, so the replica can drop them. */
|
|
165
|
-
readonly acknowledged?: ReadonlyArray<
|
|
203
|
+
readonly acknowledged?: ReadonlyArray<OpId> | undefined;
|
|
166
204
|
/** The snapshot a replica predating compaction adopts in place of the log. */
|
|
167
205
|
readonly checkpoint?: Checkpoint<Shared> | undefined;
|
|
168
206
|
}
|
|
169
207
|
interface ReplicaState<Shared> {
|
|
170
|
-
readonly protocolVersion:
|
|
171
|
-
readonly schemaVersion:
|
|
208
|
+
readonly protocolVersion: typeof PROTOCOL_VERSION;
|
|
209
|
+
readonly schemaVersion: typeof SCHEMA_VERSION;
|
|
172
210
|
readonly documentId: string;
|
|
173
211
|
readonly replicaId: string;
|
|
174
212
|
readonly revision: number;
|
|
@@ -185,18 +223,29 @@ interface ReplicaState<Shared> {
|
|
|
185
223
|
interface TransportClient {
|
|
186
224
|
exchange(cursor: number, pending: ReadonlyArray<Operation>): Promise<unknown>;
|
|
187
225
|
}
|
|
226
|
+
/** A redacted view of a replica's state, for a UI to explain and recover. */
|
|
227
|
+
interface ReplicaStatus {
|
|
228
|
+
readonly pending: number;
|
|
229
|
+
readonly cursor: number;
|
|
230
|
+
/** The last exchange failure, cleared by a successful exchange. */
|
|
231
|
+
readonly lastError: string | undefined;
|
|
232
|
+
/** Operations the server refused, most recent first. */
|
|
233
|
+
readonly rejected: ReadonlyArray<OpId>;
|
|
234
|
+
}
|
|
188
235
|
interface Replica<Message, Shared> {
|
|
189
236
|
/** The optimistic projection: committed state with pending operations replayed. */
|
|
190
237
|
readonly shared: Effect.Effect<Shared>;
|
|
191
238
|
readonly pending: Effect.Effect<ReadonlyArray<Operation>>;
|
|
192
239
|
readonly cursor: Effect.Effect<number>;
|
|
240
|
+
/** Waiting/recovery information without exposing Messages or the Model. */
|
|
241
|
+
readonly status: Effect.Effect<ReplicaStatus>;
|
|
193
242
|
readonly submit: (message: Message) => Effect.Effect<void, ReplicaError>;
|
|
194
243
|
/** Reconciles against the server. The `Transport` service must be provided. */
|
|
195
244
|
readonly synchronize: Effect.Effect<void, ReplicaError | TransportError, Transport>;
|
|
196
245
|
readonly close: Effect.Effect<void>;
|
|
197
246
|
}
|
|
198
247
|
interface SyncDefinition<Message, Shared, MessageEncoded, SharedEncoded> {
|
|
199
|
-
readonly documentId:
|
|
248
|
+
readonly documentId: DocumentId;
|
|
200
249
|
readonly message: Schema.Codec<Message, MessageEncoded, never, never>;
|
|
201
250
|
readonly shared: Schema.Codec<Shared, SharedEncoded, never, never>;
|
|
202
251
|
readonly empty: Shared;
|
|
@@ -204,12 +253,12 @@ interface SyncDefinition<Message, Shared, MessageEncoded, SharedEncoded> {
|
|
|
204
253
|
readonly replay: (shared: Shared, message: Message) => Shared;
|
|
205
254
|
}
|
|
206
255
|
interface Sync<Message, Shared> {
|
|
207
|
-
readonly documentId:
|
|
256
|
+
readonly documentId: DocumentId;
|
|
208
257
|
readonly normalizeOperation: (input: unknown) => Operation;
|
|
209
|
-
readonly operationFrom: (input: unknown, documentId:
|
|
210
|
-
readonly committedFrom: (input: unknown, documentId:
|
|
258
|
+
readonly operationFrom: (input: unknown, documentId: DocumentId) => Operation;
|
|
259
|
+
readonly committedFrom: (input: unknown, documentId: DocumentId) => Committed;
|
|
211
260
|
readonly decodeExchange: (input: unknown) => Exchange<Shared>;
|
|
212
|
-
readonly openReplica: (replicaId:
|
|
261
|
+
readonly openReplica: (replicaId: ReplicaId, storage: Storage<ReplicaState<Shared>>) => Effect.Effect<Replica<Message, Shared>, ReplicaError>;
|
|
213
262
|
}
|
|
214
263
|
/**
|
|
215
264
|
* Binds the replicated-state protocol to one application contract.
|
|
@@ -312,18 +361,20 @@ interface PresenceUpdate<Update> {
|
|
|
312
361
|
/**
|
|
313
362
|
* The ephemeral channel presence travels on.
|
|
314
363
|
*
|
|
315
|
-
*
|
|
364
|
+
* `updates` is the inbound bus a peer consumes; `publish` sends one to the bus.
|
|
365
|
+
* Splitting them keeps an inbound update from being echoed straight back out.
|
|
366
|
+
* This is deliberately not the durable transport: presence is broadcast, never
|
|
316
367
|
* journaled, so a dropped or duplicated update is harmless.
|
|
317
368
|
*/
|
|
318
369
|
interface PresenceChannel<Update> {
|
|
319
|
-
|
|
320
|
-
|
|
370
|
+
readonly updates: PubSub.PubSub<PresenceUpdate<Update>>;
|
|
371
|
+
readonly publish: (update: PresenceUpdate<Update>) => Effect.Effect<void>;
|
|
321
372
|
}
|
|
322
373
|
interface PresenceOptions<Update> {
|
|
323
374
|
/** This peer's identity on the channel. */
|
|
324
375
|
readonly id: string;
|
|
325
|
-
/**
|
|
326
|
-
readonly ttl:
|
|
376
|
+
/** How long a peer may go without refreshing before it is dropped. */
|
|
377
|
+
readonly ttl: Duration.Input;
|
|
327
378
|
/**
|
|
328
379
|
* Validates the untrusted value a peer sends before it is stored. Presence
|
|
329
380
|
* crosses a wire, so this is required rather than trusting the type
|
|
@@ -331,8 +382,6 @@ interface PresenceOptions<Update> {
|
|
|
331
382
|
*/
|
|
332
383
|
readonly decodeValue: (value: unknown) => Update;
|
|
333
384
|
readonly channel?: PresenceChannel<Update> | undefined;
|
|
334
|
-
/** Injectable clock, for tests. */
|
|
335
|
-
readonly now?: (() => number) | undefined;
|
|
336
385
|
}
|
|
337
386
|
interface PresencePeer<Update> {
|
|
338
387
|
readonly id: string;
|
|
@@ -341,26 +390,28 @@ interface PresencePeer<Update> {
|
|
|
341
390
|
}
|
|
342
391
|
interface Presence<Update> {
|
|
343
392
|
/** Sets this peer's value and broadcasts it. */
|
|
344
|
-
set(value: Update)
|
|
393
|
+
readonly set: (value: Update) => Effect.Effect<void>;
|
|
345
394
|
/** Removes this peer and broadcasts the departure. */
|
|
346
|
-
leave
|
|
395
|
+
readonly leave: Effect.Effect<void>;
|
|
347
396
|
/** Live peers, self included, with stale ones excluded. */
|
|
348
|
-
peers
|
|
397
|
+
readonly peers: Effect.Effect<ReadonlyArray<PresencePeer<Update>>>;
|
|
349
398
|
/** Drops expired peers; notifies if any went. */
|
|
350
|
-
prune
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
|
|
399
|
+
readonly prune: Effect.Effect<void>;
|
|
400
|
+
/** Notified when the peer set changes. */
|
|
401
|
+
readonly subscribe: (listener: () => void) => () => void;
|
|
402
|
+
/** Stops consuming the channel; the enclosing scope also does this on exit. */
|
|
403
|
+
readonly close: Effect.Effect<void>;
|
|
354
404
|
}
|
|
355
405
|
/**
|
|
356
406
|
* Tracks ephemeral peers with a time-to-live.
|
|
357
407
|
*
|
|
358
408
|
* Nothing here touches the durable log: presence is state a peer refreshes, and
|
|
359
|
-
* a peer that stops refreshing is dropped, not replayed.
|
|
409
|
+
* a peer that stops refreshing is dropped, not replayed. Time comes from the
|
|
410
|
+
* `Clock`, so a `TestClock` drives the TTL deterministically.
|
|
360
411
|
*/
|
|
361
|
-
export declare const createPresence: <Update>(options: PresenceOptions<Update>) => Presence<Update>;
|
|
412
|
+
export declare const createPresence: <Update>(options: PresenceOptions<Update>) => Effect.Effect<Presence<Update>, never, Scope.Scope | Clock.Clock>;
|
|
362
413
|
/** An in-process channel, for tests and single-process demos. */
|
|
363
|
-
export declare const loopbackPresenceChannel: <Update>() => PresenceChannel<Update
|
|
414
|
+
export declare const loopbackPresenceChannel: <Update>() => Effect.Effect<PresenceChannel<Update>>;
|
|
364
415
|
/** Broadcasts presence updates among connected peers. */
|
|
365
416
|
interface PresenceHub<Update> {
|
|
366
417
|
/** Registers a peer's send; returns a leave function. */
|
|
@@ -369,10 +420,10 @@ interface PresenceHub<Update> {
|
|
|
369
420
|
publish(update: PresenceUpdate<Update>): void;
|
|
370
421
|
}
|
|
371
422
|
export declare const createPresenceHub: <Update>() => PresenceHub<Update>;
|
|
372
|
-
/** A presence channel
|
|
373
|
-
export declare const socketPresenceChannel: <Update>(socket: SocketLike) => PresenceChannel<Update>;
|
|
423
|
+
/** A presence channel fed by frames arriving on a socket, sent back over it. */
|
|
424
|
+
export declare const socketPresenceChannel: <Update>(socket: SocketLike) => Effect.Effect<PresenceChannel<Update>, never, Scope.Scope>;
|
|
374
425
|
/** Serves presence frames on an accepted socket, fanning them through the hub. */
|
|
375
426
|
export declare const servePresence: <Update>(socket: SocketLike, hub: PresenceHub<Update>) => (() => void);
|
|
376
427
|
//#endregion
|
|
377
|
-
export type { Checkpoint, Committed, Exchange, ExchangeFrame, ExchangeReply, LwwClock, LwwClockState, Operation, Presence, PresenceChannel, PresenceHub, PresenceOptions, PresencePeer, PresenceUpdate, Replica, ReplicaError, ReplicaState, SocketLike, SocketOptions, Storage, Sync, SyncDefinition, TransportClient, TransportShape };
|
|
428
|
+
export type { Checkpoint, Committed, Exchange, ExchangeFrame, ExchangeReply, LwwClock, LwwClockState, Operation, Presence, PresenceChannel, PresenceHub, PresenceOptions, PresencePeer, PresenceUpdate, Replica, ReplicaError, ReplicaState, ReplicaStatus, SocketLike, SocketOptions, Storage, Sync, SyncDefinition, TransportClient, TransportShape };
|
|
378
429
|
//# sourceMappingURL=index.d.mts.map
|
package/dist/index.d.mts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.mts","names":[],"sources":["../src/indexedDb.ts","../src/
|
|
1
|
+
{"version":3,"file":"index.d.mts","names":[],"sources":["../src/errors.ts","../src/indexedDb.ts","../src/ids.ts","../src/lww.ts","../src/sync.ts","../src/transport.ts","../src/presence.ts"],"mappings":"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"}
|