foldkit-sync 0.1.0 → 0.3.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 +207 -16
- package/dist/index.d.mts +531 -187
- package/dist/index.d.mts.map +1 -1
- package/dist/index.mjs +903 -354
- package/dist/index.mjs.map +1 -1
- package/package.json +8 -2
package/dist/index.d.mts
CHANGED
|
@@ -1,14 +1,9 @@
|
|
|
1
|
-
import { Context, Duration, Effect, Layer, Metric, Schema } from "effect";
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
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 { Config, Context, Duration, Effect, Exit, Layer, Metric, PubSub, Schema, Scope, Stream } from "effect";
|
|
2
|
+
import { UrlRequest } from "foldkit/navigation";
|
|
3
|
+
import { Subscriptions } from "foldkit/subscription";
|
|
4
|
+
import * as Url from "foldkit/url";
|
|
5
|
+
import { AppScope, Contract, MergeConstructors, MergeFields, MessageSet, RunnableApplication, Surface, WritableProjection } from "foldkit-surface";
|
|
6
|
+
import { Document, HtmlBuilder } from "foldkit/html";
|
|
12
7
|
//#region src/errors.d.ts
|
|
13
8
|
declare const StorageError_base: Schema.Class<StorageError, Schema.TaggedStruct<"StorageError", {
|
|
14
9
|
readonly message: Schema.String;
|
|
@@ -16,6 +11,12 @@ declare const StorageError_base: Schema.Class<StorageError, Schema.TaggedStruct<
|
|
|
16
11
|
}>, import("effect/Cause").YieldableError>;
|
|
17
12
|
/** The persisted storage could not be read or written. */
|
|
18
13
|
export declare class StorageError extends StorageError_base {}
|
|
14
|
+
declare const UnsupportedClockVersionError_base: Schema.Class<UnsupportedClockVersionError, Schema.TaggedStruct<"UnsupportedClockVersionError", {
|
|
15
|
+
readonly schemaVersion: Schema.NullOr<Schema.Number>;
|
|
16
|
+
readonly message: Schema.String;
|
|
17
|
+
}>, import("effect/Cause").YieldableError>;
|
|
18
|
+
/** The stored clock state targets a schema version this build does not support. */
|
|
19
|
+
export declare class UnsupportedClockVersionError extends UnsupportedClockVersionError_base {}
|
|
19
20
|
declare const WrongReplicaStorageError_base: Schema.Class<WrongReplicaStorageError, Schema.TaggedStruct<"WrongReplicaStorageError", {
|
|
20
21
|
readonly documentId: Schema.String;
|
|
21
22
|
readonly replicaId: Schema.String;
|
|
@@ -29,6 +30,12 @@ declare const InvalidReplicaHistoryError_base: Schema.Class<InvalidReplicaHistor
|
|
|
29
30
|
}>, import("effect/Cause").YieldableError>;
|
|
30
31
|
/** The persisted replica history is internally inconsistent. */
|
|
31
32
|
export declare class InvalidReplicaHistoryError extends InvalidReplicaHistoryError_base {}
|
|
33
|
+
declare const InvalidExchangeError_base: Schema.Class<InvalidExchangeError, Schema.TaggedStruct<"InvalidExchangeError", {
|
|
34
|
+
readonly message: Schema.String;
|
|
35
|
+
readonly cause: Schema.optional<Schema.Unknown>;
|
|
36
|
+
}>, import("effect/Cause").YieldableError>;
|
|
37
|
+
/** The server's exchange response did not match the protocol schema. */
|
|
38
|
+
export declare class InvalidExchangeError extends InvalidExchangeError_base {}
|
|
32
39
|
declare const InvalidOutboxError_base: Schema.Class<InvalidOutboxError, Schema.TaggedStruct<"InvalidOutboxError", {
|
|
33
40
|
readonly message: Schema.String;
|
|
34
41
|
}>, import("effect/Cause").YieldableError>;
|
|
@@ -54,171 +61,74 @@ declare const ForeignRejectionError_base: Schema.Class<ForeignRejectionError, Sc
|
|
|
54
61
|
}>, import("effect/Cause").YieldableError>;
|
|
55
62
|
/** The server rejected an operation the replica never sent. */
|
|
56
63
|
export declare class ForeignRejectionError extends ForeignRejectionError_base {}
|
|
64
|
+
declare const ForeignAcknowledgementError_base: Schema.Class<ForeignAcknowledgementError, Schema.TaggedStruct<"ForeignAcknowledgementError", {
|
|
65
|
+
readonly opId: Schema.String;
|
|
66
|
+
readonly message: Schema.String;
|
|
67
|
+
}>, import("effect/Cause").YieldableError>;
|
|
68
|
+
/**
|
|
69
|
+
* The server answered an operation this request never sent, or both
|
|
70
|
+
* acknowledged and rejected it. Acting on either would let a faulty or hostile
|
|
71
|
+
* server delete local work.
|
|
72
|
+
*/
|
|
73
|
+
export declare class ForeignAcknowledgementError extends ForeignAcknowledgementError_base {}
|
|
57
74
|
declare const ReplicaClosedError_base: Schema.Class<ReplicaClosedError, Schema.TaggedStruct<"ReplicaClosedError", {
|
|
58
75
|
readonly message: Schema.String;
|
|
59
76
|
}>, import("effect/Cause").YieldableError>;
|
|
60
77
|
/** The replica was closed while work was still being submitted. */
|
|
61
78
|
export declare class ReplicaClosedError extends ReplicaClosedError_base {}
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
readonly
|
|
72
|
-
|
|
73
|
-
readonly replicaId: Schema.NonEmptyString;
|
|
74
|
-
readonly revision: Schema.Number;
|
|
75
|
-
}>;
|
|
76
|
-
type LwwClockState = typeof ClockState.Type;
|
|
77
|
-
interface LwwClock {
|
|
78
|
-
/** Persists a timestamp beyond the saved counter and supplied observation. */
|
|
79
|
-
next(observedCounter?: number): Promise<typeof Stamp.Type>;
|
|
80
|
-
/** Drains accepted allocations and closes storage; repeated calls share completion. */
|
|
81
|
-
close(): Promise<void>;
|
|
82
|
-
}
|
|
83
|
-
/** Opens a durable clock in its own storage, taking ownership even if opening fails. */
|
|
84
|
-
export declare const openLwwClock: ({ documentId, replicaId, storage }: {
|
|
85
|
-
readonly documentId: string;
|
|
86
|
-
readonly replicaId: string;
|
|
87
|
-
readonly storage: Storage<LwwClockState>;
|
|
88
|
-
}) => Promise<LwwClock>;
|
|
79
|
+
declare const UnsupportedReplicaVersionError_base: Schema.Class<UnsupportedReplicaVersionError, Schema.TaggedStruct<"UnsupportedReplicaVersionError", {
|
|
80
|
+
readonly protocolVersion: Schema.NullOr<Schema.Number>;
|
|
81
|
+
readonly schemaVersion: Schema.NullOr<Schema.Number>;
|
|
82
|
+
readonly message: Schema.String;
|
|
83
|
+
}>, import("effect/Cause").YieldableError>;
|
|
84
|
+
/** The stored replica state targets a protocol or schema version this build does not support. */
|
|
85
|
+
export declare class UnsupportedReplicaVersionError extends UnsupportedReplicaVersionError_base {}
|
|
86
|
+
declare const ReplayError_base: Schema.Class<ReplayError, Schema.TaggedStruct<"ReplayError", {
|
|
87
|
+
readonly message: Schema.String;
|
|
88
|
+
readonly cause: Schema.optional<Schema.Unknown>;
|
|
89
|
+
}>, import("effect/Cause").YieldableError>;
|
|
89
90
|
/**
|
|
90
|
-
*
|
|
91
|
-
*
|
|
92
|
-
* Merge is for decoded values; the application's schema validates wire input.
|
|
91
|
+
* `replay` threw for a submitted Message, so it could never be applied here or
|
|
92
|
+
* on any other replica; nothing was written.
|
|
93
93
|
*/
|
|
94
|
-
export declare
|
|
95
|
-
|
|
96
|
-
readonly stamp: Schema.Struct<{
|
|
97
|
-
readonly counter: Schema.Number;
|
|
98
|
-
readonly replicaId: Schema.NonEmptyString;
|
|
99
|
-
}>;
|
|
100
|
-
readonly value: Schema.Codec<Value, Encoded, RD, RE>;
|
|
101
|
-
}>;
|
|
102
|
-
merge: (left: {
|
|
103
|
-
readonly stamp: {
|
|
104
|
-
readonly counter: number;
|
|
105
|
-
readonly replicaId: string;
|
|
106
|
-
};
|
|
107
|
-
readonly value: Value;
|
|
108
|
-
}, right: {
|
|
109
|
-
readonly stamp: {
|
|
110
|
-
readonly counter: number;
|
|
111
|
-
readonly replicaId: string;
|
|
112
|
-
};
|
|
113
|
-
readonly value: Value;
|
|
114
|
-
}) => {
|
|
115
|
-
readonly stamp: {
|
|
116
|
-
readonly counter: number;
|
|
117
|
-
readonly replicaId: string;
|
|
118
|
-
};
|
|
119
|
-
readonly value: Value;
|
|
120
|
-
};
|
|
121
|
-
};
|
|
94
|
+
export declare class ReplayError extends ReplayError_base {}
|
|
95
|
+
type ReplicaError = StorageError | ReplayError | WrongReplicaStorageError | InvalidReplicaHistoryError | InvalidExchangeError | UnsupportedReplicaVersionError | InvalidOutboxError | CheckpointRegressionError | CommittedOrderError | ForeignRejectionError | ForeignAcknowledgementError | ReplicaClosedError;
|
|
122
96
|
//#endregion
|
|
123
|
-
//#region src/
|
|
124
|
-
/**
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
readonly localSequence: Schema.Number;
|
|
131
|
-
readonly opId: Schema.NonEmptyString;
|
|
132
|
-
readonly baseCursor: Schema.Number;
|
|
133
|
-
readonly message: Schema.Unknown;
|
|
134
|
-
}>;
|
|
135
|
-
type Operation = typeof OperationSchema.Type;
|
|
136
|
-
/** An operation the server committed, with its authoritative order and actor. */
|
|
137
|
-
declare const CommittedSchema: Schema.Struct<{
|
|
138
|
-
readonly serverSequence: Schema.Number;
|
|
139
|
-
readonly actorId: Schema.NonEmptyString;
|
|
140
|
-
readonly protocolVersion: Schema.Literal<1>;
|
|
141
|
-
readonly schemaVersion: Schema.Literal<1>;
|
|
142
|
-
readonly documentId: Schema.NonEmptyString;
|
|
143
|
-
readonly replicaId: Schema.NonEmptyString;
|
|
144
|
-
readonly localSequence: Schema.Number;
|
|
145
|
-
readonly opId: Schema.NonEmptyString;
|
|
146
|
-
readonly baseCursor: Schema.Number;
|
|
147
|
-
readonly message: Schema.Unknown;
|
|
148
|
-
}>;
|
|
149
|
-
type Committed = typeof CommittedSchema.Type;
|
|
150
|
-
/** Counters and a histogram an application can scrape. */
|
|
151
|
-
export declare const syncMetrics: {
|
|
152
|
-
exchanges: Metric.Counter<number>;
|
|
153
|
-
applied: Metric.Counter<number>;
|
|
154
|
-
checkpoints: Metric.Counter<number>;
|
|
155
|
-
exchangePending: Metric.Histogram<number>;
|
|
156
|
-
};
|
|
157
|
-
interface Checkpoint<Shared> {
|
|
158
|
-
readonly cursor: number;
|
|
159
|
-
readonly model: Shared;
|
|
160
|
-
}
|
|
161
|
-
interface Exchange<Shared> {
|
|
162
|
-
readonly operations: ReadonlyArray<unknown>;
|
|
163
|
-
readonly rejected: ReadonlyArray<string>;
|
|
164
|
-
/** Sends from the request that are durably committed, so the replica can drop them. */
|
|
165
|
-
readonly acknowledged?: ReadonlyArray<string> | undefined;
|
|
166
|
-
/** The snapshot a replica predating compaction adopts in place of the log. */
|
|
167
|
-
readonly checkpoint?: Checkpoint<Shared> | undefined;
|
|
168
|
-
}
|
|
169
|
-
interface ReplicaState<Shared> {
|
|
170
|
-
readonly protocolVersion: 1;
|
|
171
|
-
readonly schemaVersion: 1;
|
|
172
|
-
readonly documentId: string;
|
|
173
|
-
readonly replicaId: string;
|
|
174
|
-
readonly revision: number;
|
|
175
|
-
readonly nextLocalSequence: number;
|
|
176
|
-
readonly cursor: number;
|
|
177
|
-
readonly committed: Shared;
|
|
178
|
-
readonly committedIds: ReadonlyArray<string>;
|
|
179
|
-
readonly pending: ReadonlyArray<Operation>;
|
|
180
|
-
}
|
|
181
|
-
/**
|
|
182
|
-
* What the promise-based edge adapter consumes; the Effect `Transport` service
|
|
183
|
-
* is the primary seam.
|
|
184
|
-
*/
|
|
185
|
-
interface TransportClient {
|
|
186
|
-
exchange(cursor: number, pending: ReadonlyArray<Operation>): Promise<unknown>;
|
|
187
|
-
}
|
|
188
|
-
interface Replica<Message, Shared> {
|
|
189
|
-
/** The optimistic projection: committed state with pending operations replayed. */
|
|
190
|
-
readonly shared: Effect.Effect<Shared>;
|
|
191
|
-
readonly pending: Effect.Effect<ReadonlyArray<Operation>>;
|
|
192
|
-
readonly cursor: Effect.Effect<number>;
|
|
193
|
-
readonly submit: (message: Message) => Effect.Effect<void, ReplicaError>;
|
|
194
|
-
/** Reconciles against the server. The `Transport` service must be provided. */
|
|
195
|
-
readonly synchronize: Effect.Effect<void, ReplicaError | TransportError, Transport>;
|
|
196
|
-
readonly close: Effect.Effect<void>;
|
|
197
|
-
}
|
|
198
|
-
interface SyncDefinition<Message, Shared, MessageEncoded, SharedEncoded> {
|
|
199
|
-
readonly documentId: string;
|
|
200
|
-
readonly message: Schema.Codec<Message, MessageEncoded, never, never>;
|
|
201
|
-
readonly shared: Schema.Codec<Shared, SharedEncoded, never, never>;
|
|
202
|
-
readonly empty: Shared;
|
|
203
|
-
readonly durable: (message: Message) => boolean;
|
|
204
|
-
readonly replay: (shared: Shared, message: Message) => Shared;
|
|
205
|
-
}
|
|
206
|
-
interface Sync<Message, Shared> {
|
|
207
|
-
readonly documentId: string;
|
|
208
|
-
readonly normalizeOperation: (input: unknown) => Operation;
|
|
209
|
-
readonly operationFrom: (input: unknown, documentId: string) => Operation;
|
|
210
|
-
readonly committedFrom: (input: unknown, documentId: string) => Committed;
|
|
211
|
-
readonly decodeExchange: (input: unknown) => Exchange<Shared>;
|
|
212
|
-
readonly openReplica: (replicaId: string, storage: Storage<ReplicaState<Shared>>) => Effect.Effect<Replica<Message, Shared>, ReplicaError>;
|
|
97
|
+
//#region src/indexedDb.d.ts
|
|
98
|
+
/** Persists a replica's state with compare-and-swap on its revision. */
|
|
99
|
+
interface Storage {
|
|
100
|
+
load: () => Effect.Effect<unknown, StorageError>;
|
|
101
|
+
save: (state: unknown, expectedRevision: number | null) => Effect.Effect<void, StorageError>;
|
|
102
|
+
/** Idempotent; the caller closes the connection explicitly. */
|
|
103
|
+
close: Effect.Effect<void>;
|
|
213
104
|
}
|
|
105
|
+
/** One database per document/replica; CAS prevents two tabs from sharing a writer identity. */
|
|
106
|
+
export declare const indexedDb: (name: string | Config.Config<string>, factory?: IDBFactory | undefined) => Effect.Effect<Storage, StorageError, Scope.Scope>;
|
|
107
|
+
//#endregion
|
|
108
|
+
//#region src/ids.d.ts
|
|
109
|
+
/** Identifies the replicated document a replica or operation belongs to. */
|
|
110
|
+
export declare const DocumentId: Schema.brand<Schema.NonEmptyString, "@foldkit-sync/DocumentId">;
|
|
111
|
+
export type DocumentId = typeof DocumentId.Type;
|
|
112
|
+
/** Identifies one replica (writer identity) within a document. */
|
|
113
|
+
export declare const ReplicaId: Schema.brand<Schema.NonEmptyString, "@foldkit-sync/ReplicaId">;
|
|
114
|
+
export type ReplicaId = typeof ReplicaId.Type;
|
|
115
|
+
/** The stable identity of one operation within a document. */
|
|
116
|
+
export declare const OpId: Schema.brand<Schema.NonEmptyString, "@foldkit-sync/OpId">;
|
|
117
|
+
export type OpId = typeof OpId.Type;
|
|
214
118
|
/**
|
|
215
|
-
*
|
|
216
|
-
*
|
|
217
|
-
* The returned codecs decide what is a valid operation and what the shared
|
|
218
|
-
* projection means; the replica owns the local outbox, optimistic projection,
|
|
219
|
-
* and reconciliation as Effects, and never runs a second reducer.
|
|
119
|
+
* A position in the committed document order. `0` is the start; a committed
|
|
120
|
+
* operation's `serverSequence` and a replica's `cursor` are the same family.
|
|
220
121
|
*/
|
|
221
|
-
export declare const
|
|
122
|
+
export declare const Sequence: Schema.brand<Schema.Number, "@foldkit-sync/Sequence">;
|
|
123
|
+
export type Sequence = typeof Sequence.Type;
|
|
124
|
+
/** A replica's own operation counter within a document; 1-based. */
|
|
125
|
+
export declare const LocalSequence: Schema.brand<Schema.Number, "@foldkit-sync/LocalSequence">;
|
|
126
|
+
export type LocalSequence = typeof LocalSequence.Type;
|
|
127
|
+
export declare const documentId: (value: string) => DocumentId;
|
|
128
|
+
export declare const replicaId: (value: string) => ReplicaId;
|
|
129
|
+
export declare const opId: (value: string) => OpId;
|
|
130
|
+
export declare const sequence: (value: number) => Sequence;
|
|
131
|
+
export declare const localSequence: (value: number) => LocalSequence;
|
|
222
132
|
//#endregion
|
|
223
133
|
//#region src/transport.d.ts
|
|
224
134
|
declare const TransportError_base: Schema.Class<TransportError, Schema.TaggedStruct<"SyncTransportError", {
|
|
@@ -303,6 +213,409 @@ export declare const nativeSocket: (url: string) => SocketLike;
|
|
|
303
213
|
*/
|
|
304
214
|
export declare const layerSocket: (options: SocketOptions) => Layer.Layer<Transport, TransportError>;
|
|
305
215
|
//#endregion
|
|
216
|
+
//#region src/sync.d.ts
|
|
217
|
+
/** Wire and persisted-format versions. A bump must handle the older value explicitly. */
|
|
218
|
+
declare const PROTOCOL_VERSION = 1;
|
|
219
|
+
declare const SCHEMA_VERSION = 1;
|
|
220
|
+
/** A client-authored operation envelope. `message` is the application's encoded Message. */
|
|
221
|
+
declare const OperationSchema: Schema.Struct<{
|
|
222
|
+
readonly protocolVersion: Schema.Literal<1>;
|
|
223
|
+
readonly schemaVersion: Schema.Literal<1>;
|
|
224
|
+
readonly documentId: Schema.brand<Schema.NonEmptyString, "@foldkit-sync/DocumentId">;
|
|
225
|
+
readonly replicaId: Schema.brand<Schema.NonEmptyString, "@foldkit-sync/ReplicaId">;
|
|
226
|
+
readonly localSequence: Schema.brand<Schema.Number, "@foldkit-sync/LocalSequence">;
|
|
227
|
+
readonly opId: Schema.brand<Schema.NonEmptyString, "@foldkit-sync/OpId">;
|
|
228
|
+
readonly baseCursor: Schema.brand<Schema.Number, "@foldkit-sync/Sequence">;
|
|
229
|
+
readonly message: Schema.Unknown;
|
|
230
|
+
}>;
|
|
231
|
+
type Operation = typeof OperationSchema.Type;
|
|
232
|
+
/** An operation the server committed, with its authoritative order and actor. */
|
|
233
|
+
declare const CommittedSchema: Schema.Struct<{
|
|
234
|
+
readonly serverSequence: Schema.brand<Schema.Number, "@foldkit-sync/Sequence">;
|
|
235
|
+
readonly actorId: Schema.NonEmptyString;
|
|
236
|
+
readonly protocolVersion: Schema.Literal<1>;
|
|
237
|
+
readonly schemaVersion: Schema.Literal<1>;
|
|
238
|
+
readonly documentId: Schema.brand<Schema.NonEmptyString, "@foldkit-sync/DocumentId">;
|
|
239
|
+
readonly replicaId: Schema.brand<Schema.NonEmptyString, "@foldkit-sync/ReplicaId">;
|
|
240
|
+
readonly localSequence: Schema.brand<Schema.Number, "@foldkit-sync/LocalSequence">;
|
|
241
|
+
readonly opId: Schema.brand<Schema.NonEmptyString, "@foldkit-sync/OpId">;
|
|
242
|
+
readonly baseCursor: Schema.brand<Schema.Number, "@foldkit-sync/Sequence">;
|
|
243
|
+
readonly message: Schema.Unknown;
|
|
244
|
+
}>;
|
|
245
|
+
/** Named to avoid colliding with `foldkit-durable`'s `Committed`. */
|
|
246
|
+
type CommittedOperation = typeof CommittedSchema.Type;
|
|
247
|
+
/** Counters and a histogram an application can scrape. */
|
|
248
|
+
export declare const syncMetrics: {
|
|
249
|
+
exchanges: Metric.Counter<number>;
|
|
250
|
+
applied: Metric.Counter<number>;
|
|
251
|
+
checkpoints: Metric.Counter<number>;
|
|
252
|
+
exchangePending: Metric.Histogram<number>;
|
|
253
|
+
};
|
|
254
|
+
interface Checkpoint<Shared> {
|
|
255
|
+
readonly cursor: Sequence;
|
|
256
|
+
readonly model: Shared;
|
|
257
|
+
}
|
|
258
|
+
interface Exchange<Shared> {
|
|
259
|
+
/** Server-committed operations as they arrived; validated against `CommittedOperation` on adoption. */
|
|
260
|
+
readonly operations: ReadonlyArray<unknown>;
|
|
261
|
+
readonly rejected: ReadonlyArray<OpId>;
|
|
262
|
+
/** Sends from the request that are durably committed, so the replica can drop them. */
|
|
263
|
+
readonly acknowledged?: ReadonlyArray<OpId> | undefined;
|
|
264
|
+
/** The snapshot a replica predating compaction adopts in place of the log. */
|
|
265
|
+
readonly checkpoint?: Checkpoint<Shared> | undefined;
|
|
266
|
+
}
|
|
267
|
+
interface ReplicaState<Shared> {
|
|
268
|
+
readonly protocolVersion: typeof PROTOCOL_VERSION;
|
|
269
|
+
readonly schemaVersion: typeof SCHEMA_VERSION;
|
|
270
|
+
readonly documentId: DocumentId;
|
|
271
|
+
readonly replicaId: ReplicaId;
|
|
272
|
+
readonly revision: number;
|
|
273
|
+
readonly nextLocalSequence: LocalSequence;
|
|
274
|
+
readonly cursor: Sequence;
|
|
275
|
+
readonly committed: Shared;
|
|
276
|
+
readonly committedIds: ReadonlyArray<string>;
|
|
277
|
+
readonly pending: ReadonlyArray<Operation>;
|
|
278
|
+
}
|
|
279
|
+
/**
|
|
280
|
+
* What the promise-based edge adapter consumes; the Effect `Transport` service
|
|
281
|
+
* is the primary seam.
|
|
282
|
+
*/
|
|
283
|
+
interface TransportClient {
|
|
284
|
+
exchange(cursor: Sequence, pending: ReadonlyArray<Operation>): Promise<unknown>;
|
|
285
|
+
}
|
|
286
|
+
/** A redacted view of a replica's state, for a UI to explain and recover. */
|
|
287
|
+
interface ReplicaStatus {
|
|
288
|
+
readonly pending: number;
|
|
289
|
+
readonly cursor: Sequence;
|
|
290
|
+
/** The last exchange failure, cleared by a successful exchange. */
|
|
291
|
+
readonly lastError: string | undefined;
|
|
292
|
+
/** Operations the server refused, most recent first. */
|
|
293
|
+
readonly rejected: ReadonlyArray<OpId>;
|
|
294
|
+
}
|
|
295
|
+
/**
|
|
296
|
+
* A consistent status and optimistic-shared pair, read from one replica state.
|
|
297
|
+
* `Replica.changes` emits it so a UI can hold a single subscription.
|
|
298
|
+
*/
|
|
299
|
+
interface ReplicaSnapshot<Shared> {
|
|
300
|
+
readonly status: ReplicaStatus;
|
|
301
|
+
readonly shared: Shared;
|
|
302
|
+
}
|
|
303
|
+
interface Replica<Message, Shared> {
|
|
304
|
+
/** The optimistic projection: committed state with pending operations replayed. */
|
|
305
|
+
readonly shared: Effect.Effect<Shared>;
|
|
306
|
+
readonly pending: Effect.Effect<ReadonlyArray<Operation>>;
|
|
307
|
+
readonly cursor: Effect.Effect<Sequence>;
|
|
308
|
+
/**
|
|
309
|
+
* Waiting/recovery information without exposing Messages or the Model. It is a
|
|
310
|
+
* snapshot; `statusChanges` re-emits it after every submit and exchange.
|
|
311
|
+
*/
|
|
312
|
+
readonly status: Effect.Effect<ReplicaStatus>;
|
|
313
|
+
/** The status, re-emitted after every submit and exchange. */
|
|
314
|
+
readonly statusChanges: Stream.Stream<ReplicaStatus>;
|
|
315
|
+
/**
|
|
316
|
+
* The status and the optimistic shared value together, re-emitted after every
|
|
317
|
+
* submit and exchange, so a UI can subscribe once instead of to both.
|
|
318
|
+
*/
|
|
319
|
+
readonly changes: Stream.Stream<ReplicaSnapshot<Shared>>;
|
|
320
|
+
readonly submit: (message: Message) => Effect.Effect<void, ReplicaError>;
|
|
321
|
+
/** Reconciles against the server. The `Transport` service must be provided. */
|
|
322
|
+
readonly synchronize: Effect.Effect<void, ReplicaError | TransportError, Transport>;
|
|
323
|
+
/**
|
|
324
|
+
* The exchange loop: exchanges once, then after every `submit`, until the
|
|
325
|
+
* replica closes or the fiber is interrupted. A transport failure is recorded
|
|
326
|
+
* in `status.lastError` and retried on the next wake, so the fiber never
|
|
327
|
+
* fails. Fork it with `Effect.forkScoped` and provide `Transport`.
|
|
328
|
+
*/
|
|
329
|
+
readonly start: Effect.Effect<void, never, Transport>;
|
|
330
|
+
readonly close: Effect.Effect<void>;
|
|
331
|
+
}
|
|
332
|
+
interface SyncDefinition<Message, Shared, MessageEncoded, SharedEncoded> {
|
|
333
|
+
readonly documentId: DocumentId;
|
|
334
|
+
readonly message: Schema.Codec<Message, MessageEncoded, never, never>;
|
|
335
|
+
readonly shared: Schema.Codec<Shared, SharedEncoded, never, never>;
|
|
336
|
+
readonly empty: Shared;
|
|
337
|
+
readonly durable: (message: Message) => boolean;
|
|
338
|
+
readonly replay: (shared: Shared, message: Message) => Shared;
|
|
339
|
+
}
|
|
340
|
+
interface Sync<Message, Shared> {
|
|
341
|
+
readonly documentId: DocumentId;
|
|
342
|
+
/**
|
|
343
|
+
* Low-level wire codecs for adapters and the transport. Most applications use
|
|
344
|
+
* `journalContract` and `openReplica`; these are exposed for a custom
|
|
345
|
+
* transport or a server that must speak the operation envelope directly.
|
|
346
|
+
*/
|
|
347
|
+
readonly codec: {
|
|
348
|
+
readonly normalizeOperation: (input: unknown) => Operation;
|
|
349
|
+
readonly operationFrom: (input: unknown, documentId: DocumentId) => Operation;
|
|
350
|
+
readonly committedFrom: (input: unknown, documentId: DocumentId) => CommittedOperation;
|
|
351
|
+
readonly decodeExchange: (input: unknown) => Exchange<Shared>;
|
|
352
|
+
};
|
|
353
|
+
/** The codecs and pure reducer `foldkit-durable`'s `makeJournal` consumes. */
|
|
354
|
+
readonly journalContract: () => JournalContract<Operation, Shared>;
|
|
355
|
+
readonly openReplica: (replicaId: ReplicaId, storage: Storage) => Effect.Effect<Replica<Message, Shared>, ReplicaError>;
|
|
356
|
+
}
|
|
357
|
+
/** Structural match for `foldkit-durable`'s journal options; Sync stays independent. */
|
|
358
|
+
interface JournalContract<Operation, Shared> {
|
|
359
|
+
readonly operation: {
|
|
360
|
+
/** Operations are stored in their encoded form, so this is the identity. */
|
|
361
|
+
readonly encode: (operation: Operation) => Operation;
|
|
362
|
+
readonly decode: (input: unknown) => Operation;
|
|
363
|
+
};
|
|
364
|
+
readonly snapshot: {
|
|
365
|
+
readonly encode: (snapshot: Shared) => unknown;
|
|
366
|
+
readonly decode: (input: unknown) => Shared;
|
|
367
|
+
};
|
|
368
|
+
readonly empty: () => Shared;
|
|
369
|
+
readonly reduce: (snapshot: Shared, operation: Operation) => Shared;
|
|
370
|
+
}
|
|
371
|
+
/**
|
|
372
|
+
* Binds the replicated-state protocol to one application contract.
|
|
373
|
+
*
|
|
374
|
+
* The returned codecs decide what is a valid operation and what the shared
|
|
375
|
+
* projection means; the replica owns the local outbox, optimistic projection,
|
|
376
|
+
* and reconciliation as Effects, and never runs a second reducer.
|
|
377
|
+
*/
|
|
378
|
+
export declare const defineSync: <Message, Shared, MessageEncoded, SharedEncoded>(definition: SyncDefinition<Message, Shared, MessageEncoded, SharedEncoded>) => Sync<Message, Shared>;
|
|
379
|
+
//#endregion
|
|
380
|
+
//#region src/make.d.ts
|
|
381
|
+
type MessageConstructor<Message> = (...args: never[]) => Message;
|
|
382
|
+
/** The Message union a tuple of constructors produces. */
|
|
383
|
+
type MsgOf<Ms extends readonly unknown[]> = Ms[number] extends ((...args: never[]) => infer M) ? M : never;
|
|
384
|
+
type AppMessage<AppModel, F extends Schema.Struct.Fields, Cases extends Record<string, Schema.Struct.Fields>> = Schema.Schema.Type<AppScope<AppModel, F, Cases>['Message']>;
|
|
385
|
+
/** The `_tag` literal of the Message a constructor produces. */
|
|
386
|
+
type TagOf<C> = C extends ((...args: never[]) => infer M) ? M extends {
|
|
387
|
+
readonly _tag: infer T extends string;
|
|
388
|
+
} ? T : never : never;
|
|
389
|
+
/**
|
|
390
|
+
* A journal contract that also carries the declared authorization policy, in
|
|
391
|
+
* the shape `makeJournal` takes, so `makeJournal({ ...contract })` applies it.
|
|
392
|
+
*/
|
|
393
|
+
interface PolicyJournalContract<Operation, Shared, Principal> extends JournalContract<Operation, Shared> {
|
|
394
|
+
readonly authorize?: (request: {
|
|
395
|
+
readonly principal: Principal;
|
|
396
|
+
readonly operation: Operation;
|
|
397
|
+
readonly snapshot: Shared;
|
|
398
|
+
}) => boolean;
|
|
399
|
+
}
|
|
400
|
+
/** What a per-variant `authorize` rule sees before the journal commits. */
|
|
401
|
+
interface AuthorizeRequest<Principal, Message, Shared> {
|
|
402
|
+
readonly principal: Principal;
|
|
403
|
+
readonly message: Message;
|
|
404
|
+
readonly shared: Shared;
|
|
405
|
+
}
|
|
406
|
+
/**
|
|
407
|
+
* Per-variant policy, keyed by durable tag: `message` is that variant exactly,
|
|
408
|
+
* `shared` the authoritative snapshot. A variant without a rule is allowed; the
|
|
409
|
+
* server may still refuse on its own grounds.
|
|
410
|
+
*/
|
|
411
|
+
type AuthorizePolicy<Principal, Fields extends Schema.Struct.Fields, Ms extends readonly unknown[]> = { readonly [K in TagOf<Ms[number]>]?: (request: AuthorizeRequest<Principal, Extract<MsgOf<Ms>, {
|
|
412
|
+
readonly _tag: K;
|
|
413
|
+
}>, Schema.Struct.Type<Fields>>) => boolean; };
|
|
414
|
+
interface BaseOptions<Principal, Fields extends Schema.Struct.Fields, Ms extends readonly unknown[]> {
|
|
415
|
+
readonly documentId: DocumentId;
|
|
416
|
+
/** Name for the generated `surface`; defaults to the document id. */
|
|
417
|
+
readonly name?: string;
|
|
418
|
+
/**
|
|
419
|
+
* Replaces the replay derived from the application's `update`. It is a pure
|
|
420
|
+
* reducer over the shared subset; only durable Messages reach it, and it runs
|
|
421
|
+
* during admission, replay, and optimistic projection. It is not guarded: the
|
|
422
|
+
* author owns its agreement with `update`.
|
|
423
|
+
*/
|
|
424
|
+
readonly replay?: (shared: Schema.Struct.Type<NoInfer<Fields>>, message: MsgOf<NoInfer<Ms>>) => Schema.Struct.Type<NoInfer<Fields>>;
|
|
425
|
+
/** Authorization the server journal applies before committing; see `AuthorizePolicy`. */
|
|
426
|
+
readonly authorize?: AuthorizePolicy<Principal, NoInfer<Fields>, NoInfer<Ms>>;
|
|
427
|
+
}
|
|
428
|
+
interface MakeOptions<AppModel, Fields extends Schema.Struct.Fields, Subset, Ms extends readonly MessageConstructor<any>[], Principal = unknown> extends BaseOptions<Principal, Fields, Ms> {
|
|
429
|
+
/** The writable projection of the shared fields. */
|
|
430
|
+
readonly shared: WritableProjection<AppModel, Fields>;
|
|
431
|
+
/** The Message subset the replica durably records and replays. */
|
|
432
|
+
readonly durable: MessageSet<AppModel, any, Subset, Ms>;
|
|
433
|
+
}
|
|
434
|
+
/**
|
|
435
|
+
* One feature's contribution to a document: the fields it shares and the
|
|
436
|
+
* Messages it records. `compose` merges fragments into one, to spread into
|
|
437
|
+
* `make`; a field declared twice with a different codec or a tag declared twice
|
|
438
|
+
* is rejected there.
|
|
439
|
+
*/
|
|
440
|
+
interface SyncFragment<AppModel, Fields extends Schema.Struct.Fields, Subset, Ms extends readonly MessageConstructor<any>[]> {
|
|
441
|
+
readonly shared: WritableProjection<AppModel, Fields>;
|
|
442
|
+
readonly durable: MessageSet<AppModel, any, Subset, Ms>;
|
|
443
|
+
}
|
|
444
|
+
type SharedOf<Fs extends readonly SyncFragment<any, any, any, any>[]> = { readonly [K in keyof Fs]: Fs[K]['shared']; };
|
|
445
|
+
type DurableOf<Fs extends readonly SyncFragment<any, any, any, any>[]> = { readonly [K in keyof Fs]: Fs[K]['durable']; };
|
|
446
|
+
/** The merged shared fields of several fragments. */
|
|
447
|
+
type FragmentFields<Fs extends readonly SyncFragment<any, any, any, any>[]> = MergeFields<SharedOf<Fs>>;
|
|
448
|
+
/** The concatenated durable constructors of several fragments. */
|
|
449
|
+
type FragmentConstructors<Fs extends readonly SyncFragment<any, any, any, any>[]> = MergeConstructors<DurableOf<Fs>>;
|
|
450
|
+
/** The union of Messages several fragments record. */
|
|
451
|
+
type FragmentMessages<Fs extends readonly SyncFragment<any, any, any, any>[]> = Fs[number] extends SyncFragment<any, any, infer V, any> ? V : never;
|
|
452
|
+
/**
|
|
453
|
+
* The value `make` returns: the low-level `Sync` protocol plus the writable
|
|
454
|
+
* projection, the declared Messages, and a read-only Surface over the
|
|
455
|
+
* projection. Exported so a consumer can name the type.
|
|
456
|
+
*/
|
|
457
|
+
interface DefinedSync<AppModel, Fields extends Schema.Struct.Fields, Message, Ms extends readonly unknown[], Principal = unknown> extends Sync<Message, Schema.Struct.Type<Fields>> {
|
|
458
|
+
readonly surface: Surface<AppModel, Schema.Struct.Type<Fields>, MsgOf<Ms>, void>;
|
|
459
|
+
readonly projection: WritableProjection<AppModel, Fields>;
|
|
460
|
+
readonly messages: Ms;
|
|
461
|
+
/** For `Module`: this contract owns the shared projection's paths and records the durable tags. */
|
|
462
|
+
readonly contract: Contract;
|
|
463
|
+
/** The durable journal's codecs, reducer, and, when declared, authorization. */
|
|
464
|
+
readonly journalContract: () => PolicyJournalContract<Operation, Schema.Struct.Type<Fields>, Principal>;
|
|
465
|
+
}
|
|
466
|
+
/** The sync constructors specialized to one application. */
|
|
467
|
+
interface ApplicationSync<AppModel, F extends Schema.Struct.Fields, Cases extends Record<string, Schema.Struct.Fields>, Principal = unknown> {
|
|
468
|
+
/**
|
|
469
|
+
* Fixes the `Principal` that `authorize` rules see. A `Principal` cannot be a
|
|
470
|
+
* positional type argument beside an inferred Model, so it is supplied here:
|
|
471
|
+
* `Sync.forApplication(App).withPrincipal<User>()`. Type-only.
|
|
472
|
+
*/
|
|
473
|
+
readonly withPrincipal: <P>() => ApplicationSync<AppModel, F, Cases, P>;
|
|
474
|
+
/** One feature's shared fields and durable Messages, for `compose`. */
|
|
475
|
+
readonly fragment: <Fields extends Schema.Struct.Fields, Subset, Ms extends readonly MessageConstructor<AppMessage<AppModel, F, Cases>>[]>(config: {
|
|
476
|
+
readonly shared: WritableProjection<AppModel, Fields>;
|
|
477
|
+
readonly durable: MessageSet<AppModel, any, Subset, Ms>;
|
|
478
|
+
}) => SyncFragment<AppModel, Fields, Subset, Ms>;
|
|
479
|
+
/**
|
|
480
|
+
* Merges fragments into one: `make({ documentId, ...compose(Todos, Members) })`.
|
|
481
|
+
* A field declared twice with a different codec, a tag declared twice, or a
|
|
482
|
+
* fragment from another application throws.
|
|
483
|
+
*/
|
|
484
|
+
readonly compose: <const Fs extends readonly SyncFragment<AppModel, any, any, any>[]>(...fragments: Fs) => SyncFragment<AppModel, FragmentFields<Fs>, FragmentMessages<Fs>, FragmentConstructors<Fs>>;
|
|
485
|
+
readonly make: <Fields extends Schema.Struct.Fields, Subset, Ms extends readonly MessageConstructor<AppMessage<AppModel, F, Cases>>[]>(options: MakeOptions<AppModel, Fields, Subset, Ms, Principal>) => DefinedSync<AppModel, Fields, AppMessage<AppModel, F, Cases>, Ms, Principal>;
|
|
486
|
+
}
|
|
487
|
+
/**
|
|
488
|
+
* Specializes the sync constructors to a `Surface.application`, so
|
|
489
|
+
* `Sync.forApplication(App).make({ documentId, shared, durable })` derives the
|
|
490
|
+
* shared codec, the initial snapshot, the durable predicate, and replay from
|
|
491
|
+
* the application, and refuses a subset that belongs to another application.
|
|
492
|
+
* `defineSync` remains the protocol primitive when there is no application to
|
|
493
|
+
* derive from.
|
|
494
|
+
*/
|
|
495
|
+
export declare const forApplication: <AppModel, F extends Schema.Struct.Fields, Cases extends Record<string, Schema.Struct.Fields>>(app: RunnableApplication<AppModel, F, Cases, any>) => ApplicationSync<AppModel, F, Cases>;
|
|
496
|
+
//#endregion
|
|
497
|
+
//#region src/mount.d.ts
|
|
498
|
+
/**
|
|
499
|
+
* The URL as part of the application: `onUrlChange` names the Message the
|
|
500
|
+
* runtime sends for the current URL at start and on every navigation (so a
|
|
501
|
+
* `foldkit-mirror` URL mirror reads back in), `init` reduces the URL into the
|
|
502
|
+
* Model before the first render, and `onUrlRequest` names the Message for a
|
|
503
|
+
* link click; omitted, the mount follows the link itself (an internal one is
|
|
504
|
+
* pushed, an external one loaded).
|
|
505
|
+
*/
|
|
506
|
+
interface MountUrl<Model, Message> {
|
|
507
|
+
readonly init?: ((model: Model, url: Url.Url) => Model) | undefined;
|
|
508
|
+
readonly onUrlChange: (url: Url.Url) => Message;
|
|
509
|
+
readonly onUrlRequest?: ((request: UrlRequest) => Message) | undefined;
|
|
510
|
+
}
|
|
511
|
+
interface MountOptions<Model, Message, Shared, Resources> {
|
|
512
|
+
/** An open replica of this contract; `mount` does not close it. */
|
|
513
|
+
readonly replica: Replica<Message, Shared>;
|
|
514
|
+
/** The element the application renders into; Foldkit requires it to have an `id`. */
|
|
515
|
+
readonly container: HTMLElement;
|
|
516
|
+
readonly view: (model: Model, h: HtmlBuilder<Message>) => Document;
|
|
517
|
+
readonly subscriptions?: Subscriptions<Model, Message, Resources> | undefined;
|
|
518
|
+
readonly resources?: Layer.Layer<Resources> | undefined;
|
|
519
|
+
/** Route the URL through the application; without it the mount ignores the URL. */
|
|
520
|
+
readonly url?: MountUrl<Model, Message> | undefined;
|
|
521
|
+
/**
|
|
522
|
+
* Reflects a refused or failed persist in the Model, after the durable edit
|
|
523
|
+
* has been reverted. Omitted, the edit is reverted silently.
|
|
524
|
+
*/
|
|
525
|
+
readonly onPersistenceFailure?: ((model: Model, error: ReplicaError) => Model) | undefined;
|
|
526
|
+
}
|
|
527
|
+
interface Mounted<Model, Message> {
|
|
528
|
+
/** Sends an application Message through the runtime; the `Exit` reports a decode failure. */
|
|
529
|
+
readonly dispatch: (message: Message) => Exit.Exit<void, unknown>;
|
|
530
|
+
/** The Model after the last transition. */
|
|
531
|
+
readonly model: () => Model;
|
|
532
|
+
/** Notified after every transition; with `model` and `dispatch`, the host an agent binds to. */
|
|
533
|
+
readonly subscribe: (listener: () => void) => () => void;
|
|
534
|
+
/**
|
|
535
|
+
* Every application Message the runtime applies, from any origin, so an
|
|
536
|
+
* agent contract that declares a `completion` can see the Message that
|
|
537
|
+
* finishes its work. The mount's private Messages are not reported.
|
|
538
|
+
*/
|
|
539
|
+
readonly observe: (listener: (message: Message) => void) => () => void;
|
|
540
|
+
/** Waits for in-flight persists, then disposes the runtime. The replica stays open. */
|
|
541
|
+
readonly dispose: () => Promise<void>;
|
|
542
|
+
}
|
|
543
|
+
/** The application's Message union, as `Surface.application` types it. */
|
|
544
|
+
type MessageOf<App> = App extends RunnableApplication<any, any, any, any> ? Schema.Schema.Type<App['Message']> : never;
|
|
545
|
+
export declare const mount: <Model, F extends Schema.Struct.Fields, Cases extends Record<string, Schema.Struct.Fields>, Fields extends Schema.Struct.Fields, Ms extends readonly unknown[], Resources = never, Principal = unknown>(app: RunnableApplication<Model, F, Cases, Resources>, sync: DefinedSync<Model, Fields, MessageOf<RunnableApplication<Model, F, Cases, Resources>>, Ms, Principal>, options: MountOptions<Model, MessageOf<RunnableApplication<Model, F, Cases, Resources>>, Schema.Struct.Type<Fields>, Resources>) => Mounted<Model, MessageOf<RunnableApplication<Model, F, Cases, Resources>>>;
|
|
546
|
+
//#endregion
|
|
547
|
+
//#region src/lww.d.ts
|
|
548
|
+
/** A logical write time; replica ids break concurrent ties using UTF-16 order. */
|
|
549
|
+
declare const Stamp: Schema.Struct<{
|
|
550
|
+
readonly counter: Schema.Number;
|
|
551
|
+
readonly replicaId: Schema.brand<Schema.NonEmptyString, "@foldkit-sync/ReplicaId">;
|
|
552
|
+
}>;
|
|
553
|
+
declare const ClockState: Schema.Struct<{
|
|
554
|
+
readonly schemaVersion: Schema.Literal<1>;
|
|
555
|
+
readonly documentId: Schema.brand<Schema.NonEmptyString, "@foldkit-sync/DocumentId">;
|
|
556
|
+
readonly replicaId: Schema.brand<Schema.NonEmptyString, "@foldkit-sync/ReplicaId">;
|
|
557
|
+
readonly revision: Schema.Number;
|
|
558
|
+
}>;
|
|
559
|
+
type LwwClockState = typeof ClockState.Type;
|
|
560
|
+
interface LwwClock {
|
|
561
|
+
/** Persists a timestamp beyond the saved counter and supplied observation. */
|
|
562
|
+
next: (observedCounter?: number) => Effect.Effect<typeof Stamp.Type, StorageError>;
|
|
563
|
+
/** Drains accepted allocations, then closes storage. Repeated calls no-op. */
|
|
564
|
+
close: Effect.Effect<void>;
|
|
565
|
+
}
|
|
566
|
+
/**
|
|
567
|
+
* Opens a durable clock over the caller's storage.
|
|
568
|
+
*
|
|
569
|
+
* Allocations are serialized through a `SynchronizedRef` and each persists before
|
|
570
|
+
* its stamp is returned. A crash after the save may skip a timestamp but never
|
|
571
|
+
* reuse one. Storage is owned by the caller; a failed open closes it so a partial
|
|
572
|
+
* initialization does not leak the connection.
|
|
573
|
+
*/
|
|
574
|
+
export declare const openLwwClock: (options: {
|
|
575
|
+
readonly documentId: DocumentId;
|
|
576
|
+
readonly replicaId: ReplicaId;
|
|
577
|
+
readonly storage: Storage;
|
|
578
|
+
}) => Effect.Effect<{
|
|
579
|
+
next: (observedCounter?: any) => Effect.Effect<{
|
|
580
|
+
readonly counter: number;
|
|
581
|
+
readonly replicaId: string & import("effect/Brand").Brand<"@foldkit-sync/ReplicaId">;
|
|
582
|
+
}, StorageError, never>;
|
|
583
|
+
close: Effect.Effect<void, never, never>;
|
|
584
|
+
}, StorageError | UnsupportedClockVersionError, never>;
|
|
585
|
+
/**
|
|
586
|
+
* A schema and reducer helper for a last-writer-wins register.
|
|
587
|
+
* Allocate a unique stamp per write before dispatch, and retain it in the Message.
|
|
588
|
+
* Merge is for decoded values; the application's schema validates wire input.
|
|
589
|
+
*/
|
|
590
|
+
export declare const lwwRegister: <Value, Encoded, RD, RE>(value: Schema.Codec<Value, Encoded, RD, RE>) => {
|
|
591
|
+
schema: Schema.Struct<{
|
|
592
|
+
readonly stamp: Schema.Struct<{
|
|
593
|
+
readonly counter: Schema.Number;
|
|
594
|
+
readonly replicaId: Schema.brand<Schema.NonEmptyString, "@foldkit-sync/ReplicaId">;
|
|
595
|
+
}>;
|
|
596
|
+
readonly value: Schema.Codec<Value, Encoded, RD, RE>;
|
|
597
|
+
}>;
|
|
598
|
+
merge: (left: {
|
|
599
|
+
readonly stamp: {
|
|
600
|
+
readonly counter: number;
|
|
601
|
+
readonly replicaId: string & import("effect/Brand").Brand<"@foldkit-sync/ReplicaId">;
|
|
602
|
+
};
|
|
603
|
+
readonly value: Value;
|
|
604
|
+
}, right: {
|
|
605
|
+
readonly stamp: {
|
|
606
|
+
readonly counter: number;
|
|
607
|
+
readonly replicaId: string & import("effect/Brand").Brand<"@foldkit-sync/ReplicaId">;
|
|
608
|
+
};
|
|
609
|
+
readonly value: Value;
|
|
610
|
+
}) => {
|
|
611
|
+
readonly stamp: {
|
|
612
|
+
readonly counter: number;
|
|
613
|
+
readonly replicaId: string & import("effect/Brand").Brand<"@foldkit-sync/ReplicaId">;
|
|
614
|
+
};
|
|
615
|
+
readonly value: Value;
|
|
616
|
+
};
|
|
617
|
+
};
|
|
618
|
+
//#endregion
|
|
306
619
|
//#region src/presence.d.ts
|
|
307
620
|
/** One peer's presence. A `null` value means the peer left. */
|
|
308
621
|
interface PresenceUpdate<Update> {
|
|
@@ -312,18 +625,20 @@ interface PresenceUpdate<Update> {
|
|
|
312
625
|
/**
|
|
313
626
|
* The ephemeral channel presence travels on.
|
|
314
627
|
*
|
|
315
|
-
*
|
|
628
|
+
* `updates` is the inbound bus a peer consumes; `publish` sends one to the bus.
|
|
629
|
+
* Splitting them keeps an inbound update from being echoed straight back out.
|
|
630
|
+
* This is deliberately not the durable transport: presence is broadcast, never
|
|
316
631
|
* journaled, so a dropped or duplicated update is harmless.
|
|
317
632
|
*/
|
|
318
633
|
interface PresenceChannel<Update> {
|
|
319
|
-
|
|
320
|
-
|
|
634
|
+
readonly updates: PubSub.PubSub<PresenceUpdate<Update>>;
|
|
635
|
+
readonly publish: (update: PresenceUpdate<Update>) => Effect.Effect<void>;
|
|
321
636
|
}
|
|
322
637
|
interface PresenceOptions<Update> {
|
|
323
638
|
/** This peer's identity on the channel. */
|
|
324
639
|
readonly id: string;
|
|
325
|
-
/**
|
|
326
|
-
readonly ttl:
|
|
640
|
+
/** How long a peer may go without refreshing before it is dropped. */
|
|
641
|
+
readonly ttl: Duration.Input;
|
|
327
642
|
/**
|
|
328
643
|
* Validates the untrusted value a peer sends before it is stored. Presence
|
|
329
644
|
* crosses a wire, so this is required rather than trusting the type
|
|
@@ -331,8 +646,6 @@ interface PresenceOptions<Update> {
|
|
|
331
646
|
*/
|
|
332
647
|
readonly decodeValue: (value: unknown) => Update;
|
|
333
648
|
readonly channel?: PresenceChannel<Update> | undefined;
|
|
334
|
-
/** Injectable clock, for tests. */
|
|
335
|
-
readonly now?: (() => number) | undefined;
|
|
336
649
|
}
|
|
337
650
|
interface PresencePeer<Update> {
|
|
338
651
|
readonly id: string;
|
|
@@ -341,26 +654,52 @@ interface PresencePeer<Update> {
|
|
|
341
654
|
}
|
|
342
655
|
interface Presence<Update> {
|
|
343
656
|
/** Sets this peer's value and broadcasts it. */
|
|
344
|
-
set(value: Update)
|
|
657
|
+
readonly set: (value: Update) => Effect.Effect<void>;
|
|
345
658
|
/** Removes this peer and broadcasts the departure. */
|
|
346
|
-
leave
|
|
659
|
+
readonly leave: Effect.Effect<void>;
|
|
347
660
|
/** Live peers, self included, with stale ones excluded. */
|
|
348
|
-
peers
|
|
661
|
+
readonly peers: Effect.Effect<ReadonlyArray<PresencePeer<Update>>>;
|
|
349
662
|
/** Drops expired peers; notifies if any went. */
|
|
350
|
-
prune
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
|
|
663
|
+
readonly prune: Effect.Effect<void>;
|
|
664
|
+
/** Notified when the peer set changes. */
|
|
665
|
+
readonly subscribe: (listener: () => void) => () => void;
|
|
666
|
+
/**
|
|
667
|
+
* The live peers, re-emitted whenever the set changes. The `Stream` form of
|
|
668
|
+
* `subscribe`, for a consumer that composes with Effect.
|
|
669
|
+
*/
|
|
670
|
+
readonly changes: Stream.Stream<ReadonlyArray<PresencePeer<Update>>>;
|
|
671
|
+
/** Stops consuming the channel; the enclosing scope also does this on exit. */
|
|
672
|
+
readonly close: Effect.Effect<void>;
|
|
354
673
|
}
|
|
355
674
|
/**
|
|
356
675
|
* Tracks ephemeral peers with a time-to-live.
|
|
357
676
|
*
|
|
358
677
|
* Nothing here touches the durable log: presence is state a peer refreshes, and
|
|
359
|
-
* a peer that stops refreshing is dropped, not replayed.
|
|
678
|
+
* a peer that stops refreshing is dropped, not replayed. Time comes from the
|
|
679
|
+
* `Clock`, so a `TestClock` drives the TTL deterministically.
|
|
360
680
|
*/
|
|
361
|
-
export declare const createPresence: <Update>(options: PresenceOptions<Update>) =>
|
|
681
|
+
export declare const createPresence: <Update>(options: PresenceOptions<Update>) => Effect.Effect<{
|
|
682
|
+
set: (value: Update) => Effect.Effect<void, never, never>;
|
|
683
|
+
leave: Effect.Effect<void, never, never>;
|
|
684
|
+
peers: Effect.Effect<{
|
|
685
|
+
id: string;
|
|
686
|
+
value: Update;
|
|
687
|
+
updatedAt: number;
|
|
688
|
+
}[], never, never>;
|
|
689
|
+
prune: Effect.Effect<void, never, never>;
|
|
690
|
+
subscribe: (listener: () => void) => () => boolean;
|
|
691
|
+
changes: Stream.Stream<{
|
|
692
|
+
id: string;
|
|
693
|
+
value: Update;
|
|
694
|
+
updatedAt: number;
|
|
695
|
+
}[], never, never>;
|
|
696
|
+
close: Effect.Effect<void, never, never>;
|
|
697
|
+
}, never, Scope.Scope>;
|
|
362
698
|
/** An in-process channel, for tests and single-process demos. */
|
|
363
|
-
export declare const loopbackPresenceChannel: <Update>() =>
|
|
699
|
+
export declare const loopbackPresenceChannel: <Update>() => Effect.Effect<{
|
|
700
|
+
updates: PubSub.PubSub<PresenceUpdate<Update>>;
|
|
701
|
+
publish: (update: PresenceUpdate<Update>) => Effect.Effect<boolean, never, never>;
|
|
702
|
+
}, never, never>;
|
|
364
703
|
/** Broadcasts presence updates among connected peers. */
|
|
365
704
|
interface PresenceHub<Update> {
|
|
366
705
|
/** Registers a peer's send; returns a leave function. */
|
|
@@ -369,10 +708,15 @@ interface PresenceHub<Update> {
|
|
|
369
708
|
publish(update: PresenceUpdate<Update>): void;
|
|
370
709
|
}
|
|
371
710
|
export declare const createPresenceHub: <Update>() => PresenceHub<Update>;
|
|
372
|
-
/**
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
711
|
+
/**
|
|
712
|
+
* A presence channel fed by stamped frames from the server, sent back without an
|
|
713
|
+
* id: the server owns peer identity, so a client cannot assert another's.
|
|
714
|
+
*/
|
|
715
|
+
export declare const socketPresenceChannel: <Update>(socket: SocketLike) => Effect.Effect<PresenceChannel<Update>, never, Scope.Scope>;
|
|
716
|
+
/** Serves presence frames on an accepted socket, stamping the connection's identity. */
|
|
717
|
+
export declare const servePresence: <Update>(socket: SocketLike, hub: PresenceHub<Update>, options: {
|
|
718
|
+
readonly peerId: string;
|
|
719
|
+
}) => (() => void);
|
|
376
720
|
//#endregion
|
|
377
|
-
export type { Checkpoint,
|
|
721
|
+
export type { ApplicationSync, AuthorizePolicy, AuthorizeRequest, Checkpoint, CommittedOperation, DefinedSync, Exchange, ExchangeFrame, ExchangeReply, FragmentMessages, JournalContract, LwwClock, LwwClockState, MakeOptions, MountOptions, MountUrl, Mounted, MsgOf, Operation, PolicyJournalContract, Presence, PresenceChannel, PresenceHub, PresenceOptions, PresencePeer, PresenceUpdate, Replica, ReplicaError, ReplicaSnapshot, ReplicaState, ReplicaStatus, SocketLike, SocketOptions, Storage, Sync, SyncDefinition, SyncFragment, TransportClient, TransportShape };
|
|
378
722
|
//# sourceMappingURL=index.d.mts.map
|