Implement .compact() method for PathObject and Instance types for LiveObjects

Resolves PUB-2064

Author: VeskeR

ably.d.ts

@@ -2457,6 +2457,28 @@ export type LiveObject = LiveMap | LiveCounter;
  */
 export type Value = LiveObject | Primitive;
 
+/**
+ * CompactedValue transforms LiveObject types into plain JavaScript equivalents.
+ * LiveMap becomes an object, LiveCounter becomes a number, primitives remain unchanged.
+ */
+export type CompactedValue<T extends Value> =
+  // LiveMap types
+  [T] extends [LiveMap<infer U>]
+    ? { [K in keyof U]: CompactedValue<U[K]> }
+    : [T] extends [LiveMap<infer U> | undefined]
+      ? { [K in keyof U]: CompactedValue<U[K]> } | undefined
+      : // LiveCounter types
+        [T] extends [LiveCounter]
+        ? number
+        : [T] extends [LiveCounter | undefined]
+          ? number | undefined
+          : // Primitive types
+            [T] extends [Primitive]
+            ? T
+            : [T] extends [Primitive | undefined]
+              ? T
+              : any;
+
 /**
  * PathObjectBase defines the set of common methods on a PathObject
  * that are present regardless of the underlying type specified by the type parameter T.
@@ -2469,13 +2491,6 @@ interface PathObjectBase<_T extends Value> {
    */
   path(): string;
 
-  /**
-   * Get a JavaScript object representation of the object at this path.
-   *
-   * @experimental
-   */
-  compact(): any;
-
   /**
    * Registers a listener that is called each time the object or a primitive value at this path is updated.
    *
@@ -2579,6 +2594,13 @@ export interface LiveMapPathObject<T extends Record<string, Value> = Record<stri
    * @experimental
    */
   instance(): LiveMapInstance<T> | undefined;
+
+  /**
+   * Get a JavaScript object representation of the map at this path.
+   *
+   * @experimental
+   */
+  compact(): CompactedValue<LiveMap<T>>;
 }
 
 /**
@@ -2601,6 +2623,13 @@ export interface LiveCounterPathObject extends PathObjectBase<LiveCounter>, Live
    * @experimental
    */
   instance(): LiveCounterInstance | undefined;
+
+  /**
+   * Get a number representation of the counter at this path.
+   *
+   * @experimental
+   */
+  compact(): CompactedValue<LiveCounter>;
 }
 
 /**
@@ -2614,6 +2643,13 @@ export interface PrimitivePathObject<T extends Primitive = Primitive> extends Pa
    * @experimental
    */
   value(): T | undefined;
+
+  /**
+   * Get a JavaScript object representation of the primitive value at this path.
+   *
+   * @experimental
+   */
+  compact(): CompactedValue<T>;
 }
 
 /**
@@ -2692,6 +2728,13 @@ export interface AnyPathObject<T extends Value = Value>
    * @experimental
    */
   instance<T extends Value = Value>(): Instance<T> | undefined;
+
+  /**
+   * Get a JavaScript object representation of the object at this path.
+   *
+   * @experimental
+   */
+  compact<T extends Value = Value>(): CompactedValue<T> | undefined;
 }
 
 /**
@@ -2701,8 +2744,8 @@ export interface AnyPathObject<T extends Value = Value>
  *
  * @experimental
  */
-export type PathObject<T extends Value = Value> = [T] extends [LiveMap<infer T>]
-  ? LiveMapPathObject<T>
+export type PathObject<T extends Value = Value> = [T] extends [LiveMap<infer U>]
+  ? LiveMapPathObject<U>
   : [T] extends [LiveCounter]
     ? LiveCounterPathObject
     : [T] extends [Primitive]
@@ -2862,13 +2905,6 @@ interface InstanceBase<T extends Value> {
    */
   id(): string;
 
-  /**
-   * Get a JavaScript object representation of the instance.
-   *
-   * @experimental
-   */
-  compact(): any;
-
   /**
    * Registers a listener that is called each time this instance is updated.
    *
@@ -2943,6 +2979,13 @@ export interface LiveMapInstance<T extends Record<string, Value> = Record<string
    * @experimental
    */
   get<K extends keyof T & string>(key: K): Instance<T[K]> | undefined;
+
+  /**
+   * Get a JavaScript object representation of the map instance.
+   *
+   * @experimental
+   */
+  compact(): CompactedValue<LiveMap<T>>;
 }
 
 /**
@@ -2955,6 +2998,13 @@ export interface LiveCounterInstance extends InstanceBase<LiveCounter>, LiveCoun
    * @experimental
    */
   value(): number;
+
+  /**
+   * Get a number representation of the counter instance.
+   *
+   * @experimental
+   */
+  compact(): CompactedValue<LiveCounter>;
 }
 
 /**
@@ -2967,6 +3017,13 @@ export interface PrimitiveInstance<T extends Primitive = Primitive> {
    * @experimental
    */
   value(): T;
