@livestore/livestore 0.3.0-dev.22 → 0.3.0-dev.24

package/src/row-query-utils.ts

@@ -66,9 +66,9 @@ export const makeExecBeforeFirstRun =
         )
       }
 
-      // It's important that we only mutate and don't refresh here, as this function might be called during a render
+      // 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"
-      store.mutate(
+      store.commit(
         { otelContext, skipRefresh: true, label: `rowQuery:${table.sqliteDef.name}:${idVal}` },
         table.insert({ id, ...insertValues }),
       )

package/src/store/create-store.ts

@@ -9,7 +9,7 @@ import type {
 import { provideOtel, UnexpectedError } from '@livestore/common'
 import type { EventId, LiveStoreSchema, MutationEvent } from '@livestore/common/schema'
 import { LS_DEV } from '@livestore/utils'
-import type { Cause } from '@livestore/utils/effect'
+import type { Cause, Schema } from '@livestore/utils/effect'
 import {
   Context,
   Deferred,
@@ -102,6 +102,12 @@ export interface CreateStoreOptions<TSchema extends LiveStoreSchema, TContext =
    * @default true
    */
   confirmUnsavedChanges?: boolean
+  /**
+   * Payload that will be passed to the sync backend when connecting
+   *
+   * @default undefined
+   */
+  syncPayload?: Schema.JsonValue
   params?: {
     leaderPushBatchSize?: number
   }
@@ -155,6 +161,7 @@ export const createStore = <TSchema extends LiveStoreSchema = LiveStoreSchema, T
   params,
   debug,
   confirmUnsavedChanges = true,
+  syncPayload,
 }: CreateStoreOptions<TSchema, TContext>): Effect.Effect<
   Store<TSchema, TContext>,
   UnexpectedError,
@@ -227,6 +234,7 @@ export const createStore = <TSchema extends LiveStoreSchema = LiveStoreSchema, T
         shutdown,
         connectDevtoolsToStore: connectDevtoolsToStore_,
         debugInstanceId,
+        syncPayload,
       }).pipe(Effect.withPerformanceMeasure('livestore:makeAdapter'), Effect.withSpan('createStore:makeAdapter'))
 
       if (LS_DEV && clientSession.leaderThread.initialState.migrationsReport.migrations.length > 0) {

package/src/store/store-types.ts

@@ -1,6 +1,7 @@
 import type { ClientSession, IntentionalShutdownCause, StoreInterrupted, UnexpectedError } from '@livestore/common'
 import type { EventId, LiveStoreSchema, MutationEvent } from '@livestore/common/schema'
-import type { Deferred, MutableHashMap, Runtime, Scope } from '@livestore/utils/effect'
+import type { Effect, MutableHashMap, Runtime, Scope } from '@livestore/utils/effect'
+import { Deferred } from '@livestore/utils/effect'
 import type * as otel from '@opentelemetry/api'
 
 import type { DebugRefreshReasonBase } from '../reactive.js'
@@ -19,6 +20,10 @@ export type LiveStoreContext =
     }
 
 export type ShutdownDeferred = Deferred.Deferred<void, UnexpectedError | IntentionalShutdownCause | StoreInterrupted>
+export const makeShutdownDeferred: Effect.Effect<ShutdownDeferred> = Deferred.make<
+  void,
+  UnexpectedError | IntentionalShutdownCause | StoreInterrupted
+>()
 
 export type LiveStoreContextRunning = {
   stage: 'running'
@@ -51,7 +56,7 @@ export type StoreOptions<TSchema extends LiveStoreSchema = LiveStoreSchema, TCon
 export type RefreshReason =
   | DebugRefreshReasonBase
   | {
-      _tag: 'mutate'
+      _tag: 'commit'
       /** The mutations that were applied */
       mutations: ReadonlyArray<MutationEvent.AnyDecoded | MutationEvent.PartialAnyDecoded>
 

package/src/store/store.ts

@@ -412,6 +412,7 @@ export class Store<TSchema extends LiveStoreSchema = LiveStoreSchema, TContext =
         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!)
@@ -440,8 +441,59 @@ export class Store<TSchema extends LiveStoreSchema = LiveStoreSchema, TContext =
     ref.deref()
   }
 
