@livestore/livestore 0.2.0 → 0.3.0-dev.11

package/src/store/store.ts

@@ -1,36 +1,72 @@
-import type { ClientSession, ParamsObject, PreparedBindValues, QueryBuilder } from '@livestore/common'
+import type {
+  ClientSession,
+  ClientSessionSyncProcessor,
+  ParamsObject,
+  PreparedBindValues,
+  QueryBuilder,
+  UnexpectedError,
+} from '@livestore/common'
 import {
+  Devtools,
   getExecArgsFromMutation,
   getResultSchema,
+  IntentionalShutdownCause,
   isQueryBuilder,
+  liveStoreVersion,
+  makeClientSessionSyncProcessor,
   prepareBindValues,
   QueryBuilderAstSymbol,
   replaceSessionIdSymbol,
 } from '@livestore/common'
-import type { LiveStoreSchema, MutationEvent } from '@livestore/common/schema'
+import type { LiveStoreSchema } from '@livestore/common/schema'
 import {
-  isPartialMutationEvent,
-  makeMutationEventSchemaMemo,
+  MutationEvent,
   SCHEMA_META_TABLE,
   SCHEMA_MUTATIONS_META_TABLE,
   SESSION_CHANGESET_META_TABLE,
 } from '@livestore/common/schema'
-import { assertNever, shouldNeverHappen } from '@livestore/utils'
+import { assertNever, isDevEnv } from '@livestore/utils'
 import type { Scope } from '@livestore/utils/effect'
-import { Data, Effect, FiberSet, Inspectable, MutableHashMap, Runtime, Schema, Stream } from '@livestore/utils/effect'
+import {
+  Cause,
+  Data,
+  Effect,
+  Inspectable,
+  MutableHashMap,
+  OtelTracer,
+  Runtime,
+  Schema,
+  Stream,
+} from '@livestore/utils/effect'
+import { nanoid } from '@livestore/utils/nanoid'
 import * as otel from '@opentelemetry/api'
-import type { GraphQLSchema } from 'graphql'
-
-import type { LiveQuery, QueryContext, ReactivityGraph } from '../live-queries/base-class.js'
+import { type GraphQLSchema } from 'graphql'
+
+import type {
+  ILiveQueryRefDef,
+  LiveQuery,
+  LiveQueryDef,
+  ReactivityGraph,
+  ReactivityGraphContext,
+} from '../live-queries/base-class.js'
+import { makeReactivityGraph } from '../live-queries/base-class.js'
 import type { Ref } from '../reactive.js'
 import { makeExecBeforeFirstRun } from '../row-query-utils.js'
-import { SynchronousDatabaseWrapper } from '../SynchronousDatabaseWrapper.js'
+import { SqliteDbWrapper } from '../SqliteDbWrapper.js'
 import { ReferenceCountedSet } from '../utils/data-structures.js'
 import { downloadBlob, exposeDebugUtils } from '../utils/dev.js'
 import { getDurationMsFromSpan } from '../utils/otel.js'
