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

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

@@ -1,10 +1,10 @@
-import { isNotNil } from '@livestore/utils'
-import { Equal, Hash, Predicate } from '@livestore/utils/effect'
 import type * as otel from '@opentelemetry/api'
 
+import { Equal, Hash, Predicate } from '@livestore/utils/effect'
+
 import * as RG from '../reactive.ts'
-import type { Store } from '../store/store.ts'
 import type { QueryDebugInfo, RefreshReason } from '../store/store-types.ts'
+import type { Store } from '../store/store.ts'
 import type { StackInfo } from '../utils/stack-info.ts'
 
 export type ReactivityGraph = RG.ReactiveGraph<RefreshReason, QueryDebugInfo, ReactivityGraphContext>
@@ -23,63 +23,129 @@ export type ReactivityGraphContext = {
   effectsWrapper: (run: () => void) => void
 }
 
-export type GetResult<TQuery extends LiveQueryDef.Any | LiveQuery.Any | SignalDef<any>> = TQuery extends LiveQuery<
-  infer TResult
->
-  ? TResult
-  : TQuery extends LiveQueryDef<infer TResult>
+export type GetResult<TQuery extends LiveQueryDef.Any | LiveQuery.Any | SignalDef<any>> =
+  TQuery extends LiveQuery<infer TResult>
     ? TResult
-    : TQuery extends SignalDef<infer TResult>
+    : TQuery extends LiveQueryDef<infer TResult>
       ? TResult
-      : unknown
+      : TQuery extends SignalDef<infer TResult>
+        ? TResult
+        : unknown
 
 let queryIdCounter = 0
 
+/**
+ * A signal definition representing ephemeral, local-only reactive state.
+ *
+ * `SignalDef` is the type returned by {@link signal}. It's a blueprint for creating
+ * signal instances—the actual instance is created when you use the definition with
+ * a Store via `store.query()` or `store.setSignal()`.
+ *
+ * @typeParam T - The type of value the signal holds
+ */
 export interface SignalDef<T> extends LiveQueryDef<T, 'signal-def'> {
   _tag: 'signal-def'
+  /** The initial value used when the signal is first created */
   defaultValue: T
+  /** Unique identifier for caching and deduplication */
   hash: string
+  /** Human-readable label for debugging and devtools */
   label: string
+  /** Creates a reference-counted signal instance bound to a Store's reactivity graph */
   make: (ctx: ReactivityGraphContext) => RcRef<ISignal<T>>
-  [Equal.symbol](that: SignalDef<T>): boolean
+  [Equal.symbol](that: Equal.Equal): boolean
   [Hash.symbol](): number
 }
 
+/**
+ * Interface for a live signal instance.
+ *
+ * This represents an active signal bound to a Store's reactivity graph.
+ * Use `store.setSignal()` to update values and `store.query()` to read them.
+ *
+ * @typeParam T - The type of value the signal holds
+ */
 export interface ISignal<T> extends LiveQuery<T> {
   _tag: 'signal'
   reactivityGraph: ReactivityGraph
+  /** The underlying reactive reference in the graph */
   ref: RG.Ref<T, ReactivityGraphContext, RefreshReason>
+  /** Sets the signal's value (prefer using `store.setSignal()` instead) */
   set: (value: T) => void
+  /** Gets the signal's current value (prefer using `store.query()` instead) */
   get: () => T
+  /** Removes the signal from the reactivity graph */
   destroy: () => void
 }
 
 export const TypeId = Symbol.for('LiveQuery')
 export type TypeId = typeof TypeId
 
+/**
+ * A reference-counted wrapper around a LiveQuery or Signal instance.
+ *
+ * LiveStore uses reference counting to manage query lifecycle. When multiple
+ * components or subscriptions use the same query definition, they share a single
+ * instance. The instance is destroyed when the last reference is released.
+ *
+ * You typically don't interact with `RcRef` directly—it's used internally by
+ * hooks like `useQuery` and `useQueryRef`.
+ */
 export interface RcRef<T> {
+  /** Current reference count */
   rc: number
+  /** The wrapped query or signal instance */
   value: T
+  /** Decrements the reference count; destroys the instance when it reaches zero */
   deref: () => void
 }
 
