Update method in line with Swift guidelines

See [1], in particular "Prefer method and function names that make use
sites form grammatical English phrases".

The "omit needless words" guideline is a bit harder to interpret and I
wonder whether, under that guideline, things like `send(withParams
params: SendMessageParams)` should be `with params: SendMessageParams`
but honestly I don't know how understandable that is, especially when
you use implicit `.init()` to create the argument. I think better to err
on the side of caution and being a bit more verbose?

Have renamed:

- Messages:
   - history(options: QueryOptions) to history(withOptions options: QueryOptions)
   - send(params: SendMessageParams) to send(withParams params: SendMessageParams)
- MessageSubscriptionAsyncSequence:
  - getPreviousMessages(params: QueryOptions) to getPreviousMessages(withParams params: QueryOptions)
- MessageReactions:
  - send(messageSerial: String, params: SendMessageReactionParams) to send(forMessageWithSerial messageSerial: String, params: SendMessageReactionParams)
  - delete(messageSerial: String, params: SendMessageReactionParams) to delete(forMessageWithSerial messageSerial: String, params: SendMessageReactionParams)
- Presence:
  - get(params: PresenceParams) to get(withParams params: PresenceParams)
  - isUserPresent(clientID: String) to isUserPresent(withClientID clientID: String)
  - enter(data: PresenceData) to enter(withData data: PresenceData); ditto for update, leave
- RoomReactions:
  - send(params: SendReactionParams) to send(withParams params: SendReactionParams)
- MessageSubscriptionResponse:
  - historyBeforeSubscribe(_ params: QueryOptions) to historyBeforeSubscribe(withParams params: QueryOptions)

Have not touched Messages' `update` or `delete` methods yet because
their signature seems completely inconsistent with that of JS; need to
look into it further.

[1] https://www.swift.org/documentation/api-design-guidelines/

Author: lawrence-forooghian

Example/AblyChatExample/ContentView.swift

@@ -224,7 +224,7 @@ struct ContentView: View {
 
                 try await room.attach()
                 try await showOccupancy(room: room)
-                try await room.presence.enter(data: ["status": "📱 Online"])
+                try await room.presence.enter(withData: ["status": "📱 Online"])
 
                 try await showMessages(room: room)
             } catch {
@@ -275,7 +275,7 @@ struct ContentView: View {
                 }
             }
         }
