feat!: adopt flock 4 version encoding (#39)

Author: zxch3n

packages/loro-adaptors/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## Unreleased
+
+### ⚠ BREAKING CHANGES
+
+* Flock adaptors now encode version vectors using `@loro-dev/flock`'s binary `encodeVersionVector`; version payloads are no longer JSON.
+
 ## [0.5.0](https://github.com/loro-dev/protocol/compare/loro-adaptors-v0.4.2...loro-adaptors-v0.5.0) (2025-12-07)
 
 

packages/loro-adaptors/package.json

@@ -15,7 +15,7 @@
     "loro-protocol": "workspace:*"
   },
   "peerDependencies": {
-    "@loro-dev/flock": "^3.1.0",
+    "@loro-dev/flock": "^4.0.0",
     "loro-crdt": "^1.9.0",
     "yjs": "*"
   },

packages/loro-adaptors/src/flock-adaptor.ts

@@ -1,4 +1,4 @@
-import { Flock } from "@loro-dev/flock";
+import { Flock, decodeVersionVector, encodeVersionVector } from "@loro-dev/flock";
 import {
   CrdtType,
   JoinResponseOk,
@@ -11,42 +11,6 @@ type FlockExportBundle = Awaited<ReturnType<Flock["exportJson"]>>;
 const encoder = new TextEncoder();
 const decoder = new TextDecoder();
 
-function serializeVersion(version: FlockVersion | undefined): Uint8Array {
-  return encoder.encode(JSON.stringify(version ?? {}));
-}
-
-function deserializeVersion(bytes: Uint8Array): FlockVersion {
-  if (!bytes.length) return {};
-  try {
-    const parsed = JSON.parse(decoder.decode(bytes));
-    if (!parsed || typeof parsed !== "object") return {};
-    const next: FlockVersion = {};
-    for (const [key, value] of Object.entries(
-      parsed as Record<string, unknown>
-    )) {
-      if (!value || typeof value !== "object") continue;
-      const entry = value as {
-        logicalCounter?: unknown;
-        physicalTime?: unknown;
-      };
-      const logicalCounter =
-        typeof entry.logicalCounter === "number" &&
-          Number.isFinite(entry.logicalCounter)
-          ? Math.trunc(entry.logicalCounter)
-          : 0;
-      const physicalTime =
-        typeof entry.physicalTime === "number" &&
-          Number.isFinite(entry.physicalTime)
-          ? entry.physicalTime
-          : 0;
-      next[key] = { logicalCounter, physicalTime };
-    }
-    return next;
-  } catch {
-    return {};
-  }
-}
-
 function compareVersions(
   a: FlockVersion,
   b: FlockVersion
@@ -145,8 +109,12 @@ export class FlockAdaptor implements CrdtDocAdaptor {
   }
 
   cmpVersion(versionBytes: Uint8Array): 0 | 1 | -1 | undefined {
-    const remote = deserializeVersion(versionBytes);
-    return compareVersions(this.flock.version(), remote);
+    try {
+      const remote = decodeVersionVector(versionBytes);
+      return compareVersions(this.flock.version(), remote);
+    } catch {
+      return undefined;
+    }
   }
 
   setCtx(ctx: CrdtAdaptorContext): void {
@@ -167,7 +135,7 @@ export class FlockAdaptor implements CrdtDocAdaptor {
   }
 
   getVersion(): Uint8Array {
-    return serializeVersion(this.flock.version());
+    return encodeVersionVector(this.flock.version());
   }
 
   getAlternativeVersion(): Uint8Array | undefined {
@@ -185,7 +153,7 @@ export class FlockAdaptor implements CrdtDocAdaptor {
   async handleJoinOk(res: JoinResponseOk): Promise<void> {
     if (this.destroyed) return;
     try {
-      const serverVersion = deserializeVersion(res.version);
+      const serverVersion = decodeVersionVector(res.version);
       this.initServerVersion = serverVersion;
       const comparison = compareVersions(this.flock.version(), serverVersion);
       if (comparison != null && comparison >= 0) {

packages/loro-adaptors/src/server/server-flock-adaptor.ts

@@ -1,4 +1,4 @@
-import { Flock } from "@loro-dev/flock";
+import { Flock, decodeVersionVector, encodeVersionVector } from "@loro-dev/flock";
 import type {
   ExportBundle as FlockExportBundle,
   VersionVector as FlockVersion,
@@ -31,45 +31,6 @@ function deserializeBundle(bytes: Uint8Array): FlockExportBundle {
   return { version: 0, entries: {} };
 }
 
-function serializeVersion(version: FlockVersion | undefined): Uint8Array {
-  return encoder.encode(JSON.stringify(version ?? {}));
-}
-
-function deserializeVersion(bytes: Uint8Array): FlockVersion {
-  if (!bytes.length) {
-    return {};
-  }
-  try {
-    const parsed = JSON.parse(decoder.decode(bytes));
-    if (!parsed || typeof parsed !== "object") {
-      return {};
-    }
-    const next: FlockVersion = {};
-    for (const [peer, value] of Object.entries(
-      parsed as Record<string, unknown>,
-    )) {
-      if (!value || typeof value !== "object") {
-        continue;
-      }
-      const entry = value as { logicalCounter?: unknown; physicalTime?: unknown };
-      const logicalCounter =
-        typeof entry.logicalCounter === "number" &&
-          Number.isFinite(entry.logicalCounter)
-          ? Math.trunc(entry.logicalCounter)
-          : 0;
-      const physicalTime =
-        typeof entry.physicalTime === "number" &&
-          Number.isFinite(entry.physicalTime)
-          ? entry.physicalTime
-          : 0;
-      next[peer] = { logicalCounter, physicalTime };
-    }
-    return next;
-  } catch {
-    return {};
-  }
-}
-
 function importSnapshot(flock: Flock, data: Uint8Array): void {
   if (!data.length) return;
   const bundle = deserializeBundle(data);
@@ -112,11 +73,11 @@ export class FlockServerAdaptor implements CrdtServerAdaptor {
     const flock = new Flock();
     importSnapshot(flock, documentData);
 
-    const serverVersion = serializeVersion(flock.version());
+    const serverVersion = encodeVersionVector(flock.version());
     let updates: Uint8Array[] | undefined;
 
     if (clientVersion.length > 0) {
-      const clientVV = deserializeVersion(clientVersion);
+      const clientVV = decodeVersionVector(clientVersion);
       const delta = exportBundle(flock, clientVV);
       updates = [serializeBundle(delta)];
     } else if (documentData.length > 0) {
@@ -167,7 +128,7 @@ export class FlockServerAdaptor implements CrdtServerAdaptor {
   getVersion(documentData: Uint8Array): Uint8Array {
     const flock = new Flock();
     importSnapshot(flock, documentData);
-    return serializeVersion(flock.version());
+    return encodeVersionVector(flock.version());
   }
 
   merge(documents: Uint8Array[]): Uint8Array {

packages/loro-websocket/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## Unreleased
+
+### ⚠ BREAKING CHANGES
+
+* Flock client/server adaptors now emit binary-encoded version vectors using `@loro-dev/flock`'s `encodeVersionVector`; prior JSON encoding is no longer supported.
+
 ## [0.5.0](https://github.com/loro-dev/protocol/compare/loro-websocket-v0.4.3...loro-websocket-v0.5.0) (2025-12-07)
 
 

packages/loro-websocket/package.json

@@ -72,7 +72,7 @@
     "ws": "^8.18.3"
   },
   "devDependencies": {
-    "@loro-dev/flock": "^3.1.0",
+    "@loro-dev/flock": "^4.0.0",
     "get-port": "^7.1.0",
     "tsdown": "^0.14.1",
     "tsx": "^4.20.5",