+/**
+ * Dependency key used to identify queries on platforms where `fn.toString()` isn't reliable.
+ *
+ * On Expo/React Native, Hermes compiles functions to bytecode, so `fn.toString()` returns
+ * `[native code]`. To uniquely identify contextual queries, you must provide explicit `deps`.
+ *
+ * @example
+ * ```ts
+ * // On Expo, this would fail without deps:
+ * const filtered$ = queryDb(
+ *   (get) => tables.todos.where({ userId: get(userId$) }),
+ *   { deps: [userId] } // Required on Expo/React Native
+ * )
+ * ```
+ */
 export type DepKey = string | number | ReadonlyArray<string | number | undefined | null>
 
 export const depsToString = (deps: DepKey): string => {
   if (typeof deps === 'string' || typeof deps === 'number') {
     return deps.toString()
   }
-  return deps.filter(isNotNil).join(',')
+  return deps.filter(Predicate.isNotNullish).join(',')
 }
 
+/**
+ * A query definition representing a blueprint for a reactive query.
+ *
+ * Query definitions are created by {@link queryDb}, {@link computed}, and {@link signal}.
+ * They're lightweight and can be defined at module scope. The actual query instance
+ * (which holds state) is created lazily when you use the definition with a Store.
+ *
+ * Multiple uses of the same definition share a single instance via reference counting.
+ *
+ * @typeParam TResult - The type of value the query returns
+ * @typeParam TTag - Internal discriminator tag ('def' for queries, 'signal-def' for signals)
+ */
 // TODO we should refactor/clean up how LiveQueryDef / SignalDef / LiveQuery / ISignal are defined (particularly on the type-level)
 export interface LiveQueryDef<TResult, TTag extends string = 'def'> {
   _tag: TTag
-  /** Creates a new LiveQuery instance bound to a specific store/reactivityGraph */
+  /** Creates a reference-counted query instance bound to a Store's reactivity graph */
   make: (ctx: ReactivityGraphContext, otelContext?: otel.Context) => RcRef<LiveQuery<TResult> | ISignal<TResult>>
+  /** Human-readable label for debugging and devtools */
   label: string
+  /** Unique identifier derived from the query string or explicit deps; used for caching */
   hash: string
-  [Equal.symbol](that: LiveQueryDef<TResult, TTag>): boolean
+  [Equal.symbol](that: Equal.Equal): boolean
   [Hash.symbol](): number
 }
 
@@ -88,39 +154,84 @@ export namespace LiveQueryDef {
 }
 
 /**
- * A LiveQuery is stateful
+ * Type guard that checks if a value is a query or signal definition.
+ *
+ * Use this to distinguish between definitions (blueprints) and instances (live queries).
+ * Definitions are created by `queryDb()`, `computed()`, and `signal()`.
+ *
+ * @example
+ * ```ts
+ * const todos$ = queryDb(tables.todos.all())
+ *
+ * if (isLiveQueryDef(todos$)) {
+ *   console.log('This is a definition:', todos$.label)
+ * }
+ * ```
+ */
+export const isLiveQueryDef = (value: unknown): value is LiveQueryDef<any> | SignalDef<any> => {
+  if (Predicate.isTagged(value, 'def') === false && Predicate.isTagged(value, 'signal-def') === false) {
+    return false
+  }
+
+  return (
+    Predicate.hasProperty(value, 'make') &&
+    Predicate.isFunction(value.make) &&
+    Predicate.hasProperty(value, 'hash') &&
+    Predicate.isString(value.hash) &&
+    Predicate.hasProperty(value, 'label') &&
+    Predicate.isString(value.label)
+  )
+}
+
+export const isSignalDef = (value: unknown): value is SignalDef<any> =>
+  isLiveQueryDef(value) && Predicate.isTagged(value, 'signal-def')
+
+/**
+ * A live query instance bound to a specific Store.
+ *
+ * `LiveQuery` represents an active, stateful query in the reactivity graph. Unlike
+ * query definitions (`LiveQueryDef`), instances maintain state like execution counts,
+ * timing data, and active subscriptions.
+ *
+ * You typically don't work with `LiveQuery` directly—use `store.query()` for one-shot
+ * reads or `store.subscribe()` for reactive subscriptions. The instance is managed
+ * automatically via reference counting.
+ *
+ * @typeParam TResult - The type of value the query returns
  */
 export interface LiveQuery<TResult> {
+  /** Unique identifier for this query instance */
   id: number
+  /** Discriminator for the query type */
   _tag: 'computed' | 'db' | 'graphql' | 'signal'
   [TypeId]: TypeId
 
-  // reactivityGraph: ReactivityGraph
-
-  /** This should only be used on a type-level and doesn't hold any value during runtime */
+  /** Type-level only—extracts the result type from a LiveQuery */
   '__result!': TResult
 
-  /** A reactive thunk representing the query results */
+  /** The underlying reactive atom in the graph that holds the query result */
   results$: RG.Atom<TResult, ReactivityGraphContext, RefreshReason>
 
+  /** Human-readable label for debugging and devtools */
   label: string
 
+  /** Executes the query and returns the result */
   run: (args: { otelContext?: otel.Context; debugRefreshReason?: RefreshReason }) => TResult
 
+  /** Removes the query from the reactivity graph */
   destroy: () => void
+  /** Whether this query instance has been destroyed */
   isDestroyed: boolean
 
-  // subscribe(
-  //   onNewValue: (value: TResult) => void,
-  //   onUnsubsubscribe?: () => void,
-  //   options?: { label?: string; otelContext?: otel.Context },
-  // ): () => void
-
+  /** Stack traces of active subscriptions (for debugging) */
   activeSubscriptions: Set<StackInfo>
 
+  /** Number of times this query has been executed */
   runs: number
 
+  /** Execution times in milliseconds (for performance monitoring) */
   executionTimes: number[]
+  /** The definition that created this instance */
   def: LiveQueryDef<TResult> | SignalDef<TResult>
 }
 
