{"_id":"@cantez/tokova","_rev":"2-26d167a55de9609a8d67843cb070bf6f","name":"@cantez/tokova","dist-tags":{"latest":"1.1.0"},"versions":{"1.0.0":{"name":"@cantez/tokova","version":"1.0.0","license":"MIT","_id":"@cantez/tokova@1.0.0","maintainers":[{"name":"cantez","email":"alperencantez@gmail.com"}],"contributors":[{"name":"Alperen Cantez","email":"alperen.cantez@outlook.com"}],"dist":{"shasum":"3a26c09e12f5b97bd743a92ea6583d067ade1381","tarball":"https://registry.npmjs.org/@cantez/tokova/-/tokova-1.0.0.tgz","fileCount":24,"integrity":"sha512-Dse4KtM/rKupVMYbsO7mBOK3XWVkiSWwJH3SkfTce5Ama5OPI3J2NS5OWLvKRSZIlQ7M96Rk9Own0uKLyeGt4A==","signatures":[{"sig":"MEQCICo0LeRFxDr7SoEARhlDkyW7Bc+V9mNyt/+qyEaeVIt7AiA691sXVAV5QwH9WNlzzbp+t1eh98fXZc84Bjmw/le2FA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":46254},"main":"dist/index.js","types":"./dist/index.d.ts","private":false,"scripts":{"test":"bun lib/test.ts","build":"tsc"},"_npmUser":{"name":"cantez","email":"alperencantez@gmail.com"},"_npmVersion":"10.2.4","description":"Token bucket rate limiter middleware for Node.js applications.","directories":{},"_nodeVersion":"18.19.1","dependencies":{"async-mutex":"^0.5.0","@clack/prompts":"^0.10.1"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.8.3","@types/node":"^22.15.18","@preconstruct/cli":"^2.8.12"},"_npmOperationalInternal":{"tmp":"tmp/tokova_1.0.0_1747614735142_0.18058125376890088","host":"s3://npm-registry-packages-npm-production"}},"1.1.0":{"name":"@cantez/tokova","description":"Token bucket rate limiter middleware for Node.js applications.","license":"MIT","main":"dist/index.js","private":false,"version":"1.1.0","contributors":[{"name":"Alperen Cantez","email":"alperen.cantez@outlook.com"}],"scripts":{"build":"tsc","test":"bun lib/test.ts"},"devDependencies":{"@preconstruct/cli":"^2.8.12","@types/node":"^22.15.18","typescript":"^5.8.3"},"dependencies":{"@clack/prompts":"^0.10.1","async-mutex":"^0.5.0"},"_id":"@cantez/tokova@1.1.0","gitHead":"3179e27e621a8ae5388fdbf54690765cc87aaf67","types":"./dist/index.d.ts","_nodeVersion":"18.19.1","_npmVersion":"10.2.4","dist":{"integrity":"sha512-LGZVd/YCVb2NdOUtmr+sToX7IWlT+YykLw9LZlMzV6BxroSBwpy7lwf7xPiDCFOKfP6Ksiz/HyFJ5PHTNb0vaA==","shasum":"2531f3aae6ab585f5d7ae6bca00f70f862508dc3","tarball":"https://registry.npmjs.org/@cantez/tokova/-/tokova-1.1.0.tgz","fileCount":28,"unpackedSize":70497,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIAZk1WP/twV4vX/ASXofLwEUu8DEbspdSELPkfPyLozmAiA3rLRpIX8LN0aSiX+Qg7WfNmAILOOB3jsu2k7g4OBHCQ=="}]},"_npmUser":{"name":"cantez","email":"alperencantez@gmail.com"},"directories":{},"maintainers":[{"name":"cantez","email":"alperencantez@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/tokova_1.1.0_1747667315298_0.6054710934372718"},"_hasShrinkwrap":false}},"time":{"created":"2025-05-19T00:32:15.059Z","modified":"2025-05-19T15:08:35.632Z","1.0.0":"2025-05-19T00:32:15.337Z","1.1.0":"2025-05-19T15:08:35.464Z"},"license":"MIT","description":"Token bucket rate limiter middleware for Node.js applications.","contributors":[{"name":"Alperen Cantez","email":"alperen.cantez@outlook.com"}],"maintainers":[{"name":"cantez","email":"alperencantez@gmail.com"}],"readme":"# 🪣 Tokova\n\nA flexible and efficient token bucket rate limiter implementation for Node.js applications. Tokova provides a simple yet powerful way to implement rate limiting in your applications.\n\n## Features\n\n-   🚀 Simple and intuitive API\n-   🔒 Thread-safe operations using async-mutex\n-   ⚡️ Efficient token bucket algorithm\n-   🔄 Automatic time based token refill\n-   🛡️ Written in TypeScript\n\n## Installation\n\n```bash\nnpm i @cantez/tokova\n# or\nyarn add @cantez/tokova\n# or\nbun add @cantez/tokova\n```\n\n## Quick Start\n\n```typescript\nimport { Tokova, TKIntervals } from '@cantez/tokova';\n\n// Create a rate limiter with:\n// - 500 tokens maximum\n// - 1 second refill interval\n// - 10 tokens per interval\nconst tk = new Tokova({\n    limit: 500,\n    interval: TKIntervals.SECOND,\n    tokensPerInterval: 10,\n});\n\n// Consume tokens\ntry {\n    await tk.consume(100);\n    // Proceed with your rate-limited operation\n} catch (error: any) {\n    // Handle rate limit exceeded\n    console.error('Rate limit exceeded:', error.message);\n}\n```\n\n## API Reference\n\n### Constructor Options\n\n```typescript\ntype TokovaOptions {\n    limit: number; // Maximum number of tokens\n    interval: number; // Refill interval in milliseconds\n    tokensPerInterval: number; // Number of tokens to add per interval\n}\n```\n\n### Predefined Intervals\n\n```typescript\nenum TKIntervals {\n    SECOND = 1000,\n    MINUTE = 60000,\n    HOUR = 3600000,\n    DAY = 86400000,\n}\n```\n\n### Methods\n\n#### `consume(amount: number): Promise<void>`\n\nConsumes the specified number of tokens. Throws an error if there aren't enough tokens available.\n\n```typescript\nawait tk.consume(100);\n```\n\n#### `getTokenCount(): Promise<number>`\n\nReturns the current number of available tokens.\n\n```typescript\nconst availableTokens = await tk.getTokenCount();\n```\n\n#### `destroy(): void`\n\nCleans up the rate limiter by clearing any intervals. Call this when you're done with the rate limiter.\n\n```typescript\ntk.destroy();\n```\n\n### Properties\n\n#### `bucket: { tokens: number; lastRefill: number }`\n\nAccess the current state of the token bucket.\n\n#### `options: TokovaOptions`\n\nAccess the rate limiter configuration.\n\n## Examples\n\n### Basic Rate Limiting\n\n```typescript\nconst tk = new Tokova({\n    limit: 100,\n    interval: TKIntervals.MINUTE,\n    tokensPerInterval: 10,\n});\n\nasync function handleRequest() {\n    try {\n        await tk.consume(1);\n        // Process request\n    } catch (error) {\n        // Handle rate limit exceeded\n    }\n}\n```\n\n### Custom Interval\n\n```typescript\nconst tk = new Tokova({\n    limit: 1000,\n    interval: 5000, // 5 seconds\n    tokensPerInterval: 100,\n});\n```\n\n### Checking Available Tokens\n\n```typescript\nconst availableTokens = await tk.getTokenCount();\nif (availableTokens >= requiredTokens) {\n    // Proceed with operation\n}\n```\n\n## Error Handling\n\n```typescript\ntry {\n    await tk.consume(amount);\n} catch (error) {\n    if (error.message === 'Not enough tokens') {\n        // Handle rate limit exceeded\n    } else {\n        // Handle other errors\n    }\n}\n```\n\n## Best Practices\n\n1. **Resource Cleanup**: Always call `destroy()` when you're done with the rate limiter to prevent memory leaks.\n\n2. **Error Handling**: Always wrap `consume()` calls in try-catch blocks to handle rate limit exceeded cases.\n\n3. **Token Amount**: Choose appropriate token amounts based on your use case. Smaller amounts provide finer-grained control.\n\n4. **Interval Selection**: Choose an interval that makes sense for your application's needs.\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## License\n\nMIT © Alperen Cantez\n","readmeFilename":"README.md"}