{"id":19240375,"url":"https://github.com/paratron/rdscom","last_synced_at":"2026-02-14T01:04:43.539Z","repository":{"id":258426682,"uuid":"873907563","full_name":"Paratron/rdscom","owner":"Paratron","description":"A lightweight and efficient TypeScript library for message queuing and RPC using Redis","archived":false,"fork":false,"pushed_at":"2025-01-19T21:55:58.000Z","size":121,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-10-02T13:14:47.112Z","etag":null,"topics":[],"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/Paratron.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}},"created_at":"2024-10-16T23:38:37.000Z","updated_at":"2025-01-19T21:55:59.000Z","dependencies_parsed_at":"2024-10-19T00:06:12.525Z","dependency_job_id":"529a8459-a3f6-483f-9cf7-8ad36fd7978d","html_url":"https://github.com/Paratron/rdscom","commit_stats":null,"previous_names":["paratron/rdscom"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Paratron/rdscom","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Paratron%2Frdscom","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Paratron%2Frdscom/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Paratron%2Frdscom/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Paratron%2Frdscom/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Paratron","download_url":"https://codeload.github.com/Paratron/rdscom/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Paratron%2Frdscom/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29427672,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-13T22:20:51.549Z","status":"ssl_error","status_checked_at":"2026-02-13T22:20:49.838Z","response_time":78,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":[],"created_at":"2024-11-09T17:07:14.700Z","updated_at":"2026-02-14T01:04:43.519Z","avatar_url":"https://github.com/Paratron.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# rdscom\n\nA lightweight and efficient TypeScript library for message queuing and RPC (Remote Procedure Call) using Redis.\n\n## Table of Contents\n\n- [rdscom](#rdscom)\n  - [Table of Contents](#table-of-contents)\n  - [Overview](#overview)\n    - [Key Features](#key-features)\n  - [Core Concepts](#core-concepts)\n    - [Message Queuing](#message-queuing)\n      - [Common Use Cases](#common-use-cases)\n    - [Remote Procedure Call (RPC)](#remote-procedure-call-rpc)\n  - [Installation](#installation)\n  - [Basic Usage](#basic-usage)\n    - [Sending Messages](#sending-messages)\n    - [Receiving Messages](#receiving-messages)\n    - [Using RPC](#using-rpc)\n      - [Setting up an RPC Responder](#setting-up-an-rpc-responder)\n      - [Making an RPC Call](#making-an-rpc-call)\n  - [Advanced Usage](#advanced-usage)\n    - [Distributed Tracing](#distributed-tracing)\n    - [Worker Management](#worker-management)\n    - [Redis Connection Management](#redis-connection-management)\n    - [Logging Configuration](#logging-configuration)\n  - [Error Handling](#error-handling)\n    - [Redis Connection Errors](#redis-connection-errors)\n    - [Malformed Messages](#malformed-messages)\n  - [API Reference](#api-reference)\n    - [`send(channel: string, message: string, traceId?: string): Promise\u003cvoid\u003e`](#sendchannel-string-message-string-traceid-string-promisevoid)\n    - [`listen(channel: string, handler: Function, errorHandler?: Function, initialWorklimit?: number): Worker`](#listenchannel-string-handler-function-errorhandler-function-initialworklimit-number-worker)\n    - [`sendAndWaitForResponse(channel: string, message: string, traceId?: string): Promise\u003cstring\u003e`](#sendandwaitforresponsechannel-string-message-string-traceid-string-promisestring)\n    - [`listenAndRespond(channel: string, handler: Function, errorHandler?: Function): Worker`](#listenandrespondchannel-string-handler-function-errorhandler-function-worker)\n  - [License](#license)\n\n---\n\n## Overview\n\n`rdscom` is a lightweight and efficient TypeScript library designed for message queuing and remote procedure calls (RPC) using Redis. It facilitates asynchronous communication and scalable processing across distributed systems.\n\n### Key Features\n- **Message Queuing**: Reliable, FIFO-based message delivery with persistence until processed.\n- **Remote Procedure Call (RPC)**: Asynchronous request-response pattern across services.\n- **Distributed Tracing**: Built-in trace ID support for seamless log correlation.\n- **Customizable Logging**: Integrates with your existing logging systems.\n- **Scalable Workers**: Dynamically control concurrency with worker limits.\n- **Full Redis Control**: You manage Redis connections for complete flexibility.\n\n---\n\n## Core Concepts\n\n### Message Queuing\n\nMessage queuing enables asynchronous communication by delivering messages with low latency when receivers are listening, while ensuring persistence until processing.\n\nKey characteristics:\n- Near real-time delivery when listeners are active.\n- FIFO order within each channel.\n- Messages persist in Redis until successfully processed.\n\n#### Common Use Cases\n- Background job processing\n- Load balancing across multiple services\n- Decoupling system components\n- Handling high-throughput operations\n\n---\n\n### Remote Procedure Call (RPC)\n\nRPC allows services to make asynchronous requests and handle responses without blocking. It promotes loose coupling while enabling communication between services.\n\nExample: A service validates user credentials by making an RPC call to an authentication service.\n\nBenefits:\n- Enables request-response patterns across services.\n- Supports asynchronous and non-blocking operations.\n\n---\n\n## Installation\n\nInstall `rdscom` and its peer dependency, [ioredis](https://www.npmjs.com/package/ioredis):\n\n```bash\nnpm install rdscom ioredis\n```\n\n---\n\n## Basic Usage\n\n### Sending Messages\n\nSend messages to a specific channel:\n```typescript\nawait broker.send('user-service', JSON.stringify({\n  action: 'create',\n  data: { name: 'John Doe' }\n}));\n```\n\n### Receiving Messages\n\nStart listening on a channel:\n```typescript\nconst worker = broker.listen(\n  'user-service',\n  async (message) =\u003e {\n    const data = JSON.parse(message);\n    console.log('Processing message:', data);\n    await processMessage(data);\n  }\n);\n\n// Gracefully stop the worker later\nawait worker.stop();\n```\n\n### Using RPC\n\n#### Setting up an RPC Responder\n```typescript\nconst rpcWorker = broker.listenAndRespond(\n  'auth-service',\n  async (message) =\u003e {\n    const { username, password } = JSON.parse(message);\n    return JSON.stringify({ valid: username === 'admin' });\n  }\n);\n```\n\n#### Making an RPC Call\n```typescript\ntry {\n  const response = await broker.sendAndWaitForResponse(\n    'auth-service',\n    JSON.stringify({ username: 'user', password: 'pass' })\n  );\n  const result = JSON.parse(response);\n  console.log('Authentication result:', result);\n} catch (error) {\n  console.error('Error during RPC:', error.message);\n}\n```\n\n---\n\n## Advanced Usage\n\n### Distributed Tracing\n\nBuilt-in support for trace IDs:\n```typescript\nawait broker.send(\n  'user-service',\n  JSON.stringify({ action: 'create' }),\n  'trace-123'\n);\n```\nTrace IDs help:\n- Link messages to handlers across services.\n- Track RPC request-response pairs.\n- Correlate logs across systems.\n\n### Worker Management\n\nControl concurrency using worker limits:\n```typescript\nconst worker = broker.listen('channel', async (message) =\u003e { /* ... */ }, undefined, 5);\n\n// Adjust limits dynamically\nworker.setWorklimit(10);  // Increase to 10 workers\nworker.setWorklimit(0);   // Unlimited concurrency\n```\n\n### Redis Connection Management\n\nYou manage Redis connections for full flexibility:\n```typescript\nimport { Redis } from 'ioredis';\n\nconst redis = new Redis({ host: 'localhost', port: 6379 });\n\nredis.on('error', (err) =\u003e {\n  console.error('Redis connection error:', err);\n});\n\nconst broker = createMessageBroker(redis);\n```\n\n### Logging Configuration\n\nIntegrate with your logging system:\n```typescript\nconst broker = createMessageBroker(redisClient, { logger: customLogger });\n```\n\n__Heads up!__: Make sure your custom logger implements at least a `warn()` and `error()` method.\n\n```typescript\ninterface Logger {\n  warn(message: string, meta?: Record\u003cstring, unknown\u003e): void;\n  error(message: string, meta?: Record\u003cstring, unknown\u003e): void;\n}\n```\n\n---\n\n## Error Handling\n\n### Redis Connection Errors\n\nHandle Redis errors at the application level:\n```typescript\nredis.on('error', (error) =\u003e {\n  console.error('Redis error:', error);\n});\n```\n\n### Malformed Messages\n\nBy default, malformed messages are logged and dropped. Provide an error handler to customize:\n```typescript\nconst worker = broker.listen(\n  'channel',\n  async (message) =\u003e { /* ... */ },\n  async (error, rawMessage) =\u003e {\n    console.warn('Malformed message:', { error, rawMessage });\n  }\n);\n```\n\n---\n\n## API Reference\n\n### `send(channel: string, message: string, traceId?: string): Promise\u003cvoid\u003e`\n\n**Description**: Sends a message to a specific channel.\n\n**Arguments**:\n- `channel` (string): The name of the Redis channel to send the message to.\n- `message` (string): The content of the message. Should be a stringified JSON object or other valid string.\n- `traceId?` (string, optional): An optional unique identifier for tracing the message. If not provided, a UUID will be generated.\n\n**Example**:\n```typescript\nawait broker.send('user-service', JSON.stringify({ action: 'create' }), 'trace-123');\n```\n\n---\n\n### `listen(channel: string, handler: Function, errorHandler?: Function, initialWorklimit?: number): Worker`\n\n**Description**: Starts listening for messages on a channel.\n\n**Arguments**:\n- `channel` (string): The name of the channel to listen on.\n- `handler` (Function): The function to process each message.\n- `errorHandler?` (Function, optional): Handles malformed messages.\n- `initialWorklimit?` (number, optional): Limits concurrent workers (default is 1).\n\n**Example**:\n```typescript\nconst worker = broker.listen('channel', async (message) =\u003e { console.log(message); });\n```\n\n---\n\n### `sendAndWaitForResponse(channel: string, message: string, traceId?: string): Promise\u003cstring\u003e`\n\n**Description**: Sends an RPC message and waits for a response.\n\n**Arguments**:\n- `channel` (string): The channel to send the message to.\n- `message` (string): The content of the message.\n- `traceId?` (string, optional): A unique identifier for tracing.\n\n**Example**:\n```typescript\nconst response = await broker.sendAndWaitForResponse('auth-service', JSON.stringify({ user: 'admin' }));\n```\n\n---\n\n### `listenAndRespond(channel: string, handler: Function, errorHandler?: Function): Worker`\n\n**Description**: Sets up an RPC responder.\n\n**Arguments**:\n- `channel` (string): The name of the channel to respond to.\n- `handler` (Function): The function to handle requests.\n- `errorHandler?` (Function, optional): Handles errors during request processing.\n\n**Example**:\n```typescript\nconst rpcWorker = broker.listenAndRespond('auth-service', async (message) =\u003e { return 'response'; });\n```\n\n---\n\n## License\n\nThis project is licensed under the MIT License.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fparatron%2Frdscom","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fparatron%2Frdscom","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fparatron%2Frdscom/lists"}