@limitkit/core 1.0.0 → 1.0.2

package/README.md

@@ -200,35 +200,34 @@ In the snippet below, assuming the `/report` endpoint performs expensive computa
 
 ```ts
 interface RateLimitResult {
-  allowed: boolean,
-  limit: number,
-  remaining: number,
-  reset: number,
-  retryAt?: number
+  allowed: boolean;
   failedAt: string | null;
-  details: (RateLimitResult & { name: string })[]
+  rules: IdentifiedRateLimitRuleResult[]
 }
 ```
 
 | Field        | Meaning                            |
 | ------------ | ---------------------------------- |
 | `allowed`    | request permitted or blocked       |
-| `limit`      | maximum requests allowed           |
-| `remaining`  | remaining quota                    |
-| `reset`      | timestamp (ms) when quota fully resets   |
-| `retryAt` | seconds until next allowed request |
 | `failedAt`   | the name of the rule failed, `null` if every rule passes |
-| `details`   | an array of results for each rule evaluated and the rule's name |
-
-When the request is allowed:
-* The `limit` is the **minimum** of all the rules.
-* The `remaining` is the **minimum** of all the rules.
-* The `reset` is the **maximum** of all the rules.
+| `rules`      | an array containing the results of all evaluated rules |
 
+The result of each evaluated rule is represented as `IdentifiedRateLimitRuleResult` interface:
 
 ```ts
-interface DebugLimitResult extends RateLimitResult {
-  failedAt: string | null;
-  details: (RateLimitResult & { name: string })[];
+interface IdentifiedRateLimitRuleResult {
+  allowed: boolean;
+  limit: number;
+  remaining: number;
+  resetAt: number;
+  retryAt?: number;
 }
-```
+```
+
+| Field        | Meaning                            |
+| ------------ | ---------------------------------- |
+| `allowed`    | request permitted or blocked by the rule      |
+| `limit`   | the maximum number of requests allowed by the rule |
+| `remaining`      | the remaining number of requests allowed by the rule |
+| `resetAt`      | the Unix timestamp (ms) after which the limit for the rule fully resets |
+| `retryAt`      | the Unix timestamp (ms) after which the request is allowed by the rule (`undefined` when allowed) |

package/dist/index.d.mts

@@ -278,8 +278,8 @@ interface RateLimitConfig<C = unknown> {
 /**
  * Core rate limiter implementation that enforces rate limiting rules.
  *
- * The RateLimiter evaluates rules in order and returns the result of the first rule
- * that limits the request. If all rules allow the request, it returns a positive result.
+ * The RateLimiter evaluates rules in order and stops if a rule fails.
+ * The request is allowed if every rule passes.
  *
  * Use cases:
  * - API rate limiting (requests per second/minute)
@@ -305,7 +305,7 @@ interface RateLimitConfig<C = unknown> {
  *
  * const result = await limiter.consume({ userId: 'user-123' });
  * if (!result.allowed) {
- *   return 429 with headers: Retry-After: result.retryAt
+ *   return 429
  * }
  * ```
  * @see Limiter
@@ -330,8 +330,9 @@ declare class RateLimiter<C = unknown> implements Limiter<C> {
     /**
      * Check if a request should be allowed under the configured rate limits.
      *
-     * Evaluates each rule in order from left to right. Returns the result of the failed rule as soon as a rule is exceeded (request denied).
-     * If all rules allow the request, returns the result aggregated from all the rules.
+     * Evaluates each rule in order from left to right.
+     * If a rule fails, remaining rules won't be evaluated and the request is rejected.
+     *
      *
      * Each rule resolution (key, cost, policy) can be static or dynamic:
      * - Static: evaluated once and reused
@@ -340,8 +341,6 @@ declare class RateLimiter<C = unknown> implements Limiter<C> {
      *
      *
      * @param ctx - Request context passed to rule resolvers to determine dynamic values.
-     * @returns Promise resolving to the rate limit result. If debug mode is enabled,
-     *          includes details about each evaluated rule and which rule failed (if any).
      *
      * @example
      * ```typescript
@@ -356,7 +355,14 @@ declare class RateLimiter<C = unknown> implements Limiter<C> {
      * }
      * ```
      *
+     * @returns {RateLimitResult} an object containing:
+     * - `allowed` (boolean): whether the request is allowed
+     * - `failedRule` (string): the name of the failed rule, `null` if every rule passes
+     * - `rules` ({@link IdentifiedRateLimitRuleResult}): details of all the rules evaluated
+     *
      * @throws UndefinedKeyException if the key is empty or undefined
+     *
+     * @see RateLimitResult
      */
     consume(ctx: C): Promise<RateLimitResult>;
 }

package/dist/index.d.ts

