feat!(base): reintroduce Room::display_name

`compute_display_name` is made private again, and used only within the
base crate. A new public counterpart `Room::display_name` is introduced,
which returns a cached value for, or computes (and fills in cache) the
display name. This is simpler to use, and likely what most users expect
anyways.

Author: bnjbvr

crates/matrix-sdk-base/CHANGELOG.md

@@ -6,6 +6,16 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased] - ReleaseDate
 
+### Breaking changes
+
+- Replaced `Room::compute_display_name` with the reintroduced `Room::display_name()`. The new
+  method computes a display name, or return a cached value from the previous successful computation.
+  If you need a sync variant, consider using `Room::cached_display_name()`.
+
+### Features
+
+### Bug Fixes
+
 ## [0.9.0] - 2024-12-18
 
 ### Features

crates/matrix-sdk-base/src/rooms/normal.rs

@@ -623,18 +623,40 @@ impl Room {
         self.inner.read().active_room_call_participants()
     }
 
-    /// Calculate a room's display name, taking into account its name, aliases
-    /// and members.
+    /// Calculate a room's display name, or return the cached value, taking into
+    /// account its name, aliases and members.
+    ///
+    /// The display name is calculated according to [this algorithm][spec].
+    ///
+    /// While the underlying computation can be slow, the result is cached and
+    /// returned on the following calls. The cache is also filled on every
+    /// successful sync, since a sync may cause a change in the display
+    /// name.
+    ///
+    /// If you need a variant that's sync (but with the drawback that it returns
+    /// an `Option`), consider using [`Room::cached_display_name`].
+    ///
+    /// [spec]: <https://matrix.org/docs/spec/client_server/latest#calculating-the-display-name-for-a-room>
+    pub async fn display_name(&self) -> StoreResult<RoomDisplayName> {
+        if let Some(name) = self.cached_display_name() {
+            Ok(name)
+        } else {
+            self.compute_display_name().await
+        }
+    }
+
+    /// Force recalculating a room's display name, taking into account its name,
+    /// aliases and members.
     ///
     /// The display name is calculated according to [this algorithm][spec].
     ///
     /// ⚠ This may be slowish to compute. As such, the result is cached and can
-    /// be retrieved via [`Room::cached_display_name`], which should be
-    /// preferred in general. Indeed, the cached value is automatically
-    /// recomputed on every sync.
+    /// be retrieved via [`Room::cached_display_name`] (sync, returns an option)
+    /// or [`Room::display_name`] (async, always returns a value), which should
+    /// be preferred in general.
     ///
     /// [spec]: <https://matrix.org/docs/spec/client_server/latest#calculating-the-display-name-for-a-room>
-    pub async fn compute_display_name(&self) -> StoreResult<RoomDisplayName> {
+    pub(crate) async fn compute_display_name(&self) -> StoreResult<RoomDisplayName> {
         enum DisplayNameOrSummary {
             Summary(RoomSummary),
             DisplayName(RoomDisplayName),
@@ -871,8 +893,7 @@ impl Room {
 
     /// Returns the cached computed display name, if available.
     ///
-    /// This cache is refilled every time we call
-    /// [`Self::compute_display_name`].
+    /// This cache is refilled every time we call [`Self::display_name`].
     pub fn cached_display_name(&self) -> Option<RoomDisplayName> {
         self.inner.read().cached_display_name.clone()
     }

crates/matrix-sdk-ui/src/notification_client.rs

@@ -740,7 +740,7 @@ impl NotificationItem {
             sender_display_name,
             sender_avatar_url,
             is_sender_name_ambiguous,
-            room_computed_display_name: room.compute_display_name().await?.to_string(),
+            room_computed_display_name: room.display_name().await?.to_string(),
             room_avatar_url: room.avatar_url().map(|s| s.to_string()),
             room_canonical_alias: room.canonical_alias().map(|c| c.to_string()),
             is_direct_message_room: room.is_direct().await?,

crates/matrix-sdk/src/room_preview.rs

@@ -130,7 +130,7 @@ impl RoomPreview {
     pub(crate) async fn from_joined(room: &Room) -> Self {
         let is_direct = room.is_direct().await.ok();
 
-        let display_name = room.compute_display_name().await.ok().map(|name| name.to_string());
+        let display_name = room.display_name().await.ok().map(|name| name.to_string());
 
         Self::from_room_info(
             room.clone_info(),

crates/matrix-sdk/tests/integration/room/common.rs

@@ -65,7 +65,7 @@ async fn test_calculate_room_names_from_summary() {
 
     assert_eq!(
         RoomDisplayName::Calculated("example2".to_owned()),
-        room.compute_display_name().await.unwrap()
+        room.display_name().await.unwrap()
     );
 }
 
@@ -83,10 +83,7 @@ async fn test_room_names() {
     assert_eq!(client.rooms().len(), 1);
     let room = client.get_room(&DEFAULT_TEST_ROOM_ID).unwrap();
 
-    assert_eq!(
-        RoomDisplayName::Aliased("tutorial".to_owned()),
-        room.compute_display_name().await.unwrap()
-    );
+    assert_eq!(RoomDisplayName::Aliased("tutorial".to_owned()), room.display_name().await.unwrap());
 
     // Room with a name.
     mock_sync(&server, &*test_json::INVITE_SYNC, None).await;
@@ -99,7 +96,7 @@ async fn test_room_names() {
 
     assert_eq!(
         RoomDisplayName::Named("My Room Name".to_owned()),
-        invited_room.compute_display_name().await.unwrap()
+        invited_room.display_name().await.unwrap()
     );
 
     let mut sync_builder = SyncResponseBuilder::new();
@@ -137,7 +134,7 @@ async fn test_room_names() {
         RoomDisplayName::Calculated(
             "user_0, user_1, user_10, user_11, user_12, and 10 others".to_owned()
         ),
-        room.compute_display_name().await.unwrap()
+        room.display_name().await.unwrap()
     );
 
     // Room with joined and invited members.
@@ -185,7 +182,7 @@ async fn test_room_names() {
 
     assert_eq!(
         RoomDisplayName::Calculated("Bob, example1".to_owned()),
-        room.compute_display_name().await.unwrap()
+        room.display_name().await.unwrap()
     );
 
     // Room with only left members.
@@ -205,7 +202,7 @@ async fn test_room_names() {
 
     assert_eq!(
         RoomDisplayName::EmptyWas("user_0, user_1, user_2".to_owned()),
-        room.compute_display_name().await.unwrap()
+        room.display_name().await.unwrap()
     );
 }
 

examples/oidc_cli/src/main.rs

@@ -935,7 +935,7 @@ async fn on_room_message(event: OriginalSyncRoomMessageEvent, room: Room) {
     }
     let MessageType::Text(text_content) = &event.content.msgtype else { return };
 
-    let room_name = match room.compute_display_name().await {
+    let room_name = match room.display_name().await {
         Ok(room_name) => room_name.to_string(),
         Err(error) => {
             println!("Error getting room display name: {error}");

examples/persist_session/src/main.rs

@@ -297,7 +297,7 @@ async fn on_room_message(event: OriginalSyncRoomMessageEvent, room: Room) {
     }
     let MessageType::Text(text_content) = &event.content.msgtype else { return };
 
-    let room_name = match room.compute_display_name().await {
+    let room_name = match room.display_name().await {
         Ok(room_name) => room_name.to_string(),
         Err(error) => {
             println!("Error getting room display name: {error}");