zilmate 1.8.0 → 1.8.5

package/.agents/skills/upstash/upstash-redis-js/performance/error-handling.md

@@ -0,0 +1,118 @@
+# Error Handling
+
+## Overview
+
+Handle Redis errors gracefully with try-catch, implement retry logic for transient failures, and provide fallbacks for degraded operation.
+
+## Good For
+
+- Network failure recovery
+- Timeout handling
+- Graceful degradation
+- Debugging and monitoring
+- Production reliability
+
+## Limitations
+
+- Some errors are not recoverable
+- Retries can increase latency
+- Too many retries may cause cascading failures
+
+## Examples
+
+### Built-in Retry Configuration
+
+```typescript
+import { Redis } from "@upstash/redis";
+
+// Default: 5 retries with exponential backoff
+const redis = Redis.fromEnv();
+
+// Customize retry behavior
+const redisWithRetry = new Redis({
+  url: process.env.UPSTASH_REDIS_REST_URL!,
+  token: process.env.UPSTASH_REDIS_REST_TOKEN!,
+  retry: {
+    retries: 3,
+    backoff: (retryCount) => Math.exp(retryCount) * 50, // Exponential backoff
+  },
+});
+
+// Disable retries
+const redisNoRetry = new Redis({
+  url: process.env.UPSTASH_REDIS_REST_URL!,
+  token: process.env.UPSTASH_REDIS_REST_TOKEN!,
+  retry: false, // No retries
+});
+
+// Custom backoff strategy
+const redisCustomBackoff = new Redis({
+  url: process.env.UPSTASH_REDIS_REST_URL!,
+  token: process.env.UPSTASH_REDIS_REST_TOKEN!,
+  retry: {
+    retries: 10,
+    backoff: (retryCount) => {
+      // Linear backoff: 100ms, 200ms, 300ms...
+      return retryCount * 100;
+    },
+  },
+});
+```
+
+### Request Cancellation with AbortSignal
+
+```typescript
+import { Redis } from "@upstash/redis";
+
+const redis = Redis.fromEnv();
+
+const redisWithTimeout = new Redis({
+  url: process.env.UPSTASH_REDIS_REST_URL!,
+  token: process.env.UPSTASH_REDIS_REST_TOKEN!,
+  signal: () => AbortSignal.timeout(5000), // 5 second timeout per request
+});
+
+try {
+  await redisWithTimeout.get("key");
+} catch (error) {
+  if (error.name === "TimeoutError") {
+    console.error("Request timed out");
+  }
+}
+```
+
+### Error Types
+
+All SDK error classes are importable from `@upstash/redis`:
+
+| Error | `error.name` | When it's thrown |
+| --- | --- | --- |
+| `UpstashError` | `"UpstashError"` | A command failed server-side, or the REST response contained an `error` field. The base error type. |
+| `UpstashJSONParseError` | `"UpstashJSONParseError"` | The response body could not be parsed as JSON. Extends `UpstashError`. |
+| `UrlError` | `"UrlError"` | The client was constructed with an invalid URL (must start with `https`). Thrown synchronously at construction, before any request. |
+| `TimeoutError` | `"TimeoutError"` | A request was aborted by an `AbortSignal.timeout(...)`. This is the native DOM error, not an SDK class. |
+
+```typescript
+import { Redis, UpstashError } from "@upstash/redis";
+
+try {
+  await redis.get("key");
+} catch (error) {
+  if (error instanceof UpstashError) {
+    // command failed or bad request to Upstash
+    console.error("Upstash command failed:", error.message);
+  } else if (error.name === "TimeoutError") {
+    console.error("Request timed out");
+  } else {
+    throw error;
+  }
+}
+```
+
+Because `UpstashJSONParseError extends UpstashError`, a single `instanceof UpstashError` check catches both. `UrlError` is thrown when you construct the client, so it surfaces at startup rather than inside request `try/catch` blocks.
+
+### Debugging
+
+- **Read the message — it includes the failed command.** `UpstashError` messages are formatted like `<server error>, command was: ["GET","key"]`, so logging `error.message` shows exactly what was sent.
+- **`UrlError` at startup** almost always means a missing or typo'd `UPSTASH_REDIS_REST_URL` (it must start with `https://`). Verify env vars before suspecting the network.
+- **Retryable vs. fatal.** Network and `TimeoutError` failures are transient and already covered by the built-in `retry`. An `UpstashError` from a bad command (wrong argument types, `WRONGTYPE`, unknown command) is deterministic — retrying won't help, so fix the call instead of raising the retry count.

