@livestore/livestore 0.4.0-dev.9 → 0.4.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.
Files changed (129) hide show
  1. package/README.md +0 -1
  2. package/dist/.tsbuildinfo +1 -1
  3. package/dist/QueryCache.js +1 -1
  4. package/dist/QueryCache.js.map +1 -1
  5. package/dist/SqliteDbWrapper.d.ts +5 -5
  6. package/dist/SqliteDbWrapper.d.ts.map +1 -1
  7. package/dist/SqliteDbWrapper.js +8 -8
  8. package/dist/SqliteDbWrapper.js.map +1 -1
  9. package/dist/SqliteDbWrapper.test.js +4 -3
  10. package/dist/SqliteDbWrapper.test.js.map +1 -1
  11. package/dist/effect/LiveStore.d.ts +133 -5
  12. package/dist/effect/LiveStore.d.ts.map +1 -1
  13. package/dist/effect/LiveStore.js +187 -8
  14. package/dist/effect/LiveStore.js.map +1 -1
  15. package/dist/effect/LiveStore.test.d.ts +2 -0
  16. package/dist/effect/LiveStore.test.d.ts.map +1 -0
  17. package/dist/effect/LiveStore.test.js +42 -0
  18. package/dist/effect/LiveStore.test.js.map +1 -0
  19. package/dist/effect/mod.d.ts +1 -1
  20. package/dist/effect/mod.d.ts.map +1 -1
  21. package/dist/effect/mod.js +3 -1
  22. package/dist/effect/mod.js.map +1 -1
  23. package/dist/live-queries/base-class.d.ts +110 -7
  24. package/dist/live-queries/base-class.d.ts.map +1 -1
  25. package/dist/live-queries/base-class.js +2 -2
  26. package/dist/live-queries/base-class.js.map +1 -1
  27. package/dist/live-queries/client-document-get-query.d.ts +1 -1
  28. package/dist/live-queries/client-document-get-query.d.ts.map +1 -1
  29. package/dist/live-queries/client-document-get-query.js +4 -3
  30. package/dist/live-queries/client-document-get-query.js.map +1 -1
  31. package/dist/live-queries/computed.d.ts +56 -0
  32. package/dist/live-queries/computed.d.ts.map +1 -1
  33. package/dist/live-queries/computed.js +58 -2
  34. package/dist/live-queries/computed.js.map +1 -1
  35. package/dist/live-queries/db-query.d.ts.map +1 -1
  36. package/dist/live-queries/db-query.js +21 -19
  37. package/dist/live-queries/db-query.js.map +1 -1
  38. package/dist/live-queries/db-query.test.js +106 -23
  39. package/dist/live-queries/db-query.test.js.map +1 -1
  40. package/dist/live-queries/signal.d.ts +49 -0
  41. package/dist/live-queries/signal.d.ts.map +1 -1
  42. package/dist/live-queries/signal.js +49 -0
  43. package/dist/live-queries/signal.js.map +1 -1
  44. package/dist/live-queries/signal.test.js +2 -2
  45. package/dist/live-queries/signal.test.js.map +1 -1
  46. package/dist/mod.d.ts +3 -3
  47. package/dist/mod.d.ts.map +1 -1
  48. package/dist/mod.js +3 -2
  49. package/dist/mod.js.map +1 -1
  50. package/dist/reactive.d.ts +9 -9
  51. package/dist/reactive.d.ts.map +1 -1
  52. package/dist/reactive.js +9 -26
  53. package/dist/reactive.js.map +1 -1
  54. package/dist/reactive.test.js +2 -2
  55. package/dist/reactive.test.js.map +1 -1
  56. package/dist/store/StoreRegistry.d.ts +215 -0
  57. package/dist/store/StoreRegistry.d.ts.map +1 -0
  58. package/dist/store/StoreRegistry.js +267 -0
  59. package/dist/store/StoreRegistry.js.map +1 -0
  60. package/dist/store/StoreRegistry.test.d.ts +2 -0
  61. package/dist/store/StoreRegistry.test.d.ts.map +1 -0
  62. package/dist/store/StoreRegistry.test.js +381 -0
  63. package/dist/store/StoreRegistry.test.js.map +1 -0
  64. package/dist/store/create-store.d.ts +98 -18
  65. package/dist/store/create-store.d.ts.map +1 -1
  66. package/dist/store/create-store.js +49 -20
  67. package/dist/store/create-store.js.map +1 -1
  68. package/dist/store/devtools.d.ts +5 -16
  69. package/dist/store/devtools.d.ts.map +1 -1
  70. package/dist/store/devtools.js +59 -18
  71. package/dist/store/devtools.js.map +1 -1
  72. package/dist/store/store-eventstream.test.d.ts +2 -0
  73. package/dist/store/store-eventstream.test.d.ts.map +1 -0
  74. package/dist/store/store-eventstream.test.js +65 -0
  75. package/dist/store/store-eventstream.test.js.map +1 -0
  76. package/dist/store/store-types.d.ts +285 -27
  77. package/dist/store/store-types.d.ts.map +1 -1
  78. package/dist/store/store-types.js +77 -1
  79. package/dist/store/store-types.js.map +1 -1
  80. package/dist/store/store-types.test.d.ts +2 -0
  81. package/dist/store/store-types.test.d.ts.map +1 -0
  82. package/dist/store/store-types.test.js +39 -0
  83. package/dist/store/store-types.test.js.map +1 -0
  84. package/dist/store/store.d.ts +253 -66
  85. package/dist/store/store.d.ts.map +1 -1
  86. package/dist/store/store.js +442 -153
  87. package/dist/store/store.js.map +1 -1
  88. package/dist/utils/dev.d.ts.map +1 -1
  89. package/dist/utils/dev.js.map +1 -1
  90. package/dist/utils/stack-info.js +2 -2
  91. package/dist/utils/stack-info.js.map +1 -1
  92. package/dist/utils/tests/fixture.d.ts +20 -5
  93. package/dist/utils/tests/fixture.d.ts.map +1 -1
  94. package/dist/utils/tests/fixture.js +7 -0
  95. package/dist/utils/tests/fixture.js.map +1 -1
  96. package/dist/utils/tests/otel.d.ts.map +1 -1
  97. package/dist/utils/tests/otel.js +5 -5
  98. package/dist/utils/tests/otel.js.map +1 -1
  99. package/package.json +59 -17
  100. package/src/QueryCache.ts +1 -1
  101. package/src/SqliteDbWrapper.test.ts +5 -3
  102. package/src/SqliteDbWrapper.ts +12 -11
  103. package/src/ambient.d.ts +0 -7
  104. package/src/effect/LiveStore.test.ts +61 -0
  105. package/src/effect/LiveStore.ts +388 -13
  106. package/src/effect/mod.ts +13 -1
  107. package/src/live-queries/__snapshots__/db-query.test.ts.snap +604 -192
  108. package/src/live-queries/base-class.ts +126 -28
  109. package/src/live-queries/client-document-get-query.ts +6 -4
  110. package/src/live-queries/computed.ts +59 -2
  111. package/src/live-queries/db-query.test.ts +162 -24
  112. package/src/live-queries/db-query.ts +23 -20
  113. package/src/live-queries/signal.test.ts +3 -2
  114. package/src/live-queries/signal.ts +49 -0
  115. package/src/mod.ts +19 -2
  116. package/src/reactive.test.ts +3 -2
  117. package/src/reactive.ts +22 -23
  118. package/src/store/StoreRegistry.test.ts +540 -0
  119. package/src/store/StoreRegistry.ts +418 -0
  120. package/src/store/create-store.ts +158 -39
  121. package/src/store/devtools.ts +77 -33
  122. package/src/store/store-eventstream.test.ts +114 -0
  123. package/src/store/store-types.test.ts +52 -0
  124. package/src/store/store-types.ts +360 -40
  125. package/src/store/store.ts +571 -236
  126. package/src/utils/dev.ts +2 -3
  127. package/src/utils/stack-info.ts +2 -2
  128. package/src/utils/tests/fixture.ts +9 -1
  129. package/src/utils/tests/otel.ts +8 -7
