@livestore/livestore 0.4.0-dev.8 → 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,29 +1,142 @@
1
- import type { ClientSession, ClientSessionSyncProcessorSimulationParams, IntentionalShutdownCause, InvalidPullError, IsOfflineError, MaterializeError, StoreInterrupted, SyncError, UnexpectedError } from '@livestore/common';
2
- import type { EventSequenceNumber, LiveStoreEvent, LiveStoreSchema } from '@livestore/common/schema';
3
- import type { Effect, Runtime, Scope } from '@livestore/utils/effect';
4
- import { Deferred } from '@livestore/utils/effect';
5
1
  import type * as otel from '@opentelemetry/api';
6
- import type { DebugRefreshReasonBase } from '../reactive.ts';
2
+ import { type ClientSession, type ClientSessionSyncProcessor, type ClientSessionSyncProcessorSimulationParams, type IntentionalShutdownCause, type MaterializeError, type QueryBuilder, type StoreInterrupted, type BackendIdMismatchError, type UnknownError } from '@livestore/common';
3
+ import type { StreamEventsOptions } from '@livestore/common/leader-thread';
4
+ import type { LiveStoreEvent, LiveStoreSchema } from '@livestore/common/schema';
5
+ import type { Effect, Runtime, Schema, Scope } from '@livestore/utils/effect';
6
+ import { Deferred } from '@livestore/utils/effect';
7
+ import type { LiveQuery, LiveQueryDef, ReactivityGraph, ReactivityGraphContext, SignalDef } from '../live-queries/base-class.ts';
8
+ import type { DebugRefreshReasonBase, Ref } from '../reactive.ts';
9
+ import type { SqliteDbWrapper } from '../SqliteDbWrapper.ts';
10
+ import type { ReferenceCountedSet } from '../utils/data-structures.ts';
7
11
  import type { StackInfo } from '../utils/stack-info.ts';
8
12
  import type { Store } from './store.ts';
