@livestore/common 0.4.0-dev.1 → 0.4.0-dev.10

package/dist/testing/event-factory.js

@@ -0,0 +1,80 @@
+/**
+ * Helpers for synthesizing LiveStore events in tests while keeping track of
+ * sequence numbers, parent pointers, and authoring client identity. Inspired
+ * by the effect-based schema utilities, the factory exposes a namespaced API
+ * where each event definition maps to a helper with `next`, `advanceTo`, and
+ * `setParent` functions that share a single sequence stream.
+ *
+ * @example
+ * ```ts
+ * import { EventFactory } from '@livestore/common/testing'
+ * import { events } from './schema'
+ *
+ * const eventFactory = EventFactory.makeFactory(events)({
+ *   client: EventFactory.clientIdentity('test-client'),
+ *   startSeq: 1,
+ *   initialParent: 'root',
+ * })
+ *
+ * const bootstrap = eventFactory.todoCreated.next({
+ *   id: 'todo-1',
+ *   text: 'write tests',
+ *   completed: false,
+ * })
+ *
+ * eventFactory.todoCreated.advanceTo(42)
+ * const branched = eventFactory.todoUpdated.next({
+ *   id: 'todo-1',
+ *   text: 'ship feature',
+ *   completed: true,
+ * })
+ * ```
+ */
+import { Schema } from '@livestore/utils/effect';
+import * as EventSequenceNumber from "../schema/EventSequenceNumber.js";
+import * as LiveStoreEvent from "../schema/LiveStoreEvent.js";
+export const clientIdentity = (label, session = `${label}-session`) => ({
+    clientId: label,
+    sessionId: session,
+});
+export const makeFactory = (eventDefs) => ({ client, startSeq = 1, initialParent = 'root', }) => {
+    let nextSeq = startSeq;
+    let parentRef = initialParent;
+    const advanceTo = (seq, parent = 'root') => {
+        nextSeq = seq;
+        parentRef = parent;
+    };
+    const setParent = (parent) => {
+        parentRef = parent;
+    };
+    const current = () => ({ seq: nextSeq, parent: parentRef });
+    const factories = {};
+    for (const [name, eventDef] of Object.entries(eventDefs)) {
+        const next = (args) => {
+            const decoded = eventDef(args);
+            const encodedArgs = Schema.encodeSync(eventDef.schema)(decoded.args);
+            const encoded = eventDef.encoded(encodedArgs);
+            const event = LiveStoreEvent.AnyEncodedGlobal.make({
+                name: encoded.name,
+                args: encoded.args,
+                seqNum: EventSequenceNumber.globalEventSequenceNumber(nextSeq),
+                parentSeqNum: parentRef === 'root'
+                    ? EventSequenceNumber.ROOT.global
+                    : EventSequenceNumber.globalEventSequenceNumber(parentRef),
+                clientId: client.clientId,
+                sessionId: client.sessionId,
+            });
+            parentRef = nextSeq;
+            nextSeq = nextSeq + 1;
+            return event;
+        };
+        factories[name] = {
+            next,
+            advanceTo,
+            setParent,
+            current,
+        };
+    }
+    return factories;
+};
+//# sourceMappingURL=event-factory.js.map