package/.agents/skills/upstash/upstash-redis-js/performance/pipeline-optimization.md

@@ -0,0 +1,105 @@
+# Pipeline Optimization
+
+## Overview
+
+Pipelines batch multiple Redis commands into one HTTP request. Use automatic pipelines for Promise.all patterns, manual pipelines for sequential operations.
+
+## Good For
+
+- Multiple independent operations
+- High-latency networks
+- Serverless functions with cold starts
+- Operations that don't depend on each other's results
+
+## Limitations
+
+- Commands in pipeline cannot depend on previous results
+- Large pipelines increase memory usage
+- Errors in one command don't stop others
+
+## Examples
+
+### Auto-Pipeline Basics
+
+```typescript
+import { Redis } from "@upstash/redis";
+
+// Auto-pipeline: enable globally
+const redis = new Redis({
+  url: process.env.UPSTASH_REDIS_REST_URL!,
+  token: process.env.UPSTASH_REDIS_REST_TOKEN!,
+  enableAutoPipelining: true,
+});
+
+// With auto-pipeline: Promise.all batches automatically
+const [user, posts, comments] = await Promise.all([
+  redis.get("user:1"),
+  redis.lrange("posts:1", 0, 9),
+  redis.lrange("comments:1", 0, 9),
+]);
+// Single HTTP request!
+```
+
+### Manual Pipeline
+
+```typescript
+import { Redis } from "@upstash/redis";
+
+const redis = Redis.fromEnv();
+
+// Manual pipeline: explicit control
+const pipeline = redis.pipeline();
+pipeline.get("user:1");
+pipeline.lrange("posts:1", 0, 9);
+pipeline.lrange("comments:1", 0, 9);
+
+const results = await pipeline.exec();
+```
+
+### When to Use Pipelines
+
+```typescript
+import { Redis } from "@upstash/redis";
+
+const redis = Redis.fromEnv();
+
+// ❌ Bad: second operation depends on first
+const bad = redis.pipeline();
+bad.get("counter");
+bad.incr("counter"); // Might not see previous get result
+await bad.exec();
+
+// ✅ Good: independent operations
+const good = redis.pipeline();
+good.get("user:1");
+good.get("user:2");
+good.get("user:3");
+await good.exec();
+```
+
+### Pipeline Size Optimization
+
+```typescript
+import { Redis } from "@upstash/redis";
+
+const redis = Redis.fromEnv();
+const OPTIMAL_SIZE = 50;
+
+async function pipelinedBatch(keys: string[]) {
+  const results = [];
+  for (let i = 0; i < keys.length; i += OPTIMAL_SIZE) {
+    const batch = keys.slice(i, i + OPTIMAL_SIZE);
+    const pipeline = redis.pipeline();
+    batch.forEach((key) => pipeline.get(key));
+
+    const batchResults = await pipeline.exec();
+    results.push(...batchResults);
+  }
+
+  return results;
+}
+
+// Usage
+const keys = Array.from({ length: 200 }, (_, i) => `key:${i}`);
+const allResults = await pipelinedBatch(keys);
+```

package/.agents/skills/upstash/upstash-redis-js/performance/redis-replicas.md

@@ -0,0 +1,14 @@
+# Global Redis Replicas
+
+## Overview
+
+Upstash Redis uses global replication with one primary and multiple replicas worldwide. Writes go to primary, reads can use nearest replica. Read-your-writes ensures consistency.
+
+If you want to optimize read latency, you can add more read regions to your Upstash Redis database via the Upstash Console.
+
+## Good For
+
+- Low-latency reads from nearby regions
+- Global applications with distributed users
+- Read-heavy workloads
+- High availability

package/.agents/skills/upstash/upstash-redis-js/performance/ttl-expiration.md

