From eb47bb03fce3826f1d9787325a6a58cb69f920af Mon Sep 17 00:00:00 2001
From: Leibale <me@leibale.com>
Date: Wed, 7 Jun 2023 11:32:15 -0400
Subject: [PATCH] some docs

Co-authored-by: Guy Royse <guy@guyroyse.com>
---
 docs/command-options.md | 37 +++++++++++++++++++++++++++++++++++++
 docs/scan-iterators.md  | 29 +++++++++++++++++++++++++++++
 docs/v4-to-v5.md        | 28 +++++++++++++++++++++++-----
 3 files changed, 89 insertions(+), 5 deletions(-)
 create mode 100644 docs/command-options.md
 create mode 100644 docs/scan-iterators.md

diff --git a/docs/command-options.md b/docs/command-options.md
new file mode 100644
index 0000000000..0f2a27ec75
--- /dev/null
+++ b/docs/command-options.md
@@ -0,0 +1,37 @@
+# Command Options
+
+> :warning: The command options API in v5 has breaking changes from the previous version. For more details, refer to the [v4-to-v5 guide](./v4-to-v5.md#command-options).
+
+TODO: "proxy client" concept
+
+## Type Mapping
+
+TODO [RESP](./RESP.md)
+
+`withTypeMapping`
+
+```javascript
+await client.get('key'); // `string | null`
+
+const proxyClient = client.withTypeMapping({
+  [TYPES.BLOB_STRING]: Buffer
+});
+
+await proxyClient.get('key'); // `Buffer | null`
+```
+
+## Abort Signal
+
+TODO
+
+`withAbortSignal`
+
+## ASAP
+
+TODO
+
+`asap`
+
+## `withCommandOptions`
+
+TODO
diff --git a/docs/scan-iterators.md b/docs/scan-iterators.md
new file mode 100644
index 0000000000..cfb7545e58
--- /dev/null
+++ b/docs/scan-iterators.md
@@ -0,0 +1,29 @@
+# Scan Iterators
+
+> :warning: The scan iterators API in v5 has breaking changes from the previous version. For more details, refer to the [v4-to-v5 guide](./v4-to-v5.md#scan-iterators).
+
+[`SCAN`](https://redis.io/commands/scan) results can be looped over using [async iterators](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/asyncIterator):
+
+```typescript
+for await (const keys of client.scanIterator()) {
+  const values = await client.mGet(keys);
+}
+```
+
+This works with `HSCAN`, `SSCAN`, and `ZSCAN` too:
+
+```typescript
+for await (const entries of client.hScanIterator('hash')) {}
+for await (const members of client.sScanIterator('set')) {}
+for await (const membersWithScores of client.zScanIterator('sorted-set')) {}
+```
+
+You can override the default options by providing a configuration object:
+
+```typescript
+client.scanIterator({
+  TYPE: 'string', // `SCAN` only
+  MATCH: 'patter*',
+  COUNT: 100
+});
+```
diff --git a/docs/v4-to-v5.md b/docs/v4-to-v5.md
index 332bd12dcf..6d24149ff7 100644
--- a/docs/v4-to-v5.md
+++ b/docs/v4-to-v5.md
@@ -22,7 +22,7 @@ With the new API, instead of passing the options directly to the commands we use
 await client.get('key'); // `string | null`
 
 const proxyClient = client.withCommandOptions({
-  flags: {
+  typeMapping: {
     [TYPES.BLOB_STRING]: Buffer
   }
 });
@@ -33,10 +33,13 @@ await proxyClient.get('key'); // `Buffer | null`
 `withCommandOptions` can be used to override all of the command options, without reusing any existing ones.
 
 To override just a specific option, use the following functions:
-- `withFlags` - override `flags` only.
+- `withTypeMapping` - override `typeMapping` only.
+- `withAbortSignal` - override `abortSignal` only.
 - `asap` - override `asap` to `true`.
 - `isolated` - override `isolated` to `true`.
 
+[TODO](./command-options.md)
+
 ## Quit VS Disconnect
 
 The `QUIT` command has been deprecated in Redis 7.2 and should now also be considered deprecated in Node-Redis. Instead of sending a `QUIT` command to the server, the client can simply close the network connection.
@@ -45,9 +48,24 @@ The `QUIT` command has been deprecated in Redis 7.2 and should now also be consi
 
 ## Scan Iterators
 
-TODO
-Yields chunks instead of individual items. Allows multi key operations.
-See the [Scan Iterators guide](./scan-iterators.md).
+Iterator commands like `SCAN`, `HSCAN`, `SSCAN`, and `ZSCAN` return collections of elements (depending on the data type). However, v4 iterators loop over these collections and yield individual items:
+
+```javascript
+for await (const key of client.scanIterator()) {
+  console.log(key, await client.get(key));
+}
+```
+
+This mismatch can be awkward and makes "multi-key" commands like `MGET`, `UNLINK`, etc. pointless. So, in v5 the iterators now yield a collection instead of an element:
+
+```javascript
+for await (const keys of client.scanIterator()) {
+  // we can now meaningfully utilize "multi-key" commands
+  console.log(keys, await client.mGet(keys));
+}
+```
+
+for more information, see the [Scan Iterators guide](./scan-iterators.md).
 
 ## Legacy Mode