+
+  /**
+   * Get a JavaScript object representation of the primitive value.
+   *
+   * @experimental
+   */
+  compact(): CompactedValue<T>;
 }
 
 /**
@@ -3033,6 +3090,13 @@ export interface AnyInstance<T extends Value> extends InstanceBase<T>, AnyInstan
    * @experimental
    */
   value<T extends number | Primitive = number | Primitive>(): T | undefined;
+
+  /**
+   * Get a JavaScript object representation of the object instance.
+   *
+   * @experimental
+   */
+  compact<T extends Value = Value>(): CompactedValue<T> | undefined;
 }
 
 /**
@@ -3042,8 +3106,8 @@ export interface AnyInstance<T extends Value> extends InstanceBase<T>, AnyInstan
  *
  * @experimental
  */
-export type Instance<T extends Value> = [T] extends [LiveMap<infer T>]
-  ? LiveMapInstance<T>
+export type Instance<T extends Value> = [T] extends [LiveMap<infer U>]
+  ? LiveMapInstance<U>
   : [T] extends [LiveCounter]
     ? LiveCounterInstance
     : [T] extends [Primitive]

src/plugins/objects/instance.ts

@@ -1,5 +1,13 @@
 import type BaseClient from 'common/lib/client/baseclient';
-import type { AnyInstance, EventCallback, Instance, InstanceSubscriptionEvent, Primitive, Value } from '../../../ably';
+import type {
+  AnyInstance,
+  CompactedValue,
+  EventCallback,
+  Instance,
+  InstanceSubscriptionEvent,
+  Primitive,
+  Value,
+} from '../../../ably';
 import { LiveCounter } from './livecounter';
 import { LiveMap } from './livemap';
 import { LiveObject, LiveObjectUpdate, SubscribeResponse } from './liveobject';
@@ -30,8 +38,12 @@ export class DefaultInstance<T extends Value> implements AnyInstance<T> {
     return this._value.getObjectId();
   }
 
-  compact(): any {
-    throw new Error('Not implemented');
+  compact<U extends Value = Value>(): CompactedValue<U> | undefined {
+    if (this._value instanceof LiveMap) {
+      return this._value.compact() as CompactedValue<U>;
+    }
+
+    return this.value() as CompactedValue<U>;
   }
 
   get<U extends Value = Value>(key: string): Instance<U> | undefined {

src/plugins/objects/livemap.ts

@@ -2,6 +2,7 @@ import { dequal } from 'dequal';
 
 import type { Bufferlike } from 'common/platform';
 import type * as API from '../../../ably';
+import { LiveCounter } from './livecounter';
 import { LiveCounterValueType } from './livecountervaluetype';
 import { LiveMapValueType } from './livemapvaluetype';
 import { LiveObject, LiveObjectData, LiveObjectUpdate, LiveObjectUpdateNoop } from './liveobject';
@@ -640,6 +641,34 @@ export class LiveMap<T extends API.LiveMapType> extends LiveObject<LiveMapData,
     return super.clearData();
   }
 
+  /**
+   * Returns a plain JavaScript object representation of this LiveMap.
+   * LiveMap values are recursively compacted using their own compact methods.
+   *
+   * @internal
+   */
+  compact(): { [K in keyof T]: any } {
+    const result: Record<keyof T, any> = {} as Record<keyof T, any>;
+
+    // Use public entries() method to ensure we only include publicly exposed properties
+    for (const [key, value] of this.entries()) {
+      if (value instanceof LiveMap) {
+        result[key] = value.compact();
+        continue;
+      }
+
+      if (value instanceof LiveCounter) {
+        result[key] = value.value();
+        continue;
+      }
+
+      // Other values return as is
+      result[key] = value;
+    }
+
+    return result;
+  }
+
   /** @spec RTLM4 */
   protected _getZeroValueData(): LiveMapData {
     return { data: new Map<string, LiveMapEntry>() };

src/plugins/objects/pathobject.ts

@@ -2,6 +2,7 @@ import type BaseClient from 'common/lib/client/baseclient';
 import type * as API from '../../../ably';
 import type {
   AnyPathObject,
+  CompactedValue,
   EventCallback,
   Instance,
   PathObject,
@@ -44,10 +45,25 @@ export class DefaultPathObject<T extends Value = Value> implements AnyPathObject
   }
 
   /**
-   * Returns a compact representation of the object at this path
+   * Returns a JavaScript object representation of the object at this path
    */
-  compact(): any {
-    throw new Error('Not implemented');
+  compact<U extends Value = Value>(): CompactedValue<U> | undefined {
+    try {
+      const resolved = this._resolvePath(this._path);
+
+      if (resolved instanceof LiveMap) {
+        return resolved.compact() as CompactedValue<U>;
+      }
+
+      return this.value() as CompactedValue<U>;
+    } catch (error) {
+      if (this._client.Utils.isErrorInfoOrPartialErrorInfo(error)) {
+        // ignore ErrorInfos indicating path resolution failure and return undefined
+        return undefined;
+      }
+      // otherwise rethrow unexpected errors
+      throw error;
+    }
   }
 
   /**