zilmate 1.8.1 → 1.8.5

package/.agents/skills/upstash-redis-js/patterns/rate-limiting.md

@@ -0,0 +1,187 @@
+# Rate Limiting
+
+## Overview
+
+Control request rates to prevent abuse and ensure fair resource usage. Use counters with TTL for simple rate limiting, or @upstash/ratelimit for production.
+
+## Good For
+
+- API rate limiting (requests per user/IP)
+- Preventing brute force attacks
+- Throttling expensive operations
+- Fair resource allocation
+
+## Limitations
+
+- Simple counters can be imprecise at window boundaries
+- Distributed rate limiting requires careful coordination
+- Use @upstash/ratelimit for production (supports multiple algorithms)
+
+## Examples
+
+```typescript
+import { Redis } from "@upstash/redis";
+
+const redis = Redis.fromEnv();
+
+// Simple fixed-window rate limiter
+async function simpleRateLimit(userId: string, limit: number = 10, window: number = 60) {
+  const key = `ratelimit:${userId}`;
+
+  const count = await redis.incr(key);
+
+  if (count === 1) {
+    await redis.expire(key, window);
+  }
+
+  return {
+    allowed: count <= limit,
+    remaining: Math.max(0, limit - count),
+    reset: window,
+  };
+}
+
+// Usage
+const result = await simpleRateLimit("user:123", 10, 60);
+
+if (!result.allowed) {
+  throw new Error("Rate limit exceeded");
+}
+
+// Sliding window rate limiter using sorted set
+async function slidingWindowRateLimit(userId: string, limit: number = 10, window: number = 60) {
+  const key = `ratelimit:sliding:${userId}`;
+  const now = Date.now();
+  const windowStart = now - window * 1000;
+
+  // Remove old entries
+  await redis.zremrangebyscore(key, 0, windowStart);
+
+  // Count requests in window
+  const count = await redis.zcard(key);
+
+  if (count >= limit) {
+    return { allowed: false, remaining: 0 };
+  }
+
+  // Add current request
+  await redis.zadd(key, { score: now, member: `${now}:${Math.random()}` });
+  await redis.expire(key, window * 2); // Cleanup
+
+  return {
+    allowed: true,
+    remaining: limit - count - 1,
+  };
+}
+
+// Token bucket using Lua script
+const tokenBucketScript = `
+  local key = KEYS[1]
+  local capacity = tonumber(ARGV[1])
+  local rate = tonumber(ARGV[2])
+  local now = tonumber(ARGV[3])
+  
+  local bucket = redis.call('HMGET', key, 'tokens', 'last_refill')
+  local tokens = tonumber(bucket[1] or capacity)
+  local last_refill = tonumber(bucket[2] or now)
+  
+  -- Refill tokens based on time elapsed
+  local elapsed = now - last_refill
+  local refill = math.floor(elapsed * rate)
+  tokens = math.min(capacity, tokens + refill)
+  
+  if tokens >= 1 then
+    tokens = tokens - 1
+    redis.call('HMSET', key, 'tokens', tokens, 'last_refill', now)
+    redis.call('EXPIRE', key, 3600)
+    return 1
+  else
+    return 0
+  end
+`;
+
+async function tokenBucketRateLimit(userId: string, capacity: number = 10, rate: number = 1) {
+  const key = `ratelimit:bucket:${userId}`;
+  const now = Date.now() / 1000;
+
+  const allowed = await redis.eval<number>(tokenBucketScript, [key], [capacity, rate, now]);
+
+  return { allowed: allowed === 1 };
+}
+
+// Production: Use @upstash/ratelimit
+// npm install @upstash/ratelimit
+import { Ratelimit } from "@upstash/ratelimit";
+
+// Fixed window
+const fixedWindowLimiter = new Ratelimit({
+  redis,
+  limiter: Ratelimit.fixedWindow(10, "60 s"),
+});
+
+// Sliding window
+const slidingWindowLimiter = new Ratelimit({
+  redis,
+  limiter: Ratelimit.slidingWindow(10, "60 s"),
+});
+
+// Token bucket
+const tokenBucketLimiter = new Ratelimit({
+  redis,
+  limiter: Ratelimit.tokenBucket(10, "1 s", 10),
+});
+
+// Usage
+async function handleRequest(userId: string) {
+  const { success, limit, remaining, reset } = await fixedWindowLimiter.limit(userId);
+
+  if (!success) {
+    return {
+      error: "Rate limit exceeded",
+      limit,
+      remaining,
+      reset,
+    };
+  }
+
+  // Process request
+  return { data: "Success", remaining };
+}
+
+// Multi-tier rate limiting
+async function multiTierRateLimit(userId: string, tier: "free" | "pro") {
+  const limits = {
+    free: { requests: 100, window: 3600 },
+    pro: { requests: 1000, window: 3600 },
+  };
+
+  const config = limits[tier];
+  return await simpleRateLimit(userId, config.requests, config.window);
+}
+
+// Per-endpoint rate limiting
+async function endpointRateLimit(userId: string, endpoint: string) {
+  const key = `${userId}:${endpoint}`;
+  return await simpleRateLimit(key, 10, 60);
+}
+
+// IP-based rate limiting
+async function ipRateLimit(ip: string) {
+  return await simpleRateLimit(`ip:${ip}`, 100, 60);
+}
+
+// Combined rate limiting (both user and IP)
+async function combinedRateLimit(userId: string, ip: string) {
+  const [userLimit, ipLimit] = await Promise.all([
+    simpleRateLimit(`user:${userId}`, 100, 60),
+    simpleRateLimit(`ip:${ip}`, 1000, 60),
+  ]);
+
+  return {
+    allowed: userLimit.allowed && ipLimit.allowed,
+    limits: { user: userLimit, ip: ipLimit },
+  };
+}
+```
+
+**Recommendation**: For production, use `@upstash/ratelimit` which provides battle-tested algorithms, analytics, and better accuracy.

