DEV: (cmds) update INCREX command page for recent API change (#3350)

* DEV: (cmds) update INCREX command page for recent API change

* Address reviewer's concerns

* Address more of the reviewer's comments

Author: dwdougherty

content/commands/increx.md

@@ -17,22 +17,13 @@ arguments:
   name: increment
   optional: true
   type: oneof
-- arguments:
-  - name: fail
-    token: FAIL
-    type: pure-token
-  - name: sat
-    token: SAT
-    type: pure-token
-  - name: reject
-    token: REJECT
-    type: pure-token
-  name: overflow-block
+- name: saturate
   optional: true
-  summary: Out-of-bounds policy; defaults to FAIL. Missing LBOUND/UBOUND default to
-    the type limits (LLONG_MIN/LLONG_MAX for BYINT, -LDBL_MAX/LDBL_MAX for BYFLOAT).
-  token: OVERFLOW
-  type: oneof
+  summary: Saturate the result to LBOUND/UBOUND (or the type limits when no explicit
+    bound is given) when out of bounds. Without this option, out-of-bounds operations
+    are rejected and reply [current_value, 0].
+  token: SATURATE
+  type: pure-token
 - name: lowerbound
   optional: true
   summary: Integer when used with BYINT, floating-point when used with BYFLOAT.
@@ -115,17 +106,16 @@ reply_schema:
 since: 8.8.0
 summary: Increments the numeric value of a key by a number and sets its expiration
   time. Uses 0 as initial value if the key doesn't exist.
-syntax_fmt: "INCREX key [BYFLOAT\_float | BYINT\_integer]\n\
-  \ [LBOUND\_lowerbound] [UBOUND\_upperbound] [OVERFLOW\_<FAIL | SAT | REJECT>]\n\
-  \ [EX\_seconds | PX\_milliseconds| EXAT\_unix-time-seconds | PXAT\_unix-time-milliseconds | PERSIST]\n\
-  \ [ENX]"
+syntax_fmt: "INCREX key [BYFLOAT\_increment | BYINT\_increment]\n\
+  \ [LBOUND\_lowerbound] [UBOUND\_upperbound] [SATURATE]\n\
+  \ [EX\_seconds | PX\_milliseconds | EXAT\_unix-time-seconds| PXAT\_unix-time-milliseconds | PERSIST] [ENX]"
 title: INCREX
 ---
 Increments or decrements the numeric value stored at `key` by the specified amount, with optional upper/lower bounds and expiration control, in a single atomic operation.
 If the key does not exist, it is set to `0` before performing the operation.
 An error is returned if the key contains a value of the wrong type or a string that cannot be interpreted as a number.
 
-Unlike [`INCR`]({{< relref "/commands/incr" >}}) and [`INCRBY`]({{< relref "/commands/incrby" >}}), `INCREX` returns an array of two elements: the new value of the key after the increment, and the increment that was actually applied. The `OVERFLOW` option controls what happens when the computed result would fall outside an explicit `LBOUND`/`UBOUND` or the type limits: the command can fail with an error (the default), saturate the result to the bound, or skip the operation.
+Unlike [`INCR`]({{< relref "/commands/incr" >}}) and [`INCRBY`]({{< relref "/commands/incrby" >}}), `INCREX` returns an array of two elements: the new value of the key after the increment, and the increment that was actually applied. When the computed result would fall outside an explicit `LBOUND`/`UBOUND` or the type limits, the default is to skip the operation and reply with `[current_value, 0]`, leaving the key and its TTL untouched. The `SATURATE` flag changes this behavior so the result is capped at the bound instead.
 
 ## Required arguments
 
@@ -137,7 +127,7 @@ The name of the key to increment.
 
 ## Optional arguments
 
-<details open><summary><code>BYFLOAT float | BYINT integer</code></summary>
+<details open><summary><code>BYFLOAT increment | BYINT increment</code></summary>
 
 Specifies the increment amount and type:
 
@@ -150,23 +140,21 @@ If neither `BYFLOAT` nor `BYINT` is specified, the key is incremented by `1` in
 
 <details open><summary><code>LBOUND lowerbound</code></summary>
 
-Sets a lower bound for the resulting value. If the computed result would fall below `lowerbound`, the behavior is determined by the `OVERFLOW` option. Defaults to `LLONG_MIN` in integer mode or `-LDBL_MAX` in `BYFLOAT` mode. `LBOUND` must be less than or equal to `UBOUND` when both are specified.
+Sets a lower bound for the resulting value. If the computed result would fall below `lowerbound`, the operation is skipped and the reply is `[current_value, 0]` (or use the `SATURATE` flag to floor the result at `lowerbound` instead). When omitted, the bound is `LLONG_MIN` in integer mode or `-LDBL_MAX` in `BYFLOAT` mode. `LBOUND` must be less than or equal to `UBOUND` when both are specified.
 
 </details>
 
 <details open><summary><code>UBOUND upperbound</code></summary>
 
-Sets an upper bound for the resulting value. If the computed result would exceed `upperbound`, the behavior is determined by the `OVERFLOW` option. Defaults to `LLONG_MAX` in integer mode or `LDBL_MAX` in `BYFLOAT` mode. `UBOUND` must be greater than or equal to `LBOUND` when both are specified.
+Sets an upper bound for the resulting value. If the computed result would exceed `upperbound`, the operation is skipped and the reply is `[current_value, 0]` (or use the `SATURATE` flag to cap the result at `upperbound` instead). When omitted, the bound is `LLONG_MAX` in integer mode or `LDBL_MAX` in `BYFLOAT` mode. `UBOUND` must be greater than or equal to `LBOUND` when both are specified.
 
 </details>
 
-<details open><summary><code>OVERFLOW FAIL | SAT | REJECT</code></summary>
+<details open><summary><code>SATURATE</code></summary>
 
-Sets the policy for handling out-of-bounds results. A bound violation includes both exceeding an explicit `LBOUND`/`UBOUND` and overflowing the type limits when no explicit bound is given.
+When specified, an out-of-bounds result is capped at `UBOUND` or floored at `LBOUND` (or saturated to the type limits when no explicit bound is given). The second element of the reply reflects the saturated delta. An error is returned if the delta cannot be represented as a 64-bit signed integer in integer mode, or would produce Infinity in `BYFLOAT` mode. Any expiration option is still applied as specified.
 
-* `FAIL` (default): if the computed result would violate a bound, the command returns an error and the key is left unchanged. This matches the existing semantics of [`INCRBY`]({{< relref "/commands/incrby" >}}) and [`INCRBYFLOAT`]({{< relref "/commands/incrbyfloat" >}}) on overflow.
-* `SAT`: the result is capped at `UBOUND` or floored at `LBOUND` (or saturated to the type limits when no explicit bound is given). The second element of the reply reflects the saturated delta. An error is returned if the delta cannot be represented as a 64-bit signed integer in integer mode, or would produce Infinity in `BYFLOAT` mode. If the result is saturated, any expiration option is still applied as specified.
-* `REJECT`: the operation is skipped. The key value and its TTL are left unchanged, no keyspace notification is fired, and nothing is replicated. The reply is `[current_value, 0]`, allowing the caller to detect the rejection without handling an error. Any expiration option is ignored on the rejected branch.
+A bound violation includes both exceeding an explicit `LBOUND`/`UBOUND` and overflowing the type limits when no explicit bound is given.
 
 </details>
 
@@ -243,27 +231,25 @@ INCREX mykey BYINT 1 PERSIST
 TTL mykey
 {{% /redis-cli %}}
 
-Compare the three `OVERFLOW` policies when the result would exceed `UBOUND`. The default `FAIL` returns an error, `SAT` caps the result at the bound, and `REJECT` leaves the key untouched and reports a zero delta:
+Compare the default out-of-bounds behavior with `SATURATE` when the result would exceed `UBOUND`. By default the key is left untouched and the reply reports a zero delta; with `SATURATE` the result is capped at the bound and the reply reflects the saturated delta:
 
 {{% redis-cli %}}
 SET mykey 99
 INCREX mykey BYINT 5 UBOUND 100
 SET mykey 99
-INCREX mykey BYINT 5 UBOUND 100 OVERFLOW SAT
-SET mykey 99
-INCREX mykey BYINT 5 UBOUND 100 OVERFLOW REJECT
+INCREX mykey BYINT 5 UBOUND 100 SATURATE
 {{% /redis-cli %}}
 
 ## Pattern: window counter rate limiter
 
 A common rate-limiting pattern requires atomically incrementing a counter and setting its expiration. With plain [`INCR`]({{< relref "/commands/incr" >}}) and [`EXPIRE`]({{< relref "/commands/expire" >}}), this typically requires a Lua script to be atomic.
 
-`INCREX` requires a single native command. `UBOUND` enforces the rate cap, `OVERFLOW REJECT` skips the operation once the cap is reached, and `ENX` ensures that a new window with the correct duration is created if the previous one has expired; if a window already exists, it won't be extended. When the counter has already reached the cap, `actual_increment` is `0`, giving the caller immediate feedback without extra reads or error handling:
+`INCREX` requires a single native command. `UBOUND` enforces the rate cap — by default, once the cap is reached the operation is skipped — and `ENX` ensures that a new window with the correct duration is created if the previous one has expired; if a window already exists, it won't be extended. When the counter has already reached the cap, `actual_increment` is `0`, giving the caller immediate feedback without extra reads or error handling:
 
 ```python
 new_val, actual_incr = redis.execute_command(
     "INCREX", f"ratelimit:{user_id}",
-    "BYINT", 1, "UBOUND", 100, "OVERFLOW", "REJECT",
+    "BYINT", 1, "UBOUND", 100,
     "EX", 60, "ENX",
 )
 if actual_incr == 0:
@@ -284,17 +270,17 @@ if actual_incr == 0:
 
 [Array reply]({{< relref "/develop/reference/protocol-spec#arrays" >}}): a two-element array:
 
-1. **New value** — the value of the key after the increment, or the unchanged current value under `OVERFLOW REJECT`.
-2. **Actual increment** — the increment that was actually applied. May differ from the requested increment when `OVERFLOW SAT` saturates the result to a bound, and is always `0` when `OVERFLOW REJECT` skipped the operation.
+1. **New value** — the value of the key after the increment, or the unchanged current value when an out-of-bounds result caused the operation to be skipped.
+2. **Actual increment** — the increment that was actually applied. May differ from the requested increment when `SATURATE` caps the result at a bound, and is always `0` when an out-of-bounds result caused the operation to be skipped.
 
 Both elements are [Integer replies]({{< relref "/develop/reference/protocol-spec#integers" >}}) in integer mode (default or `BYINT`), or [Bulk string replies]({{< relref "/develop/reference/protocol-spec#bulk-strings" >}}) representing the float values in `BYFLOAT` mode.
 
 -tab-sep-
 
 [Array reply]({{< relref "/develop/reference/protocol-spec#arrays" >}}): a two-element array:
 
-1. **New value** — the value of the key after the increment, or the unchanged current value under `OVERFLOW REJECT`.
-2. **Actual increment** — the increment that was actually applied. May differ from the requested increment when `OVERFLOW SAT` saturates the result to a bound, and is always `0` when `OVERFLOW REJECT` skipped the operation.
+1. **New value** — the value of the key after the increment, or the unchanged current value when an out-of-bounds result caused the operation to be skipped.
+2. **Actual increment** — the increment that was actually applied. May differ from the requested increment when `SATURATE` caps the result at a bound, and is always `0` when an out-of-bounds result caused the operation to be skipped.
 
 Both elements are [Integer replies]({{< relref "/develop/reference/protocol-spec#integers" >}}) in integer mode (default or `BYINT`), or [Double replies]({{< relref "/develop/reference/protocol-spec#doubles" >}}) in `BYFLOAT` mode.