-        let previousMessages = try await subscription.historyBeforeSubscribe(.init())
+        let previousMessages = try await subscription.historyBeforeSubscribe(withParams: .init())
 
         for message in previousMessages.items {
             switch message.action {
@@ -387,7 +387,7 @@ struct ContentView: View {
         guard !newMessage.isEmpty else {
             return
         }
-        _ = try await room().messages.send(params: .init(text: newMessage))
+        _ = try await room().messages.send(withParams: .init(text: newMessage))
         newMessage = ""
     }
 
@@ -417,19 +417,19 @@ struct ContentView: View {
 
     func sendRoomReaction(_ reaction: String) {
         Task {
-            try await room().reactions.send(params: .init(name: reaction))
+            try await room().reactions.send(withParams: .init(name: reaction))
         }
     }
 
     func addMessageReaction(_ reaction: String, messageSerial: String) {
         Task {
-            try await room().messages.reactions.send(messageSerial: messageSerial, params: .init(name: reaction, type: .distinct))
+            try await room().messages.reactions.send(forMessageWithSerial: messageSerial, params: .init(name: reaction, type: .distinct))
         }
     }
 
     func deleteMessageReaction(_ reaction: String, messageSerial: String) {
         Task {
-            try await room().messages.reactions.delete(messageSerial: messageSerial, params: .init(name: reaction, type: .distinct))
+            try await room().messages.reactions.delete(forMessageWithSerial: messageSerial, params: .init(name: reaction, type: .distinct))
         }
     }
 

Example/AblyChatExample/Mocks/MockClients.swift

@@ -246,7 +246,7 @@ class MockMessageReactions: MessageReactions {
         self.roomName = roomName
     }
 
-    func send(messageSerial: String, params: SendMessageReactionParams) async throws(ARTErrorInfo) {
+    func send(forMessageWithSerial messageSerial: String, params: SendMessageReactionParams) async throws(ARTErrorInfo) {
         reactions.append(
             MessageReaction(
                 type: .distinct,
@@ -265,7 +265,7 @@ class MockMessageReactions: MessageReactions {
         )
     }
 
-    func delete(messageSerial: String, params: DeleteMessageReactionParams) async throws(ARTErrorInfo) {
+    func delete(forMessageWithSerial messageSerial: String, params: DeleteMessageReactionParams) async throws(ARTErrorInfo) {
         reactions.removeAll { reaction in
             reaction.messageSerial == messageSerial && reaction.name == params.name && reaction.clientID == clientID
         }

Sources/AblyChat/DefaultMessageReactions.swift

@@ -19,7 +19,7 @@ internal final class DefaultMessageReactions: MessageReactions {
     }
 
     // (CHA-MR4) Users should be able to send a reaction to a message via the `send` method of the `MessagesReactions` object
-    internal func send(messageSerial: String, params: SendMessageReactionParams) async throws(ARTErrorInfo) {
+    internal func send(forMessageWithSerial messageSerial: String, params: SendMessageReactionParams) async throws(ARTErrorInfo) {
         do {
             var count = params.count
             if params.type == .multiple, params.count == nil {
@@ -40,7 +40,7 @@ internal final class DefaultMessageReactions: MessageReactions {
     }
 
     // (CHA-MR11) Users should be able to delete a reaction from a message via the `delete` method of the `MessagesReactions` object
-    internal func delete(messageSerial: String, params: DeleteMessageReactionParams) async throws(ARTErrorInfo) {
+    internal func delete(forMessageWithSerial messageSerial: String, params: DeleteMessageReactionParams) async throws(ARTErrorInfo) {
         let reactionType = params.type ?? options.defaultMessageReactionType
         if reactionType != .unique, params.name == nil {
             throw ARTErrorInfo(chatError: .unableDeleteReactionWithoutName(reactionType: reactionType.rawValue))

Sources/AblyChat/DefaultMessages.swift

@@ -115,15 +115,15 @@ internal final class DefaultMessages: Messages {
     }
 
     // (CHA-M6a) A method must be exposed that accepts the standard Ably REST API query parameters. It shall call the "REST API"#rest-fetching-messages and return a PaginatedResult containing messages, which can then be paginated through.
-    internal func history(options: QueryOptions) async throws(ARTErrorInfo) -> some PaginatedResult<Message> {
+    internal func history(withOptions options: QueryOptions) async throws(ARTErrorInfo) -> some PaginatedResult<Message> {
         do {
             return try await chatAPI.getMessages(roomName: roomName, params: options)
         } catch {
             throw error.toARTErrorInfo()
         }
     }
 
-    internal func send(params: SendMessageParams) async throws(ARTErrorInfo) -> Message {
+    internal func send(withParams params: SendMessageParams) async throws(ARTErrorInfo) -> Message {
         do {
             return try await chatAPI.sendMessage(roomName: roomName, params: params)
         } catch {

Sources/AblyChat/DefaultPresence.swift

@@ -42,7 +42,7 @@ internal final class DefaultPresence: Presence {
         }
     }
 
-    internal func get(params: PresenceParams) async throws(ARTErrorInfo) -> [PresenceMember] {
+    internal func get(withParams params: PresenceParams) async throws(ARTErrorInfo) -> [PresenceMember] {
         do throws(InternalError) {
             logger.log(message: "Getting presence with params: \(params)", level: .debug)
 
@@ -68,7 +68,7 @@ internal final class DefaultPresence: Presence {
     }
 
     // (CHA-PR5) It must be possible to query if a given clientId is in the presence set.
-    internal func isUserPresent(clientID: String) async throws(ARTErrorInfo) -> Bool {
+    internal func isUserPresent(withClientID clientID: String) async throws(ARTErrorInfo) -> Bool {
         do throws(InternalError) {
             logger.log(message: "Checking if user is present with clientID: \(clientID)", level: .debug)
 
@@ -94,7 +94,7 @@ internal final class DefaultPresence: Presence {
         }
     }
 
-    internal func enter(data: PresenceData) async throws(ARTErrorInfo) {
+    internal func enter(withData data: PresenceData) async throws(ARTErrorInfo) {
         try await enter(optionalData: data)
     }
 
@@ -126,7 +126,7 @@ internal final class DefaultPresence: Presence {
         }
     }
 
-    internal func update(data: PresenceData) async throws(ARTErrorInfo) {
+    internal func update(withData data: PresenceData) async throws(ARTErrorInfo) {
         try await update(optionalData: data)
     }
 
@@ -158,7 +158,7 @@ internal final class DefaultPresence: Presence {
         }
     }
 
-    internal func leave(data: PresenceData) async throws(ARTErrorInfo) {
+    internal func leave(withData data: PresenceData) async throws(ARTErrorInfo) {
         try await leave(optionalData: data)
     }
 

Sources/AblyChat/DefaultRoomReactions.swift

@@ -15,7 +15,7 @@ internal final class DefaultRoomReactions: RoomReactions {
 
     // (CHA-ER3) Ephemeral room reactions are sent to Ably via the Realtime connection via a send method.
     // (CHA-ER3d) Reactions are sent on the channel using a message in a particular format - see spec for format.
-    internal func send(params: SendReactionParams) async throws(ARTErrorInfo) {
+    internal func send(withParams params: SendReactionParams) async throws(ARTErrorInfo) {
         do {
             logger.log(message: "Sending reaction with params: \(params)", level: .debug)
 

Sources/AblyChat/MessageReactions.swift

@@ -19,7 +19,7 @@ public protocol MessageReactions: AnyObject, Sendable {
      *
      * - Note: It is possible to receive your own reaction via the reactions subscription before this method returns.
      */
-    func send(messageSerial: String, params: SendMessageReactionParams) async throws(ARTErrorInfo)
+    func send(forMessageWithSerial messageSerial: String, params: SendMessageReactionParams) async throws(ARTErrorInfo)
 
     /**
      * Delete a message reaction.
@@ -28,7 +28,7 @@ public protocol MessageReactions: AnyObject, Sendable {
      *   - messageSerial: A serial of the message to remove the reaction from.
      *   - params: The type of reaction annotation and the specific reaction to remove. The reaction to remove is required for all types except ``MessageReactionType/unique``.
      */
-    func delete(messageSerial: String, params: DeleteMessageReactionParams) async throws(ARTErrorInfo)
+    func delete(forMessageWithSerial messageSerial: String, params: DeleteMessageReactionParams) async throws(ARTErrorInfo)
 
     /**
      * Subscribe to message reaction summaries. Use this to keep message reaction counts up to date efficiently in the UI.

Sources/AblyChat/Messages.swift

@@ -33,7 +33,7 @@ public protocol Messages: AnyObject, Sendable {
      *
      * - Returns: A paginated result object that can be used to fetch more messages if available.
      */
-    func history(options: QueryOptions) async throws(ARTErrorInfo) -> HistoryResult
+    func history(withOptions options: QueryOptions) async throws(ARTErrorInfo) -> HistoryResult
 
     /**
      * Send a message in the chat room.
@@ -47,7 +47,7 @@ public protocol Messages: AnyObject, Sendable {
      *
      * - Note: It is possible to receive your own message via the messages subscription before this method returns.
      */
-    func send(params: SendMessageParams) async throws(ARTErrorInfo) -> Message
+    func send(withParams params: SendMessageParams) async throws(ARTErrorInfo) -> Message
 
     /**
      * Updates a message in the chat room.
@@ -391,7 +391,7 @@ public final class MessageSubscriptionAsyncSequence<HistoryResult: PaginatedResu
     }
 
     // swiftlint:disable:next missing_docs
-    public func getPreviousMessages(params: QueryOptions) async throws(ARTErrorInfo) -> HistoryResult {
+    public func getPreviousMessages(withParams params: QueryOptions) async throws(ARTErrorInfo) -> HistoryResult {
         try await getPreviousMessages(params)
     }
 

Sources/AblyChat/Presence.swift

@@ -29,7 +29,7 @@ public protocol Presence: AnyObject, Sendable {
      *
      * - Throws: An `ARTErrorInfo`.
      */
-    func get(params: PresenceParams) async throws(ARTErrorInfo) -> [PresenceMember]
+    func get(withParams params: PresenceParams) async throws(ARTErrorInfo) -> [PresenceMember]
 
     /**
      * Method to check if user with supplied clientId is online.
@@ -41,7 +41,7 @@ public protocol Presence: AnyObject, Sendable {
      *
      * - Throws: An `ARTErrorInfo`.
      */
-    func isUserPresent(clientID: String) async throws(ARTErrorInfo) -> Bool
+    func isUserPresent(withClientID clientID: String) async throws(ARTErrorInfo) -> Bool
 
     /**
      * Method to join room presence, will emit an enter event to all subscribers. Repeat calls will trigger more enter events.
@@ -51,7 +51,7 @@ public protocol Presence: AnyObject, Sendable {
      *
      * - Throws: An `ARTErrorInfo`.
      */
-    func enter(data: PresenceData) async throws(ARTErrorInfo)
+    func enter(withData data: PresenceData) async throws(ARTErrorInfo)
 
     /**
      * Method to update room presence, will emit an update event to all subscribers. If the user is not present, it will be treated as a join event.
@@ -61,7 +61,7 @@ public protocol Presence: AnyObject, Sendable {
      *
      * - Throws: An `ARTErrorInfo`.
      */
-    func update(data: PresenceData) async throws(ARTErrorInfo)
+    func update(withData data: PresenceData) async throws(ARTErrorInfo)
 
     /**
      * Method to leave room presence, will emit a leave event to all subscribers. If the user is not present, it will be treated as a no-op.
@@ -71,7 +71,7 @@ public protocol Presence: AnyObject, Sendable {
      *
      * - Throws: An `ARTErrorInfo`.
      */
-    func leave(data: PresenceData) async throws(ARTErrorInfo)
+    func leave(withData data: PresenceData) async throws(ARTErrorInfo)
 
     /**
      * Subscribes a given listener to a particular presence event in the chat room.

Sources/AblyChat/RoomReactions.swift

@@ -18,7 +18,7 @@ public protocol RoomReactions: AnyObject, Sendable {
      *
      * - Note: It is possible to receive your own reaction via the reactions subscription before this method returns.
      */
-    func send(params: SendReactionParams) async throws(ARTErrorInfo)
+    func send(withParams params: SendReactionParams) async throws(ARTErrorInfo)
 
     /**
      * Subscribes a given listener to the room reactions.