fluxguard 0.1.1

package/dist/index.d.cts

@@ -0,0 +1,125 @@
+import { RedisOptions, Redis } from 'ioredis';
+import { Request, Response, RequestHandler } from 'express';
+import { Registry, Counter } from 'prom-client';
+
+declare enum Algorithm {
+    FIXED_WINDOW = "FIXED_WINDOW",
+    SLIDING_WINDOW_LOG = "SLIDING_WINDOW_LOG",
+    SLIDING_WINDOW_COUNTER = "SLIDING_WINDOW_COUNTER",
+    TOKEN_BUCKET = "TOKEN_BUCKET"
+}
+type RateLimitResult = {
+    allowed: boolean;
+    limit: number;
+    remaining: number;
+    /** Epoch ms when the current window resets or limit fully replenishes (best effort). */
+    resetMs: number;
+    /** Suggested retry-after in ms when throttled. */
+    retryAfterMs?: number;
+    algorithm: Algorithm;
+};
+type FluxGuardMetricsSnapshot = {
+    totalChecks: number;
+    allowed: number;
+    throttled: number;
+    redisErrors: number;
+};
+type FluxGuardEvents = {
+    onAllowed?: (key: string, result: RateLimitResult) => void;
+    onThrottled?: (key: string, result: RateLimitResult) => void;
+    onRedisError?: (err: unknown) => void;
+};
+type FluxGuardConfig = {
+    algorithm: Algorithm;
+    /** Max requests (or burst capacity for token bucket). */
+    limit: number;
+    windowMs: number;
+    /** Redis connection — omit for in-memory limiting. */
+    redis?: RedisOptions | Redis;
+    keyPrefix?: string;
+    /** Injected clock — default `Date.now`. */
+    nowFn?: () => number;
+    failOpen?: boolean;
+    /** Optional external metrics hook — receives snapshot after each successful check path. */
+    metrics?: {
+        record?: (s: FluxGuardMetricsSnapshot) => void;
+    };
+    events?: FluxGuardEvents;
+};
+
+declare class FluxGuard {
+    private readonly cfg;
+    private readonly store;
+    private readonly prefix;
+    private readonly nowFn;
+    private readonly config;
+    private metrics;
+    constructor(cfg: FluxGuardConfig);
+    getMetrics(): FluxGuardMetricsSnapshot;
+    /** Merge event recording for external metrics (e.g. Prometheus). */
+    onMetricsRecord(fn: (snapshot: FluxGuardMetricsSnapshot) => void): void;
+    check(key: string): Promise<RateLimitResult>;
+    private checkLocal;
+}
+
+/**
+ * Storage abstraction: local Map or Redis (Lua via evalScript).
+ */
+interface Store {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, ttlMs: number): Promise<void>;
+    del(key: string): Promise<void>;
+    /**
+     * Execute Lua atomically (Redis). Local store may throw if used.
+     */
+    evalScript(script: string, keys: string[], args: (string | number)[]): Promise<unknown[]>;
+}
+
+declare class LocalStore implements Store {
+    private readonly clock;
+    private readonly data;
+    constructor(clock?: () => number);
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, ttlMs: number): Promise<void>;
+    del(key: string): Promise<void>;
+    evalScript(): Promise<unknown[]>;
+    /** Test helper: clear all keys */
+    _clear(): void;
+}
+
+declare class RedisStore implements Store {
+    private readonly redis;
+    private readonly owns;
+    private readonly shaCache;
+    constructor(redis: Redis | RedisOptions, optionsIsObject: boolean);
+    loadScriptFile(filename: string): string;
+    disconnect(): void;
+    get redisClient(): Redis;
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, ttlMs: number): Promise<void>;
+    del(key: string): Promise<void>;
+    evalScript(script: string, keys: string[], args: (string | number)[]): Promise<unknown[]>;
+}
+
+type ExpressLimiterOptions = {
+    keyExtract?: (req: Request) => string;
+    onThrottled?: (req: Request, res: Response, result: RateLimitResult) => void;
+    skipSuccessfulRequests?: boolean;
+    skipFailedRequests?: boolean;
+    headers?: boolean;
+};
+declare function fluxGuardMiddleware(limiter: FluxGuard, options?: ExpressLimiterOptions): RequestHandler;
+
+type PrometheusMetrics = {
+    registry: Registry;
+    checksTotal: Counter<string>;
+    allowedTotal: Counter<string>;
+    throttledTotal: Counter<string>;
+    redisErrorsTotal: Counter<string>;
+};
+declare function createFluxGuardPrometheusMetrics(limiter: FluxGuard, options?: {
+    prefix?: string;
+    collectDefault?: boolean;
+}): PrometheusMetrics;
+
+export { Algorithm, type ExpressLimiterOptions, FluxGuard, type FluxGuardConfig, LocalStore, type PrometheusMetrics, type RateLimitResult, RedisStore, type Store, createFluxGuardPrometheusMetrics, fluxGuardMiddleware };

