{"id":24075479,"url":"https://github.com/nelreina/redis-client","last_synced_at":"2026-05-15T06:06:08.181Z","repository":{"id":270718118,"uuid":"911252358","full_name":"nelreina/redis-client","owner":"nelreina","description":"A lightweight and feature-rich Redis client wrapper for Deno applications that simplifies Redis operations including Pub/Sub, Streams, Hash operations, and more.","archived":false,"fork":false,"pushed_at":"2025-09-17T22:01:34.000Z","size":66,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-09-18T00:11:23.591Z","etag":null,"topics":["pubsub","redis","redis-streams"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nelreina.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-01-02T15:32:26.000Z","updated_at":"2025-09-17T22:01:38.000Z","dependencies_parsed_at":"2025-01-18T17:23:11.606Z","dependency_job_id":"17a9f564-d272-4a63-8dad-dd895fc469ce","html_url":"https://github.com/nelreina/redis-client","commit_stats":null,"previous_names":["nelreina/redis-client"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/nelreina/redis-client","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nelreina%2Fredis-client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nelreina%2Fredis-client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nelreina%2Fredis-client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nelreina%2Fredis-client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nelreina","download_url":"https://codeload.github.com/nelreina/redis-client/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nelreina%2Fredis-client/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33055989,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-13T13:14:54.681Z","status":"online","status_checked_at":"2026-05-15T02:00:06.351Z","response_time":103,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["pubsub","redis","redis-streams"],"created_at":"2025-01-09T19:05:06.922Z","updated_at":"2026-05-15T06:06:08.176Z","avatar_url":"https://github.com/nelreina.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Redis Client Wrapper v2\n\nA powerful and feature-rich Redis client wrapper for Deno applications with v2\nAPI improvements. Built on top of `node-redis`, this library simplifies Redis\noperations while adding advanced features like middleware support, metrics\ncollection, batch operations, and enhanced stream processing.\n\n## Features\n\n- 🔄 Redis Pub/Sub messaging system\n- 📊 Enhanced Redis Streams with batch operations and dead letter queues\n- 📝 Hash and String operations with middleware support\n- 🔑 Flexible authentication with connection pooling\n- 🔌 Automatic connection management with retry strategies\n- 🚀 Event-driven architecture with metrics collection\n- 💪 Full TypeScript support with type definitions\n- 🎯 Fluent configuration API\n- 📈 Built-in observability (metrics, health checks)\n- 🔧 Middleware pipeline for cross-cutting concerns\n- ⚡ Pipeline and transaction support\n- 🔍 Advanced querying (scan, keys, mget/mset)\n\n## Installation\n\n```javascript\nimport { RedisClient } from \"@nelreina/redis-client\";\n// TypeScript users get full type support automatically\n```\n\n## Usage\n\n### Initialize Redis Client\n\n```javascript\n// Basic initialization\nconst redis = new RedisClient({\n  redisHost: \"localhost\",\n  redisPort: 6379,\n  redisUser: \"optional_username\",\n  redisPw: \"optional_password\",\n  serviceName: \"my-service\",\n  enableMetrics: true, // Enable metrics collection\n  connectionRetries: 3, // Retry connection 3 times\n  connectionRetryDelay: 1000, // Wait 1s between retries\n  logger: customLogger, // Optional: pass custom logger\n});\n\n// Fluent configuration\nconst redis = new RedisClient({ redisHost: \"localhost\" })\n  .withConnectionPool(5)\n  .withRetries(3, 2000)\n  .withMetrics(true)\n  .withLogger(customLogger);\n\n// Custom logger example\nconst customLogger = {\n  info: (message, ...args) =\u003e console.log(`[INFO] ${message}`, ...args),\n  error: (message, ...args) =\u003e console.error(`[ERROR] ${message}`, ...args),\n  warn: (message, ...args) =\u003e console.warn(`[WARN] ${message}`, ...args),\n  debug: (message, ...args) =\u003e console.debug(`[DEBUG] ${message}`, ...args),\n};\n```\n\n### Pub/Sub Operations\n\nSubscribe to a Redis channel:\n\n```javascript\nawait redis.subscribe2RedisChannel(\"my-channel\", (message) =\u003e {\n  console.log(\"Received message:\", message);\n});\n```\n\nPublish to a Redis channel:\n\n```javascript\nawait redis.publish2RedisChannel(\"my-channel\", {\n  event: \"user-login\",\n  data: { userId: \"123\" },\n});\n```\n\n### Redis Streams\n\nConnect to an event stream with v2 configuration:\n\n```javascript\n// Simple usage (backward compatible)\nawait redis.connectToEventStream(\n  \"my-stream\",\n  (event) =\u003e {\n    console.log(\"Stream event:\", event);\n  },\n  true, // All events\n);\n\n// Advanced configuration\nawait redis.connectToEventStream(\"my-stream\", {\n  handler: (event) =\u003e console.log(\"Event:\", event),\n  events: [\"user-registered\", \"order-created\"], // Filter specific events\n  startID: \"$\", // Start from latest\n  consumer: \"worker-1\",\n  group: \"my-group\",\n  blockTimeout: 5000, // Block for 5s when reading\n  autoAck: true, // Auto acknowledge messages\n  retries: 3, // Retry failed messages 3 times\n  deadLetterStream: \"dlq:my-stream\", // Send failed messages here\n  metrics: true, // Enable stream metrics\n});\n```\n\nPublish to a stream:\n\n```javascript\n// Single event\nawait redis.publishToStream(\n  \"my-stream\",\n  \"user-registered\",\n  \"user-123\",\n  { email: \"user@example.com\" },\n);\n\n// Batch publishing for better performance\nawait redis.publishBatchToStream(\"my-stream\", [\n  {\n    event: \"user-registered\",\n    aggregateId: \"user-123\",\n    payload: { email: \"user1@example.com\" },\n  },\n  {\n    event: \"user-registered\",\n    aggregateId: \"user-124\",\n    payload: { email: \"user2@example.com\" },\n  },\n]);\n```\n\n### Hash Operations\n\nSet hash values:\n\n```javascript\nawait redis.setHashValue(\"user:123\", {\n  name: \"John Doe\",\n  email: \"john@example.com\",\n  role: \"admin\",\n});\n```\n\nGet all hash values from a set:\n\n```javascript\nconst users = await redis.getAllSetHashValues(\"users\");\n```\n\n### String Operations\n\nBasic operations:\n\n```javascript\n// Get/Set with optional expiration\nawait redis.set(\"key\", \"value\");\nawait redis.set(\"session:123\", \"data\", { EX: 3600 }); // Expire in 1 hour\nconst value = await redis.get(\"key\");\n\n// Check existence and manage TTL\nconst exists = await redis.exists(\"key\"); // Returns 1 if exists\nawait redis.expire(\"key\", 300); // Expire in 5 minutes\nconst ttl = await redis.ttl(\"key\"); // Get remaining TTL\n\n// Delete keys\nawait redis.del(\"key\"); // Delete single key\nawait redis.del([\"key1\", \"key2\", \"key3\"]); // Delete multiple\n\n// Batch operations\nconst values = await redis.mget([\"key1\", \"key2\", \"key3\"]);\nawait redis.mset({\n  \"key1\": \"value1\",\n  \"key2\": \"value2\",\n  \"key3\": \"value3\",\n});\n```\n\nSet-based string operations:\n\n```javascript\nawait redis.setStringValue(\"active-sessions\", \"session:123\", \"user-data\");\nconst sessions = await redis.getAllStringValues(\"active-sessions\");\nawait redis.clearStringValues(\"active-sessions\");\n```\n\n### Advanced Operations\n\n#### Scanning and Pattern Matching\n\n```javascript\n// Find all keys matching a pattern\nconst userKeys = await redis.keys(\"user:*\");\n\n// Scan keys efficiently (for large datasets)\nfor await (const keys of redis.scan(\"session:*\", 100)) {\n  console.log(\"Found keys:\", keys);\n}\n```\n\n#### Pipeline and Transactions\n\n```javascript\n// Pipeline for batch operations\nconst pipeline = redis.pipeline();\npipeline.get(\"key1\");\npipeline.set(\"key2\", \"value2\");\npipeline.incr(\"counter\");\nconst results = await pipeline.exec();\n\n// Transaction with watch\nawait redis.watch(\"balance\");\nconst transaction = redis.transaction();\nconst balance = await redis.get(\"balance\");\ntransaction.set(\"balance\", parseInt(balance) - 100);\ntransaction.incr(\"transactions\");\nconst results = await transaction.exec();\n```\n\n### Middleware Support\n\n```javascript\n// Add logging middleware\nredis.use(async (operation, args, next) =\u003e {\n  console.log(`Executing ${operation} with args:`, args);\n  const start = Date.now();\n  const result = await next();\n  console.log(`${operation} took ${Date.now() - start}ms`);\n  return result;\n});\n\n// Add authentication middleware\nredis.use(async (operation, args, next) =\u003e {\n  if (sensitiveOperations.includes(operation)) {\n    await validateAuth();\n  }\n  return next();\n});\n```\n\n### Observability\n\n#### Health Checks\n\n```javascript\nconst health = await redis.getHealth();\nconsole.log(health);\n// {\n//   status: 'healthy',\n//   connections: { main: true, pubsub: true },\n//   timestamp: '2024-01-01T00:00:00.000Z'\n// }\n\n// Stream-specific health\nconst streamHealth = await redis.getStreamHealth(\"my-stream\");\nconsole.log(streamHealth);\n// {\n//   exists: true,\n//   length: 1000,\n//   groups: 2,\n//   consumers: 5,\n//   pending: 10\n// }\n```\n\n#### Metrics\n\n```javascript\n// Enable metrics\nconst redis = new RedisClient({ enableMetrics: true });\n\n// Get metrics\nconst metrics = redis.getMetrics();\nconsole.log(metrics);\n// {\n//   operations: { total: 1000, successful: 995, failed: 5 },\n//   latency: { avg: 2.5, p50: 2, p95: 5, p99: 10 },\n//   connections: { active: 1, idle: 0, total: 1 },\n//   streams: {\n//     'my-stream': { published: 100, consumed: 95, errors: 2 }\n//   }\n// }\n\n// Stream-specific metrics\nconst streamMetrics = redis.getStreamMetrics(\"my-stream\");\n```\n\n## Error Handling\n\nThe client includes comprehensive error handling:\n\n- Connection errors with automatic retry and backoff\n- JSON parsing errors are caught and handled gracefully\n- Middleware can intercept and handle errors\n- Stream processing errors can be sent to dead letter queues\n- All operations return detailed error information\n\n## Migration from v1\n\nThe v2 API is mostly backward compatible. Key changes:\n\n1. Stream configuration now supports an options object\n2. New methods require explicit connection handling\n3. Metrics and middleware are opt-in features\n4. Some methods now return more detailed responses\n\n## Best Practices\n\n1. **Enable metrics in production** for monitoring and debugging\n2. **Use pipelines** for batch operations to reduce network round trips\n3. **Configure retry strategies** based on your reliability requirements\n4. **Use middleware** for cross-cutting concerns like logging and auth\n5. **Monitor stream health** to prevent backlogs and memory issues\n6. **Use batch publishing** for high-throughput scenarios\n\n## License\n\nMIT\n\n## Contributing\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add some amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n---\n\nFor more information or issues, please open an issue in the repository.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnelreina%2Fredis-client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnelreina%2Fredis-client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnelreina%2Fredis-client/lists"}