Update Objects docstrings to not use "root" terminology

[VeskeR]

As the result of https://ably.atlassian.net/wiki/spaces/LOB/pages/4235722804/LODR-042+LiveObjects+Realtime+Client+API+Improvements#Walkthrough we should not mention "root" object anymore

Summary by CodeRabbit

• Refactor

  • Renamed the default LiveMap entrypoint type to AblyDefaultObject and updated default generics accordingly.
  • Replaced the global typing key from “root” to “object” for custom object mappings.
  • Updated example/custom type names to align with the new “object” terminology.

• Documentation

  • Revised references to the entrypoint LiveMap object and the new AblyDefaultObject default.

• Tests

  • Updated sample typings and examples to use the new naming and mapping conventions.

[coderabbitai]

Caution

Review failed

The head commit changed during the review from 7d6a3b9 to 10d08e1.

Walkthrough

Renames the DefaultRoot type to AblyDefaultObject and switches the entrypoint mapping key from root to object. Updates default generic parameters in RealtimeObject.get and BatchContext.get to AblyDefaultObject. Test template types and global interface declarations are aligned with the new naming.

Changes

Cohort / File(s)	Summary
Public API type rename ably.d.ts	Renamed DefaultRoot to AblyDefaultObject; updated AblyObjectsTypes key from root to object; adjusted docs/comments; changed default generics in relevant declarations to AblyDefaultObject.
Objects plugin: default generic updates src/plugins/objects/batchcontext.ts, src/plugins/objects/realtimeobject.ts	Updated method signatures to default T to API.AblyDefaultObject for BatchContext.get and RealtimeObject.get; no runtime logic changes.
Test template alignment test/package/browser/template/src/index-objects.ts	Renamed sample types CustomRoot → MyCustomObject and ExplicitRootType → ExplicitObjectType; switched global AblyObjectsTypes mapping from root to object; updated usages accordingly.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

I nibble names with tidy delight,
Root hops to object in morning light.
Defaults burrow, clean and bright,
Ably maps set just right.
Thump-thump—tests align in sight! 🥕🐇

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title Check	✅ Passed	The title is a concise, single sentence that clearly states the PR's primary intent to remove "root" terminology from Objects docstrings and matches the PR objectives and changes in the diff (renaming DefaultRoot → AblyDefaultObject and switching AblyObjectsTypes.root → object). Although the patch also includes type and method default updates, the title accurately reflects the main focus and is appropriately specific and readable.
Docstring Coverage	✅ Passed	No functions found in the changes. Docstring coverage check skipped.

Warning

Review ran into problems

🔥 Problems

Errors were encountered while retrieving linked issues.

Errors (1)

• LODR-042: Request failed with status code 404

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (3)

ably.d.ts (2)

2291-2316: Docstring nits: use “an object property” and keep terminology consistent

• “a object property” → “an object property”.
• Doc text is otherwise aligned with the new entrypoint terminology.

Apply this edit:

- * You can specify custom types for Objects by defining a global `AblyObjectsTypes` interface with a `object` property that conforms to {@link LiveMapType}.
+ * You can specify custom types for Objects by defining a global `AblyObjectsTypes` interface with an `object` property that conforms to {@link LiveMapType}.

---

2395-2409: Improve default-type conditional and error message (handle optional property, clearer text)

• If users declare object?: ..., the current check treats it as invalid due to undefined in the type. Wrap in NonNullable<> so optional props work.
• Clarify error message: “the 'object' object” → “the 'object' property”.

Suggested change:

-export type AblyDefaultObject =
-  // we need a way to know when no types were provided by the user.
-  // 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`;
+export type AblyDefaultObject =
+  // Detect absence of user-provided types by checking if the property is still `unknown`
+  unknown extends AblyObjectsTypes['object']
+    ? LiveMapType
+    : NonNullable<AblyObjectsTypes['object']> extends LiveMapType
+      ? NonNullable<AblyObjectsTypes['object']>
+      : 'Provided type definition for the "object" property in AblyObjectsTypes must extend LiveMapType';

src/plugins/objects/realtimeobject.ts (1)

76-89: Update inline docs to avoid “root” terminology

Keep internal docs consistent with the public types/docs (“entrypoint LiveMap/object”).

