@livestore/livestore 0.4.0-dev.16 → 0.4.0-dev.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livestore/livestore",
-  "version": "0.4.0-dev.16",
+  "version": "0.4.0-dev.18",
   "type": "module",
   "sideEffects": false,
   "exports": {
@@ -11,8 +11,8 @@
   },
   "dependencies": {
     "@opentelemetry/api": "1.9.0",
-    "@livestore/common": "0.4.0-dev.16",
-    "@livestore/utils": "0.4.0-dev.16"
+    "@livestore/common": "0.4.0-dev.18",
+    "@livestore/utils": "0.4.0-dev.18"
   },
   "devDependencies": {
     "@opentelemetry/sdk-trace-base": "^2.0.1",
@@ -20,8 +20,8 @@
     "typescript": "5.9.2",
     "vite": "7.1.7",
     "vitest": "3.2.4",
-    "@livestore/utils-dev": "0.4.0-dev.16",
-    "@livestore/adapter-web": "0.4.0-dev.16"
+    "@livestore/utils-dev": "0.4.0-dev.18",
+    "@livestore/adapter-web": "0.4.0-dev.18"
   },
   "files": [
     "package.json",

package/src/SqliteDbWrapper.test.ts

@@ -1,7 +1,7 @@
 import { Effect } from '@livestore/utils/effect'
 import { Vitest } from '@livestore/utils-dev/node-vitest'
 import { expect } from 'vitest'
-
+import { StoreInternalsSymbol } from './store/store-types.ts'
 import { makeTodoMvc } from './utils/tests/fixture.ts'
 
 Vitest.describe('SqliteDbWrapper', () => {
@@ -9,7 +9,7 @@ Vitest.describe('SqliteDbWrapper', () => {
     const getTablesUsed = (query: string) =>
       Effect.gen(function* () {
         const store = yield* makeTodoMvc({})
-        return store.sqliteDbWrapper.getTablesUsed(query)
+        return store[StoreInternalsSymbol].sqliteDbWrapper.getTablesUsed(query)
       })
 
     Vitest.scopedLive('should return the correct tables used', (_test) =>

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

@@ -87,6 +87,93 @@ exports[`otel > QueryBuilder subscription - async iterator 2`] = `
 ]
 `;
 
+exports[`otel > QueryBuilder subscription - async iterator with skipInitialRun 1`] = `
+{
+  "_name": "createStore",
+  "attributes": {
+    "debugInstanceId": "test",
+    "storeId": "default",
+  },
+  "children": [
+    {
+      "_name": "livestore.in-memory-db:execute",
+      "attributes": {
+        "sql.query": "
+      PRAGMA page_size=32768;
+      PRAGMA cache_size=10000;
+      PRAGMA synchronous='OFF';
+      PRAGMA temp_store='MEMORY';
+      PRAGMA foreign_keys='ON'; -- we want foreign key constraints to be enforced
+    ",
+      },
+    },
+    {
+      "_name": "@livestore/common:LeaderSyncProcessor:push",
+      "attributes": {
+        "batch": "undefined",
+        "batchSize": 1,
+      },
+    },
+    {
+      "_name": "client-session-sync-processor:pull",
+      "attributes": {
+        "code.stacktrace": "<STACKTRACE>",
+        "span.label": "⚠︎ Interrupted",
+        "status.interrupted": true,
+      },
+    },
+    {
+      "_name": "LiveStore:sync",
+    },
+    {
+      "_name": "LiveStore:commits",
+    },
+    {
+      "_name": "LiveStore:queries",
+    },
+  ],
+}
+`;
+
+exports[`otel > QueryBuilder subscription - async iterator with skipInitialRun 2`] = `
+[
+  {
+    "_name": "LiveStore:commit",
+    "attributes": {
+      "livestore.eventTags": "[
+  "todo.created"
+]",
+      "livestore.eventsCount": 1,
+    },
+    "children": [
+      {
+        "_name": "client-session-sync-processor:push",
+        "attributes": {
+          "batchSize": 1,
+          "eventCounts": "{
+  "todo.created": 1
+}",
+          "mergeResultTag": "advance",
+        },
+        "children": [
+          {
+            "_name": "client-session-sync-processor:materialize-event",
+            "children": [
+              {
+                "_name": "livestore.in-memory-db:execute",
+                "attributes": {
+                  "sql.query": "INSERT INTO 'todos' (id, text, completed) VALUES (?, ?, ?)",
+                },
+              },
+            ],
+          },
+        ],
+      },
+    ],
+  },
+]
+`;
+
 exports[`otel > QueryBuilder subscription - basic functionality 1`] = `
 {
   "_name": "createStore",
@@ -353,6 +440,139 @@ exports[`otel > QueryBuilder subscription - direct table subscription 2`] = `
 ]
 `;
 
+exports[`otel > QueryBuilder subscription - skipInitialRun 1`] = `
+{
+  "_name": "createStore",
+  "attributes": {
+    "debugInstanceId": "test",
+    "storeId": "default",
+  },
+  "children": [
+    {
+      "_name": "livestore.in-memory-db:execute",
+      "attributes": {
+        "sql.query": "
+      PRAGMA page_size=32768;
+      PRAGMA cache_size=10000;
+      PRAGMA synchronous='OFF';
+      PRAGMA temp_store='MEMORY';
+      PRAGMA foreign_keys='ON'; -- we want foreign key constraints to be enforced
+    ",
+      },
+    },
+    {
+      "_name": "@livestore/common:LeaderSyncProcessor:push",
+      "attributes": {
+        "batch": "undefined",
+        "batchSize": 1,
+      },
+    },
+    {
+      "_name": "client-session-sync-processor:pull",
+      "attributes": {
+        "code.stacktrace": "<STACKTRACE>",
+        "span.label": "⚠︎ Interrupted",
+        "status.interrupted": true,
+      },
+    },
+    {
+      "_name": "LiveStore:sync",
+    },
+    {
+      "_name": "LiveStore:commits",
+    },
+    {
+      "_name": "LiveStore:queries",
+      "children": [
+        {
+          "_name": "LiveStore.subscribe",
+          "attributes": {
+            "queryLabel": "SELECT * FROM 'todos' WHERE completed = ? LIMIT ?",
+          },
+          "children": [
+            {
+              "_name": "db:SELECT * FROM 'todos' WHERE completed = ? LIMIT ?",
+              "attributes": {
+                "livestore.debugRefreshReason": "subscribe-initial-run:undefined",
+                "sql.query": "SELECT * FROM 'todos' WHERE completed = ? LIMIT ?",
+                "sql.rowsCount": 0,
+              },
+              "children": [
+                {
+                  "_name": "sql-in-memory-select",
+                  "attributes": {
+                    "sql.cached": false,
+                    "sql.query": "SELECT * FROM 'todos' WHERE completed = ? LIMIT ?",
+                    "sql.rowsCount": 0,
+                  },
+                },
+              ],
+            },
+            {
+              "_name": "db:SELECT * FROM 'todos' WHERE completed = ? LIMIT ?",
+              "attributes": {
+                "livestore.debugRefreshReason": "commit",
+                "sql.query": "SELECT * FROM 'todos' WHERE completed = ? LIMIT ?",
+                "sql.rowsCount": 1,
+              },
+              "children": [
+                {
+                  "_name": "sql-in-memory-select",
+                  "attributes": {
+                    "sql.cached": false,
+                    "sql.query": "SELECT * FROM 'todos' WHERE completed = ? LIMIT ?",
+                    "sql.rowsCount": 1,
+                  },
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    },
+  ],
+}
+`;
+
+exports[`otel > QueryBuilder subscription - skipInitialRun 2`] = `
+[
+  {
+    "_name": "LiveStore:commit",
+    "attributes": {
+      "livestore.eventTags": "[
+  "todo.created"
+]",
+      "livestore.eventsCount": 1,
+    },
+    "children": [
+      {
+        "_name": "client-session-sync-processor:push",
+        "attributes": {
+          "batchSize": 1,
+          "eventCounts": "{
+  "todo.created": 1
+}",
+          "mergeResultTag": "advance",
+        },
+        "children": [
+          {
+            "_name": "client-session-sync-processor:materialize-event",
+            "children": [
+              {
+                "_name": "livestore.in-memory-db:execute",
+                "attributes": {
+                  "sql.query": "INSERT INTO 'todos' (id, text, completed) VALUES (?, ?, ?)",
+                },
+              },
+            ],
+          },
+        ],
+      },
+    ],
+  },
+]
+`;
+
 exports[`otel > QueryBuilder subscription - unsubscribe functionality 1`] = `
 {
   "_name": "createStore",

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,7 +5,8 @@ import { BasicTracerProvider, InMemorySpanExporter, SimpleSpanProcessor } from '
 import { assert, expect } from 'vitest'
 
 import * as RG from '../reactive.ts'
-import { events, makeTodoMvc, tables } from '../utils/tests/fixture.ts'
+import { StoreInternalsSymbol } from '../store/store-types.ts'
+import { events, makeTodoMvc, type Todo, tables } from '../utils/tests/fixture.ts'
 import { getAllSimplifiedRootSpans, getSimplifiedRootSpan } from '../utils/tests/otel.ts'
 import { computed } from './computed.ts'
 import { queryDb } from './db-query.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()
 
@@ -237,6 +238,53 @@ Vitest.describe('otel', () => {
     ),
   )
 
+  Vitest.scopedLive('QueryBuilder subscription - skipInitialRun', () =>
+    Effect.gen(function* () {
+      const { store, exporter, span, provider } = yield* makeQuery
+
+      const callbackResults: Todo[] = []
+      const defaultTodo: Todo = { id: '', text: '', completed: false }
+
+      const queryBuilder = tables.todos
+        .where({ completed: false })
+        .first({ behaviour: 'fallback', fallback: () => defaultTodo })
+
+      const unsubscribe = store.subscribe(
+        queryBuilder,
+        (result) => {
+          callbackResults.push(result)
+        },
+        { skipInitialRun: true },
+      )
+
+      expect(callbackResults).toHaveLength(0)
+
+      store.commit(events.todoCreated({ id: 't-skip', text: 'skip initial', completed: false }))
+
+      expect(callbackResults).toHaveLength(1)
+      expect(callbackResults[0]).toMatchObject({
+        id: 't-skip',
+        text: 'skip initial',
+        completed: false,
+      })
+
+      unsubscribe()
+      span.end()
+
+      return { exporter, provider }
+    }).pipe(
+      Effect.scoped,
+      Effect.tap(({ exporter, provider }) =>
+        Effect.promise(async () => {
+          await provider.forceFlush()
+          expect(getSimplifiedRootSpan(exporter, 'createStore', mapAttributes)).toMatchSnapshot()
+          expect(getAllSimplifiedRootSpans(exporter, 'LiveStore:commit', mapAttributes)).toMatchSnapshot()
+          await provider.shutdown()
+        }),
+      ),
+    ),
+  )
+
   Vitest.scopedLive('QueryBuilder subscription - unsubscribe functionality', () =>
     Effect.gen(function* () {
       const { store, exporter, span, provider } = yield* makeQuery
@@ -293,7 +341,7 @@ Vitest.describe('otel', () => {
     Effect.gen(function* () {
       const { store, exporter, span, provider } = yield* makeQuery
 
-      const defaultTodo = { id: '', text: '', completed: false }
+      const defaultTodo: Todo = { id: '', text: '', completed: false }
 
       const queryBuilder = tables.todos
         .where({ completed: false })
@@ -337,6 +385,55 @@ Vitest.describe('otel', () => {
     ),
   )
 
+  Vitest.scopedLive('QueryBuilder subscription - async iterator with skipInitialRun', () =>
+    Effect.gen(function* () {
+      const { store, exporter, span, provider } = yield* makeQuery
+
+      const defaultTodo: Todo = { id: '', text: '', completed: false }
+
+      const queryBuilder = tables.todos
+        .where({ completed: false })
+        .first({ behaviour: 'fallback', fallback: () => defaultTodo })
+
+      yield* Effect.promise(async () => {
+        const iterator = store.subscribe(queryBuilder, { skipInitialRun: true })[Symbol.asyncIterator]()
+
+        const pending = Symbol('pending')
+        const nextPromise = iterator.next()
+        const raceResult = await Promise.race([nextPromise, Promise.resolve(pending)])
+        expect(raceResult).toBe(pending)
+
+        store.commit(events.todoCreated({ id: 't-async-skip', text: 'write tests later', completed: false }))
+
+        const update = await nextPromise
+        expect(update.done).toBe(false)
+        expect(update.value).toMatchObject({
+          id: 't-async-skip',
+          text: 'write tests later',
+          completed: false,
+        })
+
+        const doneResult = await iterator.return?.()
+        assert(doneResult)
+        expect(doneResult.done).toBe(true)
+      })
+
+      span.end()
+
+      return { exporter, provider }
+    }).pipe(
+      Effect.scoped,
+      Effect.tap(({ exporter, provider }) =>
+        Effect.promise(async () => {
+          await provider.forceFlush()
+          expect(getSimplifiedRootSpan(exporter, 'createStore', mapAttributes)).toMatchSnapshot()
+          expect(getAllSimplifiedRootSpans(exporter, 'LiveStore:commit', mapAttributes)).toMatchSnapshot()
+          await provider.shutdown()
+        }),
+      ),
+    ),
+  )
+
   Vitest.scopedLive('QueryBuilder subscription - direct table subscription', () =>
     Effect.gen(function* () {
       const { store, exporter, span, provider } = yield* makeQuery

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

@@ -41,6 +41,7 @@ import type {
   OtelOptions,
   ShutdownDeferred,
 } from './store-types.ts'
+import { StoreInternalsSymbol } from './store-types.ts'
 
 export const DEFAULT_PARAMS = {
   leaderPushBatchSize: 100,
@@ -346,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`
@@ -364,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)