@fluojs/throttler 1.0.0-beta.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 fluo contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.ko.md

@@ -0,0 +1,135 @@
+# @fluojs/throttler
+
+<p><a href="./README.md"><kbd>English</kbd></a> <strong><kbd>한국어</kbd></strong></p>
+
+메모리 내(In-memory) 및 Redis 저장소 어댑터를 지원하는 fluo 애플리케이션용 데코레이터 기반 속도 제한(Rate Limiting) 패키지입니다.
+
+## 목차
+
+- [설치](#설치)
+- [사용 시점](#사용-시점)
+- [빠른 시작](#빠른-시작)
+- [공통 패턴](#공통-패턴)
+  - [Redis 저장소 사용](#redis-저장소-사용)
+  - [커스텀 키 생성](#커스텀-키-생성)
+- [공개 API 개요](#공개-api-개요)
+- [관련 패키지](#관련-패키지)
+- [예제 소스](#예제-소스)
+
+## 설치
+
+```bash
+npm install @fluojs/throttler
+```
+
+## 사용 시점
+
+- 로그인, 회원가입 등 민감한 엔드포인트에 대한 브루트 포스 공격을 방지하고 싶을 때 사용합니다.
+- 단일 클라이언트의 과도한 요청으로부터 API 서버를 보호하고 싶을 때 적합합니다.
+- 사용자 유형별로 사용량 할당량이나 계층화된 속도 제한을 구현할 때 사용합니다.
+- 컨트롤러나 메서드에 데코레이터를 사용하여 간편하게 속도 제한을 적용하고 싶을 때 사용합니다.
+
+## 빠른 시작
+
+`ThrottlerModule`을 등록하고 컨트롤러나 메서드에 `Throttle` 데코레이터를 적용합니다.
+
+```typescript
+import { Module } from '@fluojs/core';
+import { ThrottlerModule, Throttle, SkipThrottle } from '@fluojs/throttler';
+import { Controller, Post } from '@fluojs/http';
+
+@Module({
+  imports: [
+    ThrottlerModule.forRoot({
+      ttl: 60,   // 60초
+      limit: 10, // 10회 요청
+    }),
+  ],
+})
+class AppModule {}
+
+@Controller('/auth')
+class AuthController {
+  @Post('/login')
+  @Throttle({ ttl: 60, limit: 5 }) // 오버라이드: 분당 5회 요청
+  login() {
+    return { success: true };
+  }
+
+  @Post('/public-info')
+  @SkipThrottle() // 속도 제한 제외
+  getInfo() {
+    return { info: '...' };
+  }
+}
+```
+
+## 공통 패턴
+
+### Redis 저장소 사용
+
+다중 인스턴스 배포 환경에서는 `RedisThrottlerStore`를 사용하여 모든 인스턴스 간에 속도 제한 상태를 공유하세요.
+
+```typescript
+import { ThrottlerModule, RedisThrottlerStore } from '@fluojs/throttler';
+import { REDIS_CLIENT } from '@fluojs/redis';
+
+// 프로바이더 또는 모듈 팩토리 내부에서
+const redisStore = new RedisThrottlerStore(redisClient);
+
+ThrottlerModule.forRoot({
+  ttl: 60,
+  limit: 100,
+  store: redisStore,
+});
+```
+
+### 커스텀 키 생성
+
+기본적으로 throttler는 raw socket `remoteAddress`만으로 클라이언트 식별자를 해석합니다. 배포가 `Forwarded`, `X-Forwarded-For`, `X-Real-IP`를 덮어쓰는 신뢰 가능한 리버스 프록시 뒤에 있다면 `trustProxyHeaders: true`로 명시적으로 opt-in 하세요. 신뢰 가능한 소켓 식별자나 프록시 식별자가 없으면 서로 다른 호출자를 같은 버킷으로 합치지 않도록 예외를 던집니다. API 키나 사용자 ID 등 다른 식별자를 사용하도록 커스터마이징할 수도 있습니다.
+
+```typescript
+ThrottlerModule.forRoot({
+  ttl: 60,
+  limit: 100,
+  trustProxyHeaders: true,
+});
+```
+
+```typescript
+ThrottlerModule.forRoot({
+  ttl: 60,
+  limit: 100,
+  keyGenerator: (context) => {
+    const request = context.switchToHttp().getRequest();
+    return request.headers['x-api-key'] || request.ip;
+  },
+});
+```
+
+## 공개 API 개요
+
+### 모듈
+- `ThrottlerModule.forRoot(options)`: 글로벌 속도 제한 동작 및 저장소를 설정합니다.
+- 패키지 수준 등록은 `ThrottlerModule.forRoot(options)`를 통해 지원합니다. 내부 프로바이더 조합 헬퍼는 공개 계약에 포함되지 않습니다.
+
+### 데코레이터
+- `@Throttle({ ttl, limit })`: 클래스나 메서드에 특정 속도 제한을 설정합니다.
+- `@SkipThrottle()`: 클래스나 메서드에 대해 속도 제한을 비활성화합니다.
+
+### 가드
+- `ThrottlerGuard`: 속도 제한을 강제하는 가드입니다. `ThrottlerModule.forRoot()` 사용 시 자동으로 등록됩니다.
+
+### 저장소(Store)
+- `createMemoryThrottlerStore()`: 간단한 메모리 내 저장소를 생성합니다 (기본값).
+- `RedisThrottlerStore`: Redis용 저장소 어댑터입니다.
+
+## 관련 패키지
+
+- `@fluojs/http`: HTTP 컨텍스트 및 예외 처리를 위해 필요합니다.
+- `@fluojs/redis`: `RedisThrottlerStore` 사용 시 필요합니다.
+
+## 예제 소스
+
+- `packages/throttler/src/module.test.ts`: 모듈 설정 및 데코레이터 오버라이드 테스트.
+- `packages/throttler/src/guard.ts`: 요청 제한 및 헤더 관리 코어 로직.

package/README.md

@@ -0,0 +1,135 @@
+# @fluojs/throttler
+
+<p><strong><kbd>English</kbd></strong> <a href="./README.ko.md"><kbd>한국어</kbd></a></p>
+
+Decorator-based rate limiting for fluo applications with in-memory and Redis store adapters.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [When to Use](#when-to-use)
+- [Quick Start](#quick-start)
+- [Common Patterns](#common-patterns)
+  - [Redis Storage](#redis-storage)
+  - [Custom Key Generation](#custom-key-generation)
+- [Public API Overview](#public-api-overview)
+- [Related Packages](#related-packages)
+- [Example Sources](#example-sources)
+
+## Installation
+
+```bash
+npm install @fluojs/throttler
+```
+
+## When to Use
+
+- To prevent brute-force attacks on sensitive endpoints (e.g., login, registration).
+- To protect your API from being overwhelmed by too many requests from a single client.
+- To implement usage quotas or tiered rate limits for different types of users.
+- When you need a simple way to apply rate limits using decorators on controllers or methods.
+
+## Quick Start
+
+Register the `ThrottlerModule` and apply the `Throttle` decorator to your controllers or methods.
+
+```typescript
+import { Module } from '@fluojs/core';
+import { ThrottlerModule, Throttle, SkipThrottle } from '@fluojs/throttler';
+import { Controller, Post } from '@fluojs/http';
+
+@Module({
+  imports: [
+    ThrottlerModule.forRoot({
+      ttl: 60,   // 60 seconds
+      limit: 10, // 10 requests
+    }),
+  ],
+})
+class AppModule {}
+
+@Controller('/auth')
+class AuthController {
+  @Post('/login')
+  @Throttle({ ttl: 60, limit: 5 }) // Override: 5 requests per minute
+  login() {
+    return { success: true };
+  }
+
+  @Post('/public-info')
+  @SkipThrottle() // Bypass throttling
+  getInfo() {
+    return { info: '...' };
+  }
+}
+```
+
+## Common Patterns
+
+### Redis Storage
+
+For multi-instance deployments, use `RedisThrottlerStore` to share the rate limit state across all instances.
+
+```typescript
+import { ThrottlerModule, RedisThrottlerStore } from '@fluojs/throttler';
+import { REDIS_CLIENT } from '@fluojs/redis';
+
+// Inside a provider or module factory
+const redisStore = new RedisThrottlerStore(redisClient);
+
+ThrottlerModule.forRoot({
+  ttl: 60,
+  limit: 100,
+  store: redisStore,
+});
+```
+
+### Custom Key Generation
+
+By default, the throttler resolves client identity from the raw socket `remoteAddress` only. If your deployment sits behind a trusted reverse proxy that rewrites `Forwarded`, `X-Forwarded-For`, or `X-Real-IP`, opt in with `trustProxyHeaders: true`. If no trusted socket or proxy identity is available, it throws instead of collapsing unrelated callers into a shared bucket. You can also customize this to use API keys, user IDs, or other identifiers.
+
+```typescript
+ThrottlerModule.forRoot({
+  ttl: 60,
+  limit: 100,
+  trustProxyHeaders: true,
+});
+```
+
+```typescript
+ThrottlerModule.forRoot({
+  ttl: 60,
+  limit: 100,
+  keyGenerator: (context) => {
+    const request = context.switchToHttp().getRequest();
+    return request.headers['x-api-key'] || request.ip;
+  },
+});
+```
+
+## Public API Overview
+
+### Modules
+- `ThrottlerModule.forRoot(options)`: Configures the global throttling behavior and storage.
+- Package-level registration is supported through `ThrottlerModule.forRoot(options)`. Internal provider-composition helpers are not part of the public contract.
+
+### Decorators
+- `@Throttle({ ttl, limit })`: Sets a specific rate limit for a class or method.
+- `@SkipThrottle()`: Disables throttling for a class or method.
+
+### Guards
+- `ThrottlerGuard`: The guard responsible for enforcing the rate limits. Automatically registered when using `ThrottlerModule.forRoot()`.
+
+### Stores
+- `createMemoryThrottlerStore()`: Creates a simple in-memory store (default).
+- `RedisThrottlerStore`: Store adapter for Redis.
+
+## Related Packages
+
+- `@fluojs/http`: Required for HTTP context and Exception handling.
+- `@fluojs/redis`: Required when using `RedisThrottlerStore`.
+
+## Example Sources
+
+- `packages/throttler/src/module.test.ts`: Tests for module configuration and decorator overrides.
+- `packages/throttler/src/guard.ts`: The core logic for request throttling and header management.

package/dist/decorators.d.ts

@@ -0,0 +1,50 @@
+import type { ThrottlerHandlerOptions } from './types.js';
+/** Shared controller metadata key used to store per-route throttling metadata records. */
+export declare const throttleRouteMetadataKey: unique symbol;
+type StandardMetadataBag = Record<PropertyKey, unknown>;
+type StandardMethodDecoratorFn = (value: Function, context: ClassMethodDecoratorContext) => void;
+type StandardClassDecoratorFn = (value: Function, context: ClassDecoratorContext) => void;
+type ClassOrMethodDecoratorLike = StandardClassDecoratorFn & StandardMethodDecoratorFn;
+/**
+ * Override throttling policy for a controller class or handler method.
+ *
+ * @param options Rate-limit window and request cap for the decorated target.
+ * @returns A decorator that stores throttling metadata on the class or method.
+ */
+export declare function Throttle(options: ThrottlerHandlerOptions): ClassOrMethodDecoratorLike;
+/**
+ * Disable throttling for a controller class or handler method.
+ *
+ * @returns A decorator that marks the target as exempt from `ThrottlerGuard`.
+ */
+export declare function SkipThrottle(): ClassOrMethodDecoratorLike;
+/**
+ * Read method-level throttle metadata from a metadata bag.
+ *
+ * @param bag Route-level metadata bag captured from the controller.
+ * @returns A defensive copy of the stored throttle options, if present.
+ */
+export declare function getThrottleMetadata(bag: StandardMetadataBag): ThrottlerHandlerOptions | undefined;
+/**
+ * Read method-level skip metadata from a metadata bag.
+ *
+ * @param bag Route-level metadata bag captured from the controller.
+ * @returns `true` when throttling should be skipped for the handler.
+ */
+export declare function getSkipThrottleMetadata(bag: StandardMetadataBag): boolean;
+/**
+ * Read class-level throttle metadata from a metadata bag.
+ *
+ * @param bag Controller metadata bag.
+ * @returns A defensive copy of the stored throttle options, if present.
+ */
+export declare function getClassThrottleMetadata(bag: StandardMetadataBag): ThrottlerHandlerOptions | undefined;
+/**
+ * Read class-level skip metadata from a metadata bag.
+ *
+ * @param bag Controller metadata bag.
+ * @returns `true` when throttling should be skipped for the controller.
+ */
+export declare function getClassSkipThrottleMetadata(bag: StandardMetadataBag): boolean;
+export {};
+//# sourceMappingURL=decorators.d.ts.map

package/dist/decorators.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decorators.d.ts","sourceRoot":"","sources":["../src/decorators.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAG1D,0FAA0F;AAC1F,eAAO,MAAM,wBAAwB,eAAoC,CAAC;AAM1E,KAAK,mBAAmB,GAAG,MAAM,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;AACxD,KAAK,yBAAyB,GAAG,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,2BAA2B,KAAK,IAAI,CAAC;AACjG,KAAK,wBAAwB,GAAG,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,qBAAqB,KAAK,IAAI,CAAC;AAC1F,KAAK,0BAA0B,GAAG,wBAAwB,GAAG,yBAAyB,CAAC;AAgCvF;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,uBAAuB,GAAG,0BAA0B,CAUrF;AAED;;;;GAIG;AACH,wBAAgB,YAAY,IAAI,0BAA0B,CAUzD;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,mBAAmB,GAAG,uBAAuB,GAAG,SAAS,CAGjG;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,mBAAmB,GAAG,OAAO,CAEzE;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,mBAAmB,GAAG,uBAAuB,GAAG,SAAS,CAGtG;AAED;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAAC,GAAG,EAAE,mBAAmB,GAAG,OAAO,CAE9E"}

package/dist/decorators.js

@@ -0,0 +1,106 @@
+import { validateThrottleOptions } from './validation.js';
+
+/** Shared controller metadata key used to store per-route throttling metadata records. */
+export const throttleRouteMetadataKey = Symbol.for('fluo.standard.route');
+const throttleKey = Symbol.for('fluo.throttler.throttle');
+const skipThrottleKey = Symbol.for('fluo.throttler.skip');
+const classThrottleKey = Symbol.for('fluo.throttler.class-throttle');
+const classSkipThrottleKey = Symbol.for('fluo.throttler.class-skip');
+function getMetadataBag(metadata) {
+  return metadata;
+}
+function cloneThrottleOptions(options) {
+  return validateThrottleOptions({
+    limit: options.limit,
+    ttl: options.ttl
+  });
+}
+function getRouteRecord(metadata, name) {
+  const bag = getMetadataBag(metadata);
+  let routeMap = bag[throttleRouteMetadataKey];
+  if (!routeMap) {
+    routeMap = new Map();
+    bag[throttleRouteMetadataKey] = routeMap;
+  }
+  let record = routeMap.get(name);
+  if (!record) {
+    record = {};
+    routeMap.set(name, record);
+  }
+  return record;
+}
+
+/**
+ * Override throttling policy for a controller class or handler method.
+ *
+ * @param options Rate-limit window and request cap for the decorated target.
+ * @returns A decorator that stores throttling metadata on the class or method.
+ */
+export function Throttle(options) {
+  const decorator = (_value, context) => {
+    if (context.kind === 'class') {
+      getMetadataBag(context.metadata)[classThrottleKey] = cloneThrottleOptions(options);
+    } else {
+      getRouteRecord(context.metadata, context.name)[throttleKey] = cloneThrottleOptions(options);
+    }
+  };
+  return decorator;
+}
+
+/**
+ * Disable throttling for a controller class or handler method.
+ *
+ * @returns A decorator that marks the target as exempt from `ThrottlerGuard`.
+ */
+export function SkipThrottle() {
+  const decorator = (_value, context) => {
+    if (context.kind === 'class') {
+      getMetadataBag(context.metadata)[classSkipThrottleKey] = true;
+    } else {
+      getRouteRecord(context.metadata, context.name)[skipThrottleKey] = true;
+    }
+  };
+  return decorator;
+}
+
+/**
+ * Read method-level throttle metadata from a metadata bag.
+ *
+ * @param bag Route-level metadata bag captured from the controller.
+ * @returns A defensive copy of the stored throttle options, if present.
+ */
+export function getThrottleMetadata(bag) {
+  const metadata = bag[throttleKey];
+  return metadata ? cloneThrottleOptions(metadata) : undefined;
+}
+
+/**
+ * Read method-level skip metadata from a metadata bag.
+ *
+ * @param bag Route-level metadata bag captured from the controller.
+ * @returns `true` when throttling should be skipped for the handler.
+ */
+export function getSkipThrottleMetadata(bag) {
+  return bag[skipThrottleKey] === true;
+}
+
+/**
+ * Read class-level throttle metadata from a metadata bag.
+ *
+ * @param bag Controller metadata bag.
+ * @returns A defensive copy of the stored throttle options, if present.
+ */
+export function getClassThrottleMetadata(bag) {
+  const metadata = bag[classThrottleKey];
+  return metadata ? cloneThrottleOptions(metadata) : undefined;
+}
+
+/**
+ * Read class-level skip metadata from a metadata bag.
+ *
+ * @param bag Controller metadata bag.
+ * @returns `true` when throttling should be skipped for the controller.
+ */
+export function getClassSkipThrottleMetadata(bag) {
+  return bag[classSkipThrottleKey] === true;
+}

package/dist/guard.d.ts

@@ -0,0 +1,19 @@
+import { type Guard, type GuardContext } from '@fluojs/http';
+import type { ThrottlerModuleOptions } from './types.js';
+/**
+ * Guard that enforces module-, class-, and method-level throttling policies.
+ */
+export declare class ThrottlerGuard implements Guard {
+    private readonly options;
+    private readonly store;
+    constructor(options: ThrottlerModuleOptions);
+    /**
+     * Evaluate whether the current request is still within its allowed rate-limit window.
+     *
+     * @param context Guard execution context for the current handler invocation.
+     * @returns `true` when the request is allowed to proceed.
+     * @throws TooManyRequestsException When the request exceeds the configured limit.
+     */
+    canActivate(context: GuardContext): Promise<boolean>;
+}
+//# sourceMappingURL=guard.d.ts.map

package/dist/guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guard.d.ts","sourceRoot":"","sources":["../src/guard.ts"],"names":[],"mappings":"AAEA,OAAO,EAA4B,KAAK,KAAK,EAAE,KAAK,YAAY,EAA0B,MAAM,cAAc,CAAC;AAY/G,OAAO,KAAK,EAAE,sBAAsB,EAAkB,MAAM,YAAY,CAAC;AA2CzE;;GAEG;AACH,qBACa,cAAe,YAAW,KAAK;IAG9B,OAAO,CAAC,QAAQ,CAAC,OAAO;IAFpC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAiB;gBAEV,OAAO,EAAE,sBAAsB;IAK5D;;;;;;OAMG;IACG,WAAW,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,OAAO,CAAC;CAiD3D"}

package/dist/guard.js

@@ -0,0 +1,111 @@
+let _initClass;
+function _applyDecs(e, t, n, r, o, i) { var a, c, u, s, f, l, p, d = Symbol.metadata || Symbol.for("Symbol.metadata"), m = Object.defineProperty, h = Object.create, y = [h(null), h(null)], v = t.length; function g(t, n, r) { return function (o, i) { n && (i = o, o = e); for (var a = 0; a < t.length; a++) i = t[a].apply(o, r ? [i] : []); return r ? i : o; }; } function b(e, t, n, r) { if ("function" != typeof e && (r || void 0 !== e)) throw new TypeError(t + " must " + (n || "be") + " a function" + (r ? "" : " or undefined")); return e; } function applyDec(e, t, n, r, o, i, u, s, f, l, p) { function d(e) { if (!p(e)) throw new TypeError("Attempted to access private element on non-instance"); } var h = [].concat(t[0]), v = t[3], w = !u, D = 1 === o, S = 3 === o, j = 4 === o, E = 2 === o; function I(t, n, r) { return function (o, i) { return n && (i = o, o = e), r && r(o), P[t].call(o, i); }; } if (!w) { var P = {}, k = [], F = S ? "get" : j || D ? "set" : "value"; if (f ? (l || D ? P = { get: _setFunctionName(function () { return v(this); }, r, "get"), set: function (e) { t[4](this, e); } } : P[F] = v, l || _setFunctionName(P[F], r, E ? "" : F)) : l || (P = Object.getOwnPropertyDescriptor(e, r)), !l && !f) { if ((c = y[+s][r]) && 7 !== (c ^ o)) throw Error("Decorating two elements with the same name (" + P[F].name + ") is not supported yet"); y[+s][r] = o < 3 ? 1 : o; } } for (var N = e, O = h.length - 1; O >= 0; O -= n ? 2 : 1) { var T = b(h[O], "A decorator", "be", !0), z = n ? h[O - 1] : void 0, A = {}, H = { kind: ["field", "accessor", "method", "getter", "setter", "class"][o], name: r, metadata: a, addInitializer: function (e, t) { if (e.v) throw new TypeError("attempted to call addInitializer after decoration was finished"); b(t, "An initializer", "be", !0), i.push(t); }.bind(null, A) }; if (w) c = T.call(z, N, H), A.v = 1, b(c, "class decorators", "return") && (N = c);else if (H.static = s, H.private = f, c = H.access = { has: f ? p.bind() : function (e) { return r in e; } }, j || (c.get = f ? E ? function (e) { return d(e), P.value; } : I("get", 0, d) : function (e) { return e[r]; }), E || S || (c.set = f ? I("set", 0, d) : function (e, t) { e[r] = t; }), N = T.call(z, D ? { get: P.get, set: P.set } : P[F], H), A.v = 1, D) { if ("object" == typeof N && N) (c = b(N.get, "accessor.get")) && (P.get = c), (c = b(N.set, "accessor.set")) && (P.set = c), (c = b(N.init, "accessor.init")) && k.unshift(c);else if (void 0 !== N) throw new TypeError("accessor decorators must return an object with get, set, or init properties or undefined"); } else b(N, (l ? "field" : "method") + " decorators", "return") && (l ? k.unshift(N) : P[F] = N); } return o < 2 && u.push(g(k, s, 1), g(i, s, 0)), l || w || (f ? D ? u.splice(-1, 0, I("get", s), I("set", s)) : u.push(E ? P[F] : b.call.bind(P[F])) : m(e, r, P)), N; } function w(e) { return m(e, d, { configurable: !0, enumerable: !0, value: a }); } return void 0 !== i && (a = i[d]), a = h(null == a ? null : a), f = [], l = function (e) { e && f.push(g(e)); }, p = function (t, r) { for (var i = 0; i < n.length; i++) { var a = n[i], c = a[1], l = 7 & c; if ((8 & c) == t && !l == r) { var p = a[2], d = !!a[3], m = 16 & c; applyDec(t ? e : e.prototype, a, m, d ? "#" + p : _toPropertyKey(p), l, l < 2 ? [] : t ? s = s || [] : u = u || [], f, !!t, d, r, t && d ? function (t) { return _checkInRHS(t) === e; } : o); } } }, p(8, 0), p(0, 0), p(8, 1), p(0, 1), l(u), l(s), c = f, v || w(e), { e: c, get c() { var n = []; return v && [w(e = applyDec(e, [t], r, e.name, 5, n)), g(n, 1)]; } }; }
+function _toPropertyKey(t) { var i = _toPrimitive(t, "string"); return "symbol" == typeof i ? i : i + ""; }
+function _toPrimitive(t, r) { if ("object" != typeof t || !t) return t; var e = t[Symbol.toPrimitive]; if (void 0 !== e) { var i = e.call(t, r || "default"); if ("object" != typeof i) return i; throw new TypeError("@@toPrimitive must return a primitive value."); } return ("string" === r ? String : Number)(t); }
+function _setFunctionName(e, t, n) { "symbol" == typeof t && (t = (t = t.description) ? "[" + t + "]" : ""); try { Object.defineProperty(e, "name", { configurable: !0, value: n ? n + " " + t : t }); } catch (e) {} return e; }
+function _checkInRHS(e) { if (Object(e) !== e) throw TypeError("right-hand side of 'in' should be an object, got " + (null !== e ? typeof e : "null")); return e; }
+import { Inject } from '@fluojs/core';
+import { metadataSymbol } from '@fluojs/core/internal';
+import { TooManyRequestsException } from '@fluojs/http';
+import { resolveClientIdentity } from '@fluojs/http/internal';
+import { getClassSkipThrottleMetadata, getClassThrottleMetadata, getSkipThrottleMetadata, getThrottleMetadata, throttleRouteMetadataKey } from './decorators.js';
+import { createMemoryThrottlerStore } from './store.js';
+import { THROTTLER_OPTIONS } from './tokens.js';
+import { validateThrottleOptions, validateThrottlerModuleOptions, validateThrottlerStoreEntry } from './validation.js';
+function getClassMetadataBag(target) {
+  return target[metadataSymbol];
+}
+function getMethodMetadataBag(controllerToken, methodName) {
+  const classBag = getClassMetadataBag(controllerToken);
+  if (!classBag) {
+    return undefined;
+  }
+  const routeMap = classBag[throttleRouteMetadataKey];
+  return routeMap?.get(methodName);
+}
+function defaultKeyGenerator(ctx, trustProxyHeaders) {
+  return resolveClientIdentity(ctx.request, {
+    trustProxyHeaders
+  });
+}
+function buildStoreKey(handlerKey, clientKey) {
+  const encodedHandlerKey = encodeURIComponent(handlerKey);
+  const encodedClientKey = encodeURIComponent(clientKey);
+  return `throttler:${encodedHandlerKey}:${encodedClientKey}`;
+}
+function buildHandlerKey(handler) {
+  const version = handler.route.version ?? handler.metadata.effectiveVersion ?? 'unversioned';
+  return [`method:${handler.route.method}`, `path:${encodeURIComponent(handler.route.path)}`, `version:${encodeURIComponent(version)}`, `handler:${encodeURIComponent(handler.methodName)}`].join('|');
+}
+
+/**
+ * Guard that enforces module-, class-, and method-level throttling policies.
+ */
+let _ThrottlerGuard;
+class ThrottlerGuard {
+  static {
+    [_ThrottlerGuard, _initClass] = _applyDecs(this, [Inject(THROTTLER_OPTIONS)], []).c;
+  }
+  store;
+  constructor(options) {
+    this.options = options;
+    validateThrottlerModuleOptions(options);
+    this.store = options.store ?? createMemoryThrottlerStore();
+  }
+
+  /**
+   * Evaluate whether the current request is still within its allowed rate-limit window.
+   *
+   * @param context Guard execution context for the current handler invocation.
+   * @returns `true` when the request is allowed to proceed.
+   * @throws TooManyRequestsException When the request exceeds the configured limit.
+   */
+  async canActivate(context) {
+    const {
+      handler,
+      requestContext
+    } = context;
+    const classBag = getClassMetadataBag(handler.controllerToken);
+    const methodBag = getMethodMetadataBag(handler.controllerToken, handler.methodName);
+    const classSkip = classBag ? getClassSkipThrottleMetadata(classBag) : false;
+    const methodSkip = methodBag ? getSkipThrottleMetadata(methodBag) : false;
+    if (classSkip || methodSkip) {
+      return true;
+    }
+    const methodThrottle = methodBag ? getThrottleMetadata(methodBag) : undefined;
+    const classThrottle = classBag ? getClassThrottleMetadata(classBag) : undefined;
+    const resolvedThrottle = validateThrottleOptions({
+      limit: methodThrottle?.limit ?? classThrottle?.limit ?? this.options.limit,
+      ttl: methodThrottle?.ttl ?? classThrottle?.ttl ?? this.options.ttl
+    });
+    const ttlSeconds = resolvedThrottle.ttl;
+    const limit = resolvedThrottle.limit;
+    const middlewareCtx = {
+      request: requestContext.request,
+      requestContext,
+      response: requestContext.response
+    };
+    const clientKey = this.options.keyGenerator ? this.options.keyGenerator(middlewareCtx) : defaultKeyGenerator(middlewareCtx, this.options.trustProxyHeaders ?? false);
+    const handlerKey = buildHandlerKey(handler);
+    const storeKey = buildStoreKey(handlerKey, clientKey);
+    const now = Date.now();
+    const entry = validateThrottlerStoreEntry(await this.store.consume(storeKey, {
+      now,
+      ttlSeconds
+    }));
+    if (entry.count > limit) {
+      const retryAfter = Math.ceil((entry.resetAt - now) / 1000);
+      requestContext.response.setHeader('Retry-After', String(retryAfter));
+      throw new TooManyRequestsException('Too Many Requests', {
+        meta: {
+          retryAfter
+        }
+      });
+    }
+    return true;
+  }
+  static {
+    _initClass();
+  }
+}
+export { _ThrottlerGuard as ThrottlerGuard };

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export * from './decorators.js';
+export { ThrottlerGuard } from './guard.js';
+export { RedisThrottlerStore } from './redis-store.js';
+export * from './module.js';
+export * from './status.js';
+export { createMemoryThrottlerStore } from './store.js';
+export { THROTTLER_OPTIONS } from './tokens.js';
+export type { ThrottlerHandlerOptions, ThrottlerModuleOptions, ThrottlerStore, ThrottlerStoreEntry } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC;AAChC,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AACvD,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,OAAO,EAAE,0BAA0B,EAAE,MAAM,YAAY,CAAC;AACxD,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAChD,YAAY,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,7 @@
+export * from './decorators.js';
+export { ThrottlerGuard } from './guard.js';
+export { RedisThrottlerStore } from './redis-store.js';
+export * from './module.js';
+export * from './status.js';
+export { createMemoryThrottlerStore } from './store.js';
+export { THROTTLER_OPTIONS } from './tokens.js';

package/dist/module.d.ts

@@ -0,0 +1,27 @@
+import { type ModuleType } from '@fluojs/runtime';
+import type { ThrottlerModuleOptions } from './types.js';
+/**
+ * Runtime module entrypoint for global throttling.
+ *
+ * @remarks
+ * The module wires one global `ThrottlerGuard`; route-level overrides still come
+ * from `@Throttle(...)` and `@SkipThrottle()` metadata.
+ */
+export declare class ThrottlerModule {
+    /**
+     * Register the global throttling guard with validated module options.
+     *
+     * @param options Module-wide throttling policy.
+     * @returns A runtime module exporting `ThrottlerGuard`.
+     *
+     * @example
+     * ```ts
+     * ThrottlerModule.forRoot({
+     *   ttl: 60,
+     *   limit: 10,
+     * });
+     * ```
+     */
+    static forRoot(options: ThrottlerModuleOptions): ModuleType;
+}
+//# sourceMappingURL=module.d.ts.map

package/dist/module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"module.d.ts","sourceRoot":"","sources":["../src/module.ts"],"names":[],"mappings":"AACA,OAAO,EAAgB,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAIhE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAkBzD;;;;;;GAMG;AACH,qBAAa,eAAe;IAC1B;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,sBAAsB,GAAG,UAAU;CAS5D"}

package/dist/module.js

@@ -0,0 +1,46 @@
+import { defineModule } from '@fluojs/runtime';
+import { ThrottlerGuard } from './guard.js';
+import { THROTTLER_OPTIONS } from './tokens.js';
+import { validateThrottlerModuleOptions } from './validation.js';
+function createThrottlerProviders(options) {
+  const validatedOptions = validateThrottlerModuleOptions(options);
+  return [{
+    provide: THROTTLER_OPTIONS,
+    useValue: validatedOptions
+  }, {
+    provide: ThrottlerGuard,
+    useClass: ThrottlerGuard
+  }];
+}
+
+/**
+ * Runtime module entrypoint for global throttling.
+ *
+ * @remarks
+ * The module wires one global `ThrottlerGuard`; route-level overrides still come
+ * from `@Throttle(...)` and `@SkipThrottle()` metadata.
+ */
+export class ThrottlerModule {
+  /**
+   * Register the global throttling guard with validated module options.
+   *
+   * @param options Module-wide throttling policy.
+   * @returns A runtime module exporting `ThrottlerGuard`.
+   *
+   * @example
+   * ```ts
+   * ThrottlerModule.forRoot({
+   *   ttl: 60,
+   *   limit: 10,
+   * });
+   * ```
+   */
+  static forRoot(options) {
+    class ThrottlerRootModule extends ThrottlerModule {}
+    return defineModule(ThrottlerRootModule, {
+      exports: [ThrottlerGuard],
+      global: true,
+      providers: createThrottlerProviders(options)
+    });
+  }
+}

package/dist/redis-store.d.ts

@@ -0,0 +1,22 @@
+import type Redis from 'ioredis';
+import type { ThrottlerConsumeInput, ThrottlerStore, ThrottlerStoreEntry } from './types.js';
+/**
+ * Redis-backed throttler store for distributed rate limits.
+ *
+ * @remarks
+ * This store uses one atomic Lua script per consume operation so concurrent
+ * requests across instances observe the same counter and reset window.
+ */
+export declare class RedisThrottlerStore implements ThrottlerStore {
+    private readonly client;
+    constructor(client: Redis);
+    /**
+     * Consume one throttle slot for the provided key.
+     *
+     * @param key Stable throttle key derived from the current request.
+     * @param input Current timestamp and TTL window in seconds.
+     * @returns The updated counter value and reset timestamp for the current window.
+     */
+    consume(key: string, input: ThrottlerConsumeInput): Promise<ThrottlerStoreEntry>;
+}
+//# sourceMappingURL=redis-store.d.ts.map

package/dist/redis-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redis-store.d.ts","sourceRoot":"","sources":["../src/redis-store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,SAAS,CAAC;AAEjC,OAAO,KAAK,EAAE,qBAAqB,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AA4C7F;;;;;;GAMG;AACH,qBAAa,mBAAoB,YAAW,cAAc;IAC5C,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,KAAK;IAE1C;;;;;;OAMG;IACG,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,qBAAqB,GAAG,OAAO,CAAC,mBAAmB,CAAC;CAWvF"}

package/dist/redis-store.js

@@ -0,0 +1,41 @@
+import { validateThrottlerStoreEntry } from './validation.js';
+const CONSUME_LUA = ["local key = KEYS[1]", "local now = tonumber(ARGV[1])", "local ttlMs = tonumber(ARGV[2])", "local raw = redis.call('GET', key)", "local count", "local resetAt", 'if not raw then', '  count = 1', '  resetAt = now + ttlMs', 'else', '  local decoded = cjson.decode(raw)', "  count = tonumber(decoded['count']) or 0", "  resetAt = tonumber(decoded['resetAt']) or (now + ttlMs)", '  if now >= resetAt then', '    count = 1', '    resetAt = now + ttlMs', '  else', '    count = count + 1', '  end', 'end', 'local ttlMsLeft = math.max(resetAt - now, 1)', "redis.call('SET', key, cjson.encode({ count = count, resetAt = resetAt }), 'PX', ttlMsLeft)", 'return {count, resetAt}'].join('\n');
+function parseConsumeResult(result) {
+  if (!Array.isArray(result) || result.length < 2) {
+    throw new Error('Redis throttler consume script returned an invalid response.');
+  }
+  const count = Number(result[0]);
+  const resetAt = Number(result[1]);
+  if (!Number.isFinite(count) || !Number.isFinite(resetAt)) {
+    throw new Error('Redis throttler consume script returned non-numeric counters.');
+  }
+  return validateThrottlerStoreEntry({
+    count,
+    resetAt
+  });
+}
+
+/**
+ * Redis-backed throttler store for distributed rate limits.
+ *
+ * @remarks
+ * This store uses one atomic Lua script per consume operation so concurrent
+ * requests across instances observe the same counter and reset window.
+ */
+export class RedisThrottlerStore {
+  constructor(client) {
+    this.client = client;
+  }
+
+  /**
+   * Consume one throttle slot for the provided key.
+   *
+   * @param key Stable throttle key derived from the current request.
+   * @param input Current timestamp and TTL window in seconds.
+   * @returns The updated counter value and reset timestamp for the current window.
+   */
+  async consume(key, input) {
+    const result = await this.client.eval(CONSUME_LUA, 1, key, String(input.now), String(input.ttlSeconds * 1000));
+    return parseConsumeResult(result);
+  }
+}

package/dist/status.d.ts

@@ -0,0 +1,50 @@
+import type { PlatformDiagnosticIssue, PlatformHealthReport, PlatformReadinessReport, PlatformSnapshot } from '@fluojs/runtime';
+/**
+ * Snapshot shape produced by the throttler platform status helpers.
+ */
+export interface ThrottlerPlatformStatusSnapshot {
+    readiness: PlatformReadinessReport;
+    health: PlatformHealthReport;
+    ownership: PlatformSnapshot['ownership'];
+    details: Record<string, unknown>;
+}
+/**
+ * Backing store categories recognized by the throttler status adapter.
+ */
+export type ThrottlerStoreKind = 'memory' | 'redis' | 'custom';
+/**
+ * Ownership modes used to describe who is responsible for the throttler store lifecycle.
+ */
+export type ThrottlerStoreOwnershipMode = 'framework' | 'external';
+/**
+ * Deployment modes used to describe whether throttling is local or distributed.
+ */
+export type ThrottlerOperationMode = 'local-only' | 'distributed' | 'local-fallback' | 'custom';
+/**
+ * Input consumed by throttler status and diagnostic helpers.
+ */
+export interface ThrottlerStatusAdapterInput {
+    componentId?: string;
+    storeKind: ThrottlerStoreKind;
+    storeOwnershipMode?: ThrottlerStoreOwnershipMode;
+    operationMode?: ThrottlerOperationMode;
+    backingStoreReady?: boolean;
+    backingStoreReason?: string;
+    dependencyId?: string;
+    readinessCritical?: boolean;
+}
+/**
+ * Create a platform status snapshot for throttler readiness, health, and telemetry.
+ *
+ * @param input Store metadata and readiness hints collected during bootstrap.
+ * @returns A throttler status snapshot suitable for platform diagnostics.
+ */
+export declare function createThrottlerPlatformStatusSnapshot(input: ThrottlerStatusAdapterInput): ThrottlerPlatformStatusSnapshot;
+/**
+ * Translate throttler readiness input into platform diagnostic issues.
+ *
+ * @param input Store metadata and readiness hints collected during bootstrap.
+ * @returns Zero or more diagnostic issues describing degraded or unavailable throttler backing stores.
+ */
+export declare function createThrottlerPlatformDiagnosticIssues(input: ThrottlerStatusAdapterInput): PlatformDiagnosticIssue[];
+//# sourceMappingURL=status.d.ts.map

package/dist/status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../src/status.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,uBAAuB,EAAE,oBAAoB,EAAE,uBAAuB,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAEhI;;GAEG;AACH,MAAM,WAAW,+BAA+B;IAC9C,SAAS,EAAE,uBAAuB,CAAC;IACnC,MAAM,EAAE,oBAAoB,CAAC;IAC7B,SAAS,EAAE,gBAAgB,CAAC,WAAW,CAAC,CAAC;IACzC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG,QAAQ,GAAG,OAAO,GAAG,QAAQ,CAAC;AAE/D;;GAEG;AACH,MAAM,MAAM,2BAA2B,GAAG,WAAW,GAAG,UAAU,CAAC;AAEnE;;GAEG;AACH,MAAM,MAAM,sBAAsB,GAAG,YAAY,GAAG,aAAa,GAAG,gBAAgB,GAAG,QAAQ,CAAC;AAEhG;;GAEG;AACH,MAAM,WAAW,2BAA2B;IAC1C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,kBAAkB,CAAC;IAC9B,kBAAkB,CAAC,EAAE,2BAA2B,CAAC;IACjD,aAAa,CAAC,EAAE,sBAAsB,CAAC;IACvC,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAgED;;;;;GAKG;AACH,wBAAgB,qCAAqC,CAAC,KAAK,EAAE,2BAA2B,GAAG,+BAA+B,CAiCzH;AAED;;;;;GAKG;AACH,wBAAgB,uCAAuC,CAAC,KAAK,EAAE,2BAA2B,GAAG,uBAAuB,EAAE,CAuBrH"}

package/dist/status.js

@@ -0,0 +1,132 @@
+/**
+ * Snapshot shape produced by the throttler platform status helpers.
+ */
+
+/**
+ * Backing store categories recognized by the throttler status adapter.
+ */
+
+/**
+ * Ownership modes used to describe who is responsible for the throttler store lifecycle.
+ */
+
+/**
+ * Deployment modes used to describe whether throttling is local or distributed.
+ */
+
+/**
+ * Input consumed by throttler status and diagnostic helpers.
+ */
+
+function resolveStoreOwnershipMode(input) {
+  if (input.storeOwnershipMode) {
+    return input.storeOwnershipMode;
+  }
+  return input.storeKind === 'memory' ? 'framework' : 'external';
+}
+function resolveOperationMode(input) {
+  if (input.operationMode) {
+    return input.operationMode;
+  }
+  if (input.storeKind === 'redis') {
+    return 'distributed';
+  }
+  if (input.storeKind === 'memory') {
+    return 'local-only';
+  }
+  return 'custom';
+}
+function isBackingStoreReady(input) {
+  if (input.backingStoreReady !== undefined) {
+    return input.backingStoreReady;
+  }
+  return true;
+}
+function createReadiness(input) {
+  const critical = input.readinessCritical ?? false;
+  if (isBackingStoreReady(input)) {
+    return {
+      critical,
+      status: 'ready'
+    };
+  }
+  return {
+    critical,
+    reason: input.backingStoreReason ?? 'Throttler backing store is unavailable.',
+    status: critical ? 'not-ready' : 'degraded'
+  };
+}
+function createHealth(input) {
+  if (!isBackingStoreReady(input)) {
+    return {
+      reason: input.backingStoreReason ?? 'Throttler backing store is unavailable.',
+      status: 'degraded'
+    };
+  }
+  return {
+    status: 'healthy'
+  };
+}
+
+/**
+ * Create a platform status snapshot for throttler readiness, health, and telemetry.
+ *
+ * @param input Store metadata and readiness hints collected during bootstrap.
+ * @returns A throttler status snapshot suitable for platform diagnostics.
+ */
+export function createThrottlerPlatformStatusSnapshot(input) {
+  const storeOwnershipMode = resolveStoreOwnershipMode(input);
+  const operationMode = resolveOperationMode(input);
+  const backingReady = isBackingStoreReady(input);
+  const componentId = input.componentId ?? 'throttler.default';
+  return {
+    details: {
+      backingStore: {
+        dependencyId: input.dependencyId,
+        reason: input.backingStoreReason,
+        ready: backingReady
+      },
+      operationMode,
+      storeKind: input.storeKind,
+      storeOwnershipMode,
+      telemetry: {
+        labels: {
+          component_id: componentId,
+          component_kind: 'throttler',
+          operation: 'request-throttle',
+          result: backingReady ? 'ready' : 'degraded'
+        },
+        namespace: 'throttler'
+      }
+    },
+    health: createHealth(input),
+    ownership: {
+      externallyManaged: storeOwnershipMode === 'external',
+      ownsResources: storeOwnershipMode === 'framework'
+    },
+    readiness: createReadiness(input)
+  };
+}
+
+/**
+ * Translate throttler readiness input into platform diagnostic issues.
+ *
+ * @param input Store metadata and readiness hints collected during bootstrap.
+ * @returns Zero or more diagnostic issues describing degraded or unavailable throttler backing stores.
+ */
+export function createThrottlerPlatformDiagnosticIssues(input) {
+  if (isBackingStoreReady(input)) {
+    return [];
+  }
+  const componentId = input.componentId ?? 'throttler.default';
+  const critical = input.readinessCritical ?? false;
+  return [{
+    code: 'THROTTLER_BACKING_STORE_NOT_READY',
+    componentId,
+    cause: input.backingStoreReason,
+    dependsOn: input.dependencyId ? [input.dependencyId] : undefined,
+    fixHint: input.storeKind === 'redis' ? 'Verify Redis connectivity or switch to local throttler store for non-critical environments.' : 'Restore the throttler backing store or disable throttling for this environment.',
+    message: critical ? 'Throttler is configured as critical, but its backing store is not ready.' : 'Throttler backing store is degraded; request traffic can continue in non-critical mode.',
+    severity: critical ? 'error' : 'warning'
+  }];
+}

package/dist/store.d.ts

@@ -0,0 +1,17 @@
+import type { ThrottlerStore } from './types.js';
+/**
+ * Create the default in-memory throttler store used by `ThrottlerModule`.
+ *
+ * @returns A store that keeps throttle counters isolated to the current process.
+ *
+ * @remarks
+ * This store is intentionally local-only. Use `RedisThrottlerStore` when rate
+ * limits must be shared across multiple application instances.
+ *
+ * @example
+ * ```ts
+ * const store = createMemoryThrottlerStore();
+ * ```
+ */
+export declare function createMemoryThrottlerStore(): ThrottlerStore;
+//# sourceMappingURL=store.d.ts.map

package/dist/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAyB,cAAc,EAAuB,MAAM,YAAY,CAAC;AAoC7F;;;;;;;;;;;;;GAaG;AACH,wBAAgB,0BAA0B,IAAI,cAAc,CAkB3D"}

package/dist/store.js

@@ -0,0 +1,60 @@
+function consumeWindow(entry, {
+  now,
+  ttlSeconds
+}) {
+  const resetAt = now + ttlSeconds * 1000;
+  if (!entry || now >= entry.resetAt) {
+    return {
+      count: 1,
+      resetAt
+    };
+  }
+  return {
+    count: entry.count + 1,
+    resetAt: entry.resetAt
+  };
+}
+function sweepExpiredEntries(map, now) {
+  let nextSweepAt = Number.POSITIVE_INFINITY;
+  for (const [entryKey, entry] of map) {
+    if (now >= entry.resetAt) {
+      map.delete(entryKey);
+      continue;
+    }
+    nextSweepAt = Math.min(nextSweepAt, entry.resetAt);
+  }
+  return Number.isFinite(nextSweepAt) ? nextSweepAt : 0;
+}
+
+/**
+ * Create the default in-memory throttler store used by `ThrottlerModule`.
+ *
+ * @returns A store that keeps throttle counters isolated to the current process.
+ *
+ * @remarks
+ * This store is intentionally local-only. Use `RedisThrottlerStore` when rate
+ * limits must be shared across multiple application instances.
+ *
+ * @example
+ * ```ts
+ * const store = createMemoryThrottlerStore();
+ * ```
+ */
+export function createMemoryThrottlerStore() {
+  const map = new Map();
+  let nextSweepAt = 0;
+  return {
+    consume(key, input) {
+      const {
+        now
+      } = input;
+      if (now >= nextSweepAt) {
+        nextSweepAt = sweepExpiredEntries(map, now);
+      }
+      const nextEntry = consumeWindow(map.get(key), input);
+      map.set(key, nextEntry);
+      nextSweepAt = nextSweepAt === 0 ? nextEntry.resetAt : Math.min(nextSweepAt, nextEntry.resetAt);
+      return nextEntry;
+    }
+  };
+}

package/dist/tokens.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Injection token for the throttler module options.
+ */
+export declare const THROTTLER_OPTIONS: unique symbol;
+//# sourceMappingURL=tokens.d.ts.map

package/dist/tokens.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../src/tokens.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,eAAO,MAAM,iBAAiB,eAAuC,CAAC"}

package/dist/tokens.js

@@ -0,0 +1,4 @@
+/**
+ * Injection token for the throttler module options.
+ */
+export const THROTTLER_OPTIONS = Symbol.for('fluo.throttler.options');

package/dist/types.d.ts

@@ -0,0 +1,52 @@
+import type { MiddlewareContext } from '@fluojs/http';
+/**
+ * Snapshot of a client's current rate-limit window state.
+ */
+export interface ThrottlerStoreEntry {
+    count: number;
+    resetAt: number;
+}
+/**
+ * Input passed to a `ThrottlerStore` when consuming a request slot.
+ */
+export interface ThrottlerConsumeInput {
+    now: number;
+    ttlSeconds: number;
+}
+/**
+ * Store contract used by `ThrottlerGuard` to track request windows.
+ */
+export interface ThrottlerStore {
+    consume(key: string, input: ThrottlerConsumeInput): ThrottlerStoreEntry | Promise<ThrottlerStoreEntry>;
+}
+/**
+ * Per-handler or per-controller throttle override.
+ */
+export interface ThrottlerHandlerOptions {
+    /** Seconds in the rate-limit window. */
+    ttl: number;
+    /** Maximum number of requests allowed within the window. */
+    limit: number;
+}
+/**
+ * Public configuration options for `ThrottlerModule.forRoot(...)`.
+ */
+export interface ThrottlerModuleOptions {
+    /** Seconds in the rate-limit window (module-wide default). */
+    ttl: number;
+    /** Maximum number of requests allowed within the window (module-wide default). */
+    limit: number;
+    /**
+     * Trust `Forwarded`, `X-Forwarded-For`, and `X-Real-IP` before the raw socket address.
+     * Enable this only when the adapter sits behind a trusted proxy that rewrites those headers.
+     */
+    trustProxyHeaders?: boolean;
+    /**
+     * Key generator function. Defaults to conservative client identity resolution.
+     * Receives the raw middleware context so custom headers (e.g. x-api-key) can be used.
+     */
+    keyGenerator?: (ctx: MiddlewareContext) => string;
+    /** Store adapter. Defaults to the built-in in-memory store. */
+    store?: ThrottlerStore;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAEtD;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,qBAAqB,GAAG,mBAAmB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;CACxG;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,wCAAwC;IACxC,GAAG,EAAE,MAAM,CAAC;IACZ,4DAA4D;IAC5D,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,8DAA8D;IAC9D,GAAG,EAAE,MAAM,CAAC;IACZ,kFAAkF;IAClF,KAAK,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B;;;OAGG;IACH,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,iBAAiB,KAAK,MAAM,CAAC;IAClD,+DAA+D;IAC/D,KAAK,CAAC,EAAE,cAAc,CAAC;CACxB"}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/validation.d.ts

@@ -0,0 +1,23 @@
+import type { ThrottlerHandlerOptions, ThrottlerModuleOptions, ThrottlerStoreEntry } from './types.js';
+/**
+ * Validate one per-handler or module-level throttle policy.
+ *
+ * @param options Candidate throttle settings.
+ * @returns A normalized throttle policy safe for runtime use.
+ */
+export declare function validateThrottleOptions(options: ThrottlerHandlerOptions): ThrottlerHandlerOptions;
+/**
+ * Validate the public module options passed to `ThrottlerModule.forRoot(...)`.
+ *
+ * @param options Candidate module-wide throttler settings.
+ * @returns A validated copy of the throttler module options.
+ */
+export declare function validateThrottlerModuleOptions(options: ThrottlerModuleOptions): ThrottlerModuleOptions;
+/**
+ * Validate one store-consume result before enforcing throttling decisions.
+ *
+ * @param entry Candidate store state returned by a throttler store.
+ * @returns A validated throttler store entry.
+ */
+export declare function validateThrottlerStoreEntry(entry: ThrottlerStoreEntry): ThrottlerStoreEntry;
+//# sourceMappingURL=validation.d.ts.map

package/dist/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAoBvG;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,uBAAuB,GAAG,uBAAuB,CAOjG;AAED;;;;;GAKG;AACH,wBAAgB,8BAA8B,CAAC,OAAO,EAAE,sBAAsB,GAAG,sBAAsB,CAWtG;AAED;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,mBAAmB,GAAG,mBAAmB,CAQ3F"}

package/dist/validation.js

@@ -0,0 +1,63 @@
+function assertPositiveFiniteInteger(value, field) {
+  if (!Number.isFinite(value) || !Number.isInteger(value) || value <= 0) {
+    throw new Error(`Invalid throttler ${field}: expected a positive finite integer.`);
+  }
+}
+function assertFiniteInteger(value, field) {
+  if (!Number.isFinite(value) || !Number.isInteger(value)) {
+    throw new Error(`Invalid throttler ${field}: expected a finite integer.`);
+  }
+}
+function assertOptionalBoolean(value, field) {
+  if (value !== undefined && typeof value !== 'boolean') {
+    throw new Error(`Invalid throttler ${field}: expected a boolean when provided.`);
+  }
+}
+
+/**
+ * Validate one per-handler or module-level throttle policy.
+ *
+ * @param options Candidate throttle settings.
+ * @returns A normalized throttle policy safe for runtime use.
+ */
+export function validateThrottleOptions(options) {
+  assertPositiveFiniteInteger(options.limit, 'limit');
+  assertPositiveFiniteInteger(options.ttl, 'ttl');
+  return {
+    limit: options.limit,
+    ttl: options.ttl
+  };
+}
+
+/**
+ * Validate the public module options passed to `ThrottlerModule.forRoot(...)`.
+ *
+ * @param options Candidate module-wide throttler settings.
+ * @returns A validated copy of the throttler module options.
+ */
+export function validateThrottlerModuleOptions(options) {
+  validateThrottleOptions(options);
+  assertOptionalBoolean(options.trustProxyHeaders, 'trustProxyHeaders');
+  return {
+    keyGenerator: options.keyGenerator,
+    limit: options.limit,
+    store: options.store,
+    trustProxyHeaders: options.trustProxyHeaders,
+    ttl: options.ttl
+  };
+}
+
+/**
+ * Validate one store-consume result before enforcing throttling decisions.
+ *
+ * @param entry Candidate store state returned by a throttler store.
+ * @returns A validated throttler store entry.
+ */
+export function validateThrottlerStoreEntry(entry) {
+  assertPositiveFiniteInteger(entry.count, 'store count');
+  assertFiniteInteger(entry.resetAt, 'store resetAt');
+  return {
+    count: entry.count,
+    resetAt: entry.resetAt
+  };
+}

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@fluojs/throttler",
+  "description": "Decorator-based rate limiting for Fluo applications with in-memory and Redis store adapters.",
+  "keywords": [
+    "fluo",
+    "throttler",
+    "rate-limit",
+    "rate-limiting",
+    "redis",
+    "decorator"
+  ],
+  "version": "1.0.0-beta.1",
+  "private": false,
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/fluojs/fluo.git",
+    "directory": "packages/throttler"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@fluojs/core": "^1.0.0-beta.1",
+    "@fluojs/runtime": "^1.0.0-beta.1",
+    "@fluojs/di": "^1.0.0-beta.1",
+    "@fluojs/http": "^1.0.0-beta.1"
+  },
+  "peerDependencies": {
+    "ioredis": "^5.0.0",
+    "@fluojs/redis": "^1.0.0-beta.1"
+  },
+  "peerDependenciesMeta": {
+    "@fluojs/redis": {
+      "optional": true
+    },
+    "ioredis": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "ioredis": "^5.10.0",
+    "vitest": "^3.2.4"
+  },
+  "scripts": {
+    "prebuild": "node ../../tooling/scripts/clean-dist.mjs",
+    "build": "pnpm exec babel src --extensions .ts --ignore 'src/**/*.test.ts' --out-dir dist --config-file ../../tooling/babel/babel.config.cjs && pnpm exec tsc -p tsconfig.build.json",
+    "typecheck": "pnpm exec tsc -p tsconfig.json --noEmit",
+    "test": "pnpm exec vitest run -c vitest.config.ts",
+    "test:watch": "pnpm exec vitest -c vitest.config.ts"
+  }
+}