package/dist/testing/event-factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-factory.js","sourceRoot":"","sources":["../../src/testing/event-factory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAA;AAGhD,OAAO,KAAK,mBAAmB,MAAM,kCAAkC,CAAA;AACvE,OAAO,KAAK,cAAc,MAAM,6BAA6B,CAAA;AAO7D,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,KAAa,EAAE,OAAO,GAAG,GAAG,KAAK,UAAU,EAAkB,EAAE,CAAC,CAAC;IAC9F,QAAQ,EAAE,KAAK;IACf,SAAS,EAAE,OAAO;CACnB,CAAC,CAAA;AA6BF,MAAM,CAAC,MAAM,WAAW,GACtB,CAA6C,SAAgB,EAAE,EAAE,CACjE,CAAC,EACC,MAAM,EACN,QAAQ,GAAG,CAAC,EACZ,aAAa,GAAG,MAAM,GACD,EAA0D,EAAE;IACjF,IAAI,OAAO,GAAG,QAAQ,CAAA;IACtB,IAAI,SAAS,GAAkB,aAAa,CAAA;IAE5C,MAAM,SAAS,GAAG,CAAC,GAAW,EAAE,SAAwB,MAAM,EAAE,EAAE;QAChE,OAAO,GAAG,GAAG,CAAA;QACb,SAAS,GAAG,MAAM,CAAA;IACpB,CAAC,CAAA;IAED,MAAM,SAAS,GAAG,CAAC,MAAqB,EAAE,EAAE;QAC1C,SAAS,GAAG,MAAM,CAAA;IACpB,CAAC,CAAA;IAED,MAAM,OAAO,GAAG,GAAG,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC,CAAA;IAE3D,MAAM,SAAS,GAAoE,EAAE,CAAA;IAErF,KAAK,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,SAAS,CAAwC,EAAE,CAAC;QAChG,MAAM,IAAI,GAAG,CAAC,IAA4C,EAAE,EAAE;YAC5D,MAAM,OAAO,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAA;YAC9B,MAAM,WAAW,GAAG,MAAM,CAAC,UAAU,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAA;YACpE,MAAM,OAAO,GAAG,QAAQ,CAAC,OAAO,CAAC,WAAW,CAAC,CAAA;YAE7C,MAAM,KAAK,GAAG,cAAc,CAAC,gBAAgB,CAAC,IAAI,CAAC;gBACjD,IAAI,EAAE,OAAO,CAAC,IAAI;gBAClB,IAAI,EAAE,OAAO,CAAC,IAAI;gBAClB,MAAM,EAAE,mBAAmB,CAAC,yBAAyB,CAAC,OAAO,CAAC;gBAC9D,YAAY,EACV,SAAS,KAAK,MAAM;oBAClB,CAAC,CAAC,mBAAmB,CAAC,IAAI,CAAC,MAAM;oBACjC,CAAC,CAAC,mBAAmB,CAAC,yBAAyB,CAAC,SAAS,CAAC;gBAC9D,QAAQ,EAAE,MAAM,CAAC,QAAQ;gBACzB,SAAS,EAAE,MAAM,CAAC,SAAS;aAC5B,CAAC,CAAA;YAEF,SAAS,GAAG,OAAO,CAAA;YACnB,OAAO,GAAG,OAAO,GAAG,CAAC,CAAA;YAErB,OAAO,KAAK,CAAA;QACd,CAAC,CAAA;QAED,SAAS,CAAC,IAAI,CAAC,GAAG;YAChB,IAAI;YACJ,SAAS;YACT,SAAS;YACT,OAAO;SAC+D,CAAA;IAC1E,CAAC;IAED,OAAO,SAAmE,CAAA;AAC5E,CAAC,CAAA"}

package/dist/testing/mod.d.ts

@@ -0,0 +1,2 @@
+export * as EventFactory from './event-factory.ts';
+//# sourceMappingURL=mod.d.ts.map

package/dist/testing/mod.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../../src/testing/mod.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,YAAY,MAAM,oBAAoB,CAAA"}

package/dist/testing/mod.js

@@ -0,0 +1,2 @@
+export * as EventFactory from "./event-factory.js";
+//# sourceMappingURL=mod.js.map

package/dist/testing/mod.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod.js","sourceRoot":"","sources":["../../src/testing/mod.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,YAAY,MAAM,oBAAoB,CAAA"}

package/dist/version.d.ts

