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,6 +1,7 @@
 import deepEqual from 'deep-equal';
 
 import type BaseClient from 'common/lib/client/baseclient';
+import type * as API from '../../../ably';
 import { LiveObject, LiveObjectData, LiveObjectUpdate, LiveObjectUpdateNoop } from './liveobject';
 import { LiveObjects } from './liveobjects';
 import {
@@ -14,7 +15,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. */
@@ -47,7 +47,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,
@@ -63,7 +63,7 @@ export class LiveMap<T extends LiveMapType> extends LiveObject<LiveMapData, Live
    *
    * @internal
    */
-  static zeroValue<T extends LiveMapType>(
+  static zeroValue<T extends API.LiveMapType>(
     liveobjects: LiveObjects,
     objectId?: string,
     regionalTimeserial?: Timeserial,

src/plugins/liveobjects/liveobjects.ts

@@ -9,7 +9,6 @@ import { LiveObjectsPool, ROOT_OBJECT_ID } from './liveobjectspool';
 import { StateMessage } from './statemessage';
 import { LiveCounterDataEntry, SyncLiveObjectsDataPool } from './syncliveobjectsdatapool';
 import { DefaultTimeserial, Timeserial } from './timeserial';
-import { DefaultRoot, LiveMapType } from './typings';
 
 enum LiveObjectsEvents {
   SyncCompleted = 'SyncCompleted',
@@ -48,7 +47,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);

src/plugins/liveobjects/liveobjectspool.ts

@@ -1,13 +1,13 @@
 import type BaseClient from 'common/lib/client/baseclient';
 import type RealtimeChannel from 'common/lib/client/realtimechannel';
+import type * as API from '../../../ably';
 import { LiveCounter } from './livecounter';
 import { LiveMap } from './livemap';
 import { LiveObject } from './liveobject';
 import { BufferedStateMessage, LiveObjects } from './liveobjects';
 import { ObjectId } from './objectid';
 import { MapSemantics, StateMessage, StateOperation, StateOperationAction } from './statemessage';
 import { DefaultTimeserial, Timeserial } from './timeserial';
-import { LiveMapType } from './typings';
 
 export const ROOT_OBJECT_ID = 'root';
 
@@ -194,7 +194,7 @@ export class LiveObjectsPool {
   }
 
   private _handleMapCreate(stateOperation: StateOperation, opRegionalTimeserial: Timeserial): void {
-    let map: LiveMap<LiveMapType>;
+    let map: LiveMap<API.LiveMapType>;
     if (this._client.Utils.isNil(stateOperation.map)) {
       // if a map object is missing for the MAP_CREATE op, the initial value is implicitly a zero-value map.
       map = LiveMap.zeroValue(this._liveObjects, stateOperation.objectId, opRegionalTimeserial);