@@ -0,0 +1,32 @@
+# TTL and Key Expiration
+
+## Overview
+
+Set Time-To-Live (TTL) on keys for automatic expiration. Useful for caches, sessions, and temporary data to manage memory usage.
+
+## Good For
+
+- Cache expiration (prevent stale data)
+- Session timeouts
+- Temporary data storage
+- Memory management
+
+## Examples
+
+```typescript
+import { Redis } from "@upstash/redis";
+
+const redis = Redis.fromEnv();
+
+// Set with expiration (EX = seconds)
+await redis.set("session:123", { userId: "user1" }, { ex: 3600 });
+
+// Add TTL to existing key
+await redis.set("key", "value");
+await redis.expire("key", 300); // Expire in 5 minutes
+
+// Get TTL of a key
+const ttl = await redis.ttl("key");
+console.log(`TTL: ${ttl} seconds`);
+// Returns: remaining seconds, -1 (no expiry), -2 (key doesn't exist)
+```

package/.agents/skills/upstash/upstash-redis-js/search/adapters.md

@@ -0,0 +1,99 @@
+# Adapters
+
+## Overview
+
+`@upstash/redis` works over HTTP, which is ideal for serverless environments. If you need TCP-based connections (e.g., long-running servers with `redis` or `ioredis`), use the adapter packages `@upstash/search-redis` and `@upstash/search-ioredis`. They provide the exact same search API.
+
+## Packages
+
+| Package                   | Client     | Protocol  | Install                                       |
+| ------------------------- | ---------- | --------- | --------------------------------------------- |
+| `@upstash/redis`          | Built-in   | HTTP/REST | `npm install @upstash/redis`                  |
+| `@upstash/search-redis`   | node-redis | TCP       | `npm install @upstash/search-redis redis`     |
+| `@upstash/search-ioredis` | ioredis    | TCP       | `npm install @upstash/search-ioredis ioredis` |
+
+## Examples
+
+### With @upstash/redis (HTTP)
+
+```typescript
+import { Redis, s } from "@upstash/redis";
+
+const redis = Redis.fromEnv();
+
+const index = await redis.search.createIndex({
+  name: "products",
+  prefix: "product:",
+  dataType: "json",
+  schema: s.object({ name: s.string(), price: s.number("F64") }),
+});
+
+const results = await index.query({
+  filter: { name: { $eq: "laptop" } },
+  select: { name: true, price: true },
+});
+```
+
+### With node-redis (TCP)
+
+```typescript
+import { createClient } from "redis";
+import { createSearch, s } from "@upstash/search-redis";
+
+const client = createClient({ url: process.env.REDIS_URL });
+await client.connect();
+
+const search = createSearch(client);
+
+const index = await search.createIndex({
+  name: "products",
+  prefix: "product:",
+  dataType: "json",
+  schema: s.object({ name: s.string(), price: s.number("F64") }),
+});
+
+const results = await index.query({
+  filter: { name: { $eq: "laptop" } },
+  select: { name: true, price: true },
+});
+
+await client.disconnect();
+```
+
+### With ioredis (TCP)
+
+```typescript
+import IORedis from "ioredis";
+import { createSearch, s } from "@upstash/search-ioredis";
+
+const ioredis = new IORedis(process.env.REDIS_URL);
+
+const search = createSearch(ioredis);
+
+const index = await search.createIndex({
+  name: "products",
+  prefix: "product:",
+  dataType: "json",
+  schema: s.object({ name: s.string(), price: s.number("F64") }),
+});
+
+const results = await index.query({
+  filter: { name: { $eq: "laptop" } },
+  select: { name: true, price: true },
+});
+
+await ioredis.disconnect();
+```
+
+## API Parity
+
+All three packages expose identical search APIs:
+
+- `search.createIndex()` / `createSearch(client).createIndex()`
+- `search.index()` / `createSearch(client).index()`
+- `search.alias.list()`, `search.alias.add()`, `search.alias.delete()`
+- `index.query()`, `index.aggregate()`, `index.count()`
+- `index.describe()`, `index.drop()`, `index.waitIndexing()`
+- `index.addAlias()`
+
+The only difference is initialization. The `s` schema builder is re-exported from all packages.

package/.agents/skills/upstash/upstash-redis-js/search/commands/aggregating.md

