@livestore/livestore 0.0.0-snapshot-8edfbb590201c0bff6943d89f2ebc3d5ba1a09b0 → 0.0.0-snapshot-6788a4cf00171a177a3a1e59cefc10f5bad71049

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/db-query.test.ts

@@ -289,6 +289,53 @@ 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)
+
+        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()
+        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/mod.ts

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

package/src/store/store-types.ts

@@ -14,6 +14,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 } 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 +136,12 @@ 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
+}

package/src/store/store.ts

@@ -52,16 +52,21 @@ 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 {
   RefreshReason,
   StoreCommitOptions,
   StoreEventsOptions,
   StoreOptions,
   StoreOtel,
+  SubscribeOptions,
   Unsubscribe,
 } from './store-types.ts'
 
+type SubscribeQuery<TResult> =
+  | LiveQueryDef<TResult, 'def' | 'signal-def'>
+  | LiveQuery<TResult>
+  | QueryBuilder<TResult, any, any>
+
 if (isDevEnv()) {
   exposeDebugUtils()
 }
@@ -349,98 +354,125 @@ 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$, (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>,
-    /** Called when the query result has changed */
-    onUpdate: (value: TResult) => void,
-    options?: {
-      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
-    },
-  ): Unsubscribe => {
-    this.checkShutdown('subscribe')
+  subscribe: {
+    <TResult>(
+      query: SubscribeQuery<TResult>,
+      onUpdate: (value: TResult) => void,
+      options?: SubscribeOptions<TResult>,
+    ): Unsubscribe
+    <TResult>(query: SubscribeQuery<TResult>, options?: SubscribeOptions<TResult>): AsyncIterableIterator<TResult>
+  } = <TResult>(
+    query: SubscribeQuery<TResult>,
+    onUpdateOrOptions?: ((value: TResult) => void) | SubscribeOptions<TResult>,
+    maybeOptions?: SubscribeOptions<TResult>,
+  ): Unsubscribe | AsyncIterableIterator<TResult> => {
+    if (typeof onUpdateOrOptions === 'function') {
+      const onUpdate = onUpdateOrOptions
+      const options = maybeOptions
+
+      this.checkShutdown('subscribe')
+
+      return this.otel.tracer.startActiveSpan(
+        `LiveStore.subscribe`,
+        { 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)
+            ? queryDb(query).make(this.reactivityGraph.context!)
+            : query._tag === 'def' || query._tag === 'signal-def'
+              ? query.make(this.reactivityGraph.context!)
+              : {
+                  value: query as LiveQuery<TResult>,
+                  deref: () => {},
+                }
+          const query$ = queryRcRef.value
 
-    return this.otel.tracer.startActiveSpan(
-      `LiveStore.subscribe`,
-      { 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 label = `subscribe:${options?.label}`
+          const effect = this.reactivityGraph.makeEffect(
+            (get, _otelContext, debugRefreshReason) => onUpdate(get(query$.results$, otelContext, debugRefreshReason)),
+            { label },
+          )
 
-        const queryRcRef = isQueryBuilder(query)
-          ? queryDb(query).make(this.reactivityGraph.context!)
-          : query._tag === 'def' || query._tag === 'signal-def'
-            ? query.make(this.reactivityGraph.context!)
-            : {
-                value: query as LiveQuery<TResult>,
-                deref: () => {},
-              }
-        const query$ = queryRcRef.value
+          if (options?.stackInfo) {
+            query$.activeSubscriptions.add(options.stackInfo)
+          }
 
-        const label = `subscribe:${options?.label}`
-        const effect = this.reactivityGraph.makeEffect(
-          (get, _otelContext, debugRefreshReason) => onUpdate(get(query$.results$, otelContext, debugRefreshReason)),
-          { label },
-        )
+          options?.onSubscribe?.(query$)
 
-        if (options?.stackInfo) {
-          query$.activeSubscriptions.add(options.stackInfo)
-        }
+          this.activeQueries.add(query$ as LiveQuery<TResult>)
 
-        options?.onSubscribe?.(query$)
+          // 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}`,
+            })
+          }
 
-        this.activeQueries.add(query$ as LiveQuery<TResult>)
+          const unsubscribe = () => {
+            // console.debug('store unsub', query$.id, query$.label)
+            try {
+              this.reactivityGraph.destroyNode(effect)
+              this.activeQueries.remove(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}` })
-        }
+              if (options?.stackInfo) {
+                query$.activeSubscriptions.delete(options.stackInfo)
+              }
 
-        const unsubscribe = () => {
-          // console.debug('store unsub', query$.id, query$.label)
-          try {
-            this.reactivityGraph.destroyNode(effect)
-            this.activeQueries.remove(query$ as LiveQuery<TResult>)
+              queryRcRef.deref()
 
-            if (options?.stackInfo) {
-              query$.activeSubscriptions.delete(options.stackInfo)
+              options?.onUnsubsubscribe?.()
+            } finally {
+              span.end()
             }
+          }
+
+          return unsubscribe
+        },
+      )
+    }
 
-            queryRcRef.deref()
+    return this.subscribeAsAsyncIterator(query, onUpdateOrOptions)
+  }
 
-            options?.onUnsubsubscribe?.()
-          } finally {
-            span.end()
-          }
-        }
+  private subscribeAsAsyncIterator = <TResult>(
+    query: SubscribeQuery<TResult>,
+    options?: SubscribeOptions<TResult>,
+  ): AsyncIterableIterator<TResult> => {
+    this.checkShutdown('subscribe')
+
+    const iterator = Stream.toAsyncIterable(this.subscribeStream(query, options))[Symbol.asyncIterator]()
 
-        return unsubscribe
+    return Object.assign(iterator, {
+      [Symbol.asyncIterator]() {
+        return this
       },
-    )
+    })
   }
 
   subscribeStream = <TResult>(
-    query$: LiveQueryDef<TResult>,
-    options?: { label?: string; skipInitialRun?: boolean } | undefined,
+    query: SubscribeQuery<TResult>,
+    options?: SubscribeOptions<TResult>,
   ): Stream.Stream<TResult> =>
     Stream.asyncPush<TResult>((emit) =>
       Effect.gen(this, function* () {
@@ -451,11 +483,10 @@ export class Store<TSchema extends LiveStoreSchema = LiveStoreSchema.Any, TConte
 
         yield* Effect.acquireRelease(
           Effect.sync(() =>
-            this.subscribe(
-              query$,
-              (result) => emit.single(result),
-              omitUndefineds({ otelContext, label: options?.label }),
-            ),
+            this.subscribe(query, (result) => emit.single(result), {
+              ...(options ?? {}),
+              otelContext,
+            }),
           ),
           (unsub) => Effect.sync(() => unsub()),
         )