From 7f880a64d29711f790d083124446c701e6233c66 Mon Sep 17 00:00:00 2001 From: Simon Prickett Date: Thu, 6 Apr 2023 20:29:01 +0100 Subject: [PATCH] Worked on phrasing etc for v5 doc changes. --- docs/clustering.md | 6 +++--- md/RESP3.md | 6 +++--- md/v4-to-v5.md | 29 +++++++++++++++-------------- md/v5-new-features.md | 4 ++++ 4 files changed, 25 insertions(+), 20 deletions(-) diff --git a/docs/clustering.md b/docs/clustering.md index 28ea0e2964..7b8b66a9ad 100644 --- a/docs/clustering.md +++ b/docs/clustering.md @@ -32,7 +32,7 @@ const value = await cluster.get('key'); | Property | Default | Description | |------------------------|---------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| rootNodes | | An array of root nodes that are part of the cluster, which will be used to get the cluster topology. Each element in the array is a client configuration object. There is no need to specify every node in the cluster, 3 should be enough to reliably connect and obtain the cluster configuration from the server | +| rootNodes | | An array of root nodes that are part of the cluster, which will be used to get the cluster topology. Each element in the array is a client configuration object. There is no need to specify every node in the cluster: 3 should be enough to reliably connect and obtain the cluster configuration from the server | | defaults | | The default configuration values for every client in the cluster. Use this for example when specifying an ACL user to connect with | | useReplicas | `false` | When `true`, distribute load by executing readonly commands (such as `GET`, `GEOSEARCH`, etc.) across all cluster nodes. When `false`, only use master nodes | | minimizeConnections | `false` | When `true`, `.connect()` will only discover the cluster topology, without actually connecting to all the nodes. Useful for short-term or Pub/Sub-only connections. | @@ -107,7 +107,7 @@ createCluster({ ### Commands that operate on Redis Keys -Commands such as `GET`, `SET`, etc. are routed by the first key, for instance `MGET 1 2 3` will be routed by the key `1`. +Commands such as `GET`, `SET`, etc. are routed by the first key specified. For example `MGET 1 2 3` will be routed by the key `1`. ### [Server Commands](https://redis.io/commands#server) @@ -115,4 +115,4 @@ Admin commands such as `MEMORY STATS`, `FLUSHALL`, etc. are not attached to the ### "Forwarded Commands" -Certain commands (e.g. `PUBLISH`) are forwarded to other cluster nodes by the Redis server. This client sends these commands to a random node in order to spread the load across the cluster. +Certain commands (e.g. `PUBLISH`) are forwarded to other cluster nodes by the Redis server. The client sends these commands to a random node in order to spread the load across the cluster. diff --git a/md/RESP3.md b/md/RESP3.md index c212b6fdf2..2c684be2b1 100644 --- a/md/RESP3.md +++ b/md/RESP3.md @@ -1,4 +1,4 @@ -# RESP3 => JS type mapping: +# RESP3 => JS Type Mappings: - Null (`_`) => `null` - Boolean (`#`) => `boolean` @@ -21,11 +21,11 @@ ## Map keys and Set members -When decoding Map to `Map | object` or Set to `Set`, keys/members of type "Simple String" or "Blob String" will be decode as `string`s (ignoring flags) to allow lookup by type. If you need them as `Buffer`s, make sure to decode `Map`s/`Set`s as `Array`s. +When decoding Map to `Map | object` or Set to `Set`, keys/members of type "Simple String" or "Blob String" will be decoded as `string`s (ignoring flags) to allow lookup by type. If you need them as `Buffer`s, make sure to decode `Map`s/`Set`s as `Array`s. ## Not Implemented -These parts of RESP3 are not implemented in Redis itself (at the time of writing this), so we did not implemented them in the client as well: +These parts of RESP3 are not yet implemented in Redis itself (at the time of writing), so are not yet implemented in the Node-Redis client either: - [Attribute type](https://github.com/redis/redis-specifications/blob/master/protocol/RESP3.md#attribute-type) - [Streamed strings](https://github.com/redis/redis-specifications/blob/master/protocol/RESP3.md#streamed-strings) diff --git a/md/v4-to-v5.md b/md/v4-to-v5.md index f0f3442f93..fd5de1ca13 100644 --- a/md/v4-to-v5.md +++ b/md/v4-to-v5.md @@ -2,7 +2,7 @@ ## Commands -Some command arguments/replies changed to be more aligned with Redis: +Some command arguments/replies have changed to align more closely to data types returned by Redis: - `ACL GETUSER`: `selectors` - `CLIENT KILL`: `enum ClientKillFilters` -> `const CLIENT_KILL_FILTERS` [^enum-to-constants] @@ -32,21 +32,21 @@ Some command arguments/replies changed to be more aligned with Redis: ## Command Options -in v4, command options are passed as a first optional argument: +In v4, command options are passed as a first optional argument: ```javascript await client.get('key'); // `string | null` await client.get(client.commandOptions({ returnBuffers: true }), 'key'); // `Buffer | null` ``` -which has a couple of flaws: -1. The arguments types is checked in runtime, which hit performance. -2. Makes code suggestions less readable/usable, due to "function overloading". -3. Overall makes the "user code" not very readable. +This has a couple of flaws: +1. The argument types are checked in runtime, which is a performance hit. +2. Code suggestions are less readable/usable, due to "function overloading". +3. Overall, "user code" is not as readable as it could be. -### The new API +### The new API for v5 -With the new API instead of passing the options directrly to the commands, we use a "proxy client" to store the options: +With the new API, instead of passing the options directly to the commands we use a "proxy client" to store them: ```javascript await client.get('key'); // `string | null` @@ -60,16 +60,17 @@ const proxyClient = client.withCommandOptions({ await proxyClient.get('key'); // `Buffer | null` ``` -`withCommandOptions` can be used to override all the command options, without reusing any of the existing ones. -On top of that, these functions can be used to override a specific option: +`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. - `asap` - override `asap` to `true`. - `isolated` - override `isolated` to `true`. ## Quit VS Disconnect -close -quit -disconnect +The `QUIT` command has been deprecated in Redis 7.2 and should now also be considered deprecated in Node-Redis. Rather than sending a `QUIT` command to the server, the client can simply close the network connection. -TODO +Rather than using `client.quit()`, your code should use `client.close()` or `client.disconnect()`. + +TODO difference between `close` and `disconnect`... diff --git a/md/v5-new-features.md b/md/v5-new-features.md index 8b762a3a59..b9ac586083 100644 --- a/md/v5-new-features.md +++ b/md/v5-new-features.md @@ -15,6 +15,10 @@ client.withFlags({ # `Multi.exec<'typed'>` +We have introduced the ability to perform a 'typed' `MULTI`/`EXEC` transaction. Rather than returning `Array`, a transaction invoked with `.exec<'typed'>` will return types appropriate to the commands in the transaction where possible. + +Example: + ```javascript client.multi() .ping()