Skip to content
This repository was archived by the owner on Apr 15, 2025. It is now read-only.

Commit 11318c8

Browse files
author
williamd5
authored
Merge pull request #6 from cloudnode-pro/feature/callbacks
Add optional callbacks to `check()` and `attempt()`
2 parents 2db70ee + 93023c9 commit 11318c8

File tree

9 files changed

+153
-61
lines changed

9 files changed

+153
-61
lines changed

‎README.md‎

Lines changed: 24 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -39,17 +39,17 @@ If you want to reset the rate limit after a successful login, call [`rateLimit.r
3939
<summary>Table of contents</summary>
4040

4141
- [Class: `RateLimit`](#class-ratelimit)
42-
- [Static method: `RateLimit.attempt(name, source, [attempts])`](#static-method-ratelimitattemptname-source-attempts)
43-
- [Static method: `RateLimit.check(name, source)`](#static-method-ratelimitcheckname-source)
42+
- [Static method: `RateLimit.attempt(name, source, [attempts], [callback])`](#static-method-ratelimitattemptname-source-attempts-callback)
43+
- [Static method: `RateLimit.check(name, source, [callback])`](#static-method-ratelimitcheckname-source-callback)
4444
- [Static method: `RateLimit.clear(name)`](#static-method-ratelimitclearname)
4545
- [Static method: `RateLimit.create(name, limit, timeWindow)`](#static-method-ratelimitcreatename-limit-timewindow)
4646
- [Static method: `RateLimit.delete(name)`](#static-method-ratelimitdeletename)
4747
- [Static method: `RateLimit.get(name)`](#static-method-ratelimitgetname)
4848
- [Static method: `RateLimit.reset(name, source)`](#static-method-ratelimitresetname-source)
4949
- [Static method: `RateLimit.setRemaining(name, source, remaining)`](#static-method-ratelimitsetremainingname-source-remaining)
5050
- [`new RateLimit(name, limit, timeWindow)`](#new-ratelimitname-limit-timewindow)
51-
- [`rateLimit.attempt(source, [attempts])`](#ratelimitattemptsource-attempts)
52-
- [`rateLimit.check(source)`](#ratelimitchecksource)
51+
- [`rateLimit.attempt(source, [attempts], [callback])`](#ratelimitattemptsource-attempts-callback)
52+
- [`rateLimit.check(source, [callback])`](#ratelimitchecksource-callback)
5353
- [`rateLimit.clear()`](#ratelimitclear)
5454
- [`rateLimit.delete()`](#ratelimitdelete)
5555
- [`rateLimit.limit`](#ratelimitlimit)
@@ -69,22 +69,28 @@ If you want to reset the rate limit after a successful login, call [`rateLimit.r
6969
## Class: `RateLimit`
7070
Rate limit
7171

72-
<a name="static-method-ratelimitattemptname-source-attempts"></a>
73-
### Static method: `RateLimit.attempt(name, source, [attempts])`
72+
<a name="static-method-ratelimitattemptname-source-attempts-callback"></a>
73+
### Static method: `RateLimit.attempt(name, source, [attempts], [callback])`
7474
Make an attempt with a source ID
7575

7676
- `name` [`string`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) The name of the rate limit
7777
- `source` [`string`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) Unique source identifier (e.g. username, IP, etc.)
7878
- `attempts` [`number`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type) The number of attempts to make. Default: `1`
79+
- `callback` [`function`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function) Callback function. Default: `undefined`
80+
- `result` [`AttemptResult`](#interface-attemptresult) The result of the attempt
81+
- Returns: [`void`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Undefined_type)
7982
- Returns: [`AttemptResult`](#interface-attemptresult)
8083
- Throws: [`Error`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error) If the rate limit does not exist
8184

82-
<a name="static-method-ratelimitcheckname-source"></a>
83-
### Static method: `RateLimit.check(name, source)`
85+
<a name="static-method-ratelimitcheckname-source-callbac"></a>
86+
### Static method: `RateLimit.check(name, source, [callback])`
8487
Check the attempt state for a source ID without decrementing the remaining attempts
8588

8689
- `name` [`string`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) The name of the rate limit
8790
- `source` [`string`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) Unique source identifier (e.g. username, IP, etc.)
91+
- `callback` [`function`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function) Callback function. Default: `undefined`
92+
- `result` [`AttemptResult`](#interface-attemptresult) The result of the attempt
93+
- Returns: [`void`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Undefined_type)
8894
- Returns: [`AttemptResult`](#interface-attemptresult)
8995
- Throws: [`Error`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error) If the rate limit does not exist
9096

@@ -150,19 +156,25 @@ Create a new rate limit
150156
- `timeWindow` [`number`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type) The time window in seconds (e.g. 60)
151157
- Throws: [`Error`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error) If the rate limit already exists
152158

153-
<a name="ratelimitattemptsource-attempts"></a>
154-
### `rateLimit.attempt(source, [attempts])`
159+
<a name="ratelimitattemptsource-attempts-callback"></a>
160+
### `rateLimit.attempt(source, [attempts], [callback])`
155161
Make an attempt with a source ID
156162

157163
- `source` [`string`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) Unique source identifier (e.g. username, IP, etc.)
158164
- `attempts` [`number`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type) The number of attempts to make. Default: `1`
165+
- `callback` [`function`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function) Callback function
166+
- `result` [`AttemptResult`](#interface-attemptresult) The result of the attempt
167+
- Returns: [`void`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Undefined_type)
159168
- Returns: [`AttemptResult`](#interface-attemptresult)
160169

161-
<a name="ratelimitchecksource"></a>
162-
### `rateLimit.check(source)`
170+
<a name="ratelimitchecksource-callback"></a>
171+
### `rateLimit.check(source, [callback])`
163172
Check the attempt state for a source ID without decrementing the remaining attempts
164173

165174
- `source` [`string`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) Unique source identifier (e.g. username, IP, etc.)
175+
- `callback` [`function`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function) Callback function
176+
- `result` [`AttemptResult`](#interface-attemptresult) The result of the attempt
177+
- Returns: [`void`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Undefined_type)
166178
- Returns: [`AttemptResult`](#interface-attemptresult)
167179

168180
<a name="ratelimitclear"></a>

‎README.template.md‎

Lines changed: 24 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -39,17 +39,17 @@ If you want to reset the rate limit after a successful login, call [`rateLimit.r
3939
<summary>Table of contents</summary>
4040

4141
- [Class: `RateLimit`](#class-ratelimit)
42-
- [Static method: `RateLimit.attempt(name, source, [attempts])`](#static-method-ratelimitattemptname-source-attempts)
43-
- [Static method: `RateLimit.check(name, source)`](#static-method-ratelimitcheckname-source)
42+
- [Static method: `RateLimit.attempt(name, source, [attempts], [callback])`](#static-method-ratelimitattemptname-source-attempts-callback)
43+
- [Static method: `RateLimit.check(name, source, [callback])`](#static-method-ratelimitcheckname-source-callback)
4444
- [Static method: `RateLimit.clear(name)`](#static-method-ratelimitclearname)
4545
- [Static method: `RateLimit.create(name, limit, timeWindow)`](#static-method-ratelimitcreatename-limit-timewindow)
4646
- [Static method: `RateLimit.delete(name)`](#static-method-ratelimitdeletename)
4747
- [Static method: `RateLimit.get(name)`](#static-method-ratelimitgetname)
4848
- [Static method: `RateLimit.reset(name, source)`](#static-method-ratelimitresetname-source)
4949
- [Static method: `RateLimit.setRemaining(name, source, remaining)`](#static-method-ratelimitsetremainingname-source-remaining)
5050
- [`new RateLimit(name, limit, timeWindow)`](#new-ratelimitname-limit-timewindow)
51-
- [`rateLimit.attempt(source, [attempts])`](#ratelimitattemptsource-attempts)
52-
- [`rateLimit.check(source)`](#ratelimitchecksource)
51+
- [`rateLimit.attempt(source, [attempts], [callback])`](#ratelimitattemptsource-attempts-callback)
52+
- [`rateLimit.check(source, [callback])`](#ratelimitchecksource-callback)
5353
- [`rateLimit.clear()`](#ratelimitclear)
5454
- [`rateLimit.delete()`](#ratelimitdelete)
5555
- [`rateLimit.limit`](#ratelimitlimit)
@@ -69,22 +69,28 @@ If you want to reset the rate limit after a successful login, call [`rateLimit.r
6969
## Class: `RateLimit`
7070
Rate limit
7171

72-
<a name="static-method-ratelimitattemptname-source-attempts"></a>
73-
### Static method: `RateLimit.attempt(name, source, [attempts])`
72+
<a name="static-method-ratelimitattemptname-source-attempts-callback"></a>
73+
### Static method: `RateLimit.attempt(name, source, [attempts], [callback])`
7474
Make an attempt with a source ID
7575

7676
- `name` [`string`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) The name of the rate limit
7777
- `source` [`string`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) Unique source identifier (e.g. username, IP, etc.)
7878
- `attempts` [`number`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type) The number of attempts to make. Default: `1`
79+
- `callback` [`function`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function) Callback function. Default: `undefined`
80+
- `result` [`AttemptResult`](#interface-attemptresult) The result of the attempt
81+
- Returns: [`void`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Undefined_type)
7982
- Returns: [`AttemptResult`](#interface-attemptresult)
8083
- Throws: [`Error`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error) If the rate limit does not exist
8184

82-
<a name="static-method-ratelimitcheckname-source"></a>
83-
### Static method: `RateLimit.check(name, source)`
85+
<a name="static-method-ratelimitcheckname-source-callbac"></a>
86+
### Static method: `RateLimit.check(name, source, [callback])`
8487
Check the attempt state for a source ID without decrementing the remaining attempts
8588

8689
- `name` [`string`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) The name of the rate limit
8790
- `source` [`string`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) Unique source identifier (e.g. username, IP, etc.)
91+
- `callback` [`function`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function) Callback function. Default: `undefined`
92+
- `result` [`AttemptResult`](#interface-attemptresult) The result of the attempt
93+
- Returns: [`void`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Undefined_type)
8894
- Returns: [`AttemptResult`](#interface-attemptresult)
8995
- Throws: [`Error`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error) If the rate limit does not exist
9096

@@ -150,19 +156,25 @@ Create a new rate limit
150156
- `timeWindow` [`number`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type) The time window in seconds (e.g. 60)
151157
- Throws: [`Error`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error) If the rate limit already exists
152158

153-
<a name="ratelimitattemptsource-attempts"></a>
154-
### `rateLimit.attempt(source, [attempts])`
159+
<a name="ratelimitattemptsource-attempts-callback"></a>
160+
### `rateLimit.attempt(source, [attempts], [callback])`
155161
Make an attempt with a source ID
156162

157163
- `source` [`string`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) Unique source identifier (e.g. username, IP, etc.)
158164
- `attempts` [`number`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type) The number of attempts to make. Default: `1`
165+
- `callback` [`function`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function) Callback function
166+
- `result` [`AttemptResult`](#interface-attemptresult) The result of the attempt
167+
- Returns: [`void`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Undefined_type)
159168
- Returns: [`AttemptResult`](#interface-attemptresult)
160169

161-
<a name="ratelimitchecksource"></a>
162-
### `rateLimit.check(source)`
170+
<a name="ratelimitchecksource-callback"></a>
171+
### `rateLimit.check(source, [callback])`
163172
Check the attempt state for a source ID without decrementing the remaining attempts
164173

165174
- `source` [`string`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type) Unique source identifier (e.g. username, IP, etc.)
175+
- `callback` [`function`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/function) Callback function
176+
- `result` [`AttemptResult`](#interface-attemptresult) The result of the attempt
177+
- Returns: [`void`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Undefined_type)
166178
- Returns: [`AttemptResult`](#interface-attemptresult)
167179

168180
<a name="ratelimitclear"></a>

‎lib/RateLimit.d.ts‎

Lines changed: 26 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -8,82 +8,100 @@ export declare class RateLimit {
88
/**
99
* Name of the rate limit
1010
* @readonly
11+
* @type {string}
1112
*/
1213
readonly name: string;
1314
/**
1415
* The number of requests allowed per time window
16+
* @type {number}
1517
*/
1618
limit: number;
1719
/**
1820
* The time window in seconds (e.g. 60)
21+
* @type {number}
1922
*/
2023
timeWindow: number;
2124
/**
2225
* Create a new rate limit
2326
* @param {string} name - The name of the rate limit
2427
* @param {number} limit - The number of requests allowed per time window (e.g. 60)
2528
* @param {number} timeWindow - The time window in seconds (e.g. 60)
29+
* @returns {RateLimit}
2630
* @throws {Error} - If the rate limit already exists
2731
*/
2832
constructor(name: string, limit: number, timeWindow: number);
2933
/**
3034
* Check the attempt state for a source ID without decrementing the remaining attempts
3135
* @param {string} source - Unique source identifier (e.g. username, IP, etc.)
36+
* @param {function(AttemptResult): void} [callback] - Return data in a callback
37+
* @returns {AttemptResult}
3238
*/
33-
check(source: string): AttemptResult;
39+
check(source: string, callback?: (result: AttemptResult) => void): AttemptResult;
3440
/**
3541
* Make an attempt with a source ID
3642
* @param {string} source - Unique source identifier (e.g. username, IP, etc.)
3743
* @param {number} [attempts=1] - The number of attempts to make
44+
* @param {function(AttemptResult): void} [callback] - Return data in a callback
45+
* @returns {AttemptResult}
3846
*/
39-
attempt(source: string, attempts?: number): AttemptResult;
47+
attempt(source: string, attempts?: number, callback?: (result: AttemptResult) => void): AttemptResult;
4048
/**
4149
* Reset limit for a source ID. The storage entry will be deleted and a new one will be created on the next attempt.
4250
* @param {string} source - Unique source identifier (e.g. username, IP, etc.)
51+
* @returns {void}
4352
*/
4453
reset(source: string): void;
4554
/**
4655
* Set the remaining attempts for a source ID.
4756
* > **Warning**: This is not recommended as the remaining attempts depend on the limit of the instance.
4857
* @param {string} source - Unique source identifier (e.g. username, IP, etc.)
4958
* @param {number} remaining - The number of remaining attempts
59+
* @returns {void}
5060
*/
5161
setRemaining(source: string, remaining: number): void;
5262
/**
5363
* Clear rate limit attempts storage. This is equivalent to resetting all rate limits.
64+
* @returns {void}
5465
*/
5566
clear(): void;
5667
/**
5768
* Delete the rate limit instance. After it is deleted, it should not be used any further without constructing a new instance.
69+
* @returns {void}
5870
*/
5971
delete(): void;
6072
/**
6173
* Get a rate limit instance
6274
* @param {string} name - The name of the rate limit
75+
* @returns {RateLimit | null}
6376
* @static
6477
*/
6578
static get(name: string): RateLimit | null;
6679
/**
6780
* Check the attempt state for a source ID without decrementing the remaining attempts
6881
* @param {string} name - The name of the rate limit
6982
* @param {string} source - Unique source identifier (e.g. username, IP, etc.)
83+
* @param {function(AttemptResult): void} [callback] - Return data in a callback
84+
* @returns {AttemptResult}
7085
* @throws {Error} - If the rate limit does not exist
7186
* @static
7287
*/
73-
static check(name: string, source: string): AttemptResult;
88+
static check(name: string, source: string, callback?: (result: AttemptResult) => void): AttemptResult;
7489
/**
7590
* Make an attempt with a source ID
7691
* @param {string} name - The name of the rate limit
7792
* @param {string} source - Unique source identifier (e.g. username, IP, etc.)
7893
* @param {number} [attempts=1] - The number of attempts to make
94+
* @param {function(AttemptResult): void} [callback] - Return data in a callback
95+
* @returns {AttemptResult}
7996
* @throws {Error} - If the rate limit does not exist
8097
* @static
8198
*/
82-
static attempt(name: string, source: string, attempts?: number): AttemptResult;
99+
static attempt(name: string, source: string, attempts?: number, callback?: (result: AttemptResult) => void): AttemptResult;
83100
/**
84101
* Reset limit for a source ID. The storage entry will be deleted and a new one will be created on the next attempt.
85102
* @param {string} name - The name of the rate limit
86103
* @param {string} source - Unique source identifier (e.g. username, IP, etc.)
104+
* @returns {void}
87105
* @throws {Error} - If the rate limit does not exist
88106
* @static
89107
*/
@@ -94,20 +112,23 @@ export declare class RateLimit {
94112
* @param {string} name - The name of the rate limit
95113
* @param {string} source - Unique source identifier (e.g. username, IP, etc.)
96114
* @param {number} remaining - The number of remaining attempts
115+
* @returns {void}
97116
* @throws {Error} - If the rate limit does not exist
98117
* @static
99118
*/
100119
static setRemaining(name: string, source: string, remaining: number): void;
101120
/**
102121
* Clear rate limit attempts storage. This is equivalent to resetting all rate limits.
103122
* @param {string} name - The name of the rate limit
123+
* @returns {void}
104124
* @throws {Error} - If the rate limit does not exist
105125
* @static
106126
*/
107127
static clear(name: string): void;
108128
/**
109129
* Delete the rate limit instance. After it is deleted, it should not be used any further without constructing a new instance.
110130
* @param {string} name - The name of the rate limit
131+
* @returns {void}
111132
* @throws {Error} - If the rate limit does not exist
112133
* @static
113134
*/
@@ -117,6 +138,7 @@ export declare class RateLimit {
117138
* @param {string} name - The name of the rate limit
118139
* @param {number} limit - The number of attempts allowed per time window (e.g. 60)
119140
* @param {number} timeWindow - The time window in seconds (e.g. 60)
141+
* @returns {RateLimit}
120142
* @static
121143
*/
122144
static create(name: string, limit: number, timeWindow: number): RateLimit;

0 commit comments

Comments
 (0)