Merge pull request #2052 from ably/PUB-1667/map-set-objects

[PUB-1667] Add support for encoding/decoding JSON objects for LiveMap values

Author: VeskeR

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/common/lib/types/basemessage.ts

@@ -95,13 +95,7 @@ export async function encryptData(
  * Implements RSL4 and RSL5.
  */
 export async function encode<T extends BaseMessage>(msg: T, options: unknown): Promise<T> {
-  // RSL4a, supported types
-  const isNativeDataType =
-    typeof msg.data == 'string' ||
-    Platform.BufferUtils.isBuffer(msg.data) ||
-    msg.data === null ||
-    msg.data === undefined;
-  const { data, encoding } = encodeData(msg.data, msg.encoding, isNativeDataType);
+  const { data, encoding } = encodeData(msg.data, msg.encoding);
 
   msg.data = data;
   msg.encoding = encoding;
@@ -116,9 +110,12 @@ export async function encode<T extends BaseMessage>(msg: T, options: unknown): P
 export function encodeData(
   data: any,
   encoding: string | null | undefined,
-  isNativeDataType: boolean,
 ): { data: any; encoding: string | null | undefined } {
-  if (isNativeDataType) {
+  // RSL4a, supported types
+  const nativeDataType =
+    typeof data == 'string' || Platform.BufferUtils.isBuffer(data) || data === null || data === undefined;
+
+  if (nativeDataType) {
     // nothing to do with the native data types at this point
     return {
       data,

src/plugins/objects/livemap.ts

@@ -13,27 +13,18 @@ import {
   ObjectsMapEntry,
   ObjectsMapOp,
   ObjectsMapSemantics,
+  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;
@@ -118,16 +109,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;
     }
 
@@ -193,11 +175,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
     }
@@ -258,16 +240,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;
       }
 
@@ -714,14 +687,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,
@@ -739,13 +705,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) {
@@ -870,13 +830,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;
         }
       }
 
@@ -913,19 +867,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