plugin-sync

@objectql/plugin-sync

Offline-first sync plugin for ObjectQL — mutation logging, sync engine, and conflict resolution.

Features

📝 Mutation Logging

• Client-side append-only mutation log
• Automatic sequence numbering and timestamping
• Per-object mutation filtering
• Batch acknowledgment after successful sync

🔄 Sync Engine

• Push/pull synchronization between client and server
• Configurable sync direction (push-only, pull-only, bidirectional)
• Debounced auto-sync on mutation
• Checkpoint-based delta tracking

⚔️ Conflict Resolution

• Last-Write-Wins (LWW): Timestamp-based resolution
• CRDT: Field-level LWW-Register merge
• Manual: Callback-driven resolution for user intervention
• Factory function for strategy selection

📡 Event System

• Lifecycle listeners (onSyncStart, onSyncComplete, onSyncError)
• Conflict and server change notifications
• Global and per-engine listener support

Installation

pnpm add @objectql/plugin-sync

Quick Start

import { SyncPlugin } from '@objectql/plugin-sync';
import { createKernel } from '@objectstack/runtime';

const kernel = createKernel({
  plugins: [
    new SyncPlugin({
      clientId: 'device-abc-123',
      transport: myHttpTransport,
      defaultConfig: {
        enabled: true,
        strategy: 'last-write-wins',
        debounce_ms: 1000,
        batch_size: 50,
      },
      listeners: [{
        onSyncComplete(response) {
          console.log('Sync complete:', response.checkpoint);
        },
        onConflict(conflicts) {
          console.warn('Conflicts detected:', conflicts.length);
        },
      }],
    })
  ]
});

await kernel.start();

MutationLogger

The MutationLogger records all client-side mutations in an append-only log for later synchronization.

import { MutationLogger } from '@objectql/plugin-sync';

const logger = new MutationLogger('device-abc-123');

// Record a mutation
const entry = logger.append({
  objectName: 'task',
  recordId: 'task-1',
  operation: 'update',
  data: { status: 'completed' },
  baseVersion: 3,
});

// Get all pending mutations
const pending = logger.getPending();

// Get pending for a specific object
const taskMutations = logger.getPendingForObject('task');

// Acknowledge synced mutations
logger.acknowledge(['mutation-id-1', 'mutation-id-2']);

// Check pending count
console.log(logger.size); // => 0

Conflict Resolution Strategies

Last-Write-Wins (LWW)

Compares client and server timestamps. The most recent write wins.

import { LastWriteWinsResolver } from '@objectql/plugin-sync';

const resolver = new LastWriteWinsResolver();
const result = resolver.resolve(conflict);
// result.status => 'applied' (client wins) or 'conflict' (server wins)

CRDT (Field-Level Merge)

Performs field-level LWW-Register merge. Non-conflicting fields from the client are applied; conflicting fields retain the server value.

import { CrdtResolver } from '@objectql/plugin-sync';

const resolver = new CrdtResolver();
const result = resolver.resolve(conflict);
// Merges non-conflicting fields from both sides

Manual Resolution

Flags conflicts for manual resolution via a user-provided callback.

import { ManualResolver } from '@objectql/plugin-sync';

const resolver = new ManualResolver((conflict) => {
  // Return merged data to resolve, or undefined to keep as conflict
  return {
    ...conflict.serverRecord,
    ...conflict.clientMutation.data,
    resolved_by: 'user',
  };
});

Factory Function

Use createResolver() to instantiate a resolver by strategy name.

import { createResolver } from '@objectql/plugin-sync';

const resolver = createResolver('crdt');
// => CrdtResolver instance

SyncEngine Configuration

The SyncEngine orchestrates the full push/pull sync cycle.

import { SyncEngine } from '@objectql/plugin-sync';
import type { SyncTransport } from '@objectql/plugin-sync';

const transport: SyncTransport = {
  async push(request) {
    const res = await fetch('/api/sync/push', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(request),
    });
    return res.json();
  },
};

const engine = new SyncEngine({
  clientId: 'device-abc-123',
  transport,
  config: {
    enabled: true,
    strategy: 'last-write-wins',
    direction: 'bidirectional',
    debounce_ms: 2000,
    batch_size: 50,
  },
});

// Record a mutation (auto-triggers debounced sync)
engine.recordMutation({
  objectName: 'task',
  recordId: 'task-42',
  operation: 'update',
  data: { title: 'Updated title' },
  baseVersion: 5,
});

// Manual sync trigger
const response = await engine.sync();

// Listen to sync events
engine.addListener({
  onSyncStart() { console.log('Syncing...'); },
  onSyncComplete(res) { console.log('Done:', res.checkpoint); },
  onSyncError(err) { console.error('Failed:', err.message); },
  onServerChanges(changes) { console.log('Server changes:', changes.length); },
});

SyncConfig Options

Property	Type	Default	Description
enabled	boolean	true	Enable sync for this object
strategy	'last-write-wins' | 'crdt' | 'manual'	'last-write-wins'	Conflict resolution strategy
direction	'push-only' | 'pull-only' | 'bidirectional'	'bidirectional'	Sync direction
debounce_ms	number	1000	Debounce interval for auto-sync (ms)
batch_size	number	50	Maximum mutations per sync request

API Reference

Classes

Class	Description
SyncPlugin	RuntimePlugin — registers sync capabilities on kernel
SyncEngine	Client-side push/pull sync orchestrator
MutationLogger	Append-only client-side mutation log
LastWriteWinsResolver	Timestamp-based LWW conflict resolver
CrdtResolver	Field-level LWW-Register merge resolver
ManualResolver	Callback-driven manual conflict resolver

Functions

Function	Description
createResolver(strategy, onConflict?)	Factory for ConflictResolver instances

Types

Type	Description
SyncPluginConfig	Plugin constructor options
SyncTransport	Transport interface for push requests
SyncEventListener	Listener interface for sync lifecycle events
ConflictResolver	Interface for conflict resolution strategies
SyncConfig	Per-object sync configuration
MutationLogEntry	Single mutation log record
SyncConflict	Conflict descriptor with client/server data

License

MIT