@livestore/common 0.3.0-dev.10 → 0.3.0-dev.2

package/package.json

@@ -1,8 +1,7 @@
 {
   "name": "@livestore/common",
-  "version": "0.3.0-dev.10",
+  "version": "0.3.0-dev.2",
   "type": "module",
-  "sideEffects": false,
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -50,12 +49,12 @@
     }
   },
   "dependencies": {
-    "@opentelemetry/api": "1.9.0",
+    "@opentelemetry/api": "^1.9.0",
     "graphology": "0.26.0-alpha1",
     "graphology-dag": "0.4.1",
-    "graphology-types": "0.24.8",
-    "@livestore/db-schema": "0.3.0-dev.10",
-    "@livestore/utils": "0.3.0-dev.10"
+    "graphology-types": "0.24.7",
+    "@livestore/utils": "0.3.0-dev.2",
+    "@livestore/db-schema": "0.3.0-dev.2"
   },
   "devDependencies": {
     "vitest": "^2.1.4"

package/src/adapter-types.ts

@@ -29,28 +29,8 @@ export type SynchronousDatabaseChangeset = {
 export type ClientSession = {
   /** SQLite database with synchronous API running in the same thread (usually in-memory) */
   syncDb: SynchronousDatabase
-  devtools: { enabled: boolean }
-  clientId: string
-  sessionId: string
-  /** Status info whether current session is leader or not */
-  lockStatus: SubscriptionRef.SubscriptionRef<LockStatus>
-  shutdown: (cause: Cause.Cause<UnexpectedError | IntentionalShutdownCause>) => Effect.Effect<void>
-  /** A proxy API to communicate with the leader thread */
-  leaderThread: ClientSessionLeaderThreadProxy
-}
-
-export type ClientSessionLeaderThreadProxy = {
-  mutations: {
-    pull: Stream.Stream<{ payload: PayloadUpstream; remaining: number }, UnexpectedError>
-    push(batch: ReadonlyArray<MutationEvent.AnyEncoded>): Effect.Effect<void, UnexpectedError | InvalidPushError>
-    initialMutationEventId: EventId
-  }
-  export: Effect.Effect<Uint8Array, UnexpectedError>
-  getMutationLogData: Effect.Effect<Uint8Array, UnexpectedError>
-  getSyncState: Effect.Effect<SyncState, UnexpectedError>
-  networkStatus: SubscriptionRef.SubscriptionRef<NetworkStatus>
-  /** For debugging purposes it can be useful to manually trigger devtools messages (e.g. to reset the database) */
-  sendDevtoolsMessage: (message: Devtools.MessageToAppLeader) => Effect.Effect<void, UnexpectedError>
+  /** The coordinator is responsible for persisting the database, syncing etc */
+  coordinator: Coordinator
 }
 
 export type SynchronousDatabase<TReq = any, TMetadata extends TReq = TReq> = {
@@ -123,6 +103,28 @@ export const BootStatus = Schema.Union(
 
 export type BootStatus = typeof BootStatus.Type
 
+// TODO refactor `Coordinator` to embrace more of the "leader semantics"
+export type Coordinator = {
+  devtools: {
+    enabled: boolean
+    // TODO incorporate sessionId and rethink appHostId
+    appHostId: string
+  }
+  sessionId: string
+  // TODO is exposing the lock status really needed (or only relevant for web adapter?)
+  lockStatus: SubscriptionRef.SubscriptionRef<LockStatus>
+  mutations: {
+    pull: Stream.Stream<{ payload: PayloadUpstream; remaining: number }, UnexpectedError>
+    push(batch: ReadonlyArray<MutationEvent.AnyEncoded>): Effect.Effect<void, UnexpectedError | InvalidPushError>
+    initialMutationEventId: EventId
+  }
+  export: Effect.Effect<Uint8Array, UnexpectedError>
+  getMutationLogData: Effect.Effect<Uint8Array, UnexpectedError>
+  getLeaderSyncState: Effect.Effect<SyncState, UnexpectedError>
+  networkStatus: SubscriptionRef.SubscriptionRef<NetworkStatus>
+  shutdown: (cause: Cause.Cause<UnexpectedError | IntentionalShutdownCause>) => Effect.Effect<void>
+}
+
 /**
  * Can be used in queries to refer to the current session id.
  * Will be replaced with the actual session id at runtime

package/src/derived-mutations.test.ts

@@ -94,7 +94,7 @@ describe('derived mutations', () => {
   })
 })
 
-const patchId = (muationEvent: MutationEvent.PartialAnyDecoded) => {
+const patchId = (muationEvent: MutationEvent.PartialAny) => {
   // TODO use new id paradigm
   const id = `00000000-0000-0000-0000-000000000000`
   return { ...muationEvent, id }

package/src/derived-mutations.ts

@@ -136,10 +136,8 @@ export namespace DerivedMutationHelperFns {
   > = SqliteDsl.AnyIfConstained<
     TColumns,
     UseShortcut<TOptions> extends true
-      ? (
-          values?: GetValForKey<SqliteDsl.FromColumns.InsertRowDecoded<TColumns>, 'value'>,
-        ) => MutationEvent.PartialAnyDecoded
-      : (values: SqliteDsl.FromColumns.InsertRowDecoded<TColumns>) => MutationEvent.PartialAnyDecoded
+      ? (values?: GetValForKey<SqliteDsl.FromColumns.InsertRowDecoded<TColumns>, 'value'>) => MutationEvent.PartialAny
+      : (values: SqliteDsl.FromColumns.InsertRowDecoded<TColumns>) => MutationEvent.PartialAny
   >
 
   export type UpdateMutationFn<
@@ -148,19 +146,17 @@ export namespace DerivedMutationHelperFns {
   > = SqliteDsl.AnyIfConstained<
     TColumns,
     UseShortcut<TOptions> extends true
-      ? (
-          values: Partial<GetValForKey<SqliteDsl.FromColumns.RowDecoded<TColumns>, 'value'>>,
-        ) => MutationEvent.PartialAnyDecoded
+      ? (values: Partial<GetValForKey<SqliteDsl.FromColumns.RowDecoded<TColumns>, 'value'>>) => MutationEvent.PartialAny
       : (args: {
           where: Partial<SqliteDsl.FromColumns.RowDecoded<TColumns>>
           values: Partial<SqliteDsl.FromColumns.RowDecoded<TColumns>>
-        }) => MutationEvent.PartialAnyDecoded
+        }) => MutationEvent.PartialAny
   >
 
   export type DeleteMutationFn<
     TColumns extends SqliteDsl.ConstraintColumns,
     _TOptions extends DbSchema.TableOptions,
-  > = (args: { where: Partial<SqliteDsl.FromColumns.RowDecoded<TColumns>> }) => MutationEvent.PartialAnyDecoded
+  > = (args: { where: Partial<SqliteDsl.FromColumns.RowDecoded<TColumns>> }) => MutationEvent.PartialAny
 
   type UseShortcut<TOptions extends DbSchema.TableOptions> = TOptions['isSingleColumn'] extends true
     ? TOptions['isSingleton'] extends true

package/src/devtools/devtools-bridge.ts

@@ -6,8 +6,7 @@ export type PrepareDevtoolsBridge = {
   /** Messages coming from the app host (usually responses to requests) */
   responsePubSub: PubSub.PubSub<Devtools.MessageFromAppLeader | Devtools.MessageFromAppClientSession>
   sendToAppHost: (msg: Devtools.MessageToAppLeader | Devtools.MessageToAppClientSession) => Effect.Effect<void>
-  clientId: string
-  sessionId: string
+  appHostId: string
   copyToClipboard: (text: string) => Effect.Effect<void>
   sendEscapeKey?: Effect.Effect<void>
   isLeader: boolean

package/src/devtools/devtools-messages.ts

@@ -7,8 +7,7 @@ import { PreparedBindValues } from '../util.js'
 import { liveStoreVersion as pkgVersion } from '../version.js'
 
 const requestId = Schema.String
-const clientId = Schema.String
-const sessionId = Schema.String
+const appHostId = Schema.String
 const liveStoreVersion = Schema.Literal(pkgVersion)
 
 const LSDMessage = <Tag extends string, Fields extends Schema.Struct.Fields>(tag: Tag, fields: Fields) =>
@@ -24,15 +23,13 @@ const LSDChannelMessage = <Tag extends string, Fields extends Schema.Struct.Fiel
 
 const LSDStoreChannelMessage = <Tag extends string, Fields extends Schema.Struct.Fields>(tag: Tag, fields: Fields) =>
   LSDMessage(tag, {
-    clientId,
-    sessionId,
+    appHostId,
     ...fields,
   })
 
 const LSDStoreReqResMessage = <Tag extends string, Fields extends Schema.Struct.Fields>(tag: Tag, fields: Fields) =>
   LSDMessage(tag, {
-    clientId,
-    sessionId,
+    appHostId,
     requestId,
     ...fields,
   })
@@ -85,12 +82,12 @@ export class DebugInfoRerunQueryRes extends LSDStoreReqResMessage('LSD.DebugInfo
 
 // TODO refactor this to use push/pull semantics
 export class MutationBroadcast extends LSDMessage('LSD.Leader.MutationBroadcast', {
-  mutationEventEncoded: MutationEvent.AnyEncoded,
+  mutationEventEncoded: MutationEvent.EncodedAny,
 }) {}
 
 // TODO refactor this to use push/pull semantics
 export class RunMutationReq extends LSDReqResMessage('LSD.Leader.RunMutationReq', {
-  mutationEventEncoded: MutationEvent.AnyEncoded.pipe(Schema.omit('id', 'parentId')),
+  mutationEventEncoded: MutationEvent.EncodedAny.pipe(Schema.omit('id', 'parentId')),
 }) {}
 
 export class RunMutationRes extends LSDReqResMessage('LSD.Leader.RunMutationRes', {}) {}
@@ -170,7 +167,7 @@ export class SyncingInfoRes extends LSDReqResMessage('LSD.Leader.SyncingInfoRes'
 export class SyncHistorySubscribe extends LSDReqResMessage('LSD.Leader.SyncHistorySubscribe', {}) {}
 export class SyncHistoryUnsubscribe extends LSDReqResMessage('LSD.Leader.SyncHistoryUnsubscribe', {}) {}
 export class SyncHistoryRes extends LSDReqResMessage('LSD.Leader.SyncHistoryRes', {
-  mutationEventEncoded: MutationEvent.AnyEncodedGlobal,
+  mutationEventEncoded: MutationEvent.EncodedAny,
   metadata: Schema.Option(Schema.JsonValue),
 }) {}
 

package/src/index.ts

@@ -15,3 +15,9 @@ export * from './version.js'
 export * from './query-builder/mod.js'
 export * from './sync/syncstate.js'
 export * from './otel.js'
+
+declare global {
+  interface LiveStoreGlobal {
+    // syncBackend: never
+  }
+}

package/src/leader-thread/apply-mutation.ts

@@ -3,25 +3,20 @@ import type { Scope } from '@livestore/utils/effect'
 import { Effect, Option, Schema } from '@livestore/utils/effect'
 
 import type { SqliteError, SynchronousDatabase, UnexpectedError } from '../index.js'
-import { getExecArgsFromMutation } from '../mutation.js'
 import {
-  type LiveStoreSchema,
+  getExecArgsFromMutation,
   MUTATION_LOG_META_TABLE,
-  type MutationEvent,
   mutationLogMetaTable,
   SESSION_CHANGESET_META_TABLE,
   sessionChangesetMetaTable,
-} from '../schema/mod.js'
+} from '../index.js'
+import type { LiveStoreSchema, MutationEvent } from '../schema/mod.js'
 import { insertRow } from '../sql-queries/index.js'
 import { execSql, execSqlPrepared } from './connection.js'
 import { LeaderThreadCtx } from './types.js'
 
 export type ApplyMutation = (
   mutationEventEncoded: MutationEvent.AnyEncoded,
-  options?: {
-    /** Needed for rehydrateFromMutationLog */
-    skipMutationLog?: boolean
-  },
 ) => Effect.Effect<void, SqliteError | UnexpectedError>
 
 export const makeApplyMutation: Effect.Effect<ApplyMutation, never, Scope.Scope | LeaderThreadCtx> = Effect.gen(
@@ -36,27 +31,15 @@ export const makeApplyMutation: Effect.Effect<ApplyMutation, never, Scope.Scope
       [...leaderThreadCtx.schema.mutations.entries()].map(([k, v]) => [k, Schema.hash(v.schema)] as const),
     )
 
-    return (mutationEventEncoded, options) =>
+    return (mutationEventEncoded) =>
       Effect.gen(function* () {
-        const { schema, db, dbLog } = leaderThreadCtx
-        const skipMutationLog = options?.skipMutationLog ?? false
+        const { mutationEventSchema, schema, db, dbLog } = leaderThreadCtx
+        const mutationEventDecoded = Schema.decodeUnknownSync(mutationEventSchema)(mutationEventEncoded)
 
-        const mutationName = mutationEventEncoded.mutation
+        const mutationName = mutationEventDecoded.mutation
         const mutationDef = schema.mutations.get(mutationName) ?? shouldNeverHappen(`Unknown mutation: ${mutationName}`)
 
-        const execArgsArr = getExecArgsFromMutation({
-          mutationDef,
-          mutationEvent: { decoded: undefined, encoded: mutationEventEncoded },
-        })
-
-        // NOTE we might want to bring this back if we want to debug no-op mutations
-        // const makeExecuteOptions = (statementSql: string, bindValues: any) => ({
-        //   onRowsChanged: (rowsChanged: number) => {
-        //     if (rowsChanged === 0) {
-        //       console.warn(`Mutation "${mutationDef.name}" did not affect any rows:`, statementSql, bindValues)
-        //     }
-        //   },
-        // })
+        const execArgsArr = getExecArgsFromMutation({ mutationDef, mutationEventDecoded })
 
         // console.group('[@livestore/common:leader-thread:applyMutation]', { mutationName })
 
@@ -70,28 +53,30 @@ export const makeApplyMutation: Effect.Effect<ApplyMutation, never, Scope.Scope
 
         const changeset = session.changeset()
         session.finish()
-
-        // TODO use prepared statements
-        yield* execSql(
-          db,
-          ...insertRow({
-            tableName: SESSION_CHANGESET_META_TABLE,
-            columns: sessionChangesetMetaTable.sqliteDef.columns,
-            values: {
-              idGlobal: mutationEventEncoded.id.global,
-              idLocal: mutationEventEncoded.id.local,
-              // NOTE the changeset will be empty (i.e. null) for no-op mutations
-              changeset: changeset ?? null,
-              debug: execArgsArr,
-            },
-          }),
-        )
+        // NOTE for no-op mutations (e.g. if the state didn't change) the changeset will be empty
+        // TODO possibly write a null value instead of omitting the row
+        if (changeset !== undefined && changeset.length > 0) {
+          // TODO use prepared statements
+          yield* execSql(
+            db,
+            ...insertRow({
+              tableName: SESSION_CHANGESET_META_TABLE,
+              columns: sessionChangesetMetaTable.sqliteDef.columns,
+              values: {
+                idGlobal: mutationEventEncoded.id.global,
+                idLocal: mutationEventEncoded.id.local,
+                changeset,
+                debug: execArgsArr,
+              },
+            }),
+          )
+        }
 
         // console.groupEnd()
 
         // write to mutation_log
-        const excludeFromMutationLog = shouldExcludeMutationFromLog(mutationName, mutationEventEncoded)
-        if (skipMutationLog === false && excludeFromMutationLog === false) {
+        const excludeFromMutationLog = shouldExcludeMutationFromLog(mutationName, mutationEventDecoded)
+        if (excludeFromMutationLog === false) {
           yield* insertIntoMutationLog(mutationEventEncoded, dbLog, mutationDefSchemaHashMap)
         } else {
           //   console.debug('[@livestore/common:leader-thread] skipping mutation log write', mutation, statementSql, bindValues)
@@ -101,7 +86,7 @@ export const makeApplyMutation: Effect.Effect<ApplyMutation, never, Scope.Scope
           attributes: {
             mutationName: mutationEventEncoded.mutation,
             mutationId: mutationEventEncoded.id,
-            'span.label': `(${mutationEventEncoded.id.global},${mutationEventEncoded.id.local}) ${mutationEventEncoded.mutation}`,
+            'span.label': mutationEventEncoded.mutation,
           },
         }),
         // Effect.logDuration('@livestore/common:leader-thread:applyMutation'),
@@ -147,14 +132,11 @@ const makeShouldExcludeMutationFromLog = memoizeByRef((schema: LiveStoreSchema)
       ? (migrationOptions.excludeMutations ?? new Set(['livestore.RawSql']))
       : new Set(['livestore.RawSql'])
 
-  return (mutationName: string, mutationEventEncoded: MutationEvent.AnyEncoded): boolean => {
+  return (mutationName: string, mutationEventDecoded: MutationEvent.Any): boolean => {
     if (mutationLogExclude.has(mutationName)) return true
 
     const mutationDef = schema.mutations.get(mutationName) ?? shouldNeverHappen(`Unknown mutation: ${mutationName}`)
-    const execArgsArr = getExecArgsFromMutation({
-      mutationDef,
-      mutationEvent: { decoded: undefined, encoded: mutationEventEncoded },
-    })
+    const execArgsArr = getExecArgsFromMutation({ mutationDef, mutationEventDecoded })
 
     return execArgsArr.some((_) => _.statementSql.includes('__livestore'))
   }