bun-types 1.3.2-canary.20251105T140650 → 1.3.2

package/docs/{api/redis.md → runtime/redis.mdx}

@@ -1,6 +1,13 @@
-Bun provides native bindings for working with Redis databases with a modern, Promise-based API. The interface is designed to be simple and performant, with built-in connection management, fully typed responses, and TLS support. **New in Bun v1.2.9**
+---
+title: Redis
+description: Use Bun's native Redis client with a Promise-based API
+---
 
-```ts
+<Note>Bun's Redis client supports Redis server versions 7.2 and up.</Note>
+
+Bun provides native bindings for working with Redis databases with a modern, Promise-based API. The interface is designed to be simple and performant, with built-in connection management, fully typed responses, and TLS support.
+
+```ts redis.ts icon="/icons/typescript.svg"
 import { redis } from "bun";
 
 // Set a key
@@ -21,11 +28,13 @@ const exists = await redis.exists("greeting");
 await redis.del("greeting");
 ```
 
+---
+
 ## Getting Started
 
 To use the Redis client, you first need to create a connection:
 
-```ts
+```ts redis.ts icon="/icons/typescript.svg"
 import { redis, RedisClient } from "bun";
 
 // Using the default client (reads connection info from environment)
@@ -42,14 +51,13 @@ await client.incr("counter");
 By default, the client reads connection information from the following environment variables (in order of precedence):
 
 - `REDIS_URL`
-- `VALKEY_URL`
 - If not set, defaults to `"redis://localhost:6379"`
 
 ### Connection Lifecycle
 
 The Redis client automatically handles connections in the background:
 
-```ts
+```ts redis.ts icon="/icons/typescript.svg"
 // No connection is made until a command is executed
 const client = new RedisClient();
 
@@ -65,7 +73,7 @@ client.close();
 
 You can also manually control the connection lifecycle:
 
-```ts
+```ts redis.ts icon="/icons/typescript.svg"
 const client = new RedisClient();
 
 // Explicitly connect
@@ -78,11 +86,13 @@ await client.set("key", "value");
 client.close();
 ```
 
+---
+
 ## Basic Operations
 
 ### String Operations
 
-```ts
+```ts redis.ts icon="/icons/typescript.svg"
 // Set a key
 await redis.set("user:1:name", "Alice");
 
@@ -108,7 +118,7 @@ const ttl = await redis.ttl("session:123");
 
 ### Numeric Operations
 
-```ts
+```ts redis.ts icon="/icons/typescript.svg"
 // Set initial value
 await redis.set("counter", "0");
 
@@ -121,16 +131,9 @@ await redis.decr("counter");
 
 ### Hash Operations
 
-```ts
+```ts redis.ts icon="/icons/typescript.svg"
 // Set multiple fields in a hash
-await redis.hmset("user:123", [
-  "name",
-  "Alice",
-  "email",
-  "alice@example.com",
-  "active",
-  "true",
-]);
+await redis.hmset("user:123", ["name", "Alice", "email", "alice@example.com", "active", "true"]);
 
 // Get multiple fields from a hash
 const userFields = await redis.hmget("user:123", ["name", "email"]);
@@ -149,7 +152,7 @@ await redis.hincrbyfloat("user:123", "score", 1.5);
 
 ### Set Operations
 
-```ts
+```ts redis.ts icon="/icons/typescript.svg"
 // Add member to set
 await redis.sadd("tags", "javascript");
 
@@ -169,23 +172,25 @@ const randomTag = await redis.srandmember("tags");
 const poppedTag = await redis.spop("tags");
 ```
 
+---
+
 ## Pub/Sub
 
 Bun provides native bindings for the [Redis
 Pub/Sub](https://redis.io/docs/latest/develop/pubsub/) protocol. **New in Bun
 1.2.23**
 
-{% callout %}
-**🚧** — The Redis Pub/Sub feature is experimental. Although we expect it to be
-stable, we're currently actively looking for feedback and areas for improvement.
-{% /callout %}
+<Warning>
+  The Redis Pub/Sub feature is experimental. Although we expect it to be stable, we're currently actively looking for
+  feedback and areas for improvement.
+</Warning>
 
 ### Basic Usage
 
 To get started publishing messages, you can set up a publisher in
 `publisher.ts`:
 
-```typescript#publisher.ts
+```typescript publisher.ts icon="/icons/typescript.svg"
 import { RedisClient } from "bun";
 
 const writer = new RedisClient("redis://localhost:6739");
@@ -198,7 +203,7 @@ writer.close();
 
 In another file, create the subscriber in `subscriber.ts`:
 
-```typescript#subscriber.ts
+```typescript subscriber.ts icon="/icons/typescript.svg"
 import { RedisClient } from "bun";
 
 const listener = new RedisClient("redis://localhost:6739");
@@ -211,40 +216,40 @@ await listener.subscribe("general", (message, channel) => {
 
 In one shell, run your subscriber:
 
-```bash
+```bash terminal icon="terminal"
 bun run subscriber.ts
 ```
 
 and, in another, run your publisher:
 
