@livestore/livestore 0.4.0-dev.9 → 0.5.0-dev.0

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

@@ -1,11 +1,13 @@
-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 { Vitest } from '@livestore/utils-dev/node-vitest'
+import { Effect, ReadonlyRecord, Schema } from '@livestore/utils/effect'
 
 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'
@@ -52,7 +54,7 @@ Vitest.describe('otel', () => {
     }
   })
 
-  Vitest.scopedLive('otel', () =>
+  Vitest.live('otel', () =>
     Effect.gen(function* () {
       const { store, exporter, span, provider } = yield* makeQuery
 
@@ -91,7 +93,7 @@ Vitest.describe('otel', () => {
     ),
   )
 
-  Vitest.scopedLive('with thunks', () =>
+  Vitest.live('with thunks', () =>
     Effect.gen(function* () {
       const { store, exporter, span, provider } = yield* makeQuery
 
@@ -106,7 +108,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 +118,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 +132,7 @@ Vitest.describe('otel', () => {
       }
     `)
 
-      expect(store.reactivityGraph.getSnapshot({ includeResults: true })).toMatchSnapshot()
+      expect(store[StoreInternalsSymbol].reactivityGraph.getSnapshot({ includeResults: true })).toMatchSnapshot()
 
       span.end()
 
@@ -148,7 +150,7 @@ Vitest.describe('otel', () => {
     ),
   )
 
-  Vitest.scopedLive('with thunks with query builder and without labels', () =>
+  Vitest.live('with thunks with query builder and without labels', () =>
     Effect.gen(function* () {
       const { store, exporter, span, provider } = yield* makeQuery
 
@@ -193,7 +195,7 @@ Vitest.describe('otel', () => {
     ),
   )
 
-  Vitest.scopedLive('QueryBuilder subscription - basic functionality', () =>
+  Vitest.live('QueryBuilder subscription - basic functionality', () =>
     Effect.gen(function* () {
       const { store, exporter, span, provider } = yield* makeQuery
 
@@ -204,10 +206,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)
@@ -239,7 +239,54 @@ Vitest.describe('otel', () => {
     ),
   )
 
-  Vitest.scopedLive('QueryBuilder subscription - unsubscribe functionality', () =>
+  Vitest.live('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.live('QueryBuilder subscription - unsubscribe functionality', () =>
     Effect.gen(function* () {
       const { store, exporter, span, provider } = yield* makeQuery
 
@@ -251,16 +298,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 +338,111 @@ Vitest.describe('otel', () => {
     ),
   )
 
-  Vitest.scopedLive('QueryBuilder subscription - direct table subscription', () =>
+  Vitest.live('QueryBuilder subscription - async iterator', () =>
+    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)[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.live('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.live('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/live-queries/db-query.ts

@@ -1,29 +1,30 @@
+import * as otel from '@opentelemetry/api'
+
 import type { Bindable, QueryBuilder } from '@livestore/common'
 import {
-  getDurationMsFromSpan,
   getResultSchema,
   isQueryBuilder,
   prepareBindValues,
   QueryBuilderAstSymbol,
-  replaceSessionIdSymbol,
+  resolveSessionIdSymbolInBindValues,
   SessionIdSymbol,
-  UnexpectedError,
+  UnknownError,
 } from '@livestore/common'
-import { deepEqual, omitUndefineds, shouldNeverHappen } from '@livestore/utils'
-import { Equal, Hash, Predicate, Schema, TreeFormatter } from '@livestore/utils/effect'
-import * as otel from '@opentelemetry/api'
+import { deepEqual, objectToString, omitUndefineds, shouldNeverHappen } from '@livestore/utils'
+import { Equal, Hash, Predicate, Result, Schema, SchemaIssue } from '@livestore/utils/effect'
 
 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'
+import { depsToString, isLiveQueryDef, LiveStoreQueryBase, makeGetAtomResult, withRCMap } from './base-class.ts'
 import { makeExecBeforeFirstRun, rowQueryLabel } from './client-document-get-query.ts'
 
 export type QueryInputRaw<TDecoded, TEncoded> = {
   query: string
-  schema: Schema.Schema<TDecoded, TEncoded>
+  schema: Schema.Codec<TDecoded, TEncoded>
   bindValues?: Bindable
   /**
    * Can be provided explicitly to slightly speed up initial query performance
@@ -102,7 +103,11 @@ export const queryDb: {
 } = (queryInput, options) => {
   const { queryString, extraDeps } = getQueryStringAndExtraDeps(queryInput)
 
-  const hash = [queryString, options?.deps ? depsToString(options.deps) : undefined, depsToString(extraDeps)]
+  const hash = [
+    queryString,
+    options?.deps !== undefined ? depsToString(options.deps) : undefined,
+    depsToString(extraDeps),
+  ]
     .filter(Boolean)
     .join('-')
 
@@ -111,7 +116,7 @@ export const queryDb: {
   }
 
   if (hash.trim() === '') {
-    return shouldNeverHappen(`Invalid query hash for query: ${queryInput}`)
+    return shouldNeverHappen('Invalid query hash for query:', objectToString(queryInput))
   }
 
   const label = options?.label ?? queryString
@@ -130,8 +135,8 @@ export const queryDb: {
     }),
     label,
     hash,
-    [Equal.symbol](that: LiveQueryDef<any>): boolean {
-      return this.hash === that.hash
+    [Equal.symbol](that: Equal.Equal): boolean {
+      return isLiveQueryDef(that) && that._tag === 'def' && this.hash === that.hash
     },
     [Hash.symbol](): number {
       return Hash.string(this.hash)
@@ -154,12 +159,12 @@ const bindValuesToDepKey = (bindValues: Bindable | undefined): DepKey => {
 const getQueryStringAndExtraDeps = (
   queryInput: QueryInput<any, any> | ((get: GetAtomResult) => QueryInput<any, any>),
 ): { queryString: string; extraDeps: DepKey } => {
-  if (isQueryBuilder(queryInput)) {
+  if (isQueryBuilder(queryInput) === true) {
     const { query, bindValues } = queryInput.asSql()
     return { queryString: query, extraDeps: bindValuesToDepKey(bindValues) }
   }
 
-  if (isQueryInputRaw(queryInput)) {
+  if (isQueryInputRaw(queryInput) === true) {
     return { queryString: queryInput.query, extraDeps: bindValuesToDepKey(queryInput.bindValues) }
   }
 
@@ -167,7 +172,7 @@ const getQueryStringAndExtraDeps = (
     return { queryString: queryInput.toString(), extraDeps: [] }
   }
 
-  return shouldNeverHappen(`Invalid query input: ${queryInput}`)
+  return shouldNeverHappen(`Invalid query input: ${String(queryInput)}`)
 }
 
 /* An object encapsulating a reactive SQL query */
@@ -213,9 +218,13 @@ export class LiveStoreDbQuery<TResultSchema, TResult = TResultSchema> extends Li
 
     this.mapResult = map === undefined ? (rows: any) => rows as TResult : map
 
-    const schemaRef: { current: Schema.Schema<any, any> | undefined } = {
+    const schemaRef: { current: Schema.Codec<any, any> | undefined } = {
       current:
-        typeof queryInput === 'function' ? undefined : isQueryBuilder(queryInput) ? undefined : queryInput.schema,
+        typeof queryInput === 'function'
+          ? undefined
+          : isQueryBuilder(queryInput) === true
+            ? undefined
+            : queryInput.schema,
     }
 
     const execBeforeFirstRunRef: {
@@ -231,7 +240,7 @@ export class LiveStoreDbQuery<TResultSchema, TResult = TResultSchema> extends Li
     const fromQueryBuilder = (qb: QueryBuilder.Any, otelContext: otel.Context | undefined) => {
       try {
         const qbRes = qb.asSql()
-        const schema = getResultSchema(qb) as Schema.Schema<TResultSchema, ReadonlyArray<any>>
+        const schema = getResultSchema(qb) as Schema.Codec<TResultSchema, ReadonlyArray<any>>
         const ast = qb[QueryBuilderAstSymbol]
 
         return {
@@ -253,7 +262,7 @@ export class LiveStoreDbQuery<TResultSchema, TResult = TResultSchema> extends Li
               : undefined,
         }
       } catch (cause) {
-        throw new UnexpectedError({ cause, note: `Error building query for ${qb.toString()}`, payload: { qb } })
+        throw new UnknownError({ cause, note: `Error building query for ${qb.toString()}`, payload: { qb } })
       }
     }
 
@@ -269,7 +278,7 @@ export class LiveStoreDbQuery<TResultSchema, TResult = TResultSchema> extends Li
 
           let queryInputRaw: TQueryInputRaw
 
-          if (isQueryBuilder(queryInputResult)) {
+          if (isQueryBuilder(queryInputResult) === true) {
             const res = fromQueryBuilder(queryInputResult, otelContext)
             queryInputRaw = res.queryInputRaw
             // setting label dynamically here
@@ -296,7 +305,7 @@ export class LiveStoreDbQuery<TResultSchema, TResult = TResultSchema> extends Li
       this.queryInput$ = queryInputRaw$OrQueryInputRaw
     } else {
       let queryInputRaw: TQueryInputRaw
-      if (isQueryBuilder(queryInput)) {
+      if (isQueryBuilder(queryInput) === true) {
         const res = fromQueryBuilder(queryInput, otelContext)
         queryInputRaw = res.queryInputRaw
         label = res.label
@@ -309,7 +318,7 @@ export class LiveStoreDbQuery<TResultSchema, TResult = TResultSchema> extends Li
       queryInputRaw$OrQueryInputRaw = queryInputRaw
 
       // this.label = inputLabel ? this.label : `db(${})`
-      if (inputLabel === undefined && isQueryBuilder(queryInput)) {
+      if (inputLabel === undefined && isQueryBuilder(queryInput) === true) {
         const ast = queryInput[QueryBuilderAstSymbol]
         if (ast._tag === 'RowQuery') {
           label = `db(${rowQueryLabel(ast.tableDef, ast.id)})`
@@ -319,9 +328,9 @@ export class LiveStoreDbQuery<TResultSchema, TResult = TResultSchema> extends Li
 
     const queriedTablesRef: { current: Set<string> | undefined } = { current: undefined }
 
-    const makeResultsEqual = (resultSchema: Schema.Schema<any, any>) => {
+    const makeResultsEqual = (resultSchema: Schema.Codec<any, any>) => {
       // Creating the equivalence function eagerly in outer scope as it might be expensive
-      const eq = Schema.equivalence(resultSchema)
+      const eq = Schema.toEquivalence(resultSchema)
       return (a: TResult, b: TResult) => (a === NOT_REFRESHED_YET || b === NOT_REFRESHED_YET ? false : eq(a, b))
     }
 
@@ -341,13 +350,15 @@ export class LiveStoreDbQuery<TResultSchema, TResult = TResultSchema> extends Li
           'db:...', // NOTE span name will be overridden further down
           {
             attributes: {
-              'livestore.debugRefreshReason': Predicate.hasProperty(debugRefreshReason, 'label')
-                ? (debugRefreshReason.label as string)
-                : debugRefreshReason?._tag,
+              'livestore.debugRefreshReason':
+                Predicate.hasProperty(debugRefreshReason, 'label') === true
+                  ? (debugRefreshReason.label as string)
+                  : debugRefreshReason?._tag,
             },
           },
           otelContext ?? queryContext.rootOtelContext,
           (span) => {
+            const startTimePerfNow = performance.now()
             const otelContext = otel.trace.setSpan(otel.context.active(), span)
             const { store } = queryContext
 
@@ -356,45 +367,49 @@ export class LiveStoreDbQuery<TResultSchema, TResult = TResultSchema> extends Li
               execBeforeFirstRunRef.current = undefined
             }
 
-            const queryInputResult = isThunk(queryInputRaw$OrQueryInputRaw)
-              ? (get(queryInputRaw$OrQueryInputRaw, otelContext, debugRefreshReason) as TQueryInputRaw)
-              : (queryInputRaw$OrQueryInputRaw as TQueryInputRaw)
+            const queryInputResult =
+              isThunk(queryInputRaw$OrQueryInputRaw) === true
+                ? (get(queryInputRaw$OrQueryInputRaw, otelContext, debugRefreshReason) as TQueryInputRaw)
+                : (queryInputRaw$OrQueryInputRaw as TQueryInputRaw)
 
             const sqlString = queryInputResult.query
             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)
-            }
+            // Live query inputs may be cached and re-run as reactive dependencies change.
+            // Resolve SessionIdSymbol per execution so the cached input stays symbolic and session-agnostic.
+            const resolvedBindValues =
+              bindValues === undefined ? undefined : resolveSessionIdSymbolInBindValues(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(
               sqlString,
-              bindValues ? prepareBindValues(bindValues, sqlString) : undefined,
+              resolvedBindValues !== undefined ? prepareBindValues(resolvedBindValues, sqlString) : undefined,
               {
-                queriedTables: queriedTablesRef.current,
                 otelContext,
+                ...(queriedTablesRef.current !== undefined ? { queriedTables: queriedTablesRef.current } : {}),
               },
             )
 
             span.setAttribute('sql.rowsCount', rawDbResults.length)
 
-            const parsedResult = Schema.decodeEither(schemaRef.current!)(rawDbResults)
+            const parsedResult = Schema.decodeResult(schemaRef.current!)(rawDbResults)
 
-            if (parsedResult._tag === 'Left') {
-              const parseErrorStr = TreeFormatter.formatErrorSync(parsedResult.left)
+            if (Result.isFailure(parsedResult) === true) {
+              const parseErrorStr = SchemaIssue.makeFormatterDefault()(parsedResult.failure.issue)
               const expectedSchemaStr = String(schemaRef.current!.ast)
               const bindValuesStr = bindValues === undefined ? '' : `\nBind values: ${JSON.stringify(bindValues)}`
 
@@ -415,11 +430,11 @@ Result:`,
               )
             }
 
-            const result = this.mapResult(parsedResult.right)
+            const result = this.mapResult(parsedResult.success)
 
             span.end()
 
-            const durationMs = getDurationMsFromSpan(span)
+            const durationMs = performance.now() - startTimePerfNow
 
             this.executionTimes.push(durationMs)
 

package/src/live-queries/signal.test.ts

@@ -1,13 +1,14 @@
-import { Effect } from '@livestore/utils/effect'
-import { Vitest } from '@livestore/utils-dev/node-vitest'
 import { expect } from 'vitest'
 
+import { Vitest } from '@livestore/utils-dev/node-vitest'
+import { Effect } from '@livestore/utils/effect'
+
 import { makeTodoMvc } from '../utils/tests/fixture.ts'
 import { computed } from './computed.ts'
 import { signal } from './signal.ts'
 
 Vitest.describe('signal', () => {
-  Vitest.scopedLive('should be able to create a signal', () =>
+  Vitest.live('should be able to create a signal', () =>
     Effect.gen(function* () {
       const num$ = signal(0, { label: 'num$' })
 
@@ -23,7 +24,7 @@ Vitest.describe('signal', () => {
     }),
   )
 
-  Vitest.scopedLive('counter example', () =>
+  Vitest.live('counter example', () =>
     Effect.gen(function* () {
       const count$ = signal(0, { label: 'count$' })
 

package/src/live-queries/signal.ts

@@ -4,8 +4,50 @@ import { nanoid } from '@livestore/utils/nanoid'
 import type * as RG from '../reactive.ts'
 import type { RefreshReason } from '../store/store-types.ts'
 import type { ISignal, ReactivityGraph, ReactivityGraphContext, SignalDef } from './base-class.ts'
-import { LiveStoreQueryBase, withRCMap } from './base-class.ts'
+import { isSignalDef, LiveStoreQueryBase, withRCMap } from './base-class.ts'
 
+/**
+ * Creates a reactive signal for ephemeral, local-only state that isn't persisted to the database.
+ *
+ * Signals are useful for UI state that needs to trigger query re-evaluation but shouldn't be
+ * synced across clients or stored permanently—such as search filters, selected items, or
+ * temporary form values.
+ *
+ * Unlike database-backed state (via events), signals:
+ * - Are not persisted or synced
+ * - Exist only for the lifetime of the Store
+ * - Can hold any value type (primitives, objects, functions)
+ *
+ * @example
+ * ```ts
+ * // Create a signal for search text
+ * const searchText$ = signal('', { label: 'searchText' })
+ *
+ * // Create a query that depends on the signal
+ * const filteredTodos$ = queryDb(
+ *   (get) => tables.todos.where({ text: { $like: `%${get(searchText$)}%` } }),
+ *   { deps: [searchText$] }
+ * )
+ *
+ * // Update the signal (triggers query re-evaluation)
+ * store.setSignal(searchText$, 'buy')
+ *
+ * // Read the current value
+ * const results = store.query(filteredTodos$)
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Counter with functional updates
+ * const count$ = signal(0, { label: 'count' })
+ *
+ * store.setSignal(count$, (prev) => prev + 1)
+ * ```
+ *
+ * @param defaultValue - Initial value of the signal
+ * @param options.label - Human-readable label for debugging and devtools
+ * @returns A signal definition that can be used with `store.query()`, `store.setSignal()`, and as a dependency in other queries
+ */
 export const signal = <T>(
   defaultValue: T,
   options?: {
@@ -28,8 +70,8 @@ export const signal = <T>(
           def,
         }),
     ),
-    [Equal.symbol](that: SignalDef<T>): boolean {
-      return this.hash === that.hash
+    [Equal.symbol](that: Equal.Equal): boolean {
+      return isSignalDef(that) && this.hash === that.hash
     },
     [Hash.symbol](): number {
       return Hash.string(this.hash)
@@ -39,6 +81,13 @@ export const signal = <T>(
   return def
 }
 
+/**
+ * A live signal instance bound to a specific Store.
+ *
+ * Signal instances are created internally when you use a `SignalDef` with the Store.
+ * You typically don't construct these directly—use {@link signal} to create definitions
+ * and `store.setSignal()` / `store.query()` to interact with them.
+ */
 export class Signal<T> extends LiveStoreQueryBase<T> implements ISignal<T> {
   _tag = 'signal' as const
   readonly ref: RG.Ref<T, ReactivityGraphContext, RefreshReason>