@livestore/livestore 0.4.0-dev.15 → 0.4.0-dev.17

package/src/live-queries/client-document-get-query.ts

@@ -3,7 +3,7 @@ import { SessionIdSymbol } from '@livestore/common'
 import { State } from '@livestore/common/schema'
 import { shouldNeverHappen } from '@livestore/utils'
 import type * as otel from '@opentelemetry/api'
-
+import { StoreInternalsSymbol } from '../store/store-types.ts'
 import type { ReactivityGraphContext } from './base-class.ts'
 
 export const rowQueryLabel = (
@@ -30,11 +30,11 @@ export const makeExecBeforeFirstRun =
       )
     }
 
-    const otelContext = otelContext_ ?? store.otel.queriesSpanContext
+    const otelContext = otelContext_ ?? store[StoreInternalsSymbol].otel.queriesSpanContext
 
     const idVal = id === SessionIdSymbol ? store.sessionId : id!
     const rowExists =
-      store.sqliteDbWrapper.cachedSelect(
+      store[StoreInternalsSymbol].sqliteDbWrapper.cachedSelect(
         `SELECT 1 FROM '${table.sqliteDef.name}' WHERE id = ?`,
         [idVal] as any as PreparedBindValues,
         { otelContext },

package/src/live-queries/db-query.test.ts

@@ -5,6 +5,7 @@ import { BasicTracerProvider, InMemorySpanExporter, SimpleSpanProcessor } from '
 import { assert, expect } from 'vitest'
 
 import * as RG from '../reactive.ts'
+import { StoreInternalsSymbol } from '../store/store-types.ts'
 import { events, makeTodoMvc, tables } from '../utils/tests/fixture.ts'
 import { getAllSimplifiedRootSpans, getSimplifiedRootSpan } from '../utils/tests/otel.ts'
 import { computed } from './computed.ts'
@@ -106,7 +107,7 @@ Vitest.describe('otel', () => {
         { label: 'all todos' },
       )
 
-      expect(store.reactivityGraph.getSnapshot({ includeResults: true })).toMatchSnapshot()
+      expect(store[StoreInternalsSymbol].reactivityGraph.getSnapshot({ includeResults: true })).toMatchSnapshot()
 
       expect(store.query(query$)).toMatchInlineSnapshot(`
       {
@@ -116,11 +117,11 @@ Vitest.describe('otel', () => {
       }
     `)
 
-      expect(store.reactivityGraph.getSnapshot({ includeResults: true })).toMatchSnapshot()
+      expect(store[StoreInternalsSymbol].reactivityGraph.getSnapshot({ includeResults: true })).toMatchSnapshot()
 
       store.commit(events.todoCreated({ id: 't1', text: 'buy milk', completed: false }))
 
-      expect(store.reactivityGraph.getSnapshot({ includeResults: true })).toMatchSnapshot()
+      expect(store[StoreInternalsSymbol].reactivityGraph.getSnapshot({ includeResults: true })).toMatchSnapshot()
 
       expect(store.query(query$)).toMatchInlineSnapshot(`
       {
@@ -130,7 +131,7 @@ Vitest.describe('otel', () => {
       }
     `)
 
-      expect(store.reactivityGraph.getSnapshot({ includeResults: true })).toMatchSnapshot()
+      expect(store[StoreInternalsSymbol].reactivityGraph.getSnapshot({ includeResults: true })).toMatchSnapshot()
 
       span.end()
 

package/src/live-queries/db-query.ts

@@ -16,6 +16,7 @@ import * as otel from '@opentelemetry/api'
 import type { Thunk } from '../reactive.ts'
 import { isThunk, NOT_REFRESHED_YET } from '../reactive.ts'
 import type { RefreshReason } from '../store/store-types.ts'
+import { StoreInternalsSymbol } from '../store/store-types.ts'
 import { isValidFunctionString } from '../utils/function-string.ts'
 import type { DepKey, GetAtomResult, LiveQueryDef, ReactivityGraph, ReactivityGraphContext } from './base-class.ts'
 import { depsToString, LiveStoreQueryBase, makeGetAtomResult, withRCMap } from './base-class.ts'
@@ -364,23 +365,25 @@ export class LiveStoreDbQuery<TResultSchema, TResult = TResultSchema> extends Li
             const bindValues = queryInputResult.bindValues
 
             if (queriedTablesRef.current === undefined) {
-              queriedTablesRef.current = store.sqliteDbWrapper.getTablesUsed(sqlString)
+              queriedTablesRef.current = store[StoreInternalsSymbol].sqliteDbWrapper.getTablesUsed(sqlString)
             }
 
             if (bindValues !== undefined) {
-              replaceSessionIdSymbol(bindValues, store.clientSession.sessionId)
+              replaceSessionIdSymbol(bindValues, store.sessionId)
             }
 
             // Establish a reactive dependency on the tables used in the query
             for (const tableName of queriedTablesRef.current) {
-              const tableRef = store.tableRefs[tableName] ?? shouldNeverHappen(`No table ref found for ${tableName}`)
+              const tableRef =
+                store[StoreInternalsSymbol].tableRefs[tableName] ??
+                shouldNeverHappen(`No table ref found for ${tableName}`)
               get(tableRef, otelContext, debugRefreshReason)
             }
 
             span.setAttribute('sql.query', sqlString)
             span.updateName(`db:${sqlString.slice(0, 50)}`)
 
-            const rawDbResults = store.sqliteDbWrapper.cachedSelect<any>(
+            const rawDbResults = store[StoreInternalsSymbol].sqliteDbWrapper.cachedSelect<any>(
               sqlString,
               bindValues ? prepareBindValues(bindValues, sqlString) : undefined,
               {

package/src/mod.ts

@@ -37,20 +37,20 @@ export {
 export { emptyDebugInfo, SqliteDbWrapper } from './SqliteDbWrapper.ts'
 export { type CreateStoreOptions, createStore, createStorePromise } from './store/create-store.ts'
 export { Store } from './store/store.ts'
-export type {
-  OtelOptions,
-  Queryable,
-  QueryDebugInfo,
-  RefreshReason,
-  SubscribeOptions,
-  Unsubscribe,
-} from './store/store-types.ts'
 export {
   isQueryable,
   type LiveStoreContext,
   type LiveStoreContextRunning,
   makeShutdownDeferred,
+  type OtelOptions,
+  type Queryable,
+  type QueryDebugInfo,
+  type RefreshReason,
   type ShutdownDeferred,
+  type StoreInternals,
+  StoreInternalsSymbol,
+  type SubscribeOptions,
+  type Unsubscribe,
 } from './store/store-types.ts'
 export { exposeDebugUtils } from './utils/dev.ts'
 export * from './utils/stack-info.ts'

package/src/store/create-store.ts

@@ -7,6 +7,7 @@ import {
   type IntentionalShutdownCause,
   type InvalidPullError,
   type IsOfflineError,
+  LogConfig,
   type MaterializeError,
   type MigrationsReport,
   provideOtel,
@@ -23,8 +24,6 @@ import {
   Fiber,
   identity,
   Layer,
-  Logger,
-  LogLevel,
   OtelTracer,
   Queue,
   Runtime,
@@ -42,6 +41,7 @@ import type {
   OtelOptions,
   ShutdownDeferred,
 } from './store-types.ts'
+import { StoreInternalsSymbol } from './store-types.ts'
 
 export const DEFAULT_PARAMS = {
   leaderPushBatchSize: 100,
@@ -117,7 +117,7 @@ export interface CreateStoreOptions<
   TSchema extends LiveStoreSchema,
   TContext = {},
   TSyncPayloadSchema extends Schema.Schema<any> = typeof Schema.JsonValue,
-> {
+> extends LogConfig.WithLoggerOptions {
   schema: TSchema
   adapter: Adapter
   storeId: string
@@ -205,8 +205,7 @@ export const createStorePromise = async <
     provideOtel(omitUndefineds({ parentSpanContext: otelOptions?.rootSpanContext, otelTracer: otelOptions?.tracer })),
     Effect.tapCauseLogPretty,
     Effect.annotateLogs({ thread: 'window' }),
-    Effect.provide(Logger.prettyWithThread('window')),
-    Logger.withMinimumLogLevel(LogLevel.Debug),
+    LogConfig.withLoggerConfig(options, { threadName: 'window' }),
     Effect.runPromise,
   )
 
@@ -348,7 +347,7 @@ export const createStore = <
       })
 
       // Starts background fibers (syncing, event processing, etc) for store
-      yield* store.boot
+      yield* store[StoreInternalsSymbol].boot
 
       if (boot !== undefined) {
         // TODO also incorporate `boot` function progress into `bootStatusQueue`
@@ -366,7 +365,7 @@ export const createStore = <
 
       if (batchUpdates !== undefined) {
         // Replacing the default batchUpdates function with the provided one after boot
-        store.reactivityGraph.context!.effectsWrapper = batchUpdates
+        store[StoreInternalsSymbol].reactivityGraph.context!.effectsWrapper = batchUpdates
       }
 
       yield* Deferred.succeed(storeDeferred, store as any as Store)

package/src/store/devtools.ts

@@ -1,23 +1,14 @@
-import type { ClientSession, ClientSessionSyncProcessor, DebugInfo, SyncState } from '@livestore/common'
+import type { DebugInfo, SyncState } from '@livestore/common'
 import { Devtools, liveStoreVersion, UnexpectedError } from '@livestore/common'
 import { throttle } from '@livestore/utils'
 import type { WebChannel } from '@livestore/utils/effect'
 import { Effect, Stream } from '@livestore/utils/effect'
 import { nanoid } from '@livestore/utils/nanoid'
 
-import type { LiveQuery, ReactivityGraph } from '../live-queries/base-class.ts'
 import { NOT_REFRESHED_YET } from '../reactive.ts'
-import type { SqliteDbWrapper } from '../SqliteDbWrapper.ts'
 import { emptyDebugInfo as makeEmptyDebugInfo } from '../SqliteDbWrapper.ts'
-import type { ReferenceCountedSet } from '../utils/data-structures.ts'
-
-type IStore = {
-  clientSession: ClientSession
-  reactivityGraph: ReactivityGraph
-  sqliteDbWrapper: SqliteDbWrapper
-  activeQueries: ReferenceCountedSet<LiveQuery<any>>
-  syncProcessor: ClientSessionSyncProcessor
-}
+import type { Store } from './store.ts'
+import { StoreInternalsSymbol } from './store-types.ts'
 
 type Unsub = () => void
 type RequestId = string
@@ -40,7 +31,7 @@ export const connectDevtoolsToStore = ({
     Devtools.ClientSession.MessageToApp,
     Devtools.ClientSession.MessageFromApp
   >
-  store: IStore
+  store: Store
 }) =>
   Effect.gen(function* () {
     const reactivityGraphSubcriptions: SubMap = new Map()
@@ -48,7 +39,7 @@ export const connectDevtoolsToStore = ({
     const debugInfoHistorySubscriptions: SubMap = new Map()
     const syncHeadClientSessionSubscriptions: SubMap = new Map()
 
-    const { clientId, sessionId } = store.clientSession
+    const { clientId, sessionId } = store[StoreInternalsSymbol].clientSession
 
     yield* Effect.addFinalizer(() =>
       Effect.sync(() => {
@@ -73,7 +64,21 @@ export const connectDevtoolsToStore = ({
       }
 
       if (decodedMessage._tag === 'LSD.ClientSession.Disconnect') {
-        // console.error('TODO handle disconnect properly in store')
+        // Gracefully tear down all DevTools subscriptions and close the channel.
+        // This prevents background fibers from lingering after DevTools closes
+        // (e.g. when a window is closed without sending explicit unsubs).
+        for (const unsub of reactivityGraphSubcriptions.values()) unsub()
+        reactivityGraphSubcriptions.clear()
+        for (const unsub of liveQueriesSubscriptions.values()) unsub()
+        liveQueriesSubscriptions.clear()
+        for (const unsub of debugInfoHistorySubscriptions.values()) unsub()
+        debugInfoHistorySubscriptions.clear()
+        for (const unsub of syncHeadClientSessionSubscriptions.values()) unsub()
+        syncHeadClientSessionSubscriptions.clear()
+
+        // Signal the WebChannel to shut down; this causes the `listen` stream
+        // to complete and allows the surrounding scoped fiber to exit.
+        storeDevtoolsChannel.shutdown.pipe(Effect.runFork)
         return
       }
 
@@ -103,7 +108,7 @@ export const connectDevtoolsToStore = ({
               () =>
                 sendToDevtools(
                   Devtools.ClientSession.ReactivityGraphRes.make({
-                    reactivityGraph: store.reactivityGraph.getSnapshot({ includeResults }),
+                    reactivityGraph: store[StoreInternalsSymbol].reactivityGraph.getSnapshot({ includeResults }),
                     requestId: nanoid(10),
                     clientId,
                     sessionId,
@@ -121,14 +126,17 @@ export const connectDevtoolsToStore = ({
           // This might need to be tweaked further and possibly be exposed to the user in some way.
           const throttledSend = throttle(send, 20)
 
-          reactivityGraphSubcriptions.set(subscriptionId, store.reactivityGraph.subscribeToRefresh(throttledSend))
+          reactivityGraphSubcriptions.set(
+            subscriptionId,
+            store[StoreInternalsSymbol].reactivityGraph.subscribeToRefresh(throttledSend),
+          )
 
           break
         }
         case 'LSD.ClientSession.DebugInfoReq': {
           sendToDevtools(
             Devtools.ClientSession.DebugInfoRes.make({
-              debugInfo: store.sqliteDbWrapper.debugInfo,
+              debugInfo: store[StoreInternalsSymbol].sqliteDbWrapper.debugInfo,
               requestId,
               clientId,
               sessionId,
@@ -144,13 +152,13 @@ export const connectDevtoolsToStore = ({
           let tickHandle: number | undefined
 
           const tick = () => {
-            buffer.push(store.sqliteDbWrapper.debugInfo)
+            buffer.push(store[StoreInternalsSymbol].sqliteDbWrapper.debugInfo)
 
             // NOTE this resets the debug info, so all other "readers" e.g. in other `requestAnimationFrame` loops,
             // will get the empty debug info
             // TODO We need to come up with a more graceful way to do store. Probably via a single global
             // `requestAnimationFrame` loop that is passed in somehow.
-            store.sqliteDbWrapper.debugInfo = makeEmptyDebugInfo()
+            store[StoreInternalsSymbol].sqliteDbWrapper.debugInfo = makeEmptyDebugInfo()
 
             if (buffer.length > 10) {
               sendToDevtools(
@@ -194,7 +202,7 @@ export const connectDevtoolsToStore = ({
           break
         }
         case 'LSD.ClientSession.DebugInfoResetReq': {
-          store.sqliteDbWrapper.debugInfo.slowQueries.clear()
+          store[StoreInternalsSymbol].sqliteDbWrapper.debugInfo.slowQueries.clear()
           sendToDevtools(
             Devtools.ClientSession.DebugInfoResetRes.make({ requestId, clientId, sessionId, liveStoreVersion }),
           )
@@ -202,7 +210,10 @@ export const connectDevtoolsToStore = ({
         }
         case 'LSD.ClientSession.DebugInfoRerunQueryReq': {
           const { queryStr, bindValues, queriedTables } = decodedMessage
-          store.sqliteDbWrapper.cachedSelect(queryStr, bindValues, { queriedTables, skipCache: true })
+          store[StoreInternalsSymbol].sqliteDbWrapper.cachedSelect(queryStr, bindValues, {
+            queriedTables,
+            skipCache: true,
+          })
           sendToDevtools(
             Devtools.ClientSession.DebugInfoRerunQueryRes.make({ requestId, clientId, sessionId, liveStoreVersion }),
           )
@@ -223,7 +234,7 @@ export const connectDevtoolsToStore = ({
               () =>
                 sendToDevtools(
                   Devtools.ClientSession.LiveQueriesRes.make({
-                    liveQueries: [...store.activeQueries].map((q) => ({
+                    liveQueries: [...store[StoreInternalsSymbol].activeQueries].map((q) => ({
                       _tag: q._tag,
                       id: q.id,
                       label: q.label,
@@ -251,7 +262,10 @@ export const connectDevtoolsToStore = ({
           // Same as in the reactivity graph subscription case above, we need to throttle the updates
           const throttledSend = throttle(send, 20)
 
-          liveQueriesSubscriptions.set(subscriptionId, store.reactivityGraph.subscribeToRefresh(throttledSend))
+          liveQueriesSubscriptions.set(
+            subscriptionId,
+            store[StoreInternalsSymbol].reactivityGraph.subscribeToRefresh(throttledSend),
+          )
 
           break
         }
@@ -278,11 +292,11 @@ export const connectDevtoolsToStore = ({
               }),
             )
 
-          send(store.syncProcessor.syncState.pipe(Effect.runSync))
+          send(store[StoreInternalsSymbol].syncProcessor.syncState.pipe(Effect.runSync))
 
           syncHeadClientSessionSubscriptions.set(
             subscriptionId,
-            store.syncProcessor.syncState.changes.pipe(
+            store[StoreInternalsSymbol].syncProcessor.syncState.changes.pipe(
               Stream.tap((syncState) => send(syncState)),
               Stream.runDrain,
               Effect.interruptible,

package/src/store/store-types.ts

@@ -1,5 +1,6 @@
 import {
   type ClientSession,
+  type ClientSessionSyncProcessor,
   type ClientSessionSyncProcessorSimulationParams,
   type IntentionalShutdownCause,
   type InvalidPullError,
@@ -12,13 +13,20 @@ import {
   type UnexpectedError,
 } from '@livestore/common'
 import type { EventSequenceNumber, LiveStoreEvent, LiveStoreSchema } from '@livestore/common/schema'
-import type { Effect, Runtime, Scope } from '@livestore/utils/effect'
+import type { Effect, Runtime, Schema, Scope } from '@livestore/utils/effect'
 import { Deferred, Predicate } from '@livestore/utils/effect'
 import type * as otel from '@opentelemetry/api'
-
-import type { LiveQuery, LiveQueryDef, SignalDef } from '../live-queries/base-class.ts'
+import type {
+  LiveQuery,
+  LiveQueryDef,
+  ReactivityGraph,
+  ReactivityGraphContext,
+  SignalDef,
+} from '../live-queries/base-class.ts'
 import { TypeId } from '../live-queries/base-class.ts'
-import type { DebugRefreshReasonBase } from '../reactive.ts'
+import type { DebugRefreshReasonBase, Ref } from '../reactive.ts'
+import type { SqliteDbWrapper } from '../SqliteDbWrapper.ts'
+import type { ReferenceCountedSet } from '../utils/data-structures.ts'
 import type { StackInfo } from '../utils/stack-info.ts'
 import type { Store } from './store.ts'
 
@@ -52,6 +60,101 @@ export type OtelOptions = {
   rootSpanContext: otel.Context
 }
 
+export const StoreInternalsSymbol = Symbol.for('livestore.StoreInternals')
+export type StoreInternalsSymbol = typeof StoreInternalsSymbol
+
+/**
+ * Opaque bag containing the Store's implementation details.
+ *
+ * Not part of the public API — shapes and semantics may change without notice.
+ * Access only from within the @livestore/livestore package (and Devtools) via
+ * `StoreInternalsSymbol` to avoid accidental coupling in application code.
+ */
+export type StoreInternals = {
+  /**
+   * Runtime event schema used for encoding/decoding events.
+   *
+   * Exposed primarily for Devtools (e.g. databrowser) to validate ad‑hoc
+   * event payloads. Application code should not depend on it directly.
+   */
+  readonly eventSchema: Schema.Schema<LiveStoreEvent.AnyDecoded, LiveStoreEvent.AnyEncoded>
+
+  /**
+   * The active client session backing this Store. Provides access to the
+   * leader thread, network status, and shutdown signaling.
+   *
+   * Do not close or mutate directly — use `store.shutdown(...)`.
+   */
+  readonly clientSession: ClientSession
+
+  /**
+   * Wrapper around the local SQLite state database. Centralizes query
+   * planning, caching, and change tracking used by reads and materializers.
+   */
+  readonly sqliteDbWrapper: SqliteDbWrapper
+
+  /**
+   * Effect runtime and scope used to fork background fibers for the Store.
+   *
+   * - `runtime` executes effects from imperative Store APIs.
+   * - `lifetimeScope` owns forked fibers; closed during Store shutdown.
+   */
+  readonly effectContext: {
+    /** Effect runtime to run Store effects with proper environment. */
+    readonly runtime: Runtime.Runtime<Scope.Scope>
+    /** Scope that owns all long‑lived fibers spawned by the Store. */
+    readonly lifetimeScope: Scope.Scope
+  }
+
+  /**
+   * OpenTelemetry primitives used for instrumentation of commits, queries,
+   * and Store boot lifecycle.
+   */
+  readonly otel: StoreOtel
+
+  /**
+   * The Store's reactive graph instance used to model dependencies and
+   * propagate updates. Provides APIs to create refs/thunks/effects and to
+   * subscribe to refresh cycles.
+   */
+  readonly reactivityGraph: ReactivityGraph
+
+  /**
+   * Per‑table reactive refs used to broadcast invalidations when materializers
+   * write to tables. Values are always `null`; equality is intentionally
+   * `false` to force recomputation.
+   *
+   * Keys are SQLite table names (user tables; some system tables may be
+   * intentionally excluded from refresh).
+   */
+  readonly tableRefs: Readonly<Record<string, Ref<null, ReactivityGraphContext, RefreshReason>>>
+
+  /**
+   * Set of currently subscribed LiveQuery instances (reference‑counted).
+   * Used for Devtools and diagnostics.
+   */
+  readonly activeQueries: ReferenceCountedSet<LiveQuery<any>>
+
+  /**
+   * Client‑session sync processor orchestrating push/pull and materialization
+   * of events into local state.
+   */
+  readonly syncProcessor: ClientSessionSyncProcessor
+
+  /**
+   * Starts background fibers for sync and observation. Must be run exactly
+   * once per Store instance. Scoped; installs finalizers to end spans and
+   * detach reactive refs.
+   */
+  readonly boot: Effect.Effect<void, UnexpectedError, Scope.Scope>
+
+  /**
+   * Tracks whether the Store has been shut down. When true, mutating APIs
+   * should reject via `checkShutdown`.
+   */
+  isShutdown: boolean
+}
+
 export type StoreOptions<TSchema extends LiveStoreSchema = LiveStoreSchema.Any, TContext = {}> = {
   clientSession: ClientSession
   schema: TSchema