Add support for encoding/decoding JSON objects for LiveMap values

This enables to set and get JSON objects and arrays via LiveMap.set and
LiveMap.get methods.

Resolves PUB-1667

Author: VeskeR

README.md

@@ -688,13 +688,15 @@ for (const value of root.values()) {
 await root.set('foo', 'Alice');
 await root.set('bar', 1);
 await root.set('baz', true);
-await root.set('qux', new Uint8Array([21, 31]));
+await root.set('qux', { hello: 'world' });
+await root.set('quux', [ 42 ]);
+await root.set('corge', new Uint8Array([21, 31]));
 // as well as other objects
 const counter = await objects.createCounter();
-await root.set('quux', counter);
+await root.set('grault', counter);
 
 // and you can remove keys with .remove
-await root.remove('name');
+await root.remove('foo');
 ```
 
 `LiveCounter` - A counter that can be incremented or decremented and is synchronized across clients in realtime

ably.d.ts

@@ -2440,7 +2440,7 @@ export declare interface BatchContextLiveMap<T extends LiveMapType> {
    * Mirrors the {@link LiveMap.get} method and returns the value associated with a key in the map.
    *
    * @param key - The key to retrieve the value for.
-   * @returns A {@link LiveObject}, a primitive type (string, number, boolean, or binary data) or `undefined` if the key doesn't exist in a map or the associated {@link LiveObject} has been deleted. Always `undefined` if this map object is deleted.
+   * @returns A {@link LiveObject}, a primitive type (string, number, boolean, JSON-serializable object or array, or binary data) or `undefined` if the key doesn't exist in a map or the associated {@link LiveObject} has been deleted. Always `undefined` if this map object is deleted.
    * @experimental
    */
   get<TKey extends keyof T & string>(key: TKey): T[TKey] | undefined;
@@ -2515,7 +2515,7 @@ export declare interface BatchContextLiveCounter {
  * Conflicts in a LiveMap are automatically resolved with last-write-wins (LWW) semantics,
  * meaning that if two clients update the same key in the map, the update with the most recent timestamp wins.
  *
- * Keys must be strings. Values can be another {@link LiveObject}, or a primitive type, such as a string, number, boolean, or binary data (see {@link PrimitiveObjectValue}).
+ * Keys must be strings. Values can be another {@link LiveObject}, or a primitive type, such as a string, number, boolean, JSON-serializable object or array, or binary data (see {@link PrimitiveObjectValue}).
  */
 export declare interface LiveMap<T extends LiveMapType> extends LiveObject<LiveMapUpdate<T>> {
   /**
@@ -2524,7 +2524,7 @@ export declare interface LiveMap<T extends LiveMapType> extends LiveObject<LiveM
    * Always returns undefined if this map object is deleted.
    *
    * @param key - The key to retrieve the value for.
-   * @returns A {@link LiveObject}, a primitive type (string, number, boolean, or binary data) or `undefined` if the key doesn't exist in a map or the associated {@link LiveObject} has been deleted. Always `undefined` if this map object is deleted.
+   * @returns A {@link LiveObject}, a primitive type (string, number, boolean, JSON-serializable object or array, or binary data) or `undefined` if the key doesn't exist in a map or the associated {@link LiveObject} has been deleted. Always `undefined` if this map object is deleted.
    * @experimental
    */
   get<TKey extends keyof T & string>(key: TKey): T[TKey] | undefined;
@@ -2602,7 +2602,27 @@ export declare interface LiveMapUpdate<T extends LiveMapType> extends LiveObject
  *
  * For binary data, the resulting type depends on the platform (`Buffer` in Node.js, `ArrayBuffer` elsewhere).
  */
-export type PrimitiveObjectValue = string | number | boolean | Buffer | ArrayBuffer;
+export type PrimitiveObjectValue = string | number | boolean | Buffer | ArrayBuffer | JsonArray | JsonObject;
+
+/**
+ * Represents a JSON-encodable value.
+ */
+export type Json = JsonScalar | JsonArray | JsonObject;
+
+/**
+ * Represents a JSON-encodable scalar value.
+ */
+export type JsonScalar = null | boolean | number | string;
+
+/**
+ * Represents a JSON-encodable array.
+ */
+export type JsonArray = Json[];
+
+/**
+ * Represents a JSON-encodable object.
+ */
+export type JsonObject = { [prop: string]: Json | undefined };
 
 /**
  * The `LiveCounter` class represents a counter that can be incremented or decremented and is synchronized across clients in realtime.

src/plugins/objects/livemap.ts

@@ -15,27 +15,18 @@ import {
   ObjectsMapOp,
   ObjectsMapSemantics,
   ObjectState,
+  PrimitiveObjectValue,
 } from './objectmessage';
 import { Objects } from './objects';
 
-export type PrimitiveObjectValue = string | number | boolean | Bufferlike;
-
 export interface ObjectIdObjectData {
   /** A reference to another object, used to support composable object structures. */
   objectId: string;
 }
 
 export interface ValueObjectData {
-  /** Can be set by the client to indicate that value in `string` or `bytes` field have an encoding. */
-  encoding?: string;
-  /** A primitive boolean leaf value in the object graph. Only one value field can be set. */
-  boolean?: boolean;
-  /** A primitive binary leaf value in the object graph. Only one value field can be set. */
-  bytes?: Bufferlike;
-  /** A primitive number leaf value in the object graph. Only one value field can be set. */
-  number?: number;
-  /** A primitive string leaf value in the object graph. Only one value field can be set. */
-  string?: string;
+  /** A decoded leaf value from {@link WireObjectData}. */
+  value: string | number | boolean | Bufferlike | API.JsonArray | API.JsonObject;
 }
 
 export type LiveMapObjectData = ObjectIdObjectData | ValueObjectData;
@@ -126,16 +117,7 @@ export class LiveMap<T extends API.LiveMapType> extends LiveObject<LiveMapData,
       const typedObjectData: ObjectIdObjectData = { objectId: value.getObjectId() };
       objectData = typedObjectData;
     } else {
-      const typedObjectData: ValueObjectData = {};
-      if (typeof value === 'string') {
-        typedObjectData.string = value;
-      } else if (typeof value === 'number') {
-        typedObjectData.number = value;
-      } else if (typeof value === 'boolean') {
-        typedObjectData.boolean = value;
-      } else {
-        typedObjectData.bytes = value as Bufferlike;
-      }
+      const typedObjectData: ValueObjectData = { value: value as PrimitiveObjectValue };
       objectData = typedObjectData;
     }
 
@@ -201,11 +183,11 @@ export class LiveMap<T extends API.LiveMapType> extends LiveObject<LiveMapData,
     }
 
     if (
-      typeof value !== 'string' &&
-      typeof value !== 'number' &&
-      typeof value !== 'boolean' &&
-      !client.Platform.BufferUtils.isBuffer(value) &&
-      !(value instanceof LiveObject)
+      value === null ||
+      (typeof value !== 'string' &&
+        typeof value !== 'number' &&
+        typeof value !== 'boolean' &&
+        typeof value !== 'object')
     ) {
       throw new client.ErrorInfo('Map value data type is unsupported', 40013, 400); // OD4a
     }
@@ -266,16 +248,7 @@ export class LiveMap<T extends API.LiveMapType> extends LiveObject<LiveMapData,
         const typedObjectData: ObjectIdObjectData = { objectId: value.getObjectId() };
         objectData = typedObjectData;
       } else {
-        const typedObjectData: ValueObjectData = {};
-        if (typeof value === 'string') {
-          typedObjectData.string = value;
-        } else if (typeof value === 'number') {
-          typedObjectData.number = value;
-        } else if (typeof value === 'boolean') {
-          typedObjectData.boolean = value;
-        } else {
-          typedObjectData.bytes = value as Bufferlike;
-        }
+        const typedObjectData: ValueObjectData = { value: value as PrimitiveObjectValue };
         objectData = typedObjectData;
       }
 
@@ -717,14 +690,7 @@ export class LiveMap<T extends API.LiveMapType> extends LiveObject<LiveMapData,
       return { noop: true };
     }
 
-    if (
-      Utils.isNil(op.data) ||
-      (Utils.isNil(op.data.objectId) &&
-        Utils.isNil(op.data.boolean) &&
-        Utils.isNil(op.data.bytes) &&
-        Utils.isNil(op.data.number) &&
-        Utils.isNil(op.data.string))
-    ) {
+    if (Utils.isNil(op.data) || (Utils.isNil(op.data.objectId) && Utils.isNil(op.data.value))) {
       throw new ErrorInfo(
         `Invalid object data for MAP_SET op on objectId=${this.getObjectId()} on key=${op.key}`,
         92000,
@@ -742,13 +708,7 @@ export class LiveMap<T extends API.LiveMapType> extends LiveObject<LiveMapData,
       // so instead we create a zero-value object for that object id if it not exists.
       this._objects.getPool().createZeroValueObjectIfNotExists(op.data.objectId); // RTLM7c1
     } else {
-      liveData = {
-        encoding: op.data.encoding,
-        boolean: op.data.boolean,
-        bytes: op.data.bytes,
-        number: op.data.number,
-        string: op.data.string,
-      } as ValueObjectData;
+      liveData = { value: op.data.value } as ValueObjectData;
     }
 
     if (existingEntry) {
@@ -859,13 +819,7 @@ export class LiveMap<T extends API.LiveMapType> extends LiveObject<LiveMapData,
         if (!this._client.Utils.isNil(entry.data.objectId)) {
           liveData = { objectId: entry.data.objectId } as ObjectIdObjectData;
         } else {
-          liveData = {
-            encoding: entry.data.encoding,
-            boolean: entry.data.boolean,
-            bytes: entry.data.bytes,
-            number: entry.data.number,
-            string: entry.data.string,
-          } as ValueObjectData;
+          liveData = { value: entry.data.value } as ValueObjectData;
         }
       }
 
@@ -887,19 +841,10 @@ export class LiveMap<T extends API.LiveMapType> extends LiveObject<LiveMapData,
    * Returns value as is if object data stores a primitive type, or a reference to another LiveObject from the pool if it stores an objectId.
    */
   private _getResolvedValueFromObjectData(data: LiveMapObjectData): PrimitiveObjectValue | LiveObject | undefined {
-    // if object data stores one of the primitive values, just return it as is.
-    const asValueObject = data as ValueObjectData;
-    if (asValueObject.boolean !== undefined) {
-      return asValueObject.boolean; // RTLM5d2b
-    }
-    if (asValueObject.bytes !== undefined) {
-      return asValueObject.bytes; // RTLM5d2c
-    }
-    if (asValueObject.number !== undefined) {
-      return asValueObject.number; // RTLM5d2d
-    }
-    if (asValueObject.string !== undefined) {
-      return asValueObject.string; // RTLM5d2e
+    // if object data stores primitive value, just return it as is.
+    const primitiveValue = (data as ValueObjectData).value;
+    if (primitiveValue != null) {
+      return primitiveValue; // RTLM5d2b, RTLM5d2c, RTLM5d2d, RTLM5d2e
     }
 
     // RTLM5d2f - otherwise, it has an objectId reference, and we should get the actual object from the pool