package/.agents/skills/upstash-redis-js/patterns/session-management.md

@@ -0,0 +1,217 @@
+# Session Management
+
+## Overview
+
+Store user sessions in Redis with automatic serialization and TTL-based expiration. Sessions contain user state, authentication data, and preferences.
+
+## Good For
+
+- User authentication sessions
+- Shopping carts
+- Temporary user state
+- Multi-page form data
+- "Remember me" tokens
+
+## Limitations
+
+- Sessions expire after TTL (must be renewed)
+- Large session objects consume memory
+- Shared sessions require coordination across devices
+
+## Examples
+
+```typescript
+import { Redis } from "@upstash/redis";
+
+const redis = Redis.fromEnv();
+
+// Create session with 1-hour expiration
+async function createSession(userId: string, userData: any) {
+  const sessionId = crypto.randomUUID();
+
+  await redis.set(
+    `session:${sessionId}`,
+    {
+      userId,
+      ...userData,
+      createdAt: Date.now(),
+    },
+    { ex: 3600 } // 1 hour TTL
+  );
+
+  return sessionId;
+}
+
+// Get session
+async function getSession(sessionId: string) {
+  const session = await redis.get<any>(`session:${sessionId}`);
+  return session;
+}
+
+// Update session and refresh TTL
+async function updateSession(sessionId: string, updates: any) {
+  const current = await redis.get<any>(`session:${sessionId}`);
+
+  if (!current) {
+    throw new Error("Session not found");
+  }
+
+  await redis.set(
+    `session:${sessionId}`,
+    { ...current, ...updates, updatedAt: Date.now() },
+    { ex: 3600 } // Reset TTL
+  );
+}
+
+// Extend session (refresh TTL without updating data)
+async function extendSession(sessionId: string) {
+  await redis.expire(`session:${sessionId}`, 3600);
+}
+
+// Delete session (logout)
+async function deleteSession(sessionId: string) {
+  await redis.del(`session:${sessionId}`);
+}
+
+// User login flow
+async function login(email: string, password: string) {
+  // Verify credentials (not shown)
+  const user = await verifyCredentials(email, password);
+
+  if (!user) {
+    throw new Error("Invalid credentials");
+  }
+
+  // Create session
+  const sessionId = await createSession(user.id, {
+    email: user.email,
+    name: user.name,
+    role: user.role,
+  });
+
+  return sessionId;
+}
+
+// User logout
+async function logout(sessionId: string) {
+  await deleteSession(sessionId);
+}
+
+// Session with sliding expiration (extends on each access)
+async function getSessionWithSliding(sessionId: string) {
+  const session = await redis.get<any>(`session:${sessionId}`);
+
+  if (session) {
+    // Extend session on access
+    await redis.expire(`session:${sessionId}`, 3600);
+  }
+
+  return session;
+}
+
+// Shopping cart session
+async function addToCartSession(sessionId: string, item: any) {
+  const key = `cart:${sessionId}`;
+
+  const cart = (await redis.get<any[]>(key)) || [];
+  cart.push(item);
+
+  await redis.set(key, cart, { ex: 86400 }); // 24 hour cart
+
+  return cart;
+}
+
+// Multi-device sessions (track all user sessions)
+async function createMultiDeviceSession(userId: string, deviceInfo: any) {
+  const sessionId = crypto.randomUUID();
+
+  // Store session
+  await redis.set(
+    `session:${sessionId}`,
+    { userId, ...deviceInfo, createdAt: Date.now() },
+    { ex: 3600 }
+  );
+
+  // Track in user's session list
+  await redis.sadd(`user:${userId}:sessions`, sessionId);
+
+  return sessionId;
+}
+
+// Logout from all devices
+async function logoutAllDevices(userId: string) {
+  const sessions = await redis.smembers(`user:${userId}:sessions`);
+
+  // Delete all sessions
+  const pipeline = redis.pipeline();
+  sessions.forEach((sessionId) => {
+    pipeline.del(`session:${sessionId}`);
+  });
+  pipeline.del(`user:${userId}:sessions`);
+
+  await pipeline.exec();
+}
+
+// "Remember me" token (long-lived)
+async function createRememberMeToken(userId: string) {
+  const token = crypto.randomUUID();
+
+  await redis.set(
+    `remember:${token}`,
+    { userId, createdAt: Date.now() },
+    { ex: 2592000 } // 30 days
+  );
+
+  return token;
+}
+
+async function loginWithRememberMe(token: string) {
+  const data = await redis.get<any>(`remember:${token}`);
+
+  if (!data) {
+    return null;
+  }
+
+  // Create new session
+  const sessionId = await createSession(data.userId, {});
+
+  return sessionId;
+}
+
+// Session with user activity tracking
+async function trackActivity(sessionId: string, action: string) {
+  const session = await redis.get<any>(`session:${sessionId}`);
+
+  if (!session) return;
+
+  session.lastActivity = {
+    action,
+    timestamp: Date.now(),
+  };
+
+  await redis.set(`session:${sessionId}`, session, { ex: 3600 });
+}
+
+// Clean up expired sessions manually (if needed)
+async function cleanupExpiredSessions(userId: string) {
+  const sessions = await redis.smembers(`user:${userId}:sessions`);
+
+  const pipeline = redis.pipeline();
+  sessions.forEach((sessionId) => {
+    pipeline.exists(`session:${sessionId}`);
+  });
+
+  const results = await pipeline.exec();
+
+  // Remove invalid sessions from set
+  const invalid = sessions.filter((_, i) => results[i] === 0);
+  if (invalid.length > 0) {
+    await redis.srem(`user:${userId}:sessions`, ...invalid);
+  }
+}
+
+// Helper placeholder
+async function verifyCredentials(email: string, password: string) {
+  return { id: "123", email, name: "User", role: "user" };
+}
+```

