@livestore/livestore 0.4.0-dev.10 → 0.4.0-dev.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livestore/livestore",
-  "version": "0.4.0-dev.10",
+  "version": "0.4.0-dev.12",
   "type": "module",
   "sideEffects": false,
   "exports": {
@@ -11,8 +11,8 @@
   },
   "dependencies": {
     "@opentelemetry/api": "1.9.0",
-    "@livestore/utils": "0.4.0-dev.10",
-    "@livestore/common": "0.4.0-dev.10"
+    "@livestore/common": "0.4.0-dev.12",
+    "@livestore/utils": "0.4.0-dev.12"
   },
   "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/adapter-web": "0.4.0-dev.10",
-    "@livestore/utils-dev": "0.4.0-dev.10"
+    "@livestore/utils-dev": "0.4.0-dev.12",
+    "@livestore/adapter-web": "0.4.0-dev.12"
   },
   "files": [
     "package.json",

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

@@ -1,5 +1,92 @@
 // Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
 
+exports[`otel > QueryBuilder subscription - async iterator 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 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",

package/src/live-queries/base-class.ts

@@ -166,10 +166,13 @@ export abstract class LiveStoreQueryBase<TResult> implements LiveQuery<TResult>
 
   // subscribe = (
   //   onNewValue: (value: TResult) => void,
-  //   onUnsubsubscribe?: () => void,
-  //   options?: { label?: string; otelContext?: otel.Context } | undefined,
+  //   options?: {
+  //     label?: string
+  //     otelContext?: otel.Context
+  //     onUnsubsubscribe?: () => void
+  //   },
   // ): (() => void) =>
-  //   this.reactivityGraph.context?.store.subscribe(this, onNewValue, onUnsubsubscribe, options) ??
+  //   this.reactivityGraph.context?.store.subscribe(this, onNewValue, options) ??
   //   RG.throwContextNotSetError(this.reactivityGraph)
 }
 

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

@@ -2,7 +2,7 @@ import { Effect, ReadonlyRecord, Schema } from '@livestore/utils/effect'
 import { Vitest } from '@livestore/utils-dev/node-vitest'
 import * as otel from '@opentelemetry/api'
 import { BasicTracerProvider, InMemorySpanExporter, SimpleSpanProcessor } from '@opentelemetry/sdk-trace-base'
-import { expect } from 'vitest'
+import { assert, expect } from 'vitest'
 
 import * as RG from '../reactive.ts'
 import { events, makeTodoMvc, tables } from '../utils/tests/fixture.ts'
@@ -204,10 +204,8 @@ Vitest.describe('otel', () => {
         .where({ completed: false })
         .first({ behaviour: 'fallback', fallback: () => defaultTodo })
 
-      const unsubscribe = store.subscribe(queryBuilder, {
-        onUpdate: (result) => {
-          callbackResults.push(result)
-        },
+      const unsubscribe = store.subscribe(queryBuilder, (result) => {
+        callbackResults.push(result)
       })
 
       expect(callbackResults).toHaveLength(1)
@@ -251,16 +249,12 @@ Vitest.describe('otel', () => {
         .where({ completed: false })
         .first({ behaviour: 'fallback', fallback: () => defaultTodo })
 
-      const unsubscribe1 = store.subscribe(queryBuilder, {
-        onUpdate: (result) => {
-          callbackResults1.push(result)
-        },
+      const unsubscribe1 = store.subscribe(queryBuilder, (result) => {
+        callbackResults1.push(result)
       })
 
-      const unsubscribe2 = store.subscribe(queryBuilder, {
-        onUpdate: (result) => {
-          callbackResults2.push(result)
-        },
+      const unsubscribe2 = store.subscribe(queryBuilder, (result) => {
+        callbackResults2.push(result)
       })
 
       expect(callbackResults1).toHaveLength(1)
@@ -295,16 +289,62 @@ Vitest.describe('otel', () => {
     ),
   )
 
+  Vitest.scopedLive('QueryBuilder subscription - async iterator', () =>
+    Effect.gen(function* () {
+      const { store, exporter, span, provider } = yield* makeQuery
+
+      const defaultTodo = { 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)[Symbol.asyncIterator]()
+
+        const initial = await iterator.next()
+        expect(initial.done).toBe(false)
+        expect(initial.value).toMatchObject(defaultTodo)
+
+        store.commit(events.todoCreated({ id: 't-async', text: 'write tests', completed: false }))
+
+        const update = await iterator.next()
+        expect(update.done).toBe(false)
+        expect(update.value).toMatchObject({
+          id: 't-async',
+          text: 'write tests',
+          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
 
       const callbackResults: any[] = []
 
-      const unsubscribe = store.subscribe(tables.todos, {
-        onUpdate: (result) => {
-          callbackResults.push(result)
-        },
+      const unsubscribe = store.subscribe(tables.todos, (result) => {
+        callbackResults.push(result)
       })
 
       expect(callbackResults).toHaveLength(1)

package/src/mod.ts

@@ -37,7 +37,14 @@ 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, QueryDebugInfo, RefreshReason, Unsubscribe } from './store/store-types.ts'
+export type {
+  OtelOptions,
+  Queryable,
+  QueryDebugInfo,
+  RefreshReason,
+  SubscribeOptions,
+  Unsubscribe,
+} from './store/store-types.ts'
 export {
   type LiveStoreContext,
   type LiveStoreContextRunning,

package/src/store/store-types.ts

@@ -5,6 +5,7 @@ import type {
   InvalidPullError,
   IsOfflineError,
   MaterializeError,
+  QueryBuilder,
   StoreInterrupted,
   SyncError,
   UnexpectedError,
@@ -14,6 +15,7 @@ import type { Effect, Runtime, Scope } from '@livestore/utils/effect'
 import { Deferred } from '@livestore/utils/effect'
 import type * as otel from '@opentelemetry/api'
 
+import type { LiveQuery, LiveQueryDef, SignalDef } from '../live-queries/base-class.ts'
 import type { DebugRefreshReasonBase } from '../reactive.ts'
 import type { StackInfo } from '../utils/stack-info.ts'
 import type { Store } from './store.ts'
@@ -135,3 +137,19 @@ export type StoreEventsOptions<TSchema extends LiveStoreSchema> = {
 }
 
 export type Unsubscribe = () => void
+
+export type SubscribeOptions<TResult> = {
+  onSubscribe?: (query$: LiveQuery<TResult>) => void
+  onUnsubsubscribe?: () => void
+  label?: string
+  skipInitialRun?: boolean
+  otelContext?: otel.Context
+  stackInfo?: StackInfo
+}
+
+/** All query definitions or instances the store can execute or subscribe to. */
+export type Queryable<TResult> =
+  | LiveQueryDef<TResult>
+  | SignalDef<TResult>
+  | LiveQuery<TResult>
+  | QueryBuilder<TResult, any, any>

package/src/store/store.ts

@@ -14,7 +14,6 @@ import {
   makeClientSessionSyncProcessor,
   type PreparedBindValues,
   prepareBindValues,
-  type QueryBuilder,
   QueryBuilderAstSymbol,
   replaceSessionIdSymbol,
   UnexpectedError,
@@ -38,13 +37,7 @@ import {
 import { nanoid } from '@livestore/utils/nanoid'
 import * as otel from '@opentelemetry/api'
 
-import type {
-  LiveQuery,
-  LiveQueryDef,
-  ReactivityGraph,
-  ReactivityGraphContext,
-  SignalDef,
-} from '../live-queries/base-class.ts'
+import type { LiveQuery, ReactivityGraph, ReactivityGraphContext, SignalDef } from '../live-queries/base-class.ts'
 import { makeReactivityGraph } from '../live-queries/base-class.ts'
 import { makeExecBeforeFirstRun } from '../live-queries/client-document-get-query.ts'
 import { queryDb } from '../live-queries/db-query.ts'
@@ -52,16 +45,26 @@ import type { Ref } from '../reactive.ts'
 import { SqliteDbWrapper } from '../SqliteDbWrapper.ts'
 import { ReferenceCountedSet } from '../utils/data-structures.ts'
 import { downloadBlob, exposeDebugUtils } from '../utils/dev.ts'
-import type { StackInfo } from '../utils/stack-info.ts'
 import type {
+  Queryable,
   RefreshReason,
   StoreCommitOptions,
   StoreEventsOptions,
   StoreOptions,
   StoreOtel,
+  SubscribeOptions,
   Unsubscribe,
 } from './store-types.ts'
 
+type SubscribeFn = {
+  <TResult>(
+    query: Queryable<TResult>,
+    onUpdate: (value: TResult) => void,
+    options?: SubscribeOptions<TResult>,
+  ): Unsubscribe
+  <TResult>(query: Queryable<TResult>, options?: SubscribeOptions<TResult>): AsyncIterable<TResult>
+}
+
 if (isDevEnv()) {
   exposeDebugUtils()
 }
@@ -349,32 +352,39 @@ export class Store<TSchema extends LiveStoreSchema = LiveStoreSchema.Any, TConte
   }
 
   /**
-   * Subscribe to the results of a query
-   * Returns a function to cancel the subscription.
+   * Subscribe to the results of a query.
+   *
+   * - When providing an `onUpdate` callback it returns an {@link Unsubscribe} function.
+   * - Without a callback it returns an {@link AsyncIterable} that yields query results.
    *
    * @example
    * ```ts
-   * const unsubscribe = store.subscribe(query$, { onUpdate: (result) => console.log(result) })
+   * const unsubscribe = store.subscribe(query$, (result) => console.log(result))
+   * ```
+   *
+   * @example
+   * ```ts
+   * for await (const result of store.subscribe(query$)) {
+   *   console.log(result)
+   * }
    * ```
    */
-  subscribe = <TResult>(
-    query: LiveQueryDef<TResult, 'def' | 'signal-def'> | LiveQuery<TResult> | QueryBuilder<TResult, any, any>,
-    options: {
-      /** Called when the query result has changed */
-      onUpdate: (value: TResult) => void
-      onSubscribe?: (query$: LiveQuery<TResult>) => void
-      /** Gets called after the query subscription has been removed */
-      onUnsubsubscribe?: () => void
-      label?: string
-      /**
-       * Skips the initial `onUpdate` callback
-       * @default false
-       */
-      skipInitialRun?: boolean
-      otelContext?: otel.Context
-      /** If provided, the stack info will be added to the `activeSubscriptions` set of the query */
-      stackInfo?: StackInfo
-    },
+  subscribe = (<TResult>(
+    query: Queryable<TResult>,
+    onUpdateOrOptions?: ((value: TResult) => void) | SubscribeOptions<TResult>,
+    maybeOptions?: SubscribeOptions<TResult>,
+  ): Unsubscribe | AsyncIterable<TResult> => {
+    if (typeof onUpdateOrOptions === 'function') {
+      return this.subscribeWithCallback(query, onUpdateOrOptions, maybeOptions)
+    }
+
+    return this.subscribeAsAsyncIterable(query, onUpdateOrOptions)
+  }) as SubscribeFn
+
+  private subscribeWithCallback = <TResult>(
+    query: Queryable<TResult>,
+    onUpdate: (value: TResult) => void,
+    options?: SubscribeOptions<TResult>,
   ): Unsubscribe => {
     this.checkShutdown('subscribe')
 
@@ -383,7 +393,6 @@ export class Store<TSchema extends LiveStoreSchema = LiveStoreSchema.Any, TConte
       { attributes: { label: options?.label, queryLabel: isQueryBuilder(query) ? query.toString() : query.label } },
       options?.otelContext ?? this.otel.queriesSpanContext,
       (span) => {
-        // console.debug('store sub', query$.id, query$.label)
         const otelContext = otel.trace.setSpan(otel.context.active(), span)
 
         const queryRcRef = isQueryBuilder(query)
@@ -398,8 +407,7 @@ export class Store<TSchema extends LiveStoreSchema = LiveStoreSchema.Any, TConte
 
         const label = `subscribe:${options?.label}`
         const effect = this.reactivityGraph.makeEffect(
-          (get, _otelContext, debugRefreshReason) =>
-            options.onUpdate(get(query$.results$, otelContext, debugRefreshReason)),
+          (get, _otelContext, debugRefreshReason) => onUpdate(get(query$.results$, otelContext, debugRefreshReason)),
           { label },
         )
 
@@ -411,13 +419,14 @@ export class Store<TSchema extends LiveStoreSchema = LiveStoreSchema.Any, TConte
 
         this.activeQueries.add(query$ as LiveQuery<TResult>)
 
-        // Running effect right away to get initial value (unless `skipInitialRun` is set)
         if (options?.skipInitialRun !== true && !query$.isDestroyed) {
-          effect.doEffect(otelContext, { _tag: 'subscribe.initial', label: `subscribe-initial-run:${options?.label}` })
+          effect.doEffect(otelContext, {
+            _tag: 'subscribe.initial',
+            label: `subscribe-initial-run:${options?.label}`,
+          })
         }
 
         const unsubscribe = () => {
-          // console.debug('store unsub', query$.id, query$.label)
           try {
             this.reactivityGraph.destroyNode(effect)
             this.activeQueries.remove(query$ as LiveQuery<TResult>)
@@ -439,10 +448,16 @@ export class Store<TSchema extends LiveStoreSchema = LiveStoreSchema.Any, TConte
     )
   }
 
-  subscribeStream = <TResult>(
-    query$: LiveQueryDef<TResult>,
-    options?: { label?: string; skipInitialRun?: boolean } | undefined,
-  ): Stream.Stream<TResult> =>
+  private subscribeAsAsyncIterable = <TResult>(
+    query: Queryable<TResult>,
+    options?: SubscribeOptions<TResult>,
+  ): AsyncIterable<TResult> => {
+    this.checkShutdown('subscribe')
+
+    return Stream.toAsyncIterable(this.subscribeStream(query, options))
+  }
+
+  subscribeStream = <TResult>(query: Queryable<TResult>, options?: SubscribeOptions<TResult>): Stream.Stream<TResult> =>
     Stream.asyncPush<TResult>((emit) =>
       Effect.gen(this, function* () {
         const otelSpan = yield* OtelTracer.currentOtelSpan.pipe(
@@ -452,9 +467,9 @@ export class Store<TSchema extends LiveStoreSchema = LiveStoreSchema.Any, TConte
 
         yield* Effect.acquireRelease(
           Effect.sync(() =>
-            this.subscribe(query$, {
-              onUpdate: (result) => emit.single(result),
-              ...omitUndefineds({ otelContext, label: options?.label }),
+            this.subscribe(query, (result) => emit.single(result), {
+              ...(options ?? {}),
+              otelContext,
             }),
           ),
           (unsub) => Effect.sync(() => unsub()),
@@ -477,12 +492,7 @@ export class Store<TSchema extends LiveStoreSchema = LiveStoreSchema.Any, TConte
    * ```
    */
   query = <TResult>(
-    query:
-      | QueryBuilder<TResult, any, any>
-      | LiveQuery<TResult>
-      | LiveQueryDef<TResult>
-      | SignalDef<TResult>
-      | { query: string; bindValues: Bindable; schema?: Schema.Schema<TResult> },
+    query: Queryable<TResult> | { query: string; bindValues: Bindable; schema?: Schema.Schema<TResult> },
     options?: { otelContext?: otel.Context; debugRefreshReason?: RefreshReason },
   ): TResult => {
     this.checkShutdown('query')
@@ -847,7 +857,7 @@ export class Store<TSchema extends LiveStoreSchema = LiveStoreSchema.Any, TConte
     syncStates: () =>
       Effect.gen(this, function* () {
         const session = yield* this.syncProcessor.syncState
-        const leader = yield* this.clientSession.leaderThread.getSyncState
+        const leader = yield* this.clientSession.leaderThread.syncState
         return { session, leader }
       }).pipe(this.runEffectPromise),
 
@@ -858,7 +868,7 @@ export class Store<TSchema extends LiveStoreSchema = LiveStoreSchema.Any, TConte
           `Session sync state: ${session.localHead} (upstream: ${session.upstreamHead})`,
           session.toJSON(),
         )
-        const leader = yield* this.clientSession.leaderThread.getSyncState
+        const leader = yield* this.clientSession.leaderThread.syncState
         yield* Effect.log(`Leader sync state: ${leader.localHead} (upstream: ${leader.upstreamHead})`, leader.toJSON())
       }).pipe(this.runEffectFork)
     },