docs: add docblocks

Author: thetutlage

src/define_config.ts

@@ -26,12 +26,23 @@ import type {
 } from './types.ts'
 
 /**
- * Helper to define limiter config. This function exports a
- * config provider and hence you cannot access raw config
- * directly.
+ * Defines the limiter configuration for your AdonisJS application.
+ * This function returns a config provider that resolves store configurations lazily.
  *
- * Therefore use the "limiterManager.config" property to access
- * raw config.
+ * To access the resolved config at runtime, use the `limiterManager.config` property.
+ *
+ * @param config - Configuration object with default store and stores collection
+ *
+ * @example
+ * ```ts
+ * export default defineConfig({
+ *   default: 'redis',
+ *   stores: {
+ *     redis: stores.redis({}),
+ *     memory: stores.memory({})
+ *   }
+ * })
+ * ```
  */
 export function defineConfig<
   KnownStores extends Record<
@@ -107,12 +118,34 @@ export function defineConfig<
 }
 
 /**
- * Config helpers to instantiate limiter stores inside
- * an AdonisJS application
+ * Store configuration helpers to instantiate limiter stores in your AdonisJS application.
+ * Each helper returns a factory function that creates store instances with consumption options.
+ *
+ * @example
+ * ```ts
+ * export default defineConfig({
+ *   default: 'redis',
+ *   stores: {
+ *     redis: stores.redis({ connectionName: 'main' }),
+ *     database: stores.database({ tableName: 'rate_limits' }),
+ *     memory: stores.memory({})
+ *   }
+ * })
+ * ```
  */
 export const stores: {
   /**
-   * Configure redis limiter store
+   * Configures a Redis-backed limiter store.
+   *
+   * @param config - Redis store configuration
+   *
+   * @example
+   * ```ts
+   * stores.redis({
+   *   connectionName: 'main',
+   *   keyPrefix: 'limiter'
+   * })
+   * ```
    */
   redis: (
     config: Omit<LimiterRedisStoreConfig, keyof LimiterConsumptionOptions> & {
@@ -121,7 +154,17 @@ export const stores: {
   ) => ConfigProvider<LimiterManagerStoreFactory>
 
   /**
-   * Configure database limiter store
+   * Configures a database-backed limiter store. Supports PostgreSQL, MySQL, and SQLite.
+   *
+   * @param config - Database store configuration
+   *
+   * @example
+   * ```ts
+   * stores.database({
+   *   tableName: 'rate_limits',
+   *   connectionName: 'postgres'
+   * })
+   * ```
    */
   database: (
     config: Omit<LimiterDatabaseStoreConfig, keyof LimiterConsumptionOptions> & {
@@ -130,7 +173,16 @@ export const stores: {
   ) => ConfigProvider<LimiterManagerStoreFactory>
 
   /**
-   * Configure memory limiter store
+   * Configures an in-memory limiter store. Useful for testing or single-instance applications.
+   *
+   * @param config - Memory store configuration
+   *
+   * @example
+   * ```ts
+   * stores.memory({
+   *   keyPrefix: 'limiter'
+   * })
+   * ```
    */
   memory: (
     config: Omit<LimiterMemoryStoreConfig, keyof LimiterConsumptionOptions>

src/errors.ts

@@ -15,7 +15,10 @@ import type { LimiterResponse } from './response.ts'
 
 /**
  * Throttle exception is raised when the user has exceeded
- * the number of requests allowed during a given duration
+ * the number of requests allowed during a given duration.
+ *
+ * The exception automatically sets appropriate HTTP headers and
+ * formats the response based on the request's Accept header.
  */
 export class ThrottleException extends Exception {
   message = 'Too many requests'
@@ -53,7 +56,8 @@ export class ThrottleException extends Exception {
   }
 
   /**
-   * Returns the default headers for the response
+   * Returns the default rate limit headers that will be sent in the HTTP response.
+   * Includes limit information, remaining requests, retry-after time, and reset time.
    */
   getDefaultHeaders(): { [K: string]: any } {
     return {
@@ -66,8 +70,9 @@ export class ThrottleException extends Exception {
 
   /**
    * Returns the message to be sent in the HTTP response.
-   * Feel free to override this method and return a custom
-   * response.
+   * Supports i18n translations when the i18n package is available.
+   *
+   * @param ctx - The HTTP context
    */
   getResponseMessage(ctx: HttpContext) {
     /**
@@ -87,40 +92,80 @@ export class ThrottleException extends Exception {
   }
 
   /**
-   * Update the default error message
+   * Updates the default error message.
+   *
+   * @param message - The new error message
+   *
+   * @example
+   * ```ts
+   * throw new ThrottleException(response)
+   *   .setMessage('Rate limit exceeded. Please try again later.')
+   * ```
    */
   setMessage(message: string): this {
     this.message = message
     return this
   }
 
   /**
-   * Update the default error status code
+   * Updates the default error status code.
+   *
+   * @param status - The HTTP status code
+   *
+   * @example
+   * ```ts
+   * throw new ThrottleException(response)
+   *   .setStatus(503)
+   * ```
    */
   setStatus(status: number): this {
     this.status = status
     return this
   }
 
   /**
-   * Define custom response headers. Existing headers will
-   * be removed
+   * Defines custom response headers. This will replace the default headers.
+   *
+   * @param headers - Custom headers to set
+   *
+   * @example
+   * ```ts
+   * throw new ThrottleException(response)
+   *   .setHeaders({
+   *     'X-Custom-Header': 'value',
+   *     'Retry-After': 60
+   *   })
+   * ```
    */
   setHeaders(headers: { [name: string]: any }): this {
     this.headers = headers
     return this
   }
 
   /**
-   * Define the translation identifier for the throttle response
+   * Defines the i18n translation identifier for the throttle response message.
+   *
+   * @param identifier - The translation key
+   * @param data - Optional translation data
+   *
+   * @example
+   * ```ts
+   * throw new ThrottleException(response)
+   *   .t('errors.rate_limit_exceeded', { minutes: 5 })
+   * ```
    */
   t(identifier: string, data?: Record<string, any>) {
     this.translation = { identifier, data }
     return this
   }
 
   /**
-   * Converts the throttle exception to an HTTP response
+   * Converts the throttle exception to an HTTP response.
+   * Automatically sets appropriate headers and formats the response
+   * based on the Accept header (HTML, JSON, or JSON:API).
+   *
+   * @param error - The throttle exception instance
+   * @param ctx - The HTTP context
    */
   async handle(error: ThrottleException, ctx: HttpContext) {
     const status = error.status

src/http_limiter.ts

@@ -17,9 +17,8 @@ import { E_TOO_MANY_REQUESTS, type ThrottleException } from './errors.ts'
 import type { LimiterConsumptionOptions, LimiterManagerStoreFactory } from './types.ts'
 
 /**
- * HttpLimiter is a special type of limiter instance created specifically
- * for HTTP requests. It exposes a single method to throttle the request
- * using the request ip address or the pre-defined unique key.
+ * HTTP rate limiter with a fluent API for configuring rate limiting on HTTP requests.
+ * Automatically uses the request IP address as the key unless a custom key is specified.
  */
 export class HttpLimiter<KnownStores extends Record<string, LimiterManagerStoreFactory>> {
   /**
@@ -56,62 +55,116 @@ export class HttpLimiter<KnownStores extends Record<string, LimiterManagerStoreF
   }
 
   /**
-   * Specify the store you want to use during
-   * the request
+   * Specifies which store to use for this rate limiter.
+   *
+   * @param store - Name of the configured store
+   *
+   * @example
+   * ```ts
+   * limiter
+   *   .allowRequests(100)
+   *   .every('1 hour')
+   *   .store('redis')
+   * ```
    */
   store(store: keyof KnownStores) {
     this.#store = store
     return this
   }
 
   /**
-   * Specify the number of requests to allow
+   * Sets the number of requests to allow during the specified duration.
+   *
+   * @param requests - Maximum number of requests
+   *
+   * @example
+   * ```ts
+   * limiter.allowRequests(100)
+   * ```
    */
   allowRequests(requests: number) {
     this.#options.requests = requests
     return this
   }
 
   /**
-   * Specify the duration in seconds or a time expression
-   * for which the requests to allow.
+   * Sets the duration window for the rate limit.
    *
-   * For example: allowRequests(10).every('1 minute')
+   * @param duration - Duration in seconds or time expression (e.g., '1 minute', '1 hour')
+   *
+   * @example
+   * ```ts
+   * limiter.allowRequests(100).every('1 hour')
+   * limiter.allowRequests(10).every(60) // 60 seconds
+   * ```
    */
   every(duration: number | string) {
     this.#options.duration = duration
     return this
   }
 
   /**
-   * Specify a custom unique key to identify the user.
-   * Defaults to: request.ip()
+   * Sets a custom key to uniquely identify the requester.
+   * By default, the request IP address is used.
+   *
+   * @param key - Custom identifier (e.g., user ID, API key)
+   *
+   * @example
+   * ```ts
+   * limiter
+   *   .allowRequests(100)
+   *   .every('1 hour')
+   *   .usingKey(ctx.auth.user.id)
+   * ```
    */
   usingKey(key: string | number) {
     this.#key = key
     return this
   }
 
   /**
-   * Register a callback function to modify the ThrottleException.
+   * Registers a callback to customize the ThrottleException before it's thrown.
+   * Useful for setting custom error messages or translations.
+   *
+   * @param callback - Function to modify the exception
+   *
+   * @example
+   * ```ts
+   * limiter
+   *   .allowRequests(100)
+   *   .every('1 hour')
+   *   .limitExceeded((error) => {
+   *     error.setMessage('Too many requests. Please slow down!')
+   *     error.t('errors.rate_limit_exceeded')
+   *   })
+   * ```
    */
   limitExceeded(callback: (error: ThrottleException) => void) {
     this.#exceptionModifier = callback
     return this
   }
 
   /**
-   * Define the block duration. The key will be blocked for the
-   * specified duration after all the requests have been
-   * exhausted
+   * Sets the block duration to penalize users who exceed the rate limit.
+   * The key will be blocked for this duration after exhausting all requests.
+   *
+   * @param duration - Block duration in seconds or time expression
+   *
+   * @example
+   * ```ts
+   * limiter
+   *   .allowRequests(100)
+   *   .every('1 hour')
+   *   .blockFor('15 mins')
+   * ```
    */
   blockFor(duration: number | string): this {
     this.#options.blockDuration = duration
     return this
   }
 
   /**
-   * JSON representation of the HTTP limiter
+   * Returns a JSON representation of the HTTP limiter configuration.
    */
   toJSON() {
     return {
@@ -121,9 +174,17 @@ export class HttpLimiter<KnownStores extends Record<string, LimiterManagerStoreF
   }
 
   /**
-   * Throttle request using the pre-defined options. Returns
-   * LimiterResponse when request is allowed or throws
-   * an exception.
+   * Throttles the HTTP request using the configured options.
+   * Throws a ThrottleException if the rate limit is exceeded.
+   *
+   * @param prefix - Key prefix to namespace the limiter
+   * @param ctx - HTTP context
+   *
+   * @example
+   * ```ts
+   * const response = await httpLimiter.throttle('api', ctx)
+   * console.log(`Remaining: ${response.remaining}`)
+   * ```
    */
   async throttle(prefix: string, ctx: HttpContext): Promise<LimiterResponse> {
     if (!this.#options.requests || !this.#options.duration) {