@@ -1,4 +1,4 @@
-export declare const liveStoreVersion: "0.4.0-dev.1";
+export declare const liveStoreVersion: "0.4.0-dev.10";
 /**
  * This version number is incremented whenever the internal storage format changes in a breaking way.
  * Whenever this version changes, LiveStore will start with fresh database files. Old database files are not deleted.
@@ -6,5 +6,5 @@ export declare const liveStoreVersion: "0.4.0-dev.1";
  * While LiveStore is in beta, this might happen more frequently.
  * In the future, LiveStore will provide a migration path for older database files to avoid the impression of data loss.
  */
-export declare const liveStoreStorageFormatVersion = 5;
+export declare const liveStoreStorageFormatVersion = 6;
 //# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,gBAAgB,EAAG,aAAsB,CAAA;AAEtD;;;;;;GAMG;AACH,eAAO,MAAM,6BAA6B,IAAI,CAAA"}
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,gBAAgB,EAAG,cAAuB,CAAA;AAEvD;;;;;;GAMG;AACH,eAAO,MAAM,6BAA6B,IAAI,CAAA"}

package/dist/version.js

@@ -1,7 +1,7 @@
 // TODO bring back when Expo and Playwright supports `with` imports
 // import packageJson from '../package.json' with { type: 'json' }
 // export const liveStoreVersion = packageJson.version
-export const liveStoreVersion = '0.4.0-dev.1';
+export const liveStoreVersion = '0.4.0-dev.10';
 /**
  * This version number is incremented whenever the internal storage format changes in a breaking way.
  * Whenever this version changes, LiveStore will start with fresh database files. Old database files are not deleted.
@@ -9,5 +9,5 @@ export const liveStoreVersion = '0.4.0-dev.1';
  * While LiveStore is in beta, this might happen more frequently.
  * In the future, LiveStore will provide a migration path for older database files to avoid the impression of data loss.
  */
-export const liveStoreStorageFormatVersion = 5;
+export const liveStoreStorageFormatVersion = 6;
 //# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -1 +1 @@
