@terreno/syncdb 56.0.0-beta.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 +419 -0
- package/dist/auth/betterAuthAdapter.d.ts +22 -0
- package/dist/auth/betterAuthAdapter.d.ts.map +1 -0
- package/dist/auth/betterAuthAdapter.js +181 -0
- package/dist/auth/betterAuthAdapter.js.map +1 -0
- package/dist/auth/betterAuthAdapter.test.d.ts +2 -0
- package/dist/auth/betterAuthAdapter.test.d.ts.map +1 -0
- package/dist/auth/betterAuthAdapter.test.js +350 -0
- package/dist/auth/betterAuthAdapter.test.js.map +1 -0
- package/dist/auth/types.d.ts +42 -0
- package/dist/auth/types.d.ts.map +1 -0
- package/dist/auth/types.js +9 -0
- package/dist/auth/types.js.map +1 -0
- package/dist/client.d.ts +246 -0
- package/dist/client.d.ts.map +1 -0
- package/dist/client.js +1415 -0
- package/dist/client.js.map +1 -0
- package/dist/client.test.d.ts +2 -0
- package/dist/client.test.d.ts.map +1 -0
- package/dist/client.test.js +2310 -0
- package/dist/client.test.js.map +1 -0
- package/dist/crypto/aesGcmCodec.d.ts +33 -0
- package/dist/crypto/aesGcmCodec.d.ts.map +1 -0
- package/dist/crypto/aesGcmCodec.js +80 -0
- package/dist/crypto/aesGcmCodec.js.map +1 -0
- package/dist/crypto/aesGcmCodec.test.d.ts +2 -0
- package/dist/crypto/aesGcmCodec.test.d.ts.map +1 -0
- package/dist/crypto/aesGcmCodec.test.js +83 -0
- package/dist/crypto/aesGcmCodec.test.js.map +1 -0
- package/dist/crypto/identityCodec.d.ts +7 -0
- package/dist/crypto/identityCodec.d.ts.map +1 -0
- package/dist/crypto/identityCodec.js +9 -0
- package/dist/crypto/identityCodec.js.map +1 -0
- package/dist/crypto/keyProviders.d.ts +34 -0
- package/dist/crypto/keyProviders.d.ts.map +1 -0
- package/dist/crypto/keyProviders.js +102 -0
- package/dist/crypto/keyProviders.js.map +1 -0
- package/dist/crypto/keyProviders.test.d.ts +2 -0
- package/dist/crypto/keyProviders.test.d.ts.map +1 -0
- package/dist/crypto/keyProviders.test.js +189 -0
- package/dist/crypto/keyProviders.test.js.map +1 -0
- package/dist/crypto/types.d.ts +24 -0
- package/dist/crypto/types.d.ts.map +1 -0
- package/dist/crypto/types.js +8 -0
- package/dist/crypto/types.js.map +1 -0
- package/dist/debug/debugChannel.d.ts +52 -0
- package/dist/debug/debugChannel.d.ts.map +1 -0
- package/dist/debug/debugChannel.js +73 -0
- package/dist/debug/debugChannel.js.map +1 -0
- package/dist/debug/debugChannel.test.d.ts +2 -0
- package/dist/debug/debugChannel.test.d.ts.map +1 -0
- package/dist/debug/debugChannel.test.js +105 -0
- package/dist/debug/debugChannel.test.js.map +1 -0
- package/dist/debug/debugLog.d.ts +111 -0
- package/dist/debug/debugLog.d.ts.map +1 -0
- package/dist/debug/debugLog.js +150 -0
- package/dist/debug/debugLog.js.map +1 -0
- package/dist/debug/debugLog.test.d.ts +2 -0
- package/dist/debug/debugLog.test.d.ts.map +1 -0
- package/dist/debug/debugLog.test.js +121 -0
- package/dist/debug/debugLog.test.js.map +1 -0
- package/dist/index.d.ts +46 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +51 -0
- package/dist/index.js.map +1 -0
- package/dist/isolated/defaultPersisterFactoryNative.isolated.d.ts +2 -0
- package/dist/isolated/defaultPersisterFactoryNative.isolated.d.ts.map +1 -0
- package/dist/isolated/defaultPersisterFactoryNative.isolated.js +38 -0
- package/dist/isolated/defaultPersisterFactoryNative.isolated.js.map +1 -0
- package/dist/mutations/conflicts.d.ts +31 -0
- package/dist/mutations/conflicts.d.ts.map +1 -0
- package/dist/mutations/conflicts.js +73 -0
- package/dist/mutations/conflicts.js.map +1 -0
- package/dist/mutations/outbox.d.ts +174 -0
- package/dist/mutations/outbox.d.ts.map +1 -0
- package/dist/mutations/outbox.js +385 -0
- package/dist/mutations/outbox.js.map +1 -0
- package/dist/mutations/outbox.test.d.ts +2 -0
- package/dist/mutations/outbox.test.d.ts.map +1 -0
- package/dist/mutations/outbox.test.js +643 -0
- package/dist/mutations/outbox.test.js.map +1 -0
- package/dist/mutations/resolveConflict.d.ts +32 -0
- package/dist/mutations/resolveConflict.d.ts.map +1 -0
- package/dist/mutations/resolveConflict.js +101 -0
- package/dist/mutations/resolveConflict.js.map +1 -0
- package/dist/mutations/resolveConflict.test.d.ts +2 -0
- package/dist/mutations/resolveConflict.test.d.ts.map +1 -0
- package/dist/mutations/resolveConflict.test.js +282 -0
- package/dist/mutations/resolveConflict.test.js.map +1 -0
- package/dist/persisters/defaultPersisterFactory.d.ts +9 -0
- package/dist/persisters/defaultPersisterFactory.d.ts.map +1 -0
- package/dist/persisters/defaultPersisterFactory.js +9 -0
- package/dist/persisters/defaultPersisterFactory.js.map +1 -0
- package/dist/persisters/defaultPersisterFactory.native.d.ts +10 -0
- package/dist/persisters/defaultPersisterFactory.native.d.ts.map +1 -0
- package/dist/persisters/defaultPersisterFactory.native.js +44 -0
- package/dist/persisters/defaultPersisterFactory.native.js.map +1 -0
- package/dist/persisters/defaultPersisterFactory.test.d.ts +2 -0
- package/dist/persisters/defaultPersisterFactory.test.d.ts.map +1 -0
- package/dist/persisters/defaultPersisterFactory.test.js +177 -0
- package/dist/persisters/defaultPersisterFactory.test.js.map +1 -0
- package/dist/persisters/defaultPersisterFactory.web.d.ts +17 -0
- package/dist/persisters/defaultPersisterFactory.web.d.ts.map +1 -0
- package/dist/persisters/defaultPersisterFactory.web.js +65 -0
- package/dist/persisters/defaultPersisterFactory.web.js.map +1 -0
- package/dist/persisters/encryptedIndexedDbPersister.d.ts +46 -0
- package/dist/persisters/encryptedIndexedDbPersister.d.ts.map +1 -0
- package/dist/persisters/encryptedIndexedDbPersister.js +171 -0
- package/dist/persisters/encryptedIndexedDbPersister.js.map +1 -0
- package/dist/persisters/encryptedIndexedDbPersister.test.d.ts +2 -0
- package/dist/persisters/encryptedIndexedDbPersister.test.d.ts.map +1 -0
- package/dist/persisters/encryptedIndexedDbPersister.test.js +352 -0
- package/dist/persisters/encryptedIndexedDbPersister.test.js.map +1 -0
- package/dist/persisters/memoryPersister.d.ts +19 -0
- package/dist/persisters/memoryPersister.d.ts.map +1 -0
- package/dist/persisters/memoryPersister.js +31 -0
- package/dist/persisters/memoryPersister.js.map +1 -0
- package/dist/persisters/memoryPersister.test.d.ts +2 -0
- package/dist/persisters/memoryPersister.test.d.ts.map +1 -0
- package/dist/persisters/memoryPersister.test.js +113 -0
- package/dist/persisters/memoryPersister.test.js.map +1 -0
- package/dist/persisters/types.d.ts +65 -0
- package/dist/persisters/types.d.ts.map +1 -0
- package/dist/persisters/types.js +2 -0
- package/dist/persisters/types.js.map +1 -0
- package/dist/react/hooks.d.ts +132 -0
- package/dist/react/hooks.d.ts.map +1 -0
- package/dist/react/hooks.js +269 -0
- package/dist/react/hooks.js.map +1 -0
- package/dist/react/hooks.test.d.ts +2 -0
- package/dist/react/hooks.test.d.ts.map +1 -0
- package/dist/react/hooks.test.js +645 -0
- package/dist/react/hooks.test.js.map +1 -0
- package/dist/react/index.d.ts +11 -0
- package/dist/react/index.d.ts.map +1 -0
- package/dist/react/index.js +11 -0
- package/dist/react/index.js.map +1 -0
- package/dist/react/provider.d.ts +11 -0
- package/dist/react/provider.d.ts.map +1 -0
- package/dist/react/provider.js +17 -0
- package/dist/react/provider.js.map +1 -0
- package/dist/storage/idb.d.ts +27 -0
- package/dist/storage/idb.d.ts.map +1 -0
- package/dist/storage/idb.js +72 -0
- package/dist/storage/idb.js.map +1 -0
- package/dist/storage/idb.test.d.ts +2 -0
- package/dist/storage/idb.test.d.ts.map +1 -0
- package/dist/storage/idb.test.js +100 -0
- package/dist/storage/idb.test.js.map +1 -0
- package/dist/storage/purgeUnknownStream.test.d.ts +2 -0
- package/dist/storage/purgeUnknownStream.test.d.ts.map +1 -0
- package/dist/storage/purgeUnknownStream.test.js +64 -0
- package/dist/storage/purgeUnknownStream.test.js.map +1 -0
- package/dist/storage/schema.d.ts +33 -0
- package/dist/storage/schema.d.ts.map +1 -0
- package/dist/storage/schema.js +92 -0
- package/dist/storage/schema.js.map +1 -0
- package/dist/storage/store.d.ts +136 -0
- package/dist/storage/store.d.ts.map +1 -0
- package/dist/storage/store.js +275 -0
- package/dist/storage/store.js.map +1 -0
- package/dist/storage/store.test.d.ts +2 -0
- package/dist/storage/store.test.d.ts.map +1 -0
- package/dist/storage/store.test.js +357 -0
- package/dist/storage/store.test.js.map +1 -0
- package/dist/storage/types.d.ts +146 -0
- package/dist/storage/types.d.ts.map +1 -0
- package/dist/storage/types.js +32 -0
- package/dist/storage/types.js.map +1 -0
- package/dist/storage/wipe.d.ts +22 -0
- package/dist/storage/wipe.d.ts.map +1 -0
- package/dist/storage/wipe.js +43 -0
- package/dist/storage/wipe.js.map +1 -0
- package/dist/storage/wipe.test.d.ts +2 -0
- package/dist/storage/wipe.test.d.ts.map +1 -0
- package/dist/storage/wipe.test.js +95 -0
- package/dist/storage/wipe.test.js.map +1 -0
- package/dist/sync/bootstrap.d.ts +64 -0
- package/dist/sync/bootstrap.d.ts.map +1 -0
- package/dist/sync/bootstrap.js +160 -0
- package/dist/sync/bootstrap.js.map +1 -0
- package/dist/sync/bootstrap.test.d.ts +2 -0
- package/dist/sync/bootstrap.test.d.ts.map +1 -0
- package/dist/sync/bootstrap.test.js +447 -0
- package/dist/sync/bootstrap.test.js.map +1 -0
- package/dist/sync/cursor.d.ts +67 -0
- package/dist/sync/cursor.d.ts.map +1 -0
- package/dist/sync/cursor.js +74 -0
- package/dist/sync/cursor.js.map +1 -0
- package/dist/sync/cursor.test.d.ts +2 -0
- package/dist/sync/cursor.test.d.ts.map +1 -0
- package/dist/sync/cursor.test.js +73 -0
- package/dist/sync/cursor.test.js.map +1 -0
- package/dist/sync/deltaApplier.d.ts +30 -0
- package/dist/sync/deltaApplier.d.ts.map +1 -0
- package/dist/sync/deltaApplier.js +61 -0
- package/dist/sync/deltaApplier.js.map +1 -0
- package/dist/sync/deltaApplier.test.d.ts +2 -0
- package/dist/sync/deltaApplier.test.d.ts.map +1 -0
- package/dist/sync/deltaApplier.test.js +212 -0
- package/dist/sync/deltaApplier.test.js.map +1 -0
- package/dist/sync/entityRepair.d.ts +45 -0
- package/dist/sync/entityRepair.d.ts.map +1 -0
- package/dist/sync/entityRepair.js +91 -0
- package/dist/sync/entityRepair.js.map +1 -0
- package/dist/sync/entityRepair.test.d.ts +2 -0
- package/dist/sync/entityRepair.test.d.ts.map +1 -0
- package/dist/sync/entityRepair.test.js +146 -0
- package/dist/sync/entityRepair.test.js.map +1 -0
- package/dist/sync/httpChannel.d.ts +74 -0
- package/dist/sync/httpChannel.d.ts.map +1 -0
- package/dist/sync/httpChannel.js +123 -0
- package/dist/sync/httpChannel.js.map +1 -0
- package/dist/sync/httpChannel.test.d.ts +2 -0
- package/dist/sync/httpChannel.test.d.ts.map +1 -0
- package/dist/sync/httpChannel.test.js +215 -0
- package/dist/sync/httpChannel.test.js.map +1 -0
- package/dist/sync/replayCoordinator.d.ts +212 -0
- package/dist/sync/replayCoordinator.d.ts.map +1 -0
- package/dist/sync/replayCoordinator.js +1110 -0
- package/dist/sync/replayCoordinator.js.map +1 -0
- package/dist/sync/replayCoordinator.test.d.ts +2 -0
- package/dist/sync/replayCoordinator.test.d.ts.map +1 -0
- package/dist/sync/replayCoordinator.test.js +1496 -0
- package/dist/sync/replayCoordinator.test.js.map +1 -0
- package/dist/sync/socketTransport.d.ts +56 -0
- package/dist/sync/socketTransport.d.ts.map +1 -0
- package/dist/sync/socketTransport.js +292 -0
- package/dist/sync/socketTransport.js.map +1 -0
- package/dist/sync/socketTransport.test.d.ts +2 -0
- package/dist/sync/socketTransport.test.d.ts.map +1 -0
- package/dist/sync/socketTransport.test.js +346 -0
- package/dist/sync/socketTransport.test.js.map +1 -0
- package/dist/sync/transport.d.ts +80 -0
- package/dist/sync/transport.d.ts.map +1 -0
- package/dist/sync/transport.js +5 -0
- package/dist/sync/transport.js.map +1 -0
- package/dist/testing/fakeTransport.d.ts +55 -0
- package/dist/testing/fakeTransport.d.ts.map +1 -0
- package/dist/testing/fakeTransport.js +139 -0
- package/dist/testing/fakeTransport.js.map +1 -0
- package/dist/testing/fakeTransport.test.d.ts +2 -0
- package/dist/testing/fakeTransport.test.d.ts.map +1 -0
- package/dist/testing/fakeTransport.test.js +112 -0
- package/dist/testing/fakeTransport.test.js.map +1 -0
- package/dist/testing/index.d.ts +13 -0
- package/dist/testing/index.d.ts.map +1 -0
- package/dist/testing/index.js +13 -0
- package/dist/testing/index.js.map +1 -0
- package/dist/types.d.ts +271 -0
- package/dist/types.d.ts.map +1 -0
- package/dist/types.js +9 -0
- package/dist/types.js.map +1 -0
- package/package.json +71 -0
- package/src/auth/betterAuthAdapter.test.ts +455 -0
- package/src/auth/betterAuthAdapter.ts +214 -0
- package/src/auth/types.ts +49 -0
- package/src/client.test.ts +2670 -0
- package/src/client.ts +1748 -0
- package/src/crypto/aesGcmCodec.test.ts +103 -0
- package/src/crypto/aesGcmCodec.ts +98 -0
- package/src/crypto/identityCodec.ts +10 -0
- package/src/crypto/keyProviders.test.ts +228 -0
- package/src/crypto/keyProviders.ts +153 -0
- package/src/crypto/types.ts +23 -0
- package/src/debug/debugChannel.test.ts +121 -0
- package/src/debug/debugChannel.ts +112 -0
- package/src/debug/debugLog.test.ts +139 -0
- package/src/debug/debugLog.ts +272 -0
- package/src/index.ts +157 -0
- package/src/isolated/defaultPersisterFactoryNative.isolated.ts +45 -0
- package/src/mutations/conflicts.ts +108 -0
- package/src/mutations/outbox.test.ts +754 -0
- package/src/mutations/outbox.ts +585 -0
- package/src/mutations/resolveConflict.test.ts +338 -0
- package/src/mutations/resolveConflict.ts +115 -0
- package/src/persisters/defaultPersisterFactory.native.ts +53 -0
- package/src/persisters/defaultPersisterFactory.test.ts +207 -0
- package/src/persisters/defaultPersisterFactory.ts +12 -0
- package/src/persisters/defaultPersisterFactory.web.ts +78 -0
- package/src/persisters/encryptedIndexedDbPersister.test.ts +381 -0
- package/src/persisters/encryptedIndexedDbPersister.ts +218 -0
- package/src/persisters/memoryPersister.test.ts +136 -0
- package/src/persisters/memoryPersister.ts +52 -0
- package/src/persisters/types.ts +71 -0
- package/src/react/hooks.test.tsx +761 -0
- package/src/react/hooks.ts +409 -0
- package/src/react/index.ts +11 -0
- package/src/react/provider.tsx +27 -0
- package/src/storage/idb.test.ts +116 -0
- package/src/storage/idb.ts +112 -0
- package/src/storage/purgeUnknownStream.test.ts +74 -0
- package/src/storage/schema.ts +103 -0
- package/src/storage/store.test.ts +424 -0
- package/src/storage/store.ts +461 -0
- package/src/storage/types.ts +159 -0
- package/src/storage/wipe.test.ts +111 -0
- package/src/storage/wipe.ts +58 -0
- package/src/sync/bootstrap.test.ts +486 -0
- package/src/sync/bootstrap.ts +217 -0
- package/src/sync/cursor.test.ts +84 -0
- package/src/sync/cursor.ts +113 -0
- package/src/sync/deltaApplier.test.ts +237 -0
- package/src/sync/deltaApplier.ts +84 -0
- package/src/sync/entityRepair.test.ts +161 -0
- package/src/sync/entityRepair.ts +124 -0
- package/src/sync/httpChannel.test.ts +265 -0
- package/src/sync/httpChannel.ts +220 -0
- package/src/sync/replayCoordinator.test.ts +1709 -0
- package/src/sync/replayCoordinator.ts +1370 -0
- package/src/sync/socketTransport.test.ts +413 -0
- package/src/sync/socketTransport.ts +379 -0
- package/src/sync/transport.ts +76 -0
- package/src/testing/fakeTransport.test.ts +125 -0
- package/src/testing/fakeTransport.ts +206 -0
- package/src/testing/index.ts +18 -0
- package/src/types.ts +284 -0
|
@@ -0,0 +1,121 @@
|
|
|
1
|
+
import {describe, expect, it} from "bun:test";
|
|
2
|
+
|
|
3
|
+
import {attachDebugChannel, type DebugBroadcastChannelLike} from "./debugChannel";
|
|
4
|
+
import {createSyncDebugLog} from "./debugLog";
|
|
5
|
+
|
|
6
|
+
/**
|
|
7
|
+
* An in-memory BroadcastChannel hub so tests exercise the bridge without a real
|
|
8
|
+
* DOM `BroadcastChannel`. Every channel created from the same hub delivers each
|
|
9
|
+
* `postMessage` to all OTHER channels (never back to the sender), mirroring the
|
|
10
|
+
* real cross-window semantics we depend on.
|
|
11
|
+
*/
|
|
12
|
+
const createChannelHub = (): {
|
|
13
|
+
create: (name: string) => DebugBroadcastChannelLike;
|
|
14
|
+
} => {
|
|
15
|
+
const channels = new Set<DebugBroadcastChannelLike>();
|
|
16
|
+
return {
|
|
17
|
+
create: (_name: string): DebugBroadcastChannelLike => {
|
|
18
|
+
const channel: DebugBroadcastChannelLike = {
|
|
19
|
+
close: () => {
|
|
20
|
+
channels.delete(channel);
|
|
21
|
+
},
|
|
22
|
+
onmessage: null,
|
|
23
|
+
postMessage: (message) => {
|
|
24
|
+
for (const peer of channels) {
|
|
25
|
+
if (peer !== channel) {
|
|
26
|
+
peer.onmessage?.({data: message});
|
|
27
|
+
}
|
|
28
|
+
}
|
|
29
|
+
},
|
|
30
|
+
};
|
|
31
|
+
channels.add(channel);
|
|
32
|
+
return channel;
|
|
33
|
+
},
|
|
34
|
+
};
|
|
35
|
+
};
|
|
36
|
+
|
|
37
|
+
describe("attachDebugChannel", () => {
|
|
38
|
+
it("returns undefined when no channel is available (native/SSR)", () => {
|
|
39
|
+
const log = createSyncDebugLog();
|
|
40
|
+
const bridge = attachDebugChannel({
|
|
41
|
+
createChannel: () => undefined,
|
|
42
|
+
log,
|
|
43
|
+
name: "app",
|
|
44
|
+
});
|
|
45
|
+
expect(bridge).toBeUndefined();
|
|
46
|
+
});
|
|
47
|
+
|
|
48
|
+
it("mirrors a locally-recorded event into a peer window's log", () => {
|
|
49
|
+
const hub = createChannelHub();
|
|
50
|
+
const appLog = createSyncDebugLog();
|
|
51
|
+
const debuggerLog = createSyncDebugLog();
|
|
52
|
+
attachDebugChannel({createChannel: hub.create, log: appLog, name: "app"});
|
|
53
|
+
attachDebugChannel({createChannel: hub.create, log: debuggerLog, name: "app"});
|
|
54
|
+
|
|
55
|
+
appLog.record({
|
|
56
|
+
collection: "todos",
|
|
57
|
+
detail: {data: {title: "buy milk"}},
|
|
58
|
+
direction: "local",
|
|
59
|
+
entityId: "t1",
|
|
60
|
+
label: "create todos/t1",
|
|
61
|
+
operation: "create",
|
|
62
|
+
type: "mutate",
|
|
63
|
+
});
|
|
64
|
+
|
|
65
|
+
const mirrored = debuggerLog.getEvents();
|
|
66
|
+
expect(mirrored).toHaveLength(1);
|
|
67
|
+
expect(mirrored[0].type).toBe("mutate");
|
|
68
|
+
expect(mirrored[0].label).toBe("create todos/t1");
|
|
69
|
+
// The create/update body survives the hop so the debugger can show it.
|
|
70
|
+
expect(mirrored[0].detail?.data).toEqual({title: "buy milk"});
|
|
71
|
+
});
|
|
72
|
+
|
|
73
|
+
it("preserves the original timestamp but assigns a fresh local id on the peer", () => {
|
|
74
|
+
const hub = createChannelHub();
|
|
75
|
+
const appLog = createSyncDebugLog();
|
|
76
|
+
const debuggerLog = createSyncDebugLog();
|
|
77
|
+
// Pre-seed the peer so its next id differs from the source event's id.
|
|
78
|
+
debuggerLog.record({direction: "system", label: "seed", type: "connect"});
|
|
79
|
+
attachDebugChannel({createChannel: hub.create, log: appLog, name: "app"});
|
|
80
|
+
attachDebugChannel({createChannel: hub.create, log: debuggerLog, name: "app"});
|
|
81
|
+
|
|
82
|
+
const source = appLog.record({
|
|
83
|
+
direction: "local",
|
|
84
|
+
label: "create todos/t1",
|
|
85
|
+
timestamp: "2026-07-16T16:01:45.011-07:00",
|
|
86
|
+
type: "mutate",
|
|
87
|
+
});
|
|
88
|
+
|
|
89
|
+
const mirrored = debuggerLog.getEvents().find((event) => event.label === "create todos/t1");
|
|
90
|
+
expect(mirrored?.timestamp).toBe("2026-07-16T16:01:45.011-07:00");
|
|
91
|
+
expect(mirrored?.id).not.toBe(source.id);
|
|
92
|
+
});
|
|
93
|
+
|
|
94
|
+
it("does not echo a mirrored event back to the origin (no infinite loop)", () => {
|
|
95
|
+
const hub = createChannelHub();
|
|
96
|
+
const appLog = createSyncDebugLog();
|
|
97
|
+
const debuggerLog = createSyncDebugLog();
|
|
98
|
+
attachDebugChannel({createChannel: hub.create, log: appLog, name: "app"});
|
|
99
|
+
attachDebugChannel({createChannel: hub.create, log: debuggerLog, name: "app"});
|
|
100
|
+
|
|
101
|
+
appLog.record({direction: "local", label: "one", type: "mutate"});
|
|
102
|
+
|
|
103
|
+
// The source window keeps exactly one event; the peer's re-record must not
|
|
104
|
+
// bounce back and inflate the source log.
|
|
105
|
+
expect(appLog.getEvents()).toHaveLength(1);
|
|
106
|
+
expect(debuggerLog.getEvents()).toHaveLength(1);
|
|
107
|
+
});
|
|
108
|
+
|
|
109
|
+
it("stops mirroring after close()", () => {
|
|
110
|
+
const hub = createChannelHub();
|
|
111
|
+
const appLog = createSyncDebugLog();
|
|
112
|
+
const debuggerLog = createSyncDebugLog();
|
|
113
|
+
const appBridge = attachDebugChannel({createChannel: hub.create, log: appLog, name: "app"});
|
|
114
|
+
attachDebugChannel({createChannel: hub.create, log: debuggerLog, name: "app"});
|
|
115
|
+
|
|
116
|
+
appBridge?.close();
|
|
117
|
+
appLog.record({direction: "local", label: "after close", type: "mutate"});
|
|
118
|
+
|
|
119
|
+
expect(debuggerLog.getEvents()).toHaveLength(0);
|
|
120
|
+
});
|
|
121
|
+
});
|
|
@@ -0,0 +1,112 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Cross-window bridge for the SyncDB debug log.
|
|
3
|
+
*
|
|
4
|
+
* The debug log (see `debugLog.ts`) is an in-memory, per-client recorder. Each
|
|
5
|
+
* browser window loads the app bundle fresh, so it builds its own `SyncDb`
|
|
6
|
+
* singleton with its own log. That means the debugger — which is designed to run
|
|
7
|
+
* side-by-side in a SECOND browser window — never sees local mutations recorded
|
|
8
|
+
* by the primary app window: they live only in the app window's heap.
|
|
9
|
+
*
|
|
10
|
+
* This bridge mirrors locally-recorded events onto a `BroadcastChannel` and
|
|
11
|
+
* re-records events received from peer windows into the local log, so a debugger
|
|
12
|
+
* open in any window shows the full picture (local mutations included), live.
|
|
13
|
+
*
|
|
14
|
+
* It is web-only: on native / SSR / older runtimes without `BroadcastChannel`
|
|
15
|
+
* the default factory returns nothing and `attachDebugChannel` no-ops. The
|
|
16
|
+
* channel is only ever created when a debug log exists (dev builds by default),
|
|
17
|
+
* so there is zero overhead in production where debug is off.
|
|
18
|
+
*/
|
|
19
|
+
|
|
20
|
+
import type {SyncDebugEvent, SyncDebugLog} from "./debugLog";
|
|
21
|
+
|
|
22
|
+
/** Channel name prefix; scoped per db `name` so unrelated apps never cross-talk. */
|
|
23
|
+
const CHANNEL_PREFIX = "terreno-syncdb-debug";
|
|
24
|
+
|
|
25
|
+
/** Message shape sent between windows. `origin` lets a sender ignore echoes. */
|
|
26
|
+
interface DebugChannelMessage {
|
|
27
|
+
origin: string;
|
|
28
|
+
event: SyncDebugEvent;
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
/**
|
|
32
|
+
* Minimal structural subset of the DOM `BroadcastChannel` we rely on. Declared
|
|
33
|
+
* locally (rather than depending on DOM lib types) so the package compiles under
|
|
34
|
+
* a non-DOM `lib` and so tests can inject an in-memory fake.
|
|
35
|
+
*/
|
|
36
|
+
export interface DebugBroadcastChannelLike {
|
|
37
|
+
postMessage: (message: DebugChannelMessage) => void;
|
|
38
|
+
close: () => void;
|
|
39
|
+
onmessage: ((event: {data: DebugChannelMessage}) => void) | null;
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
export interface DebugChannelBridge {
|
|
43
|
+
/** Tear down: stop mirroring and close the underlying channel. */
|
|
44
|
+
close: () => void;
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
const defaultChannelFactory = (channelName: string): DebugBroadcastChannelLike | undefined => {
|
|
48
|
+
if (typeof BroadcastChannel === "undefined") {
|
|
49
|
+
return undefined;
|
|
50
|
+
}
|
|
51
|
+
return new BroadcastChannel(channelName) as unknown as DebugBroadcastChannelLike;
|
|
52
|
+
};
|
|
53
|
+
|
|
54
|
+
/**
|
|
55
|
+
* Wire a debug log to peer windows. Returns `undefined` when no channel is
|
|
56
|
+
* available (native / SSR), in which case the log stays purely local.
|
|
57
|
+
*/
|
|
58
|
+
export const attachDebugChannel = ({
|
|
59
|
+
log,
|
|
60
|
+
name,
|
|
61
|
+
createChannel = defaultChannelFactory,
|
|
62
|
+
}: {
|
|
63
|
+
log: SyncDebugLog;
|
|
64
|
+
name: string;
|
|
65
|
+
/** Channel factory; injectable for tests. Defaults to a real BroadcastChannel. */
|
|
66
|
+
createChannel?: (channelName: string) => DebugBroadcastChannelLike | undefined;
|
|
67
|
+
}): DebugChannelBridge | undefined => {
|
|
68
|
+
const channel = createChannel(`${CHANNEL_PREFIX}:${name}`);
|
|
69
|
+
if (!channel) {
|
|
70
|
+
return undefined;
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
// Unique per bridge instance (i.e. per window). Used to drop echoes and to
|
|
74
|
+
// keep a peer's re-recorded event from bouncing back and forth forever.
|
|
75
|
+
const origin = `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
|
|
76
|
+
|
|
77
|
+
// True only while we are re-recording a peer's event into the local log, so
|
|
78
|
+
// the subscribe callback below skips broadcasting it back out (no echo loop).
|
|
79
|
+
let ingestingRemote = false;
|
|
80
|
+
|
|
81
|
+
const unsubscribe = log.subscribe((event) => {
|
|
82
|
+
if (ingestingRemote) {
|
|
83
|
+
return;
|
|
84
|
+
}
|
|
85
|
+
channel.postMessage({event, origin});
|
|
86
|
+
});
|
|
87
|
+
|
|
88
|
+
channel.onmessage = (messageEvent): void => {
|
|
89
|
+
const data = messageEvent.data;
|
|
90
|
+
if (!data || data.origin === origin) {
|
|
91
|
+
return;
|
|
92
|
+
}
|
|
93
|
+
// Re-record the peer's event locally: it gets a fresh local id (ids only need
|
|
94
|
+
// to be monotonic within a window) but keeps its original timestamp, type, and
|
|
95
|
+
// detail so the debugger renders it inline with local events.
|
|
96
|
+
const {id: _id, ...input} = data.event;
|
|
97
|
+
ingestingRemote = true;
|
|
98
|
+
try {
|
|
99
|
+
log.record(input);
|
|
100
|
+
} finally {
|
|
101
|
+
ingestingRemote = false;
|
|
102
|
+
}
|
|
103
|
+
};
|
|
104
|
+
|
|
105
|
+
return {
|
|
106
|
+
close: (): void => {
|
|
107
|
+
unsubscribe();
|
|
108
|
+
channel.onmessage = null;
|
|
109
|
+
channel.close();
|
|
110
|
+
},
|
|
111
|
+
};
|
|
112
|
+
};
|
|
@@ -0,0 +1,139 @@
|
|
|
1
|
+
import {describe, expect, it} from "bun:test";
|
|
2
|
+
|
|
3
|
+
import {createSyncDebugLog, resolveDebugLog} from "./debugLog";
|
|
4
|
+
|
|
5
|
+
describe("createSyncDebugLog", () => {
|
|
6
|
+
it("assigns monotonic ids and timestamps and preserves order", () => {
|
|
7
|
+
let tick = 0;
|
|
8
|
+
const log = createSyncDebugLog({clock: () => `2026-01-01T00:00:0${tick++}.000Z`});
|
|
9
|
+
|
|
10
|
+
log.record({direction: "local", label: "one", type: "mutate"});
|
|
11
|
+
log.record({direction: "inbound", label: "two", type: "delta"});
|
|
12
|
+
|
|
13
|
+
const events = log.getEvents();
|
|
14
|
+
expect(events.map((e) => e.id)).toEqual([1, 2]);
|
|
15
|
+
expect(events.map((e) => e.label)).toEqual(["one", "two"]);
|
|
16
|
+
expect(events[0].timestamp).toBe("2026-01-01T00:00:00.000Z");
|
|
17
|
+
expect(events[1].timestamp).toBe("2026-01-01T00:00:01.000Z");
|
|
18
|
+
});
|
|
19
|
+
|
|
20
|
+
it("evicts oldest events beyond capacity (circular buffer)", () => {
|
|
21
|
+
const log = createSyncDebugLog({capacity: 3});
|
|
22
|
+
for (let i = 1; i <= 5; i++) {
|
|
23
|
+
log.record({direction: "local", label: `e${i}`, type: "mutate"});
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
const events = log.getEvents();
|
|
27
|
+
expect(events).toHaveLength(3);
|
|
28
|
+
expect(events.map((e) => e.label)).toEqual(["e3", "e4", "e5"]);
|
|
29
|
+
expect(events.map((e) => e.id)).toEqual([3, 4, 5]);
|
|
30
|
+
|
|
31
|
+
const stats = log.getStats();
|
|
32
|
+
expect(stats.total).toBe(5);
|
|
33
|
+
expect(stats.retained).toBe(3);
|
|
34
|
+
expect(stats.dropped).toBe(2);
|
|
35
|
+
expect(stats.byType.mutate).toBe(5);
|
|
36
|
+
});
|
|
37
|
+
|
|
38
|
+
it("notifies subscribers with each new event and supports unsubscribe", () => {
|
|
39
|
+
const log = createSyncDebugLog();
|
|
40
|
+
const received: string[] = [];
|
|
41
|
+
const unsubscribe = log.subscribe((event) => received.push(event.label));
|
|
42
|
+
|
|
43
|
+
log.record({direction: "local", label: "a", type: "mutate"});
|
|
44
|
+
unsubscribe();
|
|
45
|
+
log.record({direction: "local", label: "b", type: "mutate"});
|
|
46
|
+
|
|
47
|
+
expect(received).toEqual(["a"]);
|
|
48
|
+
});
|
|
49
|
+
|
|
50
|
+
it("bumps revision on record and clear", () => {
|
|
51
|
+
const log = createSyncDebugLog();
|
|
52
|
+
expect(log.getRevision()).toBe(0);
|
|
53
|
+
log.record({direction: "local", label: "a", type: "mutate"});
|
|
54
|
+
expect(log.getRevision()).toBe(1);
|
|
55
|
+
log.clear();
|
|
56
|
+
expect(log.getRevision()).toBe(2);
|
|
57
|
+
expect(log.getEvents()).toHaveLength(0);
|
|
58
|
+
// E6: clear() resets every derived stat coherently — total (and
|
|
59
|
+
// everything else getStats() reports) describes only what happened
|
|
60
|
+
// since the last clear, not a lifetime count that would otherwise be
|
|
61
|
+
// inconsistent with retained: 0.
|
|
62
|
+
expect(log.getStats().total).toBe(0);
|
|
63
|
+
});
|
|
64
|
+
|
|
65
|
+
it("clear() resets total/dropped/byType/firstEventAt/lastEventAt, not just retained (E6)", () => {
|
|
66
|
+
const log = createSyncDebugLog({capacity: 2});
|
|
67
|
+
log.record({direction: "local", label: "a", type: "mutate"});
|
|
68
|
+
log.record({direction: "inbound", label: "b", type: "delta"});
|
|
69
|
+
// Overflow past capacity to also populate `dropped`.
|
|
70
|
+
log.record({direction: "inbound", label: "c", type: "ack"});
|
|
71
|
+
|
|
72
|
+
const beforeClear = log.getStats();
|
|
73
|
+
expect(beforeClear.total).toBe(3);
|
|
74
|
+
expect(beforeClear.dropped).toBe(1);
|
|
75
|
+
expect(beforeClear.byType.mutate).toBe(1);
|
|
76
|
+
expect(beforeClear.firstEventAt).toBeDefined();
|
|
77
|
+
expect(beforeClear.lastEventAt).toBeDefined();
|
|
78
|
+
|
|
79
|
+
log.clear();
|
|
80
|
+
const afterClear = log.getStats();
|
|
81
|
+
expect(afterClear).toEqual({
|
|
82
|
+
byType: {
|
|
83
|
+
ack: 0,
|
|
84
|
+
conflict: 0,
|
|
85
|
+
connect: 0,
|
|
86
|
+
delta: 0,
|
|
87
|
+
disconnect: 0,
|
|
88
|
+
failed: 0,
|
|
89
|
+
mutate: 0,
|
|
90
|
+
nack: 0,
|
|
91
|
+
reconcile: 0,
|
|
92
|
+
replay: 0,
|
|
93
|
+
resolve: 0,
|
|
94
|
+
retry: 0,
|
|
95
|
+
send: 0,
|
|
96
|
+
},
|
|
97
|
+
dropped: 0,
|
|
98
|
+
firstEventAt: undefined,
|
|
99
|
+
lastEventAt: undefined,
|
|
100
|
+
retained: 0,
|
|
101
|
+
total: 0,
|
|
102
|
+
});
|
|
103
|
+
|
|
104
|
+
// A fresh record after clear reports as if the log were brand new, and
|
|
105
|
+
// ids stay monotonic (not reset) across the clear.
|
|
106
|
+
const next = log.record({direction: "local", label: "d", type: "mutate"});
|
|
107
|
+
expect(next.id).toBe(4);
|
|
108
|
+
expect(log.getStats()).toMatchObject({
|
|
109
|
+
byType: {mutate: 1},
|
|
110
|
+
dropped: 0,
|
|
111
|
+
retained: 1,
|
|
112
|
+
total: 1,
|
|
113
|
+
});
|
|
114
|
+
});
|
|
115
|
+
|
|
116
|
+
it("snapshot returns a serializable events + stats view", () => {
|
|
117
|
+
const log = createSyncDebugLog({capacity: 10});
|
|
118
|
+
log.record({collection: "todos", direction: "local", label: "create", type: "mutate"});
|
|
119
|
+
|
|
120
|
+
const snapshot = log.snapshot();
|
|
121
|
+
expect(snapshot.capacity).toBe(10);
|
|
122
|
+
expect(snapshot.events).toHaveLength(1);
|
|
123
|
+
expect(snapshot.stats.total).toBe(1);
|
|
124
|
+
// Must round-trip through JSON unchanged (MCP-facing contract).
|
|
125
|
+
expect(JSON.parse(JSON.stringify(snapshot))).toEqual(snapshot);
|
|
126
|
+
});
|
|
127
|
+
});
|
|
128
|
+
|
|
129
|
+
describe("resolveDebugLog", () => {
|
|
130
|
+
it("returns undefined when disabled", () => {
|
|
131
|
+
expect(resolveDebugLog(undefined)).toBeUndefined();
|
|
132
|
+
expect(resolveDebugLog(false)).toBeUndefined();
|
|
133
|
+
});
|
|
134
|
+
|
|
135
|
+
it("creates a log for true or options", () => {
|
|
136
|
+
expect(resolveDebugLog(true)?.capacity).toBe(500);
|
|
137
|
+
expect(resolveDebugLog({capacity: 25})?.capacity).toBe(25);
|
|
138
|
+
});
|
|
139
|
+
});
|
|
@@ -0,0 +1,272 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* SyncDebugLog — an opt-in, in-memory event recorder for @terreno/syncdb.
|
|
3
|
+
*
|
|
4
|
+
* It captures the semantic sync events the client produces (local mutations,
|
|
5
|
+
* inbound server deltas/patches, outbox send/ack/nack/retry/failure, conflicts,
|
|
6
|
+
* reconcile/replay phases, connectivity) into a fixed-capacity circular buffer.
|
|
7
|
+
* This is the data source behind the "sync debugger" UI (a Redux-DevTools-style
|
|
8
|
+
* live stream) and is deliberately shaped as a plain, JSON-serializable snapshot
|
|
9
|
+
* so the same surface can be exposed over MCP in the future without change:
|
|
10
|
+
*
|
|
11
|
+
* const snapshot = client.debug?.snapshot(); // -> return straight from an MCP tool
|
|
12
|
+
*
|
|
13
|
+
* Design notes:
|
|
14
|
+
* - Zero overhead when disabled: the client never constructs event objects unless
|
|
15
|
+
* a log exists (call sites guard with `emit?.(...)`, which short-circuits arg
|
|
16
|
+
* evaluation).
|
|
17
|
+
* - Circular buffer (no array shifts) so recording stays O(1) under bursts.
|
|
18
|
+
* - `subscribe` delivers each new event individually so consumers can append
|
|
19
|
+
* without re-reading the whole buffer; `getRevision` powers `useSyncExternalStore`.
|
|
20
|
+
*/
|
|
21
|
+
|
|
22
|
+
import {DateTime} from "luxon";
|
|
23
|
+
|
|
24
|
+
import type {SyncMutationOperation} from "../types";
|
|
25
|
+
|
|
26
|
+
/** Coarse category for an event, mirroring the sync protocol vocabulary. */
|
|
27
|
+
export type SyncDebugEventType =
|
|
28
|
+
| "mutate"
|
|
29
|
+
| "delta"
|
|
30
|
+
| "send"
|
|
31
|
+
| "ack"
|
|
32
|
+
| "nack"
|
|
33
|
+
| "retry"
|
|
34
|
+
| "failed"
|
|
35
|
+
| "conflict"
|
|
36
|
+
| "resolve"
|
|
37
|
+
| "reconcile"
|
|
38
|
+
| "replay"
|
|
39
|
+
| "connect"
|
|
40
|
+
| "disconnect";
|
|
41
|
+
|
|
42
|
+
/** Which way the event flows relative to the device. */
|
|
43
|
+
export type SyncDebugDirection = "local" | "inbound" | "outbound" | "system";
|
|
44
|
+
|
|
45
|
+
/** A single recorded sync event. All fields are JSON-serializable. */
|
|
46
|
+
export interface SyncDebugEvent {
|
|
47
|
+
/** Monotonic local id (assigned by the log; stable ordering key). */
|
|
48
|
+
id: number;
|
|
49
|
+
/** ISO-8601 capture time. */
|
|
50
|
+
timestamp: string;
|
|
51
|
+
type: SyncDebugEventType;
|
|
52
|
+
direction: SyncDebugDirection;
|
|
53
|
+
/** Short human-readable summary, e.g. "update todos/abc @4". */
|
|
54
|
+
label: string;
|
|
55
|
+
collection?: string;
|
|
56
|
+
entityId?: string;
|
|
57
|
+
stream?: string;
|
|
58
|
+
mutationId?: string;
|
|
59
|
+
operation?: SyncMutationOperation;
|
|
60
|
+
/** Server seq (deltas, acks) where applicable. */
|
|
61
|
+
seq?: number;
|
|
62
|
+
/** For long-running events (reconcile/replay) split into start/end. */
|
|
63
|
+
phase?: "start" | "end";
|
|
64
|
+
/** Outcome flag: true for ack, false for nack/failed. */
|
|
65
|
+
ok?: boolean;
|
|
66
|
+
/** Wall-clock duration for a phase:"end" event. */
|
|
67
|
+
durationMs?: number;
|
|
68
|
+
/** Extra serializable context (delta data, mutation args, nack code, counts). */
|
|
69
|
+
detail?: Record<string, unknown>;
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
/** Input to `record`; the log fills in `id` and `timestamp`. */
|
|
73
|
+
export type SyncDebugRecordInput = Omit<SyncDebugEvent, "id" | "timestamp"> & {
|
|
74
|
+
timestamp?: string;
|
|
75
|
+
};
|
|
76
|
+
|
|
77
|
+
export interface SyncDebugStats {
|
|
78
|
+
/** Events recorded since creation/last clear (including evicted ones). */
|
|
79
|
+
total: number;
|
|
80
|
+
/** Live count of events currently retained in the buffer. */
|
|
81
|
+
retained: number;
|
|
82
|
+
/** Events dropped from the tail because the buffer was full. */
|
|
83
|
+
dropped: number;
|
|
84
|
+
byType: Record<SyncDebugEventType, number>;
|
|
85
|
+
firstEventAt?: string;
|
|
86
|
+
lastEventAt?: string;
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
/** A plain, serializable point-in-time view — the MCP-facing shape. */
|
|
90
|
+
export interface SyncDebugSnapshot {
|
|
91
|
+
capacity: number;
|
|
92
|
+
events: SyncDebugEvent[];
|
|
93
|
+
stats: SyncDebugStats;
|
|
94
|
+
}
|
|
95
|
+
|
|
96
|
+
export interface SyncDebugLog {
|
|
97
|
+
/** Max events retained before the oldest are evicted. */
|
|
98
|
+
readonly capacity: number;
|
|
99
|
+
/** Record an event; returns the stored event (with id + timestamp). */
|
|
100
|
+
record: (input: SyncDebugRecordInput) => SyncDebugEvent;
|
|
101
|
+
/** Events in chronological (oldest → newest) order. */
|
|
102
|
+
getEvents: () => SyncDebugEvent[];
|
|
103
|
+
/** Subscribe to each newly recorded event. Returns an unsubscribe fn. */
|
|
104
|
+
subscribe: (listener: (event: SyncDebugEvent) => void) => () => void;
|
|
105
|
+
/** Monotonic revision, bumped on every record and clear (for external stores). */
|
|
106
|
+
getRevision: () => number;
|
|
107
|
+
/** Aggregate counters. */
|
|
108
|
+
getStats: () => SyncDebugStats;
|
|
109
|
+
/** Serializable snapshot (events + stats) — safe to return over MCP. */
|
|
110
|
+
snapshot: () => SyncDebugSnapshot;
|
|
111
|
+
/**
|
|
112
|
+
* Drop all retained events AND reset every derived stat (`total`,
|
|
113
|
+
* `dropped`, `byType`, `firstEventAt`, `lastEventAt`) to match the
|
|
114
|
+
* now-empty buffer — `getStats()` immediately after `clear()` always
|
|
115
|
+
* describes exactly what the log currently holds (nothing), never a
|
|
116
|
+
* lifetime total left over from before the clear. The event id sequence
|
|
117
|
+
* (`nextId`) is the only thing that survives a clear, so ids stay
|
|
118
|
+
* monotonic across it.
|
|
119
|
+
*/
|
|
120
|
+
clear: () => void;
|
|
121
|
+
}
|
|
122
|
+
|
|
123
|
+
export interface SyncDebugLogOptions {
|
|
124
|
+
/** Max retained events (default 500). */
|
|
125
|
+
capacity?: number;
|
|
126
|
+
/** ISO clock, injectable for deterministic tests. */
|
|
127
|
+
clock?: () => string;
|
|
128
|
+
}
|
|
129
|
+
|
|
130
|
+
const DEFAULT_CAPACITY = 500;
|
|
131
|
+
|
|
132
|
+
const emptyByType = (): Record<SyncDebugEventType, number> => ({
|
|
133
|
+
ack: 0,
|
|
134
|
+
conflict: 0,
|
|
135
|
+
connect: 0,
|
|
136
|
+
delta: 0,
|
|
137
|
+
disconnect: 0,
|
|
138
|
+
failed: 0,
|
|
139
|
+
mutate: 0,
|
|
140
|
+
nack: 0,
|
|
141
|
+
reconcile: 0,
|
|
142
|
+
replay: 0,
|
|
143
|
+
resolve: 0,
|
|
144
|
+
retry: 0,
|
|
145
|
+
send: 0,
|
|
146
|
+
});
|
|
147
|
+
|
|
148
|
+
/**
|
|
149
|
+
* Create an in-memory debug log backed by a circular buffer.
|
|
150
|
+
*/
|
|
151
|
+
export const createSyncDebugLog = (options: SyncDebugLogOptions = {}): SyncDebugLog => {
|
|
152
|
+
const capacity = Math.max(1, options.capacity ?? DEFAULT_CAPACITY);
|
|
153
|
+
const clock = options.clock ?? ((): string => DateTime.now().toISO() ?? new Date().toISOString());
|
|
154
|
+
|
|
155
|
+
const buffer: (SyncDebugEvent | undefined)[] = new Array(capacity);
|
|
156
|
+
let writeIndex = 0;
|
|
157
|
+
let retained = 0;
|
|
158
|
+
let nextId = 1;
|
|
159
|
+
let total = 0;
|
|
160
|
+
let dropped = 0;
|
|
161
|
+
let revision = 0;
|
|
162
|
+
const byType = emptyByType();
|
|
163
|
+
let firstEventAt: string | undefined;
|
|
164
|
+
let lastEventAt: string | undefined;
|
|
165
|
+
const listeners = new Set<(event: SyncDebugEvent) => void>();
|
|
166
|
+
|
|
167
|
+
const record = (input: SyncDebugRecordInput): SyncDebugEvent => {
|
|
168
|
+
const event: SyncDebugEvent = {
|
|
169
|
+
...input,
|
|
170
|
+
id: nextId++,
|
|
171
|
+
timestamp: input.timestamp ?? clock(),
|
|
172
|
+
};
|
|
173
|
+
|
|
174
|
+
// Evict the slot we are about to overwrite once the buffer is saturated.
|
|
175
|
+
if (retained === capacity) {
|
|
176
|
+
dropped++;
|
|
177
|
+
} else {
|
|
178
|
+
retained++;
|
|
179
|
+
}
|
|
180
|
+
buffer[writeIndex] = event;
|
|
181
|
+
writeIndex = (writeIndex + 1) % capacity;
|
|
182
|
+
|
|
183
|
+
total++;
|
|
184
|
+
byType[event.type]++;
|
|
185
|
+
if (!firstEventAt) {
|
|
186
|
+
firstEventAt = event.timestamp;
|
|
187
|
+
}
|
|
188
|
+
lastEventAt = event.timestamp;
|
|
189
|
+
revision++;
|
|
190
|
+
|
|
191
|
+
for (const listener of listeners) {
|
|
192
|
+
listener(event);
|
|
193
|
+
}
|
|
194
|
+
return event;
|
|
195
|
+
};
|
|
196
|
+
|
|
197
|
+
const getEvents = (): SyncDebugEvent[] => {
|
|
198
|
+
const events: SyncDebugEvent[] = [];
|
|
199
|
+
const start = (writeIndex - retained + capacity) % capacity;
|
|
200
|
+
for (let i = 0; i < retained; i++) {
|
|
201
|
+
const event = buffer[(start + i) % capacity];
|
|
202
|
+
if (event) {
|
|
203
|
+
events.push(event);
|
|
204
|
+
}
|
|
205
|
+
}
|
|
206
|
+
return events;
|
|
207
|
+
};
|
|
208
|
+
|
|
209
|
+
const getStats = (): SyncDebugStats => ({
|
|
210
|
+
byType: {...byType},
|
|
211
|
+
dropped,
|
|
212
|
+
firstEventAt,
|
|
213
|
+
lastEventAt,
|
|
214
|
+
retained,
|
|
215
|
+
total,
|
|
216
|
+
});
|
|
217
|
+
|
|
218
|
+
const snapshot = (): SyncDebugSnapshot => ({
|
|
219
|
+
capacity,
|
|
220
|
+
events: getEvents(),
|
|
221
|
+
stats: getStats(),
|
|
222
|
+
});
|
|
223
|
+
|
|
224
|
+
const subscribe = (listener: (event: SyncDebugEvent) => void): (() => void) => {
|
|
225
|
+
listeners.add(listener);
|
|
226
|
+
return () => {
|
|
227
|
+
listeners.delete(listener);
|
|
228
|
+
};
|
|
229
|
+
};
|
|
230
|
+
|
|
231
|
+
const clear = (): void => {
|
|
232
|
+
buffer.fill(undefined);
|
|
233
|
+
writeIndex = 0;
|
|
234
|
+
retained = 0;
|
|
235
|
+
// E6: reset every derived stat to match the now-empty buffer, not just
|
|
236
|
+
// `retained` — leaving `total`/`dropped`/`byType`/`firstEventAt`/
|
|
237
|
+
// `lastEventAt` at their pre-clear values produced an incoherent
|
|
238
|
+
// snapshot (e.g. `retained: 0` alongside `byType.mutate: 5` and a
|
|
239
|
+
// `total` that no longer describes anything the log still holds).
|
|
240
|
+
// `nextId` is NOT reset: ids stay monotonic across a clear so a listener
|
|
241
|
+
// that cached an event by id never collides with a later one.
|
|
242
|
+
total = 0;
|
|
243
|
+
dropped = 0;
|
|
244
|
+
for (const type of Object.keys(byType) as SyncDebugEventType[]) {
|
|
245
|
+
byType[type] = 0;
|
|
246
|
+
}
|
|
247
|
+
firstEventAt = undefined;
|
|
248
|
+
lastEventAt = undefined;
|
|
249
|
+
revision++;
|
|
250
|
+
};
|
|
251
|
+
|
|
252
|
+
return {
|
|
253
|
+
capacity,
|
|
254
|
+
clear,
|
|
255
|
+
getEvents,
|
|
256
|
+
getRevision: () => revision,
|
|
257
|
+
getStats,
|
|
258
|
+
record,
|
|
259
|
+
snapshot,
|
|
260
|
+
subscribe,
|
|
261
|
+
};
|
|
262
|
+
};
|
|
263
|
+
|
|
264
|
+
/** Resolve a `debug` config value (boolean | options) into a log or undefined. */
|
|
265
|
+
export const resolveDebugLog = (
|
|
266
|
+
debug: boolean | SyncDebugLogOptions | undefined
|
|
267
|
+
): SyncDebugLog | undefined => {
|
|
268
|
+
if (!debug) {
|
|
269
|
+
return undefined;
|
|
270
|
+
}
|
|
271
|
+
return createSyncDebugLog(debug === true ? {} : debug);
|
|
272
|
+
};
|