foldkit-sync 0.3.1 → 0.5.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 +823 -266
- package/dist/index.d.mts +348 -184
- package/dist/index.d.mts.map +1 -1
- package/dist/index.mjs +369 -253
- package/dist/index.mjs.map +1 -1
- package/package.json +4 -3
package/dist/index.mjs
CHANGED
|
@@ -1,10 +1,10 @@
|
|
|
1
1
|
import { Clock, Context, Duration, Effect, Exit, Fiber, Layer, Metric, PubSub, Queue, Ref, Schedule, Schema, Stream, SynchronizedRef } from "effect";
|
|
2
|
+
import { MessageSet, Projection, Surface } from "foldkit-surface";
|
|
2
3
|
import * as Navigation from "foldkit/navigation";
|
|
3
4
|
import * as Port from "foldkit/port";
|
|
4
5
|
import * as Runtime from "foldkit/runtime";
|
|
5
6
|
import * as Subscription from "foldkit/subscription";
|
|
6
7
|
import * as Url from "foldkit/url";
|
|
7
|
-
import { MessageSet, Projection, Surface } from "foldkit-surface";
|
|
8
8
|
//#region src/errors.ts
|
|
9
9
|
/** The persisted storage could not be read or written. */
|
|
10
10
|
var StorageError = class extends Schema.TaggedError()("StorageError", {
|
|
@@ -130,142 +130,6 @@ const indexedDb = Effect.fn("Storage.indexedDb")(function* (name, factory = glob
|
|
|
130
130
|
};
|
|
131
131
|
});
|
|
132
132
|
//#endregion
|
|
133
|
-
//#region src/mount.ts
|
|
134
|
-
/**
|
|
135
|
-
* `Sync.mount`: runs a Foldkit application over a replica with one reducer.
|
|
136
|
-
*
|
|
137
|
-
* A durable Message is a state-only, deterministic transition of the shared
|
|
138
|
-
* projection (the derived replay enforces it), so the application's own `update`
|
|
139
|
-
* is applied at once and the Message is persisted afterwards in a Command. The
|
|
140
|
-
* shared slice is re-installed from the replica when an exchange changes it or
|
|
141
|
-
* a persist fails, through one private Message the application never sees.
|
|
142
|
-
*/
|
|
143
|
-
const REFRESH = "foldkit-sync/Refresh";
|
|
144
|
-
const PERSISTED = "foldkit-sync/Persisted";
|
|
145
|
-
const FAILED = "foldkit-sync/PersistenceFailed";
|
|
146
|
-
const NAVIGATE = "foldkit-sync/Navigate";
|
|
147
|
-
const NAVIGATED = "foldkit-sync/Navigated";
|
|
148
|
-
/** Exchanges and rejections change what the replica holds; a submit only echoes a local edit. */
|
|
149
|
-
const sharedChanged = (previous, next) => previous === void 0 || previous.cursor !== next.cursor || previous.rejected.length !== next.rejected.length || previous.rejected.some((id, index) => id !== next.rejected[index]);
|
|
150
|
-
const mount = (app, sync, options) => {
|
|
151
|
-
if (options.container.id === "") throw new Error("Sync.mount: the container needs an id (`container.id = \"app\"`)");
|
|
152
|
-
const { replica } = options;
|
|
153
|
-
const durable = new Set(sync.contract.messages);
|
|
154
|
-
const install = (model) => sync.projection.set(model, Effect.runSync(replica.shared));
|
|
155
|
-
const inFlight = /* @__PURE__ */ new Set();
|
|
156
|
-
let latest = install(app.initial);
|
|
157
|
-
const modelListeners = /* @__PURE__ */ new Set();
|
|
158
|
-
const messageListeners = /* @__PURE__ */ new Set();
|
|
159
|
-
const update = (model, message) => {
|
|
160
|
-
switch (message._tag) {
|
|
161
|
-
case REFRESH: return { model: install(model) };
|
|
162
|
-
case PERSISTED: return { model };
|
|
163
|
-
case FAILED: {
|
|
164
|
-
const { error } = message;
|
|
165
|
-
const reverted = install(model);
|
|
166
|
-
return { model: options.onPersistenceFailure?.(reverted, error) ?? reverted };
|
|
167
|
-
}
|
|
168
|
-
case NAVIGATE: {
|
|
169
|
-
const { request } = message;
|
|
170
|
-
return {
|
|
171
|
-
model,
|
|
172
|
-
commands: [{
|
|
173
|
-
name: "foldkit-sync/navigate",
|
|
174
|
-
effect: (request._tag === "Internal" ? Navigation.pushUrl(Url.toString(request.url)) : Navigation.load(request.href)).pipe(Effect.as({ _tag: NAVIGATED }))
|
|
175
|
-
}]
|
|
176
|
-
};
|
|
177
|
-
}
|
|
178
|
-
case NAVIGATED: return { model };
|
|
179
|
-
default: {
|
|
180
|
-
for (const listener of messageListeners) listener(message);
|
|
181
|
-
const result = app.update(model, message);
|
|
182
|
-
if (!durable.has(message._tag)) return result;
|
|
183
|
-
const persist = {
|
|
184
|
-
name: "foldkit-sync/persist",
|
|
185
|
-
effect: Effect.gen(function* () {
|
|
186
|
-
let settle;
|
|
187
|
-
const done = new Promise((resolve) => {
|
|
188
|
-
settle = resolve;
|
|
189
|
-
});
|
|
190
|
-
inFlight.add(done);
|
|
191
|
-
const outcome = yield* Effect.result(replica.submit(message));
|
|
192
|
-
inFlight.delete(done);
|
|
193
|
-
settle();
|
|
194
|
-
return outcome._tag === "Success" ? { _tag: PERSISTED } : {
|
|
195
|
-
_tag: FAILED,
|
|
196
|
-
error: outcome.failure
|
|
197
|
-
};
|
|
198
|
-
})
|
|
199
|
-
};
|
|
200
|
-
return {
|
|
201
|
-
model: result.model,
|
|
202
|
-
commands: [...result.commands ?? [], persist]
|
|
203
|
-
};
|
|
204
|
-
}
|
|
205
|
-
}
|
|
206
|
-
};
|
|
207
|
-
const ports = { inbound: { message: Port.inbound(app.Message) } };
|
|
208
|
-
const own = Subscription.make()(() => ({
|
|
209
|
-
message: Port.subscription(ports.inbound.message, (message) => message),
|
|
210
|
-
refresh: Subscription.persistent(replica.statusChanges.pipe(Stream.mapAccum(() => void 0, (previous, status) => [status, sharedChanged(previous, status) ? [{ _tag: REFRESH }] : []]))),
|
|
211
|
-
latest: {
|
|
212
|
-
dependenciesSchema: Schema.Struct({}),
|
|
213
|
-
modelToDependencies: (model) => {
|
|
214
|
-
latest = model;
|
|
215
|
-
for (const listener of modelListeners) listener();
|
|
216
|
-
return {};
|
|
217
|
-
},
|
|
218
|
-
dependenciesToStream: () => Stream.never
|
|
219
|
-
}
|
|
220
|
-
}));
|
|
221
|
-
const subscriptions = options.subscriptions === void 0 ? own : Subscription.aggregate()(options.subscriptions, own);
|
|
222
|
-
const view = (model, h) => options.view(model, h);
|
|
223
|
-
const common = {
|
|
224
|
-
Model: app.Model,
|
|
225
|
-
container: options.container,
|
|
226
|
-
ports,
|
|
227
|
-
update,
|
|
228
|
-
subscriptions,
|
|
229
|
-
...options.resources === void 0 ? {} : { resources: options.resources },
|
|
230
|
-
view
|
|
231
|
-
};
|
|
232
|
-
const url = options.url;
|
|
233
|
-
const program = url === void 0 ? Runtime.makeApplication({
|
|
234
|
-
...common,
|
|
235
|
-
init: () => ({ model: latest })
|
|
236
|
-
}) : Runtime.makeApplication({
|
|
237
|
-
...common,
|
|
238
|
-
routing: {
|
|
239
|
-
onUrlChange: (at) => url.onUrlChange(at),
|
|
240
|
-
onUrlRequest: (request) => url.onUrlRequest === void 0 ? {
|
|
241
|
-
_tag: NAVIGATE,
|
|
242
|
-
request
|
|
243
|
-
} : url.onUrlRequest(request)
|
|
244
|
-
},
|
|
245
|
-
init: (at) => {
|
|
246
|
-
latest = url.init === void 0 ? latest : url.init(latest, at);
|
|
247
|
-
return { model: latest };
|
|
248
|
-
}
|
|
249
|
-
});
|
|
250
|
-
const handle = Runtime.embed(program);
|
|
251
|
-
return {
|
|
252
|
-
dispatch: (message) => handle.ports.message.send(message),
|
|
253
|
-
model: () => latest,
|
|
254
|
-
subscribe: (listener) => {
|
|
255
|
-
modelListeners.add(listener);
|
|
256
|
-
return () => modelListeners.delete(listener);
|
|
257
|
-
},
|
|
258
|
-
observe: (listener) => {
|
|
259
|
-
messageListeners.add(listener);
|
|
260
|
-
return () => messageListeners.delete(listener);
|
|
261
|
-
},
|
|
262
|
-
dispose: async () => {
|
|
263
|
-
await Promise.all([...inFlight]);
|
|
264
|
-
handle.dispose();
|
|
265
|
-
}
|
|
266
|
-
};
|
|
267
|
-
};
|
|
268
|
-
//#endregion
|
|
269
133
|
//#region src/ids.ts
|
|
270
134
|
/** Identifies the replicated document a replica or operation belongs to. */
|
|
271
135
|
const DocumentId = Schema.NonEmptyString.pipe(Schema.brand("@foldkit-sync/DocumentId"));
|
|
@@ -280,12 +144,133 @@ const OpId = Schema.NonEmptyString.pipe(Schema.brand("@foldkit-sync/OpId"));
|
|
|
280
144
|
const Sequence = Schema.Number.check(Schema.isInt(), Schema.isGreaterThanOrEqualTo(0), Schema.isLessThanOrEqualTo(Number.MAX_SAFE_INTEGER)).pipe(Schema.brand("@foldkit-sync/Sequence"));
|
|
281
145
|
/** A replica's own operation counter within a document; 1-based. */
|
|
282
146
|
const LocalSequence = Schema.Number.check(Schema.isInt(), Schema.isGreaterThanOrEqualTo(1), Schema.isLessThanOrEqualTo(Number.MAX_SAFE_INTEGER)).pipe(Schema.brand("@foldkit-sync/LocalSequence"));
|
|
147
|
+
/**
|
|
148
|
+
* Decode-and-brand helpers. A branded schema constructs the same value with
|
|
149
|
+
* `DocumentId.make('todos')`, which is the spelling to lead with; these stay
|
|
150
|
+
* for callers that already have them.
|
|
151
|
+
*/
|
|
283
152
|
const documentId = (value) => Schema.decodeUnknownSync(DocumentId)(value);
|
|
284
153
|
const replicaId = (value) => Schema.decodeUnknownSync(ReplicaId)(value);
|
|
285
154
|
const opId = (value) => Schema.decodeUnknownSync(OpId)(value);
|
|
286
155
|
const sequence = (value) => Schema.decodeUnknownSync(Sequence)(value);
|
|
287
156
|
const localSequence = (value) => Schema.decodeUnknownSync(LocalSequence)(value);
|
|
288
157
|
//#endregion
|
|
158
|
+
//#region src/lww.ts
|
|
159
|
+
/** A logical write time; replica ids break concurrent ties using UTF-16 order. */
|
|
160
|
+
const Stamp = Schema.Struct({
|
|
161
|
+
counter: Schema.Number.check(Schema.isInt(), Schema.isGreaterThanOrEqualTo(0), Schema.isLessThanOrEqualTo(Number.MAX_SAFE_INTEGER)),
|
|
162
|
+
replicaId: ReplicaId
|
|
163
|
+
});
|
|
164
|
+
/** The persisted clock format. A bump must handle the older value explicitly. */
|
|
165
|
+
const CLOCK_SCHEMA_VERSION = 1;
|
|
166
|
+
const ClockState = Schema.Struct({
|
|
167
|
+
schemaVersion: Schema.Literal(CLOCK_SCHEMA_VERSION),
|
|
168
|
+
documentId: DocumentId,
|
|
169
|
+
replicaId: ReplicaId,
|
|
170
|
+
revision: Stamp.fields.counter
|
|
171
|
+
});
|
|
172
|
+
const decodeClock = Schema.decodeUnknownSync(ClockState, { onExcessProperty: "error" });
|
|
173
|
+
const decodeCounter = Schema.decodeUnknownSync(Stamp.fields.counter);
|
|
174
|
+
const clockError = (message, cause) => new StorageError({
|
|
175
|
+
message: `${message}: ${cause instanceof Error ? cause.message : String(cause)}`,
|
|
176
|
+
cause
|
|
177
|
+
});
|
|
178
|
+
const VersionProbe = Schema.Struct({ schemaVersion: Schema.optional(Schema.Number) });
|
|
179
|
+
/**
|
|
180
|
+
* Tells a version this build does not understand apart from malformed data, so
|
|
181
|
+
* the caller gets an actionable failure and the stored state is preserved.
|
|
182
|
+
*/
|
|
183
|
+
const unsupportedVersion = (input) => {
|
|
184
|
+
let found;
|
|
185
|
+
try {
|
|
186
|
+
found = Schema.decodeUnknownSync(VersionProbe)(input);
|
|
187
|
+
} catch {
|
|
188
|
+
return;
|
|
189
|
+
}
|
|
190
|
+
if (found.schemaVersion === CLOCK_SCHEMA_VERSION) return void 0;
|
|
191
|
+
return new UnsupportedClockVersionError({
|
|
192
|
+
schemaVersion: found.schemaVersion ?? null,
|
|
193
|
+
message: `Stored clock uses schema ${found.schemaVersion ?? "?"}; this build supports ${CLOCK_SCHEMA_VERSION}`
|
|
194
|
+
});
|
|
195
|
+
};
|
|
196
|
+
/**
|
|
197
|
+
* Opens a durable clock over the caller's storage.
|
|
198
|
+
*
|
|
199
|
+
* Allocations are serialized through a `SynchronizedRef` and each persists before
|
|
200
|
+
* its stamp is returned. A crash after the save may skip a timestamp but never
|
|
201
|
+
* reuse one. Storage is owned by the caller; a failed open closes it so a partial
|
|
202
|
+
* initialization does not leak the connection.
|
|
203
|
+
*/
|
|
204
|
+
const openLwwClock = Effect.fn("Lww.openClock")(function* (options) {
|
|
205
|
+
const { documentId, replicaId, storage } = options;
|
|
206
|
+
yield* Effect.annotateCurrentSpan({
|
|
207
|
+
documentId,
|
|
208
|
+
replicaId
|
|
209
|
+
});
|
|
210
|
+
const initial = decodeClock({
|
|
211
|
+
schemaVersion: CLOCK_SCHEMA_VERSION,
|
|
212
|
+
documentId,
|
|
213
|
+
replicaId,
|
|
214
|
+
revision: 0
|
|
215
|
+
});
|
|
216
|
+
const saved = yield* storage.load();
|
|
217
|
+
const state = yield* Effect.try({
|
|
218
|
+
try: () => saved === void 0 ? initial : decodeClock(saved),
|
|
219
|
+
catch: (cause) => unsupportedVersion(saved) ?? clockError("Stored clock state is invalid", cause)
|
|
220
|
+
});
|
|
221
|
+
if (state.documentId !== documentId || state.replicaId !== replicaId) return yield* new StorageError({ message: "Wrong clock storage" });
|
|
222
|
+
if (saved === void 0) yield* storage.save(state, null);
|
|
223
|
+
const stateRef = yield* SynchronizedRef.make(state);
|
|
224
|
+
const closed = yield* Ref.make(false);
|
|
225
|
+
return {
|
|
226
|
+
next: Effect.fn("Lww.next")(function* (observedCounter = 0) {
|
|
227
|
+
if (yield* Ref.get(closed)) return yield* new StorageError({ message: "Clock is closed" });
|
|
228
|
+
return yield* SynchronizedRef.modifyEffect(stateRef, (current) => Effect.gen(function* () {
|
|
229
|
+
if (yield* Ref.get(closed)) return yield* new StorageError({ message: "Clock is closed" });
|
|
230
|
+
const allocated = yield* Effect.try({
|
|
231
|
+
try: () => decodeClock({
|
|
232
|
+
...current,
|
|
233
|
+
revision: Math.max(current.revision, decodeCounter(observedCounter)) + 1
|
|
234
|
+
}),
|
|
235
|
+
catch: (cause) => clockError("Invalid clock allocation", cause)
|
|
236
|
+
});
|
|
237
|
+
yield* storage.save(allocated, current.revision);
|
|
238
|
+
return [{
|
|
239
|
+
counter: allocated.revision,
|
|
240
|
+
replicaId
|
|
241
|
+
}, allocated];
|
|
242
|
+
}));
|
|
243
|
+
}),
|
|
244
|
+
close: Effect.fn("Lww.close")(function* () {
|
|
245
|
+
if (yield* Ref.modify(closed, (current) => [current, true])) return;
|
|
246
|
+
yield* SynchronizedRef.modifyEffect(stateRef, (current) => Effect.succeed([void 0, current]));
|
|
247
|
+
yield* storage.close;
|
|
248
|
+
})()
|
|
249
|
+
};
|
|
250
|
+
}, (effect, options) => effect.pipe(Effect.onExit((exit) => Exit.isSuccess(exit) ? Effect.void : options.storage.close.pipe(Effect.ignore))));
|
|
251
|
+
/**
|
|
252
|
+
* A schema and reducer helper for a last-writer-wins register.
|
|
253
|
+
* Allocate a unique stamp per write before dispatch, and retain it in the Message.
|
|
254
|
+
* Merge is for decoded values; the application's schema validates wire input.
|
|
255
|
+
*/
|
|
256
|
+
const lwwRegister = (value) => {
|
|
257
|
+
const schema = Schema.Struct({
|
|
258
|
+
stamp: Stamp,
|
|
259
|
+
value
|
|
260
|
+
});
|
|
261
|
+
const equivalent = Schema.toEquivalence(value);
|
|
262
|
+
const merge = (left, right) => {
|
|
263
|
+
if (left.stamp.counter !== right.stamp.counter) return left.stamp.counter > right.stamp.counter ? left : right;
|
|
264
|
+
if (left.stamp.replicaId !== right.stamp.replicaId) return left.stamp.replicaId > right.stamp.replicaId ? left : right;
|
|
265
|
+
if (!equivalent(left.value, right.value)) throw new Error("Conflicting LWW write identity");
|
|
266
|
+
return left;
|
|
267
|
+
};
|
|
268
|
+
return {
|
|
269
|
+
schema,
|
|
270
|
+
merge
|
|
271
|
+
};
|
|
272
|
+
};
|
|
273
|
+
//#endregion
|
|
289
274
|
//#region src/transport.ts
|
|
290
275
|
/** The wire failure of a transport. A refusal is a result, not an error. */
|
|
291
276
|
var TransportError = class extends Schema.TaggedError()("SyncTransportError", { message: Schema.String }) {};
|
|
@@ -735,7 +720,9 @@ const defineSync = (definition) => {
|
|
|
735
720
|
lastError: yield* Ref.get(lastError),
|
|
736
721
|
rejected: yield* Ref.get(rejectedOps)
|
|
737
722
|
},
|
|
738
|
-
shared: projected
|
|
723
|
+
shared: projected,
|
|
724
|
+
committed: current.committed,
|
|
725
|
+
nextLocalSequence: current.nextLocalSequence
|
|
739
726
|
};
|
|
740
727
|
})();
|
|
741
728
|
const shared = Effect.map(snapshot, (value) => value.shared);
|
|
@@ -893,6 +880,8 @@ const defineSync = (definition) => {
|
|
|
893
880
|
});
|
|
894
881
|
return {
|
|
895
882
|
shared,
|
|
883
|
+
snapshot,
|
|
884
|
+
committed: Effect.map(SynchronizedRef.get(stateRef), (state) => state.committed),
|
|
896
885
|
pending: Effect.map(SynchronizedRef.get(stateRef), (state) => state.pending),
|
|
897
886
|
cursor: Effect.map(SynchronizedRef.get(stateRef), (state) => state.cursor),
|
|
898
887
|
status,
|
|
@@ -987,10 +976,11 @@ const build = (app) => {
|
|
|
987
976
|
if (durable.owner !== app.owner) throw new Error("Sync.make: the durable subset belongs to a different application");
|
|
988
977
|
const replay = options.replay === void 0 ? derivedReplay(app, shared) : (value, message) => options.replay(value, message);
|
|
989
978
|
const durableTags = new Set(durable.constructors.map(messageTag).filter((tag) => tag !== void 0));
|
|
979
|
+
const sharedCodec = shared.schema;
|
|
990
980
|
const sync = defineSync({
|
|
991
981
|
documentId: options.documentId,
|
|
992
982
|
message: app.Message,
|
|
993
|
-
shared:
|
|
983
|
+
shared: sharedCodec,
|
|
994
984
|
empty: shared.get(app.initial),
|
|
995
985
|
durable: (message) => {
|
|
996
986
|
const tag = message._tag;
|
|
@@ -1015,13 +1005,7 @@ const build = (app) => {
|
|
|
1015
1005
|
}
|
|
1016
1006
|
};
|
|
1017
1007
|
};
|
|
1018
|
-
const readOnly = {
|
|
1019
|
-
Model: shared.schema,
|
|
1020
|
-
dependencies: shared.dependencies,
|
|
1021
|
-
requirements: [],
|
|
1022
|
-
connections: [],
|
|
1023
|
-
read: shared.get
|
|
1024
|
-
};
|
|
1008
|
+
const readOnly = Projection.fromReader(sharedCodec, shared.get, { dependencies: shared.dependencies });
|
|
1025
1009
|
const surface = Surface.make(app, options.name ?? String(options.documentId), {
|
|
1026
1010
|
model: () => readOnly,
|
|
1027
1011
|
messages: durable.constructors
|
|
@@ -1033,13 +1017,14 @@ const build = (app) => {
|
|
|
1033
1017
|
owns: shared.dependencies,
|
|
1034
1018
|
observes: shared.dependencies,
|
|
1035
1019
|
messages: [...durable.tags],
|
|
1036
|
-
|
|
1020
|
+
metadata: []
|
|
1037
1021
|
};
|
|
1038
1022
|
return {
|
|
1039
1023
|
...sync,
|
|
1040
1024
|
journalContract,
|
|
1041
1025
|
surface,
|
|
1042
1026
|
projection: shared,
|
|
1027
|
+
replay,
|
|
1043
1028
|
messages: durable.constructors,
|
|
1044
1029
|
contract
|
|
1045
1030
|
};
|
|
@@ -1058,119 +1043,192 @@ const build = (app) => {
|
|
|
1058
1043
|
};
|
|
1059
1044
|
};
|
|
1060
1045
|
//#endregion
|
|
1061
|
-
//#region src/
|
|
1062
|
-
/** A logical write time; replica ids break concurrent ties using UTF-16 order. */
|
|
1063
|
-
const Stamp = Schema.Struct({
|
|
1064
|
-
counter: Schema.Number.check(Schema.isInt(), Schema.isGreaterThanOrEqualTo(0), Schema.isLessThanOrEqualTo(Number.MAX_SAFE_INTEGER)),
|
|
1065
|
-
replicaId: ReplicaId
|
|
1066
|
-
});
|
|
1067
|
-
/** The persisted clock format. A bump must handle the older value explicitly. */
|
|
1068
|
-
const CLOCK_SCHEMA_VERSION = 1;
|
|
1069
|
-
const ClockState = Schema.Struct({
|
|
1070
|
-
schemaVersion: Schema.Literal(CLOCK_SCHEMA_VERSION),
|
|
1071
|
-
documentId: DocumentId,
|
|
1072
|
-
replicaId: ReplicaId,
|
|
1073
|
-
revision: Stamp.fields.counter
|
|
1074
|
-
});
|
|
1075
|
-
const decodeClock = Schema.decodeUnknownSync(ClockState, { onExcessProperty: "error" });
|
|
1076
|
-
const decodeCounter = Schema.decodeUnknownSync(Stamp.fields.counter);
|
|
1077
|
-
const clockError = (message, cause) => new StorageError({
|
|
1078
|
-
message: `${message}: ${cause instanceof Error ? cause.message : String(cause)}`,
|
|
1079
|
-
cause
|
|
1080
|
-
});
|
|
1081
|
-
const VersionProbe = Schema.Struct({ schemaVersion: Schema.optional(Schema.Number) });
|
|
1046
|
+
//#region src/mount.ts
|
|
1082
1047
|
/**
|
|
1083
|
-
*
|
|
1084
|
-
*
|
|
1048
|
+
* `Sync.mount`: runs a Foldkit application over a replica with one reducer.
|
|
1049
|
+
*
|
|
1050
|
+
* A durable Message is a state-only, deterministic transition of the shared
|
|
1051
|
+
* projection (the derived replay enforces it), so the application's own `update`
|
|
1052
|
+
* is applied at once and the Message is persisted afterwards in a Command. The
|
|
1053
|
+
* shared slice is re-installed from the replica when an exchange changes it or
|
|
1054
|
+
* a persist fails, through one private Message the application never sees.
|
|
1085
1055
|
*/
|
|
1086
|
-
const
|
|
1087
|
-
|
|
1088
|
-
|
|
1089
|
-
|
|
1090
|
-
|
|
1091
|
-
return;
|
|
1092
|
-
}
|
|
1093
|
-
if (found.schemaVersion === CLOCK_SCHEMA_VERSION) return void 0;
|
|
1094
|
-
return new UnsupportedClockVersionError({
|
|
1095
|
-
schemaVersion: found.schemaVersion ?? null,
|
|
1096
|
-
message: `Stored clock uses schema ${found.schemaVersion ?? "?"}; this build supports ${CLOCK_SCHEMA_VERSION}`
|
|
1097
|
-
});
|
|
1098
|
-
};
|
|
1056
|
+
const REFRESH = "foldkit-sync/Refresh";
|
|
1057
|
+
const PERSISTED = "foldkit-sync/Persisted";
|
|
1058
|
+
const FAILED = "foldkit-sync/PersistenceFailed";
|
|
1059
|
+
const NAVIGATE = "foldkit-sync/Navigate";
|
|
1060
|
+
const NAVIGATED = "foldkit-sync/Navigated";
|
|
1099
1061
|
/**
|
|
1100
|
-
*
|
|
1101
|
-
*
|
|
1102
|
-
*
|
|
1103
|
-
* its stamp is returned. A crash after the save may skip a timestamp but never
|
|
1104
|
-
* reuse one. Storage is owned by the caller; a failed open closes it so a partial
|
|
1105
|
-
* initialization does not leak the connection.
|
|
1062
|
+
* Commits, rejections and acknowledgments change what the replica holds; a
|
|
1063
|
+
* submit only echoes a local edit. An acknowledgment that does not return the
|
|
1064
|
+
* operation moves no cursor, but it still drops the edit from the outbox.
|
|
1106
1065
|
*/
|
|
1107
|
-
const
|
|
1108
|
-
const { documentId, replicaId, storage } = options;
|
|
1109
|
-
yield* Effect.annotateCurrentSpan({
|
|
1110
|
-
documentId,
|
|
1111
|
-
replicaId
|
|
1112
|
-
});
|
|
1113
|
-
const initial = decodeClock({
|
|
1114
|
-
schemaVersion: CLOCK_SCHEMA_VERSION,
|
|
1115
|
-
documentId,
|
|
1116
|
-
replicaId,
|
|
1117
|
-
revision: 0
|
|
1118
|
-
});
|
|
1119
|
-
const saved = yield* storage.load();
|
|
1120
|
-
const state = yield* Effect.try({
|
|
1121
|
-
try: () => saved === void 0 ? initial : decodeClock(saved),
|
|
1122
|
-
catch: (cause) => unsupportedVersion(saved) ?? clockError("Stored clock state is invalid", cause)
|
|
1123
|
-
});
|
|
1124
|
-
if (state.documentId !== documentId || state.replicaId !== replicaId) return yield* new StorageError({ message: "Wrong clock storage" });
|
|
1125
|
-
if (saved === void 0) yield* storage.save(state, null);
|
|
1126
|
-
const stateRef = yield* SynchronizedRef.make(state);
|
|
1127
|
-
const closed = yield* Ref.make(false);
|
|
1128
|
-
return {
|
|
1129
|
-
next: Effect.fn("Lww.next")(function* (observedCounter = 0) {
|
|
1130
|
-
if (yield* Ref.get(closed)) return yield* new StorageError({ message: "Clock is closed" });
|
|
1131
|
-
return yield* SynchronizedRef.modifyEffect(stateRef, (current) => Effect.gen(function* () {
|
|
1132
|
-
if (yield* Ref.get(closed)) return yield* new StorageError({ message: "Clock is closed" });
|
|
1133
|
-
const allocated = yield* Effect.try({
|
|
1134
|
-
try: () => decodeClock({
|
|
1135
|
-
...current,
|
|
1136
|
-
revision: Math.max(current.revision, decodeCounter(observedCounter)) + 1
|
|
1137
|
-
}),
|
|
1138
|
-
catch: (cause) => clockError("Invalid clock allocation", cause)
|
|
1139
|
-
});
|
|
1140
|
-
yield* storage.save(allocated, current.revision);
|
|
1141
|
-
return [{
|
|
1142
|
-
counter: allocated.revision,
|
|
1143
|
-
replicaId
|
|
1144
|
-
}, allocated];
|
|
1145
|
-
}));
|
|
1146
|
-
}),
|
|
1147
|
-
close: Effect.fn("Lww.close")(function* () {
|
|
1148
|
-
if (yield* Ref.modify(closed, (current) => [current, true])) return;
|
|
1149
|
-
yield* SynchronizedRef.modifyEffect(stateRef, (current) => Effect.succeed([void 0, current]));
|
|
1150
|
-
yield* storage.close;
|
|
1151
|
-
})()
|
|
1152
|
-
};
|
|
1153
|
-
}, (effect, options) => effect.pipe(Effect.onExit((exit) => Exit.isSuccess(exit) ? Effect.void : options.storage.close.pipe(Effect.ignore))));
|
|
1066
|
+
const sharedChanged = (previous, next) => previous === void 0 || previous.cursor !== next.cursor || next.pending < previous.pending || previous.rejected.length !== next.rejected.length || previous.rejected.some((id, index) => id !== next.rejected[index]);
|
|
1154
1067
|
/**
|
|
1155
|
-
*
|
|
1156
|
-
*
|
|
1157
|
-
*
|
|
1068
|
+
* The edits a replica whose next local sequence is `next` does not hold yet.
|
|
1069
|
+
* Submits run one at a time, so the one in flight is in the replica exactly
|
|
1070
|
+
* when its submit has moved the sequence past `started`.
|
|
1158
1071
|
*/
|
|
1159
|
-
const
|
|
1160
|
-
|
|
1161
|
-
|
|
1162
|
-
|
|
1163
|
-
|
|
1164
|
-
const
|
|
1165
|
-
|
|
1166
|
-
|
|
1167
|
-
|
|
1168
|
-
|
|
1169
|
-
|
|
1072
|
+
const unconfirmedEdits = (edits, next) => edits.filter((edit) => edit.started === void 0 || next <= edit.started).map((edit) => edit.message);
|
|
1073
|
+
const mount = (app, sync, options) => {
|
|
1074
|
+
if (options.container.id === "") throw new Error("Sync.mount: the container needs an id (`container.id = \"app\"`)");
|
|
1075
|
+
const { replica } = options;
|
|
1076
|
+
const durable = new Set(sync.contract.messages);
|
|
1077
|
+
const edits = [];
|
|
1078
|
+
let tail = Promise.resolve();
|
|
1079
|
+
const install = (model) => {
|
|
1080
|
+
const snapshot = Effect.runSync(replica.snapshot);
|
|
1081
|
+
const shared = unconfirmedEdits(edits, snapshot.nextLocalSequence).reduce((value, message) => {
|
|
1082
|
+
try {
|
|
1083
|
+
return sync.replay(value, message);
|
|
1084
|
+
} catch {
|
|
1085
|
+
return value;
|
|
1086
|
+
}
|
|
1087
|
+
}, snapshot.shared);
|
|
1088
|
+
return sync.projection.set(model, shared);
|
|
1089
|
+
};
|
|
1090
|
+
const inFlight = /* @__PURE__ */ new Set();
|
|
1091
|
+
let latest = install(app.initial);
|
|
1092
|
+
const modelListeners = /* @__PURE__ */ new Set();
|
|
1093
|
+
const committedListeners = /* @__PURE__ */ new Set();
|
|
1094
|
+
const messageListeners = /* @__PURE__ */ new Set();
|
|
1095
|
+
const notifyEach = (listeners, value) => {
|
|
1096
|
+
for (const listener of [...listeners]) try {
|
|
1097
|
+
listener(value);
|
|
1098
|
+
} catch (error) {
|
|
1099
|
+
queueMicrotask(() => {
|
|
1100
|
+
throw error;
|
|
1101
|
+
});
|
|
1102
|
+
}
|
|
1103
|
+
};
|
|
1104
|
+
const notifyCommitted = () => notifyEach(committedListeners, void 0);
|
|
1105
|
+
const update = (model, message) => {
|
|
1106
|
+
switch (message._tag) {
|
|
1107
|
+
case REFRESH: return { model: install(model) };
|
|
1108
|
+
case PERSISTED: return { model };
|
|
1109
|
+
case FAILED: {
|
|
1110
|
+
const { error } = message;
|
|
1111
|
+
const reverted = install(model);
|
|
1112
|
+
return { model: options.onPersistenceFailure?.(reverted, error) ?? reverted };
|
|
1113
|
+
}
|
|
1114
|
+
case NAVIGATE: {
|
|
1115
|
+
const { request } = message;
|
|
1116
|
+
return {
|
|
1117
|
+
model,
|
|
1118
|
+
commands: [{
|
|
1119
|
+
name: "foldkit-sync/navigate",
|
|
1120
|
+
effect: (request._tag === "Internal" ? Navigation.pushUrl(Url.toString(request.url)) : Navigation.load(request.href)).pipe(Effect.as({ _tag: NAVIGATED }))
|
|
1121
|
+
}]
|
|
1122
|
+
};
|
|
1123
|
+
}
|
|
1124
|
+
case NAVIGATED: return { model };
|
|
1125
|
+
default: {
|
|
1126
|
+
notifyEach(messageListeners, message);
|
|
1127
|
+
const result = app.update(model, message);
|
|
1128
|
+
if (!durable.has(message._tag)) return result;
|
|
1129
|
+
const edit = {
|
|
1130
|
+
message,
|
|
1131
|
+
started: void 0
|
|
1132
|
+
};
|
|
1133
|
+
edits.push(edit);
|
|
1134
|
+
const previous = tail;
|
|
1135
|
+
let settle;
|
|
1136
|
+
const done = new Promise((resolve) => {
|
|
1137
|
+
settle = resolve;
|
|
1138
|
+
});
|
|
1139
|
+
tail = done;
|
|
1140
|
+
const release = () => {
|
|
1141
|
+
const index = edits.indexOf(edit);
|
|
1142
|
+
if (index !== -1) edits.splice(index, 1);
|
|
1143
|
+
inFlight.delete(done);
|
|
1144
|
+
settle();
|
|
1145
|
+
};
|
|
1146
|
+
const persist = {
|
|
1147
|
+
name: "foldkit-sync/persist",
|
|
1148
|
+
effect: Effect.gen(function* () {
|
|
1149
|
+
inFlight.add(done);
|
|
1150
|
+
yield* Effect.promise(() => previous);
|
|
1151
|
+
edit.started = (yield* replica.snapshot).nextLocalSequence;
|
|
1152
|
+
const outcome = yield* Effect.result(replica.submit(edit.message));
|
|
1153
|
+
return outcome._tag === "Success" ? { _tag: PERSISTED } : {
|
|
1154
|
+
_tag: FAILED,
|
|
1155
|
+
error: outcome.failure
|
|
1156
|
+
};
|
|
1157
|
+
}).pipe(Effect.ensuring(Effect.sync(release)))
|
|
1158
|
+
};
|
|
1159
|
+
return {
|
|
1160
|
+
model: result.model,
|
|
1161
|
+
commands: [...result.commands ?? [], persist]
|
|
1162
|
+
};
|
|
1163
|
+
}
|
|
1164
|
+
}
|
|
1165
|
+
};
|
|
1166
|
+
const ports = { inbound: { message: Port.inbound(app.Message) } };
|
|
1167
|
+
const own = Subscription.make()(() => ({
|
|
1168
|
+
message: Port.subscription(ports.inbound.message, (message) => message),
|
|
1169
|
+
refresh: Subscription.persistent(replica.statusChanges.pipe(Stream.tap(() => Effect.sync(notifyCommitted)), Stream.mapAccum(() => void 0, (previous, status) => [status, sharedChanged(previous, status) ? [{ _tag: REFRESH }] : []]))),
|
|
1170
|
+
latest: {
|
|
1171
|
+
dependenciesSchema: Schema.Struct({}),
|
|
1172
|
+
modelToDependencies: (model) => {
|
|
1173
|
+
latest = model;
|
|
1174
|
+
notifyEach(modelListeners, void 0);
|
|
1175
|
+
return {};
|
|
1176
|
+
},
|
|
1177
|
+
dependenciesToStream: () => Stream.never
|
|
1178
|
+
}
|
|
1179
|
+
}));
|
|
1180
|
+
const subscriptions = options.subscriptions === void 0 ? own : Subscription.aggregate()(options.subscriptions, own);
|
|
1181
|
+
const view = (model, h) => options.view(model, h);
|
|
1182
|
+
const common = {
|
|
1183
|
+
Model: app.Model,
|
|
1184
|
+
container: options.container,
|
|
1185
|
+
ports,
|
|
1186
|
+
update,
|
|
1187
|
+
subscriptions,
|
|
1188
|
+
...options.resources === void 0 ? {} : { resources: options.resources },
|
|
1189
|
+
view
|
|
1170
1190
|
};
|
|
1191
|
+
const url = options.url;
|
|
1192
|
+
const program = url === void 0 ? Runtime.makeApplication({
|
|
1193
|
+
...common,
|
|
1194
|
+
init: () => ({ model: latest })
|
|
1195
|
+
}) : Runtime.makeApplication({
|
|
1196
|
+
...common,
|
|
1197
|
+
routing: {
|
|
1198
|
+
onUrlChange: (at) => url.onUrlChange(at),
|
|
1199
|
+
onUrlRequest: (request) => url.onUrlRequest === void 0 ? {
|
|
1200
|
+
_tag: NAVIGATE,
|
|
1201
|
+
request
|
|
1202
|
+
} : url.onUrlRequest(request)
|
|
1203
|
+
},
|
|
1204
|
+
init: (at) => {
|
|
1205
|
+
latest = url.init === void 0 ? latest : url.init(latest, at);
|
|
1206
|
+
return { model: latest };
|
|
1207
|
+
}
|
|
1208
|
+
});
|
|
1209
|
+
const handle = Runtime.embed(program);
|
|
1171
1210
|
return {
|
|
1172
|
-
|
|
1173
|
-
|
|
1211
|
+
dispatch: (message) => handle.ports.message.send(message),
|
|
1212
|
+
model: () => latest,
|
|
1213
|
+
subscribe: (listener) => {
|
|
1214
|
+
modelListeners.add(listener);
|
|
1215
|
+
return () => modelListeners.delete(listener);
|
|
1216
|
+
},
|
|
1217
|
+
observe: (listener) => {
|
|
1218
|
+
messageListeners.add(listener);
|
|
1219
|
+
return () => messageListeners.delete(listener);
|
|
1220
|
+
},
|
|
1221
|
+
committed: {
|
|
1222
|
+
get: () => Effect.runSync(replica.committed),
|
|
1223
|
+
subscribe: (listener) => {
|
|
1224
|
+
committedListeners.add(listener);
|
|
1225
|
+
return () => committedListeners.delete(listener);
|
|
1226
|
+
}
|
|
1227
|
+
},
|
|
1228
|
+
dispose: async () => {
|
|
1229
|
+
await Promise.all([...inFlight]);
|
|
1230
|
+
handle.dispose();
|
|
1231
|
+
}
|
|
1174
1232
|
};
|
|
1175
1233
|
};
|
|
1176
1234
|
//#endregion
|
|
@@ -1361,6 +1419,64 @@ const servePresence = (socket, hub, options) => {
|
|
|
1361
1419
|
};
|
|
1362
1420
|
};
|
|
1363
1421
|
//#endregion
|
|
1364
|
-
|
|
1422
|
+
//#region src/index.ts
|
|
1423
|
+
/**
|
|
1424
|
+
* `foldkit-sync` — a local-first replica of a shared Foldkit projection.
|
|
1425
|
+
*
|
|
1426
|
+
* The application's Message union and update function stay authoritative: sync
|
|
1427
|
+
* wraps them rather than introducing a second reducer. The replica owns the
|
|
1428
|
+
* local outbox, optimistic projection, and reconciliation; a durable server
|
|
1429
|
+
* journal provides authoritative order.
|
|
1430
|
+
*
|
|
1431
|
+
* `Sync` is the namespace: `Sync.forApplication`, `Sync.mount`,
|
|
1432
|
+
* `Sync.transport.socket`. Ids are branded schemas, so they construct through
|
|
1433
|
+
* `DocumentId.make('todos')`. Every name is also exported on its own.
|
|
1434
|
+
*/
|
|
1435
|
+
/** The package's public surface, grouped. Each entry is the exported function itself. */
|
|
1436
|
+
const Sync = {
|
|
1437
|
+
/** Derives a sync contract from a Foldkit application: `Sync.forApplication(App).make({…})`. */
|
|
1438
|
+
forApplication,
|
|
1439
|
+
/** The protocol primitive, for a client with no Foldkit application to derive from. */
|
|
1440
|
+
define: defineSync,
|
|
1441
|
+
/** Runs a Foldkit application over an open replica with one reducer. */
|
|
1442
|
+
mount,
|
|
1443
|
+
/** Counters and a histogram an application can scrape. */
|
|
1444
|
+
metrics: syncMetrics,
|
|
1445
|
+
/** The only storage adapter: one IndexedDB database per document/replica. */
|
|
1446
|
+
indexedDb,
|
|
1447
|
+
/** The `Transport` service's layers, and the bridges to and from a promise client. */
|
|
1448
|
+
transport: {
|
|
1449
|
+
/** A reconnecting WebSocket client layer. */
|
|
1450
|
+
socket: layerSocket,
|
|
1451
|
+
/** An in-process layer, for tests and single-process demos. */
|
|
1452
|
+
loopback: layerLoopback,
|
|
1453
|
+
/** Wraps the promise-based client the replica already speaks. */
|
|
1454
|
+
fromPromise: layerFromPromise,
|
|
1455
|
+
/** Bridges the service back to that promise client. */
|
|
1456
|
+
toPromise,
|
|
1457
|
+
/** The server side of one accepted socket connection. */
|
|
1458
|
+
serve: serveSocket,
|
|
1459
|
+
/** The default socket factory: the platform `WebSocket`. */
|
|
1460
|
+
nativeSocket
|
|
1461
|
+
},
|
|
1462
|
+
/** An ephemeral, TTL'd peer registry, deliberately outside the durable log. */
|
|
1463
|
+
presence: {
|
|
1464
|
+
make: createPresence,
|
|
1465
|
+
/** Broadcasts presence updates among connected peers, on the server. */
|
|
1466
|
+
hub: createPresenceHub,
|
|
1467
|
+
/** Serves presence frames on an accepted socket, stamping the connection's identity. */
|
|
1468
|
+
serve: servePresence,
|
|
1469
|
+
socketChannel: socketPresenceChannel,
|
|
1470
|
+
loopbackChannel: loopbackPresenceChannel
|
|
1471
|
+
},
|
|
1472
|
+
/** Last-writer-wins registers (experimental): a per-field merge on logical time. */
|
|
1473
|
+
lww: {
|
|
1474
|
+
register: lwwRegister,
|
|
1475
|
+
/** The durable counter a stamp is allocated from, before dispatch. */
|
|
1476
|
+
openClock: openLwwClock
|
|
1477
|
+
}
|
|
1478
|
+
};
|
|
1479
|
+
//#endregion
|
|
1480
|
+
export { CheckpointRegressionError, CommittedOrderError, DocumentId, ForeignAcknowledgementError, ForeignRejectionError, InvalidExchangeError, InvalidOutboxError, InvalidReplicaHistoryError, LocalSequence, OpId, ReplayError, ReplicaClosedError, ReplicaId, Sequence, StorageError, Sync, Transport, TransportError, UnsupportedClockVersionError, UnsupportedReplicaVersionError, WrongReplicaStorageError, createPresence, createPresenceHub, defineSync, documentId, forApplication, indexedDb, layerFromPromise, layerLoopback, layerSocket, localSequence, loopbackPresenceChannel, lwwRegister, mount, nativeSocket, opId, openLwwClock, replicaId, sequence, servePresence, serveSocket, socketPresenceChannel, syncMetrics, toPromise };
|
|
1365
1481
|
|
|
1366
1482
|
//# sourceMappingURL=index.mjs.map
|