-```bash
+```bash terminal icon="terminal"
 bun run publisher.ts
 ```
 
-{% callout %}
-**Note:** The subscription mode takes over the `RedisClient` connection. A
+<Note>
+The subscription mode takes over the `RedisClient` connection. A
 client with subscriptions can only call `RedisClient.prototype.subscribe()`. In
 other words, applications which need to message Redis need a separate
 connection, acquirable through `.duplicate()`:
 
-```typescript
+```ts redis.ts icon="/icons/typescript.svg"
 import { RedisClient } from "bun";
 
 const redis = new RedisClient("redis://localhost:6379");
 await redis.connect();
-const subscriber = await redis.duplicate();
+const subscriber = await redis.duplicate(); // [!code ++]
 
 await subscriber.subscribe("foo", () => {});
 await redis.set("bar", "baz");
 ```
 
-{% /callout %}
+</Note>
 
 ### Publishing
 
 Publishing messages is done through the `publish()` method:
 
-```typescript
+```typescript redis.ts icon="/icons/typescript.svg"
 await client.publish(channelName, message);
 ```
 
@@ -253,13 +258,13 @@ await client.publish(channelName, message);
 The Bun `RedisClient` allows you to subscribe to channels through the
 `.subscribe()` method:
 
-```typescript
+```typescript redis.ts icon="/icons/typescript.svg"
 await client.subscribe(channel, (message, channel) => {});
 ```
 
 You can unsubscribe through the `.unsubscribe()` method:
 
-```typescript
+```typescript redis.ts icon="/icons/typescript.svg"
 await client.unsubscribe(); // Unsubscribe from all channels.
 await client.unsubscribe(channel); // Unsubscribe a particular channel.
 await client.unsubscribe(channel, listener); // Unsubscribe a particular listener.
@@ -271,19 +276,16 @@ await client.unsubscribe(channel, listener); // Unsubscribe a particular listene
 
 The client automatically pipelines commands, improving performance by sending multiple commands in a batch and processing responses as they arrive.
 
-```ts
+```ts redis.ts icon="/icons/typescript.svg"
 // Commands are automatically pipelined by default
-const [infoResult, listResult] = await Promise.all([
-  redis.get("user:1:name"),
-  redis.get("user:2:email"),
-]);
+const [infoResult, listResult] = await Promise.all([redis.get("user:1:name"), redis.get("user:2:email")]);
 ```
 
 To disable automatic pipelining, you can set the `enableAutoPipelining` option to `false`:
 
-```ts
+```ts redis.ts icon="/icons/typescript.svg"
 const client = new RedisClient("redis://localhost:6379", {
-  enableAutoPipelining: false,
+  enableAutoPipelining: false, // [!code ++]
 });
 ```
 
