@limitkit/core 0.1.0

package/dist/index.mjs

@@ -0,0 +1,347 @@
+// src/exceptions/bad-arguments-exception.ts
+var BadArgumentsException = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "BAD_ARGUMENTS_EXCEPTION";
+  }
+};
+
+// src/exceptions/empty-rules-exception.ts
+var EmptyRulesException = class extends Error {
+  constructor() {
+    super("The rate limit rules are empty. Ensure there is at least one rule");
+    this.name = "EMPTY_RULES_EXCEPTION";
+  }
+};
+
+// src/exceptions/unknown-algorithm-exception.ts
+var UnknownAlgorithmException = class extends Error {
+  constructor(algorithm) {
+    super(`Found unknown algorithm: ${algorithm}`);
+    this.name = "UNKNOWN_ALGORITHM_EXCEPTION";
+  }
+};
+
+// src/utils/add-config-to-key.ts
+import { createHash } from "crypto";
+function addConfigToKey(config, key) {
+  const sortedKeys = Object.keys(config).sort();
+  const sortedConfig = sortedKeys.reduce((acc, k) => {
+    acc[k] = config[k];
+    return acc;
+  }, {});
+  const configJson = JSON.stringify(sortedConfig);
+  const hashedConfig = createHash("sha256").update(configJson).digest("hex");
+  const modifiedKey = `ratelimit:${config.name}:${hashedConfig}:${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.
+   * @throws {EmptyRulesException} If the list of rules is empty
+   * @param config - Configuration for the rate limiter
+   * @see RateLimitConfig
+   */
+  constructor({ rules, debug, store }) {
+    if (rules.length === 0) throw new EmptyRulesException();
+    this.rules = rules ?? this.rules;
+    this.debug = debug ?? this.debug;
+    this.store = store;
+  }
+  /**
+   * Return the configuration object
+   * @returns {RateLimitConfig<C>}
+   */
+  get config() {
+    return { rules: this.rules, debug: this.debug, 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.
+   *
+   * 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).
+   *
+   * @example
+   * ```typescript
+   * const result = await limiter.consume({
+   *   userId: 'user-123',
+   *   ip: '192.168.1.1',
+   *   endpoint: '/api/search'
+   * });
+   *
+   * if (!result.allowed) {
+   *   console.log(`Rate limited. Retry in ${result.retryAfter} seconds`);
+   * }
+   * ```
+   */
+  async consume(ctx) {
+    let result;
+    let minRemaining = Infinity;
+    let maxReset = 0;
+    let minLimit = Infinity;
+    const debugRules = [];
+    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;
+      const cost = typeof rule.cost === "function" ? await rule.cost(ctx) : rule.cost;
+      if (cost && 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(
+        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);
+      }
+      if (result.remaining === 0) {
+        if (this.debug) {
+          const debugResults = {
+            failedRule: rule.name,
+            ...result,
+            details: debugRules
+          };
+          return debugResults;
+        }
+        return {
+          ...result,
+          reset: maxReset,
+          limit: minLimit,
+          remaining: minRemaining
+        };
+      }
+    }
+    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
+    };
+  }
+};
+
+// src/algorithms/fixed-window.ts
+var FixedWindow = class {
+  constructor(config) {
+    this.config = config;
+  }
+  /**
+   * Validates the fixed window configuration.
+   *
+   * Ensures the configured window size and request limit are positive values.
+   *
+   * @throws BadArgumentsException
+   * Thrown if:
+   * - `limit <= 0`
+   * - `window <= 0`
+   */
+  validate() {
+    if (this.config.limit <= 0)
+      throw new BadArgumentsException(
+        `Expected limit to be positive, got limit=${this.config.limit}`
+      );
+    if (this.config.window <= 0)
+      throw new BadArgumentsException(
+        `Expected window to be positive, got window=${this.config.window}`
+      );
+  }
+};
+
+// src/algorithms/sliding-window.ts
+var SlidingWindow = class {
+  constructor(config) {
+    this.config = config;
+  }
+  /**
+   * Validates the sliding window configuration.
+   *
+   * Ensures the configured window size and request limit are positive values.
+   *
+   * @throws BadArgumentsException
+   * Thrown if:
+   * - `limit <= 0`
+   * - `window <= 0`
+   */
+  validate() {
+    if (this.config.limit <= 0)
+      throw new BadArgumentsException(
+        `Expected limit to be positive, got limit=${this.config.limit}`
+      );
+    if (this.config.window <= 0)
+      throw new BadArgumentsException(
+        `Expected window to be positive, got window=${this.config.window}`
+      );
+  }
+};
+
+// src/algorithms/sliding-window-counter.ts
+var SlidingWindowCounter = class {
+  constructor(config) {
+    this.config = config;
+  }
+  /**
+   * Validates the sliding window counter configuration.
+   *
+   * Ensures the configured window size and request limit are positive values.
+   *
+   * @throws BadArgumentsException
+   * Thrown if:
+   * - `limit <= 0`
+   * - `window <= 0`
+   */
+  validate() {
+    if (this.config.limit <= 0)
+      throw new BadArgumentsException(
+        `Expected limit to be positive, got limit=${this.config.limit}`
+      );
+    if (this.config.window <= 0)
+      throw new BadArgumentsException(
+        `Expected window to be positive, got window=${this.config.window}`
+      );
+  }
+};
+
+// src/algorithms/token-bucket.ts
+var TokenBucket = class {
+  constructor(config) {
+    this.config = config;
+  }
+  /**
+   * Validates the token bucket configuration.
+   *
+   * Ensures the configured capacity and refill rate are positive values.
+   *
+   * @throws BadArgumentsException
+   * Thrown if:
+   * - `capacity <= 0`
+   * - `refillRate <= 0`
+   */
+  validate() {
+    if (this.config.capacity <= 0)
+      throw new BadArgumentsException(
+        `Expected capacity to be positive, got capacity=${this.config.capacity}`
+      );
+    if (this.config.refillRate <= 0)
+      throw new BadArgumentsException(
+        `Expected refillRate to be positive, got refillRate=${this.config.refillRate}`
+      );
+  }
+};
+
+// src/algorithms/leaky-bucket.ts
+var LeakyBucket = class {
+  constructor(config) {
+    this.config = config;
+  }
+  /**
+   * Validates the leaky bucket configuration.
+   *
+   * Ensures the configured capacity and leak rate are positive values.
+   *
+   * @throws BadArgumentsException
+   * Thrown if:
+   * - `capacity <= 0`
+   * - `leakRate <= 0`
+   */
+  validate() {
+    if (this.config.capacity <= 0)
+      throw new BadArgumentsException(
+        `Expected capacity to be positive, got capacity=${this.config.capacity}`
+      );
+    if (this.config.leakRate <= 0)
+      throw new BadArgumentsException(
+        `Expected leakRate to be positive, got leakRate=${this.config.leakRate}`
+      );
+  }
+};
+
+// src/algorithms/gcra.ts
+var GCRA = class {
+  constructor(config) {
+    this.config = config;
+  }
+  /**
+   * Validates the GCRA configuration.
+   *
+   * Ensures the configured burst and interval are positive values.
+   *
+   * @throws BadArgumentsException
+   * Thrown if:
+   * - `burst <= 0`
+   * - `interval <= 0`
+   */
+  validate() {
+    if (this.config.burst <= 0)
+      throw new BadArgumentsException(
+        `Expected burst to be positive, got burst=${this.config.burst}`
+      );
+    if (this.config.interval <= 0)
+      throw new BadArgumentsException(
+        `Expected interval to be positive, got interval=${this.config.interval}`
+      );
+  }
+};
+export {
+  BadArgumentsException,
+  EmptyRulesException,
+  FixedWindow,
+  GCRA,
+  LeakyBucket,
+  RateLimiter,
+  SlidingWindow,
+  SlidingWindowCounter,
+  TokenBucket,
+  UnknownAlgorithmException,
+  addConfigToKey,
+  mergeRules
+};

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@limitkit/core",
+  "version": "0.1.0",
+  "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"
+  ],
+  "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"
+  }
+}