-  /**
-   * When called without a type variable, we return a default root type which is based on globally defined interface for Objects feature.
-   * A user can provide an explicit type for the this method to explicitly set the type structure on this particular channel.
-   * This is useful when working with multiple channels with different underlying data structure.
-   * @spec RTO1
-   */
+  /**
+   * When called without a type parameter, returns the default entrypoint object type
+   * based on the globally defined AblyObjectsTypes interface.
+   * You can provide an explicit type parameter to set the object structure for this channel.
+   * This is useful when working with multiple channels that have different object schemas.
+   * @spec RTO1
+   */
@@
-    // if we're not synced yet, wait for sync sequence to finish before returning root
+    // if we're not synced yet, wait for sync sequence to finish before returning the entrypoint object

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

Disabled knowledge base sources:

• Jira integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

📥 Commits

Reviewing files that changed from the base of the PR and between be5eb4b and e56a7b3.

📒 Files selected for processing (4)

• ably.d.ts (3 hunks)
• src/plugins/objects/batchcontext.ts (1 hunks)
• src/plugins/objects/realtimeobject.ts (1 hunks)
• test/package/browser/template/src/index-objects.ts (4 hunks)

🧰 Additional context used

🧬 Code graph analysis (4)

src/plugins/objects/realtimeobject.ts (2)

ably.d.ts (2)

• LiveMapType (2392-2392)
• AblyDefaultObject (2401-2408)

src/plugins/objects/livemap.ts (1)

• LiveMap (48-929)

src/plugins/objects/batchcontext.ts (2)

ably.d.ts (2)

• LiveMapType (2392-2392)
• AblyDefaultObject (2401-2408)

src/plugins/objects/batchcontextlivemap.ts (1)

• BatchContextLiveMap (7-62)

test/package/browser/template/src/index-objects.ts (2)

src/plugins/objects/livemap.ts (2)

• LiveMap (48-929)
• size (305-319)

ably.d.ts (1)

• AblyObjectsTypes (2383-2385)

ably.d.ts (3)

src/plugins/objects/livemap.ts (1)

• LiveMap (48-929)

test/package/browser/template/src/index-objects.ts (1)

• AblyObjectsTypes (26-28)

src/plugins/objects/batchcontextlivemap.ts (1)

• BatchContextLiveMap (7-62)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (7)

• GitHub Check: test-browser (firefox)
• GitHub Check: test-browser (webkit)
• GitHub Check: test-browser (chromium)
• GitHub Check: test-node (20.x)
• GitHub Check: test-npm-package
• GitHub Check: test-node (18.x)
• GitHub Check: test-node (16.x)

🔇 Additional comments (8)

ably.d.ts (3)

2316-2316: Default generic switch to AblyDefaultObject looks good

The API surface now defaults to AblyDefaultObject. This aligns with the new global mapping via AblyObjectsTypes['object'].

---

2427-2433: BatchContext.get default generic aligned with AblyDefaultObject

The type default is consistent with RealtimeObject.get and the new global mapping.

---

1-4042: No lingering DefaultRoot / AblyObjectsTypes.root references found. Search returned only unrelated root keys in config files — vitest.config.ts:6, src/platform/react-hooks/vite.config.ts:5, vite.config.ts:6 — no matches for DefaultRoot or AblyObjectsTypes.root.

src/plugins/objects/realtimeobject.ts (1)

82-91: Default generic switch to API.AblyDefaultObject looks good

Type inference for callers that omit the generic now correctly flows from AblyObjectsTypes['object'].

src/plugins/objects/batchcontext.ts (1)

26-30: BatchContext.get default generic updated to API.AblyDefaultObject

Consistent with RealtimeObject.get and ably.d.ts; no runtime impact.

test/package/browser/template/src/index-objects.ts (3)

11-29: Global typing switch to object: MyCustomObject is correct

The new mapping aligns with AblyDefaultObject resolution. Good rename and structure.

---

43-61: Type-checks validate new default inference path

• Default generic correctly infers MyCustomObject.
• Referencing AblyObjectsTypes['object']['mapKey'] ensures the global mapping is exercised.

---

92-94: Explicit generic override test is appropriate

Verifies callers can bypass the global default when needed.