Update Objects docstrings to not use "root" terminology

Author: VeskeR

ably.d.ts

@@ -2288,32 +2288,32 @@ export type LiveObjectLifecycleEvent = LiveObjectLifecycleEvents.DELETED;
  */
 export declare interface RealtimeObject {
   /**
-   * Retrieves the root {@link LiveMap} object for Objects on a channel.
+   * Retrieves the {@link LiveMap} object - the entrypoint for Objects on a channel.
    *
    * A type parameter can be provided to describe the structure of the Objects on the channel. By default, it uses types from the globally defined `AblyObjectsTypes` interface.
    *
-   * You can specify custom types for Objects by defining a global `AblyObjectsTypes` interface with a `root` property that conforms to {@link LiveMapType}.
+   * You can specify custom types for Objects by defining a global `AblyObjectsTypes` interface with a `object` property that conforms to {@link LiveMapType}.
    *
    * Example:
    *
    * ```typescript
    * import { LiveCounter } from 'ably';
    *
-   * type MyRoot = {
+   * type MyObject = {
    *   myTypedKey: LiveCounter;
    * };
    *
    * declare global {
    *   export interface AblyObjectsTypes {
-   *     root: MyRoot;
+   *     object: MyObject;
    *   }
    * }
    * ```
    *
    * @returns A promise which, upon success, will be fulfilled with a {@link LiveMap} object. Upon failure, the promise will be rejected with an {@link ErrorInfo} object which explains the error.
    * @experimental
    */
-  get<T extends LiveMapType = DefaultRoot>(): Promise<LiveMap<T>>;
+  get<T extends LiveMapType = AblyDefaultObject>(): Promise<LiveMap<T>>;
 
   /**
    * Creates a new {@link LiveMap} object instance with the provided entries.
@@ -2392,20 +2392,20 @@ declare global {
 export type LiveMapType = { [key: string]: PrimitiveObjectValue | LiveMap<LiveMapType> | LiveCounter | undefined };
 
 /**
- * The default type for the `root` object for Objects on a channel, based on the globally defined {@link AblyObjectsTypes} interface.
+ * The default type for the entrypoint {@link LiveMap} object on a channel, based on the globally defined {@link AblyObjectsTypes} interface.
  *
- * - If no custom types are provided in `AblyObjectsTypes`, defaults to an untyped root map representation using the {@link LiveMapType} interface.
- * - If a `root` type exists in `AblyObjectsTypes` and conforms to the {@link LiveMapType} interface, it is used as the type for the `root` object.
- * - If the provided `root` type does not match {@link LiveMapType}, a type error message is returned.
+ * - If no custom types are provided in `AblyObjectsTypes`, defaults to an untyped map representation using the {@link LiveMapType} interface.
+ * - If an `object` key exists in `AblyObjectsTypes` and its type conforms to the {@link LiveMapType} interface, it is used as the type for the entrypoint {@link LiveMap} object.
+ * - If the provided type in `object` key does not match {@link LiveMapType}, a type error message is returned.
  */
-export type DefaultRoot =
+export type AblyDefaultObject =
   // we need a way to know when no types were provided by the user.
-  // we expect a "root" property to be set on AblyObjectsTypes interface, e.g. it won't be "unknown" anymore
-  unknown extends AblyObjectsTypes['root']
-    ? LiveMapType // no custom types provided; use the default untyped map representation for the root
-    : AblyObjectsTypes['root'] extends LiveMapType
-      ? AblyObjectsTypes['root'] // "root" property exists, and it is of an expected type, we can use this interface for the root object in Objects.
-      : `Provided type definition for the "root" object in AblyObjectsTypes is not of an expected LiveMapType`;
+  // we expect an "object" property to be set on AblyObjectsTypes interface, e.g. it won't be "unknown" anymore
+  unknown extends AblyObjectsTypes['object']
+    ? LiveMapType // no custom types provided; use the default untyped map representation for the entrypoint map
+    : AblyObjectsTypes['object'] extends LiveMapType
+      ? AblyObjectsTypes['object'] // "object" property exists, and it is of an expected type, we can use this interface for the entrypoint map
+      : `Provided type definition for the "object" object in AblyObjectsTypes is not of an expected LiveMapType`;
 
 /**
  * Object returned from an `on` call, allowing the listener provided in that call to be deregistered.
@@ -2424,12 +2424,12 @@ export declare interface OnObjectsEventResponse {
  */
 export declare interface BatchContext {
   /**
-   * Mirrors the {@link RealtimeObject.get} method and returns a {@link BatchContextLiveMap} wrapper for the root object on a channel.
+   * Mirrors the {@link RealtimeObject.get} method and returns a {@link BatchContextLiveMap} wrapper for the entrypoint {@link LiveMap} object on a channel.
    *
    * @returns A {@link BatchContextLiveMap} object.
    * @experimental
    */
-  get<T extends LiveMapType = DefaultRoot>(): BatchContextLiveMap<T>;
+  get<T extends LiveMapType = AblyDefaultObject>(): BatchContextLiveMap<T>;
 }
 
 /**

src/plugins/objects/batchcontext.ts

@@ -23,7 +23,7 @@ export class BatchContext {
     this._wrappedObjects.set(this._root.getObjectId(), new BatchContextLiveMap(this, this._realtimeObject, this._root));
   }
 
-  get<T extends API.LiveMapType = API.DefaultRoot>(): BatchContextLiveMap<T> {
+  get<T extends API.LiveMapType = API.AblyDefaultObject>(): BatchContextLiveMap<T> {
     this._realtimeObject.throwIfInvalidAccessApiConfiguration();
     this.throwIfClosed();
     return this.getWrappedObject(ROOT_OBJECT_ID) as BatchContextLiveMap<T>;

src/plugins/objects/realtimeobject.ts

@@ -79,7 +79,7 @@ export class RealtimeObject {
    * This is useful when working with multiple channels with different underlying data structure.
    * @spec RTO1
    */
-  async get<T extends API.LiveMapType = API.DefaultRoot>(): Promise<LiveMap<T>> {
+  async get<T extends API.LiveMapType = API.AblyDefaultObject>(): Promise<LiveMap<T>> {
     this.throwIfInvalidAccessApiConfiguration(); // RTO1a, RTO1b
 
     // if we're not synced yet, wait for sync sequence to finish before returning root

test/package/browser/template/src/index-objects.ts

@@ -8,7 +8,7 @@ declare module globalThis {
   var testAblyPackage: () => Promise<void>;
 }
 
-type CustomRoot = {
+type MyCustomObject = {
   numberKey: number;
   stringKey: string;
   booleanKey: boolean;
@@ -24,11 +24,11 @@ type CustomRoot = {
 
 declare global {
   export interface AblyObjectsTypes {
-    root: CustomRoot;
+    object: MyCustomObject;
   }
 }
 
-type ExplicitRootType = {
+type ExplicitObjectType = {
   someOtherKey: string;
 };
 
@@ -40,32 +40,32 @@ globalThis.testAblyPackage = async function () {
   const channel = realtime.channels.get('channel', { modes: ['OBJECT_SUBSCRIBE', 'OBJECT_PUBLISH'] });
   // check Objects can be accessed
   await channel.attach();
-  // expect root to be a LiveMap instance with Objects types defined via the global AblyObjectsTypes interface
+  // expect entrypoint to be a LiveMap instance with Objects types defined via the global AblyObjectsTypes interface
   // also checks that we can refer to the Objects types exported from 'ably' by referencing a LiveMap interface
-  const root: Ably.LiveMap<CustomRoot> = await channel.object.get();
+  const myObject: Ably.LiveMap<MyCustomObject> = await channel.object.get();
 
-  // check root has expected LiveMap TypeScript type methods
-  const size: number = root.size();
+  // check entrypoint has expected LiveMap TypeScript type methods
+  const size: number = myObject.size();
 
   // check custom user provided typings via AblyObjectsTypes are working:
   // any LiveMap.get() call can return undefined, as the LiveMap itself can be tombstoned (has empty state),
   // or referenced object is tombstoned.
-  // keys on a root:
-  const aNumber: number | undefined = root.get('numberKey');
-  const aString: string | undefined = root.get('stringKey');
-  const aBoolean: boolean | undefined = root.get('booleanKey');
-  const userProvidedUndefined: string | undefined = root.get('couldBeUndefined');
-  // objects on a root:
-  const counter: Ably.LiveCounter | undefined = root.get('counterKey');
-  const map: AblyObjectsTypes['root']['mapKey'] | undefined = root.get('mapKey');
+  // keys on the entrypoint:
+  const aNumber: number | undefined = myObject.get('numberKey');
+  const aString: string | undefined = myObject.get('stringKey');
+  const aBoolean: boolean | undefined = myObject.get('booleanKey');
+  const userProvidedUndefined: string | undefined = myObject.get('couldBeUndefined');
+  // objects on the entrypoint:
+  const counter: Ably.LiveCounter | undefined = myObject.get('counterKey');
+  const map: AblyObjectsTypes['object']['mapKey'] | undefined = myObject.get('mapKey');
   // check string literal types works
-  // need to use nullish coalescing as we didn't actually create any data on the root,
+  // need to use nullish coalescing as we didn't actually create any data on the entrypoint object,
   // so the next calls would fail. we only need to check that TypeScript types work
   const foo: 'bar' = map?.get('foo')!;
   const baz: 'qux' = map?.get('nestedMap')?.get('baz')!;
 
   // check LiveMap subscription callback has correct TypeScript types
-  const { unsubscribe } = root.subscribe(({ update }) => {
+  const { unsubscribe } = myObject.subscribe(({ update }) => {
     // check update object infers keys from map type
     const typedKeyOnMap = update.stringKey;
     switch (typedKeyOnMap) {
@@ -89,6 +89,6 @@ globalThis.testAblyPackage = async function () {
   counterSubscribeResponse?.unsubscribe();
 
   // check can provide custom types for the object.get() method, ignoring global AblyObjectsTypes interface
-  const explicitRoot: Ably.LiveMap<ExplicitRootType> = await channel.object.get<ExplicitRootType>();
-  const someOtherKey: string | undefined = explicitRoot.get('someOtherKey');
+  const explicitObjectType: Ably.LiveMap<ExplicitObjectType> = await channel.object.get<ExplicitObjectType>();
+  const someOtherKey: string | undefined = explicitObjectType.get('someOtherKey');
 };