@livestore/livestore 0.4.0-dev.20 → 0.4.0-dev.22

package/src/effect/LiveStore.ts

@@ -1,11 +1,12 @@
 import type { UnknownError } from '@livestore/common'
-import type { LiveStoreSchema } from '@livestore/common/schema'
+import type { LiveStoreEvent, LiveStoreSchema } from '@livestore/common/schema'
 import { omitUndefineds } from '@livestore/utils'
 import type { Cause, OtelTracer, Scope } from '@livestore/utils/effect'
-import { Deferred, Duration, Effect, Layer, pipe } from '@livestore/utils/effect'
-
+import { Context, Deferred, Duration, Effect, Layer, pipe } from '@livestore/utils/effect'
 import type { LiveStoreContextProps } from '../store/create-store.ts'
 import { createStore, DeferredStoreContext, LiveStoreContextRunning } from '../store/create-store.ts'
+import type { Store as StoreClass } from '../store/store.ts'
+import type { LiveStoreContextRunning as LiveStoreContextRunningType, Queryable } from '../store/store-types.ts'
 
 export const makeLiveStoreContext = <TSchema extends LiveStoreSchema, TContext = {}>({
   schema,
@@ -49,6 +50,19 @@ export const makeLiveStoreContext = <TSchema extends LiveStoreSchema, TContext =
     Effect.withSpan('@livestore/livestore/effect:makeLiveStoreContext'),
   )
 
+/**
+ * @deprecated Use `Store.Tag(schema, storeId)` instead for type-safe store contexts.
+ *
+ * @example Migration
+ * ```ts
+ * // Before
+ * const layer = LiveStoreContextLayer({ schema, adapter, ... })
+ *
+ * // After
+ * class MainStore extends Store.Tag(schema, 'main') {}
+ * const layer = MainStore.layer({ adapter, ... })
+ * ```
+ */
 export const LiveStoreContextLayer = <TSchema extends LiveStoreSchema, TContext = {}>(
   props: LiveStoreContextProps<TSchema, TContext>,
 ): Layer.Layer<LiveStoreContextRunning, UnknownError | Cause.TimeoutException, OtelTracer.OtelTracer> =>
@@ -57,7 +71,375 @@ export const LiveStoreContextLayer = <TSchema extends LiveStoreSchema, TContext
     Layer.provide(LiveStoreContextDeferred),
   )
 
+/**
+ * @deprecated Use `Store.Tag(schema, storeId)` and `MainStore.DeferredLayer` instead.
+ */
 export const LiveStoreContextDeferred = Layer.effect(
   DeferredStoreContext,
   Deferred.make<LiveStoreContextRunning['Type'], UnknownError>(),
 )