package/.agents/skills/upstash-redis-js/performance/batching-operations.md

@@ -0,0 +1,76 @@
+# Batching Operations
+
+## Overview
+
+Batch multiple Redis operations into single commands to reduce network round trips. Use MGET/MSET for strings, HMGET/HMSET for hashes, pipelines for mixed operations.
+
+## Good For
+
+- Fetching multiple keys at once
+- Bulk data loading
+- Reducing latency in high-latency networks
+- Operations on related data
+
+## Limitations
+
+- Batch operations are atomic per command, not across commands
+- Some commands don't have batch equivalents
+
+## Examples
+
+```typescript
+import { Redis } from "@upstash/redis";
+
+const redis = Redis.fromEnv();
+
+// MGET - batch get multiple keys
+const [user1, user2, user3] = await redis.mget<any[]>("user:1", "user:2", "user:3");
+
+// MSET - batch set multiple keys
+await redis.mset({
+  "user:1": { name: "Alice", age: 30 },
+  "user:2": { name: "Bob", age: 25 },
+  "user:3": { name: "Charlie", age: 35 },
+});
+
+// Compare: individual operations (3 round trips)
+const u1 = await redis.get("user:1");
+const u2 = await redis.get("user:2");
+const u3 = await redis.get("user:3");
+
+// vs batch operation (1 round trip)
+const users = await redis.mget("user:1", "user:2", "user:3");
+
+// HMGET - batch get hash fields
+const [name, email] = await redis.hmget("user:123", "name", "email");
+
+// HMSET - batch set hash fields
+await redis.hset("user:123", {
+  name: "Alice",
+  email: "alice@example.com",
+  age: 30,
+});
+
+// Batch with mixed operations - use pipeline
+const pipeline = redis.pipeline();
+userIds.forEach((id) => {
+  pipeline.get(`user:${id}`);
+  pipeline.hgetall(`user:${id}:profile`);
+  pipeline.zrank("leaderboard", id);
+});
+const results = await pipeline.exec();
+
+// Batch delete
+await redis.del("key1", "key2", "key3", "key4");
+
+// Batch SADD
+await redis.sadd("tags", "redis", "nodejs", "typescript", "upstash");
+
+// Batch with Promise.all (for independent operations)
+const [userCount, postCount, commentCount] = await Promise.all([
+  redis.get("count:users"),
+  redis.get("count:posts"),
+  redis.get("count:comments"),
+]);
+// Note: With auto-pipelining enabled, these batch automatically
+```

package/.agents/skills/upstash-redis-js/performance/data-serialization.md

@@ -0,0 +1,134 @@
+# Data Serialization and Deserialization
+
+## Overview
+
+Automatic serialization preserves JavaScript types across Redis operations. Numbers stay numbers, objects stay objects, arrays stay arrays.
+
+## Good For
+
+- Storing any JavaScript value without JSON.stringify/parse
+- Type preservation across GET/SET
+- Cleaner code (no manual serialization)
+- Storing numbers, booleans, objects, arrays, null
+
+## Limitations
+
+- undefined, functions, symbols cannot be serialized
+- Date objects serialize as ISO strings
+- Class instances lose their prototype
+- Map and Set serialize to `{}` (their contents are lost) — convert to a plain object/array first
+- Binary data requires special handling
+
+## Examples
+
+### Basic Type Preservation
+
+```typescript
+import { Redis } from "@upstash/redis";
+
+const redis = Redis.fromEnv();
+
+// Numbers preserved
+await redis.set("age", 42);
+const age = await redis.get("age");
+console.log(typeof age); // "number"
+console.log(age === 42); // true
+
+// Compare with other SDKs
+// ioredis: returns "42" (string)
+// @upstash/redis: returns 42 (number)
+
+// Booleans preserved
+await redis.set("active", true);
+const active = await redis.get("active");
+console.log(typeof active); // "boolean"
+
+// Objects preserved
+await redis.set("user", { name: "Alice", age: 30 });
+const user = await redis.get("user");
+console.log(user.name); // "Alice"
+console.log(user.age); // 30 (number, not string)
+
+// Arrays preserved
+await redis.set("scores", [100, 200, 300]);
+const scores = await redis.get<number[]>("scores");
+console.log(scores[0]); // 100 (number)
+
+// Nested structures preserved
+await redis.set("data", {
+  user: { name: "Alice", age: 30 },
+  scores: [100, 200, 300],
+  active: true,
+  count: 42,
+});
+
+const data = await redis.get<any>("data");
+console.log(typeof age); // "number"
+console.log(Array.isArray(data.scores)); // true
+```
+
+### Complex Types
+
+```typescript
+import { Redis } from "@upstash/redis";
+
+const redis = Redis.fromEnv();
+
+// Date objects become ISO strings
+await redis.set("created", new Date());
+const created = await redis.get<string>("created");
+console.log(typeof created); // "string"
+console.log(created); // "2024-01-01T00:00:00.000Z"
+
+// Convert back to Date
+const createdDate = new Date(created);
+
+// Class instances lose prototype
+class User {
+  constructor(public name: string) {}
+  greet() {
+    return `Hello, ${this.name}`;
+  }
+}
+
+const alice = new User("Alice");
+await redis.set("instance", alice);
+
+const retrieved = await redis.get<any>("instance");
+console.log(retrieved.name); // "Alice"
+console.log(retrieved.greet); // undefined (method lost)
+
+// Solution: serialize/deserialize manually
+class SerializableUser {
+  constructor(public name: string) {}
+
+  static toRedis(user: SerializableUser) {
+    return { name: user.name };
+  }
+
+  static fromRedis(data: any) {
+    return new SerializableUser(data.name);
+  }
+}
+
+await redis.set("ser_user", SerializableUser.toRedis(alice));
+const serRetrieved = SerializableUser.fromRedis(await redis.get("ser_user"));
+```
+
+### Disabling Auto-Serialization
+
+```typescript
+import { Redis } from "@upstash/redis";
+
+// Disable auto-serialization if needed
+const redis = new Redis({
+  url: process.env.UPSTASH_REDIS_REST_URL!,
+  token: process.env.UPSTASH_REDIS_REST_TOKEN!,
+  automaticDeserialization: false,
+});
+
+await redis.set("key", JSON.stringify({ value: 42 }));
+const raw = await redis.get("key");
+console.log(typeof raw); // "string"
+const parsed = JSON.parse(raw as string);
+```