@livestore/common 0.2.0 → 0.3.0-dev.0

package/src/sync/next/history-dag-common.ts

@@ -0,0 +1,44 @@
+import * as EventId from '../../schema/EventId.js'
+import type { MutationEventFactsGroup } from '../../schema/mutations.js'
+import { graphology } from './graphology_.js'
+
+export const connectionTypeOptions = ['parent', 'facts'] as const
+export type ConnectionType = (typeof connectionTypeOptions)[number]
+
+/**
+ * Eventlog represented as a multi-DAG including edges for
+ * - total-order (parent) relationships
+ * - dependency (requires/reads facts) relationships
+ */
+export type HistoryDag = graphology.IGraph<HistoryDagNode, { type: ConnectionType }>
+
+export const emptyHistoryDag = (): HistoryDag =>
+  new graphology.Graph({
+    allowSelfLoops: false,
+    multi: true,
+    type: 'directed',
+  })
+
+// TODO consider making `ROOT_ID` parent to itself
+export const rootParentId = { global: EventId.ROOT.global - 1, local: 0 } satisfies EventId.EventId
+
+export type HistoryDagNode = {
+  id: EventId.EventId
+  parentId: EventId.EventId
+  mutation: string
+  args: any
+  /** Facts are being used for conflict detection and history compaction */
+  factsGroup: MutationEventFactsGroup
+  meta?: any
+}
+
+export const rootEventNode: HistoryDagNode = {
+  id: EventId.ROOT,
+  parentId: rootParentId,
+  // unused below
+  mutation: '__Root__',
+  args: {},
+  factsGroup: { modifySet: new Map(), modifyUnset: new Map(), depRequire: new Map(), depRead: new Map() },
+}
+
+export const EMPTY_FACT_VALUE = Symbol('EMPTY_FACT_VALUE')

package/src/sync/next/history-dag.ts

@@ -1,50 +1,8 @@
-import { type EventId, ROOT_ID } from '../../adapter-types.js'
-import type { MutationEventFactsGroup } from '../../schema/mutations.js'
+import type * as EventId from '../../schema/EventId.js'
 import { factsToString, validateFacts } from './facts.js'
-import { graphology } from './graphology_.js'
+import { emptyHistoryDag, type HistoryDagNode, rootParentId } from './history-dag-common.js'
 