package/dist/index.d.ts

@@ -0,0 +1,125 @@
+import { RedisOptions, Redis } from 'ioredis';
+import { Request, Response, RequestHandler } from 'express';
+import { Registry, Counter } from 'prom-client';
+
+declare enum Algorithm {
+    FIXED_WINDOW = "FIXED_WINDOW",
+    SLIDING_WINDOW_LOG = "SLIDING_WINDOW_LOG",
+    SLIDING_WINDOW_COUNTER = "SLIDING_WINDOW_COUNTER",
+    TOKEN_BUCKET = "TOKEN_BUCKET"
+}
+type RateLimitResult = {
+    allowed: boolean;
+    limit: number;
+    remaining: number;
+    /** Epoch ms when the current window resets or limit fully replenishes (best effort). */
+    resetMs: number;
+    /** Suggested retry-after in ms when throttled. */
+    retryAfterMs?: number;
+    algorithm: Algorithm;
+};
+type FluxGuardMetricsSnapshot = {
+    totalChecks: number;
+    allowed: number;
+    throttled: number;
+    redisErrors: number;
+};
+type FluxGuardEvents = {
+    onAllowed?: (key: string, result: RateLimitResult) => void;
+    onThrottled?: (key: string, result: RateLimitResult) => void;
+    onRedisError?: (err: unknown) => void;
+};
+type FluxGuardConfig = {
+    algorithm: Algorithm;
+    /** Max requests (or burst capacity for token bucket). */
+    limit: number;
+    windowMs: number;
+    /** Redis connection — omit for in-memory limiting. */
+    redis?: RedisOptions | Redis;
+    keyPrefix?: string;
+    /** Injected clock — default `Date.now`. */
+    nowFn?: () => number;
+    failOpen?: boolean;
+    /** Optional external metrics hook — receives snapshot after each successful check path. */
+    metrics?: {
+        record?: (s: FluxGuardMetricsSnapshot) => void;
+    };
+    events?: FluxGuardEvents;
+};
+
+declare class FluxGuard {
+    private readonly cfg;
+    private readonly store;
+    private readonly prefix;
+    private readonly nowFn;
+    private readonly config;
+    private metrics;
+    constructor(cfg: FluxGuardConfig);
+    getMetrics(): FluxGuardMetricsSnapshot;
+    /** Merge event recording for external metrics (e.g. Prometheus). */
+    onMetricsRecord(fn: (snapshot: FluxGuardMetricsSnapshot) => void): void;
+    check(key: string): Promise<RateLimitResult>;
+    private checkLocal;
+}
+
+/**
+ * Storage abstraction: local Map or Redis (Lua via evalScript).
+ */
+interface Store {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, ttlMs: number): Promise<void>;
+    del(key: string): Promise<void>;
+    /**
+     * Execute Lua atomically (Redis). Local store may throw if used.
+     */
+    evalScript(script: string, keys: string[], args: (string | number)[]): Promise<unknown[]>;
+}
+
+declare class LocalStore implements Store {
+    private readonly clock;
+    private readonly data;
+    constructor(clock?: () => number);
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, ttlMs: number): Promise<void>;
+    del(key: string): Promise<void>;
+    evalScript(): Promise<unknown[]>;
+    /** Test helper: clear all keys */
+    _clear(): void;
+}
+
+declare class RedisStore implements Store {
+    private readonly redis;
+    private readonly owns;
+    private readonly shaCache;
+    constructor(redis: Redis | RedisOptions, optionsIsObject: boolean);
+    loadScriptFile(filename: string): string;
+    disconnect(): void;
+    get redisClient(): Redis;
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, ttlMs: number): Promise<void>;
+    del(key: string): Promise<void>;
+    evalScript(script: string, keys: string[], args: (string | number)[]): Promise<unknown[]>;
+}
+
+type ExpressLimiterOptions = {
+    keyExtract?: (req: Request) => string;
+    onThrottled?: (req: Request, res: Response, result: RateLimitResult) => void;
+    skipSuccessfulRequests?: boolean;
+    skipFailedRequests?: boolean;
+    headers?: boolean;
+};
+declare function fluxGuardMiddleware(limiter: FluxGuard, options?: ExpressLimiterOptions): RequestHandler;
+
+type PrometheusMetrics = {
+    registry: Registry;
+    checksTotal: Counter<string>;
+    allowedTotal: Counter<string>;
+    throttledTotal: Counter<string>;
+    redisErrorsTotal: Counter<string>;
+};
+declare function createFluxGuardPrometheusMetrics(limiter: FluxGuard, options?: {
+    prefix?: string;
+    collectDefault?: boolean;
+}): PrometheusMetrics;
+
+export { Algorithm, type ExpressLimiterOptions, FluxGuard, type FluxGuardConfig, LocalStore, type PrometheusMetrics, type RateLimitResult, RedisStore, type Store, createFluxGuardPrometheusMetrics, fluxGuardMiddleware };