+
+// =============================================================================
+// Store.Tag - Idiomatic Effect API
+// =============================================================================
+
+/** Branded type for unique store context identity */
+declare const StoreContextTypeId: unique symbol
+
+/** Phantom type carrying schema and storeId information */
+export interface StoreContextId<TSchema extends LiveStoreSchema, TStoreId extends string> {
+  readonly [StoreContextTypeId]: {
+    readonly schema: TSchema
+    readonly storeId: TStoreId
+  }
+}
+
+/** Phantom type for deferred store context */
+declare const DeferredContextTypeId: unique symbol
+
+export interface DeferredContextId<TStoreId extends string> {
+  readonly [DeferredContextTypeId]: {
+    readonly storeId: TStoreId
+  }
+}
+
+/** Props for creating a store layer (schema and storeId are already provided) */
+export type StoreLayerProps<TSchema extends LiveStoreSchema, TContext = {}> = Omit<
+  LiveStoreContextProps<TSchema, TContext>,
+  'storeId' | 'schema'
+>
+
+/**
+ * Type for a Store.Tag class. This is the return type of `Store.Tag(schema, storeId)`.
+ * Can be extended as a class and is yieldable in Effect.gen.
+ *
+ * Note: This uses a type alias with a new() signature to make it extendable.
+ */
+export type StoreTagClass<TSchema extends LiveStoreSchema, TStoreId extends string> = {
+  /** Constructor signature (makes the type extendable as a class) */
+  new (): Context.Tag<StoreContextId<TSchema, TStoreId>, LiveStoreContextRunningType<TSchema>>
+
+  /** Tag identity type (from Context.Tag) */
+  readonly Id: StoreContextId<TSchema, TStoreId>
+
+  /** Service type (from Context.Tag) */
+  readonly Type: LiveStoreContextRunningType<TSchema>
+
+  /** The LiveStore schema for this store */
+  readonly schema: TSchema
+
+  /** Unique identifier for this store */
+  readonly storeId: TStoreId
+
+  /** Creates a layer that initializes the store */
+  layer<TContext = {}>(
+    props: StoreLayerProps<TSchema, TContext>,
+  ): Layer.Layer<StoreTagClass<TSchema, TStoreId>, UnknownError | Cause.TimeoutException, OtelTracer.OtelTracer>
+
+  /** Deferred store tag for async initialization patterns */
+  readonly Deferred: Context.Tag<
+    DeferredContextId<TStoreId>,
+    Deferred.Deferred<LiveStoreContextRunningType<TSchema>, UnknownError>
+  >
+
+  /** Layer that provides the Deferred tag */
+  readonly DeferredLayer: Layer.Layer<DeferredContextId<TStoreId>, never, never>
+
+  /** Layer that waits for Deferred and provides the running store */
+  readonly fromDeferred: Layer.Layer<StoreTagClass<TSchema, TStoreId>, UnknownError, DeferredContextId<TStoreId>>
+
+  /** Query the store. Returns an Effect that yields the query result. */
+  query<TResult>(query: Queryable<TResult>): Effect.Effect<TResult, never, StoreTagClass<TSchema, TStoreId>>
+
+  /** Commit events to the store. */
+  commit(
+    ...eventInputs: LiveStoreEvent.Input.ForSchema<TSchema>[]
+  ): Effect.Effect<void, never, StoreTagClass<TSchema, TStoreId>>
+
+  /** Use the store with a callback function. */
+  use<A, E, R>(
+    f: (ctx: LiveStoreContextRunningType<TSchema>) => Effect.Effect<A, E, R>,
+  ): Effect.Effect<A, E, R | StoreTagClass<TSchema, TStoreId>>
+} & Context.Tag<StoreContextId<TSchema, TStoreId>, LiveStoreContextRunningType<TSchema>>
+
+/**
+ * Create a typed store context class for use with Effect.
+ *
+ * Returns a class that extends `Context.Tag`, making it directly yieldable in Effect code.
+ * The class includes static methods for creating layers and accessors for common operations.
+ *
+ * @param schema - The LiveStore schema (used for type inference and runtime)
+ * @param storeId - Unique identifier for this store
+ *
+ * @example Basic usage
+ * ```ts
+ * import { Store } from '@livestore/livestore/effect'
+ * import { schema } from './schema.ts'
+ *
+ * // Define your store (once per store)
+ * export class MainStore extends Store.Tag(schema, 'main') {}
+ *
+ * // Create the layer
+ * const storeLayer = MainStore.layer({
+ *   adapter: myAdapter,
+ *   batchUpdates: ReactDOM.unstable_batchedUpdates,
+ * })
+ *
+ * // Use in Effect code
+ * Effect.gen(function* () {
+ *   const { store } = yield* MainStore
+ *   //       ^? Store<typeof schema> - fully typed!
+ *
+ *   // Or use accessors
+ *   const users = yield* MainStore.query(tables.users.all())
+ *   yield* MainStore.commit(events.createUser({ id: '1', name: 'Alice' }))
+ * })
+ * ```
+ *
+ * @example Multiple stores
+ * ```ts
+ * class MainStore extends Store.Tag(mainSchema, 'main') {}
+ * class SettingsStore extends Store.Tag(settingsSchema, 'settings') {}
+ *
+ * // Both available in same Effect context
+ * Effect.gen(function* () {
+ *   const main = yield* MainStore
+ *   const settings = yield* SettingsStore
+ * })
+ *
+ * const layer = Layer.mergeAll(
+ *   MainStore.layer({ adapter: mainAdapter }),
+ *   SettingsStore.layer({ adapter: settingsAdapter }),
+ * )
+ * ```
+ */
+const makeStoreTag = <TSchema extends LiveStoreSchema, TStoreId extends string>(
+  schema: TSchema,
+  storeId: TStoreId,
+): StoreTagClass<TSchema, TStoreId> => {
+  type RunningType = LiveStoreContextRunningType<TSchema>
+  type DeferredType = Deferred.Deferred<RunningType, UnknownError>
+
+  // Create the deferred tag and layers upfront
+  const _DeferredTag = Context.GenericTag<DeferredContextId<TStoreId>, DeferredType>(
+    `@livestore/store-deferred/${storeId}`,
+  )
+
+  const _DeferredLayer = Layer.effect(_DeferredTag, Deferred.make<RunningType, UnknownError>())
+
+  class Tag extends Context.Tag(`@livestore/store/${storeId}`)<Tag, RunningType>() {
+    static readonly schema: TSchema = schema
+    static readonly storeId: TStoreId = storeId
+
+    static layer<TContext = {}>(props: StoreLayerProps<TSchema, TContext>) {
+      return pipe(
+        Effect.gen(function* () {
+          const store = yield* createStore({
+            schema,
+            storeId,
+            adapter: props.adapter,
+            batchUpdates: props.batchUpdates,
+            ...omitUndefineds({
+              context: props.context,
+              boot: props.boot,
+              disableDevtools: props.disableDevtools,
+              onBootStatus: props.onBootStatus,
+              syncPayload: props.syncPayload,
+              syncPayloadSchema: props.syncPayloadSchema,
+            }),
+          })
+
+          globalThis.__debugLiveStore ??= {}
+          if (Object.keys(globalThis.__debugLiveStore).length === 0) {
+            globalThis.__debugLiveStore._ = store
+          }
+          globalThis.__debugLiveStore[storeId] = store
+
+          const ctx: RunningType = { stage: 'running', store: store as StoreClass<TSchema> }
+
+          // Also fulfill the deferred if it exists in context
+          yield* Effect.flatMap(Effect.serviceOption(_DeferredTag), (optDeferred) =>
+            optDeferred._tag === 'Some' ? Deferred.succeed(optDeferred.value, ctx) : Effect.void,
+          )
+
+          return ctx
+        }),
+        Effect.timeout(Duration.minutes(5)),
+        Effect.withSpan(`@livestore/effect:Store.Tag:${storeId}`),
+        Layer.scoped(Tag),
+        Layer.withSpan(`LiveStore:${storeId}`),
+        Layer.provide(_DeferredLayer),
+      )
+    }
+
+    static readonly Deferred = _DeferredTag
+    static readonly DeferredLayer = _DeferredLayer
+
+    static readonly fromDeferred = pipe(
+      Effect.gen(function* () {
+        const deferred = yield* _DeferredTag
+        const ctx = yield* deferred
+        return Layer.succeed(Tag, ctx)
+      }),
+      Layer.unwrapScoped,
+    )
+
+    static query<TResult>(query: Queryable<TResult>) {
+      return Effect.map(Tag, ({ store }) => store.query(query))
+    }
+
+    static commit(...eventInputs: LiveStoreEvent.Input.ForSchema<TSchema>[]) {
+      return Effect.map(Tag, ({ store }) => {
+        store.commit(...eventInputs)
+      })
+    }
+
+    static use<A, E, R>(f: (ctx: RunningType) => Effect.Effect<A, E, R>) {
+      return Effect.flatMap(Tag, f)
+    }
+  }
+
+  return Tag as unknown as StoreTagClass<TSchema, TStoreId>
+}
+
+/**
+ * Store utilities for Effect integration.
+ *
+ * @example
+ * ```ts
+ * import { Store } from '@livestore/livestore/effect'
+ *
+ * export class MainStore extends Store.Tag(schema, 'main') {}
+ * ```
+ */
+export const Store = {
+  /**
+   * Create a typed store context class for use with Effect.
+   * @see {@link makeStoreTag} for full documentation
+   */
+  Tag: makeStoreTag,
+}
+
+// =============================================================================
+// Legacy API (deprecated)
+// =============================================================================
+
+/**
+ * @deprecated Use `Store.Tag(schema, storeId)` instead.
+ *
+ * @example Migration
+ * ```ts
+ * // Before
+ * const MainStoreContext = makeStoreContext<typeof schema>()('main')
+ * export const MainStore = MainStoreContext.Tag
+ * export const MainStoreLayer = MainStoreContext.Layer
+ *
+ * // After
+ * export class MainStore extends Store.Tag(schema, 'main') {}
+ * // MainStore.layer({ ... }) for the layer
+ * ```
+ */
+export interface StoreContext<TSchema extends LiveStoreSchema, TStoreId extends string> {
+  readonly storeId: TStoreId
+  readonly Tag: Context.Tag<StoreContextId<TSchema, TStoreId>, LiveStoreContextRunningType<TSchema>>
+  readonly DeferredTag: Context.Tag<
+    DeferredContextId<TStoreId>,
+    Deferred.Deferred<LiveStoreContextRunningType<TSchema>, UnknownError>
+  >
+  readonly Layer: <TContext = {}>(
+    props: Omit<LiveStoreContextProps<TSchema, TContext>, 'storeId'>,
+  ) => Layer.Layer<StoreContextId<TSchema, TStoreId>, UnknownError | Cause.TimeoutException, OtelTracer.OtelTracer>
+  readonly DeferredLayer: Layer.Layer<DeferredContextId<TStoreId>, never, never>
+  readonly fromDeferred: Layer.Layer<StoreContextId<TSchema, TStoreId>, UnknownError, DeferredContextId<TStoreId>>
+}
+
+/**
+ * @deprecated Use `Store.Tag(schema, storeId)` instead.
+ *
+ * @example Migration
+ * ```ts
+ * // Before
+ * const MainStoreContext = makeStoreContext<typeof schema>()('main')
+ *
+ * // After
+ * class MainStore extends Store.Tag(schema, 'main') {}
+ * ```
+ */
+export const makeStoreContext =
+  <TSchema extends LiveStoreSchema>() =>
+  <TStoreId extends string>(storeId: TStoreId): StoreContext<TSchema, TStoreId> => {
+    type RunningType = LiveStoreContextRunningType<TSchema>
+    type DeferredType = Deferred.Deferred<RunningType, UnknownError>
+
+    const Tag = Context.GenericTag<StoreContextId<TSchema, TStoreId>, RunningType>(`@livestore/store/${storeId}`)
+
+    const DeferredTag = Context.GenericTag<DeferredContextId<TStoreId>, DeferredType>(
+      `@livestore/store-deferred/${storeId}`,
+    )
+
+    const DeferredLayer = Layer.effect(DeferredTag, Deferred.make<RunningType, UnknownError>())
+
+    const makeLayer = <TContext = {}>(
+      props: Omit<LiveStoreContextProps<TSchema, TContext>, 'storeId'>,
+    ): Layer.Layer<StoreContextId<TSchema, TStoreId>, UnknownError | Cause.TimeoutException, OtelTracer.OtelTracer> =>
+      pipe(
+        Effect.gen(function* () {
+          const store = yield* createStore({
+            schema: props.schema,
+            storeId,
+            adapter: props.adapter,
+            batchUpdates: props.batchUpdates,
+            ...omitUndefineds({
+              context: props.context,
+              boot: props.boot,
+              disableDevtools: props.disableDevtools,
+              onBootStatus: props.onBootStatus,
+              syncPayload: props.syncPayload,
+              syncPayloadSchema: props.syncPayloadSchema,
+            }),
+          })
+
+          globalThis.__debugLiveStore ??= {}
+          if (Object.keys(globalThis.__debugLiveStore).length === 0) {
+            globalThis.__debugLiveStore._ = store
+          }
+          globalThis.__debugLiveStore[storeId] = store
+
+          const ctx: RunningType = { stage: 'running', store: store as StoreClass<TSchema> }
+
+          // Also fulfill the deferred if it exists in context
+          yield* Effect.flatMap(Effect.serviceOption(DeferredTag), (optDeferred) =>
+            optDeferred._tag === 'Some' ? Deferred.succeed(optDeferred.value, ctx) : Effect.void,
+          )
+
+          return ctx
+        }),
+        Effect.timeout(Duration.minutes(5)),
+        Effect.withSpan(`@livestore/effect:makeStoreContext:${storeId}`),
+        Layer.scoped(Tag),
+        Layer.withSpan(`LiveStore:${storeId}`),
+        Layer.provide(DeferredLayer),
+      )
+
+    const fromDeferred: Layer.Layer<
+      StoreContextId<TSchema, TStoreId>,
+      UnknownError,
+      DeferredContextId<TStoreId>
+    > = pipe(
+      Effect.gen(function* () {
+        const deferred = yield* DeferredTag
+        const ctx = yield* deferred
+        return Layer.succeed(Tag, ctx)
+      }),
+      Layer.unwrapScoped,
+    )
+
+    return {
+      storeId,
+      Tag,
+      DeferredTag,
+      Layer: makeLayer,
+      DeferredLayer,
+      fromDeferred,
+    }
+  }

package/src/effect/mod.ts

@@ -4,4 +4,16 @@ export {
   LiveStoreContextRunning as LiveStoreContext,
   LiveStoreContextRunning,
 } from '../store/create-store.ts'
-export { LiveStoreContextDeferred, LiveStoreContextLayer } from './LiveStore.ts'
+// Store.Tag - Idiomatic Effect API
+// Legacy API (deprecated)
+export {
+  type DeferredContextId,
+  LiveStoreContextDeferred,
+  LiveStoreContextLayer,
+  makeStoreContext,
+  Store,
+  type StoreContext,
+  type StoreContextId,
+  type StoreLayerProps,
+  type StoreTagClass,
+} from './LiveStore.ts'

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

@@ -23,46 +23,98 @@ 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
   [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 => {
@@ -72,12 +124,26 @@ export const depsToString = (deps: DepKey): string => {
   return deps.filter(isNotNil).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
   [Hash.symbol](): number
@@ -88,39 +154,51 @@ export namespace LiveQueryDef {
 }
 
 /**
- * A LiveQuery is stateful
+ * 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>
 }
 
@@ -176,6 +254,22 @@ export abstract class LiveStoreQueryBase<TResult> implements LiveQuery<TResult>
   //   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,