@livestore/common 0.3.0-dev.1 → 0.3.0-dev.11

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@livestore/common",
-  "version": "0.3.0-dev.1",
+  "version": "0.3.0-dev.11",
   "type": "module",
+  "sideEffects": false,
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -49,12 +50,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.7",
-    "@livestore/utils": "0.3.0-dev.1",
-    "@livestore/db-schema": "0.3.0-dev.1"
+    "graphology-types": "0.24.8",
+    "@livestore/db-schema": "0.3.0-dev.11",
+    "@livestore/utils": "0.3.0-dev.11"
   },
   "devDependencies": {
     "vitest": "^2.1.4"

package/src/adapter-types.ts

@@ -15,26 +15,51 @@ export interface PreparedStatement {
   sql: string
 }
 
-export type SynchronousDatabaseSession = {
+export type SqliteDbSession = {
   changeset: () => Uint8Array | undefined
   finish: () => void
 }
 
-export type SynchronousDatabaseChangeset = {
+export type SqliteDbChangeset = {
   // TODO combining changesets (requires changes in the SQLite WASM binding)
-  invert: () => SynchronousDatabaseChangeset
+  invert: () => SqliteDbChangeset
   apply: () => void
 }
 
 export type ClientSession = {
   /** SQLite database with synchronous API running in the same thread (usually in-memory) */
-  syncDb: SynchronousDatabase
-  /** The coordinator is responsible for persisting the database, syncing etc */
-  coordinator: Coordinator
+  sqliteDb: SqliteDb
+  devtools: { enabled: false } | { enabled: true; pullLatch: Effect.Latch; pushLatch: Effect.Latch }
+  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 SynchronousDatabase<TReq = any, TMetadata extends TReq = TReq> = {
-  _tag: 'SynchronousDatabase'
+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>
+}
+
+/**
+ * Common interface for SQLite databases used by LiveStore to facilitate a consistent API across different platforms.
+ * Always assumes a synchronous SQLite build with the `bytecode` and `session` extensions enabled.
+ * Can be either in-memory or persisted to disk.
+ */
+export type SqliteDb<TReq = any, TMetadata extends TReq = TReq> = {
+  _tag: 'SqliteDb'
   metadata: TMetadata
   prepare(queryStr: string): PreparedStatement
   execute(
@@ -44,14 +69,14 @@ export type SynchronousDatabase<TReq = any, TMetadata extends TReq = TReq> = {
   ): void
   select<T>(queryStr: string, bindValues?: PreparedBindValues | undefined): ReadonlyArray<T>
   export(): Uint8Array
-  import: (data: Uint8Array | SynchronousDatabase<TReq>) => void
+  import: (data: Uint8Array | SqliteDb<TReq>) => void
   close(): void
   destroy(): void
-  session(): SynchronousDatabaseSession
-  makeChangeset: (data: Uint8Array) => SynchronousDatabaseChangeset
+  session(): SqliteDbSession
+  makeChangeset: (data: Uint8Array) => SqliteDbChangeset
 }
 
-export type MakeSynchronousDatabase<
+export type MakeSqliteDb<
   TReq = { dbPointer: number; persistenceInfo: PersistenceInfo },
   TInput_ extends { _tag: string } = { _tag: string },
   TMetadata_ extends TReq = TReq,
@@ -61,11 +86,7 @@ export type MakeSynchronousDatabase<
   TMetadata extends TMetadata_ & { _tag: TInput['_tag'] } = TMetadata_ & { _tag: TInput['_tag'] },
 >(
   input: TInput,
-) => Effect.Effect<
-  SynchronousDatabase<TReq, Extract<TMetadata, { _tag: TInput['_tag'] }>>,
-  SqliteError | UnexpectedError,
-  R
->
+) => Effect.Effect<SqliteDb<TReq, Extract<TMetadata, { _tag: TInput['_tag'] }>>, SqliteError | UnexpectedError, R>
 
 export const PersistenceInfo = Schema.Struct(
   {
@@ -103,28 +124,6 @@ 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
@@ -198,7 +197,7 @@ export type MigrationHooks = {
   post: MigrationHook
 }
 
-export type MigrationHook = (db: SynchronousDatabase) => void | Promise<void> | Effect.Effect<void, unknown>
+export type MigrationHook = (db: SqliteDb) => void | Promise<void> | Effect.Effect<void, unknown>
 
 export type MigrationOptionsFromMutationLog<TSchema extends LiveStoreSchema = LiveStoreSchema> = {
   strategy: 'from-mutation-log'

package/src/derived-mutations.test.ts

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

package/src/derived-mutations.ts

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

package/src/devtools/devtools-bridge.ts

@@ -6,7 +6,8 @@ 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>
-  appHostId: string
+  clientId: string
+  sessionId: string
   copyToClipboard: (text: string) => Effect.Effect<void>
   sendEscapeKey?: Effect.Effect<void>
   isLeader: boolean

package/src/devtools/devtools-messages-client-session.ts

@@ -0,0 +1,109 @@
+import { Schema } from '@livestore/utils/effect'
+
+import { DebugInfo } from '../debug-info.js'
+import { PreparedBindValues } from '../util.js'
+import { Disconnect, LSDClientSessionReqResMessage } from './devtools-messages-common.js'
+
+export class DebugInfoReq extends LSDClientSessionReqResMessage('LSD.ClientSession.DebugInfoReq', {}) {}
+
+export class DebugInfoRes extends LSDClientSessionReqResMessage('LSD.ClientSession.DebugInfoRes', {
+  debugInfo: DebugInfo,
+}) {}
+
+export class DebugInfoHistorySubscribe extends LSDClientSessionReqResMessage(
+  'LSD.ClientSession.DebugInfoHistorySubscribe',
+  {},
+) {}
+
+export class DebugInfoHistoryRes extends LSDClientSessionReqResMessage('LSD.ClientSession.DebugInfoHistoryRes', {
+  debugInfoHistory: Schema.Array(DebugInfo),
+}) {}
+
+export class DebugInfoHistoryUnsubscribe extends LSDClientSessionReqResMessage(
+  'LSD.ClientSession.DebugInfoHistoryUnsubscribe',
+  {},
+) {}
+
+export class DebugInfoResetReq extends LSDClientSessionReqResMessage('LSD.ClientSession.DebugInfoResetReq', {}) {}
+
+export class DebugInfoResetRes extends LSDClientSessionReqResMessage('LSD.ClientSession.DebugInfoResetRes', {}) {}
+
+export class DebugInfoRerunQueryReq extends LSDClientSessionReqResMessage('LSD.ClientSession.DebugInfoRerunQueryReq', {
+  queryStr: Schema.String,
+  bindValues: Schema.UndefinedOr(PreparedBindValues),
+  queriedTables: Schema.ReadonlySet(Schema.String),
+}) {}
+
+export class DebugInfoRerunQueryRes extends LSDClientSessionReqResMessage(
+  'LSD.ClientSession.DebugInfoRerunQueryRes',
+  {},
+) {}
+
+export class ReactivityGraphSubscribe extends LSDClientSessionReqResMessage(
+  'LSD.ClientSession.ReactivityGraphSubscribe',
+  {
+    includeResults: Schema.Boolean,
+  },
+) {}
+
+export class ReactivityGraphUnsubscribe extends LSDClientSessionReqResMessage(
+  'LSD.ClientSession.ReactivityGraphUnsubscribe',
+  {},
+) {}
+
+export class ReactivityGraphRes extends LSDClientSessionReqResMessage('LSD.ClientSession.ReactivityGraphRes', {
+  reactivityGraph: Schema.Any,
+}) {}
+
+export class LiveQueriesSubscribe extends LSDClientSessionReqResMessage('LSD.ClientSession.LiveQueriesSubscribe', {}) {}
+
+export class LiveQueriesUnsubscribe extends LSDClientSessionReqResMessage(
+  'LSD.ClientSession.LiveQueriesUnsubscribe',
+  {},
+) {}
+
+export class SerializedLiveQuery extends Schema.Struct({
+  _tag: Schema.Literal('computed', 'db', 'graphql'),
+  id: Schema.Number,
+  label: Schema.String,
+  runs: Schema.Number,
+  executionTimes: Schema.Array(Schema.Number),
+  lastestResult: Schema.Any,
+  activeSubscriptions: Schema.Array(
+    Schema.Struct({ frames: Schema.Array(Schema.Struct({ name: Schema.String, filePath: Schema.String })) }),
+  ),
+}) {}
+
+export class LiveQueriesRes extends LSDClientSessionReqResMessage('LSD.ClientSession.LiveQueriesRes', {
+  liveQueries: Schema.Array(SerializedLiveQuery),
+}) {}
+
+export const MessageToAppClientSession = Schema.Union(
+  DebugInfoReq,
+  DebugInfoHistorySubscribe,
+  DebugInfoHistoryUnsubscribe,
+  DebugInfoResetReq,
+  DebugInfoRerunQueryReq,
+  ReactivityGraphSubscribe,
+  ReactivityGraphUnsubscribe,
+  LiveQueriesSubscribe,
+  LiveQueriesUnsubscribe,
+  Disconnect,
+  // TODO also introduce a ping/pong protocol for the client session <> devtools connection
+  // Ping,
+).annotations({ identifier: 'LSD.MessageToAppClientSession' })
+
+export type MessageToAppClientSession = typeof MessageToAppClientSession.Type
+
+export const MessageFromAppClientSession = Schema.Union(
+  DebugInfoRes,
+  DebugInfoHistoryRes,
+  DebugInfoResetRes,
+  DebugInfoRerunQueryRes,
+  ReactivityGraphRes,
+  LiveQueriesRes,
+  Disconnect,
+  // Pong,
+).annotations({ identifier: 'LSD.MessageFromAppClientSession' })
+
+export type MessageFromAppClientSession = typeof MessageFromAppClientSession.Type

package/src/devtools/devtools-messages-common.ts

@@ -0,0 +1,52 @@
+import { Schema } from '@livestore/utils/effect'
+
+import { liveStoreVersion as pkgVersion } from '../version.js'
+
+const requestId = Schema.String
+const clientId = Schema.String
+const sessionId = Schema.String
+const liveStoreVersion = Schema.Literal(pkgVersion)
+
+export const LSDMessage = <Tag extends string, Fields extends Schema.Struct.Fields>(tag: Tag, fields: Fields) =>
+  Schema.TaggedStruct(tag, {
+    liveStoreVersion,
+    ...fields,
+  }).annotations({ identifier: tag })
+
+export const LSDChannelMessage = <Tag extends string, Fields extends Schema.Struct.Fields>(tag: Tag, fields: Fields) =>
+  LSDMessage(tag, {
+    ...fields,
+  })
+
+export const LSDClientSessionChannelMessage = <Tag extends string, Fields extends Schema.Struct.Fields>(
+  tag: Tag,
+  fields: Fields,
+) =>
+  LSDMessage(tag, {
+    clientId,
+    sessionId,
+    ...fields,
+  })
+
+export const LSDClientSessionReqResMessage = <Tag extends string, Fields extends Schema.Struct.Fields>(
+  tag: Tag,
+  fields: Fields,
+) =>
+  LSDMessage(tag, {
+    clientId,
+    sessionId,
+    requestId,
+    ...fields,
+  })
+
+export const LSDReqResMessage = <Tag extends string, Fields extends Schema.Struct.Fields>(tag: Tag, fields: Fields) =>
+  LSDChannelMessage(tag, {
+    requestId,
+    ...fields,
+  })
+
+export class Disconnect extends LSDClientSessionChannelMessage('LSD.Disconnect', {}) {}
+
+export class Ping extends LSDReqResMessage('LSD.Ping', {}) {}
+
+export class Pong extends LSDReqResMessage('LSD.Pong', {}) {}

package/src/devtools/devtools-messages-leader.ts

@@ -0,0 +1,115 @@
+import { Schema, Transferable } from '@livestore/utils/effect'
+
+import { NetworkStatus } from '../adapter-types.js'
+import * as MutationEvent from '../schema/MutationEvent.js'
+import { Disconnect, LSDMessage, LSDReqResMessage, Ping, Pong } from './devtools-messages-common.js'
+
+export class ResetAllDataReq extends LSDReqResMessage('LSD.Leader.ResetAllDataReq', {
+  mode: Schema.Literal('all-data', 'only-app-db'),
+}) {}
+
+export class ResetAllDataRes extends LSDReqResMessage('LSD.Leader.ResetAllDataRes', {}) {}
+
+export class DatabaseFileInfoReq extends LSDReqResMessage('LSD.Leader.DatabaseFileInfoReq', {}) {}
+
+export class DatabaseFileInfo extends Schema.Struct({
+  fileSize: Schema.Number,
+  persistenceInfo: Schema.Struct({ fileName: Schema.String }, { key: Schema.String, value: Schema.Any }),
+}) {}
+
+export class DatabaseFileInfoRes extends LSDReqResMessage('LSD.Leader.DatabaseFileInfoRes', {
+  readModel: DatabaseFileInfo,
+  mutationLog: DatabaseFileInfo,
+}) {}
+
+export class NetworkStatusSubscribe extends LSDReqResMessage('LSD.Leader.NetworkStatusSubscribe', {}) {}
+export class NetworkStatusUnsubscribe extends LSDReqResMessage('LSD.Leader.NetworkStatusUnsubscribe', {}) {}
+
+export class NetworkStatusRes extends LSDReqResMessage('LSD.Leader.NetworkStatusRes', {
+  networkStatus: NetworkStatus,
+}) {}
+
+export class SyncingInfoReq extends LSDReqResMessage('LSD.Leader.SyncingInfoReq', {}) {}
+
+export class SyncingInfo extends Schema.Struct({
+  enabled: Schema.Boolean,
+  metadata: Schema.Record({ key: Schema.String, value: Schema.Any }),
+}) {}
+
+export class SyncingInfoRes extends LSDReqResMessage('LSD.Leader.SyncingInfoRes', {
+  syncingInfo: SyncingInfo,
+}) {}
+
+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,
+  metadata: Schema.Option(Schema.JsonValue),
+}) {}
+
+export class SnapshotReq extends LSDReqResMessage('LSD.Leader.SnapshotReq', {}) {}
+
+export class SnapshotRes extends LSDReqResMessage('LSD.Leader.SnapshotRes', {
+  snapshot: Transferable.Uint8Array,
+}) {}
+
+export class LoadDatabaseFileReq extends LSDReqResMessage('LSD.Leader.LoadDatabaseFileReq', {
+  data: Transferable.Uint8Array,
+}) {}
+
+export class LoadDatabaseFileRes extends LSDReqResMessage('LSD.Leader.LoadDatabaseFileRes', {
+  status: Schema.Literal('ok', 'unsupported-file', 'unsupported-database'),
+}) {}
+
+// TODO refactor this to use push/pull semantics
+export class MutationBroadcast extends LSDMessage('LSD.Leader.MutationBroadcast', {
+  mutationEventEncoded: MutationEvent.AnyEncoded,
+}) {}
+
+// TODO refactor this to use push/pull semantics
+export class RunMutationReq extends LSDReqResMessage('LSD.Leader.RunMutationReq', {
+  mutationEventEncoded: MutationEvent.AnyEncoded.pipe(Schema.omit('id', 'parentId')),
+}) {}
+
+export class RunMutationRes extends LSDReqResMessage('LSD.Leader.RunMutationRes', {}) {}
+
+export class MutationLogReq extends LSDReqResMessage('LSD.Leader.MutationLogReq', {}) {}
+
+export class MutationLogRes extends LSDReqResMessage('LSD.Leader.MutationLogRes', {
+  mutationLog: Transferable.Uint8Array,
+}) {}
+
+export const MessageToAppLeader = Schema.Union(
+  SnapshotReq,
+  LoadDatabaseFileReq,
+  MutationLogReq,
+  ResetAllDataReq,
+  NetworkStatusSubscribe,
+  NetworkStatusUnsubscribe,
+  Disconnect,
+  RunMutationReq,
+  Ping,
+  DatabaseFileInfoReq,
+  SyncHistorySubscribe,
+  SyncHistoryUnsubscribe,
+  SyncingInfoReq,
+).annotations({ identifier: 'LSD.MessageToAppLeader' })
+
+export type MessageToAppLeader = typeof MessageToAppLeader.Type
+
+export const MessageFromAppLeader = Schema.Union(
+  SnapshotRes,
+  LoadDatabaseFileRes,
+  MutationLogRes,
+  ResetAllDataRes,
+  Disconnect,
+  MutationBroadcast,
+  NetworkStatusRes,
+  RunMutationRes,
+  Pong,
+  DatabaseFileInfoRes,
+  SyncHistoryRes,
+  SyncingInfoRes,
+).annotations({ identifier: 'LSD.MessageFromAppLeader' })
+
+export type MessageFromAppLeader = typeof MessageFromAppLeader.Type