halt-rate 0.2.0 → 0.3.0

package/dist/limiter-HCt8ADZ2.d.mts

@@ -1,177 +0,0 @@
-/**
- * Decision model for rate limiting results.
- */
-interface Decision {
-    /** Whether the request is allowed */
-    allowed: boolean;
-    /** Maximum number of requests allowed in the window */
-    limit: number;
-    /** Number of requests remaining in the current window */
-    remaining: number;
-    /** Unix timestamp when the limit resets */
-    resetAt: number;
-    /** Seconds to wait before retrying (only set when blocked) */
-    retryAfter?: number;
-}
-/**
- * Convert decision to standard rate limit headers.
- */
-declare function toHeaders(decision: Decision): Record<string, string>;
-
-/**
- * Policy model for rate limiting configuration.
- */
-declare enum KeyStrategy {
-    IP = "ip",
-    USER = "user",
-    API_KEY = "api_key",
-    COMPOSITE = "composite",
-    CUSTOM = "custom"
-}
-declare enum Algorithm {
-    TOKEN_BUCKET = "token_bucket",
-    FIXED_WINDOW = "fixed_window",
-    SLIDING_WINDOW = "sliding_window",
-    LEAKY_BUCKET = "leaky_bucket"
-}
-interface Policy {
-    /** Human-readable policy name */
-    name: string;
-    /** Maximum number of requests allowed */
-    limit: number;
-    /** Time window in seconds */
-    window: number;
-    /** Rate limiting algorithm to use */
-    algorithm?: Algorithm;
-    /** Strategy for extracting the rate limit key */
-    keyStrategy?: KeyStrategy;
-    /** Maximum burst size (for token bucket) */
-    burst?: number;
-    /** Cost per request (default: 1) */
-    cost?: number;
-    /** Duration to block after limit exceeded (seconds) */
-    blockDuration?: number;
-    /** Custom function to extract key from request */
-    keyExtractor?: (request: any) => string | null;
-    /** List of paths or IPs to exempt from rate limiting */
-    exemptions?: string[];
-}
-/**
- * Validate and normalize policy configuration.
- */
-declare function normalizePolicy(policy: Policy): Required<Policy>;
-
-/**
- * In-memory storage backend for rate limiting.
- */
-interface Store {
-    get(key: string): any;
-    set(key: string, value: any, ttl?: number): void;
-    increment(key: string, delta?: number, ttl?: number): number;
-    delete(key: string): void;
-}
-declare class InMemoryStore implements Store {
-    private data;
-    get(key: string): any;
-    set(key: string, value: any, ttl?: number): void;
-    increment(key: string, delta?: number, ttl?: number): number;
-    delete(key: string): void;
-    private cleanupExpired;
-    /**
-     * Clean up all expired keys.
-     */
-    cleanupAllExpired(): number;
-}
-
-/**
- * Atomic-evaluation protocol.
- *
- * Simple stores (e.g. InMemoryStore) expose get/set and let the limiter run the
- * algorithm in-process. Distributed stores that can compute the decision
- * atomically (e.g. RedisStore via Lua) instead expose `evaluate()`: the limiter
- * hands them the resolved policy params + storage key and gets back a finished
- * Decision. The limiter prefers `evaluate()` when present (see core/limiter.ts).
- */
-
-/** Everything an atomic store needs to compute a decision for one request. */
-interface EvaluateInput {
-    /** Full storage key, already namespaced (e.g. `halt:public_api:1.2.3.4`). */
-    key: string;
-    /** Algorithm to apply. */
-    algorithm: Algorithm;
-    /** Requests permitted per window. */
-    limit: number;
-    /** Window length in seconds. */
-    window: number;
-    /** Bucket capacity (token/leaky bucket). */
-    burst: number;
-    /** Cost this request consumes. */
-    cost: number;
-    /** Seconds to keep the key alive in the backing store. */
-    ttl: number;
-}
-/** A store that computes the rate-limit decision atomically on its own. */
-interface AtomicStore {
-    evaluate(input: EvaluateInput): Promise<Decision>;
-}
-/** True if the store implements the atomic-evaluation protocol. */
-declare function isAtomicStore(store: unknown): store is AtomicStore;
-/**
- * Minimal structural type for a Redis client (satisfied by ioredis and
- * node-redis v4+). Declared here so Halt has no hard dependency on any concrete
- * Redis package — the user injects their own client.
- */
-interface RedisClientLike {
-    eval(script: string, numKeys: number, ...args: (string | number)[]): Promise<unknown>;
-    evalsha?(sha: string, numKeys: number, ...args: (string | number)[]): Promise<unknown>;
-    script?(subcommand: 'LOAD', script: string): Promise<unknown>;
-}
-
-/**
- * Main rate limiter implementation.
- */
-
-interface RateLimiterOptions {
-    /**
-     * Storage backend. Either a simple KV store (InMemoryStore — the limiter runs
-     * the algorithm in-process) or an atomic store (RedisStore — the store
-     * computes the decision atomically via Lua).
-     */
-    store: Store | AtomicStore;
-    /** Either a static policy or a resolver returning a policy per-request */
-    policy: Policy | ((request: any) => Policy | Promise<Policy>);
-    trustedProxies?: string[];
-    exemptPrivateIps?: boolean;
-    /** Optional OpenTelemetry-like tracer (object with startSpan) */
-    otelTracer?: any;
-    /** Optional metrics recorder: (name, tags?, value?) => void */
-    metricsRecorder?: (name: string, tags?: Record<string, string>, value?: number) => void;
-}
-declare class RateLimiter {
-    private store;
-    private policyOrResolver;
-    private trustedProxies;
-    private exemptPrivateIps;
-    private algorithmCache;
-    private otelTracer?;
-    private metricsRecorder?;
-    constructor(options: RateLimiterOptions);
-    /**
-     * Check if request is allowed under rate limit.
-     */
-    /**
-     * Check if request is allowed under rate limit.
-     * This method is async because policy resolution may be async (e.g. DB lookup).
-     */
-    check(request: any, cost?: number): Promise<Decision>;
-    /**
-     * Extract rate limit key from request based on policy strategy.
-     */
-    private extractKey;
-    /**
-     * Check if request is exempt from rate limiting.
-     */
-    private isExempt;
-}
-
-export { type AtomicStore as A, type Decision as D, type EvaluateInput as E, InMemoryStore as I, KeyStrategy as K, type Policy as P, type RedisClientLike as R, type Store as S, Algorithm as a, RateLimiter as b, type RateLimiterOptions as c, isAtomicStore as i, normalizePolicy as n, toHeaders as t };

