Expose protocol v6 typed fields on public ObjectOperation and ObjectData

The public ObjectOperation interface is updated to use the protocol v6
field names (mapCreate, mapSet, mapRemove, counterCreate, counterInc).
The previous fields (mapOp, counterOp, map, counter) are preserved as
deprecated aliases.

The public ObjectData interface previously exposed a combined `value`
field, which was an incorrect internal representation leaking through
the public API (introduced in 54f8ae2).
The LODR-042 [1] DR proposed that subscription events should be
equivalent to the REST API publish endpoint syntax. With protocol v6
aligning the realtime protocol and REST API in LODR-51 [2], ObjectData
now exposes the same typed fields available on the wire: boolean, bytes,
number, string, json - with decoded values (bytes as Buffer/ArrayBuffer,
json as parsed objects). The combined `value` field is preserved as a
deprecated alias.

Both new and deprecated fields are populated for backwards
compatibility; deprecated fields will be removed in a future major
version.

[1] https://ably.atlassian.net/wiki/spaces/LOB/pages/4235722804/LODR-042+LiveObjects+Realtime+Client+API+Improvements#Subscriptions
[2] https://ably.atlassian.net/wiki/x/AQAPEgE

Author: VeskeR

liveobjects.d.ts

@@ -1577,18 +1577,61 @@ export interface ObjectOperation {
   action: ObjectOperationAction;
   /** The ID of the object the operation was applied to. */
   objectId: string;
-  /** The payload for the operation if it is a mutation operation on a map object. */
+
+  /**
+   * The payload for the operation if the action is {@link ObjectOperationActions.MAP_CREATE}.
+   * Defines the initial value of the map object.
+   */
+  mapCreate?: MapCreate;
+  /**
+   * The payload for the operation if the action is {@link ObjectOperationActions.MAP_SET}.
+   * Describes the key and value to set on the map object.
+   */
+  mapSet?: MapSet;
+  /**
+   * The payload for the operation if the action is {@link ObjectOperationActions.MAP_REMOVE}.
+   * Describes the key to remove from the map object.
+   */
+  mapRemove?: MapRemove;
+  /**
+   * The payload for the operation if the action is {@link ObjectOperationActions.COUNTER_CREATE}.
+   * Defines the initial value of the counter object.
+   */
+  counterCreate?: CounterCreate;
+  /**
+   * The payload for the operation if the action is {@link ObjectOperationActions.COUNTER_INC}.
+   * Describes the value to add to the counter.
+   */
+  counterInc?: CounterInc;
+  /**
+   * The payload for the operation if the action is {@link ObjectOperationActions.OBJECT_DELETE}.
+   */
+  objectDelete?: ObjectDelete;
+
+  /**
+   * The payload for the operation if it is a mutation operation on a map object.
+   *
+   * @deprecated This property is deprecated and will be removed in a future major version. Use {@link mapSet} and {@link mapRemove} instead.
+   */
   mapOp?: ObjectsMapOp;
-  /** The payload for the operation if it is a mutation operation on a counter object. */
+  /**
+   * The payload for the operation if it is a mutation operation on a counter object.
+   *
+   * @deprecated This property is deprecated and will be removed in a future major version. Use {@link counterInc} instead.
+   */
   counterOp?: ObjectsCounterOp;
   /**
    * The payload for the operation if the action is {@link ObjectOperationActions.MAP_CREATE}.
    * Defines the initial value of the map object.
+   *
+   * @deprecated This property is deprecated and will be removed in a future major version. Use {@link mapCreate} instead.
    */
   map?: ObjectsMap;
   /**
    * The payload for the operation if the action is {@link ObjectOperationActions.COUNTER_CREATE}.
    * Defines the initial value of the counter object.
+   *
+   * @deprecated This property is deprecated and will be removed in a future major version. Use {@link counterCreate} instead.
    */
   counter?: ObjectsCounter;
 }
@@ -1643,13 +1686,77 @@ export interface ObjectsCounter {
   count?: number;
 }
 