@@ -166,17 +277,36 @@ 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)
 }
 
+/**
+ * Function signature for the `get` parameter in `computed()` and `queryDb()` callbacks.
+ *
+ * Call `get()` with a query definition, signal, or live query instance to:
+ * 1. Read its current value
+ * 2. Establish a reactive dependency (the caller re-runs when the dependency changes)
+ *
+ * @example
+ * ```ts
+ * const filtered$ = computed((get) => {
+ *   const todos = get(todos$)        // Depends on todos$
+ *   const filter = get(filterText$)  // Depends on filterText$
+ *   return todos.filter((t) => t.text.includes(filter))
+ * })
+ * ```
+ */
 export type GetAtomResult = <T>(
   atom: RG.Atom<T, any, RefreshReason> | LiveQueryDef<T> | LiveQuery<T> | ISignal<T> | SignalDef<T>,
-  otelContext?: otel.Context | undefined,
-  debugRefreshReason?: RefreshReason | undefined,
+  otelContext?: otel.Context,
+  debugRefreshReason?: RefreshReason,
 ) => T
 
 export type DependencyQueriesRef = Set<RcRef<LiveQuery.Any | ISignal<any>>>
@@ -201,7 +331,7 @@ export const makeGetAtomResult = (
     }
 
     // Signal case