@@ -0,0 +1,234 @@
+# Aggregations
+
+## Overview
+
+Run analytics over indexed data using metric and bucket aggregations. Compute statistics, group documents, build histograms, and perform faceted navigation. Aggregations can be nested for multi-level analysis.
+
+## Good For
+
+- Computing averages, sums, min/max across documents
+- Grouping documents by field values (category breakdown)
+- Building price range facets for e-commerce
+- Histogram distributions (price ranges, date ranges)
+- Multi-level analytics (average price per category)
+
+## Examples
+
+### Metric Aggregations
+
+```typescript
+import { Redis, s } from "@upstash/redis";
+
+const redis = Redis.fromEnv();
+
+const index = await redis.search.createIndex({
+  name: "orders",
+  prefix: "order:",
+  dataType: "json",
+  schema: s.object({
+    product: s.string(),
+    category: s.facet(),
+    price: s.number("F64"),
+    quantity: s.number("U64"),
+    date: s.date(),
+  }),
+});
+
+// Insert sample data
+await redis.json.set("order:1", "$", {
+  product: "Laptop",
+  category: "electronics",
+  price: 999.99,
+  quantity: 1,
+  date: "2024-06-15",
+});
+await redis.json.set("order:2", "$", {
+  product: "Mouse",
+  category: "electronics",
+  price: 29.99,
+  quantity: 3,
+  date: "2024-06-16",
+});
+await redis.json.set("order:3", "$", {
+  product: "Desk",
+  category: "furniture",
+  price: 249.99,
+  quantity: 1,
+  date: "2024-07-01",
+});
+await index.waitIndexing();
+
+// Average price
+const result = await index.aggregate({
+  aggregations: {
+    avg_price: { $avg: { field: "price" } },
+  },
+});
+// result.avg_price -> number
+
+// Multiple metrics at once
+const stats = await index.aggregate({
+  aggregations: {
+    avg_price: { $avg: { field: "price" } },
+    total_revenue: { $sum: { field: "price" } },
+    cheapest: { $min: { field: "price" } },
+    most_expensive: { $max: { field: "price" } },
+    order_count: { $count: { field: "price" } },
+  },
+});
+
+// Combined statistics
+const priceStats = await index.aggregate({
+  aggregations: {
+    price_stats: { $stats: { field: "price" } },
+    // Returns: { count, min, max, sum, avg }
+  },
+});
+
+// Extended statistics (includes variance and standard deviation)
+const extended = await index.aggregate({
+  aggregations: {
+    price_extended: { $extendedStats: { field: "price" } },
+    // Returns: { count, min, max, sum, avg, sumOfSquares, variance, stdDeviation }
+  },
+});
+
+// Percentiles
+const percentiles = await index.aggregate({
+  aggregations: {
+    price_percentiles: { $percentiles: { field: "price", percents: [25, 50, 75, 95] } },
+  },
+});
+
+// Count distinct values
+const uniqueCategories = await index.aggregate({
+  aggregations: {
+    unique_cats: { $cardinality: { field: "category" } },
+  },
+});
+```
+
+### Bucket Aggregations
+
+#### $terms - Group by field values
+
+```typescript
+const byCategory = await index.aggregate({
+  aggregations: {
+    categories: {
+      $terms: { field: "category", size: 10 },
+    },
+  },
+});
+// categories.buckets -> [{ key: "electronics", doc_count: 2 }, { key: "furniture", doc_count: 1 }]
+```
+
+#### $range - Group by numeric ranges
+
+```typescript
+const priceRanges = await index.aggregate({
+  aggregations: {
+    price_ranges: {
+      $range: {
+        field: "price",
+        ranges: [
+          { to: 50 }, // Under $50
+          { from: 50, to: 200 }, // $50-$200
+          { from: 200 }, // Over $200
+        ],
+      },
+    },
+  },
+});
+```
+
+#### $histogram - Fixed-interval numeric buckets
+
+```typescript
+const priceHistogram = await index.aggregate({
+  aggregations: {
+    price_distribution: {
+      $histogram: { field: "price", interval: 100 },
+    },
+  },
+});
+```
+
+#### $facet - Faceted navigation
+
+```typescript
+const facets = await index.aggregate({
+  aggregations: {
+    brand_facets: { $facet: { field: "brand" } },
+  },
+});
+```
+
+### Nested Aggregations
+
+Combine buckets with metrics for multi-level analysis:
+
+```typescript
+// Average price per category
+const result = await index.aggregate({
+  aggregations: {
+    by_category: {
+      $terms: { field: "category" },
+      $aggs: {
+        avg_price: { $avg: { field: "price" } },
+        min_price: { $min: { field: "price" } },
+        max_price: { $max: { field: "price" } },
+        total_orders: { $count: { field: "price" } },
+      },
+    },
+  },
+});
+// by_category.buckets -> [
+//   { key: "electronics", doc_count: 2, avg_price: 514.99, min_price: 29.99, max_price: 999.99, total_orders: 2 },
+//   { key: "furniture", doc_count: 1, avg_price: 249.99, ... },
+// ]
+```
+
+### Filtered Aggregations
+
+Apply a filter before aggregating:
+
+```typescript
+const electronicsStats = await index.aggregate({
+  filter: { category: { $eq: "electronics" } },
+  aggregations: {
+    avg_price: { $avg: { field: "price" } },
+    price_ranges: {
+      $range: {
+        field: "price",
+        ranges: [{ to: 100 }, { from: 100, to: 500 }, { from: 500 }],
+      },
+    },
+  },
+});
+```
+
+## Available Aggregations
+
+### Metric Aggregations
+
+| Aggregation      | Description                                |
+| ---------------- | ------------------------------------------ |
+| `$avg`           | Average value of a numeric field           |
+| `$sum`           | Sum of values                              |
+| `$min`           | Minimum value                              |
+| `$max`           | Maximum value                              |
+| `$count`         | Count of documents                         |
+| `$cardinality`   | Count of distinct values                   |
+| `$stats`         | Combined count/min/max/sum/avg             |
+| `$extendedStats` | Stats + variance/stdDeviation/sumOfSquares |
+| `$percentiles`   | Percentile values at specified thresholds  |
+
+### Bucket Aggregations
+
+| Aggregation  | Description                       |
+| ------------ | --------------------------------- |
+| `$terms`     | Group by field values             |
+| `$range`     | Group by custom numeric ranges    |
+| `$histogram` | Fixed-interval numeric buckets    |
+| `$facet`     | Faceted navigation (hierarchical) |

