@mengine/sync 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,221 @@
+import { LoroDoc } from "loro-crdt";
+import { Disposable } from "@mengine/utils";
+import { DocStorage } from "@mengine/storage";
+
+//#region src/sync/api.d.ts
+interface SynchronizingDocState {
+  docId: string;
+  syncing: boolean;
+  retrying: boolean;
+  synced: boolean;
+  error: string | null;
+}
+interface SynchronizerState {
+  syncing: boolean;
+  retrying: boolean;
+  error: string | null;
+}
+interface Synchronizer {
+  /**
+   * Start automatically updates synchronization.
+   */
+  start(): void;
+  /**
+   * Stop automatically updates synchronization.
+   */
+  stop(): void;
+  /**
+   * Get the state of the synchronizer.
+   */
+  getState(): SynchronizerState;
+  /**
+   * Subscribe to the state changes of the synchronizer.
+   */
+  onStateChange(callback: (state: SynchronizerState) => void): () => void;
+  /**
+   * Get the state of a document.
+   */
+  getDocState(docId: string): SynchronizingDocState;
+  /**
+   * Subscribe to the state changes of a document.
+   */
+  onDocStateChange(docId: string, callback: (state: SynchronizingDocState) => void): () => void;
+  /**
+   * Add a document synchronization job delegation to the Synchronizer.
+   */
+  connectDoc(docId: string, doc: LoroDoc): void;
+  /**
+   * Remove a document synchronization job delegation from the Synchronizer.
+   */
+  disconnectDoc(docId: string): void;
+  /**
+   * Request a one-off sync for a connected document.
+   *
+   * The apply path imports single updates that may arrive out of causal order;
+   * Loro buffers such an update as `pending` and resolves it only once its
+   * missing dependency arrives. Nothing on the apply path fetches that
+   * dependency, so a lone out-of-order update would stay pending indefinitely.
+   * Callers invoke this after observing a pending import to schedule a
+   * version-vector diff that pulls the missing causal closure. No-ops if the
+   * document is not connected.
+   */
+  requestSync(docId: string): void;
+}
+//#endregion
+//#region src/sync/synchronizers/client-server.d.ts
+declare class ClientServerSynchronizer implements Synchronizer {
+  private readonly local;
+  private readonly server;
+  readonly id: string;
+  private readonly event;
+  private abort;
+  private docs;
+  /**
+   * Signal fired whenever a new job is scheduled. The connect cycle blocks on
+   * this promise after draining the job queue so the loop does not spin while
+   * there is nothing to do.
+   */
+  private wakeUp;
+  private status;
+  constructor(local: DocStorage, server: DocStorage);
+  start(): void;
+  stop(): void;
+  getState(): SynchronizerState;
+  onStateChange(callback: (state: SynchronizerState) => void): () => void;
+  getDocState(docId: string): SynchronizingDocState;
+  onDocStateChange(docId: string, callback: (state: SynchronizingDocState) => void): () => void;
+  connectDoc(docId: string, doc: LoroDoc): void;
+  disconnectDoc(docId: string): void;
+  requestSync(docId: string): void;
+  private mainLoop;
+  private connectLoop;
+  private schedule;
+  /** Returns true when at least one watched doc has pending jobs. */
+  private hasPendingJobs;
+  /**
+   * Fire any waiter currently parked on the wake up signal and install a fresh
+   * one for the next round of waiters.
+   */
+  private wake;
+  /**
+   * Resolve when either a new job arrives or the cycle is aborted. Short
+   * circuits synchronously if jobs are already pending so we never miss a
+   * push that happened between draining and re-arming the waiter.
+   */
+  private waitForJobs;
+  private consumeJobs;
+  private updateStatus;
+  private waitConnectionReady;
+  private pushUpdatesToRemote;
+  private pullUpdatesFromRemote;
+  private saveDocUpdates;
+  private syncWithRemote;
+}
+//#endregion
+//#region src/sync/synchronizers/dummy.d.ts
+declare class DummySynchronizer implements Synchronizer {
+  getState(): SynchronizerState;
+  onStateChange(_callback: (state: SynchronizerState) => void): () => void;
+  start(): void;
+  stop(): void;
+  getDocState(docId: string): SynchronizingDocState;
+  onDocStateChange(_docId: string, _callback: (state: SynchronizingDocState) => void): () => void;
+  connectDoc(_docId: string, _doc: LoroDoc): void;
+  disconnectDoc(_docId: string): void;
+  requestSync(_docId: string): void;
+}
+//#endregion
+//#region src/manager/job.d.ts
+type ManagerJobs = {
+  type: 'apply';
+  payload: {
+    update: Uint8Array;
+  };
+} | {
+  type: 'load';
+  payload: null;
+} | {
+  type: 'save';
+  payload: {
+    update: Uint8Array;
+  };
+};
+declare class ManagerJob<T extends ManagerJobs['type'] = ManagerJobs['type']> {
+  readonly type: T;
+  readonly payload: Extract<ManagerJobs, {
+    type: T;
+  }>['payload'];
+  constructor(type: T, payload: Extract<ManagerJobs, {
+    type: T;
+  }>['payload']);
+  static apply(update: Uint8Array): ManagerJob<"apply">;
+  static load(): ManagerJob<"load">;
+  static save(update: Uint8Array): ManagerJob<"save">;
+}
+//#endregion
+//#region src/manager/doc.d.ts
+interface ManagedDocState {
+  docId: string;
+  loaded: boolean;
+  error: string | null;
+}
+declare class ManagedDoc extends Disposable {
+  readonly docId: string;
+  readonly doc: LoroDoc;
+  readonly state: ManagedDocState;
+  readonly jobs: ManagerJob[];
+  private readonly eventBus;
+  private readonly disposables;
+  constructor(docId: string, doc: LoroDoc);
+  dispose(): void;
+  setState(state: Partial<ManagedDocState>): void;
+  onStateChanged(callback: (state: ManagedDocState) => void): () => void;
+  onDocChanged(callback: (update: Uint8Array) => void): () => void;
+}
+//#endregion
+//#region src/manager/index.d.ts
+type DocState = ManagedDocState & SynchronizingDocState;
+declare class DocManager {
+  readonly storage: DocStorage;
+  readonly synchronizer: Synchronizer;
+  readonly origin: string;
+  readonly docs: Map<string, ManagedDoc>;
+  private abort;
+  private event;
+  private wakeUp;
+  constructor(storage: DocStorage, synchronizer: Synchronizer);
+  start(): void;
+  stop(): void;
+  connectDoc(id: string): LoroDoc;
+  disconnectDoc(id: string): void;
+  getDocState(docId: string): DocState;
+  onDocStateChange(docId: string, callback: (state: DocState) => void): () => void;
+  private getManagedDoc;
+  private mainLoop;
+  private bindDoc;
+  private wake;
+  private schedule;
+  private hasPendingJobs;
+  private waitForJobs;
+  private consumeJobs;
+  /**
+   * Handling [load] jobs.
+   *
+   * The [load] jobs only come from new doc managed by [DocManager].
+   */
+  private loadDoc;
+  /**
+   * Handling [save] jobs.
+   *
+   * The [save] jobs only come from local changes.
+   */
+  private saveDoc;
+  /**
+   * Handling [apply] jobs.
+   *
+   * The [apply] jobs only come from local storage changes(cross-tab updates, server-side updates, etc.).
+   */
+  private applyDocUpdate;
+}
+//#endregion
+export { ClientServerSynchronizer, DocManager, DocState, DummySynchronizer, Synchronizer, SynchronizerState, SynchronizingDocState };