+/**
+ * Describes the payload for a MAP_CREATE operation.
+ */
+export interface MapCreate {
+  /** The conflict-resolution semantics used by the map object, one of the {@link ObjectsMapSemantics} enum values. */
+  semantics: ObjectsMapSemantics;
+  /** The map entries, indexed by key. */
+  entries: Record<string, ObjectsMapEntry>;
+}
+
+/**
+ * Describes the payload for a MAP_SET operation on a map object.
+ */
+export interface MapSet {
+  /** The key to set. */
+  key: string;
+  /** The value to set. */
+  value: ObjectData;
+}
+
+/**
+ * Describes the payload for a MAP_REMOVE operation on a map object.
+ */
+export interface MapRemove {
+  /** The key to remove. */
+  key: string;
+}
+
+/**
+ * Describes the payload for a COUNTER_CREATE operation.
+ */
+export interface CounterCreate {
+  /** The initial counter value. */
+  count: number;
+}
+
+/**
+ * Describes the payload for a COUNTER_INC operation on a counter object.
+ */
+export interface CounterInc {
+  /** The value to be added to the counter. */
+  number: number;
+}
+
+/**
+ * Describes the payload for an OBJECT_DELETE operation.
+ */
+export interface ObjectDelete {}
+
 /**
  * Represents a value in an object on a channel.
  */
 export interface ObjectData {
   /** A reference to another object. */
   objectId?: string;
-  /** A decoded primitive value. */
+  /** A boolean leaf value in the object. */
+  boolean?: boolean;
+  /** A decoded binary leaf value in the object. */
+  bytes?: Buffer | ArrayBuffer;
+  /** A number leaf value in the object. */
+  number?: number;
+  /** A string leaf value in the object. */
+  string?: string;
+  /** A decoded JSON leaf value in the object. */
+  json?: JsonObject | JsonArray;
+
+  /**
+   * A decoded primitive value.
+   *
+   * @deprecated This property is deprecated and will be removed in a future major version. Use one of the typed {@link boolean}, {@link bytes}, {@link number}, {@link string} or {@link json} fields instead.
+   */
   value?: Primitive;
 }
 

src/plugins/liveobjects/objectmessage.ts

@@ -443,6 +443,8 @@ function toUserFacingObjectData(data: ObjectData): ObjectsApi.ObjectData {
   }
 
   return {
+    ...data,
+    // deprecated field for backwards compatibility
     value: getObjectDataPrimitive(data),
   };
 }
@@ -455,40 +457,56 @@ function toUserFacingMapEntry(entry: ObjectsMapEntry<ObjectData>): ObjectsApi.Ob
 }
 
 function toUserFacingObjectOperation(operation: ObjectOperation<ObjectData>): ObjectsApi.ObjectOperation {
-  // Convert internal field names to user-facing API field names
-  let map: ObjectsApi.ObjectsMap | undefined;
-  if (operation.mapCreate) {
-    map = {
-      ...operation.mapCreate,
-      semantics: mapSemantics[operation.mapCreate.semantics] || 'unknown',
+  const { mapCreate: internalMapCreate, mapSet: internalMapSet, mapRemove, counterCreate, counterInc } = operation;
+
+  let mapCreate: ObjectsApi.MapCreate | undefined;
+  if (internalMapCreate) {
+    mapCreate = {
+      ...internalMapCreate,
+      semantics: mapSemantics[internalMapCreate.semantics] ?? 'unknown',
       entries: Object.fromEntries(
-        Object.entries(operation.mapCreate.entries).map(([key, entry]) => [key, toUserFacingMapEntry(entry)]),
+        Object.entries(internalMapCreate.entries).map(([key, entry]) => [key, toUserFacingMapEntry(entry)]),
       ),
     };
   }
 
+  let mapSet: ObjectsApi.MapSet | undefined;
+  if (internalMapSet) {
+    mapSet = {
+      ...internalMapSet,
+      value: toUserFacingObjectData(internalMapSet.value),
+    };
+  }
+
+  // ObjectOperation deprecated fields for backwards compatibility
   let mapOp: ObjectsApi.ObjectsMapOp | undefined;
-  if (operation.mapSet) {
+  if (mapSet) {
     mapOp = {
-      key: operation.mapSet.key,
-      data: toUserFacingObjectData(operation.mapSet.value),
+      key: mapSet.key,
+      data: mapSet.value,
     };
-  } else if (operation.mapRemove) {
-    mapOp = { key: operation.mapRemove.key };
+  } else if (mapRemove) {
+    mapOp = { key: mapRemove.key };
   }
 
   let counterOp: ObjectsApi.ObjectsCounterOp | undefined;
-  if (operation.counterInc) {
-    counterOp = { amount: operation.counterInc.number };
+  if (counterInc) {
+    counterOp = { amount: counterInc.number };
   }
 
   return {
+    ...operation,
     action: operationActions[operation.action] || 'unknown',
-    objectId: operation.objectId,
+    mapCreate,
+    mapSet,
+    mapRemove,
+    counterCreate,
+    counterInc,
+    // deprecated fields
     mapOp,
     counterOp,
-    map,
-    counter: operation.counterCreate,
+    map: mapCreate,
+    counter: counterCreate,
   };
 }
 

test/common/modules/private_api_recorder.js

@@ -22,6 +22,7 @@ define(['test/support/output_directory_paths'], function (outputDirectoryPaths)
     'call.ObjectMessage.encode',
     'call.ObjectMessage.fromValues',
     'call.ObjectMessage.getMessageSize',
+    'call.ObjectMessage.toUserFacingMessage',
     'call.Platform.Config.push.storage.clear',
     'call.Platform.nextTick',
     'call.PresenceMessage.fromValues',