some docs

Co-authored-by: Guy Royse <guy@guyroyse.com>

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

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
+});
+```

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