package/dist/index.js

@@ -0,0 +1,660 @@
+import { remove } from "lodash-es";
+import { LoroDoc, VersionVector } from "loro-crdt";
+import { nanoid } from "nanoid";
+import { Disposable, DisposableSet, EventBus, MANUALLY_STOP, Task, runWithCheckpoint } from "@mengine/utils";
+//#region src/utils.ts
+function createWakeUpSignal() {
+	const { promise, resolve } = Promise.withResolvers();
+	return {
+		promise,
+		wake: resolve
+	};
+}
+//#endregion
+//#region src/manager/job.ts
+var ManagerJob = class ManagerJob {
+	type;
+	payload;
+	constructor(type, payload) {
+		this.type = type;
+		this.payload = payload;
+	}
+	static apply(update) {
+		return new ManagerJob("apply", { update });
+	}
+	static load() {
+		return new ManagerJob("load", null);
+	}
+	static save(update) {
+		return new ManagerJob("save", { update });
+	}
+};
+//#endregion
+//#region src/manager/doc.ts
+var ManagedDoc = class extends Disposable {
+	docId;
+	doc;
+	state;
+	jobs = [];
+	eventBus = new EventBus();
+	disposables = new DisposableSet();
+	constructor(docId, doc) {
+		super();
+		this.docId = docId;
+		this.doc = doc;
+		this.state = {
+			docId: this.docId,
+			loaded: false,
+			error: null
+		};
+		this.disposables.add(() => {
+			this.jobs.splice(0, this.jobs.length);
+		});
+		this.disposables.add(this.doc.subscribeLocalUpdates((update) => {
+			this.eventBus.emit("docChanged", { update });
+		}));
+	}
+	dispose() {
+		this.disposables.dispose();
+	}
+	setState(state) {
+		Object.assign(this.state, state);
+		this.eventBus.emit("stateChanged", { state: this.state });
+	}
+	onStateChanged(callback) {
+		const off = this.eventBus.on("stateChanged", ({ state }) => {
+			callback(state);
+		});
+		this.disposables.add(off);
+		return off;
+	}
+	onDocChanged(callback) {
+		const off = this.eventBus.on("docChanged", ({ update }) => {
+			callback(update);
+		});
+		this.disposables.add(off);
+		return off;
+	}
+};
+//#endregion
+//#region src/manager/index.ts
+const hasUpdateData$1 = (update) => {
+	return update.byteLength > 0;
+};
+var DocManager = class {
+	storage;
+	synchronizer;
+	origin = `DocManager:${nanoid(10)}`;
+	docs = /* @__PURE__ */ new Map();
+	abort = null;
+	event = new EventBus();
+	wakeUp = createWakeUpSignal();
+	constructor(storage, synchronizer) {
+		this.storage = storage;
+		this.synchronizer = synchronizer;
+	}
+	start() {
+		if (this.abort) return;
+		this.abort = new AbortController();
+		this.mainLoop(this.abort.signal).catch((e) => {
+			if (e === MANUALLY_STOP) return;
+			console.error(e);
+		});
+	}
+	stop() {
+		this.abort?.abort(MANUALLY_STOP);
+		this.abort = null;
+	}
+	connectDoc(id) {
+		let managedDoc = this.docs.get(id);
+		if (!managedDoc) {
+			managedDoc = new ManagedDoc(id, new LoroDoc());
+			this.docs.set(id, managedDoc);
+			this.bindDoc(managedDoc);
+		}
+		return managedDoc.doc;
+	}
+	disconnectDoc(id) {
+		const managedDoc = this.getManagedDoc(id);
+		if (!managedDoc) return;
+		this.synchronizer.disconnectDoc(id);
+		managedDoc.dispose();
+		this.docs.delete(id);
+	}
+	getDocState(docId) {
+		const managedDoc = this.getManagedDoc(docId);
+		if (!managedDoc) return {
+			docId,
+			loaded: false,
+			syncing: false,
+			retrying: false,
+			synced: false,
+			error: null
+		};
+		return {
+			...managedDoc.state,
+			...this.synchronizer.getDocState(docId)
+		};
+	}
+	onDocStateChange(docId, callback) {
+		const unsubscribeSyncWatcher = this.synchronizer.onDocStateChange(docId, (state) => {
+			const managedDoc = this.getManagedDoc(docId);
+			if (!managedDoc) return;
+			callback({
+				...managedDoc.state,
+				...state
+			});
+		});
+		const unsubscribeManagerWatcher = this.event.on("managedDocStateChanged", (state) => {
+			if (state.docId !== docId) return;
+			callback({
+				...state,
+				...this.synchronizer.getDocState(docId)
+			});
+		});
+		return () => {
+			unsubscribeSyncWatcher();
+			unsubscribeManagerWatcher();
+		};
+	}
+	getManagedDoc(docId) {
+		return this.docs.get(docId) ?? null;
+	}
+	async mainLoop(signal) {
+		await this.storage.connection.waitForConnected().abortOn(signal);
+		const dispose = this.storage.subscribeDocUpdate((update, origin) => {
+			if (origin === this.origin) return;
+			this.schedule(update.docId, ManagerJob.apply(update.data));
+		});
+		try {
+			while (true) {
+				await this.consumeJobs(signal);
+				await this.waitForJobs().abortOn(signal);
+			}
+		} catch (err) {
+			if (signal.aborted) return;
+			console.warn("manager main loop error", err);
+		} finally {
+			dispose();
+		}
+	}
+	bindDoc(doc) {
+		this.schedule(doc.docId, ManagerJob.load());
+		doc.onDocChanged((update) => {
+			this.schedule(doc.docId, ManagerJob.save(update));
+		});
+		doc.onStateChanged((state) => {
+			this.event.emit("managedDocStateChanged", state);
+		});
+	}
+	wake() {
+		const previous = this.wakeUp;
+		this.wakeUp = createWakeUpSignal();
+		previous.wake();
+	}
+	schedule(id, job) {
+		let doc = this.docs.get(id);
+		if (!doc) return;
+		doc.jobs.push(job);
+		this.wake();
+	}
+	hasPendingJobs() {
+		for (const doc of this.docs.values()) if (doc.jobs.length > 0) return true;
+		return false;
+	}
+	waitForJobs() {
+		return Task.spawn(async () => {
+			if (this.hasPendingJobs()) return;
+			await this.wakeUp.promise;
+		});
+	}
+	async consumeJobs(signal) {
+		return runWithCheckpoint(signal, async () => {
+			for (const doc of this.docs.values()) {
+				const jobs = doc.jobs;
+				if (!jobs.length) continue;
+				if (remove(jobs, (j) => j.type === "load").length) await Task.spawn(() => this.loadDoc(doc.docId)).abortOn(signal);
+				const apply = remove(jobs, (j) => j.type === "apply");
+				for (const job of apply) await Task.spawn(() => this.applyDocUpdate(doc.docId, job.payload.update)).abortOn(signal);
+				const save = remove(jobs, (j) => j.type === "save");
+				for (const job of save) await Task.spawn(() => this.saveDoc(doc.docId, job.payload.update)).abortOn(signal);
+			}
+		});
+	}
+	/**
+	* Handling [load] jobs.
+	*
+	* The [load] jobs only come from new doc managed by [DocManager].
+	*/
+	async loadDoc(docId) {
+		const managedDoc = this.docs.get(docId);
+		if (!managedDoc) return;
+		if (managedDoc.doc.changeCount() > 0) this.schedule(docId, ManagerJob.save(managedDoc.doc.export({ mode: "update" })));
+		const snapshot = await this.storage.getDoc(docId);
+		if (snapshot && hasUpdateData$1(snapshot.data)) managedDoc.doc.import(snapshot.data);
+		this.synchronizer.connectDoc(docId, managedDoc.doc);
+		managedDoc.setState({ loaded: true });
+	}
+	/**
+	* Handling [save] jobs.
+	*
+	* The [save] jobs only come from local changes.
+	*/
+	async saveDoc(docId, update) {
+		if (!hasUpdateData$1(update)) return;
+		await this.storage.pushDocUpdate({
+			docId,
+			data: update
+		}, this.origin);
+	}
+	/**
+	* Handling [apply] jobs.
+	*
+	* The [apply] jobs only come from local storage changes(cross-tab updates, server-side updates, etc.).
+	*/
+	async applyDocUpdate(docId, update) {
+		if (!hasUpdateData$1(update)) return;
+		const managedDoc = this.docs.get(docId);
+		if (!managedDoc) return;
+		if (managedDoc.doc.import(update).pending != null) this.synchronizer.requestSync(docId);
+	}
+};
+//#endregion
+//#region src/sync/job.ts
+var SynchronizerJob = class SynchronizerJob {
+	type;
+	payload;
+	constructor(type, payload) {
+		this.type = type;
+		this.payload = payload;
+	}
+	static push(update) {
+		return new SynchronizerJob("push", { update });
+	}
+	static pull() {
+		return new SynchronizerJob("pull", null);
+	}
+	static sync() {
+		return new SynchronizerJob("sync", null);
+	}
+	static save(update) {
+		return new SynchronizerJob("save", { update });
+	}
+};
+//#endregion
+//#region src/sync/doc.ts
+var SynchronizingDoc = class extends Disposable {
+	docId;
+	doc;
+	state;
+	jobs = [];
+	eventBus = new EventBus();
+	disposables = new DisposableSet();
+	constructor(docId, doc) {
+		super();
+		this.docId = docId;
+		this.doc = doc;
+		this.state = {
+			docId,
+			syncing: false,
+			retrying: false,
+			synced: false,
+			error: null
+		};
+		this.disposables.add(() => {
+			this.jobs.splice(0, this.jobs.length);
+			this.eventBus.clearAll();
+		});
+	}
+	setState(state) {
+		Object.assign(this.state, state);
+		this.eventBus.emit("stateChanged", { state: this.state });
+	}
+	onStateChanged(callback) {
+		const off = this.eventBus.on("stateChanged", ({ state }) => {
+			callback(state);
+		});
+		this.disposables.add(off);
+		return off;
+	}
+	dispose() {
+		this.disposables.dispose();
+	}
+};
+//#endregion
+//#region src/sync/synchronizers/client-server.ts
+const hasUpdateData = (update) => {
+	return update.byteLength > 0;
+};
+const SYNCHRONIZER_ORIGIN_PREFIX = "ClientServerSynchronizer:";
+const isSynchronizerOrigin = (origin) => {
+	return typeof origin === "string" && origin.startsWith(SYNCHRONIZER_ORIGIN_PREFIX);
+};
+var ClientServerSynchronizer = class {
+	local;
+	server;
+	id = `${SYNCHRONIZER_ORIGIN_PREFIX}${nanoid(10)}`;
+	event = new EventBus();
+	abort = null;
+	docs = /* @__PURE__ */ new Map();
+	/**
+	* Signal fired whenever a new job is scheduled. The connect cycle blocks on
+	* this promise after draining the job queue so the loop does not spin while
+	* there is nothing to do.
+	*/
+	wakeUp = createWakeUpSignal();
+	status = {
+		syncing: false,
+		retrying: false,
+		error: null
+	};
+	constructor(local, server) {
+		this.local = local;
+		this.server = server;
+	}
+	start() {
+		if (this.abort) return;
+		this.abort = new AbortController();
+		this.mainLoop(this.abort.signal).catch((e) => {
+			if (e === MANUALLY_STOP) return;
+			console.error(e);
+		});
+	}
+	stop() {
+		this.abort?.abort(MANUALLY_STOP);
+		this.abort = null;
+		this.updateStatus({
+			syncing: false,
+			retrying: false,
+			error: null
+		});
+	}
+	getState() {
+		return this.status;
+	}
+	onStateChange(callback) {
+		return this.event.on("stateChanged", callback);
+	}
+	getDocState(docId) {
+		const doc = this.docs.get(docId);
+		if (!doc) return {
+			docId,
+			syncing: false,
+			retrying: false,
+			synced: false,
+			error: null
+		};
+		return doc.state;
+	}
+	onDocStateChange(docId, callback) {
+		return this.event.on("docStateChanged", (state) => {
+			if (state.docId === docId) callback(state);
+		});
+	}
+	connectDoc(docId, doc) {
+		if (!this.docs.has(docId)) {
+			const synchronizingDoc = new SynchronizingDoc(docId, doc);
+			synchronizingDoc.onStateChanged((state) => {
+				this.event.emit("docStateChanged", state);
+			});
+			this.docs.set(docId, synchronizingDoc);
+		}
+		this.schedule(docId, SynchronizerJob.sync());
+	}
+	disconnectDoc(docId) {
+		let doc = this.docs.get(docId);
+		if (doc) {
+			doc.dispose();
+			this.docs.delete(docId);
+		}
+	}
+	requestSync(docId) {
+		if (!this.docs.has(docId)) return;
+		this.schedule(docId, SynchronizerJob.sync());
+	}
+	async mainLoop(signal) {
+		while (true) {
+			try {
+				await this.connectLoop(signal);
+			} catch (err) {
+				if (signal.aborted) return;
+				console.warn("synchronizer main loop error, retry in 5s", err);
+				this.updateStatus({
+					syncing: false,
+					retrying: true,
+					error: err instanceof Error ? err.message : String(err)
+				});
+			} finally {
+				this.updateStatus({
+					syncing: false,
+					retrying: true
+				});
+			}
+			await Task.delay(5e3).abortOn(signal);
+		}
+	}
+	async connectLoop(signal) {
+		return runWithCheckpoint(signal, async () => {
+			const abort = new AbortController();
+			const propagateAbort = () => {
+				abort.abort(signal.reason);
+			};
+			if (signal.aborted) propagateAbort();
+			else signal.addEventListener("abort", propagateAbort);
+			const cycleSignal = abort.signal;
+			const disposes = [];
+			try {
+				await this.waitConnectionReady(cycleSignal);
+				console.info("Remote synchronization started");
+				this.updateStatus({
+					syncing: true,
+					retrying: false
+				});
+				disposes.push(this.local.connection.onStatusChanged((status, error) => {
+					abort.abort(/* @__PURE__ */ new Error(`Local connection status changed to ${status}, error: ${error?.message}`));
+				}));
+				disposes.push(this.server.connection.onStatusChanged((status, error) => {
+					abort.abort(/* @__PURE__ */ new Error(`Server connection status changed to ${status}, error: ${error?.message}`));
+				}));
+				disposes.push(this.local.subscribeDocUpdate((docRecord, origin) => {
+					if (isSynchronizerOrigin(origin)) return;
+					this.schedule(docRecord.docId, SynchronizerJob.push(docRecord.data));
+				}));
+				disposes.push(this.server.subscribeDocUpdate((docRecord, origin) => {
+					if (origin === this.id) return;
+					this.schedule(docRecord.docId, SynchronizerJob.save(docRecord.data));
+				}));
+				for (const docId of this.docs.keys()) this.schedule(docId, SynchronizerJob.sync());
+				while (!cycleSignal.aborted) {
+					await this.consumeJobs(cycleSignal);
+					await this.waitForJobs().abortOn(cycleSignal);
+				}
+			} finally {
+				signal.removeEventListener("abort", propagateAbort);
+				for (const dispose of disposes) try {
+					dispose();
+				} catch (err) {
+					console.error("Failed to dispose synchronizer resource", err);
+				}
+				this.updateStatus({ syncing: false });
+				console.info("Remote synchronization stopped");
+			}
+		});
+	}
+	schedule(docId, job) {
+		const docState = this.docs.get(docId);
+		if (!docState) {
+			console.warn(`Doc ${docId} not added`);
+			return;
+		}
+		docState.setState({ synced: false });
+		docState.jobs.push(job);
+		this.wake();
+	}
+	/** Returns true when at least one watched doc has pending jobs. */
+	hasPendingJobs() {
+		for (const doc of this.docs.values()) if (doc.jobs.length > 0) return true;
+		return false;
+	}
+	/**
+	* Fire any waiter currently parked on the wake up signal and install a fresh
+	* one for the next round of waiters.
+	*/
+	wake() {
+		const previous = this.wakeUp;
+		this.wakeUp = createWakeUpSignal();
+		previous.wake();
+	}
+	/**
+	* Resolve when either a new job arrives or the cycle is aborted. Short
+	* circuits synchronously if jobs are already pending so we never miss a
+	* push that happened between draining and re-arming the waiter.
+	*/
+	waitForJobs() {
+		return Task.spawn(async () => {
+			if (this.hasPendingJobs()) return;
+			await this.wakeUp.promise;
+		});
+	}
+	async consumeJobs(signal) {
+		return runWithCheckpoint(signal, async () => {
+			for (const doc of this.docs.values()) {
+				const jobs = doc.jobs;
+				if (!doc.jobs.length) continue;
+				doc.setState({
+					syncing: true,
+					retrying: false,
+					synced: false,
+					error: null
+				});
+				try {
+					if (remove(jobs, (j) => j.type === "sync").length) await this.syncWithRemote(doc, signal);
+					const push = remove(jobs, (j) => j.type === "push");
+					if (push.length) await this.pushUpdatesToRemote(doc, push.map((j) => j.payload.update), signal);
+					if (remove(jobs, (j) => j.type === "pull").length) await this.pullUpdatesFromRemote(doc, signal);
+					const save = remove(jobs, (j) => j.type === "save");
+					if (save.length) await this.saveDocUpdates(doc, save.map((j) => j.payload.update), signal);
+					doc.setState({
+						syncing: false,
+						retrying: false,
+						synced: true,
+						error: null
+					});
+				} catch (error) {
+					doc.setState({
+						syncing: false,
+						retrying: true,
+						synced: false,
+						error: error instanceof Error ? error.message : String(error)
+					});
+					throw error;
+				}
+			}
+		});
+	}
+	updateStatus(status) {
+		this.status = {
+			...this.status,
+			...status
+		};
+		this.event.emit("stateChanged", this.status);
+	}
+	async waitConnectionReady(signal) {
+		return runWithCheckpoint(signal, async () => {
+			const localConnected = this.local.connection.waitForConnected();
+			const serverConnected = this.server.connection.waitForConnected();
+			await Task.all([localConnected, serverConnected]).timeout(30 * 1e3).abortOn(signal);
+		});
+	}
+	async pushUpdatesToRemote(docState, updates, signal) {
+		return runWithCheckpoint(signal, async () => {
+			await Promise.allSettled(updates.filter(hasUpdateData).map((update) => {
+				return this.server.pushDocUpdate({
+					docId: docState.docId,
+					data: update
+				}, this.id);
+			}));
+		});
+	}
+	async pullUpdatesFromRemote(docState, signal) {
+		return runWithCheckpoint(signal, async () => {
+			const doc = docState.doc;
+			const serverDoc = await this.server.getDocDiff(docState.docId, doc.version().encode());
+			if (!serverDoc) return;
+			const { missing } = serverDoc;
+			if (hasUpdateData(missing)) {
+				doc.import(missing);
+				await this.local.pushDocUpdate({
+					docId: docState.docId,
+					data: missing
+				}, this.id);
+			}
+		});
+	}
+	async saveDocUpdates(docState, updates, signal) {
+		return runWithCheckpoint(signal, async () => {
+			for (const update of updates.filter(hasUpdateData)) await this.local.pushDocUpdate({
+				docId: docState.docId,
+				data: update
+			}, this.id);
+		});
+	}
+	async syncWithRemote(docState, signal) {
+		return runWithCheckpoint(signal, async () => {
+			const localDoc = docState.doc;
+			const response = await this.server.getDocDiff(docState.docId, localDoc.version().encode());
+			let serverMissing = null;
+			if (response) {
+				const { missing, version } = response;
+				if (hasUpdateData(missing)) {
+					localDoc.import(missing);
+					await this.local.pushDocUpdate({
+						docId: docState.docId,
+						data: missing
+					}, this.id);
+				}
+				serverMissing = localDoc.export({
+					mode: "update",
+					from: VersionVector.decode(version)
+				});
+			} else serverMissing = localDoc.export({ mode: "update" });
+			if (serverMissing && hasUpdateData(serverMissing)) await this.server.pushDocUpdate({
+				docId: docState.docId,
+				data: serverMissing
+			}, this.id);
+		});
+	}
+};
+//#endregion
+//#region src/sync/synchronizers/dummy.ts
+var DummySynchronizer = class {
+	getState() {
+		return {
+			syncing: false,
+			retrying: false,
+			error: null
+		};
+	}
+	onStateChange(_callback) {
+		return () => {};
+	}
+	start() {}
+	stop() {}
+	getDocState(docId) {
+		return {
+			docId,
+			syncing: false,
+			retrying: false,
+			synced: false,
+			error: null
+		};
+	}
+	onDocStateChange(_docId, _callback) {
+		return () => {};
+	}
+	connectDoc(_docId, _doc) {}
+	disconnectDoc(_docId) {}
+	requestSync(_docId) {}
+};
+//#endregion
+export { ClientServerSynchronizer, DocManager, DummySynchronizer };

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@mengine/sync",
+  "version": "0.1.0",
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/one2x-ai/medeo-engine.git",
+    "directory": "packages/connector"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "exports": {
+      ".": "./dist/index.js",
+      "./package.json": "./package.json"
+    },
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "vp pack",
+    "dev": "vp pack --watch",
+    "test": "vp test",
+    "prepublishOnly": "vp pack"
+  },
+  "dependencies": {
+    "nanoid": "catalog:"
+  },
+  "devDependencies": {
+    "@types/lodash-es": "catalog:",
+    "@types/node": "catalog:",
+    "@typescript/native-preview": "catalog:",
+    "typescript": "catalog:",
+    "vite-plus": "catalog:"
+  },
+  "peerDependencies": {
+    "@mengine/storage": "workspace:*",
+    "@mengine/utils": "workspace:*",
+    "lodash-es": "catalog:",
+    "loro-crdt": "catalog:"
+  }
+}