...

specs/backgroundinfo/redis_basics.md

@@ -0,0 +1,251 @@
+Got it 👍 — let’s break this down properly.
+
+Redis has two broad classes you’re asking about:
+
+1. **Basic key-space functions** (SET, GET, DEL, EXISTS, etc.)
+2. **Iteration commands** (`SCAN`, `SSCAN`, `HSCAN`, `ZSCAN`)
+
+And for each I’ll show:
+
+* What it does
+* How it works at a high level
+* Its **RESP protocol implementation** (the actual wire format).
+
+---
+
+# 1. Basic Key-Space Commands
+
+### `SET key value`
+
+* Stores a string value at a key.
+* Overwrites if the key already exists.
+
+**Protocol (RESP2):**
+
+```
+*3
+$3
+SET
+$3
+foo
+$3
+bar
+```
+
+(client sends: array of 3 bulk strings: `["SET", "foo", "bar"]`)
+
+**Reply:**
+
+```
++OK
+```
+
+---
+
+### `GET key`
+
+* Retrieves the string value stored at the key.
+* Returns `nil` if key doesn’t exist.
+
+**Protocol:**
+
+```
+*2
+$3
+GET
+$3
+foo
+```
+
+**Reply:**
+
+```
+$3
+bar
+```
+
+(or `$-1` for nil)
+
+---
+
+### `DEL key [key ...]`
+
+* Removes one or more keys.
+* Returns number of keys actually removed.
+
+**Protocol:**
+
+```
+*2
+$3
+DEL
+$3
+foo
+```
+
+**Reply:**
+
+```
+:1
+```
+
+(integer reply = number of deleted keys)
+
+---
+
+### `EXISTS key [key ...]`
+
+* Checks if one or more keys exist.
+* Returns count of existing keys.
+
+**Protocol:**
+
+```
+*2
+$6
+EXISTS
+$3
+foo
+```
+
+**Reply:**
+
+```
+:1
+```
+
+---
+
+### `KEYS pattern`
+
+* Returns all keys matching a glob-style pattern.
+  ⚠️ Not efficient in production (O(N)), better to use `SCAN`.
+
+**Protocol:**
+
+```
+*2
+$4
+KEYS
+$1
+*
+```
+
+**Reply:**
+
+```
+*2
+$3
+foo
+$3
+bar
+```
+
+(array of bulk strings with key names)
+
+---
+
+# 2. Iteration Commands (`SCAN` family)
+
+### `SCAN cursor [MATCH pattern] [COUNT n]`
+
+* Iterates the keyspace incrementally.
+* Client keeps sending back the cursor from previous call until it returns `0`.
+
+**Protocol example:**
+
+```
+*2
+$4
+SCAN
+$1
+0
+```
+
+**Reply:**
+
+```
+*2
+$1
+0
+*2
+$3
+foo
+$3
+bar
+```
+
+Explanation:
+
+* First element = new cursor (`"0"` means iteration finished).
+* Second element = array of keys returned in this batch.
+
+---
+
+### `HSCAN key cursor [MATCH pattern] [COUNT n]`
+
+* Like `SCAN`, but iterates fields of a hash.
+
+**Protocol:**
+
+```
+*3
+$5
+HSCAN
+$3
+myh
+$1
+0
+```
+
+**Reply:**
+
+```
+*2
+$1
+0
+*4
+$5
+field
+$5
+value
+$5
+age
+$2
+42
+```
+
+(Array of alternating field/value pairs)
+
+---
+
+### `SSCAN key cursor [MATCH pattern] [COUNT n]`
+
+* Iterates members of a set.
+
+Protocol and reply structure same as SCAN.
+
+---
+
+### `ZSCAN key cursor [MATCH pattern] [COUNT n]`
+
+* Iterates members of a sorted set with scores.
+* Returns alternating `member`, `score`.
+
+---
+
+# Quick Comparison
+
+| Command  | Purpose                       | Return Type           |
+| -------- | ----------------------------- | --------------------- |
+| `SET`    | Store a string value          | Simple string `+OK`   |
+| `GET`    | Retrieve a string value       | Bulk string / nil     |
+| `DEL`    | Delete keys                   | Integer (count)       |
+| `EXISTS` | Check existence               | Integer (count)       |
+| `KEYS`   | List all matching keys (slow) | Array of bulk strings |
+| `SCAN`   | Iterate over keys (safe)      | `[cursor, array]`     |
+| `HSCAN`  | Iterate over hash fields      | `[cursor, array]`     |
+| `SSCAN`  | Iterate over set members      | `[cursor, array]`     |
+| `ZSCAN`  | Iterate over sorted set       | `[cursor, array]`     |
+
+##