axios-rate-limit 1.3.3 → 1.5.0

package/README.md

@@ -23,21 +23,28 @@ npm install axios-rate-limit
 import axios from 'axios';
 import rateLimit from 'axios-rate-limit';
 
-// sets max 2 requests per 1 second, other will be delayed
-// note maxRPS is a shorthand for perMilliseconds: 1000, and it takes precedence
-// if specified both with maxRequests and perMilliseconds
-const http = rateLimit(axios.create(), { maxRequests: 2, perMilliseconds: 1000, maxRPS: 2 })
-http.getMaxRPS() // 2
-http.get('https://example.com/api/v1/users.json?page=1') // will perform immediately
-http.get('https://example.com/api/v1/users.json?page=2') // will perform immediately
-http.get('https://example.com/api/v1/users.json?page=3') // will perform after 1 second from the first one
-
-// options hot-reloading also available
+const http = rateLimit(axios.create(), {
+  limits: [
+    { maxRequests: 5, duration: '2s' },
+    { maxRequests: 2, duration: '500ms' }
+  ]
+})
+http.get('https://example.com/api/v1/users.json?page=1')
+http.getQueue()
+
+// options hot-reloading (same options as constructor)
 http.setMaxRPS(3)
 http.getMaxRPS() // 3
-http.setRateLimitOptions({ maxRequests: 6, perMilliseconds: 150 }) // same options as constructor
+http.setRateLimitOptions({ maxRequests: 6, perMilliseconds: 150 })
+http.setRateLimitOptions({ maxRequests: 10, duration: '1s' })
+http.setRateLimitOptions({ limits: [{ maxRequests: 3, duration: '1s' }, { maxRequests: 1, duration: '200ms' }] })
 ```
 
+## Tech Details
+
+The axios-rate-limit implements fixed-window, queued rate limiter. The main disadvantage of this
+approach is possibility of bursts at window boundaries in case of limit hit.
+
 ## Alternatives
 
 Consider using Axios built-in [rate-limiting](https://www.npmjs.com/package/axios#user-content--rate-limiting) functionality.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "axios-rate-limit",
-  "description": "Rate limit for axios.",
-  "version": "1.3.3",
+  "description": "Rate limit for axios",
+  "version": "1.5.0",
   "license": "MIT",
   "bugs": {
     "url": "https://github.com/aishek/axios-rate-limit/issues"

package/src/index.js

@@ -1,6 +1,100 @@
+var DURATION_MSG = " Expected format: number+unit ms, s, m, h (e.g. '1s')."
+
+var DURATION_UNITS = { ms: 1, s: 1000, m: 60000, h: 3600000 }
+
+function throwDurationError (value) {
+  var msg = "Unrecognized duration: '" + String(value) + "'." + DURATION_MSG
+  throw new Error(msg)
+}
+
+function parseDuration (value) {
+  if (typeof value === 'number' && !isNaN(value)) {
+    if (value < 0) throwDurationError(value)
+    return value
+  }
+  if (typeof value !== 'string') {
+    throwDurationError(value)
+  }
+  var s = value.trim()
+  var num
+  var mult
+  if (s.length >= 2 && s.slice(-2) === 'ms') {
+    num = parseFloat(s.slice(0, -2))
+    mult = DURATION_UNITS.ms
+  } else if (s.length >= 1) {
+    var u = s.slice(-1)
+    mult = DURATION_UNITS[u]
+    if (mult == null) throwDurationError(value)
+    num = parseFloat(s.slice(0, -1))
+  } else {
+    throwDurationError(value)
+  }
+  if (isNaN(num) || num < 0) {
+    throwDurationError(value)
+  }
+  return num * mult
+}
+
+function buildWindows (options) {
+  var limits = options && options.limits
+  if (limits && limits.length > 0) {
+    return limits.map(function (limit, i) {
+      var max = limit.maxRequests
+      if (typeof max !== 'number' || !isFinite(max) || max <= 0) {
+        throw new Error(
+          'Invalid rate limit option at limits[' + i + ']: ' +
+          'maxRequests is required and must be a positive number.'
+        )
+      }
+      var perMs = parseDuration(limit.duration)
+      if (typeof perMs !== 'number' || !isFinite(perMs) || perMs <= 0) {
+        throw new Error(
+          'Invalid rate limit option at limits[' + i + ']: ' +
+          'duration must be a positive finite number.'
+        )
+      }
+      return { count: 0, max: max, perMs: perMs, timeoutId: null }
+    })
+  }
+  var maxRequests = options.maxRequests
+  var perMs
+  if (options.maxRPS != null) {
+    maxRequests = options.maxRPS
+    perMs = 1000
+  } else {
+    var optD = options.duration
+    perMs = optD != null ? parseDuration(optD) : options.perMilliseconds
+  }
+  if (typeof perMs !== 'number' || !isFinite(perMs) || perMs <= 0) {
+    throw new Error(
+      'Invalid rate limit options: one of maxRPS, duration, or ' +
+      'perMilliseconds is required and must be positive.'
+    )
+  }
+  var maxInvalid = typeof maxRequests !== 'number' ||
+    !isFinite(maxRequests) || maxRequests <= 0
+  if (maxInvalid) {
+    throw new Error(
+      'Invalid rate limit options: maxRequests is required and ' +
+      'must be a positive number.'
+    )
+  }
+  return [{ count: 0, max: maxRequests, perMs: perMs, timeoutId: null }]
+}
+
+function clearWindowsTimeouts (windows) {
+  if (!windows) return
+  for (var i = 0; i < windows.length; i++) {
+    if (windows[i].timeoutId != null) {
+      clearTimeout(windows[i].timeoutId)
+      windows[i].timeoutId = null
+    }
+  }
+}
+
 function AxiosRateLimit (axios) {
   this.queue = []
-  this.timeslotRequests = 0
+  this.windows = []
 
   this.interceptors = {
     request: null,
@@ -14,8 +108,13 @@ function AxiosRateLimit (axios) {
 }
 
 AxiosRateLimit.prototype.getMaxRPS = function () {
-  var perSeconds = (this.perMilliseconds / 1000)
-  return this.maxRequests / perSeconds
+  var w = this.windows[0]
+  if (!w) return 0
+  return w.max / (w.perMs / 1000)
+}
+
+AxiosRateLimit.prototype.getQueue = function () {
+  return this.queue
 }
 
 AxiosRateLimit.prototype.setMaxRPS = function (rps) {
@@ -26,12 +125,11 @@ AxiosRateLimit.prototype.setMaxRPS = function (rps) {
 }
 
 AxiosRateLimit.prototype.setRateLimitOptions = function (options) {
-  if (options.maxRPS) {
-    this.setMaxRPS(options.maxRPS)
-  } else {
-    this.perMilliseconds = options.perMilliseconds
-    this.maxRequests = options.maxRequests
-  }
+  if (!options) return
+  var newWindows = buildWindows(options)
+  clearWindowsTimeouts(this.windows)
+  this.windows = newWindows
+  this.shift()
 }
 
 AxiosRateLimit.prototype.enable = function (axios) {
@@ -96,34 +194,40 @@ AxiosRateLimit.prototype.shiftInitial = function () {
 
 AxiosRateLimit.prototype.shift = function () {
   if (!this.queue.length) return
-  if (this.timeslotRequests === this.maxRequests) {
-    if (this.timeoutId && typeof this.timeoutId.ref === 'function') {
-      this.timeoutId.ref()
+  var windows = this.windows
+  for (var i = 0; i < windows.length; i++) {
+    if (windows[i].count === windows[i].max) {
+      var tid = windows[i].timeoutId
+      if (tid && typeof tid.ref === 'function') {
+        tid.ref()
+      }
+      return
     }
-
-    return
   }
 
   var queued = this.queue.shift()
   var resolved = queued.resolve()
 
-  if (this.timeslotRequests === 0) {
-    this.timeoutId = setTimeout(function () {
-      this.timeslotRequests = 0
-      this.shift()
-    }.bind(this), this.perMilliseconds)
-
-    if (typeof this.timeoutId.unref === 'function') {
-      if (this.queue.length === 0) this.timeoutId.unref()
-    }
-  }
-
   if (!resolved) {
-    this.shift() // rejected request --> shift another request
+    this.shift()
     return
   }
 
-  this.timeslotRequests += 1
+  var self = this
+  for (var j = 0; j < windows.length; j++) {
+    var w = windows[j]
+    w.count += 1
+    if (w.count === 1) {
+      w.timeoutId = setTimeout(function (win) {
+        win.count = 0
+        win.timeoutId = null
+        self.shift()
+      }.bind(null, w), w.perMs)
+      if (typeof w.timeoutId.unref === 'function') {
+        if (this.queue.length === 0) w.timeoutId.unref()
+      }
+    }
+  }
 }
 
 /**
@@ -153,8 +257,11 @@ AxiosRateLimit.prototype.shift = function () {
  */
 function axiosRateLimit (axios, options) {
   var rateLimitInstance = new AxiosRateLimit(axios)
-  rateLimitInstance.setRateLimitOptions(options)
+  if (options != null) {
+    rateLimitInstance.setRateLimitOptions(options)
+  }
 
+  axios.getQueue = AxiosRateLimit.prototype.getQueue.bind(rateLimitInstance)
   axios.getMaxRPS = AxiosRateLimit.prototype.getMaxRPS.bind(rateLimitInstance)
   axios.setMaxRPS = AxiosRateLimit.prototype.setMaxRPS.bind(rateLimitInstance)
   axios.setRateLimitOptions = AxiosRateLimit.prototype.setRateLimitOptions

package/typings/index.d.ts

@@ -1,21 +1,33 @@
 import { AxiosInstance } from 'axios';
 
+export type RateLimitRequestHandler = {
+  resolve: () => boolean
+}
+
 export interface RateLimitedAxiosInstance extends AxiosInstance {
-   getMaxRPS: () => number,
-   setMaxRPS: (rps: number) => void,
-   setRateLimitOptions: (options: rateLimitOptions) => void,
-   // enable(axios: any): void,
-   // handleRequest(request:any):any,
-   // handleResponse(response: any): any,
-   // push(requestHandler:any):any,
-   // shiftInitial():any,
-   // shift():any
+    getQueue: () => RateLimitRequestHandler[],
+    getMaxRPS: () => number,
+    setMaxRPS: (rps: number) => void,
+    setRateLimitOptions: (options?: rateLimitOptions) => void,
+    // enable(axios: any): void,
+    // handleRequest(request:any):any,
+    // handleResponse(response: any): any,
+    // push(requestHandler:any):any,
+    // shiftInitial():any,
+    // shift():any
 }
 
+export type RateLimitEntry = {
+    maxRequests: number,
+    duration: string | number
+};
+
 export type rateLimitOptions = {
     maxRequests?: number,
     perMilliseconds?: number,
-    maxRPS?: number
+    maxRPS?: number,
+    duration?: string | number,
+    limits?: RateLimitEntry[]
 };
 
  /**
@@ -45,5 +57,5 @@ export type rateLimitOptions = {
   */
 export default function axiosRateLimit(
     axiosInstance: AxiosInstance,
-    options: rateLimitOptions
+    options?: rateLimitOptions
 ): RateLimitedAxiosInstance;