@@ -291,7 +293,7 @@ const client = new RedisClient("redis://localhost:6379", {
 
 When you need to use commands that don't have convenience methods, you can use the `send` method:
 
-```ts
+```ts redis.ts icon="/icons/typescript.svg"
 // Run any Redis command
 const info = await redis.send("INFO", []);
 
@@ -308,7 +310,7 @@ The `send` method allows you to use any Redis command, even ones that don't have
 
 You can register handlers for connection events:
 
-```ts
+```ts redis.ts icon="/icons/typescript.svg"
 const client = new RedisClient();
 
 // Called when successfully connected to Redis server
@@ -328,7 +330,7 @@ client.close();
 
 ### Connection Status and Monitoring
 
-```ts
+```ts redis.ts icon="/icons/typescript.svg"
 // Check if connected
 console.log(client.connected); // boolean indicating connection status
 
@@ -373,11 +375,13 @@ The following commands disable automatic pipelining:
 - `UNSUBSCRIBE`
 - `UNPSUBSCRIBE`
 
+---
+
 ## Connection Options
 
 When creating a client, you can pass various options to configure the connection:
 
-```ts
+```ts redis.ts icon="/icons/typescript.svg"
 const client = new RedisClient("redis://localhost:6379", {
   // Connection timeout in milliseconds (default: 10000)
   connectionTimeout: 5000,
@@ -420,11 +424,13 @@ When a connection is lost, the client automatically attempts to reconnect with e
    - Queued if `enableOfflineQueue` is true (default)
    - Rejected immediately if `enableOfflineQueue` is false
 
+---
+
 ## Supported URL Formats
 
 The Redis client supports various URL formats:
 
-```ts
+```ts redis.ts icon="/icons/typescript.svg"
 // Standard Redis URL
 new RedisClient("redis://localhost:6379");
 new RedisClient("redis://localhost:6379");
@@ -450,11 +456,13 @@ new RedisClient("redis+tls+unix:///path/to/socket");
 new RedisClient("redis+tls+unix:///path/to/socket");
 ```
 
+---
+
 ## Error Handling
 
 The Redis client throws typed errors for different scenarios:
 
-```ts
+```ts redis.ts icon="/icons/typescript.svg"
 try {
   await redis.get("non-existent-key");
 } catch (error) {
@@ -474,11 +482,13 @@ Common error codes:
 - `ERR_REDIS_AUTHENTICATION_FAILED` - Failed to authenticate with the server
 - `ERR_REDIS_INVALID_RESPONSE` - Received an invalid response from the server
 
+---
+
 ## Example Use Cases
 
 ### Caching
 
-```ts
+```ts redis.ts icon="/icons/typescript.svg"
 async function getUserWithCache(userId) {
   const cacheKey = `user:${userId}`;
 
@@ -501,7 +511,7 @@ async function getUserWithCache(userId) {
 
 ### Rate Limiting
 
-```ts
+```ts redis.ts icon="/icons/typescript.svg"
 async function rateLimit(ip, limit = 100, windowSecs = 3600) {
   const key = `ratelimit:${ip}`;
 
@@ -523,20 +533,13 @@ async function rateLimit(ip, limit = 100, windowSecs = 3600) {
 
 ### Session Storage
 
-```ts
+```ts redis.ts icon="/icons/typescript.svg"
 async function createSession(userId, data) {
   const sessionId = crypto.randomUUID();
   const key = `session:${sessionId}`;
 
   // Store session with expiration
-  await redis.hmset(key, [
-    "userId",
-    userId.toString(),
-    "created",
-    Date.now().toString(),
-    "data",
-    JSON.stringify(data),
-  ]);
+  await redis.hmset(key, ["userId", userId.toString(), "created", Date.now().toString(), "data", JSON.stringify(data)]);
   await redis.expire(key, 86400); // 24 hours
 
   return sessionId;
@@ -549,11 +552,7 @@ async function getSession(sessionId) {
   const exists = await redis.exists(key);
   if (!exists) return null;
 
-  const [userId, created, data] = await redis.hmget(key, [
-    "userId",
-    "created",
-    "data",
-  ]);
+  const [userId, created, data] = await redis.hmget(key, ["userId", "created", "data"]);
 
   return {
     userId: Number(userId),
@@ -563,33 +562,19 @@ async function getSession(sessionId) {
 }
 ```
 
+---
+
 ## Implementation Notes
 
 Bun's Redis client is implemented in Zig and uses the Redis Serialization Protocol (RESP3). It manages connections efficiently and provides automatic reconnection with exponential backoff.
 
 The client supports pipelining commands, meaning multiple commands can be sent without waiting for the replies to previous commands. This significantly improves performance when sending multiple commands in succession.
 
-### RESP3 Protocol Support
-
-Bun's Redis client uses the newer RESP3 protocol by default, which provides more data types and features compared to RESP2:
-
-- Better error handling with typed errors
-- Native Boolean responses
-- Map/Dictionary responses (key-value objects)
-- Set responses
-- Double (floating point) values
-- BigNumber support for large integer values
-
-When connecting to Redis servers using older versions that don't support RESP3, the client automatically fallbacks to compatible modes.
-
 ## Limitations and Future Plans
 
 Current limitations of the Redis client we are planning to address in future versions:
 
-- [ ] Transactions (MULTI/EXEC) must be done through raw commands for now
-- [ ] Streams are supported but without dedicated methods
-- [ ] Pub/Sub does not currently support binary data, nor pattern-based
-      subscriptions.
+- Transactions (MULTI/EXEC) must be done through raw commands for now
 
 Unsupported features: