zilmate 1.8.0 → 1.8.5

package/.agents/skills/upstash-redis-js/data-structures/lists.md

@@ -0,0 +1,72 @@
+# Lists
+
+## Overview
+
+Lists are ordered collections of strings. They support operations at both ends (head and tail) with O(1) time complexity.
+
+## Good For
+
+- Activity feeds (latest posts, news)
+- Job queues
+- Recent items (last 100 searches)
+- Stack or queue implementations
+
+## Limitations
+
+- Maximum length: 2^32 - 1 (4.2 billion) elements
+- Accessing elements by index is O(N) for large lists
+- No built-in deduplication (use sets for unique values)
+
+## Examples
+
+```typescript
+import { Redis } from "@upstash/redis";
+
+const redis = Redis.fromEnv();
+
+// Push to left (head) of list
+await redis.lpush("tasks", "task1");
+await redis.lpush("tasks", "task2", "task3"); // ["task3", "task2", "task1"]
+
+// Push to right (tail) of list
+await redis.rpush("tasks", "task4"); // ["task3", "task2", "task1", "task4"]
+
+// Get list length
+const length = await redis.llen("tasks"); // 4
+
+// Get range of elements (0-based index, inclusive)
+const allTasks = await redis.lrange("tasks", 0, -1); // All elements
+const firstTwo = await redis.lrange("tasks", 0, 1); // ["task3", "task2"]
+
+// Get element by index
+const first = await redis.lindex("tasks", 0); // "task3"
+const last = await redis.lindex("tasks", -1); // "task4"
+
+// Set element at index
+await redis.lset("tasks", 0, "updated-task");
+
+// Pop from left (head)
+const leftItem = await redis.lpop("tasks"); // "updated-task"
+
+// Pop from right (tail)
+const rightItem = await redis.rpop("tasks"); // "task4"
+
+// Pop multiple elements from left
+await redis.lpush("numbers", 1, 2, 3, 4, 5);
+const twoItems = await redis.lpop("numbers", 2); // [5, 4]
+
+// Trim list to specified range (keep only indices 0 to 2)
+await redis.ltrim("tasks", 0, 2);
+
+// Remove elements by value
+await redis.rpush("items", "a", "b", "c", "b", "d");
+await redis.lrem("items", 2, "b"); // Remove first 2 occurrences of "b" from left
+// Use negative count to remove from right, 0 to remove all
+
+// Insert before or after a pivot element
+await redis.linsert("items", "BEFORE", "c", "x"); // Insert "x" before "c"
+await redis.linsert("items", "AFTER", "c", "y"); // Insert "y" after "c"
+
+// Delete entire list
+await redis.del("tasks");
+```

package/.agents/skills/upstash-redis-js/data-structures/sets.md

@@ -0,0 +1,90 @@
+# Sets
+
+## Overview
+
+Sets are unordered collections of unique strings. They provide fast membership testing and set operations (union, intersection, difference).
+
+## Good For
+
+- Unique item tracking (unique visitors, tags)
+- Deduplication
+- Membership testing
+- Set operations (finding common elements between sets)
+
+## Limitations
+
+- Maximum members: 2^32 - 1 (4.2 billion) per set
+- Unordered (no guaranteed iteration order)
+- Members must be unique (duplicates are automatically ignored)
+
+## Examples
+
+```typescript
+import { Redis } from "@upstash/redis";
+
+const redis = Redis.fromEnv();
+
+// Add members to set (duplicates are ignored)
+await redis.sadd("tags", "javascript", "redis", "typescript");
+await redis.sadd("tags", "javascript"); // Ignored, already exists
+
+// Get all members
+const allTags = await redis.smembers("tags"); // ["javascript", "redis", "typescript"]
+
+// Check if member exists
+const hasRedis = await redis.sismember("tags", "redis"); // 1 if exists, 0 if not
+
+// Check multiple members at once
+const exists = await redis.smismember("tags", ["redis", "python", "typescript"]);
+// [1, 0, 1] - redis exists, python doesn't, typescript exists
+
+// Get number of members
+const count = await redis.scard("tags"); // 3
+
+// Remove members
+await redis.srem("tags", "typescript");
+await redis.srem("tags", "javascript", "redis"); // Remove multiple
+
+// Pop random member (removes and returns)
+await redis.sadd("items", "a", "b", "c", "d");
+const random = await redis.spop("items"); // Removes and returns random member
+const twoRandom = await redis.spop("items", 2); // Remove and return 2 random members
+
+// Get random member without removing
+const randomItem = await redis.srandmember("items");
+const threeRandom = await redis.srandmember("items", 3);
+
+// Set operations with multiple sets
+await redis.sadd("set1", "a", "b", "c");
+await redis.sadd("set2", "b", "c", "d");
+await redis.sadd("set3", "c", "d", "e");
+
+// Intersection (common elements)
+const common = await redis.sinter("set1", "set2"); // ["b", "c"]
+const commonAll = await redis.sinter("set1", "set2", "set3"); // ["c"]
+
+// Count the intersection without returning members
+const commonCount = await redis.sintercard(["set1", "set2"]); // 2
+
+// Store intersection result in new set
+await redis.sinterstore("result", "set1", "set2");
+
+// Union (all unique elements from all sets)
+const union = await redis.sunion("set1", "set2"); // ["a", "b", "c", "d"]
+
+// Store union result
+await redis.sunionstore("result", "set1", "set2");
+
+// Difference (elements in first set but not in others)
+const diff = await redis.sdiff("set1", "set2"); // ["a"]
+const diff2 = await redis.sdiff("set2", "set1"); // ["d"]
+
+// Store difference result
+await redis.sdiffstore("result", "set1", "set2");
+
+// Move member from one set to another
+await redis.smove("set1", "set2", "a"); // Move "a" from set1 to set2
+
+// Delete entire set
+await redis.del("tags");
+```

package/.agents/skills/upstash-redis-js/data-structures/sorted-sets.md

@@ -0,0 +1,126 @@
+# Sorted Sets
+
+## Overview
+
+Sorted sets store unique members with associated scores. Members are automatically ordered by score, enabling range queries and rankings.
+
+## Good For
+
+- Leaderboards and rankings
+- Priority queues
+- Time-series data (using timestamp as score)
+- Trending content (using engagement score)
+
+## Limitations
+
+- Maximum members: 2^32 - 1 (4.2 billion) per sorted set
+- Scores are 64-bit floating point numbers
+- Members must be unique (updating a member replaces its score)
+
+## Examples
+
+```typescript
+import { Redis } from "@upstash/redis";
+
+const redis = Redis.fromEnv();
+
+// Add members with scores
+await redis.zadd("leaderboard", { score: 100, member: "player1" });
+await redis.zadd(
+  "leaderboard",
+  { score: 250, member: "player2" },
+  { score: 150, member: "player3" }
+);
+
+// Update score (replaces if member exists)
+await redis.zadd("leaderboard", { score: 300, member: "player1" });
+
+// Increment score
+await redis.zincrby("leaderboard", 50, "player3"); // player3 now has 200
+
+// Get number of members
+const count = await redis.zcard("leaderboard"); // 3
+
+// Get score of a member
+const score = await redis.zscore("leaderboard", "player1"); // 300
+
+// Get rank (position) of member (0-based, lowest score = rank 0)
+const rank = await redis.zrank("leaderboard", "player3"); // 0 (lowest score)
+
+// Get reverse rank (highest score = rank 0)
+const revRank = await redis.zrevrank("leaderboard", "player1"); // 0 (highest score)
+
+// Get range by rank (ascending order)
+const bottom2 = await redis.zrange("leaderboard", 0, 1);
+// ["player3", "player2"] - without scores
+
+// Get range with scores
+const bottom2WithScores = await redis.zrange("leaderboard", 0, 1, { withScores: true });
+// [{ member: "player3", score: 200 }, { member: "player2", score: 250 }]
+
+// Get range in descending order (highest scores first)
+const top2 = await redis.zrange("leaderboard", 0, 1, { rev: true });
+// ["player1", "player2"]
+
+const top2WithScores = await redis.zrange("leaderboard", 0, 1, { withScores: true, rev: true });
+// [{ member: "player1", score: 300 }, { member: "player2", score: 250 }]
+
+// Get all members
+const all = await redis.zrange("leaderboard", 0, -1);
+
+// Get range by score
+const midRange = await redis.zrange("leaderboard", 150, 250, { byScore: true });
+// ["player3", "player2"]
+
+// Get range by score (descending)
+const midRangeDesc = await redis.zrange("leaderboard", 250, 150, { rev: true, byScore: true });
+// ["player2", "player3"]
+
+// Count members in score range
+const countInRange = await redis.zcount("leaderboard", 100, 250); // 2
+
+// Remove members
+await redis.zrem("leaderboard", "player2");
+await redis.zrem("leaderboard", "player1", "player3"); // Remove multiple
+
+// Remove by rank range
+await redis.zadd(
+  "scores",
+  { score: 1, member: "a" },
+  { score: 2, member: "b" },
+  { score: 3, member: "c" }
+);
+await redis.zremrangebyrank("scores", 0, 0); // Remove lowest score (rank 0)
+
+// Remove by score range
+await redis.zremrangebyscore("scores", 2, 3); // Remove members with scores 2-3
+
+// Pop members (remove and return)
+await redis.zadd("items", { score: 1, member: "a" }, { score: 2, member: "b" });
+const lowest = await redis.zpopmin("items"); // Remove and return lowest score
+const highest = await redis.zpopmax("items"); // Remove and return highest score
+
+// Pop multiple members
+await redis.zadd(
+  "items",
+  { score: 1, member: "a" },
+  { score: 2, member: "b" },
+  { score: 3, member: "c" }
+);
+const twoLowest = await redis.zpopmin("items", 2); // Remove 2 lowest
+
+// Practical example: Time-series data
+const now = Date.now();
+await redis.zadd(
+  "events",
+  { score: now - 3600000, member: "event1" }, // 1 hour ago
+  { score: now - 1800000, member: "event2" }, // 30 min ago
+  { score: now, member: "event3" } // now
+);
+
+// Get events from last hour
+const lastHour = await redis.zrange("events", now - 3600000, now, { byScore: true });
+
+// Delete entire sorted set
+await redis.del("leaderboard");
+```

package/.agents/skills/upstash-redis-js/data-structures/streams.md

@@ -0,0 +1,196 @@
+# Streams
+
+## Overview
+
+Streams are append-only logs of entries with unique IDs. They support consumer groups for distributed processing and delivery guarantees.
+
+## Good For
+
+- Event sourcing
+- Activity logs
+- Message queues with multiple consumers
+- Real-time data feeds
+- Chat systems
+
+## Limitations
+
+- Entries cannot be modified after insertion
+- Memory grows unbounded unless trimmed
+- Maximum stream length: practical limits based on memory
+
+## Examples
+
+```typescript
+import { Redis } from "@upstash/redis";
+
+const redis = Redis.fromEnv();
+
+// Add entry to stream (auto-generated ID)
+const id1 = await redis.xadd("events", "*", {
+  type: "user.login",
+  userId: "123",
+  timestamp: Date.now(),
+});
+// Returns ID like "1642424242424-0"
+
+// Add with specific ID (timestamp-sequence format)
+const id2 = await redis.xadd("events", "1642424242424-1", {
+  type: "user.logout",
+  userId: "123",
+});
+
+// Add with trim (limit stream size)
+await redis.xadd(
+  "events",
+  "*",
+  { event: "test" },
+  {
+    trim: {
+      type: "MAXLEN",
+      comparison: "=",
+      threshold: 1000,
+    },
+  }
+);
+
+// Add with approximate trim (more efficient)
+await redis.xadd(
+  "events",
+  "*",
+  { event: "test" },
+  {
+    trim: {
+      type: "MAXLEN",
+      comparison: "~",
+      threshold: 1000,
+    },
+  }
+);
+
+// Get stream length
+const length = await redis.xlen("events");
+
+// Read entries from stream
+const entries = await redis.xread("events", "0", { count: 10 });
+// Returns: [{ name: "events", messages: [{ id: "...", message: {...} }] }]
+
+// Read latest entries
+const latest = await redis.xread("events", "$"); // $ means new entries only
+
+// Read from multiple streams
+const multi = await redis.xread(["stream1", "stream2"], ["0", "0"]);
+
+// Note: Blocking (BLOCK option) is not yet supported in Upstash Redis
+
+// Get range of entries by ID
+const range = await redis.xrange("events", "-", "+"); // All entries
+const specific = await redis.xrange("events", "1642424242424-0", "1642424242424-1");
+const last10 = await redis.xrevrange("events", "+", "-", 10); // Last 10 in reverse
+
+// Create consumer group
+await redis.xgroup("events", {
+  type: "CREATE",
+  group: "processors",
+  id: "0",
+  options: { MKSTREAM: true },
+});
+// Creates group "processors" starting from beginning
+
+// Read as consumer group member
+const groupEntries = await redis.xreadgroup(
+  "processors", // group name
+  "consumer1", // consumer name
+  "events", // stream key
+  ">", // > means undelivered messages
+  { count: 5 }
+);
+
+// Acknowledge processed messages
+if (groupEntries && groupEntries[0]) {
+  const messages = (groupEntries[0] as any)[1] as Array<{ 0: string; 1: any }>;
+  if (messages && messages.length > 0) {
+    const messageIds = messages.map((m) => m[0]);
+    await redis.xack("events", "processors", messageIds);
+  }
+}
+
+// Get pending messages (delivered but not acknowledged)
+const pending = await redis.xpending("events", "processors", "-", "+", 10);
+// Returns pending entry details
+
+// Get detailed pending info for specific consumer
+const pendingDetails = await redis.xpending(
+  "events", // stream key
+  "processors", // group
+  "-", // start
+  "_+", // end
+  10, // count
+  { consumer: "consumer1" } // optional: specific consumer
+);
+
+// Claim pending messages (take over from another consumer)
+const claimed = await redis.xclaim(
+  "events", // stream key
+  "processors", // group
+  "consumer2", // new owner (consumer)
+  3600000, // min idle time (ms)
+  "1642424242424-0" // message ID(s) to claim
+);
+
+// Delete messages
+await redis.xdel("events", [id1, id2]);
+
+// Trim stream to maximum length
+await redis.xtrim("events", { strategy: "MAXLEN", threshold: 1000, exactness: "=" });
+await redis.xtrim("events", { strategy: "MAXLEN", threshold: 1000, exactness: "~" }); // Approximate (more efficient)
+
+// Get consumer group info
+const groups = await redis.xinfo("events", { type: "GROUPS" });
+// Returns list of consumer groups
+
+// Get consumers in group
+const consumers = await redis.xinfo("events", { type: "CONSUMERS", group: "processors" });
+// Returns list of consumers and their stats
+
+// Delete consumer from group
+await redis.xgroup("events", {
+  type: "DELCONSUMER",
+  group: "processors",
+  consumer: "consumer1",
+});
+
+// Delete consumer group
+await redis.xgroup("events", { type: "DESTROY", group: "processors" });
+
+// Practical example: Event log with processing
+await redis.xadd("orders", "*", {
+  orderId: "order-123",
+  status: "pending",
+  amount: 99.99,
+});
+
+// Create processor group
+await redis.xgroup("orders", {
+  type: "CREATE",
+  group: "order-processors",
+  id: "0",
+  options: { MKSTREAM: true },
+});
+
+// Worker reads and processes
+const orders = await redis.xreadgroup("order-processors", "worker-1", "orders", ">", {
+  count: 1,
+});
+
+if (orders && orders[0]) {
+  const messages = (orders[0] as any)[1] as Array<{ 0: string; 1: any }>;
+  if (messages && messages.length > 0) {
+    const order = messages[0];
+    // Process order...
+    console.log("Processing:", order[1]);
+
+    // Acknowledge when done
+    await redis.xack("orders", "order-processors", order[0]);
+  }
+}
+```

package/.agents/skills/upstash-redis-js/data-structures/strings.md

@@ -0,0 +1,73 @@
+# Strings
+
+## Overview
+
+Strings are the most basic Redis data structure. They store a single value and support atomic operations like increment/decrement.
+
+## Good For
+
+- Caching simple values (strings, numbers, booleans, objects)
+- Counters (page views, likes, inventory)
+- Feature flags
+- Session tokens
+
+## Limitations
+
+- Maximum value size: 512 MB
+- No built-in list or set operations on a single key
+- Increment/decrement only work on values that can be parsed as integers
+
+## Examples
+
+```typescript
+import { Redis } from "@upstash/redis";
+
+const redis = Redis.fromEnv();
+
+// Set and get strings
+await redis.set("greeting", "Hello World");
+const greeting = await redis.get("greeting"); // "Hello World"
+
+// Set and get numbers (automatic serialization)
+await redis.set("views", 100);
+const views = await redis.get("views"); // 100 (as number, not string)
+
+// Set and get objects (automatic JSON serialization)
+await redis.set("user", { name: "Alice", age: 30 });
+const user = await redis.get("user"); // { name: "Alice", age: 30 }
+
+// Set with expiration (TTL in seconds)
+await redis.setex("session", 3600, { userId: "123" });
+
+// Set only if key doesn't exist
+await redis.setnx("lock", "process-1"); // Returns 1 if set, 0 if already exists
+
+// Increment and decrement counters
+await redis.incr("views"); // 101
+await redis.decr("views"); // 100
+await redis.incrby("views", 10); // 110
+await redis.decrby("views", 5); // 105
+
+// Append to string
+await redis.set("name", "Alice");
+await redis.append("name", " Smith"); // "Alice Smith"
+
+// Get and set atomically
+const oldValue = await redis.getset("counter", 0);
+
+// Multiple get/set (batch operations)
+await redis.mset({ key1: "value1", key2: "value2", key3: 123 });
+const values = await redis.mget("key1", "key2", "key3"); // ["value1", "value2", 123]
+
+// Check if key exists
+const exists = await redis.exists("greeting"); // 1 if exists, 0 if not
+
+// Delete key
+await redis.del("greeting");
+
+// Get TTL (time to live in seconds)
+await redis.ttl("session"); // seconds remaining, -1 if no expiry, -2 if doesn't exist
+
+// Set expiration on existing key
+await redis.expire("key1", 60); // expires in 60 seconds
+```