@evolu/common 6.0.1-preview.1 → 6.0.1-preview.10

package/src/Evolu/Evolu.ts

@@ -1,5 +1,5 @@
 import { isNonEmptyArray, isNonEmptyReadonlyArray } from "../Array.js";
-import { assertNonEmptyArray } from "../Assert.js";
+import { assert, assertNonEmptyArray } from "../Assert.js";
 import { createCallbacks } from "../Callbacks.js";
 import { ConsoleDep } from "../Console.js";
 import { SymmetricCryptoDecryptError } from "../Crypto.js";
@@ -44,9 +44,9 @@ import {
   SubscribedQueries,
 } from "./Query.js";
 import {
-  assertValidEvoluSchema,
   CreateQuery,
   EvoluSchema,
+  evoluSchemaToDbSchema,
   insertable,
   Mutation,
   MutationKind,
@@ -54,7 +54,7 @@ import {
   MutationOptions,
   updateable,
   upsertable,
-  validEvoluSchemaToDbSchema,
+  ValidateSchema,
   ValidMutationSize,
   ValidMutationSizeError,
 } from "./Schema.js";
@@ -88,7 +88,7 @@ export interface Evolu<S extends EvoluSchema = EvoluSchema> {
    * All this function does is compile the Kysely query and serialize it into a
    * unique string. Both operations are fast and cheap.
    *
-   * For mutations, use {@link Evolu.insert} and {@link Evolu.update}.
+   * For mutations, use {@link Evolu#insert} and {@link Evolu#update}.
    *
    * ### Example
    *
@@ -111,7 +111,7 @@ export interface Evolu<S extends EvoluSchema = EvoluSchema> {
    * A returned promise always resolves successfully because there is no reason
    * why loading should fail. All data are local, and the query is typed. A
    * serious unexpected Evolu error shall be handled with
-   * {@link Evolu.subscribeError}.
+   * {@link Evolu#subscribeError}.
    *
    * Loading is batched, and returned promises are cached, so there is no need
    * for an additional cache. Evolu's internal cache is invalidated on
@@ -144,7 +144,7 @@ export interface Evolu<S extends EvoluSchema = EvoluSchema> {
    * If you are curious why Evolu does not do that for all queries by default,
    * the answer is simple: performance. Tracking changes is costly and
    * meaningful only for visible (hence subscribed) queries anyway. To subscribe
-   * to a query, use {@link Evolu.subscribeQuery}.
+   * to a query, use {@link Evolu#subscribeQuery}.
    *
    * ### Example
    *
@@ -300,7 +300,7 @@ export interface Evolu<S extends EvoluSchema = EvoluSchema> {
 
   /**
    * Restore {@link AppOwner} with all their synced data. It uses
-   * {@link Evolu.resetAppOwner}, so be careful.
+   * {@link Evolu#resetAppOwner}, so be careful.
    */
   readonly restoreAppOwner: (
     mnemonic: Mnemonic,
@@ -431,9 +431,7 @@ let tabId: Id | null = null;
 export const createEvolu =
   (deps: EvoluDeps) =>
   <S extends EvoluSchema>(
-    // TODO: Validate missing Id, unsupported types, used default types via TS types
-    // with type errors messages as we had it in the old Evolu.
-    schema: S,
+    schema: ValidateSchema<S> extends never ? S : ValidateSchema<S>,
     partialConfig: Partial<EvoluConfigWithInitialData<S>> = {},
   ): Evolu<S> => {
     const config = { ...defaultConfig, ...partialConfig };
@@ -441,11 +439,14 @@ export const createEvolu =
     let evolu = evoluInstances.get(config.name);
 
     if (evolu == null) {
-      evolu = createEvoluInstance(deps)(schema, config as IntentionalNever);
+      evolu = createEvoluInstance(deps)(
+        schema as EvoluSchema,
+        config as IntentionalNever,
+      );
       evoluInstances.set(config.name, evolu);
     } else {
       // Hot reloading. Note that indexes are intentionally omitted.
-      evolu.ensureSchema(schema);
+      evolu.ensureSchema(schema as EvoluSchema);
     }
 
     return evolu as IntentionalNever;
@@ -554,10 +555,7 @@ const createEvoluInstance =
       }
     });
 
-    const dbSchema = validEvoluSchemaToDbSchema(
-      assertValidEvoluSchema(schema),
-      indexes,
-    );
+    const dbSchema = evoluSchemaToDbSchema(schema, indexes);
 
     const mutationTypesCache = new Map<
       MutationKind,
@@ -592,21 +590,17 @@ const createEvoluInstance =
     if (initialData)
       initialData({
         insert: (table, props) => {
-          const Type = getMutationType(table, "insert");
           const id = createId(deps);
+          const values = getMutationType(table, "insert").fromUnknown(props);
 
-          const result = Type.fromUnknown(props);
-
-          if (result.ok) {
-            initialDataDbChanges.push({
-              id,
-              table,
-              values: result.value,
-            } as unknown as DbChange);
+          if (values.ok) {
+            const dbChange = { table, id, values: values.value };
+            assertValidDbChange(dbChange);
+            initialDataDbChanges.push(dbChange);
             return ok({ id });
           }
 
-          return result;
+          return values;
         },
       });
 
@@ -654,14 +648,14 @@ const createEvoluInstance =
           } else {
             // Remove `id` from values.
             const { id: _id, ...values } = result.value;
-            // EvoluSchema Types ensure valid types.
-            const change = { table, id, values } as unknown as DbChange;
-            mutateMicrotaskQueue.push([change, options?.onComplete]);
+            const dbChange = { table, id, values };
+            assertValidDbChange(dbChange);
+            mutateMicrotaskQueue.push([dbChange, options?.onComplete]);
           }
 
           if (mutateMicrotaskQueue.length === 1)
             queueMicrotask(() => {
-              const changes = [];
+              const changes: Array<DbChange> = [];
               const onCompletes = [];
 
               for (const [change, onComplete] of mutateMicrotaskQueue) {
@@ -807,6 +801,7 @@ const createEvoluInstance =
         const onCompleteId = callbacks.register(() => {
           resolve();
         });
+
         dbWorker.postMessage({
           type: "reset",
           onCompleteId,
@@ -822,11 +817,8 @@ const createEvoluInstance =
 
       ensureSchema: (schema) => {
         mutationTypesCache.clear();
-        const validSchema = assertValidEvoluSchema(schema);
-        dbWorker.postMessage({
-          type: "ensureDbSchema",
-          dbSchema: validEvoluSchemaToDbSchema(validSchema),
-        });
+        const dbSchema = evoluSchemaToDbSchema(schema);
+        dbWorker.postMessage({ type: "ensureDbSchema", dbSchema });
       },
 
       exportDatabase: () => {
@@ -945,3 +937,14 @@ const createLoadingPromises = (
 
   return loadingPromises;
 };
+
+const assertValidDbChange: (dbChange: {
+  table: string;
+  id: Id;
+  values: unknown;
+}) => asserts dbChange is DbChange = (dbChange) => {
+  assert(
+    DbChange.is(dbChange),
+    `Failed to create DbChange for table "${dbChange.table}". If you see this message, you either disabled EvoluSchema validation or Evolu has a bug - please report it.`,
+  );
+};

package/src/Evolu/Protocol.ts

@@ -15,21 +15,39 @@
  *
  * ### Message Structure
  *
- * | Field                          | Notes                      |
- * | :----------------------------- | :------------------------- |
- * | **Header**                     |                            |
- * | - {@link protocolVersion}      |                            |
- * | - {@link OwnerId}              |                            |
- * | - {@link ProtocolErrorCode}    | In non-initiator response. |
- * | **Messages**                   |                            |
- * | - {@link NonNegativeInt}       | A number of messages.      |
- * | - {@link EncryptedCrdtMessage} |                            |
- * | - {@link WriteKey}             | In initiator request.      |
- * | **Ranges**                     |                            |
- * | - {@link NonNegativeInt}       | Number of ranges.          |
- * | - {@link Range}                |                            |
+ * | Field                          | Notes                     |
+ * | :----------------------------- | :------------------------ |
+ * | **Header**                     |                           |
+ * | - {@link protocolVersion}      |                           |
+ * | - {@link OwnerId}              | {@link Owner}             |
+ * | **Initiator**                  |                           |
+ * | - {@link WriteKeyMode}         |                           |
+ * | - {@link WriteKey}             | If WriteKeyMode >= 1      |
+ * | - {@link WriteKey}             | If WriteKeyMode = 2 (new) |
+ * | **Non-initiator**              |                           |
+ * | - {@link ProtocolErrorCode}    |                           |
+ * | **Messages**                   |                           |
+ * | - {@link NonNegativeInt}       | A number of messages.     |
+ * | - {@link EncryptedCrdtMessage} |                           |
+ * | **Ranges**                     |                           |
+ * | - {@link NonNegativeInt}       | Number of ranges.         |
+ * | - {@link Range}                |                           |
  *
- * Every protocol message belongs to an {@link Owner}.
+ * ### WriteKey Validation
+ *
+ * The initiator sends WriteKeyMode and optionally one or two WriteKeys. One key
+ * for write operations and two for key rotation (current and new). Note that
+ * it's ok to not send any key if initiator is going to be synced with readonly
+ * owner. The non-initiator validates them immediately after parsing the
+ * initiator header, before processing any messages or ranges.
+ *
+ * ### WriteKey Rotation
+ *
+ * When initiator's {@link WriteKeyMode} is `Rotation`, two WriteKeys are
+ * present:
+ *
+ * 1. Current WriteKey (for validation)
+ * 2. New WriteKey (to be stored)
  *
  * ### Synchronization
  *
@@ -127,10 +145,8 @@ import { isNonEmptyReadonlyArray, NonEmptyReadonlyArray } from "../Array.js";
 import { assert } from "../Assert.js";
 import {
   Buffer,
-  BufferError,
   bytesToHex,
   bytesToUtf8,
-  concatBytes,
   createBuffer,
   hexToBytes,
   utf8ToBytes,
@@ -144,7 +160,7 @@ import {
 } from "../Crypto.js";
 import { eqArrayNumber } from "../Eq.js";
 import { computeBalancedBuckets } from "../Number.js";
-import { objectToEntries, ReadonlyRecord } from "../Object.js";
+import { objectToEntries } from "../Object.js";
 import { err, ok, Result } from "../Result.js";
 import { SqliteValue } from "../Sqlite.js";
 import {
@@ -157,11 +173,12 @@ import {
   NanoId,
   NonNegativeInt,
   Number,
+  object,
   PositiveInt,
+  record,
 } from "../Type.js";
 import { Brand, Predicate } from "../Types.js";
 import {
-  // eslint-disable-next-line @typescript-eslint/no-unused-vars
   Owner,
   OwnerId,
   OwnerWithWriteAccess,
@@ -203,6 +220,14 @@ export const ProtocolErrorCode = {
 type ProtocolErrorCode =
   (typeof ProtocolErrorCode)[keyof typeof ProtocolErrorCode];
 
+export const WriteKeyMode = {
+  None: 0,
+  Single: 1,
+  Rotation: 2,
+} as const;
+
+type WriteKeyMode = (typeof WriteKeyMode)[keyof typeof WriteKeyMode];
+
 /**
  * Evolu Protocol Storage
  *
@@ -247,17 +272,15 @@ export interface Storage {
     callback: (timestamp: BinaryTimestamp, index: NonNegativeInt) => boolean,
   ) => void;
 
-  /**
-   * Authorizes the initiator's {@link WriteKey} for the given
-   * {@link BinaryOwnerId}.
-   *
-   * For a client that does not expect foreign writes, return `false`.
-   */
+  /** Validates the {@link WriteKey} for the given {@link Owner}. */
   readonly validateWriteKey: (
     ownerId: BinaryOwnerId,
     writeKey: WriteKey,
   ) => boolean;
 
+  /** Sets the {@link WriteKey} for the given {@link Owner}. */
+  readonly setWriteKey: (ownerId: BinaryOwnerId, writeKey: WriteKey) => boolean;
+
   /** Write encrypted {@link CrdtMessage}s to storage. */
   readonly writeMessages: (
     ownerId: BinaryOwnerId,
@@ -269,6 +292,9 @@ export interface Storage {
     ownerId: BinaryOwnerId,
     timestamp: BinaryTimestamp,
   ) => EncryptedDbChange | null;
+
+  /** Delete all data for the given {@link Owner}. */
+  readonly deleteOwner: (ownerId: BinaryOwnerId) => boolean;
 }
 
 export interface StorageDep {
@@ -293,15 +319,23 @@ export interface CrdtMessage {
   readonly change: DbChange;
 }
 
+/**
+ * Base64Url string with maximum length of 256 characters. Encoding strings as
+ * Base64UrlString saves up to 25% in size compared to regular strings.
+ */
+export const Base64Url256 = maxLength(256)(Base64Url);
+export type Base64Url256 = typeof Base64Url256.Type;
+
 /**
  * A DbChange is a change to a table row. Together with a unique
  * {@link Timestamp}, it forms a {@link CrdtMessage}.
  */
-export interface DbChange {
-  readonly table: Base64Url256;
-  readonly id: Id;
-  readonly values: ReadonlyRecord<Base64Url256, SqliteValue>;
-}
+export const DbChange = object({
+  table: Base64Url256,
+  id: Id,
+  values: record(Base64Url256, SqliteValue),
+});
+export type DbChange = typeof DbChange.Type;
 
 export const RangeType = {
   Fingerprint: 1,
@@ -425,6 +459,7 @@ export const createProtocolMessageFromCrdtMessages =
     maxSize?: PositiveInt,
   ): ProtocolMessage => {
     const buffer = createProtocolMessageBuffer(owner.id, {
+      type: "initiator",
       totalMaxSize: maxSize ?? maxProtocolMessageSize,
       writeKey: owner.writeKey,
     });
@@ -480,7 +515,7 @@ export const createProtocolMessageFromCrdtMessages =
 export const createProtocolMessageForSync =
   (deps: StorageDep) =>
   (ownerId: OwnerId): ProtocolMessage | null => {
-    const buffer = createProtocolMessageBuffer(ownerId);
+    const buffer = createProtocolMessageBuffer(ownerId, { type: "initiator" });
     const binaryOwnerId = ownerIdToBinaryOwnerId(ownerId);
 
     const size = deps.storage.getSize(binaryOwnerId);
@@ -498,6 +533,19 @@ export const createProtocolMessageForSync =
     return buffer.unwrap();
   };
 
+/** Creates a ProtocolMessage for {@link WriteKey} rotation. */
+export const createProtocolMessageForWriteKeyRotation = (
+  ownerId: OwnerId,
+  currentWriteKey: WriteKey,
+  newWriteKey: WriteKey,
+): ProtocolMessage => {
+  const buffer = createProtocolMessageBuffer(ownerId, {
+    type: "initiator",
+    writeKey: [currentWriteKey, newWriteKey],
+  });
+  return buffer.unwrap();
+};
+
 /**
  * Mutable builder for constructing {@link ProtocolMessage} respecting size
  * limits.
@@ -525,16 +573,22 @@ export interface ProtocolMessageBuffer {
 export const createProtocolMessageBuffer = (
   ownerId: OwnerId,
   options: {
-    readonly errorCode?: ProtocolErrorCode;
-    readonly writeKey?: WriteKey;
     readonly totalMaxSize?: PositiveInt | undefined;
     readonly rangesMaxSize?: PositiveInt | undefined;
     readonly version?: NonNegativeInt;
-  } = {},
+  } & (
+    | {
+        readonly type: "initiator";
+        /** Single key or [current, new] for rotation. */
+        readonly writeKey?: WriteKey | readonly [WriteKey, WriteKey];
+      }
+    | {
+        readonly type: "non-initiator";
+        readonly errorCode: ProtocolErrorCode;
+      }
+  ),
 ): ProtocolMessageBuffer => {
   const {
-    errorCode,
-    writeKey,
     totalMaxSize = maxProtocolMessageSize,
     rangesMaxSize = maxProtocolMessageRangesSize,
     version = protocolVersion,
@@ -555,7 +609,21 @@ export const createProtocolMessageBuffer = (
 
   encodeNonNegativeInt(buffers.header, version);
   buffers.header.extend(ownerIdToBinaryOwnerId(ownerId));
-  if (errorCode != null) buffers.header.extend([errorCode]);
+
+  if (options.type === "initiator") {
+    if (!options.writeKey) {
+      buffers.header.extend([WriteKeyMode.None]);
+    } else if (!Array.isArray(options.writeKey)) {
+      buffers.header.extend([WriteKeyMode.Single]);
+      buffers.header.extend(options.writeKey as WriteKey);
+    } else {
+      buffers.header.extend([WriteKeyMode.Rotation]);
+      buffers.header.extend(options.writeKey[0] as WriteKey); // current
+      buffers.header.extend(options.writeKey[1] as WriteKey); // new
+    }
+  } else {
+    buffers.header.extend([options.errorCode]);
+  }
 
   let isLastRangeInfinite = false;
 
@@ -567,10 +635,7 @@ export const createProtocolMessageBuffer = (
   const getHeaderAndMessagesSize = () =>
     buffers.header.getLength() +
     buffers.messages.timestamps.getLength() +
-    buffers.messages.dbChanges.getLength() +
-    (buffers.messages.timestamps.getCount() > 0 && writeKey
-      ? writeKeyLength
-      : 0);
+    buffers.messages.dbChanges.getLength();
 
   const getRangesSize = () =>
     buffers.ranges.timestamps.getCount() > 0
@@ -685,8 +750,6 @@ export const createProtocolMessageBuffer = (
 
       buffers.messages.timestamps.append(buffers.header);
       buffers.header.extend(buffers.messages.dbChanges.unwrap());
-      if (buffers.messages.timestamps.getCount() > 0 && writeKey)
-        buffers.header.extend(writeKey);
 
       if (buffers.ranges.timestamps.getCount() > 0) {
         buffers.ranges.timestamps.append(buffers.header);
@@ -836,8 +899,6 @@ export const applyProtocolMessageAsClient =
           });
         }
 
-        const binaryOwnerId = ownerIdToBinaryOwnerId(ownerId);
-
         const errorCode = input.shift() as ProtocolErrorCode;
         if (errorCode !== ProtocolErrorCode.NoError) {
           switch (errorCode) {
@@ -864,6 +925,7 @@ export const applyProtocolMessageAsClient =
         }
 
         const messages = decodeMessages(input);
+        const binaryOwnerId = ownerIdToBinaryOwnerId(ownerId);
 
         if (
           isNonEmptyReadonlyArray(messages) &&
@@ -877,6 +939,7 @@ export const applyProtocolMessageAsClient =
         if (writeKey == null) return ok(null);
 
         const output = createProtocolMessageBuffer(ownerId, {
+          type: "initiator",
           writeKey,
           totalMaxSize,
           rangesMaxSize,
@@ -911,8 +974,7 @@ export const applyProtocolMessageAsRelay =
     version = protocolVersion,
   ): Result<ProtocolMessage | null, ProtocolInvalidDataError> =>
     tryDecodeProtocolData(inputMessage, (input) => {
-      const requestedVersion = decodeNonNegativeInt(input);
-      const ownerId = decodeOwnerId(input);
+      const [requestedVersion, ownerId] = decodeVersionAndOwner(input);
       const binaryOwnerId = ownerIdToBinaryOwnerId(ownerId);
 
       if (requestedVersion !== version) {
@@ -925,44 +987,89 @@ export const applyProtocolMessageAsRelay =
 
       subscribe?.(ownerId);
 
-      const messages = decodeMessages(input);
+      const writeKeyMode = input.shift() as WriteKeyMode;
+      let writeKey: WriteKey | undefined;
+      let newWriteKey: WriteKey | undefined;
+
+      if (writeKeyMode !== WriteKeyMode.None) {
+        writeKey = input.shiftN(writeKeyLength) as WriteKey;
+        switch (writeKeyMode) {
+          case WriteKeyMode.Single:
+            break;
+          case WriteKeyMode.Rotation:
+            newWriteKey = input.shiftN(writeKeyLength) as WriteKey;
+            break;
+          default:
+            throw new ProtocolDecodeError(
+              `Invalid WriteKeyMode: ${writeKeyMode}`,
+            );
+        }
+      }
 
-      if (isNonEmptyReadonlyArray(messages)) {
-        const messagesEnd = inputMessage.length - input.getLength();
-        const writeKey = input.shiftN(writeKeyLength) as WriteKey;
+      if (writeKey) {
+        const isValid = deps.storage.validateWriteKey(binaryOwnerId, writeKey);
+        if (!isValid) {
+          return ok(
+            createProtocolMessageBuffer(ownerId, {
+              type: "non-initiator",
+              errorCode: ProtocolErrorCode.WriteKeyError,
+            }).unwrap(),
+          );
+        }
 
-        const writeKeyIsValid = deps.storage.validateWriteKey(
-          binaryOwnerId,
-          writeKey,
-        );
+        if (newWriteKey) {
+          const rotationSuccess = deps.storage.setWriteKey(
+            binaryOwnerId,
+            newWriteKey,
+          );
+          if (!rotationSuccess) {
+            return ok(
+              createProtocolMessageBuffer(ownerId, {
+                type: "non-initiator",
+                errorCode: ProtocolErrorCode.WriteError,
+              }).unwrap(),
+            );
+          }
+        }
+      }
+
+      const messages = decodeMessages(input);
 
-        if (!writeKeyIsValid)
+      if (isNonEmptyReadonlyArray(messages)) {
+        if (!writeKey)
           return ok(
             createProtocolMessageBuffer(ownerId, {
+              type: "non-initiator",
               errorCode: ProtocolErrorCode.WriteKeyError,
             }).unwrap(),
           );
 
-        if (broadcast) {
-          // Instead of encoding a new protocol message, we reuse the inputMessage.
-          const broadcastMessage = concatBytes(
-            inputMessage.slice(0, 17),
-            new Uint8Array([ProtocolErrorCode.NoError]),
-            inputMessage.slice(17, messagesEnd),
-          ) as ProtocolMessage;
-
-          broadcast(ownerId, broadcastMessage);
+        // Only broadcast if there's no ranges.
+        if (broadcast && input.getLength() === 0) {
+          const broadcastBuffer = createProtocolMessageBuffer(ownerId, {
+            type: "non-initiator",
+            errorCode: ProtocolErrorCode.NoError,
+            totalMaxSize,
+            rangesMaxSize,
+            version,
+          });
+          for (const message of messages) {
+            broadcastBuffer.addMessage(message);
+          }
+          broadcast(ownerId, broadcastBuffer.unwrap());
         }
 
         if (!deps.storage.writeMessages(binaryOwnerId, messages))
           return ok(
             createProtocolMessageBuffer(ownerId, {
+              type: "non-initiator",
               errorCode: ProtocolErrorCode.WriteError,
             }).unwrap(),
           );
       }
 
       const output = createProtocolMessageBuffer(ownerId, {
+        type: "non-initiator",
         errorCode: ProtocolErrorCode.NoError,
         totalMaxSize,
         rangesMaxSize,
@@ -983,18 +1090,19 @@ const tryDecodeProtocolData = <T, E>(
   try {
     return callback(createBuffer(data));
   } catch (error: unknown) {
-    if (error instanceof ProtocolDecodeError || error instanceof BufferError)
-      return err<ProtocolInvalidDataError>({
-        type: "ProtocolInvalidDataError",
-        data,
-        error,
-      });
-
-    throw error;
+    return err<ProtocolInvalidDataError>({
+      type: "ProtocolInvalidDataError",
+      data,
+      error,
+    });
   }
 };
 
 const decodeVersionAndOwner = (input: Buffer): [NonNegativeInt, OwnerId] => {
+  // This structure must never change across protocol versions. The version
+  // and owner ID must always be the first two fields in every protocol message
+  // to enable version negotiation and owner identification before any other
+  // processing occurs.
   const version = decodeNonNegativeInt(input);
   const ownerId = decodeOwnerId(input);
   return [version, ownerId];
@@ -1052,6 +1160,7 @@ const sync =
         return ok(null);
       }
       const message = createProtocolMessageBuffer(binaryOwnerId, {
+        type: "non-initiator",
         errorCode: ProtocolErrorCode.SyncError,
       });
       return ok(message.unwrap());
@@ -1434,13 +1543,6 @@ export const ownerIdToBinaryOwnerId = (ownerId: OwnerId): BinaryOwnerId =>
 export const binaryOwnerIdToOwnerId = (binaryOwnerId: BinaryOwnerId): OwnerId =>
   decodeOwnerId(createBuffer(binaryOwnerId));
 
-/**
- * Base64Url string with maximum length of 256 characters. Encoding strings as
- * Base64UrlString saves up to 25% in size compared to regular strings.
- */
-export const Base64Url256 = maxLength(256)(Base64Url);
-export type Base64Url256 = typeof Base64Url256.Type;
-
 /**
  * Union type for all variants of Base64Url strings with limited length. All
  * these types use Base64Url alphabet and are < 256 characters.
@@ -1895,3 +1997,27 @@ export const decodeSqliteValue = (buffer: Buffer): SqliteValue => {
       throw new ProtocolDecodeError("invalid ProtocolValueType");
   }
 };
+
+/**
+ * Decodes a ProtocolMessage into a readable JSON object for debugging.
+ *
+ * Note: This is a stub for future implementation. It should use:
+ *
+ * - DecodeVersionAndOwner
+ * - DecodeError or decodeWriteKeys (depending on context)
+ * - DecodeMessages
+ * - DecodeRanges
+ *
+ * If you want to help, please contribute to this function.
+ */
+export const decodeProtocolMessageToJson = (
+  _protocolMessage: ProtocolMessage,
+  _isInitiator: boolean,
+): unknown => {
+  // TODO: Implement using
+  // - decodeVersionAndOwner
+  // -- decodeError or decodeWriteKeys (should be refactored out),
+  // -- decodeMessages, and decodeRanges.
+  // This is a stub for PRs and community contributions.
+  throw new Error("decodeProtocolMessageToJson is not implemented yet.");
+};