halt-rate 0.3.0 → 0.4.0

package/dist/index.d.mts

@@ -130,6 +130,54 @@ declare namespace extractors {
   export { extractors_HEALTH_CHECK_PATHS as HEALTH_CHECK_PATHS, extractors_extractApiKey as extractApiKey, extractors_extractIp as extractIp, extractors_extractPath as extractPath, extractors_extractUserId as extractUserId, extractors_isHealthCheck as isHealthCheck, extractors_isPrivateIp as isPrivateIp };
 }
 
+/**
+ * Dynamic limits — change policies at runtime without restarting.
+ *
+ * `PolicyRegistry` holds named policies you can mutate live. Use it as the
+ * limiter's `policy` via `registry.resolver(selector)`:
+ *
+ *   const registry = new PolicyRegistry([presets.PUBLIC_API]);
+ *   const limiter = new RateLimiter({
+ *     store,
+ *     policy: registry.resolver((req) => 'public_api'),
+ *   });
+ *   // later, no restart:
+ *   registry.update('public_api', { limit: 500 });
+ *
+ * For limits stored in Redis/DB/config (and shared across a fleet), use
+ * `cachedPolicyResolver` with a loader that reads that shared state.
+ */
+
+declare class PolicyRegistry {
+    private policies;
+    constructor(initial?: Policy[]);
+    /** Add or replace a policy (keyed by `policy.name`). */
+    register(policy: Policy): this;
+    get(name: string): Policy | undefined;
+    has(name: string): boolean;
+    /** Mutate fields of an existing policy at runtime (e.g. `{ limit: 500 }`). */
+    update(name: string, patch: Partial<Omit<Policy, 'name'>>): Policy;
+    remove(name: string): boolean;
+    list(): Policy[];
+    /**
+     * Build a resolver for the limiter's `policy` option.
+     * @param selector maps a request to a registered policy name.
+     */
+    resolver(selector: (request: any) => string): (request: any) => Policy;
+}
+interface CachedPolicyResolverOptions {
+    /** Cache entry lifetime in ms (default 5000). */
+    ttlMs?: number;
+    /** Cache key for a request (default: the loaded policy is shared under one key). */
+    key?: (request: any) => string;
+}
+/**
+ * Wrap a (possibly async) loader with a per-key TTL cache. The loader reads your
+ * source of truth (Redis/DB/config), so limits propagate across a fleet and
+ * refresh live — without restarting. Use the returned function as `policy`.
+ */
+declare function cachedPolicyResolver(loader: (request: any) => Policy | Promise<Policy>, options?: CachedPolicyResolverOptions): (request: any) => Promise<Policy>;
+
 /**
  * In-process statistics collector for rate-limit observability.
  *
@@ -253,4 +301,4 @@ declare class OpenTelemetryMetrics implements TelemetryHooks {
     onViolation(_identifier: string, _penalty: Penalty, severity: number): void;
 }
 
-export { AtomicStore, Decision, EvaluateInput, type FailMode, type OTelCounterLike, type OTelMeterLike, OpenTelemetryMetrics, Penalty, Policy, Quota, RedisClientLike, RedisStore, type RedisStoreOptions, StatsCollector, type StatsCollectorOptions, type StatsSnapshot, TelemetryHooks, extractors, index as presets };
+export { AtomicStore, type CachedPolicyResolverOptions, Decision, EvaluateInput, type FailMode, type OTelCounterLike, type OTelMeterLike, OpenTelemetryMetrics, Penalty, Policy, PolicyRegistry, Quota, RedisClientLike, RedisStore, type RedisStoreOptions, StatsCollector, type StatsCollectorOptions, type StatsSnapshot, TelemetryHooks, cachedPolicyResolver, extractors, index as presets };

package/dist/index.d.ts

@@ -130,6 +130,54 @@ declare namespace extractors {
   export { extractors_HEALTH_CHECK_PATHS as HEALTH_CHECK_PATHS, extractors_extractApiKey as extractApiKey, extractors_extractIp as extractIp, extractors_extractPath as extractPath, extractors_extractUserId as extractUserId, extractors_isHealthCheck as isHealthCheck, extractors_isPrivateIp as isPrivateIp };
 }
 
+/**
+ * Dynamic limits — change policies at runtime without restarting.
+ *
+ * `PolicyRegistry` holds named policies you can mutate live. Use it as the
+ * limiter's `policy` via `registry.resolver(selector)`:
+ *
+ *   const registry = new PolicyRegistry([presets.PUBLIC_API]);
+ *   const limiter = new RateLimiter({
+ *     store,
+ *     policy: registry.resolver((req) => 'public_api'),
+ *   });
+ *   // later, no restart:
+ *   registry.update('public_api', { limit: 500 });
+ *
+ * For limits stored in Redis/DB/config (and shared across a fleet), use
+ * `cachedPolicyResolver` with a loader that reads that shared state.
+ */
+
+declare class PolicyRegistry {
+    private policies;
+    constructor(initial?: Policy[]);
+    /** Add or replace a policy (keyed by `policy.name`). */
+    register(policy: Policy): this;
+    get(name: string): Policy | undefined;
+    has(name: string): boolean;
+    /** Mutate fields of an existing policy at runtime (e.g. `{ limit: 500 }`). */
+    update(name: string, patch: Partial<Omit<Policy, 'name'>>): Policy;
+    remove(name: string): boolean;
+    list(): Policy[];
+    /**
+     * Build a resolver for the limiter's `policy` option.
+     * @param selector maps a request to a registered policy name.
+     */
+    resolver(selector: (request: any) => string): (request: any) => Policy;
+}
+interface CachedPolicyResolverOptions {
+    /** Cache entry lifetime in ms (default 5000). */
+    ttlMs?: number;
+    /** Cache key for a request (default: the loaded policy is shared under one key). */
+    key?: (request: any) => string;
+}
+/**
+ * Wrap a (possibly async) loader with a per-key TTL cache. The loader reads your
+ * source of truth (Redis/DB/config), so limits propagate across a fleet and
+ * refresh live — without restarting. Use the returned function as `policy`.
+ */
+declare function cachedPolicyResolver(loader: (request: any) => Policy | Promise<Policy>, options?: CachedPolicyResolverOptions): (request: any) => Promise<Policy>;
+
 /**
  * In-process statistics collector for rate-limit observability.
  *
@@ -253,4 +301,4 @@ declare class OpenTelemetryMetrics implements TelemetryHooks {
     onViolation(_identifier: string, _penalty: Penalty, severity: number): void;
 }
 
-export { AtomicStore, Decision, EvaluateInput, type FailMode, type OTelCounterLike, type OTelMeterLike, OpenTelemetryMetrics, Penalty, Policy, Quota, RedisClientLike, RedisStore, type RedisStoreOptions, StatsCollector, type StatsCollectorOptions, type StatsSnapshot, TelemetryHooks, extractors, index as presets };
+export { AtomicStore, type CachedPolicyResolverOptions, Decision, EvaluateInput, type FailMode, type OTelCounterLike, type OTelMeterLike, OpenTelemetryMetrics, Penalty, Policy, PolicyRegistry, Quota, RedisClientLike, RedisStore, type RedisStoreOptions, StatsCollector, type StatsCollectorOptions, type StatsSnapshot, TelemetryHooks, cachedPolicyResolver, extractors, index as presets };

package/dist/index.js

@@ -486,7 +486,8 @@ var RateLimiter = class {
       return decision2;
     }
     const store = this.store;
-    let algorithm = this.algorithmCache.get(policy.name);
+    const cacheKey = `${policy.name}|${policy.algorithm}|${policy.limit}|${policy.window}|${policy.burst}`;
+    let algorithm = this.algorithmCache.get(cacheKey);
     if (!algorithm) {
       if (policy.algorithm === "token_bucket" /* TOKEN_BUCKET */) {
         algorithm = new TokenBucket(policy.burst, policy.limit, policy.window);
@@ -500,7 +501,7 @@ var RateLimiter = class {
       } else {
         throw new Error(`Algorithm ${policy.algorithm} not implemented`);
       }
-      this.algorithmCache.set(policy.name, algorithm);
+      this.algorithmCache.set(cacheKey, algorithm);
     }
     const span = this.otelTracer?.startSpan?.("halt.check", { attributes: { policy: policy.name, key } });
     const state = store.get(storageKey);
