Transaction documentation (#156)

* Transaction docs

Signed-off-by: Adam Fowler <[email protected]>

* Update Sources/Valkey/Documentation.docc/Pipelining.md

Co-authored-by: Joseph Heck <[email protected]>
Signed-off-by: Adam Fowler <[email protected]>

* Update Sources/Valkey/Documentation.docc/Pipelining.md

Co-authored-by: Joseph Heck <[email protected]>
Signed-off-by: Adam Fowler <[email protected]>

* Update Sources/Valkey/Documentation.docc/Transactions.md

Co-authored-by: Joseph Heck <[email protected]>
Signed-off-by: Adam Fowler <[email protected]>

* Update Sources/Valkey/Documentation.docc/Transactions.md

Co-authored-by: Joseph Heck <[email protected]>
Signed-off-by: Adam Fowler <[email protected]>

* Edit check and set text

Signed-off-by: Adam Fowler <[email protected]>

* Transactions are only available on connections

Signed-off-by: Adam Fowler <[email protected]>

---------

Signed-off-by: Adam Fowler <[email protected]>
Co-authored-by: Joseph Heck <[email protected]>

Author: adam-fowler

Sources/Valkey/Documentation.docc/Pipelining.md

@@ -1,6 +1,6 @@
-# Pipelining Commands
+# Pipelining
 
-Sending multiple commands at once without waiting for the response of each command
+Send multiple commands at once without waiting for the response of each command.
 
 Valkey pipelining is a technique for improving performance by issuing multiple commands at once without waiting for the response to each individual command. Pipelining not only reduces the latency cost of waiting for the result of each command it also reduces the cost to the server as it reduces I/O costs. Multiple commands can be read with a single syscall, and multiple results are delivered with a single syscall. 
 
@@ -10,9 +10,9 @@ In valkey-swift each command has its own type conforming to the protocol ``Valke
 
 ```swift
 let (_,_, getResult) = await valkeyClient.pipeline(
-    SET(key: "foo", value: "100"),
-    INCR(key: "foo")
-    GET(key: "foo")
+    SET("foo", value: "100"),
+    INCR("foo")
+    GET("foo")
 )
 // get returns an optional ByteBuffer
 if let result = try getResult.get().map({ String(buffer: $0) }) {
@@ -28,10 +28,10 @@ Being able to have multiple requests in transit on a single connection means we
 try await client.withConnection { connection in
     try await withThrowingTaskGroup(of: Void.self) { group in
         group.addTask {
-            _ = try await connection.lpush(key: "fooList", element: ["bar"])
+            _ = try await connection.lpush("fooList", elements: ["bar"])
         }
         group.addTask {
-            _ = try await connection.rpush(key: "fooList2", element: ["baz"])
+            _ = try await connection.rpush("fooList2", elements: ["baz"])
         }
         try await group.waitForAll()
     }
@@ -41,9 +41,12 @@ try await client.withConnection { connection in
 You can also use `async let` to run commands without waiting for their results immediately.
 
 ```swift
-async let asyncResult = connection.lpush(key: "fooList", element: ["bar"])
+async let asyncResult = connection.lpush("fooList", elements: ["bar"])
 // do something else
 let result = try await asyncResult
 ```
 
-Be careful when using a single connection across multiple Tasks though. The result of a command will only become available when the result of any previous command queued has been made available. So a command that either blocks the connection or takes a long time could affect the response time of commands that follow it.
+Be careful when using a single connection across multiple Tasks though. The result of a command only becomes available when the server makes available the result of the command previously queued. Because of this, a command that either blocks the connection or takes a long time can affect the response time of commands that follow it.
+
+You can find out more about pipelining of commands in the [Valkey documentation](https://valkey.io/topics/pipelining/).
+

Sources/Valkey/Documentation.docc/Transactions.md

@@ -0,0 +1,53 @@
+# Transactions
+
+Perform atomic operations.
+
+Transactions allow you to group multiple commands into an atomic operation. A request sent by another client isn't processed in the middle of the execution of a transaction. Valkey uses the commands `MULTI` and `EXEC` to setup and execute a transaction. After initiating a transaction with `MULTI`, commands return a simple string `QUEUED` to indicate the server queued the commands. When the client sends the `EXEC` command, the server executes all the queued commands and returns an array with their results. 
+
+Because of this custom behaviour valkey-swift provides extra support for executing transactions. The API is very similar to the pipelining function which accepts a parameter pack of commands, detailed in <doc:Pipelining>.
+
+```swift
+try await valkeyClient.withConnection { connection in
+    let results = try await connection.transaction(
+        SET("foo", value: "100"),
+        LPUSH("queue", elements: ["foo"])
+    )
+    let lpushResponse = try results.1.get()
+}
+```
+
+### Rollbacks
+
+Valkey does not support rollbacks of transactions for simplicity and performance reasons. 
+
+### Check and set
+
+The transaction command `WATCH` is used to add a check-and-set behaviour to Valkey transactions. This sets up a list of keys to WATCH, and if any changes to them are detected before the next transaction is executed on the same connection, then that transaction will fail.
+
+For instance, imagine we wanted to atomically increment a counter (assuming we don't have the INCR command). A simple implementation might look like this:
+
+```swift
+// get value, otherwise default to 0
+let value = try await connection.get("counter").map { Int(String(buffer: $0)) } ?? 0
+try await connection.set("counter", String(value + 1))
+```
+
+Unfortunately this isn't a reliable solution as another client could attempt to increment the key "counter" in between the GET and SET commands, then the increment would be applied to the wrong value. By using WATCH and executing the SET inside a transaction we can avoid this. If the key is edited between the WATCH and SET, the transaction fails and throws a `ValkeyClientError(.transactionAborted)` error. When this occurs we know the key was edited between these two commands and we need to update the "counter" value before trying to call SET again, so we run the operation again.
+
+```swift
+while true {
+    try await connection.watch(keys: ["counter"])
+    let value = try await connection.get("counter").map { Int(String(buffer: $0)) } ?? 0
+    do {
+        let result = try await connection.transaction(
+            SET("counter", String(value + 1))
+        )
+        // set was succesful break out of the while loop
+        break
+    } catch let error as ValkeyClientError where error.errorCode == .transactionAborted {
+        // Cancelled SET because "counter" was edited after WATCH, try again
+    }
+}
+```
+
+More can be found out about Valkey transactions in the [Valkey documentation](https://valkey.io/topics/transactions/).

Sources/Valkey/Documentation.docc/index.md

@@ -45,6 +45,7 @@ try await valkeyClient.withConnection { connection in
 ### Articles
 
 - <doc:Pipelining>
+- <doc:Transactions>
 
 ### Client