@@ -1,71 +1,152 @@
1
- import { type Bindable, type ClientSession, type ClientSessionSyncProcessor, MaterializeError, type QueryBuilder, UnexpectedError } from '@livestore/common';
1
+ import { type Bindable, type ClientSession, MaterializeError, type StorageMode, type SyncState, UnknownError } from '@livestore/common';
2
2
  import type { LiveStoreSchema } from '@livestore/common/schema';
3
3
  import { LiveStoreEvent } from '@livestore/common/schema';
4
- import type { Scope } from '@livestore/utils/effect';
5
4
  import { Cause, Effect, Inspectable, Schema, Stream } from '@livestore/utils/effect';
6
5
  import * as otel from '@opentelemetry/api';
7
- import type { LiveQuery, LiveQueryDef, ReactivityGraph, ReactivityGraphContext, SignalDef } from '../live-queries/base-class.ts';
8
- import type { Ref } from '../reactive.ts';
9
- import { SqliteDbWrapper } from '../SqliteDbWrapper.ts';
10
- import { ReferenceCountedSet } from '../utils/data-structures.ts';
11
- import type { StackInfo } from '../utils/stack-info.ts';
12
- import type { RefreshReason, StoreCommitOptions, StoreEventsOptions, StoreOptions, StoreOtel, Unsubscribe } from './store-types.ts';
6
+ import type { SignalDef } from '../live-queries/base-class.ts';
7
+ import { type Queryable, type RefreshReason, type StoreCommitOptions, type StoreConstructorParams, type StoreEventsOptions, type StoreInternals, StoreInternalsSymbol, type SubscribeOptions, type SyncStatus, type Unsubscribe } from './store-types.ts';
8
+ export type SubscribeFn = {
9
+ <TResult>(query: Queryable<TResult>, onUpdate: (value: TResult) => void, options?: SubscribeOptions<TResult>): Unsubscribe;
10
+ <TResult>(query: Queryable<TResult>, options?: SubscribeOptions<TResult>): AsyncIterable<TResult>;
11
+ };
12
+ /**
13
+ * Default parameters for the Store. Also used in `create-store.ts`
14
+ */
15
+ export declare const STORE_DEFAULT_PARAMS: {
16
+ leaderPushBatchSize: number;
17
+ eventQueryBatchSize: number;
18
+ };
19
+ /**
20
+ * Central interface to a LiveStore database providing reactive queries, event commits, and sync.
21
+ *
22
+ * A `Store` instance wraps a local SQLite database that is kept in sync with other clients via
23
+ * an event log. Instead of mutating state directly, you commit events that get materialized
24
+ * into database rows. Queries automatically re-run when their underlying tables change.
25
+ *
26
+ * ## Creating a Store
27
+ *
28
+ * Use `createStore` (Effect-based) or `createStorePromise` to obtain a Store instance.
29
+ * In React applications, use `StoreRegistry` with `<StoreRegistryProvider>` and the `useStore()` hook
30
+ * which manages the Store lifecycle.
31
+ *
32
+ * ## Querying Data
33
+ *
34
+ * Use {@link Store.query} for one-shot reads or {@link Store.subscribe} for reactive subscriptions.
35
+ * Both accept query builders (e.g. `tables.todo.where({ complete: true })`) or custom `LiveQueryDef`s.
36
+ *
37
+ * ## Committing Events
38
+ *
39
+ * Use {@link Store.commit} to persist events. Events are immediately materialized locally and
40
+ * asynchronously synced to other clients. Multiple events can be committed atomically.
41
+ *
42
+ * ## Lifecycle
43
+ *
44
+ * The Store must be shut down when no longer needed via {@link Store.shutdown} or
45
+ * {@link Store.shutdownPromise}. Framework integrations (React, Effect) handle this automatically.
46
+ *
47
+ * @typeParam TSchema - The LiveStore schema defining tables and events
48
+ * @typeParam TContext - Optional user-defined context attached to the Store (e.g. for dependency injection)
49
+ *
50
+ * @example
51
+ * ```ts
52
+ * // Query data
53
+ * const todos = store.query(tables.todo.where({ complete: false }))
54
+ *
55
+ * // Subscribe to changes
56
+ * const unsubscribe = store.subscribe(tables.todo.all(), (todos) => {
57
+ * console.log('Todos updated:', todos)
58
+ * })
59
+ *
60
+ * // Commit an event
61
+ * store.commit(events.todoCreated({ id: nanoid(), text: 'Buy milk' }))
62
+ * ```
63
+ */
13
64
  export declare class Store<TSchema extends LiveStoreSchema = LiveStoreSchema.Any, TContext = {}> extends Inspectable.Class {
65
+ /** Unique identifier for this Store instance, stable for its lifetime. */
14
66
  readonly storeId: string;
15
- reactivityGraph: ReactivityGraph;
16
- sqliteDbWrapper: SqliteDbWrapper;
17
- clientSession: ClientSession;
18
- schema: LiveStoreSchema;
19
- context: TContext;
20
- otel: StoreOtel;
21
- /**
22
- * Note we're using `Ref<null>` here as we don't care about the value but only about *that* something has changed.
23
- * This only works in combination with `equal: () => false` which will always trigger a refresh.
24
- */
25
- tableRefs: {
26
- [key: string]: Ref<null, ReactivityGraphContext, RefreshReason>;
27
- };
28
- /** Tracks whether the store has been shut down */
29
- private isShutdown;
30
- private effectContext;
31
- /** RC-based set to see which queries are currently subscribed to */
32
- activeQueries: ReferenceCountedSet<LiveQuery<any>>;
33
- readonly __eventSchema: LiveStoreEvent.ForEventDefRecord<TSchema["_EventDefMapType"]>;
34
- readonly syncProcessor: ClientSessionSyncProcessor;
35
- readonly boot: Effect.Effect<void, UnexpectedError, Scope.Scope>;
36
- constructor({ clientSession, schema, otelOptions, context, batchUpdates, storeId, effectContext, params, confirmUnsavedChanges, __runningInDevtools, }: StoreOptions<TSchema, TContext>);
67
+ /** The LiveStore schema defining tables, events, and materializers. */
68
+ readonly schema: LiveStoreSchema;
69
+ /** User-defined context attached to this Store (e.g. for dependency injection). */
70
+ readonly context: TContext;
71
+ /** Options provided to the Store constructor. */
72
+ readonly params: StoreConstructorParams<TSchema, TContext>['params'];
73
+ /**
74
+ * Reactive connectivity updates emitted by the backing sync backend.
75
+ *
76
+ * @example
77
+ * ```ts
78
+ * import { Effect, Stream } from 'effect'
79
+ *
80
+ * const status = await store.networkStatus.pipe(Effect.runPromise)
81
+ *
82
+ * await store.networkStatus.changes.pipe(
83
+ * Stream.tap((next) => console.log('network status update', next)),
84
+ * Stream.runDrain,
85
+ * Effect.scoped,
86
+ * Effect.runPromise,
87
+ * )
88
+ * ```
89
+ */
90
+ readonly networkStatus: ClientSession['leaderThread']['networkStatus'];
91
+ /**
92
+ * Indicates how data is being stored.
93
+ *
94
+ * - `persisted`: Data is persisted to disk (e.g., via OPFS on web, SQLite file on native)
95
+ * - `in-memory`: Data is only stored in memory and will be lost on page refresh
96
+ *
97
+ * The store operates in `in-memory` mode when persistent storage is unavailable,
98
+ * such as in Safari/Firefox private browsing mode where OPFS is restricted.
99
+ *
100
+ * @example
101
+ * ```tsx
102
+ * if (store.storageMode === 'in-memory') {
103
+ * showWarning('Data will not be persisted in private browsing mode')
104
+ * }
105
+ * ```
106
+ */
107
+ readonly storageMode: StorageMode;
108
+ /**
109
+ * Store internals. Not part of the public API — shapes and semantics may change without notice.
110
+ */
111
+ readonly [StoreInternalsSymbol]: StoreInternals;
112
+ constructor({ clientSession, schema, otelOptions, context, batchUpdates, storeId, effectContext, params, confirmUnsavedChanges, __runningInDevtools, }: StoreConstructorParams<TSchema, TContext>);
113
+ /**
114
+ * Current session identifier for this Store instance.
115
+ *
116
+ * - Stable for the lifetime of the Store
117
+ * - Useful for correlating events or scoping per-session data
118
+ */
37
119
  get sessionId(): string;
120
+ /**
121
+ * Stable client identifier for the process/device using this Store.
122
+ *
123
+ * - Shared across Store instances created by the same client
124
+ * - Useful for diagnostics and multi-client correlation
125
+ */
38
126
  get clientId(): string;
39
127
  private checkShutdown;
40
128
  /**
41
- * Subscribe to the results of a query
42
- * Returns a function to cancel the subscription.
129
+ * Subscribe to the results of a query.
130
+ *
131
+ * - When providing an `onUpdate` callback it returns an {@link Unsubscribe} function.
132
+ * - Without a callback it returns an {@link AsyncIterable} that yields query results.
133
+ *
134
+ * @example
135
+ * ```ts
136
+ * const unsubscribe = store.subscribe(query$, (result) => console.log(result))
137
+ * ```
43
138
  *
44
139
  * @example
45
140
  * ```ts
46
- * const unsubscribe = store.subscribe(query$, { onUpdate: (result) => console.log(result) })
141
+ * for await (const result of store.subscribe(query$)) {
142
+ * console.log(result)
143
+ * }
47
144
  * ```
48
145
  */
49
- subscribe: <TResult>(query: LiveQueryDef<TResult, "def" | "signal-def"> | LiveQuery<TResult> | QueryBuilder<TResult, any, any>, options: {
50
- /** Called when the query result has changed */
51
- onUpdate: (value: TResult) => void;
52
- onSubscribe?: (query$: LiveQuery<TResult>) => void;
53
- /** Gets called after the query subscription has been removed */
54
- onUnsubsubscribe?: () => void;
55
- label?: string;
56
- /**
57
- * Skips the initial `onUpdate` callback
58
- * @default false
59
- */
60
- skipInitialRun?: boolean;
61
- otelContext?: otel.Context;
62
- /** If provided, the stack info will be added to the `activeSubscriptions` set of the query */
63
- stackInfo?: StackInfo;
64
- }) => Unsubscribe;
65
- subscribeStream: <TResult>(query$: LiveQueryDef<TResult>, options?: {
66
- label?: string;
67
- skipInitialRun?: boolean;
68
- } | undefined) => Stream.Stream<TResult>;
146
+ subscribe: SubscribeFn;
147
+ private subscribeWithCallback;
148
+ private subscribeAsAsyncIterable;
149
+ subscribeStream: <TResult>(query: Queryable<TResult>, options?: SubscribeOptions<TResult>) => Stream.Stream<TResult>;
69
150
  /**
70
151
  * Synchronously queries the database without creating a LiveQuery.
71
152
  * This is useful for queries that don't need to be reactive.
@@ -80,7 +161,7 @@ export declare class Store<TSchema extends LiveStoreSchema = LiveStoreSchema.Any
80
161
  * const completedTodos = store.query({ query: 'SELECT * FROM todo WHERE complete = 1', bindValues: {} })
81
162
  * ```
82
163
  */
83
- query: <TResult>(query: QueryBuilder<TResult, any, any> | LiveQuery<TResult> | LiveQueryDef<TResult> | SignalDef<TResult> | {
164
+ query: <TResult>(query: Queryable<TResult> | {
84
165
  query: string;
85
166
  bindValues: Bindable;
86
167
  schema?: Schema.Schema<TResult>;
@@ -156,31 +237,117 @@ export declare class Store<TSchema extends LiveStoreSchema = LiveStoreSchema.Any
156
237
  * ```
157
238
  */
158
239
  commit: {
159
- <const TCommitArg extends ReadonlyArray<LiveStoreEvent.PartialForSchema<TSchema>>>(...list: TCommitArg): void;
160
- (txn: <const TCommitArg extends ReadonlyArray<LiveStoreEvent.PartialForSchema<TSchema>>>(...list: TCommitArg) => void): void;
161
- <const TCommitArg extends ReadonlyArray<LiveStoreEvent.PartialForSchema<TSchema>>>(options: StoreCommitOptions, ...list: TCommitArg): void;
162
- (options: StoreCommitOptions, txn: <const TCommitArg extends ReadonlyArray<LiveStoreEvent.PartialForSchema<TSchema>>>(...list: TCommitArg) => void): void;
240
+ <const TCommitArg extends ReadonlyArray<LiveStoreEvent.Input.ForSchema<TSchema>>>(...list: TCommitArg): void;
241
+ (txn: <const TCommitArg extends ReadonlyArray<LiveStoreEvent.Input.ForSchema<TSchema>>>(...list: TCommitArg) => void): void;
242
+ <const TCommitArg extends ReadonlyArray<LiveStoreEvent.Input.ForSchema<TSchema>>>(options: StoreCommitOptions, ...list: TCommitArg): void;
243
+ (options: StoreCommitOptions, txn: <const TCommitArg extends ReadonlyArray<LiveStoreEvent.Input.ForSchema<TSchema>>>(...list: TCommitArg) => void): void;
163
244
  };
164
245
  /**
165
- * Returns an async iterable of events.
246
+ * Returns an async iterable of events from the eventlog.
247
+ * Currently only events confirmed by the sync backend is supported.
248
+ *
249
+ * Defaults to tracking upstreamHead as it advances. If an `until` event is
250
+ * supplied the stream finalizes upon reaching it.
251
+ *
252
+ * To start streaming from a specific point in the eventlog
253
+ * you can provide a `since` event.
254
+ *
255
+ * Allows filtering by:
256
+ * - `filter`: event types
257
+ * - `clientIds`: client identifiers
258
+ * - `sessionIds`: session identifiers
259
+ *
260
+ * The batchSize option controls the maximum amount of events that are fetched
261
+ * from the eventlog in each query. Defaults to 100 and has a max allowed
262
+ * value of 1000.
263
+ *
264
+ * TODO:
265
+ * - Support streaming unconfirmed events
266
+ * - Leader level
267
+ * - Session level
268
+ * - Support streaming client-only events
166
269
  *
167
270
  * @example
168
271
  * ```ts
169
- * for await (const event of store.events()) {
272
+ * // Stream todoCompleted events from the start
273
+ * for await (const event of store.events(filter: ['todoCompleted'])) {
170
274
  * console.log(event)
171
275
  * }
172
276
  * ```
173
277
  *
174
278
  * @example
175
279
  * ```ts
176
- * // Get all events from the beginning of time
177
- * for await (const event of store.events({ cursor: EventSequenceNumber.ROOT })) {
280
+ * // Start streaming from a specific event
281
+ * for await (const event of store.events({ since: EventSequenceNumber.Client.fromString('e3') })) {
178
282
  * console.log(event)
179
283
  * }
180
284
  * ```
181
285
  */
182
- events: (_options?: StoreEventsOptions<TSchema>) => AsyncIterable<LiveStoreEvent.ForSchema<TSchema>>;
183
- eventsStream: (_options?: StoreEventsOptions<TSchema>) => Stream.Stream<LiveStoreEvent.ForSchema<TSchema>>;
286
+ events: (options?: StoreEventsOptions<TSchema>) => AsyncIterable<LiveStoreEvent.Client.ForSchema<TSchema>>;
287
+ /**
288
+ * Returns an Effect Stream of events from the eventlog.
289
+ * See `store.events` for details on options and behaviour.
290
+ */
291
+ eventsStream: (options?: StoreEventsOptions<TSchema>) => Stream.Stream<LiveStoreEvent.Client.ForSchema<TSchema>, UnknownError>;
292
+ /**
293
+ * Returns the current synchronization status of the store.
294
+ *
295
+ * This is a synchronous operation that returns the sync state between the
296
+ * client session and the leader thread. Use this to display sync indicators
297
+ * or check if local changes have been pushed to the leader.
298
+ *
299
+ * @example
300
+ * ```ts
301
+ * const status = store.syncStatus()
302
+ * console.log(status.isSynced ? 'Synced' : `${status.pendingCount} pending`)
303
+ * ```
304
+ *
305
+ * @example
306
+ * ```ts
307
+ * // Health check for backend connectivity
308
+ * const status = store.syncStatus()
309
+ * if (!status.isSynced && status.pendingCount > 100) {
310
+ * console.warn('Large backlog of unsynced events')
311
+ * }
312
+ * ```
313
+ */
314
+ syncStatus: () => SyncStatus;
315
+ /**
316
+ * Returns an Effect Stream of sync status updates.
317
+ *
318
+ * Emits the current status immediately and then whenever the sync state changes.
319
+ * Use this for Effect-based workflows or when you need more control over the stream.
320
+ *
321
+ * @example
322
+ * ```ts
323
+ * store.syncStatusStream().pipe(
324
+ * Stream.tap((status) => Effect.log(`Sync status: ${status.isSynced}`)),
325
+ * Stream.runDrain,
326
+ * )
327
+ * ```
328
+ */
329
+ syncStatusStream: () => Stream.Stream<SyncStatus>;
330
+ /**
331
+ * Subscribes to sync status changes.
332
+ *
333
+ * The callback is invoked immediately with the current status and then
334
+ * whenever the sync state changes (e.g., when events are pushed or confirmed).
335
+ *
336
+ * @param onUpdate - Callback invoked with the current sync status
337
+ * @returns Unsubscribe function to stop receiving updates
338
+ *
339
+ * @example
340
+ * ```ts
341
+ * const unsubscribe = store.subscribeSyncStatus((status) => {
342
+ * updateUI(status.isSynced ? 'Synced' : 'Syncing...')
343
+ * })
344
+ *
345
+ * // Later, stop listening
346
+ * unsubscribe()
347
+ * ```
348
+ */
349
+ subscribeSyncStatus: (onUpdate: (status: SyncStatus) => void) => Unsubscribe;
350
+ private makeSyncStatus;
184
351
  /**
185
352
  * This can be used in combination with `skipRefresh` when committing events.
186
353
  * We might need a better solution for this. Let's see.
@@ -193,13 +360,33 @@ export declare class Store<TSchema extends LiveStoreSchema = LiveStoreSchema.Any
193
360
  *
194
361
  * This is called automatically when the store was created using the React or Effect API.
195
362
  */
196
- shutdownPromise: (cause?: UnexpectedError) => Promise<void>;
363
+ shutdownPromise: (cause?: UnknownError) => Promise<void>;
197
364
  /**
198
365
  * Shuts down the store and closes the client session.
199
366
  *
200
367
  * This is called automatically when the store was created using the React or Effect API.
201
368
  */
202
- shutdown: (cause?: Cause.Cause<UnexpectedError | MaterializeError>) => Effect.Effect<void>;
369
+ shutdown: (cause?: Cause.Cause<UnknownError | MaterializeError>) => Effect.Effect<void>;
370
+ /**
371
+ * Helper methods useful during development
372
+ *
373
+ * @internal
374
+ */
375
+ _dev: {
376
+ downloadDb: (source?: "local" | "leader") => void;
377
+ downloadEventlogDb: () => void;
378
+ hardReset: (mode?: "all-data" | "only-app-db") => void;
379
+ overrideNetworkStatus: (status: "online" | "offline") => void;
380
+ syncStates: () => Promise<{
381
+ session: SyncState.SyncState;
382
+ leader: SyncState.SyncState;
383
+ }>;
384
+ printSyncStates: () => void;
385
+ version: string;
386
+ otel: {
387
+ rootSpanContext: () => otel.SpanContext | undefined;
388
+ };
389
+ };
203
390
  toJSON: () => {
204
391
  _tag: string;
205
392
  reactivityGraph: import("../reactive.ts").ReactiveGraphSnapshot;
@@ -1 +1 @@
1
- {"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/store/store.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/store/store.ts"],"names":[],"mappings":"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"}