-import type { BaseGraphQLContext, RefreshReason, StoreMutateOptions, StoreOptions, StoreOtel } from './store-types.js'
-
-if (import.meta.env.DEV) {
+import type { StackInfo } from '../utils/stack-info.js'
+import type {
+  BaseGraphQLContext,
+  RefreshReason,
+  StoreMutateOptions,
+  StoreOptions,
+  StoreOtel,
+  Unsubscribe,
+} from './store-types.js'
+
+if (isDevEnv()) {
   exposeDebugUtils()
 }
 
@@ -40,7 +76,7 @@ export class Store<
 > extends Inspectable.Class {
   readonly storeId: string
   reactivityGraph: ReactivityGraph
-  syncDbWrapper: SynchronousDatabaseWrapper
+  sqliteDbWrapper: SqliteDbWrapper
   clientSession: ClientSession
   schema: LiveStoreSchema
   graphQLSchema?: GraphQLSchema
@@ -50,9 +86,8 @@ export class Store<
    * Note we're using `Ref<null>` here as we don't care about the value but only about *that* something has changed.
    * This only works in combination with `equal: () => false` which will always trigger a refresh.
    */
-  tableRefs: { [key: string]: Ref<null, QueryContext, RefreshReason> }
+  tableRefs: { [key: string]: Ref<null, ReactivityGraphContext, RefreshReason> }
 
-  private fiberSet: FiberSet.FiberSet
   private runtime: Runtime.Runtime<Scope.Scope>
 
   /** RC-based set to see which queries are currently subscribed to */
@@ -61,36 +96,91 @@ export class Store<
   // NOTE this is currently exposed for the Devtools databrowser to emit mutation events
   readonly __mutationEventSchema
   private unsyncedMutationEvents
+  private syncProcessor: ClientSessionSyncProcessor
+  readonly lifetimeScope: Scope.Scope
+
+  readonly boot: Effect.Effect<void, UnexpectedError, Scope.Scope>
 
   // #region constructor
-  private constructor({
+  constructor({
     clientSession,
     schema,
     graphQLOptions,
-    reactivityGraph,
     otelOptions,
     disableDevtools,
     batchUpdates,
     unsyncedMutationEvents,
     storeId,
-    fiberSet,
+    lifetimeScope,
     runtime,
   }: StoreOptions<TGraphQLContext, TSchema>) {
     super()
 
     this.storeId = storeId
-
     this.unsyncedMutationEvents = unsyncedMutationEvents
 
-    this.syncDbWrapper = new SynchronousDatabaseWrapper({ otel: otelOptions, db: clientSession.syncDb })
+    this.sqliteDbWrapper = new SqliteDbWrapper({ otel: otelOptions, db: clientSession.sqliteDb })
     this.clientSession = clientSession
     this.schema = schema
 
-    this.fiberSet = fiberSet
+    this.lifetimeScope = lifetimeScope
     this.runtime = runtime
 
-    // TODO refactor
-    this.__mutationEventSchema = makeMutationEventSchemaMemo(schema)
+    const reactivityGraph = makeReactivityGraph()
+
+    const syncSpan = otelOptions.tracer.startSpan('LiveStore:sync', {}, otelOptions.rootSpanContext)
+
+    this.syncProcessor = makeClientSessionSyncProcessor({
+      schema,
+      clientSession,
+      runtime,
+      applyMutation: (mutationEventDecoded, { otelContext, withChangeset }) => {
+        const mutationDef = schema.mutations.get(mutationEventDecoded.mutation)!
+        const execArgsArr = getExecArgsFromMutation({
+          mutationDef,
+          mutationEvent: { decoded: mutationEventDecoded, encoded: undefined },
+        })
+
+        const writeTablesForEvent = new Set<string>()
+
+        const exec = () => {
+          for (const {
+            statementSql,
+            bindValues,
+            writeTables = this.sqliteDbWrapper.getTablesUsed(statementSql),
+          } of execArgsArr) {
+            this.sqliteDbWrapper.execute(statementSql, bindValues, { otelContext, writeTables })
+
+            // durationMsTotal += durationMs
+            writeTables.forEach((table) => writeTablesForEvent.add(table))
+          }
+        }
+
+        let sessionChangeset: Uint8Array | undefined
+        if (withChangeset === true) {
+          sessionChangeset = this.sqliteDbWrapper.withChangeset(exec).changeset
+        } else {
+          exec()
+        }
+
+        return { writeTables: writeTablesForEvent, sessionChangeset }
+      },
+      rollback: (changeset) => {
+        this.sqliteDbWrapper.rollback(changeset)
+      },
+      refreshTables: (tables) => {
+        const tablesToUpdate = [] as [Ref<null, ReactivityGraphContext, RefreshReason>, null][]
+        for (const tableName of tables) {
+          const tableRef = this.tableRefs[tableName]
+          assertNever(tableRef !== undefined, `No table ref found for ${tableName}`)
+          tablesToUpdate.push([tableRef!, null])
+        }
+        reactivityGraph.setRefs(tablesToUpdate)
+      },
+      span: syncSpan,
+    })
+
+    this.__mutationEventSchema = MutationEvent.makeMutationEventSchemaMemo(schema)
 
     // TODO generalize the `tableRefs` concept to allow finer-grained refs
     this.tableRefs = {}
@@ -105,6 +195,8 @@ export class Store<
     this.reactivityGraph = reactivityGraph
     this.reactivityGraph.context = {
       store: this as unknown as Store<BaseGraphQLContext, LiveStoreSchema>,
+      liveQueryRCMap: new Map(),
+      reactivityGraph: new WeakRef(reactivityGraph),
       otelTracer: otelOptions.tracer,
       rootOtelContext: otelQueriesSpanContext,
       effectsWrapper: batchUpdates,
@@ -141,26 +233,10 @@ export class Store<
 
     if (graphQLOptions) {
       this.graphQLSchema = graphQLOptions.schema
-      this.graphQLContext = graphQLOptions.makeContext(
-        this.syncDbWrapper,
-        this.otel.tracer,
-        clientSession.coordinator.sessionId,
-      )
+      this.graphQLContext = graphQLOptions.makeContext(this.sqliteDbWrapper, this.otel.tracer, clientSession.sessionId)
     }
 
-    Effect.gen(this, function* () {
-      yield* this.clientSession.coordinator.syncMutations.pipe(
-        Stream.tapChunk((mutationsEventsDecodedChunk) =>
-          Effect.sync(() => {
-            this.mutate({ wasSyncMessage: true }, ...mutationsEventsDecodedChunk)
-          }),
-        ),
-        Stream.runDrain,
-        Effect.interruptible,
-        Effect.withSpan('LiveStore:syncMutations'),
-        Effect.forkScoped,
-      )
-
+    this.boot = Effect.gen(this, function* () {
       yield* Effect.addFinalizer(() =>
         Effect.sync(() => {
           // Remove all table refs from the reactivity graph
@@ -171,60 +247,84 @@ export class Store<
           }
 
           // End the otel spans
-          otel.trace.getSpan(this.otel.mutationsSpanContext)!.end()
-          otel.trace.getSpan(this.otel.queriesSpanContext)!.end()
+          syncSpan.end()
+          mutationsSpan.end()
+          queriesSpan.end()
         }),
       )
 
-      yield* Effect.never // to keep the scope alive and bind to the parent scope
-    }).pipe(Effect.scoped, Effect.withSpan('LiveStore:constructor'), this.runEffectFork)
-  }
-  // #endregion constructor
-
-  static createStore = <TGraphQLContext extends BaseGraphQLContext, TSchema extends LiveStoreSchema = LiveStoreSchema>(
-    storeOptions: StoreOptions<TGraphQLContext, TSchema>,
-    parentSpan: otel.Span,
-  ): Store<TGraphQLContext, TSchema> => {
-    const ctx = otel.trace.setSpan(otel.context.active(), parentSpan)
-    return storeOptions.otelOptions.tracer.startActiveSpan('LiveStore:createStore', {}, ctx, (span) => {
-      try {
-        return new Store(storeOptions)
-      } finally {
-        span.end()
-      }
+      yield* this.syncProcessor.boot
     })
   }
+  // #endregion constructor
 
   get sessionId(): string {
-    return this.clientSession.coordinator.sessionId
+    return this.clientSession.sessionId
   }
 
   /**
    * Subscribe to the results of a query
    * Returns a function to cancel the subscription.
+   *
+   * @example
+   * ```ts
+   * const unsubscribe = store.subscribe(query$, { onUpdate: (result) => console.log(result) })
+   * ```
    */
   subscribe = <TResult>(
-    query$: LiveQuery<TResult, any>,
-    onNewValue: (value: TResult) => void,
-    onUnsubsubscribe?: () => void,
-    options?: { label?: string; otelContext?: otel.Context; skipInitialRun?: boolean } | undefined,
-  ): (() => void) =>
+    query: LiveQueryDef<TResult, any> | LiveQuery<TResult, any>,
+    options: {
+      /** Called when the query result has changed */
+      onUpdate: (value: TResult) => void
+      onSubscribe?: (query$: LiveQuery<TResult, any>) => 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.otel.tracer.startActiveSpan(
       `LiveStore.subscribe`,
-      { attributes: { label: options?.label, queryLabel: query$.label } },
+      { attributes: { label: options?.label, queryLabel: 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 =
+          query._tag === 'def'
+            ? query.make(this.reactivityGraph.context!)
+            : {
+                value: query,
+                deref: () => {},
+              }
+        const query$ = queryRcRef.value
+
         const label = `subscribe:${options?.label}`
-        const effect = this.reactivityGraph.makeEffect((get) => onNewValue(get(query$.results$)), { label })
+        const effect = this.reactivityGraph.makeEffect(
+          (get, _otelContext, debugRefreshReason) =>
+            options.onUpdate(get(query$.results$, otelContext, debugRefreshReason)),
+          { label },
+        )
+
+        if (options?.stackInfo) {
+          query$.activeSubscriptions.add(options.stackInfo)
+        }
+
+        options?.onSubscribe?.(query$)
 
         this.activeQueries.add(query$ as LiveQuery<TResult>)
 
         // Running effect right away to get initial value (unless `skipInitialRun` is set)
-        if (options?.skipInitialRun !== true) {
-          effect.doEffect(otelContext)
+        if (options?.skipInitialRun !== true && !query$.isDestroyed) {
+          effect.doEffect(otelContext, { _tag: 'subscribe.initial', label: `subscribe-initial-run:${options?.label}` })
         }
 
         const unsubscribe = () => {
@@ -232,7 +332,14 @@ export class Store<
           try {
             this.reactivityGraph.destroyNode(effect)
             this.activeQueries.remove(query$ as LiveQuery<TResult>)
-            onUnsubsubscribe?.()
+
+            if (options?.stackInfo) {
+              query$.activeSubscriptions.delete(options.stackInfo)
+            }
+
+            queryRcRef.deref()
+
+            options?.onUnsubsubscribe?.()
           } finally {
             span.end()
           }
@@ -242,13 +349,54 @@ export class Store<
       },
     )
 
+  subscribeStream = <TResult>(
+    query$: LiveQueryDef<TResult, any>,
+    options?: { label?: string; skipInitialRun?: boolean } | undefined,
+  ): Stream.Stream<TResult> =>
+    Stream.asyncPush<TResult>((emit) =>
+      Effect.gen(this, function* () {
+        const otelSpan = yield* OtelTracer.currentOtelSpan.pipe(
+          Effect.catchTag('NoSuchElementException', () => Effect.succeed(undefined)),
+        )
+        const otelContext = otelSpan ? otel.trace.setSpan(otel.context.active(), otelSpan) : otel.context.active()
+
+        yield* Effect.acquireRelease(
+          Effect.sync(() =>
+            this.subscribe(query$, {
+              onUpdate: (result) => emit.single(result),
+              otelContext,
+              label: options?.label,
+            }),
+          ),
+          (unsub) => Effect.sync(() => unsub()),
+        )
+      }),
+    )
+
+  /**
+   * Synchronously queries the database without creating a LiveQuery.
+   * This is useful for queries that don't need to be reactive.
+   *
+   * Example: Query builder
+   * ```ts
+   * const completedTodos = store.query(tables.todo.where({ complete: true }))
+   * ```
+   *
+   * Example: Raw SQL query
+   * ```ts
+   * const completedTodos = store.query({ query: 'SELECT * FROM todo WHERE complete = 1', bindValues: {} })
+   * ```
+   */
   query = <TResult>(
-    query: QueryBuilder<TResult, any, any> | LiveQuery<TResult, any> | { query: string; bindValues: ParamsObject },
-    options?: { otelContext?: otel.Context },
+    query:
+      | QueryBuilder<TResult, any, any>
+      | LiveQuery<TResult, any>
+      | LiveQueryDef<TResult, any>
+      | { query: string; bindValues: ParamsObject },
+    options?: { otelContext?: otel.Context; debugRefreshReason?: RefreshReason },
   ): TResult => {
     if (typeof query === 'object' && 'query' in query && 'bindValues' in query) {
-      return this.syncDbWrapper.select(query.query, {
-        bindValues: prepareBindValues(query.bindValues, query.query),
+      return this.sqliteDbWrapper.select(query.query, prepareBindValues(query.bindValues, query.query), {
         otelContext: options?.otelContext,
       }) as any
     } else if (isQueryBuilder(query)) {
@@ -264,17 +412,38 @@ export class Store<
 
       const sqlRes = query.asSql()
       const schema = getResultSchema(query)
-      const rawRes = this.syncDbWrapper.select(sqlRes.query, {
-        bindValues: sqlRes.bindValues as any as PreparedBindValues,
+      const rawRes = this.sqliteDbWrapper.select(sqlRes.query, sqlRes.bindValues as any as PreparedBindValues, {
         otelContext: options?.otelContext,
         queriedTables: new Set([query[QueryBuilderAstSymbol].tableDef.sqliteDef.name]),
       })
       return Schema.decodeSync(schema)(rawRes)
+    } else if (query._tag === 'def') {
+      const query$ = query.make(this.reactivityGraph.context!)
+      const result = this.query(query$.value, options)
+      query$.deref()
+      return result
     } else {
-      return query.run(options?.otelContext)
+      return query.run({ otelContext: options?.otelContext, debugRefreshReason: options?.debugRefreshReason })
     }
   }
 
+  // makeLive: {
+  //   <T>(def: LiveQueryDef<T, any>): LiveQuery<T, any>
+  //   <T>(def: ILiveQueryRefDef<T>): ILiveQueryRef<T>
+  // } = (def: any) => {
+  //   if (def._tag === 'live-ref-def') {
+  //     return (def as ILiveQueryRefDef<any>).make(this.reactivityGraph.context!)
+  //   } else {
+  //     return (def as LiveQueryDef<any, any>).make(this.reactivityGraph.context!) as any
+  //   }
+  // }
+
+  setRef = <T>(refDef: ILiveQueryRefDef<T>, value: T): void => {
+    const ref = refDef.make(this.reactivityGraph.context!)
+    ref.value.set(value)
+    ref.deref()
+  }
+
   // #region mutate
   mutate: {
     <const TMutationArg extends ReadonlyArray<MutationEvent.PartialForSchema<TSchema>>>(...list: TMutationArg): void
@@ -294,39 +463,15 @@ export class Store<
       ) => void,
     ): void
   } = (firstMutationOrTxnFnOrOptions: any, ...restMutations: any[]) => {
-    let mutationsEvents: MutationEvent.ForSchema<TSchema>[]
-    let options: StoreMutateOptions | undefined
+    const { mutationsEvents, options } = this.getMutateArgs(firstMutationOrTxnFnOrOptions, restMutations)
 
-    if (typeof firstMutationOrTxnFnOrOptions === 'function') {
-      // TODO ensure that function is synchronous and isn't called in a async way (also write tests for this)
-      mutationsEvents = firstMutationOrTxnFnOrOptions((arg: any) => mutationsEvents.push(arg))
-    } else if (
-      firstMutationOrTxnFnOrOptions?.label !== undefined ||
-      firstMutationOrTxnFnOrOptions?.skipRefresh !== undefined ||
-      firstMutationOrTxnFnOrOptions?.wasSyncMessage !== undefined ||
-      firstMutationOrTxnFnOrOptions?.persisted !== undefined
-    ) {
-      options = firstMutationOrTxnFnOrOptions
-      mutationsEvents = restMutations
-    } else if (firstMutationOrTxnFnOrOptions === undefined) {
-      // When `mutate` is called with no arguments (which sometimes happens when dynamically filtering mutations)
-      mutationsEvents = []
-    } else {
-      mutationsEvents = [firstMutationOrTxnFnOrOptions, ...restMutations]
+    for (const mutationEvent of mutationsEvents) {
+      replaceSessionIdSymbol(mutationEvent.args, this.clientSession.sessionId)
     }
 
-    mutationsEvents = mutationsEvents.filter(
-      (_) => _.id === undefined || !MutableHashMap.has(this.unsyncedMutationEvents, Data.struct(_.id)),
-    )
-
-    if (mutationsEvents.length === 0) {
-      return
-    }
+    if (mutationsEvents.length === 0) return
 
-    const label = options?.label ?? 'mutate'
     const skipRefresh = options?.skipRefresh ?? false
-    const wasSyncMessage = options?.wasSyncMessage ?? false
-    const persisted = options?.persisted ?? true
 
     const mutationsSpan = otel.trace.getSpan(this.otel.mutationsSpanContext)!
     mutationsSpan.addEvent('mutate')
@@ -337,59 +482,41 @@ export class Store<
 
     let durationMs: number
 
-    const res = this.otel.tracer.startActiveSpan(
+    return this.otel.tracer.startActiveSpan(
       'LiveStore:mutate',
-      { attributes: { 'livestore.mutateLabel': label } },
-      this.otel.mutationsSpanContext,
+      {
+        attributes: {
+          'livestore.mutationEventsCount': mutationsEvents.length,
+          'livestore.mutationEventTags': mutationsEvents.map((_) => _.mutation),
+          'livestore.mutateLabel': options?.label,
+        },
+        links: options?.spanLinks,
+      },
+      options?.otelContext ?? this.otel.mutationsSpanContext,
       (span) => {
         const otelContext = otel.trace.setSpan(otel.context.active(), span)
 
         try {
-          const writeTables: Set<string> = new Set()
-
-          this.otel.tracer.startActiveSpan(
-            'LiveStore:processWrites',
-            { attributes: { 'livestore.mutateLabel': label } },
-            otel.trace.setSpan(otel.context.active(), span),
-            (span) => {
-              try {
-                const otelContext = otel.trace.setSpan(otel.context.active(), span)
-
-                const applyMutations = () => {
-                  for (const mutationEvent of mutationsEvents) {
-                    try {
-                      const { writeTables: writeTablesForEvent } = this.mutateWithoutRefresh(mutationEvent, {
-                        otelContext,
-                        // NOTE if it was a sync message, it's already coming from the coordinator, so we can skip the coordinator
-                        coordinatorMode: wasSyncMessage ? 'skip-coordinator' : persisted ? 'default' : 'skip-persist',
-                      })
-                      for (const tableName of writeTablesForEvent) {
-                        writeTables.add(tableName)
-                      }
-                    } catch (e: any) {
-                      console.error(e, mutationEvent)
-                      throw e
-                    }
-                  }
-                }
-
-                if (mutationsEvents.length > 1) {
-                  // TODO: what to do about coordinator transaction here?
-                  this.syncDbWrapper.txn(applyMutations)
-                } else {
-                  applyMutations()
-                }
-              } catch (e: any) {
-                console.error(e)
-                span.setStatus({ code: otel.SpanStatusCode.ERROR, message: e.toString() })
-                throw e
-              } finally {
-                span.end()
+          const { writeTables } = (() => {
+            try {
+              const applyMutations = () => this.syncProcessor.push(mutationsEvents, { otelContext })
+
+              if (mutationsEvents.length > 1) {
+                // TODO: what to do about leader transaction here?
+                return this.sqliteDbWrapper.txn(applyMutations)
+              } else {
+                return applyMutations()
               }
-            },
-          )
+            } catch (e: any) {
+              console.error(e)
+              span.setStatus({ code: otel.SpanStatusCode.ERROR, message: e.toString() })
+              throw e
+            } finally {
+              span.end()
+            }
+          })()
 
-          const tablesToUpdate = [] as [Ref<null, QueryContext, RefreshReason>, null][]
+          const tablesToUpdate = [] as [Ref<null, ReactivityGraphContext, RefreshReason>, null][]
           for (const tableName of writeTables) {
             const tableRef = this.tableRefs[tableName]
             assertNever(tableRef !== undefined, `No table ref found for ${tableName}`)
@@ -417,16 +544,6 @@ export class Store<
         return { durationMs }
       },
     )
-
-    // NOTE we need to add the mutation events to the unsynced mutation events map only after running the code above
-    // so the short-circuiting in `mutateWithoutRefresh` doesn't kick in for those events
-    for (const mutationEvent of mutationsEvents) {
-      if (mutationEvent.id !== undefined) {
-        MutableHashMap.set(this.unsyncedMutationEvents, Data.struct(mutationEvent.id), mutationEvent)
-      }
-    }
-
-    return res
   }
   // #endregion mutate
 
@@ -448,117 +565,6 @@ export class Store<
     )
   }
 
-  // #region mutateWithoutRefresh
-  /**
-   * Apply a mutation to the store.
-   * Returns the tables that were affected by the event.
-   * This is an internal method that doesn't trigger a refresh;
-   * the caller must refresh queries after calling this method.
-   */
-  mutateWithoutRefresh = (
-    mutationEventDecoded_: MutationEvent.ForSchema<TSchema> | MutationEvent.PartialForSchema<TSchema>,
-    options: {
-      otelContext: otel.Context
-      // TODO adjust `skip-persist` with new rebase sync strategy
-      coordinatorMode: 'default' | 'skip-coordinator' | 'skip-persist'
-    },
-  ): { writeTables: ReadonlySet<string>; durationMs: number } => {
-    const mutationDef =
-      this.schema.mutations.get(mutationEventDecoded_.mutation) ??
-      shouldNeverHappen(`Unknown mutation type: ${mutationEventDecoded_.mutation}`)
-
-    // Needs to happen only for partial mutation events (thus a function)
-    const nextMutationEventId = () => {
-      const { id, parentId } = this.clientSession.coordinator
-        .nextMutationEventIdPair({ localOnly: mutationDef.options.localOnly })
-        .pipe(Effect.runSync)
-
-      return { id, parentId }
-    }
-
-    const mutationEventDecoded: MutationEvent.ForSchema<TSchema> = isPartialMutationEvent(mutationEventDecoded_)
-      ? { ...mutationEventDecoded_, ...nextMutationEventId() }
-      : mutationEventDecoded_
-
-    // NOTE we also need this temporary workaround here since some code-paths use `mutateWithoutRefresh` directly
-    // e.g. the row-query functionality
-    if (MutableHashMap.has(this.unsyncedMutationEvents, Data.struct(mutationEventDecoded.id))) {
-      // NOTE this data should never be used
-      return { writeTables: new Set(), durationMs: 0 }
-    } else {
-      MutableHashMap.set(this.unsyncedMutationEvents, Data.struct(mutationEventDecoded.id), mutationEventDecoded)
-    }
-
-    const { otelContext, coordinatorMode = 'default' } = options
-
-    return this.otel.tracer.startActiveSpan(
-      'LiveStore:mutateWithoutRefresh',
-      {
-        attributes: {
-          'livestore.mutation': mutationEventDecoded.mutation,
-          'livestore.args': JSON.stringify(mutationEventDecoded.args, null, 2),
-        },
-      },
-      otelContext,
-      (span) => {
-        const otelContext = otel.trace.setSpan(otel.context.active(), span)
-
-        const allWriteTables = new Set<string>()
-        let durationMsTotal = 0
-
-        replaceSessionIdSymbol(mutationEventDecoded.args, this.clientSession.coordinator.sessionId)
-
-        const execArgsArr = getExecArgsFromMutation({ mutationDef, mutationEventDecoded })
-
-        for (const {
-          statementSql,
-          bindValues,
-          writeTables = this.syncDbWrapper.getTablesUsed(statementSql),
-        } of execArgsArr) {
-          // TODO when the store doesn't have the lock, we need wait for the coordinator to confirm the mutation
-          // before executing the mutation on the main db
-          const { durationMs } = this.syncDbWrapper.execute(statementSql, bindValues, writeTables, { otelContext })
-
-          durationMsTotal += durationMs
-          writeTables.forEach((table) => allWriteTables.add(table))
-        }
-
-        const mutationEventEncoded = Schema.encodeUnknownSync(this.__mutationEventSchema)(mutationEventDecoded)
-
-        if (coordinatorMode !== 'skip-coordinator') {
-          // Asynchronously apply mutation to a persistent storage (we're not awaiting this promise here)
-          this.clientSession.coordinator
-            .mutate(mutationEventEncoded as MutationEvent.AnyEncoded, { persisted: coordinatorMode !== 'skip-persist' })
-            .pipe(this.runEffectFork)
-        }
-
-        // Uncomment to print a list of queries currently registered on the store
-        // console.debug(JSON.parse(JSON.stringify([...this.queries].map((q) => `${labelForKey(q.componentKey)}/${q.label}`))))
-
-        span.end()
-
-        return { writeTables: allWriteTables, durationMs: durationMsTotal }
-      },
-    )
-  }
-  // #endregion mutateWithoutRefresh
-
-  /**
-   * Directly execute a SQL query on the Store.
-   * This should only be used for framework-internal purposes;
-   * all app writes should go through mutate.
-   */
-  __execute = (
-    query: string,
-    params: ParamsObject = {},
-    writeTables?: ReadonlySet<string>,
-    otelContext?: otel.Context,
-  ) => {
-    this.syncDbWrapper.execute(query, prepareBindValues(params, query), writeTables, { otelContext })
-
-    this.clientSession.coordinator.execute(query, prepareBindValues(params, query)).pipe(this.runEffectFork)
-  }
-
   private makeTableRef = (tableName: string) =>
     this.reactivityGraph.makeRef(null, {
       equal: () => false,
@@ -566,27 +572,92 @@ export class Store<
       meta: { liveStoreRefType: 'table' },
     })
 
-  __devDownloadDb = () => {
-    const data = this.syncDbWrapper.export()
-    downloadBlob(data, `livestore-${Date.now()}.db`)
-  }
+  /**
+   * Helper methods useful during development
+   *
+   * @internal
+   */
+  _dev = {
+    downloadDb: (source: 'local' | 'leader' = 'local') => {
+      Effect.gen(this, function* () {
+        const data = source === 'local' ? this.sqliteDbWrapper.export() : yield* this.clientSession.leaderThread.export
+        downloadBlob(data, `livestore-${Date.now()}.db`)
+      }).pipe(this.runEffectFork)
+    },
 
-  __devDownloadMutationLogDb = () =>
-    Effect.gen(this, function* () {
-      const data = yield* this.clientSession.coordinator.getMutationLogData
-      downloadBlob(data, `livestore-mutationlog-${Date.now()}.db`)
-    }).pipe(this.runEffectFork)
+    downloadMutationLogDb: () => {
+      Effect.gen(this, function* () {
+        const data = yield* this.clientSession.leaderThread.getMutationLogData
+        downloadBlob(data, `livestore-mutationlog-${Date.now()}.db`)
+      }).pipe(this.runEffectFork)
+    },
 
-  __devCurrentMutationEventId = () => this.clientSession.coordinator.getCurrentMutationEventId.pipe(Effect.runSync)
+    hardReset: (mode: 'all-data' | 'only-app-db' = 'all-data') => {
+      Effect.gen(this, function* () {
+        yield* this.clientSession.leaderThread.sendDevtoolsMessage(
+          Devtools.ResetAllDataReq.make({ liveStoreVersion, mode, requestId: nanoid() }),
+        )
+      }).pipe(this.runEffectFork)
+    },
+
+    syncStates: () => {
+      Effect.gen(this, function* () {
+        const session = this.syncProcessor.syncStateRef.current
+        console.log('Session sync state:', session.toJSON())
+        const leader = yield* this.clientSession.leaderThread.getSyncState
+        console.log('Leader sync state:', leader.toJSON())
+      }).pipe(this.runEffectFork)
+    },
+
+    shutdown: (cause?: Cause.Cause<UnexpectedError>) => {
+      this.clientSession
+        .shutdown(cause ?? Cause.fail(IntentionalShutdownCause.make({ reason: 'manual' })))
+        .pipe(Effect.tapCauseLogPretty, Effect.provide(this.runtime), Effect.runFork)
+    },
+  }
 
   // NOTE This is needed because when booting a Store via Effect it seems to call `toJSON` in the error path
-  toJSON = () => {
-    return {
-      _tag: 'livestore.Store',
-      reactivityGraph: this.reactivityGraph.getSnapshot({ includeResults: true }),
+  toJSON = () => ({
+    _tag: 'livestore.Store',
+    reactivityGraph: this.reactivityGraph.getSnapshot({ includeResults: true }),
+  })
+
+  private runEffectFork = <A, E>(effect: Effect.Effect<A, E, Scope.Scope>) =>
+    effect.pipe(Effect.forkIn(this.lifetimeScope), Effect.tapCauseLogPretty, Runtime.runFork(this.runtime))
+
+  private getMutateArgs = (
+    firstMutationOrTxnFnOrOptions: any,
+    restMutations: any[],
+  ): {
+    mutationsEvents: (MutationEvent.ForSchema<TSchema> | MutationEvent.PartialForSchema<TSchema>)[]
+    options: StoreMutateOptions | undefined
+  } => {
+    let mutationsEvents: (MutationEvent.ForSchema<TSchema> | MutationEvent.PartialForSchema<TSchema>)[]
+    let options: StoreMutateOptions | undefined
+
+    if (typeof firstMutationOrTxnFnOrOptions === 'function') {
+      // TODO ensure that function is synchronous and isn't called in a async way (also write tests for this)
+      mutationsEvents = firstMutationOrTxnFnOrOptions((arg: any) => mutationsEvents.push(arg))
+    } else if (
+      firstMutationOrTxnFnOrOptions?.label !== undefined ||
+      firstMutationOrTxnFnOrOptions?.skipRefresh !== undefined ||
+      firstMutationOrTxnFnOrOptions?.otelContext !== undefined ||
+      firstMutationOrTxnFnOrOptions?.spanLinks !== undefined
+    ) {
+      options = firstMutationOrTxnFnOrOptions
+      mutationsEvents = restMutations
+    } else if (firstMutationOrTxnFnOrOptions === undefined) {
+      // When `mutate` is called with no arguments (which sometimes happens when dynamically filtering mutations)
+      mutationsEvents = []
+    } else {
+      mutationsEvents = [firstMutationOrTxnFnOrOptions, ...restMutations]
     }
-  }
 
-  private runEffectFork = <A, E>(effect: Effect.Effect<A, E, never>) =>
-    effect.pipe(Effect.tapCauseLogPretty, FiberSet.run(this.fiberSet), Runtime.runFork(this.runtime))
+    mutationsEvents = mutationsEvents.filter(
+      // @ts-expect-error TODO
+      (_) => _.id === undefined || !MutableHashMap.has(this.unsyncedMutationEvents, Data.struct(_.id)),
+    )
+
+    return { mutationsEvents, options }
+  }
 }