Move types required for user-provided LiveObjects typings to ably.d.ts

ably.d.ts

@@ -2029,13 +2029,32 @@ export declare interface PushChannel {
  * Enables the LiveObjects state to be subscribed to for a channel.
  */
 export declare interface LiveObjects {
-  getRoot(): Promise<LiveMap>;
+  getRoot<T extends LiveMapType = DefaultRoot>(): Promise<LiveMap<T>>;
 }
 
 // TODO: document public API for LiveObjects
 
-export declare interface LiveMap extends LiveObject<LiveMapUpdate> {
-  get(key: string): LiveObject | StateValue | undefined;
+declare global {
+  // a global interface which can be used by users to define their own types for LiveObjects.
+  export interface LiveObjectsTypes {
+    [key: string]: unknown;
+  }
+}
+
+// LiveMap type representation of how it looks to the user. A mapping of string keys to scalar values (StateValue) or other Live Objects.
+export type LiveMapType = { [key: string]: StateValue | LiveMap<LiveMapType> | LiveCounter | undefined };
+
+export type DefaultRoot =
+  // we need a way to know when no types were provided by the user.
+  // we expect a "root" property to be set on LiveObjectsTypes interface, e.g. it won't be "unknown" anymore
+  unknown extends LiveObjectsTypes['root']
+    ? LiveMapType // no types provided by the user, use the default map type for the root
+    : LiveObjectsTypes['root'] extends LiveMapType
+      ? LiveObjectsTypes['root'] // "root" was provided by the user, and it is of an expected type, we can use this interface for the root object in LiveObjects.
+      : `Provided type definition for the "root" object in LiveObjectsTypes is not of an expected LiveMapType type`;
+
+export declare interface LiveMap<T extends LiveMapType> extends LiveObject<LiveMapUpdate> {
+  get<TKey extends keyof T & string>(key: TKey): T[TKey];
   size(): number;
 }
 

src/plugins/liveobjects/livemap.ts

@@ -1,5 +1,6 @@
 import deepEqual from 'deep-equal';
 
+import type * as API from '../../../ably';
 import { LiveObject, LiveObjectData, LiveObjectUpdate, LiveObjectUpdateNoop } from './liveobject';
 import { LiveObjects } from './liveobjects';
 import {
@@ -13,7 +14,6 @@ import {
   StateValue,
 } from './statemessage';
 import { DefaultTimeserial, Timeserial } from './timeserial';
-import { LiveMapType } from './typings';
 
 export interface ObjectIdStateData {
   /** A reference to another state object, used to support composable state objects. */
@@ -46,7 +46,7 @@ export interface LiveMapUpdate extends LiveObjectUpdate {
   update: { [keyName: string]: 'updated' | 'removed' };
 }
 
-export class LiveMap<T extends LiveMapType> extends LiveObject<LiveMapData, LiveMapUpdate> {
+export class LiveMap<T extends API.LiveMapType> extends LiveObject<LiveMapData, LiveMapUpdate> {
   constructor(
     liveObjects: LiveObjects,
     private _semantics: MapSemantics,
@@ -60,7 +60,7 @@ export class LiveMap<T extends LiveMapType> extends LiveObject<LiveMapData, Live
    *
    * @internal
    */
-  static zeroValue<T extends LiveMapType>(liveobjects: LiveObjects, objectId: string): LiveMap<T> {
+  static zeroValue<T extends API.LiveMapType>(liveobjects: LiveObjects, objectId: string): LiveMap<T> {
     return new LiveMap(liveobjects, MapSemantics.LWW, objectId);
   }
 
@@ -70,7 +70,7 @@ export class LiveMap<T extends LiveMapType> extends LiveObject<LiveMapData, Live
    *
    * @internal
    */
-  static fromStateObject<T extends LiveMapType>(liveobjects: LiveObjects, stateObject: StateObject): LiveMap<T> {
+  static fromStateObject<T extends API.LiveMapType>(liveobjects: LiveObjects, stateObject: StateObject): LiveMap<T> {
     const obj = new LiveMap<T>(liveobjects, stateObject.map?.semantics!, stateObject.objectId);
     obj.overrideWithStateObject(stateObject);
     return obj;

src/plugins/liveobjects/liveobjects.ts

@@ -8,7 +8,6 @@ import { LiveObject, LiveObjectUpdate } from './liveobject';
 import { LiveObjectsPool, ROOT_OBJECT_ID } from './liveobjectspool';
 import { StateMessage } from './statemessage';
 import { SyncLiveObjectsDataPool } from './syncliveobjectsdatapool';
-import { DefaultRoot, LiveMapType } from './typings';
 
 enum LiveObjectsEvents {
   SyncCompleted = 'SyncCompleted',
@@ -42,7 +41,7 @@ export class LiveObjects {
    * A user can provide an explicit type for the getRoot method to explicitly set the LiveObjects type structure on this particular channel.
    * This is useful when working with LiveObjects on multiple channels with different underlying data.
    */
-  async getRoot<T extends LiveMapType = DefaultRoot>(): Promise<LiveMap<T>> {
+  async getRoot<T extends API.LiveMapType = API.DefaultRoot>(): Promise<LiveMap<T>> {
     // SYNC is currently in progress, wait for SYNC sequence to finish
     if (this._syncInProgress) {
       await this._eventEmitter.once(LiveObjectsEvents.SyncCompleted);