CrdtSync 1.0.2

CrdtSync

A lightweight State-based LWW-Map CRDT (Last-Writer-Wins Map) sync engine for .NET. Mark properties with [Synced], extend SyncableEntity, and get automatic per-field merge with last-writer-wins conflict resolution.

Features

• Per-field conflict resolution — each property tracks its own timestamp, so concurrent edits to different fields on the same entity never conflict
• Last-Writer-Wins — when two devices edit the same field, the most recent write wins automatically
• Zero configuration — just inherit SyncableEntity, add [Synced] to properties, and implement SyncKey
• Transport agnostic — works with any serialization/transport layer (JSON files, REST APIs, Google Drive, databases, etc.)
• Reflection-cached — property metadata is built once per type and reused across all instances
• INotifyPropertyChanged — built-in change notification for MVVM/UI binding
• Logging — optional Microsoft.Extensions.Logging integration; silent by default

Installation

dotnet add package CrdtSync

Quick Start

1. Define your entity

using CrdtSync;

public class TodoItem : SyncableEntity
{
    private string _title = "";
    private bool _isDone;
    private int _priority;

    // SyncKey matches entities across devices (must be unique)
    public override string SyncKey => _title;

    [Synced]
    public string Title
    {
        get => _title;
        set => SetField(ref _title, value);
    }

    [Synced]
    public bool IsDone
    {
        get => _isDone;
        set => SetField(ref _isDone, value);
    }

    [Synced(ClearValue = 0)]
    public int Priority
    {
        get => _priority;
        set => SetField(ref _priority, value);
    }
}

2. Edit entities (timestamps are tracked automatically)

var item = new TodoItem { SuppressTimestamp = false };
item.Title = "Buy milk";
item.Priority = 3;
// FieldTimestamps now contains UTC timestamps for "Title" and "Priority"

3. Merge from a remote copy

// Single entity merge
bool changed = localItem.MergeFrom(remoteItem);

// Bulk merge — matches by SyncKey, returns changed count + new entities
var (mergeCount, newItems) = SyncableEntity.MergeAll(localList, remoteList, "Device1");
localList.AddRange(newItems);

4. Serialize and transport however you like

using System.Text.Json;

// Serialize
var json = JsonSerializer.Serialize(localList);

// Deserialize (SuppressTimestamp defaults to true, so deserialization won't overwrite timestamps)
var remoteList = JsonSerializer.Deserialize<List<TodoItem>>(json);

API Reference

SyncableEntity (abstract base class)

[Synced] attribute

Logging

CrdtSync uses Microsoft.Extensions.Logging. By default logging is disabled (NullLogger). To enable:

// Option A: Pass an ILogger directly
SyncableEntity.SetLogger(myLogger);

// Option B: Pass an ILoggerFactory
SyncableEntity.SetLogger(loggerFactory);

// With Serilog (add Serilog.Extensions.Logging package):
using Serilog.Extensions.Logging;
SyncableEntity.SetLogger(new SerilogLoggerFactory(Log.Logger).CreateLogger("CrdtSync"));

How It Works

CrdtSync implements a State-based LWW-Map CRDT:

1. Each entity has a FieldTimestamps dictionary mapping property names to their last-edit UTC time
2. When SetField is called (and SuppressTimestamp is false), the field's timestamp is set to DateTime.UtcNow
3. During MergeFrom, each [Synced] property is compared by timestamp — the newer value wins
4. MergeAll matches entities across lists using SyncKey, merges existing ones, and returns entities that only exist remotely

This means:

• No central server needed — any device can merge with any other device
• Offline-friendly — edits accumulate timestamps locally and resolve on next sync
• No data loss — only individual fields are overwritten, not entire objects

Supported Property Types

Any type that works with EqualityComparer<T>.Default and can be set via reflection:

• string (default clear value: "")
• int, bool, double, float, decimal
• DateTime, Guid
• Enums
• Any serializable reference type

Requirements

• .NET 8.0 or later
• Microsoft.Extensions.Logging.Abstractions (included automatically)

License

MIT