@limitkit/core 0.1.6 → 1.0.0

package/README.md

@@ -1,117 +1,234 @@
-# @limitkit/core
+# 📦 `@limitkit/core`
 
-Core rate limiting engine for **LimitKit**.
+[![npm version](https://img.shields.io/npm/v/@limitkit/core)](https://www.npmjs.com/package/@limitkit/core)
+[![downloads](https://img.shields.io/npm/dw/@limitkit/core)](https://www.npmjs.com/package/@limitkit/core)
+[![license](https://img.shields.io/npm/l/@limitkit/core)](https://github.com/alphatrann/limitkit/blob/main/LICENSE)
 
-Provides the `RateLimiter`, rule system, and algorithm abstractions used by all LimitKit integrations.
+**The core rate limiting engine for LimitKit.**
 
-👉 Main project: https://github.com/alphatrann/limitkit
+`@limitkit/core` evaluates **rules and policies** to decide whether a request should be allowed or rejected.
+It is **store-agnostic** and works with multiple storage backends in any context.
+
+Apart from traditional REST APIs, it can also be adopted in any context such as GraphQL, WebSockets, job queues.
 
 ---
 
-## Installation
+## 🔌 Integrations
+
+The core engine integrates seamlessly with other LimitKit packages:
+
+| Package             | Purpose                         |
+| ------------------- | ------------------------------- |
+| [`@limitkit/memory`](https://www.npmjs.com/package/@limitkit/memory)  | In-memory store for development |
+| [`@limitkit/redis`](https://www.npmjs.com/package/@limitkit/redis)   | Distributed rate limiting with Redis      |
+| [`@limitkit/express`](https://www.npmjs.com/package/@limitkit/express) | Express.js middleware           |
+| [`@limitkit/nest`](https://www.npmjs.com/package/@limitkit/nest)    | NestJS guards & decorators      |
+
+---
+
+## ⚡ Installation
 
 ```bash
 npm install @limitkit/core
-````
+```
 
 ---
 
-## Basic Usage
+## ⚡ Quick Start
+
+Simply have a `limiter` instance where you define all the rules, configure store and debug (optional).
+
+Then, call `limiter.consume`, which returns an object containing `allowed` that indicates whether the request is allowed or rejected.
 
 ```ts
-import { RateLimiter } from "@limitkit/core"
-import { InMemoryStore, InMemoryFixedWindow } from "@limitkit/memory"
+import { RateLimiter } from "@limitkit/core";
+import { InMemoryStore, fixedWindow } from "@limitkit/memory";
 
 const limiter = new RateLimiter({
   store: new InMemoryStore(),
+
   rules: [
     {
       name: "global",
-      key: (req) => req.ip,
-      policy: new InMemoryFixedWindow({
-        name: "fixed-window",
-        window: 60,
-        limit: 100
-      })
-    }
-  ]
-})
+      key: "global",
+      policy: fixedWindow({ window: 60, limit: 100 }),
+    },
+  ],
+});
+
+const result = await limiter.consume(ctx);
+
+if (!result.allowed) {
+  console.log("Rate limited");
+}
 ```
 
+
+The `rules` array in the `limiter` object are evaluated in order **from first to last**.
+
+Once the **first failure** is found, the remaining rules are not evaluated.
+
 ---
 
-## Supported Algorithms
+## 🏗 Architecture
 
-LimitKit supports multiple rate limiting algorithms:
+The engine follows a simple pipeline:
 
-* Fixed Window
-* Sliding Window
-* Sliding Window Counter
-* Token Bucket
-* Leaky Bucket
-* GCRA
+```
+request
+  ↓
+rules
+  ↓
+key resolution
+  ↓
+policy evaluation
+  ↓
+store update
+  ↓
+decision
+```
 
-Algorithms are provided by store-specific packages such as `@limitkit/memory` or `@limitkit/redis`.
+Each rule:
 
----
+1. resolves a **key** (who is being limited)
+2. selects a **policy** (how to limit)
+3. consumes quota from the **store**
+4. returns allow / reject
 
-## Rules
+---
 
-Each rule defines how a request is evaluated.
+## 🧩 Rule Definition
 
-Example rule:
+A rule in LimitKit consists of these main properties:
 
 ```ts
 {
-  name: "per-ip",
-  key: (req) => req.ip,
-  policy: new InMemoryFixedWindow({
-    name: "fixed-window",
-    window: 60,
-    limit: 100
-  })
+  name: "user",
+  key: (ctx) => ctx.user.id,
+  policy: tokenBucket(...),
+  cost: 1
+}
+```
+
+| Field    | Description                                           |
+| -------- | ----------------------------------------------------- |
+| `name`   | rule identifier (ensure it is unique in a set of layers)     |
+| `key`    | groups requests (string, function, or async function) |
+| `policy` | rate limiting algorithm (can be resolved dynamically) |
+| `cost`   | weight per request (default `1`)                      |
+
+---
+
+## 🧠 Dynamic Policies
+
+Policies can be resolved dynamically per request:
+
+```ts
+policy: (ctx) => {
+  return ctx.user.plan === "pro"
+    ? proPolicy
+    : freePolicy;
 }
 ```
 
-Rules can define:
+This is particularly useful when you want to enforce:
 
-* `name` — unique rule identifier
-* `key` — request key (e.g. IP or user ID)
-* `policy` — rate limit algorithm
+* SaaS plan limits
+* per-endpoint limits
+* feature-based quotas
 
 ---
 
-## Custom Algorithms
+## 🎯 Examples
+
+Here are some common examples in LimitKit:
+
+### Layered Limits
 
-You can create custom algorithms by implementing the `Algorithm` interface.
+As a rule of thumb, rules are evaluated from global scope to user scope.
+
+If any rule fails, the evaluation stops and the request is rejected.
 
 ```ts
-import { Algorithm } from "@limitkit/core"
+rules: [
+  { name: "global", key: "global", policy: globalPolicy },
+  { name: "ip", key: (ctx) => ctx.ip, policy: ipPolicy },
+  { name: "user", key: (ctx) => ctx.user.id, policy: userPolicy },
+]
+```
+
+---
+
+### SaaS Plans
 
-class MyAlgorithm implements Algorithm<MyConfig> {
+This example introduces dynamic strategies depending on the user's subscription plans.
 
-  constructor(public readonly config: MyConfig) {}
+The `policy` can be an async function in which you can query the database or cache, but it may increase latency.
 
-  validate(): void {
-    if (this.config.limit <= 0) {
-      throw new Error("Invalid configuration")
-    }
+```ts
+{
+  key: (ctx) => ctx.user.id,
+  policy: (ctx) => {
+    return ctx.user.plan === "pro"
+      ? proPolicy
+      : freePolicy;
   }
+}
+```
 
+---
+
+### Expensive Operations
+
+Sometimes, it's more convenient to add weights to requests instead of restricting the number of requests.
+
+In the snippet below, assuming the `/report` endpoint performs expensive computations, `cost` represents the weight of the resources needed to handle a request. Thus, a request to `/report` consumes 10x more tokens than other endpoints, which triggers rate limits faster to mitigate abuse.
+
+```ts
+{
+  key: (ctx) => ctx.user.id,
+  cost: (ctx) => ctx.endpoint === "/report" ? 10 : 1,
+  policy: tokenBucketPolicy
 }
 ```
 
 ---
 
-## Custom Stores
+## 📊 Result
 
-Stores control where rate limiting state is stored.
+`consume(context)` returns a normalized result represented as `RateLimitResult` interface:
 
-Custom stores can implement the `Store` interface.
+```ts
+interface RateLimitResult {
+  allowed: boolean,
+  limit: number,
+  remaining: number,
+  reset: number,
+  retryAt?: number
+  failedAt: string | null;
+  details: (RateLimitResult & { name: string })[]
+}
+```
+
+| 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 |
 
-Example use cases:
+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.
 
-* DynamoDB
-* PostgreSQL
-* MongoDB
-* Cloudflare KV
+
+```ts
+interface DebugLimitResult extends RateLimitResult {
+  failedAt: string | null;
+  details: (RateLimitResult & { name: string })[];
+}
+```

package/dist/index.d.mts

@@ -158,12 +158,11 @@ interface LimitRule<C = unknown> {
 type PolicyResolver<C> = Algorithm<AlgorithmConfig> | ((ctx: C) => Algorithm<AlgorithmConfig> | Promise<Algorithm<AlgorithmConfig>>);
 
 /**
- * Result of a rate limit check for a single request.
+ * Result of evaluating a single rate limit rule.
  *
- * Indicates whether the request is allowed, the maximum number of requests can be made, how many requests remain in the current
- * window, when the limit resets and how many seconds to wait before retrying.
+ * Represents the state of one rule (e.g., per-IP, per-user).
  */
-interface RateLimitResult {
+interface RateLimitRuleResult {
     /**
      * Whether the request is allowed (true = within limits, false = limit exceeded).
      */
@@ -181,32 +180,40 @@ interface RateLimitResult {
      * Unix timestamp (in milliseconds) when the rate limit counter fully resets.
      * Useful for implementing client-side backoff strategies.
      */
-    reset: number;
+    resetAt: number;
     /**
-     * If the request is rate limited, suggests how many seconds to wait before retrying.
-     * Clients should use exponential backoff and add jitter, rather than strictly following this value.
-     * Only present when `allowed` is false.
+     * If the request is rate limited, suggests the timestamp to retry.
+     * Defined only present when `allowed` is false.
      */
-    retryAfter?: number;
+    retryAt?: number;
+}
+interface IdentifiedRateLimitRuleResult extends RateLimitRuleResult {
+    /**
+     * Unique name of the rule.
+     */
+    name: string;
 }
 /**
- * Extended rate limit result with debug information.
+ * Result of a rate limit check across all rules.
  *
- * Returned when debug mode is enabled on the RateLimiter. Includes details about
- * all evaluated rules and which rule caused the rate limit (if any).
+ * This is a composable, lossless representation of all evaluated rules.
+ * No aggregation or interpretation is applied at this level.
  */
-interface DebugLimitResult extends RateLimitResult {
+interface RateLimitResult {
     /**
-     * The name of the rule that caused the rate limit to be exceeded.
-     * If the request was allowed, this is null.
+     * Whether the request is allowed across all rules.
+     * Equivalent to: all(rule.allowed === true)
+     */
+    allowed: boolean;
+    /**
+     * The name of the rule that caused the rejection.
+     * Null if the request was allowed.
      */
     failedRule: string | null;
     /**
-     * An array of results from the first rule to the first failed one
+     * Results for each evaluated rule, in order.
      */
-    details: (RateLimitResult & {
-        name: string;
-    })[];
+    rules: IdentifiedRateLimitRuleResult[];
 }
 
 /**
@@ -249,9 +256,9 @@ interface Store {
      * @param now - Unix timestamp in millisecond
      * @param cost - The cost/weight of this request. Defaults to 1. Higher costs consume
      *               more quota (useful for charging different amounts for different operations).
-     * @returns A promise that resolves to the rate limit check result.
+     * @returns A promise that resolves to the rate limit check result for a particular rule.
      */
-    consume<TConfig extends AlgorithmConfig>(key: string, algorithm: Algorithm<TConfig>, now: number, cost?: number): Promise<RateLimitResult>;
+    consume<TConfig extends AlgorithmConfig>(key: string, algorithm: Algorithm<TConfig>, now: number, cost?: number): Promise<RateLimitRuleResult>;
 }
 
 /**
@@ -266,11 +273,6 @@ interface RateLimitConfig<C = unknown> {
      * The storage backend for tracking rate limit state.
      */
     store: Store;
-    /**
-     * Optional. When true, returns detailed information about
-     * each evaluated rule. Useful for troubleshooting. Defaults to false.
-     */
-    debug?: boolean;
 }
 
 /**
@@ -296,14 +298,14 @@ interface RateLimitConfig<C = unknown> {
  *     {
  *       name: 'per-user-limit',
  *       key: (ctx) => ctx.userId,
- *       policy: new RedisFixedWindow({ name: 'fixed-window', window: 60, limit: 100 })
+ *       policy: fixedWindow({ window: 60, limit: 100 })
  *     }
  *   ]
  * });
  *
  * const result = await limiter.consume({ userId: 'user-123' });
  * if (!result.allowed) {
- *   return 429 with headers: Retry-After: result.retryAfter
+ *   return 429 with headers: Retry-After: result.retryAt
  * }
  * ```
  * @see Limiter
@@ -312,7 +314,6 @@ interface RateLimitConfig<C = unknown> {
  */
 declare class RateLimiter<C = unknown> implements Limiter<C> {
     private rules;
-    private debug;
     private store;
     /**
      * Create a new rate limiter instance.
@@ -320,7 +321,7 @@ declare class RateLimiter<C = unknown> implements Limiter<C> {
      * @param config - Configuration for the rate limiter
      * @see RateLimitConfig
      */
-    constructor({ rules, debug, store }: RateLimitConfig<C>);
+    constructor({ rules, store }: RateLimitConfig<C>);
     /**
      * Return the configuration object
      * @returns {RateLimitConfig<C>}
@@ -329,14 +330,15 @@ 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 as soon as a rule is exceeded (request denied).
-     * If all rules allow the request, returns the result of the last rule evaluated.
+     * 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.
      *
      * Each rule resolution (key, cost, policy) can be static or dynamic:
      * - Static: evaluated once and reused
      * - Dynamic: evaluated per request based on context
      * - Async: evaluated asynchronously (e.g., database lookups)
      *
+     *
      * @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).
@@ -350,9 +352,11 @@ declare class RateLimiter<C = unknown> implements Limiter<C> {
      * });
      *
      * if (!result.allowed) {
-     *   console.log(`Rate limited. Retry in ${result.retryAfter} seconds`);
+     *   console.log(`Rate limited. Retry at ${new Date(result.retryAt)}`);
      * }
      * ```
+     *
+     * @throws UndefinedKeyException if the key is empty or undefined
      */
     consume(ctx: C): Promise<RateLimitResult>;
 }
@@ -369,6 +373,10 @@ declare class UnknownAlgorithmException extends Error {
     constructor(algorithm: string);
 }
 
+declare class UndefinedKeyException extends Error {
+    constructor(ruleName: string);
+}
+
 /**
  * Prepend additional data to user-defined rate limiting keys, which include:
  * * Rate limiting algorithm name e.g., `"fixed-window"`, `"sliding-window"`
@@ -377,22 +385,15 @@ declare class UnknownAlgorithmException extends Error {
  * @warning Avoid nested or non-primitive key-value pairs to ensure deterministic hash value
  *
  * The modified key will have the format: `ratelimit:{algorithm_name}:{sha256_hash}:{key}`
+ *
+ * This prevents accessing corrupted states in the store if the policies are changed.
+ *
  * @param config The algorithm config object
  * @param key The user-defined key
  * @returns {string} A modified key with the format above
  */
 declare function addConfigToKey(config: AlgorithmConfig, key: string): string;
 
-/**
- * Merge two arrays of rules by name such that:
- * * Local rules override global rules if the name matches
- * * New local rules are appended
- * @param globalRules The global rules to be overriden
- * @param localRules The local rules to be appended or to override global rules
- * @returns {LimitRule<C>[]} A new list of rules merged from `globalRules` and `localRules`
- */
-declare function mergeRules<C>(globalRules?: LimitRule<C>[], localRules?: LimitRule<C>[]): LimitRule<C>[];
-
 /**
  * Base implementation of the **Fixed Window** rate limiting algorithm.
  *
@@ -699,4 +700,4 @@ declare abstract class GCRA implements Algorithm<GCRAConfig> {
     validate(): void;
 }
 
-export { type Algorithm, type AlgorithmConfig, type AlgorithmName, BadArgumentsException, type BaseConfig, type CustomConfig, type DebugLimitResult, EmptyRulesException, FixedWindow, type FixedWindowConfig, GCRA, type GCRAConfig, LeakyBucket, type LeakyBucketConfig, type LimitRule, type Limiter, type RateLimitConfig, type RateLimitResult, RateLimiter, SlidingWindow, type SlidingWindowConfig, SlidingWindowCounter, type SlidingWindowCounterConfig, type Store, TokenBucket, type TokenBucketConfig, UnknownAlgorithmException, type WindowConfig, addConfigToKey, mergeRules };
+export { type Algorithm, type AlgorithmConfig, type AlgorithmName, BadArgumentsException, type BaseConfig, type CustomConfig, EmptyRulesException, FixedWindow, type FixedWindowConfig, GCRA, type GCRAConfig, type IdentifiedRateLimitRuleResult, LeakyBucket, type LeakyBucketConfig, type LimitRule, type Limiter, type RateLimitConfig, type RateLimitResult, type RateLimitRuleResult, RateLimiter, SlidingWindow, type SlidingWindowConfig, SlidingWindowCounter, type SlidingWindowCounterConfig, type Store, TokenBucket, type TokenBucketConfig, UndefinedKeyException, UnknownAlgorithmException, type WindowConfig, addConfigToKey };

package/dist/index.d.ts

@@ -158,12 +158,11 @@ interface LimitRule<C = unknown> {
 type PolicyResolver<C> = Algorithm<AlgorithmConfig> | ((ctx: C) => Algorithm<AlgorithmConfig> | Promise<Algorithm<AlgorithmConfig>>);
 
 /**
- * Result of a rate limit check for a single request.
+ * Result of evaluating a single rate limit rule.
  *
- * Indicates whether the request is allowed, the maximum number of requests can be made, how many requests remain in the current
- * window, when the limit resets and how many seconds to wait before retrying.
+ * Represents the state of one rule (e.g., per-IP, per-user).
  */
-interface RateLimitResult {
+interface RateLimitRuleResult {
     /**
      * Whether the request is allowed (true = within limits, false = limit exceeded).
      */
@@ -181,32 +180,40 @@ interface RateLimitResult {
      * Unix timestamp (in milliseconds) when the rate limit counter fully resets.
      * Useful for implementing client-side backoff strategies.
      */
-    reset: number;
+    resetAt: number;
     /**
-     * If the request is rate limited, suggests how many seconds to wait before retrying.
-     * Clients should use exponential backoff and add jitter, rather than strictly following this value.
-     * Only present when `allowed` is false.
+     * If the request is rate limited, suggests the timestamp to retry.
+     * Defined only present when `allowed` is false.
      */
-    retryAfter?: number;
+    retryAt?: number;
+}
+interface IdentifiedRateLimitRuleResult extends RateLimitRuleResult {
+    /**
+     * Unique name of the rule.
+     */
+    name: string;
 }
 /**
- * Extended rate limit result with debug information.
+ * Result of a rate limit check across all rules.
  *
- * Returned when debug mode is enabled on the RateLimiter. Includes details about
- * all evaluated rules and which rule caused the rate limit (if any).
+ * This is a composable, lossless representation of all evaluated rules.
+ * No aggregation or interpretation is applied at this level.
  */
-interface DebugLimitResult extends RateLimitResult {
+interface RateLimitResult {
     /**
-     * The name of the rule that caused the rate limit to be exceeded.
-     * If the request was allowed, this is null.
+     * Whether the request is allowed across all rules.
+     * Equivalent to: all(rule.allowed === true)
+     */
+    allowed: boolean;
+    /**
+     * The name of the rule that caused the rejection.
+     * Null if the request was allowed.
      */
     failedRule: string | null;
     /**
-     * An array of results from the first rule to the first failed one
+     * Results for each evaluated rule, in order.
      */
-    details: (RateLimitResult & {
-        name: string;
-    })[];
+    rules: IdentifiedRateLimitRuleResult[];
 }
 
 /**
@@ -249,9 +256,9 @@ interface Store {
      * @param now - Unix timestamp in millisecond
      * @param cost - The cost/weight of this request. Defaults to 1. Higher costs consume
      *               more quota (useful for charging different amounts for different operations).
-     * @returns A promise that resolves to the rate limit check result.
+     * @returns A promise that resolves to the rate limit check result for a particular rule.
      */
-    consume<TConfig extends AlgorithmConfig>(key: string, algorithm: Algorithm<TConfig>, now: number, cost?: number): Promise<RateLimitResult>;
+    consume<TConfig extends AlgorithmConfig>(key: string, algorithm: Algorithm<TConfig>, now: number, cost?: number): Promise<RateLimitRuleResult>;
 }
 
 /**
@@ -266,11 +273,6 @@ interface RateLimitConfig<C = unknown> {
      * The storage backend for tracking rate limit state.
      */
     store: Store;
-    /**
-     * Optional. When true, returns detailed information about
-     * each evaluated rule. Useful for troubleshooting. Defaults to false.
-     */
-    debug?: boolean;
 }
 
 /**
@@ -296,14 +298,14 @@ interface RateLimitConfig<C = unknown> {
  *     {
  *       name: 'per-user-limit',
  *       key: (ctx) => ctx.userId,
- *       policy: new RedisFixedWindow({ name: 'fixed-window', window: 60, limit: 100 })
+ *       policy: fixedWindow({ window: 60, limit: 100 })
  *     }
  *   ]
  * });
  *
  * const result = await limiter.consume({ userId: 'user-123' });
  * if (!result.allowed) {
- *   return 429 with headers: Retry-After: result.retryAfter
+ *   return 429 with headers: Retry-After: result.retryAt
  * }
  * ```
  * @see Limiter
@@ -312,7 +314,6 @@ interface RateLimitConfig<C = unknown> {
  */
 declare class RateLimiter<C = unknown> implements Limiter<C> {
     private rules;
-    private debug;
     private store;
     /**
      * Create a new rate limiter instance.
@@ -320,7 +321,7 @@ declare class RateLimiter<C = unknown> implements Limiter<C> {
      * @param config - Configuration for the rate limiter
      * @see RateLimitConfig
      */
-    constructor({ rules, debug, store }: RateLimitConfig<C>);
+    constructor({ rules, store }: RateLimitConfig<C>);
     /**
      * Return the configuration object
      * @returns {RateLimitConfig<C>}
@@ -329,14 +330,15 @@ 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 as soon as a rule is exceeded (request denied).
-     * If all rules allow the request, returns the result of the last rule evaluated.
+     * 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.
      *
      * Each rule resolution (key, cost, policy) can be static or dynamic:
      * - Static: evaluated once and reused
      * - Dynamic: evaluated per request based on context
      * - Async: evaluated asynchronously (e.g., database lookups)
      *
+     *
      * @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).
@@ -350,9 +352,11 @@ declare class RateLimiter<C = unknown> implements Limiter<C> {
      * });
      *
      * if (!result.allowed) {
-     *   console.log(`Rate limited. Retry in ${result.retryAfter} seconds`);
+     *   console.log(`Rate limited. Retry at ${new Date(result.retryAt)}`);
      * }
      * ```
+     *
+     * @throws UndefinedKeyException if the key is empty or undefined
      */
     consume(ctx: C): Promise<RateLimitResult>;
 }
@@ -369,6 +373,10 @@ declare class UnknownAlgorithmException extends Error {
     constructor(algorithm: string);
 }
 
+declare class UndefinedKeyException extends Error {
+    constructor(ruleName: string);
+}
+
 /**
  * Prepend additional data to user-defined rate limiting keys, which include:
  * * Rate limiting algorithm name e.g., `"fixed-window"`, `"sliding-window"`
@@ -377,22 +385,15 @@ declare class UnknownAlgorithmException extends Error {
  * @warning Avoid nested or non-primitive key-value pairs to ensure deterministic hash value
  *
  * The modified key will have the format: `ratelimit:{algorithm_name}:{sha256_hash}:{key}`
+ *
+ * This prevents accessing corrupted states in the store if the policies are changed.
+ *
  * @param config The algorithm config object
  * @param key The user-defined key
  * @returns {string} A modified key with the format above
  */
 declare function addConfigToKey(config: AlgorithmConfig, key: string): string;
 
-/**
- * Merge two arrays of rules by name such that:
- * * Local rules override global rules if the name matches
- * * New local rules are appended
- * @param globalRules The global rules to be overriden
- * @param localRules The local rules to be appended or to override global rules
- * @returns {LimitRule<C>[]} A new list of rules merged from `globalRules` and `localRules`
- */
-declare function mergeRules<C>(globalRules?: LimitRule<C>[], localRules?: LimitRule<C>[]): LimitRule<C>[];
-
 /**
  * Base implementation of the **Fixed Window** rate limiting algorithm.
  *
@@ -699,4 +700,4 @@ declare abstract class GCRA implements Algorithm<GCRAConfig> {
     validate(): void;
 }
 
-export { type Algorithm, type AlgorithmConfig, type AlgorithmName, BadArgumentsException, type BaseConfig, type CustomConfig, type DebugLimitResult, EmptyRulesException, FixedWindow, type FixedWindowConfig, GCRA, type GCRAConfig, LeakyBucket, type LeakyBucketConfig, type LimitRule, type Limiter, type RateLimitConfig, type RateLimitResult, RateLimiter, SlidingWindow, type SlidingWindowConfig, SlidingWindowCounter, type SlidingWindowCounterConfig, type Store, TokenBucket, type TokenBucketConfig, UnknownAlgorithmException, type WindowConfig, addConfigToKey, mergeRules };
+export { type Algorithm, type AlgorithmConfig, type AlgorithmName, BadArgumentsException, type BaseConfig, type CustomConfig, EmptyRulesException, FixedWindow, type FixedWindowConfig, GCRA, type GCRAConfig, type IdentifiedRateLimitRuleResult, LeakyBucket, type LeakyBucketConfig, type LimitRule, type Limiter, type RateLimitConfig, type RateLimitResult, type RateLimitRuleResult, RateLimiter, SlidingWindow, type SlidingWindowConfig, SlidingWindowCounter, type SlidingWindowCounterConfig, type Store, TokenBucket, type TokenBucketConfig, UndefinedKeyException, UnknownAlgorithmException, type WindowConfig, addConfigToKey };

package/dist/index.js

@@ -29,9 +29,9 @@ __export(index_exports, {
   SlidingWindow: () => SlidingWindow,
   SlidingWindowCounter: () => SlidingWindowCounter,
   TokenBucket: () => TokenBucket,
+  UndefinedKeyException: () => UndefinedKeyException,
   UnknownAlgorithmException: () => UnknownAlgorithmException,
-  addConfigToKey: () => addConfigToKey,
-  mergeRules: () => mergeRules
+  addConfigToKey: () => addConfigToKey
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -59,10 +59,19 @@ var UnknownAlgorithmException = class extends Error {
   }
 };
 
+// src/exceptions/undefined-key-exception.ts
+var UndefinedKeyException = class extends Error {
+  constructor(ruleName) {
+    super(
+      `Rule "${ruleName}" returned undefined or empty key. Double-check your key function.`
+    );
+  }
+};
+
 // src/utils/add-config-to-key.ts
 var import_crypto = require("crypto");
 function addConfigToKey(config, key) {
-  const sortedKeys = Object.keys(config).sort();
+  const sortedKeys = Object.keys(config ?? {}).sort();
   const sortedConfig = sortedKeys.reduce((acc, k) => {
     acc[k] = config[k];
     return acc;
@@ -73,29 +82,9 @@ function addConfigToKey(config, key) {
   return modifiedKey;
 }
 
-// src/utils/merge-rules.ts
-function mergeRules(globalRules = [], localRules = []) {
-  const map = /* @__PURE__ */ new Map();
-  for (const rule of globalRules) {
-    map.set(rule.name, rule);
-  }
-  for (const rule of localRules) {
-    if (map.has(rule.name)) {
-      map.set(rule.name, {
-        ...map.get(rule.name),
-        ...rule
-      });
-    } else {
-      map.set(rule.name, rule);
-    }
-  }
-  return [...map.values()];
-}
-
 // src/rate-limiter.ts
 var RateLimiter = class {
   rules = [];
-  debug = false;
   store;
   /**
    * Create a new rate limiter instance.
@@ -103,10 +92,9 @@ var RateLimiter = class {
    * @param config - Configuration for the rate limiter
    * @see RateLimitConfig
    */
-  constructor({ rules, debug, store }) {
+  constructor({ rules, store }) {
     if (rules.length === 0) throw new EmptyRulesException();
     this.rules = rules ?? this.rules;
-    this.debug = debug ?? this.debug;
     this.store = store;
   }
   /**
@@ -114,19 +102,20 @@ var RateLimiter = class {
    * @returns {RateLimitConfig<C>}
    */
   get config() {
-    return { rules: this.rules, debug: this.debug, store: this.store };
+    return { rules: this.rules, store: this.store };
   }
   /**
    * Check if a request should be allowed under the configured rate limits.
    *
-   * Evaluates each rule in order from left to right. Returns as soon as a rule is exceeded (request denied).
-   * If all rules allow the request, returns the result of the last rule evaluated.
+   * 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.
    *
    * Each rule resolution (key, cost, policy) can be static or dynamic:
    * - Static: evaluated once and reused
    * - Dynamic: evaluated per request based on context
    * - Async: evaluated asynchronously (e.g., database lookups)
    *
+   *
    * @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).
@@ -140,64 +129,43 @@ var RateLimiter = class {
    * });
    *
    * if (!result.allowed) {
-   *   console.log(`Rate limited. Retry in ${result.retryAfter} seconds`);
+   *   console.log(`Rate limited. Retry at ${new Date(result.retryAt)}`);
    * }
    * ```
+   *
+   * @throws UndefinedKeyException if the key is empty or undefined
    */
   async consume(ctx) {
-    let result;
-    let minRemaining = Infinity;
-    let maxReset = 0;
-    let minLimit = Infinity;
-    const debugRules = [];
+    const evaluatedRules = [];
     for (const rule of this.rules) {
       const algorithm = typeof rule.policy === "function" ? await rule.policy(ctx) : rule.policy;
       const key = typeof rule.key === "function" ? await rule.key(ctx) : rule.key;
+      if (!key) throw new UndefinedKeyException(rule.name);
       const cost = typeof rule.cost === "function" ? await rule.cost(ctx) : rule.cost;
       if (cost !== void 0 && cost <= 0)
         throw new BadArgumentsException(
           `Cost must be a positive integer, got cost=${cost}`
         );
       const keyWithConfig = addConfigToKey(algorithm.config, key);
-      result = await this.store.consume(
+      const result = await this.store.consume(
         keyWithConfig,
         algorithm,
         Date.now(),
         cost ?? 1
       );
-      minRemaining = Math.min(result.remaining, minRemaining);
-      minLimit = Math.min(result.limit, minLimit);
-      maxReset = Math.max(result.reset, maxReset);
-      if (this.debug) {
-        debugRules.push({ ...result, name: rule.name });
-        if (result.allowed) console.log(debugRules);
-        else console.error(debugRules);
-      }
+      evaluatedRules.push({ ...result, name: rule.name });
       if (!result.allowed) {
-        if (this.debug) {
-          const debugResults = {
-            failedRule: rule.name,
-            ...result,
-            details: debugRules
-          };
-          return debugResults;
-        }
-        return result;
+        return {
+          allowed: result.allowed,
+          failedRule: rule.name,
+          rules: evaluatedRules
+        };
       }
     }
-    if (this.debug) {
-      const final = {
-        ...result,
-        details: this.debug ? debugRules : void 0
-      };
-      console.log(final);
-      return final;
-    }
     return {
-      ...result,
-      reset: maxReset,
-      limit: minLimit,
-      remaining: minRemaining
+      allowed: true,
+      failedRule: null,
+      rules: evaluatedRules
     };
   }
 };
@@ -374,7 +342,7 @@ var GCRA = class {
   SlidingWindow,
   SlidingWindowCounter,
   TokenBucket,
+  UndefinedKeyException,
   UnknownAlgorithmException,
-  addConfigToKey,
-  mergeRules
+  addConfigToKey
 });

package/dist/index.mjs

@@ -22,10 +22,19 @@ var UnknownAlgorithmException = class extends Error {
   }
 };
 
+// src/exceptions/undefined-key-exception.ts
+var UndefinedKeyException = class extends Error {
+  constructor(ruleName) {
+    super(
+      `Rule "${ruleName}" returned undefined or empty key. Double-check your key function.`
+    );
+  }
+};
+
 // src/utils/add-config-to-key.ts
 import { createHash } from "crypto";
 function addConfigToKey(config, key) {
-  const sortedKeys = Object.keys(config).sort();
+  const sortedKeys = Object.keys(config ?? {}).sort();
   const sortedConfig = sortedKeys.reduce((acc, k) => {
     acc[k] = config[k];
     return acc;
@@ -36,29 +45,9 @@ function addConfigToKey(config, key) {
   return modifiedKey;
 }
 
-// src/utils/merge-rules.ts
-function mergeRules(globalRules = [], localRules = []) {
-  const map = /* @__PURE__ */ new Map();
-  for (const rule of globalRules) {
-    map.set(rule.name, rule);
-  }
-  for (const rule of localRules) {
-    if (map.has(rule.name)) {
-      map.set(rule.name, {
-        ...map.get(rule.name),
-        ...rule
-      });
-    } else {
-      map.set(rule.name, rule);
-    }
-  }
-  return [...map.values()];
-}
-
 // src/rate-limiter.ts
 var RateLimiter = class {
   rules = [];
-  debug = false;
   store;
   /**
    * Create a new rate limiter instance.
@@ -66,10 +55,9 @@ var RateLimiter = class {
    * @param config - Configuration for the rate limiter
    * @see RateLimitConfig
    */
-  constructor({ rules, debug, store }) {
+  constructor({ rules, store }) {
     if (rules.length === 0) throw new EmptyRulesException();
     this.rules = rules ?? this.rules;
-    this.debug = debug ?? this.debug;
     this.store = store;
   }
   /**
@@ -77,19 +65,20 @@ var RateLimiter = class {
    * @returns {RateLimitConfig<C>}
    */
   get config() {
-    return { rules: this.rules, debug: this.debug, store: this.store };
+    return { rules: this.rules, store: this.store };
   }
   /**
    * Check if a request should be allowed under the configured rate limits.
    *
-   * Evaluates each rule in order from left to right. Returns as soon as a rule is exceeded (request denied).
-   * If all rules allow the request, returns the result of the last rule evaluated.
+   * 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.
    *
    * Each rule resolution (key, cost, policy) can be static or dynamic:
    * - Static: evaluated once and reused
    * - Dynamic: evaluated per request based on context
    * - Async: evaluated asynchronously (e.g., database lookups)
    *
+   *
    * @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).
@@ -103,64 +92,43 @@ var RateLimiter = class {
    * });
    *
    * if (!result.allowed) {
-   *   console.log(`Rate limited. Retry in ${result.retryAfter} seconds`);
+   *   console.log(`Rate limited. Retry at ${new Date(result.retryAt)}`);
    * }
    * ```
+   *
+   * @throws UndefinedKeyException if the key is empty or undefined
    */
   async consume(ctx) {
-    let result;
-    let minRemaining = Infinity;
-    let maxReset = 0;
-    let minLimit = Infinity;
-    const debugRules = [];
+    const evaluatedRules = [];
     for (const rule of this.rules) {
       const algorithm = typeof rule.policy === "function" ? await rule.policy(ctx) : rule.policy;
       const key = typeof rule.key === "function" ? await rule.key(ctx) : rule.key;
+      if (!key) throw new UndefinedKeyException(rule.name);
       const cost = typeof rule.cost === "function" ? await rule.cost(ctx) : rule.cost;
       if (cost !== void 0 && cost <= 0)
         throw new BadArgumentsException(
           `Cost must be a positive integer, got cost=${cost}`
         );
       const keyWithConfig = addConfigToKey(algorithm.config, key);
-      result = await this.store.consume(
+      const result = await this.store.consume(
         keyWithConfig,
         algorithm,
         Date.now(),
         cost ?? 1
       );
-      minRemaining = Math.min(result.remaining, minRemaining);
-      minLimit = Math.min(result.limit, minLimit);
-      maxReset = Math.max(result.reset, maxReset);
-      if (this.debug) {
-        debugRules.push({ ...result, name: rule.name });
-        if (result.allowed) console.log(debugRules);
-        else console.error(debugRules);
-      }
+      evaluatedRules.push({ ...result, name: rule.name });
       if (!result.allowed) {
-        if (this.debug) {
-          const debugResults = {
-            failedRule: rule.name,
-            ...result,
-            details: debugRules
-          };
-          return debugResults;
-        }
-        return result;
+        return {
+          allowed: result.allowed,
+          failedRule: rule.name,
+          rules: evaluatedRules
+        };
       }
     }
-    if (this.debug) {
-      const final = {
-        ...result,
-        details: this.debug ? debugRules : void 0
-      };
-      console.log(final);
-      return final;
-    }
     return {
-      ...result,
-      reset: maxReset,
-      limit: minLimit,
-      remaining: minRemaining
+      allowed: true,
+      failedRule: null,
+      rules: evaluatedRules
     };
   }
 };
@@ -336,7 +304,7 @@ export {
   SlidingWindow,
   SlidingWindowCounter,
   TokenBucket,
+  UndefinedKeyException,
   UnknownAlgorithmException,
-  addConfigToKey,
-  mergeRules
+  addConfigToKey
 };

package/package.json

@@ -1,29 +1,43 @@
-{
-  "name": "@limitkit/core",
-  "version": "0.1.6",
-  "main": "dist/index.js",
-  "module": "dist/index.mjs",
-  "types": "dist/index.d.ts",
-  "exports": {
-    ".": "./dist/index.js"
-  },
-  "description": "Core rate limiting engine for LimitKit",
-  "files": [
-    "dist"
-  ],
-  "publishConfig": {
-    "access": "public"
-  },
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/alphatrann/limitkit"
-  },
-  "scripts": {
-    "build": "tsup src/index.ts --format esm,cjs --dts",
-    "test": "jest --silent"
-  },
-  "devDependencies": {
-    "@types/node": "^25.4.0"
-  }
-}
+{
+  "name": "@limitkit/core",
+  "version": "1.0.0",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "keywords": [
+    "rate-limiter",
+    "rate-limit",
+    "rate-limiting",
+    "throttling",
+    "token-bucket",
+    "leaky-bucket",
+    "sliding-window",
+    "sliding-window-counter",
+    "gcra",
+    "rules-engine",
+    "policy-based",
+    "nodejs"
+  ],
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "description": "Core rate limiting engine for LimitKit",
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/alphatrann/limitkit"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts",
+    "test": "jest --silent"
+  },
+  "devDependencies": {
+    "@types/node": "^25.4.0"
+  }
+}