@@ -278,8 +278,8 @@ interface RateLimitConfig<C = unknown> {
 /**
  * Core rate limiter implementation that enforces rate limiting rules.
  *
- * The RateLimiter evaluates rules in order and returns the result of the first rule
- * that limits the request. If all rules allow the request, it returns a positive result.
+ * The RateLimiter evaluates rules in order and stops if a rule fails.
+ * The request is allowed if every rule passes.
  *
  * Use cases:
  * - API rate limiting (requests per second/minute)
@@ -305,7 +305,7 @@ interface RateLimitConfig<C = unknown> {
  *
  * const result = await limiter.consume({ userId: 'user-123' });
  * if (!result.allowed) {
- *   return 429 with headers: Retry-After: result.retryAt
+ *   return 429
  * }
  * ```
  * @see Limiter
@@ -330,8 +330,9 @@ declare class RateLimiter<C = unknown> implements Limiter<C> {
     /**
      * Check if a request should be allowed under the configured rate limits.
      *
-     * Evaluates each rule in order from left to right. Returns the result of the failed rule as soon as a rule is exceeded (request denied).
-     * If all rules allow the request, returns the result aggregated from all the rules.
+     * Evaluates each rule in order from left to right.
+     * If a rule fails, remaining rules won't be evaluated and the request is rejected.
+     *
      *
      * Each rule resolution (key, cost, policy) can be static or dynamic:
      * - Static: evaluated once and reused
@@ -340,8 +341,6 @@ declare class RateLimiter<C = unknown> implements Limiter<C> {
      *
      *
      * @param ctx - Request context passed to rule resolvers to determine dynamic values.
-     * @returns Promise resolving to the rate limit result. If debug mode is enabled,
-     *          includes details about each evaluated rule and which rule failed (if any).
      *
      * @example
      * ```typescript
@@ -356,7 +355,14 @@ declare class RateLimiter<C = unknown> implements Limiter<C> {
      * }
      * ```
      *
+     * @returns {RateLimitResult} an object containing:
+     * - `allowed` (boolean): whether the request is allowed
+     * - `failedRule` (string): the name of the failed rule, `null` if every rule passes
+     * - `rules` ({@link IdentifiedRateLimitRuleResult}): details of all the rules evaluated
+     *
      * @throws UndefinedKeyException if the key is empty or undefined
+     *
+     * @see RateLimitResult
      */
     consume(ctx: C): Promise<RateLimitResult>;
 }

package/dist/index.js

@@ -107,8 +107,9 @@ var RateLimiter = class {
   /**
    * Check if a request should be allowed under the configured rate limits.
    *
-   * Evaluates each rule in order from left to right. Returns the result of the failed rule as soon as a rule is exceeded (request denied).
-   * If all rules allow the request, returns the result aggregated from all the rules.
+   * Evaluates each rule in order from left to right.
+   * If a rule fails, remaining rules won't be evaluated and the request is rejected.
+   *
    *
    * Each rule resolution (key, cost, policy) can be static or dynamic:
    * - Static: evaluated once and reused
@@ -117,8 +118,6 @@ var RateLimiter = class {
    *
    *
    * @param ctx - Request context passed to rule resolvers to determine dynamic values.
-   * @returns Promise resolving to the rate limit result. If debug mode is enabled,
-   *          includes details about each evaluated rule and which rule failed (if any).
    *
    * @example
    * ```typescript
@@ -133,7 +132,14 @@ var RateLimiter = class {
    * }
    * ```
    *
+   * @returns {RateLimitResult} an object containing:
+   * - `allowed` (boolean): whether the request is allowed
+   * - `failedRule` (string): the name of the failed rule, `null` if every rule passes
+   * - `rules` ({@link IdentifiedRateLimitRuleResult}): details of all the rules evaluated
+   *
    * @throws UndefinedKeyException if the key is empty or undefined
+   *
+   * @see RateLimitResult
    */
   async consume(ctx) {
     const evaluatedRules = [];

package/dist/index.mjs

@@ -70,8 +70,9 @@ var RateLimiter = class {
   /**
    * Check if a request should be allowed under the configured rate limits.
    *
-   * Evaluates each rule in order from left to right. Returns the result of the failed rule as soon as a rule is exceeded (request denied).
-   * If all rules allow the request, returns the result aggregated from all the rules.
+   * Evaluates each rule in order from left to right.
+   * If a rule fails, remaining rules won't be evaluated and the request is rejected.
+   *
    *
    * Each rule resolution (key, cost, policy) can be static or dynamic:
    * - Static: evaluated once and reused
@@ -80,8 +81,6 @@ var RateLimiter = class {
    *
    *
    * @param ctx - Request context passed to rule resolvers to determine dynamic values.
-   * @returns Promise resolving to the rate limit result. If debug mode is enabled,
-   *          includes details about each evaluated rule and which rule failed (if any).
    *
    * @example
    * ```typescript
@@ -96,7 +95,14 @@ var RateLimiter = class {
    * }
    * ```
    *
+   * @returns {RateLimitResult} an object containing:
+   * - `allowed` (boolean): whether the request is allowed
+   * - `failedRule` (string): the name of the failed rule, `null` if every rule passes
+   * - `rules` ({@link IdentifiedRateLimitRuleResult}): details of all the rules evaluated
+   *
    * @throws UndefinedKeyException if the key is empty or undefined
+   *
+   * @see RateLimitResult
    */
   async consume(ctx) {
     const evaluatedRules = [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@limitkit/core",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",