{"id":21916520,"url":"https://github.com/cloudnode-pro/ratelimit","last_synced_at":"2025-04-18T21:56:19.310Z","repository":{"id":60828843,"uuid":"545401772","full_name":"cloudnode-pro/ratelimit","owner":"cloudnode-pro","description":"Simple ratelimiter for Node.js","archived":false,"fork":false,"pushed_at":"2024-11-04T19:01:38.000Z","size":295,"stargazers_count":2,"open_issues_count":5,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2024-11-13T17:09:25.058Z","etag":null,"topics":["limit","limiter","rate","ratelimit","ratelimiter"],"latest_commit_sha":null,"homepage":"https://cloudnode.pro","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cloudnode-pro.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-10-04T09:55:04.000Z","updated_at":"2024-10-07T14:41:58.000Z","dependencies_parsed_at":"2023-02-13T19:30:52.661Z","dependency_job_id":null,"html_url":"https://github.com/cloudnode-pro/ratelimit","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudnode-pro%2Fratelimit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudnode-pro%2Fratelimit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudnode-pro%2Fratelimit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudnode-pro%2Fratelimit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cloudnode-pro","download_url":"https://codeload.github.com/cloudnode-pro/ratelimit/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":226971307,"owners_count":17711414,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["limit","limiter","rate","ratelimit","ratelimiter"],"created_at":"2024-11-28T19:18:20.762Z","updated_at":"2024-11-28T19:18:21.416Z","avatar_url":"https://github.com/cloudnode-pro.png","language":"JavaScript","readme":"# Rate limiting utility\n[![npm](https://img.shields.io/npm/v/cldn-ratelimit)](https://www.npmjs.com/package/cldn-ratelimit)\n[![npm downloads](https://img.shields.io/npm/dt/cldn-ratelimit?label=downloads)](https://www.npmjs.com/package/cldn-ratelimit)\n![test: passing](https://img.shields.io/badge/tests-passing-%2316a34a)\n![coverage: 100%](https://img.shields.io/badge/coverage-100%25-%2316a34a)\n![build: passing](https://img.shields.io/badge/build-passing-%2316a34a)\n[![CodeQL](https://github.com/cloudnode-pro/ratelimit/actions/workflows/github-code-scanning/codeql/badge.svg)](https://github.com/cloudnode-pro/ratelimit/actions/workflows/github-code-scanning/codeql)\n\nA relatively simple utility for abstract rate limiting. This library uses memory storage (i.e. does not rely on external database or writing data on your file system). Rate limits are reset if the process is restarted.\n\n# Get started\n#### Install package from `npm`\n```sh\nnpm i cldn-ratelimit\n```\n#### Import in your project\nHere is a very simple demo demonstrating very basic limiting of login attempts.\n```js\nimport {RateLimit} from 'cldn-ratelimit';\n\nconst rateLimit = new RateLimit(\"login-attempts\", 3, 60); // max 3 requests per 60 seconds\n\nconst attemptLogin = (username, password) =\u003e {\n\tif (!rateLimit.attempt(username).allow) return \"rate-limited\";\n\tif (username === \"john.doe\" \u0026\u0026 password === \"password123\") return \"success\";\n\treturn \"wrong-password\";\n}\n\nattemptLogin(\"john.doe\", \"wrongpass\"); //-\u003e \"wrong-password\"\nattemptLogin(\"john.doe\", \"wrongpass2\"); //-\u003e \"wrong-password\"\nattemptLogin(\"john.doe\", \"wrongpass\"); //-\u003e \"wrong-password\"\nattemptLogin(\"john.doe\", \"password123\"); //-\u003e \"rate-limited\"\n// wait 60 seconds\nattemptLogin(\"john.doe\", \"password123\"); //-\u003e \"success\"\n```\n\nIf you want to reset the rate limit after a successful login, call [`rateLimit.reset(username)`](#ratelimitresetsource).\n\n# Documentation\n\u003cdetails open\u003e\n\t\u003csummary\u003eTable of contents\u003c/summary\u003e\n\n- [Class: `RateLimit`](#class-ratelimit)\n\t- [Static method: `RateLimit.attempt(name, source, [attempts], [callback])`](#static-method-ratelimitattemptname-source-attempts-callback)\n\t- [Static method: `RateLimit.check(name, source, [callback])`](#static-method-ratelimitcheckname-source-callback)\n\t- [Static method: `RateLimit.clear(name)`](#static-method-ratelimitclearname)\n\t- [Static method: `RateLimit.create(name, limit, timeWindow)`](#static-method-ratelimitcreatename-limit-timewindow)\n\t- [Static method: `RateLimit.delete(name)`](#static-method-ratelimitdeletename)\n\t- [Static method: `RateLimit.get(name)`](#static-method-ratelimitgetname)\n\t- [Static method: `RateLimit.reset(name, source)`](#static-method-ratelimitresetname-source)\n\t- [Static method: `RateLimit.setRemaining(name, source, remaining)`](#static-method-ratelimitsetremainingname-source-remaining)\n\t- [`new RateLimit(name, limit, timeWindow)`](#new-ratelimitname-limit-timewindow)\n\t- [`rateLimit.attempt(source, [attempts], [callback])`](#ratelimitattemptsource-attempts-callback)\n\t- [`rateLimit.check(source, [callback])`](#ratelimitchecksource-callback)\n\t- [`rateLimit.clear()`](#ratelimitclear)\n\t- [`rateLimit.delete()`](#ratelimitdelete)\n\t- [`rateLimit.limit`](#ratelimitlimit)\n\t- [`rateLimit.name`](#ratelimitname)\n\t- [`rateLimit.reset(source)`](#ratelimitresetsource)\n\t- [`rateLimit.setRemaining(source, remaining)`](#ratelimitsetremainingsource-remaining)\n\t- [`rateLimit.timeWindow`](#ratelimittimewindow)\n- [Interface: `AttemptResult`](#interface-attemptresult)\n    - [`attemptResult.limit`](#attemptresultlimit)\n    - [`attemptResult.remaining`](#attemptresultremaining)\n    - [`attemptResult.reset`](#attemptresultreset)\n    - [`attemptResult.rateLimit`](#attemptresultratelimit)\n    - [`attemptResult.allow`](#attemptresultallow)\n\u003c/details\u003e\n\n\u003ca name=\"class-ratelimit\"\u003e\u003c/a\u003e\n## Class: `RateLimit`\nRate limit\n\n\u003ca name=\"static-method-ratelimitattemptname-source-attempts-callback\"\u003e\u003c/a\u003e\n### Static method: `RateLimit.attempt(name, source, [attempts], [callback])`\nMake an attempt with a source ID\n\n- `name` [`string`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) The name of the rate limit\n- `source` [`string`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) Unique source identifier (e.g. username, IP, etc.)\n- `attempts` [`number`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type) The number of attempts to make. Default: `1`\n- `callback` [`function`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function) Callback function. Default: `undefined`\n  - `result` [`AttemptResult`](#interface-attemptresult) The result of the attempt\n  - Returns: [`void`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Undefined_type)\n- Returns: [`AttemptResult`](#interface-attemptresult)\n- Throws: [`Error`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error) If the rate limit does not exist\n\n\u003ca name=\"static-method-ratelimitcheckname-source-callbac\"\u003e\u003c/a\u003e\n### Static method: `RateLimit.check(name, source, [callback])`\nCheck the attempt state for a source ID without decrementing the remaining attempts\n\n- `name` [`string`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) The name of the rate limit\n- `source` [`string`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) Unique source identifier (e.g. username, IP, etc.)\n- `callback` [`function`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function) Callback function. Default: `undefined`\n  - `result` [`AttemptResult`](#interface-attemptresult) The result of the attempt\n  - Returns: [`void`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Undefined_type)\n- Returns: [`AttemptResult`](#interface-attemptresult)\n- Throws: [`Error`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error) If the rate limit does not exist\n\n\u003ca name=\"static-method-ratelimitclearname\"\u003e\u003c/a\u003e\n### Static method: `RateLimit.clear(name)`\nClear rate limit attempts storage. This is equivalent to resetting all rate limits.\n\n- `name` [`string`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) The name of the rate limit\n- Returns: [`void`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Undefined_type)\n- Throws: [`Error`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error) If the rate limit does not exist\n\n\u003ca name=\"static-method-ratelimitcreatename-limit-timewindow\"\u003e\u003c/a\u003e\n### Static method: `RateLimit.create(name, limit, timeWindow)`\nCreate a new rate limit\n\n- `name` [`string`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) The name of the rate limit\n- `limit` [`number`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type) The number of attempts allowed per time window (e.g. 60)\n- `timeWindow` [`number`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type) The time window in seconds (e.g. 60)\n- Returns: [`RateLimit`](#class-ratelimit)\n\n\u003ca name=\"static-method-ratelimitdeletename\"\u003e\u003c/a\u003e\n### Static method: `RateLimit.delete(name)`\nDelete the rate limit instance. After it is deleted, it should not be used any further without constructing a new instance.\n\n- `name` [`string`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) The name of the rate limit\n- Returns: [`void`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Undefined_type)\n- Throws: [`Error`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error) If the rate limit does not exist\n\n\u003ca name=\"static-method-ratelimitgetname\"\u003e\u003c/a\u003e\n### Static method: `RateLimit.get(name)`\nGet a rate limit instance\n\n- `name` [`string`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) The name of the rate limit\n- Returns: [`RateLimit`](#class-ratelimit) or [`null`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Null_type)\n\n\u003ca name=\"static-method-ratelimitresetsource\"\u003e\u003c/a\u003e\n### Static method: `RateLimit.reset(name, source)`\nReset limit for a source ID. The storage entry will be deleted and a new one will be created on the next attempt.\n\n- `name` [`string`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) The name of the rate limit\n- `source` [`string`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) Unique source identifier (e.g. username, IP, etc.)\n- Returns: [`void`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Undefined_type)\n- Throws: [`Error`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error) If the rate limit does not exist\n\n\u003ca name=\"static-method-ratelimitsetremainingname-source-remaining\"\u003e\u003c/a\u003e\n### Static method: `RateLimit.setRemaining(name, source, remaining)`\nSet the remaining attempts for a source ID.\n\n\u003e **Warning**: This is not recommended as the remaining attempts depend on the limit of the instance.\n\n- `name` [`string`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) The name of the rate limit\n- `source` [`string`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) Unique source identifier (e.g. username, IP, etc.)\n- `remaining` [`number`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type) The number of remaining attempts\n- Returns: [`void`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Undefined_type)\n- Throws: [`Error`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error) If the rate limit does not exist\n\n\u003ca name=\"new-ratelimitname-limit-timewindow\"\u003e\u003c/a\u003e\n### `new RateLimit(name, limit, timeWindow)`\nCreate a new rate limit\n\n- `name` [`string`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) The name of the rate limit\n- `limit` [`number`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type) The number of attempts allowed per time window (e.g. 60)\n- `timeWindow` [`number`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type) The time window in seconds (e.g. 60)\n- Throws: [`Error`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error) If the rate limit already exists\n\n\u003ca name=\"ratelimitattemptsource-attempts-callback\"\u003e\u003c/a\u003e\n### `rateLimit.attempt(source, [attempts], [callback])`\nMake an attempt with a source ID\n\n- `source` [`string`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) Unique source identifier (e.g. username, IP, etc.)\n- `attempts` [`number`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type) The number of attempts to make. Default: `1`\n- `callback` [`function`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function) Callback function\n  - `result` [`AttemptResult`](#interface-attemptresult) The result of the attempt\n  - Returns: [`void`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Undefined_type)\n- Returns: [`AttemptResult`](#interface-attemptresult)\n\n\u003ca name=\"ratelimitchecksource-callback\"\u003e\u003c/a\u003e\n### `rateLimit.check(source, [callback])`\nCheck the attempt state for a source ID without decrementing the remaining attempts\n\n- `source` [`string`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) Unique source identifier (e.g. username, IP, etc.)\n- `callback` [`function`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function) Callback function\n  - `result` [`AttemptResult`](#interface-attemptresult) The result of the attempt\n  - Returns: [`void`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Undefined_type)\n- Returns: [`AttemptResult`](#interface-attemptresult)\n\n\u003ca name=\"ratelimitclear\"\u003e\u003c/a\u003e\n### `rateLimit.clear()`\nClear rate limit attempts storage. This is equivalent to resetting all rate limits.\n\n- Returns: [`void`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Undefined_type)\n\n\u003ca name=\"ratelimitdelete\"\u003e\u003c/a\u003e\n### `rateLimit.delete()`\nDelete the rate limit instance. After it is deleted, it should not be used any further without constructing a new instance.\n\n- Returns: [`void`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Undefined_type)\n\n\u003ca name=\"ratelimitlimit\"\u003e\u003c/a\u003e\n### `rateLimit.limit`\nThe number of requests allowed per time window\n\n- Type: [`number`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type)\n\n\u003ca name=\"ratelimitname\"\u003e\u003c/a\u003e\n### `rateLimit.name`\nGet rate limit name\n\n- Type: [`string`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type)\n- Readonly\n\n\u003ca name=\"ratelimitresetsource\"\u003e\u003c/a\u003e\n### `rateLimit.reset(source)`\nReset limit for a source ID. The storage entry will be deleted and a new one will be created on the next attempt.\n\n- `source` [`string`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) Unique source identifier (e.g. username, IP, etc.)\n- Returns: [`void`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Undefined_type)\n\n\u003ca name=\"ratelimitsetremainingsource-remaining\"\u003e\u003c/a\u003e\n### `rateLimit.setRemaining(source, remaining)`\nSet the remaining attempts for a source ID.\n\n\u003e **Warning**: This is not recommended as the remaining attempts depend on the limit of the instance.\n\n- `source` [`string`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) Unique source identifier (e.g. username, IP, etc.)\n- `remaining` [`number`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type) The number of remaining attempts\n- Returns: [`void`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Undefined_type)\n\n\u003ca name=\"ratelimittimewindow\"\u003e\u003c/a\u003e\n### `rateLimit.timeWindow`\nThe time window in seconds (e.g. 60)\n\n- Type: [`number`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type)\n\n\u003ca name=\"interface-attemptresult\"\u003e\u003c/a\u003e\n## Interface: `AttemptResult`\nThe result from a rate limit attempt\n\n\u003ca name=\"attemptresultlimit\"\u003e\u003c/a\u003e\n### `attemptResult.limit`\nThe number of requests this rate limit allows per time window\n\n- Type: [`number`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type)\n- Readonly\n\n\u003ca name=\"attemptresultremaining\"\u003e\u003c/a\u003e\n### `attemptResult.remaining`\nThe number of requests remaining in the current time window\n\n- Type: [`number`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type)\n- Readonly\n\n\u003ca name=\"attemptresultreset\"\u003e\u003c/a\u003e\n### `attemptResult.reset`\nThe number of seconds until the current time window resets\n\n- Type: [`number`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type)\n- Readonly\n\n\u003ca name=\"attemptresultratelimit\"\u003e\u003c/a\u003e\n### `attemptResult.rateLimit`\nThe rate limit that this attempt was made on\n\n- Type: [`RateLimit`](#class-ratelimit)\n- Readonly\n\n\u003ca name=\"attemptresultallow\"\u003e\u003c/a\u003e\n### `attemptResult.allow`\nWhether this attempt should be allowed to proceed. If false, the attempt is rate limited.\n\n- Type: [`boolean`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type)\n- Readonly\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcloudnode-pro%2Fratelimit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcloudnode-pro%2Fratelimit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcloudnode-pro%2Fratelimit/lists"}