Require plain json object as metadata

Author: w1am

docs/api/appending-events.md

@@ -206,19 +206,19 @@ This feature is only available in KurrentDB 25.1 and later.
 You can append events to multiple streams in a single atomic operation. Either all streams are updated, or the entire operation fails.
 
 ::: warning
-Currently, metadata must be valid JSON. Binary metadata will not be supported in
-this version. This limitation ensures compatibility with KurrentDB's metadata
-handling and will be removed in the next major release.
+Metadata must be a valid JSON object, using string keys and string values only.
+Binary metadata is not supported in this version to maintain compatibility with
+KurrentDB's metadata handling. This restriction will be lifted in the next major
+release.
 :::
 
 ```ts
 import { jsonEvent } from "@kurrent/kurrentdb-client";
 import { v4 as uuid } from "uuid";
 
 const metadata = {
-  timestamp: new Date().toISOString(),
   source: "OrderProcessingSystem",
-  version: 1.0
+  version: "1.0"
 };
 
 const requests = [

packages/db-client/src/streams/appendToStream/multiStreamAppend.ts

@@ -19,16 +19,22 @@ export const multiStreamAppend = async function (
   this: Client,
   requests: AppendStreamRequest[]
 ): Promise<MultiAppendResult> {
-  if (
-    requests.some((request) =>
-      request.events.some(
-        (event) => event.metadata && event.metadata.constructor === Uint8Array
-      )
-    )
-  )
-    throw new Error(
-      "multiStreamAppend requires all event metadata to be in JSON format."
-    );
+  for (const request of requests) {
+    for (const event of request.events) {
+      const { metadata } = event;
+      if (metadata == null) continue;
+      if (
+        metadata.constructor === Uint8Array ||
+        typeof metadata !== "object" ||
+        Array.isArray(metadata) ||
+        Object.values(metadata).some((value) => typeof value !== "string")
+      ) {
+        throw new Error(
+          "multiStreamAppend requires metadata to be a plain object with string keys and string values."
+        );
+      }
+    }
+  }
 
   return this.execute(
     grpc.StreamsServiceClient,
@@ -95,7 +101,7 @@ export const multiStreamAppend = async function (
 
             if (event.metadata) {
               const metadataMap = mapToValueMap(
-                event.metadata as Record<string, unknown>
+                event.metadata as Record<string, string>
               );
               for (const [key, value] of metadataMap) {
                 record.getPropertiesMap().set(key, value);

packages/db-client/src/utils/mapToValue.ts

@@ -1,48 +1,13 @@
-import { NullValue, Value } from "google-protobuf/google/protobuf/struct_pb";
+import { Value } from "google-protobuf/google/protobuf/struct_pb";
 
-export const mapToValue = (source: unknown): Value => {
+export const mapToValue = (source: string): Value => {
   const value = new Value();
-
-  if (source === null || source === undefined) {
-    value.setNullValue(NullValue.NULL_VALUE);
-    return value;
-  }
-
-  switch (typeof source) {
-    case "string":
-      value.setStringValue(source);
-      break;
-
-    case "boolean":
-      value.setBoolValue(source);
-      break;
-
-    case "number":
-      value.setNumberValue(source);
-      break;
-
-    case "object":
-      if (source instanceof Date) {
-        value.setStringValue(source.toISOString());
-      } else if (source instanceof Uint8Array) {
-        value.setStringValue(Buffer.from(source).toString("base64"));
-      } else if (Buffer.isBuffer(source)) {
-        value.setStringValue(source.toString("base64"));
-      } else {
-        value.setStringValue(JSON.stringify(source));
-      }
-      break;
-
-    default:
-      value.setStringValue(String(source));
-      break;
-  }
-
+  value.setStringValue(source);
   return value;
 };
 
 export const mapToValueMap = (
-  obj: Record<string, unknown>
+  obj: Record<string, string>
 ): Map<string, Value> => {
   const map = new Map<string, Value>();
 

packages/test/src/streams/multiAppendStream.test.ts

@@ -17,6 +17,8 @@ import {
   STREAM_EXISTS,
   WrongExpectedVersionError,
   StreamTombstonedError,
+  jsonEvent,
+  binaryEvent,
 } from "@kurrent/kurrentdb-client";
 
 import { v4 } from "uuid";
@@ -35,36 +37,64 @@ describe("multiAppend", () => {
     await node.down();
   });
 
-  test("json events", async () => {
-    const STREAM_NAME = v4().toString();
+  optionalDescribe(supported)("Supported (>=25.1)", () => {
+    test("invalid metadata (binary metadata)", async () => {
+      const STREAM_NAME = v4().toString();
 
-    const requests: AppendStreamRequest[] = [];
+      const requests: AppendStreamRequest[] = [];
 
-    requests.push({
-      streamName: STREAM_NAME,
-      events: binaryTestEvents(),
-      expectedState: ANY,
-    });
+      requests.push({
+        streamName: STREAM_NAME,
+        events: [
+          jsonEvent({
+            type: "test",
+            data: { key: "value" },
+            metadata: Buffer.from("binary metadata"),
+          }),
+        ],
+        expectedState: ANY,
+      });
 
-    try {
-      await client.multiStreamAppend(requests);
-    } catch (error) {
-      expect(error).toBeInstanceOf(Error);
-      expect(error.message).toBe(
-        "multiStreamAppend requires server version 25.1 or higher."
+      await expect(client.multiStreamAppend(requests)).rejects.toThrow(
+        "multiStreamAppend requires metadata to be a plain object with string keys and string values."
       );
-    }
-  });
+    });
+
+    test("invalid metadata (non plain object)", async () => {
+      const STREAM_NAME = v4().toString();
+
+      const requests: AppendStreamRequest[] = [];
+
+      requests.push({
+        streamName: STREAM_NAME,
+        events: [
+          jsonEvent({
+            type: "test",
+            data: {
+              stringKey: "stringValue",
+              numberKey: 42,
+            },
+          }),
+        ],
+        expectedState: ANY,
+      });
+
+      try {
+        await client.multiStreamAppend(requests);
+      } catch (error) {
+        expect(error).toBeInstanceOf(Error);
+        await expect(client.multiStreamAppend(requests)).rejects.toThrow(
+          "multiStreamAppend requires metadata to be a plain object with string keys and string values."
+        );
+      }
+    });
 
-  optionalDescribe(supported)("Supported (>=25.1)", () => {
     test("json events", async () => {
       const STREAM_NAME_1 = v4().toString();
       const STREAM_NAME_2 = v4().toString();
       const expectedMetadata = {
-        timestamp: new Date().toISOString(),
-        int: 1,
-        float: 1.1,
-        string: "test",
+        name: "multiAppendTest",
+        empty: ""
       };
 
       const requests: AppendStreamRequest[] = [];
@@ -99,14 +129,13 @@ describe("multiAppend", () => {
           expect.objectContaining({
             "$schema.format": "Json",
             "$schema.name": "test",
-            ...expectedMetadata,
+            name: "multiAppendTest",
+            empty: ""
           })
         );
       }
     });
-  });
 
-  optionalDescribe(supported)("Supported (>=25.1)", () => {
     test("stream deleted", async () => {
       const STREAM_NAME = v4().toString();
 
@@ -126,9 +155,7 @@ describe("multiAppend", () => {
         expect(error).toBeInstanceOf(StreamTombstonedError);
       }
     });
-  });
 
-  optionalDescribe(supported)("Supported (>=25.1)", () => {
     test("stream revision conflict", async () => {
       const STREAM_NAME = v4().toString();