-    if (atom._tag === 'signal' && Predicate.hasProperty(atom, 'ref')) {
+    if (atom._tag === 'signal' && Predicate.hasProperty(atom, 'ref') === true) {
       return get(atom.ref, otelContext, debugRefreshReason)
     }
 
@@ -218,7 +348,7 @@ export const withRCMap = <T extends LiveQuery.Any | ISignal<any>>(
 ): ((ctx: ReactivityGraphContext, otelContext?: otel.Context) => RcRef<T>) => {
   return (ctx, otelContext) => {
     let item = ctx.defRcMap.get(id)
-    if (item) {
+    if (item !== undefined) {
       item.rc++
       return item as RcRef<T>
     }

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

@@ -1,9 +1,11 @@
+import type * as otel from '@opentelemetry/api'
+
 import type { PreparedBindValues } from '@livestore/common'
 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,17 +32,17 @@ 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 },
       ).length === 1
 
-    if (rowExists) return
+    if (rowExists === true) return
 
     // It's important that we only commit and don't refresh here, as this function might be called during a render
     // and otherwise we might end up in a "reactive loop"

package/src/live-queries/computed.ts

@@ -1,13 +1,62 @@
-import { getDurationMsFromSpan } from '@livestore/common'
-import { Equal, Hash } from '@livestore/utils/effect'
 import * as otel from '@opentelemetry/api'
 
+import { Equal, Hash } from '@livestore/utils/effect'
+
 import type { Thunk } from '../reactive.ts'
 import type { RefreshReason } 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'
+
+/**
+ * Creates a derived query that computes a value from other queries or signals.
+ *
+ * Computed queries are memoized—they only re-evaluate when their dependencies change,
+ * and if the new result equals the previous result, downstream dependents won't re-run.
+ * Use them for expensive calculations, aggregations, or transformations.
+ *
+ * The `get` function inside `computed` establishes reactive dependencies automatically.
+ * When any dependency updates, the computed re-evaluates.
+ *
+ * @example
+ * ```ts
+ * // Derive a count from a database query
+ * const todos$ = queryDb(tables.todos.all())
+ * const todoCount$ = computed((get) => get(todos$).length, { label: 'todoCount' })
+ *
+ * // Use in a component
+ * const count = store.query(todoCount$) // 5
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Combine multiple queries into derived stats
+ * const stats$ = computed((get) => {
+ *   const todos = get(todos$)
+ *   const completed = todos.filter((t) => t.completed).length
+ *   return {
+ *     total: todos.length,
+ *     completed,
+ *     remaining: todos.length - completed,
+ *     percentComplete: todos.length > 0 ? (completed / todos.length) * 100 : 0,
+ *   }
+ * }, { label: 'todoStats' })
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Chain computed queries
+ * const hasCompletedTodos$ = computed(
+ *   (get) => get(stats$).completed > 0,
+ *   { label: 'hasCompletedTodos' }
+ * )
+ * ```
+ *
+ * @param fn - Pure function that computes the result. Use `get()` to read dependencies.
+ * @param options.label - Human-readable label for debugging and devtools
+ * @param options.deps - Explicit dependency keys (required on Expo/React Native where `fn.toString()` returns `[native code]`)
+ * @returns A query definition usable with `store.query()`, `store.subscribe()`, and as a dependency in other queries
+ */
 export const computed = <TResult>(
   fn: (get: GetAtomResult) => TResult,
   options?: {
@@ -15,7 +64,7 @@ export const computed = <TResult>(
     deps?: DepKey
   },
 ): LiveQueryDef<TResult> => {
-  const hash = options?.deps ? depsToString(options.deps) : fn.toString()
+  const hash = options?.deps !== undefined ? depsToString(options.deps) : fn.toString()
   if (isValidFunctionString(hash)._tag === 'invalid') {
     throw new Error(`On Expo/React Native, computed queries must provide a \`deps\` option`)
   }
@@ -36,8 +85,8 @@ export const computed = <TResult>(
     // TODO we should figure out whether this could cause some problems and/or if there's a better way to do this
     // NOTE `fn.toString()` doesn't work in Expo as it always produces `[native code]`
     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)
@@ -47,6 +96,13 @@ export const computed = <TResult>(
   return def
 }
 
+/**
+ * A live computed query instance bound to a specific Store.
+ *
+ * Computed query instances are created internally when you use a `LiveQueryDef` (from {@link computed})
+ * with the Store. You typically don't construct these directly—use `computed()` to create definitions
+ * and `store.query()` / `store.subscribe()` to interact with them.
+ */
 export class LiveStoreComputedQuery<TResult> extends LiveStoreQueryBase<TResult> {
   _tag = 'computed' as const
 
@@ -80,12 +136,13 @@ export class LiveStoreComputedQuery<TResult> extends LiveStoreQueryBase<TResult>
     this.results$ = this.reactivityGraph.makeThunk(
       (get, setDebugInfo, ctx, otelContext) =>
         ctx.otelTracer.startActiveSpan(`js:${label}`, {}, otelContext ?? ctx.rootOtelContext, (span) => {
+          const startTimePerfNow = performance.now()
           const otelContext = otel.trace.setSpan(otel.context.active(), span)
           const res = fn(makeGetAtomResult(get, ctx, otelContext, this.dependencyQueriesRef))
 
           span.end()
 
-          const durationMs = getDurationMsFromSpan(span)
+          const durationMs = performance.now() - startTimePerfNow
 
           this.executionTimes.push(durationMs)