-export const connectionTypeOptions = ['parent', 'facts'] as const
-export type ConnectionType = (typeof connectionTypeOptions)[number]
-
-/**
- * Eventlog represented as a multi-DAG including edges for
- * - total-order (parent) relationships
- * - dependency (requires/reads facts) relationships
- */
-export type HistoryDag = graphology.IGraph<HistoryDagNode, { type: ConnectionType }>
-
-export const emptyHistoryDag = (): HistoryDag =>
-  new graphology.Graph({
-    allowSelfLoops: false,
-    multi: true,
-    type: 'directed',
-  })
-
-// TODO consider making `ROOT_ID` parent to itself
-const rootParentId = { global: ROOT_ID.global - 1, local: 0 } satisfies EventId
-
-export type HistoryDagNode = {
-  id: EventId
-  parentId: EventId
-  mutation: string
-  args: any
-  /** Facts are being used for conflict detection and history compaction */
-  factsGroup: MutationEventFactsGroup
-  meta?: any
-}
-
-export const rootEventNode: HistoryDagNode = {
-  id: ROOT_ID,
-  parentId: rootParentId,
-  // unused below
-  mutation: '__Root__',
-  args: {},
-  factsGroup: { modifySet: new Map(), modifyUnset: new Map(), depRequire: new Map(), depRead: new Map() },
-}
-
-export const EMPTY_FACT_VALUE = Symbol('EMPTY_FACT_VALUE')
-
-export const eventIdToString = (eventId: EventId) =>
+export const eventIdToString = (eventId: EventId.EventId) =>
   eventId.local === 0 ? eventId.global.toString() : `${eventId.global}.${eventId.local}`
 
 export const historyDagFromNodes = (dagNodes: HistoryDagNode[], options?: { skipFactsCheck: boolean }) => {

package/src/sync/next/mod.ts

@@ -1,3 +1,4 @@
+export * from './history-dag-common.js'
 export * from './history-dag.js'
 export * from './facts.js'
 export * from './compact-events.js'

package/src/sync/next/rebase-events.ts

@@ -1,5 +1,6 @@
-import type { EventId } from '../../adapter-types.js'
-import type { MutationDef, MutationEvent, MutationEventFactsSnapshot } from '../../schema/mutations.js'
+import type * as EventId from '../../schema/EventId.js'
+import type * as MutationEvent from '../../schema/MutationEvent.js'
+import type { MutationDef, MutationEventFactsSnapshot } from '../../schema/mutations.js'
 import {
   applyFactGroups,
   factsIntersect,
@@ -7,7 +8,7 @@ import {
   getFactsGroupForMutationArgs,
   validateFacts,
 } from './facts.js'
-import type { HistoryDagNode } from './history-dag.js'
+import type { HistoryDagNode } from './history-dag-common.js'
 
 export type RebaseEventWithConflict = HistoryDagNode & {
   conflictType: 'overlap' | 'missing-requirement'
@@ -88,8 +89,8 @@ export const rebaseEvents = ({
   return rebasedLocalEvents.map(
     (event, index) =>
       ({
-        id: { global: headGlobalId + index + 1, local: 0 } satisfies EventId,
-        parentId: { global: headGlobalId + index, local: 0 } satisfies EventId,
+        id: { global: headGlobalId + index + 1, local: 0 } satisfies EventId.EventId,
+        parentId: { global: headGlobalId + index, local: 0 } satisfies EventId.EventId,
         mutation: event.mutation,
         args: event.args,
       }) satisfies MutationEvent.Any,

package/src/sync/next/test/compact-events.test.ts

@@ -2,8 +2,9 @@ import type { MutationEventFacts } from '@livestore/common/schema'
 import { describe, expect, it } from 'vitest'
 
 import { compactEvents } from '../compact-events.js'
-import type { HistoryDagNode } from '../history-dag.js'
-import { EMPTY_FACT_VALUE, historyDagFromNodes } from '../history-dag.js'
+import { historyDagFromNodes } from '../history-dag.js'
+import type { HistoryDagNode } from '../history-dag-common.js'
+import { EMPTY_FACT_VALUE } from '../history-dag-common.js'
 import { mutations, toEventNodes } from './mutation-fixtures.js'
 
 const customStringify = (value: any): string => {

package/src/sync/next/test/mutation-fixtures.ts

@@ -1,11 +1,12 @@
 import { Schema } from '@livestore/utils/effect'
 
-import { type EventId, ROOT_ID } from '../../../adapter-types.js'
+import * as EventId from '../../../schema/EventId.js'
 import type { MutationDef } from '../../../schema/mutations.js'
 import { defineFacts, defineMutation } from '../../../schema/mutations.js'
 import { factsSnapshotForDag, getFactsGroupForMutationArgs } from '../facts.js'
-import type { HistoryDagNode } from '../history-dag.js'
-import { historyDagFromNodes, rootEventNode } from '../history-dag.js'
+import { historyDagFromNodes } from '../history-dag.js'
+import type { HistoryDagNode } from '../history-dag-common.js'
+import { rootEventNode } from '../history-dag-common.js'
 
 /** Used for conflict detection and event history compaction */
 export const facts = defineFacts({
@@ -137,9 +138,9 @@ export const toEventNodes = (
 ): HistoryDagNode[] => {
   const nodesAcc: HistoryDagNode[] = [rootEventNode]
 
-  let currentEventId: EventId = ROOT_ID
+  let currentEventId: EventId.EventId = EventId.ROOT
 
-  const getNextEventId = (mutationDef: MutationDef.Any): EventId => {
+  const getNextEventId = (mutationDef: MutationDef.Any): EventId.EventId => {
     if (mutationDef.options.localOnly) {
       return { global: currentEventId.global, local: currentEventId.local + 1 }
     }
@@ -218,7 +219,7 @@ export const toEventNodes = (
   return eventNodes
 }
 
-const getParentId = (eventId: EventId): EventId => {
+const getParentId = (eventId: EventId.EventId): EventId.EventId => {
   const globalParentId = eventId.global
   const localParentId = eventId.local - 1
 

package/src/sync/sync.ts

@@ -1,8 +1,8 @@
 import type { Effect, HttpClient, Option, Stream, SubscriptionRef } from '@livestore/utils/effect'
 import { Schema } from '@livestore/utils/effect'
 
-import type { EventId } from '../adapter-types.js'
-import type { MutationEvent } from '../schema/mutations.js'
+import * as EventId from '../schema/EventId.js'
+import type * as MutationEvent from '../schema/MutationEvent.js'
 
 export interface SyncBackendOptionsBase {
   type: string
@@ -12,25 +12,33 @@ export interface SyncBackendOptionsBase {
 export type SyncBackend<TSyncMetadata = Schema.JsonValue> = {
   pull: (
     args: Option.Option<{
-      cursor: EventId
+      cursor: EventId.EventId
       metadata: Option.Option<TSyncMetadata>
     }>,
-    options: { listenForNew: boolean },
   ) => Stream.Stream<
     {
-      mutationEventEncoded: MutationEvent.AnyEncoded
-      metadata: Option.Option<TSyncMetadata>
-      persisted: boolean
+      batch: ReadonlyArray<{
+        mutationEventEncoded: MutationEvent.AnyEncoded
+        metadata: Option.Option<TSyncMetadata>
+      }>
+      remaining: number
     },
     IsOfflineError | InvalidPullError,
     HttpClient.HttpClient
   >
-  // TODO support batching
+  // TODO support transactions (i.e. group of mutation events which need to be applied together)
   push: (
-    mutationEventEncoded: MutationEvent.AnyEncoded,
-    persisted: boolean,
+    /**
+     * Constraints for batch:
+     * - Number of events: 1-100
+     * - event ids must be in ascending order
+     * */
+    batch: ReadonlyArray<MutationEvent.AnyEncoded>,
   ) => Effect.Effect<
-    { metadata: Option.Option<TSyncMetadata> },
+    {
+      /** Indexes are relative to `batch` */
+      metadata: ReadonlyArray<Option.Option<TSyncMetadata>>
+    },
     IsOfflineError | InvalidPushError,
     HttpClient.HttpClient
   >
@@ -39,7 +47,19 @@ export type SyncBackend<TSyncMetadata = Schema.JsonValue> = {
 
 export class IsOfflineError extends Schema.TaggedError<IsOfflineError>()('IsOfflineError', {}) {}
 export class InvalidPushError extends Schema.TaggedError<InvalidPushError>()('InvalidPushError', {
-  message: Schema.String,
+  reason: Schema.Union(
+    Schema.TaggedStruct('Unexpected', {
+      message: Schema.String,
+    }),
+    Schema.TaggedStruct('ServerAhead', {
+      minimumExpectedId: Schema.Number,
+      providedId: Schema.Number,
+    }),
+    Schema.TaggedStruct('LeaderAhead', {
+      minimumExpectedId: EventId.EventId,
+      providedId: EventId.EventId,
+    }),
+  ),
 }) {}
 export class InvalidPullError extends Schema.TaggedError<InvalidPullError>()('InvalidPullError', {
   message: Schema.String,