@@ -1095,6 +1096,70 @@ function getPlanPolicy(planName) {
   return PLAN_TIERS[normalized];
 }
 
+// src/core/registry.ts
+var PolicyRegistry = class {
+  constructor(initial = []) {
+    this.policies = /* @__PURE__ */ new Map();
+    for (const p of initial) this.register(p);
+  }
+  /** Add or replace a policy (keyed by `policy.name`). */
+  register(policy) {
+    this.policies.set(policy.name, policy);
+    return this;
+  }
+  get(name) {
+    return this.policies.get(name);
+  }
+  has(name) {
+    return this.policies.has(name);
+  }
+  /** Mutate fields of an existing policy at runtime (e.g. `{ limit: 500 }`). */
+  update(name, patch) {
+    const existing = this.policies.get(name);
+    if (!existing) throw new Error(`Unknown policy: ${name}`);
+    const updated = { ...existing, ...patch, name: existing.name };
+    if (patch.limit !== void 0 && patch.burst === void 0) {
+      delete updated.burst;
+    }
+    this.policies.set(name, updated);
+    return updated;
+  }
+  remove(name) {
+    return this.policies.delete(name);
+  }
+  list() {
+    return [...this.policies.values()];
+  }
+  /**
+   * Build a resolver for the limiter's `policy` option.
+   * @param selector maps a request to a registered policy name.
+   */
+  resolver(selector) {
+    return (request) => {
+      const name = selector(request);
+      const policy = this.policies.get(name);
+      if (!policy) throw new Error(`Unknown policy: ${name}`);
+      return policy;
+    };
+  }
+};
+function cachedPolicyResolver(loader, options = {}) {
+  const ttlMs = options.ttlMs ?? 5e3;
+  const keyFn = options.key ?? (() => "__default__");
+  const cache = /* @__PURE__ */ new Map();
+  return async (request) => {
+    const key = keyFn(request);
+    const now = Date.now();
+    const hit = cache.get(key);
+    if (hit && hit.expires > now) {
+      return hit.policy;
+    }
+    const policy = await loader(request);
+    cache.set(key, { policy, expires: now + ttlMs });
+    return policy;
+  };
+}
+
 // src/core/quota.ts
 var QuotaPeriod = /* @__PURE__ */ ((QuotaPeriod2) => {
   QuotaPeriod2["HOURLY"] = "hourly";
@@ -1624,6 +1689,7 @@ exports.PENALTY_LENIENT = PENALTY_LENIENT;
 exports.PENALTY_MODERATE = PENALTY_MODERATE;
 exports.PENALTY_STRICT = PENALTY_STRICT;
 exports.PenaltyManager = PenaltyManager;
+exports.PolicyRegistry = PolicyRegistry;
 exports.QUOTA_ENTERPRISE_MONTHLY = QUOTA_ENTERPRISE_MONTHLY;
 exports.QUOTA_FREE_DAILY = QUOTA_FREE_DAILY;
 exports.QUOTA_FREE_MONTHLY = QUOTA_FREE_MONTHLY;
@@ -1634,6 +1700,7 @@ exports.QuotaPeriod = QuotaPeriod;
 exports.RateLimiter = RateLimiter;
 exports.RedisStore = RedisStore;
 exports.StatsCollector = StatsCollector;
+exports.cachedPolicyResolver = cachedPolicyResolver;
 exports.extractors = extractors_exports;
 exports.isAtomicStore = isAtomicStore;
 exports.normalizePolicy = normalizePolicy;