-  // #region mutate
-  mutate: {
+  // #region commit
+  /**
+   * Commit a list of mutations to the store which will immediately update the local database
+   * and sync the mutations across other clients (similar to a `git commit`).
+   *
+   * @example
+   * ```ts
+   * store.commit(mutations.todoCreated({ id: nanoid(), text: 'Make coffee' }))
+   * ```
+   *
+   * You can call `commit` with multiple mutations to apply them in a single database transaction.
+   *
+   * @example
+   * ```ts
+   * const todoId = nanoid()
+   * store.commit(
+   *   mutations.todoCreated({ id: todoId, text: 'Make coffee' }),
+   *   mutations.todoCompleted({ id: todoId }))
+   * ```
+   *
+   * For more advanced transaction scenarios, you can pass a synchronous function to `commit` which will receive a callback
+   * to which you can pass multiple mutations to be committed in the same database transaction.
+   * Under the hood this will simply collect all mutations and apply them in a single database transaction.
+   *
+   * @example
+   * ```ts
+   * store.commit((commit) => {
+   *   const todoId = nanoid()
+   *   if (Math.random() > 0.5) {
+   *     commit(mutations.todoCreated({ id: todoId, text: 'Make coffee' }))
+   *   } else {
+   *     commit(mutations.todoCompleted({ id: todoId }))
+   *   }
+   * })
+   * ```
+   *
+   * When committing a large batch of mutations, you can also skip the database refresh to improve performance
+   * and call `store.manualRefresh()` after all mutations have been committed.
+   *
+   * @example
+   * ```ts
+   * const todos = [
+   *   { id: nanoid(), text: 'Make coffee' },
+   *   { id: nanoid(), text: 'Buy groceries' },
+   *   // ... 1000 more todos
+   * ]
+   * for (const todo of todos) {
+   *   store.commit({ skipRefresh: true }, mutations.todoCreated({ id: todo.id, text: todo.text }))
+   * }
+   * store.manualRefresh()
+   * ```
+   */
+  commit: {
     <const TMutationArg extends ReadonlyArray<MutationEvent.PartialForSchema<TSchema>>>(...list: TMutationArg): void
     (
       txn: <const TMutationArg extends ReadonlyArray<MutationEvent.PartialForSchema<TSchema>>>(
@@ -470,21 +522,21 @@ export class Store<TSchema extends LiveStoreSchema = LiveStoreSchema, TContext =
     const skipRefresh = options?.skipRefresh ?? false
 
     const mutationsSpan = otel.trace.getSpan(this.otel.mutationsSpanContext)!
-    mutationsSpan.addEvent('mutate')
+    mutationsSpan.addEvent('commit')
 
-    // console.group('LiveStore.mutate', { skipRefresh, wasSyncMessage, label })
+    // console.group('LiveStore.commit', { skipRefresh, wasSyncMessage, label })
     // mutationsEvents.forEach((_) => console.debug(_.mutation, _.id, _.args))
     // console.groupEnd()
 
     let durationMs: number
 
     return this.otel.tracer.startActiveSpan(
-      'LiveStore:mutate',
+      'LiveStore:commit',
       {
         attributes: {
           'livestore.mutationEventsCount': mutationsEvents.length,
           'livestore.mutationEventTags': mutationsEvents.map((_) => _.mutation),
-          'livestore.mutateLabel': options?.label,
+          'livestore.commitLabel': options?.label,
         },
         links: options?.spanLinks,
       },
@@ -520,7 +572,7 @@ export class Store<TSchema extends LiveStoreSchema = LiveStoreSchema, TContext =
           }
 
           const debugRefreshReason = {
-            _tag: 'mutate' as const,
+            _tag: 'commit' as const,
             mutations: mutationsEvents,
             writeTables: Array.from(writeTables),
           }
@@ -541,7 +593,7 @@ export class Store<TSchema extends LiveStoreSchema = LiveStoreSchema, TContext =
       },
     )
   }
-  // #endregion mutate
+  // #endregion commit
 
   /**
    * This can be used in combination with `skipRefresh` when applying mutations.
@@ -643,7 +695,7 @@ export class Store<TSchema extends LiveStoreSchema = LiveStoreSchema, TContext =
       options = firstMutationOrTxnFnOrOptions
       mutationsEvents = restMutations
     } else if (firstMutationOrTxnFnOrOptions === undefined) {
-      // When `mutate` is called with no arguments (which sometimes happens when dynamically filtering mutations)
+      // When `commit` is called with no arguments (which sometimes happens when dynamically filtering mutations)
       mutationsEvents = []
     } else {
       mutationsEvents = [firstMutationOrTxnFnOrOptions, ...restMutations]