package/.agents/skills/upstash/upstash-redis-js/search/commands/aliases.md

@@ -0,0 +1,76 @@
+# Aliases
+
+## Overview
+
+Index aliases provide an indirection layer between your application and the actual index. You can point an alias to any index and swap it atomically, enabling zero-downtime reindexing.
+
+## Good For
+
+- Zero-downtime index rebuilds (blue/green reindexing)
+- A/B testing different index configurations
+- Versioned index management
+
+## Examples
+
+### Add an Alias
+
+```typescript
+import { Redis, s } from "@upstash/redis";
+
+const redis = Redis.fromEnv();
+
+// Create an index
+const index = await redis.search.createIndex({
+  name: "products-v1",
+  prefix: "product:",
+  dataType: "json",
+  schema: s.object({ name: s.string(), price: s.number("F64") }),
+});
+
+// Add alias via the index instance
+await index.addAlias({ alias: "products" });
+
+// Or via the redis.search.alias API
+await redis.search.alias.add({ indexName: "products-v1", alias: "products" });
+```
+
+### List All Aliases
+
+```typescript
+const aliases = await redis.search.alias.list();
+// { "products": "products-v1", "users": "users-v2" }
+```
+
+### Delete an Alias
+
+```typescript
+await redis.search.alias.delete({ alias: "products" });
+// Returns 1 if deleted, 0 if alias didn't exist
+```
+
+### Zero-Downtime Reindexing
+
+```typescript
+// 1. Create new index with updated schema
+const newIndex = await redis.search.createIndex({
+  name: "products-v2",
+  prefix: "product:",
+  dataType: "json",
+  schema: s.object({
+    name: s.string(),
+    price: s.number("F64"),
+    description: s.string(), // new field
+  }),
+});
+
+// 2. Wait for new index to finish scanning existing keys
+await newIndex.waitIndexing();
+
+// 3. Atomically swap the alias to the new index
+// (addAlias updates the alias if it already exists)
+await redis.search.alias.add({ indexName: "products-v2", alias: "products" });
+
+// 4. Drop the old index
+const oldIndex = redis.search.index({ name: "products" });
+await oldIndex.drop();
+```