-{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,mEAAmE;AACnE,kEAAkE;AAClE,sDAAsD;AAEtD,MAAM,CAAC,MAAM,gBAAgB,GAAG,aAAsB,CAAA;AAEtD;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAAG,CAAC,CAAA"}
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,mEAAmE;AACnE,kEAAkE;AAClE,sDAAsD;AAEtD,MAAM,CAAC,MAAM,gBAAgB,GAAG,cAAuB,CAAA;AAEvD;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAAG,CAAC,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livestore/common",
-  "version": "0.4.0-dev.1",
+  "version": "0.4.0-dev.10",
   "type": "module",
   "sideEffects": false,
   "exports": {
@@ -8,20 +8,19 @@
     "./sql-queries": "./dist/sql-queries/index.js",
     "./leader-thread": "./dist/leader-thread/mod.js",
     "./schema": "./dist/schema/mod.js",
+    "./sync": "./dist/sync/index.js",
     "./sync/next": "./dist/sync/next/mod.js",
-    "./sync/next/test": "./dist/sync/next/test/mod.js"
+    "./sync/next/test": "./dist/sync/next/test/mod.js",
+    "./testing": "./dist/testing/mod.js"
   },
   "dependencies": {
     "@opentelemetry/api": "1.9.0",
-    "graphology": "0.26.0-alpha1",
-    "graphology-dag": "0.4.1",
-    "graphology-types": "0.24.8",
-    "@livestore/webmesh": "0.4.0-dev.1",
-    "@livestore/utils": "0.4.0-dev.1"
+    "@livestore/utils": "0.4.0-dev.10",
+    "@livestore/webmesh": "0.4.0-dev.10"
   },
   "devDependencies": {
     "vitest": "3.2.4",
-    "@livestore/utils-dev": "0.4.0-dev.1"
+    "@livestore/utils-dev": "0.4.0-dev.10"
   },
   "files": [
     "package.json",

package/src/ClientSessionLeaderThreadProxy.ts

@@ -1,11 +1,11 @@
-import type { Effect, Stream } from '@livestore/utils/effect'
+import type { Effect, Stream, Subscribable } from '@livestore/utils/effect'
 
 import type { MigrationsReport } from './defs.ts'
 import type * as Devtools from './devtools/mod.ts'
 import type { UnexpectedError } from './errors.ts'
 import type * as EventSequenceNumber from './schema/EventSequenceNumber.ts'
 import type { LiveStoreEvent } from './schema/mod.ts'
-import type { LeaderAheadError } from './sync/sync.ts'
+import type { LeaderAheadError, SyncBackend } from './sync/sync.ts'
 import type { PayloadUpstream, SyncState } from './sync/syncstate.ts'
 
 export interface ClientSessionLeaderThreadProxy {
@@ -28,6 +28,11 @@ export interface ClientSessionLeaderThreadProxy {
   getSyncState: Effect.Effect<SyncState, UnexpectedError>
   /** For debugging purposes it can be useful to manually trigger devtools messages (e.g. to reset the database) */
   sendDevtoolsMessage: (message: Devtools.Leader.MessageToApp) => Effect.Effect<void, UnexpectedError>
+  /**
+   * Reactive stream describing the connectivity between the leader and its upstream sync backend.
+   * Includes raw connection state, last transition timestamp, and devtools overrides (latch state).
+   */
+  networkStatus: Subscribable.Subscribable<SyncBackend.NetworkStatus>
 }
 
 export const of = (

package/src/adapter-types.ts

@@ -10,15 +10,21 @@ import {
 
 import type { ClientSessionLeaderThreadProxy } from './ClientSessionLeaderThreadProxy.ts'
 import type * as Devtools from './devtools/mod.ts'
-import type { IntentionalShutdownCause, SyncError, UnexpectedError } from './errors.ts'
+import type { IntentionalShutdownCause, MaterializeError, UnexpectedError } from './errors.ts'
 import type { LiveStoreSchema } from './schema/mod.ts'
 import type { SqliteDb } from './sqlite-types.ts'
+import type { IsOfflineError, SyncError } from './sync/index.js'
 
 export * as ClientSessionLeaderThreadProxy from './ClientSessionLeaderThreadProxy.ts'
 export * from './defs.ts'
 export * from './errors.ts'
 export * from './sqlite-types.ts'
 
+/**
+ * Runtime handle to an active LiveStore client session within the current process.
+ * Provides direct access to the embedded SQLite database, leader thread bridge,
+ * and lifecycle controls useful for application-level coordination.
+ */
 export interface ClientSession {
   /** SQLite database with synchronous API running in the same thread (usually in-memory) */
   sqliteDb: SqliteDb
@@ -27,7 +33,9 @@ export interface ClientSession {
   sessionId: string
   /** Status info whether current session is leader or not */
   lockStatus: SubscriptionRef.SubscriptionRef<LockStatus>
-  shutdown: (cause: Exit.Exit<IntentionalShutdownCause, UnexpectedError | SyncError>) => Effect.Effect<void>
+  shutdown: (
+    cause: Exit.Exit<IntentionalShutdownCause, UnexpectedError | SyncError | MaterializeError>,
+  ) => Effect.Effect<void>
   /** A proxy API to communicate with the leader thread */
   leaderThread: ClientSessionLeaderThreadProxy
   /** A unique identifier for the current instance of the client session. Used for debugging purposes. */
@@ -121,7 +129,9 @@ export interface AdapterArgs {
   devtoolsEnabled: boolean
   debugInstanceId: string
   bootStatusQueue: Queue.Queue<BootStatus>
-  shutdown: (exit: Exit.Exit<IntentionalShutdownCause, UnexpectedError | SyncError>) => Effect.Effect<void>
+  shutdown: (
+    exit: Exit.Exit<IntentionalShutdownCause, UnexpectedError | SyncError | MaterializeError | IsOfflineError>,
+  ) => Effect.Effect<void>
   connectDevtoolsToStore: ConnectDevtoolsToStore
   /**
    * Payload that will be passed to the sync backend when connecting

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

@@ -2,14 +2,7 @@ import { Schema } from '@livestore/utils/effect'
 
 import { liveStoreVersion as pkgVersion } from '../version.ts'
 
-export const NetworkStatus = Schema.Struct({
-  isConnected: Schema.Boolean,
-  timestampMs: Schema.Number,
-  /** Whether the network status devtools latch is closed. Used to simulate network disconnection. */
-  latchClosed: Schema.Boolean,
-})
-
-export type NetworkStatus = typeof NetworkStatus.Type
+export { NetworkStatus } from '../sync/sync-backend.ts'
 
 export const requestId = Schema.String
 export const clientId = Schema.String

package/src/errors.ts

@@ -1,4 +1,6 @@
-import { Effect, Schema, Stream } from '@livestore/utils/effect'
+import { Cause, Effect, Layer, Schema, Stream } from '@livestore/utils/effect'
+
+import * as LiveStoreEvent from './schema/LiveStoreEvent.ts'
 
 export class UnexpectedError extends Schema.TaggedError<UnexpectedError>()('LiveStore.UnexpectedError', {
   cause: Schema.Defect,
@@ -11,15 +13,30 @@ export class UnexpectedError extends Schema.TaggedError<UnexpectedError>()('Live
       Effect.catchAllDefect((cause) => new UnexpectedError({ cause })),
     )
 
+  static mapToUnexpectedErrorLayer = <A, E, R>(layer: Layer.Layer<A, E, R>) =>
+    layer.pipe(
+      Layer.catchAllCause((cause) =>
+        Cause.isFailType(cause) && Schema.is(UnexpectedError)(cause.error)
+          ? Layer.fail(cause.error)
+          : Layer.fail(new UnexpectedError({ cause: cause })),
+      ),
+    )
+
   static mapToUnexpectedErrorStream = <A, E, R>(stream: Stream.Stream<A, E, R>) =>
     stream.pipe(
       Stream.mapError((cause) => (Schema.is(UnexpectedError)(cause) ? cause : new UnexpectedError({ cause }))),
     )
 }
 
-export class SyncError extends Schema.TaggedError<SyncError>()('LiveStore.SyncError', {
-  cause: Schema.Defect,
-}) {}
+export class MaterializerHashMismatchError extends Schema.TaggedError<MaterializerHashMismatchError>()(
+  'LiveStore.MaterializerHashMismatchError',
+  {
+    eventName: Schema.String,
+    note: Schema.optionalWith(Schema.String, {
+      default: () => 'Please make sure your event materializer is a pure function without side effects.',
+    }),
+  },
+) {}
 
 export class IntentionalShutdownCause extends Schema.TaggedError<IntentionalShutdownCause>()(
   'LiveStore.IntentionalShutdownCause',
@@ -47,3 +64,15 @@ export class SqliteError extends Schema.TaggedError<SqliteError>()('LiveStore.Sq
   cause: Schema.Defect,
   note: Schema.optional(Schema.String),
 }) {}
+
+export class UnknownEventError extends Schema.TaggedError<UnknownEventError>()('LiveStore.UnknownEventError', {
+  event: LiveStoreEvent.AnyEncoded.pipe(Schema.pick('name', 'args', 'seqNum', 'clientId', 'sessionId')),
+  reason: Schema.Literal('event-definition-missing', 'materializer-missing'),
+  operation: Schema.String,
+  note: Schema.optional(Schema.String),
+}) {}
+
+export class MaterializeError extends Schema.TaggedError<MaterializeError>()('LiveStore.MaterializeError', {
+  cause: Schema.Union(MaterializerHashMismatchError, SqliteError, UnknownEventError),
+  note: Schema.optional(Schema.String),
+}) {}