@livestore/livestore 0.4.0-dev.9 → 0.4.0

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

@@ -7,15 +7,16 @@ import {
   QueryBuilderAstSymbol,
   replaceSessionIdSymbol,
   SessionIdSymbol,
-  UnexpectedError,
+  UnknownError,
 } from '@livestore/common'
-import { deepEqual, omitUndefineds, shouldNeverHappen } from '@livestore/utils'
+import { deepEqual, objectToString, omitUndefineds, shouldNeverHappen } from '@livestore/utils'
 import { Equal, Hash, Predicate, Schema, TreeFormatter } from '@livestore/utils/effect'
 import * as otel from '@opentelemetry/api'
 
 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'
@@ -102,7 +103,7 @@ 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 +112,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
@@ -154,12 +155,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 +168,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 */
@@ -215,7 +216,7 @@ export class LiveStoreDbQuery<TResultSchema, TResult = TResultSchema> extends Li
 
     const schemaRef: { current: Schema.Schema<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: {
@@ -253,7 +254,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 +270,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 +297,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 +310,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)})`
@@ -341,7 +342,7 @@ export class LiveStoreDbQuery<TResultSchema, TResult = TResultSchema> extends Li
           'db:...', // NOTE span name will be overridden further down
           {
             attributes: {
-              'livestore.debugRefreshReason': Predicate.hasProperty(debugRefreshReason, 'label')
+              'livestore.debugRefreshReason': Predicate.hasProperty(debugRefreshReason, 'label') === true
                 ? (debugRefreshReason.label as string)
                 : debugRefreshReason?._tag,
             },
@@ -356,7 +357,7 @@ export class LiveStoreDbQuery<TResultSchema, TResult = TResultSchema> extends Li
               execBeforeFirstRunRef.current = undefined
             }
 
-            const queryInputResult = isThunk(queryInputRaw$OrQueryInputRaw)
+            const queryInputResult = isThunk(queryInputRaw$OrQueryInputRaw) === true
               ? (get(queryInputRaw$OrQueryInputRaw, otelContext, debugRefreshReason) as TQueryInputRaw)
               : (queryInputRaw$OrQueryInputRaw as TQueryInputRaw)
 
@@ -364,28 +365,30 @@ export class LiveStoreDbQuery<TResultSchema, TResult = TResultSchema> extends Li
             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)
+              replaceSessionIdSymbol(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,
+              bindValues !== undefined ? prepareBindValues(bindValues, sqlString) : undefined,
               {
-                queriedTables: queriedTablesRef.current,
                 otelContext,
+                ...(queriedTablesRef.current !== undefined ? { queriedTables: queriedTablesRef.current } : {}),
               },
             )
 

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

@@ -1,7 +1,8 @@
-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'

package/src/live-queries/signal.ts

@@ -6,6 +6,48 @@ 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'
 
+/**
+ * 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?: {
@@ -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>

package/src/mod.ts

@@ -35,14 +35,31 @@ export {
   signal,
 } from './live-queries/mod.ts'
 export { emptyDebugInfo, SqliteDbWrapper } from './SqliteDbWrapper.ts'
-export { type CreateStoreOptions, createStore, createStorePromise } from './store/create-store.ts'
+export {
+  type CreateStoreOptions,
+  type CreateStoreOptionsPromise,
+  createStore,
+  createStorePromise,
+} from './store/create-store.ts'
+export { type RegistryStoreOptions, StoreRegistry, storeOptions } from './store/StoreRegistry.ts'
 export { Store } from './store/store.ts'
-export type { OtelOptions, QueryDebugInfo, RefreshReason, Unsubscribe } from './store/store-types.ts'
 export {
+  isLiveQueryDef,
+  isLiveQueryInstance,
+  isQueryable,
   type LiveStoreContext,
   type LiveStoreContextRunning,
   makeShutdownDeferred,
+  type OtelOptions,
+  type Queryable,
+  type QueryDebugInfo,
+  type RefreshReason,
   type ShutdownDeferred,
+  type StoreInternals,
+  StoreInternalsSymbol,
+  type SubscribeOptions,
+  type SyncStatus,
+  type Unsubscribe,
 } from './store/store-types.ts'
 export { exposeDebugUtils } from './utils/dev.ts'
 export * from './utils/stack-info.ts'

package/src/reactive.test.ts

@@ -1,4 +1,5 @@
 import { describe, expect, it } from 'vitest'
+
 import type { DebugRefreshReasonBase, DebugThunkInfo } from './reactive.ts'
 import { ReactiveGraph } from './reactive.ts'
 
@@ -142,7 +143,7 @@ describe('a trivial graph', () => {
       expect(numberOfEffectRuns).toBe(0)
       const effect = graph.makeEffect((get) => {
         // establish a dependency on thunk c and mutate an outside value
-        expect(get(c)).toBe(aHasChanged ? 3 : 4)
+        expect(get(c)).toBe(aHasChanged === true ? 3 : 4)
         numberOfEffectRuns++
       })
 
@@ -562,7 +563,7 @@ describe('bug fix: node corruption protection', () => {
 
     let firstRun = true
     const effect = graph.makeEffect((get) => {
-      if (firstRun) {
+      if (firstRun !== undefined) {
         firstRun = false
         graph.destroyNode(thunk1) // Destroy dependency mid-execution
       }

package/src/reactive.ts

@@ -21,10 +21,11 @@
 //   is maintained eagerly as edges are added and removed.)
 // - At every thunk we check value equality with the previous value and cutoff propagation if possible.
 
+import type * as otel from '@opentelemetry/api'
+
 import { BoundArray } from '@livestore/common'
 import { deepEqual, omitUndefineds, shouldNeverHappen } from '@livestore/utils'
 import type { Types } from '@livestore/utils/effect'
-import type * as otel from '@opentelemetry/api'
 // import { getDurationMsFromSpan } from './otel.ts'
 
 export const NOT_REFRESHED_YET = Symbol.for('NOT_REFRESHED_YET')
@@ -32,8 +33,8 @@ export type NOT_REFRESHED_YET = typeof NOT_REFRESHED_YET
 
 export type GetAtom = <T>(
   atom: Atom<T, any, any>,
-  otelContext?: otel.Context | undefined,
-  debugRefreshReason?: TODO | undefined,
+  otelContext?: otel.Context  ,
+  debugRefreshReason?: TODO  ,
 ) => T
 
 export type Ref<T, TContext, TDebugRefreshReason extends DebugRefreshReason> = {
@@ -47,7 +48,7 @@ export type Ref<T, TContext, TDebugRefreshReason extends DebugRefreshReason> = {
   super: Set<Thunk<any, TContext, TDebugRefreshReason> | Effect<TDebugRefreshReason>>
   label?: string | undefined
   /** Container for meta information (e.g. the LiveStore Store) */
-  meta?: any | undefined
+  meta?: unknown
   equal: (a: T, b: T) => boolean
   refreshes: number
 }
@@ -63,7 +64,7 @@ export type Thunk<TResult, TContext, TDebugRefreshReason extends DebugRefreshRea
   super: Set<Thunk<any, TContext, TDebugRefreshReason> | Effect<TDebugRefreshReason>>
   label?: string | undefined
   /** Container for meta information (e.g. the LiveStore Store) */
-  meta?: any | undefined
+  meta?: unknown
   equal: (a: TResult, b: TResult) => boolean
   recomputations: number
 
@@ -78,7 +79,7 @@ export type Effect<TDebugRefreshReason extends DebugRefreshReason> = {
   _tag: 'effect'
   id: string
   isDestroyed: boolean
-  doEffect: (otelContext?: otel.Context | undefined, debugRefreshReason?: TDebugRefreshReason | undefined) => void
+  doEffect: (otelContext?: otel.Context  , debugRefreshReason?: TDebugRefreshReason  ) => void
   sub: Set<Atom<any, TODO, TODO>>
   label?: string | undefined
   invocations: number
@@ -91,7 +92,7 @@ export type Node<T, TContext, TDebugRefreshReason extends DebugRefreshReason> =
 export const isThunk = <T, TContext, TDebugRefreshReason extends DebugRefreshReason>(
   obj: unknown,
 ): obj is Thunk<T, TContext, TDebugRefreshReason> => {
-  return typeof obj === 'object' && obj !== null && '_tag' in obj && (obj as any)._tag === 'thunk'
+  return typeof obj === 'object' && obj !== null && '_tag' in obj && (obj as { _tag: unknown })._tag === 'thunk'
 }
 
 export type DebugThunkInfo<T extends string = string> = {
@@ -203,9 +204,7 @@ export class ReactiveGraph<
 
   debugRefreshInfos: BoundArray<RefreshDebugInfo<TDebugRefreshReason, TDebugThunkInfo>> = new BoundArray(200)
 
-  private currentDebugRefresh:
-    | { refreshedAtoms: AtomDebugInfo<TDebugThunkInfo>[]; startMs: DOMHighResTimeStamp }
-    | undefined
+  private currentDebugRefresh: { refreshedAtoms: AtomDebugInfo<TDebugThunkInfo>[]; startMs: number } | undefined
 
   private deferredEffects: Map<Effect<TDebugRefreshReason>, Set<TDebugRefreshReason>> = new Map()
 
@@ -253,7 +252,7 @@ export class ReactiveGraph<
           meta?: any
           equal?: (a: T, b: T) => boolean
         }
-      | undefined,
+       ,
   ): Thunk<T, TContext, TDebugRefreshReason> {
     const thunk: Thunk<T, TContext, TDebugRefreshReason> = {
       _tag: 'thunk',
@@ -262,10 +261,10 @@ export class ReactiveGraph<
       isDirty: true,
       isDestroyed: false,
       computeResult: (otelContext, debugRefreshReason) => {
-        if (thunk.isDirty) {
+        if (thunk.isDirty === true) {
           const neededCurrentRefresh = this.currentDebugRefresh === undefined
           let localDebugRefresh: { refreshedAtoms: any[]; startMs: number } | undefined
-          if (neededCurrentRefresh) {
+          if (neededCurrentRefresh === true) {
             // Use local variable to prevent corruption from nested computations
             localDebugRefresh = { refreshedAtoms: [], startMs: performance.now() }
             this.currentDebugRefresh = localDebugRefresh
@@ -292,7 +291,7 @@ export class ReactiveGraph<
             debugRefreshReason,
           )
 
-          const resultChanged = thunk.equal(thunk.previousResult as T, result) === false
+          const resultChanged = ! thunk.equal(thunk.previousResult as T, result)
 
           const debugInfoForAtom = {
             atom: serializeAtom(thunk, false),
@@ -302,7 +301,7 @@ export class ReactiveGraph<
 
           // Use currentDebugRefresh if available (could be from parent or local)
           const debugRefresh = localDebugRefresh ?? this.currentDebugRefresh
-          if (debugRefresh) {
+          if (debugRefresh !== undefined) {
             debugRefresh.refreshedAtoms.push(debugInfoForAtom)
           }
 
@@ -310,7 +309,7 @@ export class ReactiveGraph<
           thunk.previousResult = result
           thunk.recomputations++
 
-          if (neededCurrentRefresh && localDebugRefresh) {
+          if (neededCurrentRefresh === true && localDebugRefresh !== undefined) {
             // Use local reference which can't be corrupted by nested calls
             const refreshedAtoms = localDebugRefresh.refreshedAtoms
             const durationMs = performance.now() - localDebugRefresh.startMs
@@ -385,7 +384,7 @@ export class ReactiveGraph<
       otelContext: otel.Context | undefined,
       debugRefreshReason: DebugRefreshReason | undefined,
     ) => void,
-    options?: { label?: string } | undefined,
+    options?: { label?: string }  ,
   ): Effect<TDebugRefreshReason> {
     const effect: Effect<TDebugRefreshReason> = {
       _tag: 'effect',
@@ -429,7 +428,7 @@ export class ReactiveGraph<
           debugRefreshReason?: TDebugRefreshReason
           otelContext?: otel.Context
         }
-      | undefined,
+       ,
   ) {
     this.setRefs([[ref, val]], options)
   }
@@ -442,7 +441,7 @@ export class ReactiveGraph<
           debugRefreshReason?: TDebugRefreshReason
           otelContext?: otel.Context
         }
-      | undefined,
+       ,
   ) {
     const effectsToRefresh = new Set<Effect<TDebugRefreshReason>>()
     for (const [ref, val] of refs) {
@@ -452,7 +451,7 @@ export class ReactiveGraph<
       markSuperCompDirtyRec(ref, effectsToRefresh)
     }
 
-    if (options?.skipRefresh) {
+    if (options?.skipRefresh === true) {
       for (const effect of effectsToRefresh) {
         if (this.deferredEffects.has(effect) === false) {
           this.deferredEffects.set(effect, new Set())
@@ -598,11 +597,11 @@ const compute = <T>(
   debugRefreshReason: DebugRefreshReason | undefined,
 ): T => {
   // const __getResult = atom._tag === 'thunk' ? atom.__getResult.toString() : ''
-  if (atom.isDestroyed) {
+  if (atom.isDestroyed === true) {
     shouldNeverHappen(`LiveStore Error: Attempted to compute destroyed ${atom._tag} (${atom.id}): ${atom.label ?? ''}`)
   }
 
-  if (atom.isDirty) {
+  if (atom.isDirty === true) {
     // console.log('atom is dirty', atom.id, atom.label ?? '', atom._tag, __getResult)
     const result = atom.computeResult(otelContext, debugRefreshReason)
     atom.isDirty = false
@@ -641,7 +640,7 @@ const serializeAtom = (atom: Atom<any, unknown, any>, includeResult: boolean): S
     super_.push(a.id)
   }
 
-  const previousResult: EncodedOption<string> = includeResult
+  const previousResult: EncodedOption<string> = includeResult === true
     ? encodedOptionSome(
         atom.previousResult === NOT_REFRESHED_YET ? '"SYMBOL_NOT_REFRESHED_YET"' : JSON.stringify(atom.previousResult),
       )