{"_id":"@alonye/rate-limiter-core","name":"@alonye/rate-limiter-core","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@alonye/rate-limiter-core","version":"1.0.0","description":"Framework-agnostic Redis-based rate limiter with OpenTelemetry support","main":"./dist/index.cjs","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"import":"./dist/index.js","require":"./dist/index.cjs","types":"./dist/index.d.ts"}},"sideEffects":false,"scripts":{"build":"tsup","dev":"tsup --watch","test":"jest","lint":"eslint src --ext .ts","clean":"rimraf dist"},"keywords":["rate-limiter","redis","opentelemetry","distributed","queue","throttling"],"peerDependencies":{"ioredis":"^5.0.0"},"dependencies":{"rate-limiter-flexible":"^7.2.0","bottleneck":"^2.19.5"},"devDependencies":{"@types/jest":"^29.5.0","@typescript-eslint/eslint-plugin":"^6.0.0","@typescript-eslint/parser":"^6.0.0","eslint":"^8.0.0","jest":"^29.0.0","rimraf":"^5.0.0","ts-jest":"^29.0.0","tsup":"^8.0.0","typescript":"^5.0.0"},"_id":"@alonye/rate-limiter-core@1.0.0","gitHead":"621132e2de682fb5a21a6b36ca80e054f47c9fae","_nodeVersion":"22.17.1","_npmVersion":"10.9.2","dist":{"integrity":"sha512-iUGBi+vXyXMLqAtm7HeKBQpE2xgaAp1n7bIEa8q2u4w+grLTzXAHPMFqmgL+Yro6BK0OoOryDCDo6ndeRPypzg==","shasum":"1acd537a8971aee2f0d3795ae5b2140d2e4cec18","tarball":"https://registry.npmjs.org/@alonye/rate-limiter-core/-/rate-limiter-core-1.0.0.tgz","fileCount":8,"unpackedSize":149839,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIBXzSZzlvxsohD/4QzxGZFiLSEboPS1+FiVxQkd7AnbqAiAPNvU13A6IDMzLkDVFJWjjArySAfKHCa9B5/SPvZndGg=="}]},"_npmUser":{"name":"alonye","email":"alon.yeroushalmi@entrata.com"},"directories":{},"maintainers":[{"name":"alonye","email":"alon.yeroushalmi@entrata.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/rate-limiter-core_1.0.0_1757515975754_0.05279541925773468"},"_hasShrinkwrap":false}},"time":{"created":"2025-09-10T14:52:55.667Z","1.0.0":"2025-09-10T14:52:55.940Z","modified":"2025-09-10T14:52:56.198Z"},"maintainers":[{"name":"alonye","email":"alon.yeroushalmi@entrata.com"}],"description":"Framework-agnostic Redis-based rate limiter with OpenTelemetry support","keywords":["rate-limiter","redis","opentelemetry","distributed","queue","throttling"],"readme":"# @eli-plus/rate-limiter-core\n\nFramework-agnostic Redis-based rate limiter with OpenTelemetry support.\n\n## Features\n\n- **Distributed Rate Limiting**: Redis-based rate limiting with support for multiple profiles\n- **Cross-Process Tracing**: OpenTelemetry integration with trace context propagation\n- **Multiple Implementations**: Flexible and Bottleneck rate limiter implementations\n- **Priority Queuing**: Job priority support with configurable priority levels\n- **Graceful Degradation**: Fallback to immediate execution when Redis is unavailable\n\n## Installation\n\n```bash\nnpm install @eli-plus/rate-limiter-core\n```\n\n## Usage\n\n### Basic Usage\n\n```typescript\nimport { createFlexibleRateLimiter } from '@eli-plus/rate-limiter-core';\nimport Redis from 'ioredis';\n\nconst redis = new Redis({\n  host: 'localhost',\n  port: 6379,\n});\n\nconst rateLimiter = createFlexibleRateLimiter({\n  redis,\n  profiles: {\n    google: {\n      profile: 'google',\n      points: 100,\n      durationSec: 60,\n    },\n    microsoft: {\n      profile: 'microsoft',\n      points: 50,\n      durationSec: 60,\n    },\n  },\n});\n\n// Provide your own JobExecutor\nrateLimiter.executor = {\n  execute: async (descriptor) => {\n    // Your job execution logic here\n    return await doWork(descriptor.payloadJson);\n  },\n};\n\n// Schedule a job\nconst result = await rateLimiter.schedule({\n  namespace: 'sendingEmail',\n  bucketKey: 'sender@example.com',\n  profile: 'google',\n  jobId: 'message-123',\n  payloadJson: JSON.stringify({ message: 'Hello World' }),\n});\n```\n\n### Advanced Usage with Custom Executor\n\n```typescript\nimport {\n  FlexibleRateLimiterService,\n  JobExecutor,\n} from '@eli-plus/rate-limiter-core';\n\nclass CustomExecutor implements JobExecutor {\n  async execute(descriptor: any): Promise<unknown> {\n    // Parse the payload\n    const payload = JSON.parse(descriptor.payloadJson);\n\n    // Perform your custom work\n    const result = await this.performWork(payload);\n\n    return result;\n  }\n}\n\nconst rateLimiter = new FlexibleRateLimiterService(\n  redis,\n  logger,\n  new CustomExecutor(),\n  telemetry,\n  profiles,\n);\n```\n\n## API Reference\n\n### Types\n\n- `ScheduleOpts`: Options for scheduling a job\n- `JobDescriptor`: Job metadata and payload\n- `JobExecutor`: Interface for executing jobs\n- `LoggerLike`: Logger interface\n- `TelemetryLike`: Telemetry interface\n\n### Classes\n\n- `FlexibleRateLimiterService`: Main rate limiter implementation\n- `BottleneckRateLimiterService`: Alternative implementation using Bottleneck\n- `BaseRateLimiterService`: Abstract base class for rate limiters\n\n## Configuration\n\n### Rate Limiter Profiles\n\n```typescript\nconst profiles = {\n  google: {\n    profile: 'google',\n    points: 100, // 100 requests per window\n    durationSec: 60, // 60 second window\n  },\n  microsoft: {\n    profile: 'microsoft',\n    points: 50, // 50 requests per window\n    durationSec: 60, // 60 second window\n  },\n};\n```\n\n### Options\n\n- `redis`: Redis instance (required)\n- `logger`: Logger instance (optional)\n- `telemetry`: Telemetry instance (optional)\n- `profiles`: Rate limit profiles (required)\n- `claimLockTtlSec`: Lock TTL in seconds (default: 30)\n- `resultTtlSec`: Result TTL in seconds (default: 30)\n\n## Telemetry\n\nThe rate limiter supports OpenTelemetry integration:\n\n- **Spans**: Automatic span creation for job scheduling and execution\n- **Metrics**: Job counts, processing times, queue sizes\n- **Trace Context**: Cross-process trace propagation\n\n## Error Handling\n\nThe rate limiter provides graceful degradation:\n\n- **Redis Unavailable**: Jobs execute immediately when Redis is down\n- **Job Failures**: Failed jobs are properly logged and metrics recorded\n- **Timeout Handling**: Jobs timeout gracefully with configurable TTL\n\n## License\n\nMIT License\n","readmeFilename":"README.md","_rev":"1-02fb168f6d76e0ef24f28377bb5851dc"}