9
- export type LiveStoreContext = LiveStoreContextRunning | {
13
+ /**
14
+ * Union type representing the possible states of a LiveStore context.
15
+ *
16
+ * Used by framework integrations (React, Solid, etc.) to track Store lifecycle:
17
+ * - `running`: Store is active and ready for queries/commits
18
+ * - `error`: Store failed during boot or operation
19
+ * - `shutdown`: Store was intentionally shut down or interrupted
20
+ *
21
+ * @typeParam TSchema - The LiveStore schema type. Defaults to `LiveStoreSchema.Any`.
22
+ */
23
+ export type LiveStoreContext<TSchema extends LiveStoreSchema = LiveStoreSchema.Any> = LiveStoreContextRunning<TSchema> | {
10
24
  stage: 'error';
11
- error: UnexpectedError | unknown;
25
+ error: unknown;
12
26
  } | {
13
27
  stage: 'shutdown';
14
- cause: IntentionalShutdownCause | StoreInterrupted | SyncError;
28
+ cause: IntentionalShutdownCause | StoreInterrupted | UnknownError;
15
29
  };
16
- export type ShutdownDeferred = Deferred.Deferred<IntentionalShutdownCause, UnexpectedError | SyncError | StoreInterrupted | MaterializeError | InvalidPullError | IsOfflineError>;
30
+ export type ShutdownDeferred = Deferred.Deferred<IntentionalShutdownCause, UnknownError | StoreInterrupted | MaterializeError | BackendIdMismatchError>;
17
31
  export declare const makeShutdownDeferred: Effect.Effect<ShutdownDeferred>;
18
- export type LiveStoreContextRunning = {
32
+ /**
33
+ * Context state when the Store is active and ready for use.
34
+ *
35
+ * This is the normal operating state where you can query data, commit events,
36
+ * and subscribe to changes.
37
+ *
38
+ * @typeParam TSchema - The LiveStore schema type. Defaults to `LiveStoreSchema.Any`
39
+ * for backwards compatibility, but prefer providing the concrete schema type
40
+ * for full type safety.
41
+ */
42
+ export type LiveStoreContextRunning<TSchema extends LiveStoreSchema = LiveStoreSchema.Any> = {
19
43
  stage: 'running';
20
- store: Store;
44
+ store: Store<TSchema>;
21
45
  };
22
46
  export type OtelOptions = {
23
47
  tracer: otel.Tracer;
24
48
  rootSpanContext: otel.Context;
25
49
  };
26
- export type StoreOptions<TSchema extends LiveStoreSchema = LiveStoreSchema.Any, TContext = {}> = {
50
+ export declare const StoreInternalsSymbol: unique symbol;
51
+ export type StoreInternalsSymbol = typeof StoreInternalsSymbol;
52
+ /**
53
+ * Opaque bag containing the Store's implementation details.
54
+ *
55
+ * Not part of the public API — shapes and semantics may change without notice.
56
+ * Access only from within the @livestore/livestore package (and Devtools) via
57
+ * `StoreInternalsSymbol` to avoid accidental coupling in application code.
58
+ */
59
+ export type StoreInternals = {
60
+ /**
61
+ * Runtime event schema used for encoding/decoding events.
62
+ *
63
+ * Exposed primarily for Devtools (e.g. databrowser) to validate ad‑hoc
64
+ * event payloads. Application code should not depend on it directly.
65
+ */
66
+ readonly eventSchema: Schema.Schema<LiveStoreEvent.Client.Decoded, LiveStoreEvent.Client.Encoded>;
67
+ /**
68
+ * The active client session backing this Store. Provides access to the
69
+ * leader thread, network status, and shutdown signaling.
70
+ *
71
+ * Do not close or mutate directly — use `store.shutdown(...)`.
72
+ */
73
+ readonly clientSession: ClientSession;
74
+ /**
75
+ * Wrapper around the local SQLite state database. Centralizes query
76
+ * planning, caching, and change tracking used by reads and materializers.
77
+ */
78
+ readonly sqliteDbWrapper: SqliteDbWrapper;
79
+ /**
80
+ * Effect runtime and scope used to fork background fibers for the Store.
81
+ *
82
+ * - `runtime` executes effects from imperative Store APIs.
83
+ * - `lifetimeScope` owns forked fibers; closed during Store shutdown.
84
+ */
85
+ readonly effectContext: {
86
+ /** Effect runtime to run Store effects with proper environment. */
87
+ readonly runtime: Runtime.Runtime<Scope.Scope>;
88
+ /** Scope that owns all long‑lived fibers spawned by the Store. */
89
+ readonly lifetimeScope: Scope.Scope;
90
+ };
91
+ /**
92
+ * OpenTelemetry primitives used for instrumentation of commits, queries,
93
+ * and Store boot lifecycle.
94
+ */
95
+ readonly otel: StoreOtel;
96
+ /**
97
+ * The Store's reactive graph instance used to model dependencies and
98
+ * propagate updates. Provides APIs to create refs/thunks/effects and to
99
+ * subscribe to refresh cycles.
100
+ */
101
+ readonly reactivityGraph: ReactivityGraph;
102
+ /**
103
+ * Per‑table reactive refs used to broadcast invalidations when materializers
104
+ * write to tables. Values are always `null`; equality is intentionally
105
+ * `false` to force recomputation.
106
+ *
107
+ * Keys are SQLite table names (user tables; some system tables may be
108
+ * intentionally excluded from refresh).
109
+ */
110
+ readonly tableRefs: Readonly<Record<string, Ref<null, ReactivityGraphContext, RefreshReason>>>;
111
+ /**
112
+ * Set of currently subscribed LiveQuery instances (reference‑counted).
113
+ * Used for Devtools and diagnostics.
114
+ */
115
+ readonly activeQueries: ReferenceCountedSet<LiveQuery<any>>;
116
+ /**
117
+ * Client‑session sync processor orchestrating push/pull and materialization
118
+ * of events into local state.
119
+ */
120
+ readonly syncProcessor: ClientSessionSyncProcessor;
121
+ /**
122
+ * Starts background fibers for sync and observation. Must be run exactly
123
+ * once per Store instance. Scoped; installs finalizers to end spans and
124
+ * detach reactive refs.
125
+ */
126
+ readonly boot: Effect.Effect<void, UnknownError, Scope.Scope>;
127
+ /**
128
+ * Tracks whether the Store has been shut down. When true, mutating APIs
129
+ * should reject via `checkShutdown`.
130
+ */
131
+ isShutdown: boolean;
132
+ };
133
+ /**
134
+ * Parameters for constructing a Store instance.
135
+ *
136
+ * @internal This type is used by the Store constructor and is not part of the public API.
137
+ * For creating stores, use `createStore()` or `StoreRegistry` instead.
138
+ */
139
+ export type StoreConstructorParams<TSchema extends LiveStoreSchema = LiveStoreSchema.Any, TContext = {}> = {
27
140
  clientSession: ClientSession;
28
141
  schema: TSchema;
29
142
  storeId: string;
@@ -37,16 +150,23 @@ export type StoreOptions<TSchema extends LiveStoreSchema = LiveStoreSchema.Any,
37
150
  batchUpdates: (runUpdates: () => void) => void;
38
151
  params: {
39
152
  leaderPushBatchSize: number;
153
+ eventQueryBatchSize?: number;
40
154
  simulation?: {
41
155
  clientSessionSyncProcessor: typeof ClientSessionSyncProcessorSimulationParams.Type;
42
156
  };
43
157
  };
44
158
  __runningInDevtools: boolean;
45
159
  };
160
+ /**
161
+ * Tagged union describing why a reactive refresh occurred.
162
+ *
163
+ * Used internally for debugging and devtools to trace the cause of query re-evaluations.
164
+ * Each variant includes context about what triggered the refresh.
165
+ */
46
166
  export type RefreshReason = DebugRefreshReasonBase | {
47
167
  _tag: 'commit';
48
168
  /** The events that were applied */
49
- events: ReadonlyArray<LiveStoreEvent.AnyDecoded | LiveStoreEvent.PartialAnyDecoded>;
169
+ events: ReadonlyArray<LiveStoreEvent.Client.Decoded | LiveStoreEvent.Input.Decoded>;
50
170
  /** The tables that were written to by the event */
51
171
  writeTables: ReadonlyArray<string>;
52
172
  } | {
@@ -64,10 +184,19 @@ export type RefreshReason = DebugRefreshReasonBase | {
64
184
  _tag: 'manual';
65
185
  label?: string;
66
186
  };
187
+ /**
188
+ * Debug information captured for each query execution.
189
+ *
190
+ * Used by devtools and performance monitoring to track query behavior.
191
+ */
67
192
  export type QueryDebugInfo = {
193
+ /** Query type discriminator ('db', 'computed', etc.) */
68
194
  _tag: string;
195
+ /** Human-readable query label */
69
196
  label: string;
197
+ /** SQL query string or computed function representation */
70
198
  query: string;
199
+ /** Execution time in milliseconds */
71
200
  durationMs: number;
72
201
  };
73
202
  export type StoreOtel = {
@@ -82,27 +211,156 @@ export type StoreCommitOptions = {
82
211
  spanLinks?: otel.Link[];
83
212
  otelContext?: otel.Context;
84
213
  };
85
- export type StoreEventsOptions<TSchema extends LiveStoreSchema> = {
214
+ /**
215
+ * filter: Narrowed to the store's event types
216
+ * includeClientOnly: Omitted from public API until supported
217
+ */
218
+ export type StoreEventsOptions<TSchema extends LiveStoreSchema> = Omit<StreamEventsOptions, 'filter' | 'includeClientOnly'> & {
86
219
  /**
87
- * By default only new events are returned.
88
- * Use this to get all events from a specific point in time.
89
- */
90
- cursor?: EventSequenceNumber.EventSequenceNumber;
91
- /**
92
- * Only include events of the given names
220
+ * Only include events of the given names.
93
221
  * @default undefined (include all)
94
222
  */
95
223
  filter?: ReadonlyArray<keyof TSchema['_EventDefMapType']>;
224
+ };
225
+ /**
226
+ * Function returned by `store.subscribe()` to stop receiving updates.
227
+ *
228
+ * Call this to unsubscribe from a query and release the associated resources.
229
+ *
230
+ * @example
231
+ * ```ts
232
+ * const unsubscribe = store.subscribe(todos$, (todos) => console.log(todos))
233
+ * // Later...
234
+ * unsubscribe()
235
+ * ```
236
+ */
237
+ export type Unsubscribe = () => void;
238
+ /**
239
+ * Options for `store.subscribe()`.
240
+ *
241
+ * @typeParam TResult - The result type of the subscribed query
242
+ */
243
+ export type SubscribeOptions<TResult> = {
244
+ /** Callback invoked when the subscription is established (receives the live query instance) */
245
+ onSubscribe?: (query$: LiveQuery<TResult>) => void;
246
+ /** Callback invoked when the subscription is terminated */
247
+ onUnsubsubscribe?: () => void;
248
+ /** Label for debugging and devtools */
249
+ label?: string;
250
+ /** If true, skips invoking the callback for the initial value */
251
+ skipInitialRun?: boolean;
252
+ /** OpenTelemetry context for tracing */
253
+ otelContext?: otel.Context;
254
+ /** Stack trace info for debugging subscription origins */
255
+ stackInfo?: StackInfo;
256
+ };
257
+ /** All query definitions or instances the store can execute or subscribe to. */
258
+ export type Queryable<TResult> = LiveQueryDef<TResult> | SignalDef<TResult> | LiveQuery<TResult> | QueryBuilder<TResult, any, any>;
259
+ /**
260
+ * Helper types for `Queryable`.
261
+ *
262
+ * Provides type-level utilities to work with `Queryable` values.
263
+ */
264
+ export declare namespace Queryable {
265
+ /**
266
+ * Extracts the result type from a `Queryable`.
267
+ *
268
+ * Example:
269
+ * - `Queryable.Result<LiveQueryDef<number>>` → `number`
270
+ * - `Queryable.Result<SignalDef<string>>` → `string`
271
+ * - `Queryable.Result<LiveQuery<{ id: string }>>` → `{ id: string }`
272
+ * - `Queryable.Result<LiveQueryDef<A> | SignalDef<B>>` → `A | B`
273
+ */
274
+ type Result<TQueryable extends Queryable<any>> = TQueryable extends Queryable<infer TResult> ? TResult : never;
275
+ }
276
+ /**
277
+ * Type guard that checks if a value is a query or signal definition.
278
+ *
279
+ * Use this to distinguish between definitions (blueprints) and instances (live queries).
280
+ * Definitions are created by `queryDb()`, `computed()`, and `signal()`.
281
+ *
282
+ * @example
283
+ * ```ts
284
+ * const todos$ = queryDb(tables.todos.all())
285
+ *
286
+ * if (isLiveQueryDef(todos$)) {
287
+ * console.log('This is a definition:', todos$.label)
288
+ * }
289
+ * ```
290
+ */
291
+ export declare const isLiveQueryDef: (value: unknown) => value is LiveQueryDef<any> | SignalDef<any>;
292
+ /**
293
+ * Type guard that checks if a value is a live query instance.
294
+ *
295
+ * Live query instances are stateful objects bound to a Store's reactivity graph.
296
+ * They're created internally when you use a definition with `store.query()` or `store.subscribe()`.
297
+ *
298
+ * @example
299
+ * ```ts
300
+ * const [, , , query$] = useClientDocument(tables.uiState)
301
+ *
302
+ * if (isLiveQueryInstance(query$)) {
303
+ * console.log('Execution count:', query$.runs)
304
+ * }
305
+ * ```
306
+ */
307
+ export declare const isLiveQueryInstance: (value: unknown) => value is LiveQuery<any>;
308
+ /**
309
+ * Type guard that checks if a value can be used with `store.query()` or `store.subscribe()`.
310
+ *
311
+ * Queryable values include:
312
+ * - Query definitions (`LiveQueryDef` from `queryDb()`, `computed()`)
313
+ * - Signal definitions (`SignalDef` from `signal()`)
314
+ * - Live query instances (`LiveQuery`)
315
+ * - Query builders (e.g., `tables.todos.where(...)`)
316
+ *
317
+ * @example
318
+ * ```ts
319
+ * const handleQuery = (input: unknown) => {
320
+ * if (isQueryable(input)) {
321
+ * return store.query(input)
322
+ * }
323
+ * throw new Error('Not a valid query')
324
+ * }
325
+ * ```
326
+ */
327
+ export declare const isQueryable: (value: unknown) => value is Queryable<unknown>;
328
+ /**
329
+ * Represents the current synchronization status of the store.
330
+ *
331
+ * This provides visibility into the sync state between the client session
332
+ * and the leader thread, allowing applications to show sync indicators
333
+ * or determine backend health.
334
+ *
335
+ * @example
336
+ * ```ts
337
+ * const status = store.syncStatus()
338
+ * if (status.isSynced) {
339
+ * console.log('All changes synced')
340
+ * } else {
341
+ * console.log(`${status.pendingCount} events pending sync`)
342
+ * }
343
+ * ```
344
+ */
345
+ export type SyncStatus = {
96
346
  /**
97
- * Whether to include client-only events or only return synced events
98
- * @default true
347
+ * The local head sequence number (most recent event in the client session).
348
+ * Represented as a string in the format "e{global}.{client}" (e.g., "e5.2").
99
349
  */
100
- includeClientOnly?: boolean;
350
+ localHead: string;
101
351
  /**
102
- * Exclude own events that have not been pushed to the sync backend yet
103
- * @default false
352
+ * The upstream head sequence number (what the leader thread has confirmed).
353
+ * Represented as a string in the format "e{global}" (e.g., "e3").
104
354
  */
105
- excludeUnpushed?: boolean;
355
+ upstreamHead: string;
356
+ /**
357
+ * Number of events pending synchronization to the leader thread.
358
+ */
359
+ pendingCount: number;
360
+ /**
361
+ * Whether the client session is fully synced with the leader thread.
362
+ * True when there are no pending events (pendingCount === 0).
363
+ */
364
+ isSynced: boolean;
106
365
  };
107
- export type Unsubscribe = () => void;
108
366
  //# sourceMappingURL=store-types.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"store-types.d.ts","sourceRoot":"","sources":["../../src/store/store-types.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"store-types.d.ts","sourceRoot":"","sources":["../../src/store/store-types.ts"],"names":[],"mappings":"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"}
@@ -1,3 +1,79 @@
1
- import { Deferred } from '@livestore/utils/effect';
1
+ import { isQueryBuilder, } from '@livestore/common';
2
+ import { Deferred, Predicate } from '@livestore/utils/effect';
3
+ import { TypeId } from "../live-queries/base-class.js";
2
4
  export const makeShutdownDeferred = Deferred.make();
5
+ export const StoreInternalsSymbol = Symbol.for('livestore.StoreInternals');
6
+ /**
7
+ * Type guard that checks if a value is a query or signal definition.
8
+ *
9
+ * Use this to distinguish between definitions (blueprints) and instances (live queries).
10
+ * Definitions are created by `queryDb()`, `computed()`, and `signal()`.
11
+ *
12
+ * @example
13
+ * ```ts
14
+ * const todos$ = queryDb(tables.todos.all())
15
+ *
16
+ * if (isLiveQueryDef(todos$)) {
17
+ * console.log('This is a definition:', todos$.label)
18
+ * }
19
+ * ```
20
+ */
21
+ export const isLiveQueryDef = (value) => {
22
+ if (typeof value !== 'object' || value === null) {
23
+ return false;
24
+ }
25
+ if (!('_tag' in value)) {
26
+ return false;
27
+ }
28
+ const tag = value._tag;
29
+ if (tag !== 'def' && tag !== 'signal-def') {
30
+ return false;
31
+ }
32
+ const candidate = value;
33
+ if (typeof candidate.make !== 'function') {
34
+ // The store calls make() to turn the definition into a live query instance.
35
+ return false;
36
+ }
37
+ if (typeof candidate.hash !== 'string' || typeof candidate.label !== 'string') {
38
+ // Both identifiers must be present so the store can cache and log the query.
39
+ return false;
40
+ }
41
+ return true;
42
+ };
43
+ /**
44
+ * Type guard that checks if a value is a live query instance.
45
+ *
46
+ * Live query instances are stateful objects bound to a Store's reactivity graph.
47
+ * They're created internally when you use a definition with `store.query()` or `store.subscribe()`.
48
+ *
49
+ * @example
50
+ * ```ts
51
+ * const [, , , query$] = useClientDocument(tables.uiState)
52
+ *
53
+ * if (isLiveQueryInstance(query$)) {
54
+ * console.log('Execution count:', query$.runs)
55
+ * }
56
+ * ```
57
+ */
58
+ export const isLiveQueryInstance = (value) => Predicate.hasProperty(value, TypeId);
59
+ /**
60
+ * Type guard that checks if a value can be used with `store.query()` or `store.subscribe()`.
61
+ *
62
+ * Queryable values include:
63
+ * - Query definitions (`LiveQueryDef` from `queryDb()`, `computed()`)
64
+ * - Signal definitions (`SignalDef` from `signal()`)
65
+ * - Live query instances (`LiveQuery`)
66
+ * - Query builders (e.g., `tables.todos.where(...)`)
67
+ *
68
+ * @example
69
+ * ```ts
70
+ * const handleQuery = (input: unknown) => {
71
+ * if (isQueryable(input)) {
72
+ * return store.query(input)
73
+ * }
74
+ * throw new Error('Not a valid query')
75
+ * }
76
+ * ```
77
+ */
78
+ export const isQueryable = (value) => isQueryBuilder(value) || isLiveQueryInstance(value) || isLiveQueryDef(value);
3
79
  //# sourceMappingURL=store-types.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"store-types.js","sourceRoot":"","sources":["../../src/store/store-types.ts"],"names":[],"mappings":"AAaA,OAAO,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAA;AAsBlD,MAAM,CAAC,MAAM,oBAAoB,GAAoC,QAAQ,CAAC,IAAI,EAG/E,CAAA"}
1
+ {"version":3,"file":"store-types.js","sourceRoot":"","sources":["../../src/store/store-types.ts"],"names":[],"mappings":"AAEA,OAAO,EAKL,cAAc,GAMf,MAAM,mBAAmB,CAAA;AAI1B,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAA;AAS7D,OAAO,EAAE,MAAM,EAAE,MAAM,+BAA+B,CAAA;AAgCtD,MAAM,CAAC,MAAM,oBAAoB,GAAoC,QAAQ,CAAC,IAAI,EAG/E,CAAA;AAsBH,MAAM,CAAC,MAAM,oBAAoB,GAAG,MAAM,CAAC,GAAG,CAAC,0BAA0B,CAAC,CAAA;AA8P1E;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,KAAc,EAA+C,EAAE;IAC5F,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QAChD,OAAO,KAAK,CAAA;IACd,CAAC;IAED,IAAI,CAAC,CAAC,MAAM,IAAI,KAAK,CAAC,EAAE,CAAC;QACvB,OAAO,KAAK,CAAA;IACd,CAAC;IAED,MAAM,GAAG,GAAI,KAA4C,CAAC,IAAI,CAAA;IAC9D,IAAI,GAAG,KAAK,KAAK,IAAI,GAAG,KAAK,YAAY,EAAE,CAAC;QAC1C,OAAO,KAAK,CAAA;IACd,CAAC;IAED,MAAM,SAAS,GAAG,KAA0B,CAAA;IAC5C,IAAI,OAAO,SAAS,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;QACzC,4EAA4E;QAC5E,OAAO,KAAK,CAAA;IACd,CAAC;IAED,IAAI,OAAO,SAAS,CAAC,IAAI,KAAK,QAAQ,IAAI,OAAO,SAAS,CAAC,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9E,6EAA6E;QAC7E,OAAO,KAAK,CAAA;IACd,CAAC;IAED,OAAO,IAAI,CAAA;AACb,CAAC,CAAA;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,KAAc,EAA2B,EAAE,CAAC,SAAS,CAAC,WAAW,CAAC,KAAK,EAAE,MAAM,CAAC,CAAA;AAEpH;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,KAAc,EAA+B,EAAE,CACzE,cAAc,CAAC,KAAK,CAAC,IAAI,mBAAmB,CAAC,KAAK,CAAC,IAAI,cAAc,CAAC,KAAK,CAAC,CAAA"}
@@ -0,0 +1,2 @@
1
+ export {};
2
+ //# sourceMappingURL=store-types.test.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"store-types.test.d.ts","sourceRoot":"","sources":["../../src/store/store-types.test.ts"],"names":[],"mappings":""}
@@ -0,0 +1,39 @@
1
+ import { describe, expect, it } from 'vitest';
2
+ import { QueryBuilderTypeId } from '@livestore/common';
3
+ import { Schema } from '@livestore/utils/effect';
4
+ import { TypeId } from "../live-queries/base-class.js";
5
+ import { queryDb, signal } from "../live-queries/mod.js";
6
+ import { isQueryable } from "./store-types.js";
7
+ const makeQueryBuilder = () => ({
8
+ [QueryBuilderTypeId]: QueryBuilderTypeId,
9
+ ResultType: null,
10
+ asSql: () => ({ query: 'select 1', bindValues: [], usedTables: new Set() }),
11
+ toString: () => 'select 1',
12
+ });
13
+ describe('isQueryable', () => {
14
+ it('identifies live query definitions', () => {
15
+ const def = queryDb({
16
+ query: 'select 1 as value',
17
+ schema: Schema.Array(Schema.Struct({ value: Schema.Number })),
18
+ });
19
+ expect(isQueryable(def)).toBe(true);
20
+ });
21
+ it('identifies signal definitions', () => {
22
+ const sig = signal(0, { label: 'count' });
23
+ expect(isQueryable(sig)).toBe(true);
24
+ });
25
+ it('identifies live query instances', () => {
26
+ const liveQueryLike = { [TypeId]: TypeId };
27
+ expect(isQueryable(liveQueryLike)).toBe(true);
28
+ });
29
+ it('identifies query builders', () => {
30
+ const qb = makeQueryBuilder();
31
+ expect(isQueryable(qb)).toBe(true);
32
+ });
33
+ it('rejects unrelated values', () => {
34
+ expect(isQueryable(null)).toBe(false);
35
+ expect(isQueryable(undefined)).toBe(false);
36
+ expect(isQueryable({})).toBe(false);
37
+ });
38
+ });
39
+ //# sourceMappingURL=store-types.test.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"store-types.test.js","sourceRoot":"","sources":["../../src/store/store-types.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAA;AAG7C,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAA;AACtD,OAAO,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAA;AAEhD,OAAO,EAAE,MAAM,EAAE,MAAM,+BAA+B,CAAA;AACtD,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAA;AACxD,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAE9C,MAAM,gBAAgB,GAAG,GAAgC,EAAE,CACzD,CAAC;IACC,CAAC,kBAAkB,CAAC,EAAE,kBAAkB;IACxC,UAAU,EAAE,IAAI;IAChB,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,EAAE,EAAE,UAAU,EAAE,IAAI,GAAG,EAAU,EAAE,CAAC;IACnF,QAAQ,EAAE,GAAG,EAAE,CAAC,UAAU;CAC3B,CAA2C,CAAA;AAE9C,QAAQ,CAAC,aAAa,EAAE,GAAG,EAAE;IAC3B,EAAE,CAAC,mCAAmC,EAAE,GAAG,EAAE;QAC3C,MAAM,GAAG,GAAG,OAAO,CAAC;YAClB,KAAK,EAAE,mBAAmB;YAC1B,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;SAC9D,CAAC,CAAA;QAEF,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IACrC,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,+BAA+B,EAAE,GAAG,EAAE;QACvC,MAAM,GAAG,GAAG,MAAM,CAAC,CAAC,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,CAAA;QAEzC,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IACrC,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,iCAAiC,EAAE,GAAG,EAAE;QACzC,MAAM,aAAa,GAAG,EAAE,CAAC,MAAM,CAAC,EAAE,MAAM,EAAW,CAAA;QAEnD,MAAM,CAAC,WAAW,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IAC/C,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,2BAA2B,EAAE,GAAG,EAAE;QACnC,MAAM,EAAE,GAAG,gBAAgB,EAAE,CAAA;QAE7B,MAAM,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IACpC,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,0BAA0B,EAAE,GAAG,EAAE;QAClC,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;QACrC,MAAM,CAAC,WAAW,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;QAC1C,MAAM,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;IACrC,CAAC,CAAC,CAAA;AACJ,CAAC,CAAC,CAAA"}