@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
package/dist/client.d.ts
ADDED
|
@@ -0,0 +1,246 @@
|
|
|
1
|
+
import type { KeyProvider } from "./crypto/types";
|
|
2
|
+
import { type SyncDebugLog, type SyncDebugLogOptions } from "./debug/debugLog";
|
|
3
|
+
import { type Outbox } from "./mutations/outbox";
|
|
4
|
+
import type { DefaultPersisterFactoryConfig, PersisterFactory } from "./persisters/types";
|
|
5
|
+
import { type SyncStore } from "./storage/store";
|
|
6
|
+
import { type HttpChannel } from "./sync/httpChannel";
|
|
7
|
+
import type { SyncTransport } from "./sync/transport";
|
|
8
|
+
import type { AuthProvider, ConflictResolutionStrategy, SyncMutationOperation, SyncStatus } from "./types";
|
|
9
|
+
/** Periodic reconcile interval when not configured (5 minutes). */
|
|
10
|
+
export declare const DEFAULT_RECONCILE_INTERVAL_MS: number;
|
|
11
|
+
/** Minimum interval between seq-jump-triggered reconciles per stream (30s). */
|
|
12
|
+
export declare const DEFAULT_SEQ_JUMP_RECONCILE_MIN_INTERVAL_MS = 30000;
|
|
13
|
+
/** E5: default local tombstone retention window (90 days), matching the server's (C7). */
|
|
14
|
+
export declare const DEFAULT_TOMBSTONE_RETENTION_MS: number;
|
|
15
|
+
/**
|
|
16
|
+
* `start()` auth-resolution retry defaults. A host app only calls `start()` once it
|
|
17
|
+
* already believes the user is authenticated (e.g. right after its own login flow
|
|
18
|
+
* resolved), so a `null` from `authProvider.getUserId()` on the first attempt is far
|
|
19
|
+
* more likely a transient hiccup — the session cookie/token not yet queryable, or a
|
|
20
|
+
* one-off fetch failure racing a just-completed navigation — than a genuine
|
|
21
|
+
* logged-out state. Retrying briefly avoids `start()` giving up permanently on a call
|
|
22
|
+
* site that (by design, see the client.ts start() doc) never retries itself.
|
|
23
|
+
*/
|
|
24
|
+
export declare const DEFAULT_START_AUTH_RETRY_ATTEMPTS = 3;
|
|
25
|
+
export declare const DEFAULT_START_AUTH_RETRY_DELAY_MS = 250;
|
|
26
|
+
export interface SyncDbConfig {
|
|
27
|
+
/** App/store name; used as the persisted database name. */
|
|
28
|
+
name: string;
|
|
29
|
+
/** Collections to sync (become local entity tables and subscriptions). */
|
|
30
|
+
collections: string[];
|
|
31
|
+
authProvider: AuthProvider;
|
|
32
|
+
/** Server origin; required unless both transport and httpChannel are injected. */
|
|
33
|
+
baseUrl?: string;
|
|
34
|
+
/** Transport override (tests inject a fake; default is the socket transport). */
|
|
35
|
+
transport?: SyncTransport;
|
|
36
|
+
/** HTTP channel override (default is built from baseUrl when present). */
|
|
37
|
+
httpChannel?: HttpChannel;
|
|
38
|
+
/** Persister factory override (default is the platform default factory). */
|
|
39
|
+
persisterFactory?: PersisterFactory;
|
|
40
|
+
/** Encryption key provider forwarded to the default persister factory (web). */
|
|
41
|
+
keyProvider?: KeyProvider;
|
|
42
|
+
/**
|
|
43
|
+
* Test-only IndexedDB read/write overrides forwarded to the default web
|
|
44
|
+
* persister factory (e.g. to simulate a read error or a quota-exceeded
|
|
45
|
+
* write in tests without a real broken IndexedDB). Ignored on native and
|
|
46
|
+
* ignored entirely when `persisterFactory` is overridden.
|
|
47
|
+
*/
|
|
48
|
+
idbGetImpl?: DefaultPersisterFactoryConfig["idbGetImpl"];
|
|
49
|
+
idbSetImpl?: DefaultPersisterFactoryConfig["idbSetImpl"];
|
|
50
|
+
/** Periodic reconcile interval in ms; 0 disables (default 5 minutes). */
|
|
51
|
+
reconcileIntervalMs?: number;
|
|
52
|
+
/** Rate limit for seq-jump-triggered reconciles per stream (default 30s). */
|
|
53
|
+
seqJumpReconcileMinIntervalMs?: number;
|
|
54
|
+
/** Millisecond clock, injectable for deterministic rate-limit tests. */
|
|
55
|
+
now?: () => number;
|
|
56
|
+
/** Random source in [0, 1), injectable for deterministic backoff-jitter tests. */
|
|
57
|
+
random?: () => number;
|
|
58
|
+
/**
|
|
59
|
+
* Enable the in-memory debug event log (patches, mutations, acks/nacks,
|
|
60
|
+
* conflicts, reconcile/replay, connectivity). `true` uses defaults; pass
|
|
61
|
+
* options to size the buffer. Off by default — zero overhead when disabled.
|
|
62
|
+
* Powers the sync debugger UI and the future MCP introspection surface.
|
|
63
|
+
*/
|
|
64
|
+
debug?: boolean | SyncDebugLogOptions;
|
|
65
|
+
/**
|
|
66
|
+
* Fired at most once per auth-pause episode when the client enters
|
|
67
|
+
* `paused: "auth"` (INV-2), so the host app can show a re-login prompt.
|
|
68
|
+
* Clears and can fire again after a subsequent pause episode.
|
|
69
|
+
*/
|
|
70
|
+
onAuthRequired?: () => void;
|
|
71
|
+
/**
|
|
72
|
+
* When true, `client.signOut()` wipes local data for the current user (in
|
|
73
|
+
* addition to clearing auth state). Local data is otherwise NEVER wiped on
|
|
74
|
+
* logout or 401 (INV-2) — only on a confirmed different-user login, or via
|
|
75
|
+
* this explicit, host-app-initiated opt-in.
|
|
76
|
+
*/
|
|
77
|
+
wipeOnSignOut?: boolean;
|
|
78
|
+
/** Max mutations per batched drain send (B3, default 50; server caps at 100). */
|
|
79
|
+
batchSize?: number;
|
|
80
|
+
/**
|
|
81
|
+
* B4: when true, a conflict halts the ENTIRE drain instead of just blocking
|
|
82
|
+
* its entity. Default false (per-entity blocking — see README "Conflict
|
|
83
|
+
* handling modes").
|
|
84
|
+
*/
|
|
85
|
+
haltQueueOnConflict?: boolean;
|
|
86
|
+
/**
|
|
87
|
+
* E3(b): invoked when persisted local data cannot be decrypted (web only —
|
|
88
|
+
* corrupt data, or a rotated/lost encryption key). DEFAULT BEHAVIOR when
|
|
89
|
+
* omitted: wipe all local data for the current user, re-stamp the schema
|
|
90
|
+
* version, and run a full snapshot re-bootstrap — always preceded by a
|
|
91
|
+
* `console.warn`. Pass this to override that default (e.g. to prompt the
|
|
92
|
+
* user before wiping); when provided, the client's own wipe/re-bootstrap is
|
|
93
|
+
* skipped and the host app is fully responsible for recovery.
|
|
94
|
+
*/
|
|
95
|
+
onDecryptFailure?: () => void;
|
|
96
|
+
/**
|
|
97
|
+
* E5: client-side compaction — local tombstone rows (`deleted: true`) older
|
|
98
|
+
* than this window (from their `deletedAt` stamp) are deleted after each
|
|
99
|
+
* successful reconcile. Default 90 days, matching the server's own
|
|
100
|
+
* tombstone retention (C7); keep the two in sync — compacting locally
|
|
101
|
+
* before the server's retention window elapses risks a client permanently
|
|
102
|
+
* missing a delete it hasn't converged on yet. 0 disables compaction.
|
|
103
|
+
*/
|
|
104
|
+
tombstoneRetentionMs?: number;
|
|
105
|
+
/**
|
|
106
|
+
* Number of `authProvider.getUserId()` attempts `start()` makes before giving up
|
|
107
|
+
* with "requires an authenticated user" (default {@link DEFAULT_START_AUTH_RETRY_ATTEMPTS}).
|
|
108
|
+
* A host app calls `start()` only once it believes the user is signed in, so an
|
|
109
|
+
* initial `null` is usually a transient auth-provider hiccup (e.g. a session fetch
|
|
110
|
+
* racing a just-completed login) rather than a real logged-out state — retrying
|
|
111
|
+
* a few times avoids `start()` permanently failing on that race. Set to 1 to
|
|
112
|
+
* disable retrying.
|
|
113
|
+
*/
|
|
114
|
+
startAuthRetryAttempts?: number;
|
|
115
|
+
/** Delay between `start()` auth-resolution retries (default {@link DEFAULT_START_AUTH_RETRY_DELAY_MS}). */
|
|
116
|
+
startAuthRetryDelayMs?: number;
|
|
117
|
+
}
|
|
118
|
+
/**
|
|
119
|
+
* Why a {@link SyncDb.forceResync} call could not run (or could not finish).
|
|
120
|
+
*
|
|
121
|
+
* `"superseded"` means a `stop()`/`start()` cycle or a different-user login took over
|
|
122
|
+
* mid-flight, so the resync abandoned its work rather than writing into a store that
|
|
123
|
+
* now belongs to another lifecycle or user — distinct from `"noStreams"` (the server
|
|
124
|
+
* reported no streams for this user, and there was no local set to fall back on),
|
|
125
|
+
* which is a stable outcome that retrying will reproduce.
|
|
126
|
+
*/
|
|
127
|
+
export type ForceResyncSkipReason = "noHttpChannel" | "offline" | "authPaused" | "noStreams" | "superseded";
|
|
128
|
+
/** Outcome of a {@link SyncDb.forceResync} call. */
|
|
129
|
+
export interface ForceResyncResult {
|
|
130
|
+
/** False when the resync could not run at all; `reason` explains why. */
|
|
131
|
+
ok: boolean;
|
|
132
|
+
reason?: ForceResyncSkipReason;
|
|
133
|
+
/** Streams purged and re-bootstrapped. */
|
|
134
|
+
streams: number;
|
|
135
|
+
/** Local entity rows deleted before re-bootstrapping. */
|
|
136
|
+
purged: number;
|
|
137
|
+
/** Entities re-fetched by the point-lookup repair pass. */
|
|
138
|
+
repaired: number;
|
|
139
|
+
}
|
|
140
|
+
export interface MutateArgs {
|
|
141
|
+
collection: string;
|
|
142
|
+
operation: SyncMutationOperation;
|
|
143
|
+
/** Target entity id; required for update/delete, generated for create. */
|
|
144
|
+
id?: string;
|
|
145
|
+
/** Fields to write (create/update). */
|
|
146
|
+
data?: Record<string, unknown>;
|
|
147
|
+
}
|
|
148
|
+
export interface SyncDb {
|
|
149
|
+
/** Local-first entity store (the UI's source of truth). */
|
|
150
|
+
readonly store: SyncStore;
|
|
151
|
+
/** Durable mutation outbox. */
|
|
152
|
+
readonly outbox: Outbox;
|
|
153
|
+
/**
|
|
154
|
+
* Resolve the user, run the wipe-on-user-change check, start persistence,
|
|
155
|
+
* connect the transport, subscribe collections, and start the periodic
|
|
156
|
+
* reconcile timer. Resolves even when the transport cannot connect
|
|
157
|
+
* (local-first: the app works offline and syncs when connectivity returns).
|
|
158
|
+
*/
|
|
159
|
+
start: () => Promise<void>;
|
|
160
|
+
/** Disconnect, stop persistence, clear timers, and remove listeners. */
|
|
161
|
+
stop: () => Promise<void>;
|
|
162
|
+
/**
|
|
163
|
+
* Simulate a network outage: disconnect the transport and pause replay,
|
|
164
|
+
* reconcile, and the periodic timer. Unlike stop(), the resolved user and
|
|
165
|
+
* persistence stay alive, so mutations keep applying locally and queueing
|
|
166
|
+
* in the durable outbox. `getSyncStatus().isOnline` reports false until
|
|
167
|
+
* goOnline() (or a stop()/start() cycle) restores connectivity.
|
|
168
|
+
*/
|
|
169
|
+
goOffline: () => void;
|
|
170
|
+
/**
|
|
171
|
+
* End a simulated outage: reconnect the transport, resubscribe, and restart
|
|
172
|
+
* the periodic timer. The reconnect status event triggers a reconcile and
|
|
173
|
+
* replays the queued outbox.
|
|
174
|
+
*/
|
|
175
|
+
goOnline: () => Promise<void>;
|
|
176
|
+
/**
|
|
177
|
+
* Apply a mutation optimistically to the local store, enqueue it in the
|
|
178
|
+
* outbox, and kick off a fire-and-forget replay. Returns the generated
|
|
179
|
+
* mutation id and the entity id (generated for creates).
|
|
180
|
+
*/
|
|
181
|
+
mutate: (args: MutateArgs) => {
|
|
182
|
+
mutationId: string;
|
|
183
|
+
id: string;
|
|
184
|
+
};
|
|
185
|
+
/** Snapshot-from-cursor catch-up for every collection (no-op without HTTP). */
|
|
186
|
+
reconcile: () => Promise<void>;
|
|
187
|
+
/**
|
|
188
|
+
* Purge every known stream locally and re-bootstrap from cursor 0. Use when
|
|
189
|
+
* devices have diverged and a full server snapshot is needed without wiping
|
|
190
|
+
* the outbox or conflicts. Reports what it did (or why it could not run) so a
|
|
191
|
+
* caller can surface the outcome instead of a silent no-op.
|
|
192
|
+
*/
|
|
193
|
+
forceResync: () => Promise<ForceResyncResult>;
|
|
194
|
+
/** Drain queued mutations for the current user now. */
|
|
195
|
+
replayOutbox: () => Promise<void>;
|
|
196
|
+
/** Resolve a recorded conflict with the given strategy. */
|
|
197
|
+
resolveConflict: (args: {
|
|
198
|
+
mutationId: string;
|
|
199
|
+
strategy: ConflictResolutionStrategy;
|
|
200
|
+
}) => void;
|
|
201
|
+
/**
|
|
202
|
+
* B4: re-enable an entity's queued successors after a terminal validation
|
|
203
|
+
* failure blocked them. Does not touch unresolved conflicts (those clear
|
|
204
|
+
* via `resolveConflict`); kicks off a replay so the re-enabled mutations
|
|
205
|
+
* drain immediately rather than waiting for the next trigger.
|
|
206
|
+
*/
|
|
207
|
+
retryFailed: (args: {
|
|
208
|
+
entityId: string;
|
|
209
|
+
}) => void;
|
|
210
|
+
/**
|
|
211
|
+
* Explicit, host-app-initiated sign-out. Tears the client down like `stop()`
|
|
212
|
+
* (transport disconnected, listeners and timers cleared, persister flushed and
|
|
213
|
+
* destroyed) and clears the in-memory current-user pointer; wipes local data
|
|
214
|
+
* ONLY when `wipeOnSignOut` is configured (INV-2 — a bare 401/logout event
|
|
215
|
+
* never triggers this on its own). Safe to call whether or not the client is
|
|
216
|
+
* currently paused, and safe to race against `start()`/`stop()`/an auth
|
|
217
|
+
* change. Call `start()` again to sync as the next signed-in user.
|
|
218
|
+
*/
|
|
219
|
+
signOut: () => Promise<void>;
|
|
220
|
+
/** Aggregate sync state for status UI. */
|
|
221
|
+
getSyncStatus: () => SyncStatus;
|
|
222
|
+
/**
|
|
223
|
+
* Subscribe to non-store status inputs (connectivity, syncing activity).
|
|
224
|
+
* `getSyncStatus()` is a snapshot; store-backed inputs (outbox, conflicts,
|
|
225
|
+
* cursors) already emit through TinyBase listeners on `store.raw`, but
|
|
226
|
+
* `isOnline`/`isSyncing` live outside the store — this hook covers them.
|
|
227
|
+
* Returns an unsubscribe function.
|
|
228
|
+
*/
|
|
229
|
+
onStatusChange: (callback: () => void) => () => void;
|
|
230
|
+
/**
|
|
231
|
+
* In-memory debug event log when `config.debug` is enabled; otherwise
|
|
232
|
+
* undefined. Its `snapshot()` is a plain serializable object suitable for
|
|
233
|
+
* returning directly over MCP.
|
|
234
|
+
*/
|
|
235
|
+
readonly debug?: SyncDebugLog;
|
|
236
|
+
}
|
|
237
|
+
/**
|
|
238
|
+
* Assemble the full local-first client: store + outbox + persister + transport
|
|
239
|
+
* + HTTP channel + replay coordinator + reconcile heuristics.
|
|
240
|
+
*
|
|
241
|
+
* Reconcile triggers: transport (re)connect, rate-limited seq-jump hints from
|
|
242
|
+
* deltas, and a periodic timer. Replay triggers: (re)connect, auth changes,
|
|
243
|
+
* and every `mutate()`.
|
|
244
|
+
*/
|
|
245
|
+
export declare const createSyncDb: (config: SyncDbConfig) => SyncDb;
|
|
246
|
+
//# sourceMappingURL=client.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}
|