package/dist/limiter-HCt8ADZ2.d.ts

@@ -1,177 +0,0 @@
-/**
- * Decision model for rate limiting results.
- */
-interface Decision {
-    /** Whether the request is allowed */
-    allowed: boolean;
-    /** Maximum number of requests allowed in the window */
-    limit: number;
-    /** Number of requests remaining in the current window */
-    remaining: number;
-    /** Unix timestamp when the limit resets */
-    resetAt: number;
-    /** Seconds to wait before retrying (only set when blocked) */
-    retryAfter?: number;
-}
-/**
- * Convert decision to standard rate limit headers.
- */
-declare function toHeaders(decision: Decision): Record<string, string>;
-
-/**
- * Policy model for rate limiting configuration.
- */
-declare enum KeyStrategy {
-    IP = "ip",
-    USER = "user",
-    API_KEY = "api_key",
-    COMPOSITE = "composite",
-    CUSTOM = "custom"
-}
-declare enum Algorithm {
-    TOKEN_BUCKET = "token_bucket",
-    FIXED_WINDOW = "fixed_window",
-    SLIDING_WINDOW = "sliding_window",
-    LEAKY_BUCKET = "leaky_bucket"
-}
-interface Policy {
-    /** Human-readable policy name */
-    name: string;
-    /** Maximum number of requests allowed */
-    limit: number;
-    /** Time window in seconds */
-    window: number;
-    /** Rate limiting algorithm to use */
-    algorithm?: Algorithm;
-    /** Strategy for extracting the rate limit key */
-    keyStrategy?: KeyStrategy;
-    /** Maximum burst size (for token bucket) */
-    burst?: number;
-    /** Cost per request (default: 1) */
-    cost?: number;
-    /** Duration to block after limit exceeded (seconds) */
-    blockDuration?: number;
-    /** Custom function to extract key from request */
-    keyExtractor?: (request: any) => string | null;
-    /** List of paths or IPs to exempt from rate limiting */
-    exemptions?: string[];
-}
-/**
- * Validate and normalize policy configuration.
- */
-declare function normalizePolicy(policy: Policy): Required<Policy>;
-
-/**
- * In-memory storage backend for rate limiting.
- */
-interface Store {
-    get(key: string): any;
-    set(key: string, value: any, ttl?: number): void;
-    increment(key: string, delta?: number, ttl?: number): number;
-    delete(key: string): void;
-}
-declare class InMemoryStore implements Store {
-    private data;
-    get(key: string): any;
-    set(key: string, value: any, ttl?: number): void;
-    increment(key: string, delta?: number, ttl?: number): number;
-    delete(key: string): void;
-    private cleanupExpired;
-    /**
-     * Clean up all expired keys.
-     */
-    cleanupAllExpired(): number;
-}
-
-/**
- * Atomic-evaluation protocol.
- *
- * Simple stores (e.g. InMemoryStore) expose get/set and let the limiter run the
- * algorithm in-process. Distributed stores that can compute the decision
- * atomically (e.g. RedisStore via Lua) instead expose `evaluate()`: the limiter
- * hands them the resolved policy params + storage key and gets back a finished
- * Decision. The limiter prefers `evaluate()` when present (see core/limiter.ts).
- */
-
-/** Everything an atomic store needs to compute a decision for one request. */
-interface EvaluateInput {
-    /** Full storage key, already namespaced (e.g. `halt:public_api:1.2.3.4`). */
-    key: string;
-    /** Algorithm to apply. */
-    algorithm: Algorithm;
-    /** Requests permitted per window. */
-    limit: number;
-    /** Window length in seconds. */
-    window: number;
-    /** Bucket capacity (token/leaky bucket). */
-    burst: number;
-    /** Cost this request consumes. */
-    cost: number;
-    /** Seconds to keep the key alive in the backing store. */
-    ttl: number;
-}
-/** A store that computes the rate-limit decision atomically on its own. */
-interface AtomicStore {
-    evaluate(input: EvaluateInput): Promise<Decision>;
-}
-/** True if the store implements the atomic-evaluation protocol. */
-declare function isAtomicStore(store: unknown): store is AtomicStore;
-/**
- * Minimal structural type for a Redis client (satisfied by ioredis and
- * node-redis v4+). Declared here so Halt has no hard dependency on any concrete
- * Redis package — the user injects their own client.
- */
-interface RedisClientLike {
-    eval(script: string, numKeys: number, ...args: (string | number)[]): Promise<unknown>;
-    evalsha?(sha: string, numKeys: number, ...args: (string | number)[]): Promise<unknown>;
-    script?(subcommand: 'LOAD', script: string): Promise<unknown>;
-}
-
-/**
- * Main rate limiter implementation.
- */
-
-interface RateLimiterOptions {
-    /**
-     * Storage backend. Either a simple KV store (InMemoryStore — the limiter runs
-     * the algorithm in-process) or an atomic store (RedisStore — the store
-     * computes the decision atomically via Lua).
-     */
-    store: Store | AtomicStore;
-    /** Either a static policy or a resolver returning a policy per-request */
-    policy: Policy | ((request: any) => Policy | Promise<Policy>);
-    trustedProxies?: string[];
-    exemptPrivateIps?: boolean;
-    /** Optional OpenTelemetry-like tracer (object with startSpan) */
-    otelTracer?: any;
-    /** Optional metrics recorder: (name, tags?, value?) => void */
-    metricsRecorder?: (name: string, tags?: Record<string, string>, value?: number) => void;
-}
-declare class RateLimiter {
-    private store;
-    private policyOrResolver;
-    private trustedProxies;
-    private exemptPrivateIps;
-    private algorithmCache;
-    private otelTracer?;
-    private metricsRecorder?;
-    constructor(options: RateLimiterOptions);
-    /**
-     * Check if request is allowed under rate limit.
-     */
-    /**
-     * Check if request is allowed under rate limit.
-     * This method is async because policy resolution may be async (e.g. DB lookup).
-     */
-    check(request: any, cost?: number): Promise<Decision>;
-    /**
-     * Extract rate limit key from request based on policy strategy.
-     */
-    private extractKey;
-    /**
-     * Check if request is exempt from rate limiting.
-     */
-    private isExempt;
-}
-
-export { type AtomicStore as A, type Decision as D, type EvaluateInput as E, InMemoryStore as I, KeyStrategy as K, type Policy as P, type RedisClientLike as R, type Store as S, Algorithm as a, RateLimiter as b, type RateLimiterOptions as c, isAtomicStore as i, normalizePolicy as n, toHeaders as t };