@ttt-productions/rate-limit-core 0.6.0 → 0.8.0

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 export { createRedisClientFactory } from "./redis-client.js";
 export type { RedisCredentialsProvider, RedisClientFactoryOptions, } from "./redis-client.js";
 export { createRateLimiterFactory } from "./rate-limiter.js";
-export type { RateLimitConfig, RateLimiterFactoryOptions, } from "./rate-limiter.js";
+export type { RateLimitConfig, RateLimiterFactoryOptions, RateLimiterDegradation, } from "./rate-limiter.js";
 export { getRateLimitErrorMessage } from "./error-message.js";
 export type { RateLimitErrorMessageOptions } from "./error-message.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wBAAwB,EAAE,MAAM,mBAAmB,CAAC;AAC7D,YAAY,EACV,wBAAwB,EACxB,yBAAyB,GAC1B,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,wBAAwB,EAAE,MAAM,mBAAmB,CAAC;AAC7D,YAAY,EACV,eAAe,EACf,yBAAyB,GAC1B,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAC;AAC9D,YAAY,EAAE,4BAA4B,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wBAAwB,EAAE,MAAM,mBAAmB,CAAC;AAC7D,YAAY,EACV,wBAAwB,EACxB,yBAAyB,GAC1B,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,wBAAwB,EAAE,MAAM,mBAAmB,CAAC;AAC7D,YAAY,EACV,eAAe,EACf,yBAAyB,EACzB,sBAAsB,GACvB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAC;AAC9D,YAAY,EAAE,4BAA4B,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wBAAwB,EAAE,MAAM,mBAAmB,CAAC;AAM7D,OAAO,EAAE,wBAAwB,EAAE,MAAM,mBAAmB,CAAC;AAM7D,OAAO,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wBAAwB,EAAE,MAAM,mBAAmB,CAAC;AAM7D,OAAO,EAAE,wBAAwB,EAAE,MAAM,mBAAmB,CAAC;AAO7D,OAAO,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/rate-limiter.d.ts

@@ -8,11 +8,39 @@ export interface RateLimitConfig {
     /** Window duration (e.g. "1 h", "10 m", "1 d"). */
     window: string;
 }
+/**
+ * Structured report of a rate-limiter degradation. Passed to the injected
+ * `onDegraded` hook so the consuming app can decide the alerting posture
+ * (e.g. Sentry `captureMessage` in prod, a warn line in the emulator) WITHOUT
+ * this generic package importing a monitoring provider directly.
+ *
+ * - `reason: 'unavailable'` — a limiter could not be built (Redis is null:
+ *   missing credentials or the disable hook). Fired at most once per factory
+ *   instance, on the FIRST `checkRateLimit` call, so an unconfigured prod deploy
+ *   pages within minutes of traffic instead of silently allowing everything.
+ * - `reason: 'limit-error'` — `limiter.limit()` rejected at runtime (e.g. an
+ *   Upstash outage). The call fails OPEN (`allowed: true`) after reporting.
+ */
+export interface RateLimiterDegradation {
+    reason: 'unavailable' | 'limit-error';
+    /** The limiter prefix in play, when known. */
+    prefix?: string;
+    /** The underlying error for `reason: 'limit-error'`. */
+    error?: unknown;
+}
 export interface RateLimiterFactoryOptions {
     /** Returns the Redis client or null when disabled. */
     getRedis: () => Redis | null;
     /** When true, includes Upstash analytics. Default true. */
     analytics?: boolean;
+    /**
+     * Optional degradation hook. The consuming app injects its own alerting
+     * (Sentry capture in prod, warn in local/emulator) — this package stays
+     * provider-agnostic. `unavailable` fires at most once per factory instance;
+     * `limit-error` fires per failed `limit()` call. The hook must never throw
+     * (it is invoked inside the fail-open path).
+     */
+    onDegraded?: (info: RateLimiterDegradation) => void;
 }
 /**
  * Create a memoized Ratelimit factory. Limiters are cached by their `prefix`

package/dist/rate-limiter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rate-limiter.d.ts","sourceRoot":"","sources":["../src/rate-limiter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC/C,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAE5C,MAAM,WAAW,eAAe;IAC9B,gEAAgE;IAChE,MAAM,EAAE,MAAM,CAAC;IACf,0CAA0C;IAC1C,WAAW,EAAE,MAAM,CAAC;IACpB,mDAAmD;IACnD,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,yBAAyB;IACxC,sDAAsD;IACtD,QAAQ,EAAE,MAAM,KAAK,GAAG,IAAI,CAAC;IAC7B,2DAA2D;IAC3D,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,yBAAyB;6BAIzC,eAAe,KAAG,SAAS,GAAG,IAAI;0BAsB3D,MAAM,UACH,eAAe,KACtB,OAAO,CAAC;QAAE,OAAO,EAAE,IAAI,CAAA;KAAE,GAAG;QAAE,OAAO,EAAE,KAAK,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;EASlE"}
+{"version":3,"file":"rate-limiter.d.ts","sourceRoot":"","sources":["../src/rate-limiter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC/C,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAE5C,MAAM,WAAW,eAAe;IAC9B,gEAAgE;IAChE,MAAM,EAAE,MAAM,CAAC;IACf,0CAA0C;IAC1C,WAAW,EAAE,MAAM,CAAC;IACpB,mDAAmD;IACnD,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,aAAa,GAAG,aAAa,CAAC;IACtC,8CAA8C;IAC9C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wDAAwD;IACxD,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,yBAAyB;IACxC,sDAAsD;IACtD,QAAQ,EAAE,MAAM,KAAK,GAAG,IAAI,CAAC;IAC7B,2DAA2D;IAC3D,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,sBAAsB,KAAK,IAAI,CAAC;CACrD;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,yBAAyB;6BAczC,eAAe,KAAG,SAAS,GAAG,IAAI;0BA6B3D,MAAM,UACH,eAAe,KACtB,OAAO,CAAC;QAAE,OAAO,EAAE,IAAI,CAAA;KAAE,GAAG;QAAE,OAAO,EAAE,KAAK,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;EAqBlE"}

package/dist/rate-limiter.js

@@ -6,6 +6,16 @@ import { Ratelimit } from "@upstash/ratelimit";
 export function createRateLimiterFactory(options) {
     const limiters = new Map();
     const analytics = options.analytics ?? true;
+    // Fire the `unavailable` degradation at most once per factory instance.
+    let reportedUnavailable = false;
+    function report(info) {
+        try {
+            options.onDegraded?.(info);
+        }
+        catch {
+            // The alerting hook must never break the fail-open path.
+        }
+    }
     function getRateLimiter(config) {
         const redis = options.getRedis();
         if (!redis)
@@ -24,16 +34,35 @@ export function createRateLimiterFactory(options) {
     }
     /**
      * Check rate limit for a key (e.g. userId). Returns `{ allowed: true }`
-     * when Redis is disabled OR the limit isn't exceeded.
+     * when Redis is unavailable OR the limit isn't exceeded.
+     *
+     * FAIL-OPEN POSTURE (decided 2026-07-03): both failure modes degrade to
+     * "allow, but observed" rather than blocking every write. When the limiter is
+     * unavailable (Redis null — missing credentials / disabled), the first call
+     * reports `unavailable` so an unconfigured prod deploy is loud. When a built
+     * limiter's `limit()` rejects (Upstash outage), the error is reported and the
+     * call still allows — an outage must not take down every rate-limited callable.
      */
     async function checkRateLimit(key, config) {
         const limiter = getRateLimiter(config);
-        if (!limiter)
+        if (!limiter) {
+            if (!reportedUnavailable) {
+                reportedUnavailable = true;
+                report({ reason: 'unavailable', prefix: config.prefix });
+            }
+            return { allowed: true };
+        }
+        try {
+            const { success, reset } = await limiter.limit(key);
+            if (!success)
+                return { allowed: false, reset };
+            return { allowed: true };
+        }
+        catch (error) {
+            // Runtime Redis error (e.g. Upstash outage). Fail OPEN, but report.
+            report({ reason: 'limit-error', prefix: config.prefix, error });
             return { allowed: true };
-        const { success, reset } = await limiter.limit(key);
-        if (!success)
-            return { allowed: false, reset };
-        return { allowed: true };
+        }
     }
     return { getRateLimiter, checkRateLimit };
 }

package/dist/rate-limiter.js.map

@@ -1 +1 @@
-{"version":3,"file":"rate-limiter.js","sourceRoot":"","sources":["../src/rate-limiter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAmB/C;;;GAGG;AACH,MAAM,UAAU,wBAAwB,CAAC,OAAkC;IACzE,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAqB,CAAC;IAC9C,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,IAAI,CAAC;IAE5C,SAAS,cAAc,CAAC,MAAuB;QAC7C,MAAM,KAAK,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;QACjC,IAAI,CAAC,KAAK;YAAE,OAAO,IAAI,CAAC;QAExB,MAAM,QAAQ,GAAG,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QAC7C,IAAI,QAAQ;YAAE,OAAO,QAAQ,CAAC;QAE9B,MAAM,OAAO,GAAG,IAAI,SAAS,CAAC;YAC5B,KAAK;YACL,OAAO,EAAE,SAAS,CAAC,aAAa,CAAC,MAAM,CAAC,WAAW,EAAE,MAAM,CAAC,MAAuD,CAAC;YACpH,SAAS;YACT,MAAM,EAAE,MAAM,CAAC,MAAM;SACtB,CAAC,CAAC;QACH,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACrC,OAAO,OAAO,CAAC;IACjB,CAAC;IAED;;;OAGG;IACH,KAAK,UAAU,cAAc,CAC3B,GAAW,EACX,MAAuB;QAEvB,MAAM,OAAO,GAAG,cAAc,CAAC,MAAM,CAAC,CAAC;QACvC,IAAI,CAAC,OAAO;YAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;QACvC,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,GAAG,MAAM,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACpD,IAAI,CAAC,OAAO;YAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;QAC/C,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IAC3B,CAAC;IAED,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,CAAC;AAC5C,CAAC"}
+{"version":3,"file":"rate-limiter.js","sourceRoot":"","sources":["../src/rate-limiter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAgD/C;;;GAGG;AACH,MAAM,UAAU,wBAAwB,CAAC,OAAkC;IACzE,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAqB,CAAC;IAC9C,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,IAAI,CAAC;IAC5C,wEAAwE;IACxE,IAAI,mBAAmB,GAAG,KAAK,CAAC;IAEhC,SAAS,MAAM,CAAC,IAA4B;QAC1C,IAAI,CAAC;YACH,OAAO,CAAC,UAAU,EAAE,CAAC,IAAI,CAAC,CAAC;QAC7B,CAAC;QAAC,MAAM,CAAC;YACP,yDAAyD;QAC3D,CAAC;IACH,CAAC;IAED,SAAS,cAAc,CAAC,MAAuB;QAC7C,MAAM,KAAK,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;QACjC,IAAI,CAAC,KAAK;YAAE,OAAO,IAAI,CAAC;QAExB,MAAM,QAAQ,GAAG,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QAC7C,IAAI,QAAQ;YAAE,OAAO,QAAQ,CAAC;QAE9B,MAAM,OAAO,GAAG,IAAI,SAAS,CAAC;YAC5B,KAAK;YACL,OAAO,EAAE,SAAS,CAAC,aAAa,CAAC,MAAM,CAAC,WAAW,EAAE,MAAM,CAAC,MAAuD,CAAC;YACpH,SAAS;YACT,MAAM,EAAE,MAAM,CAAC,MAAM;SACtB,CAAC,CAAC;QACH,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACrC,OAAO,OAAO,CAAC;IACjB,CAAC;IAED;;;;;;;;;;OAUG;IACH,KAAK,UAAU,cAAc,CAC3B,GAAW,EACX,MAAuB;QAEvB,MAAM,OAAO,GAAG,cAAc,CAAC,MAAM,CAAC,CAAC;QACvC,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,IAAI,CAAC,mBAAmB,EAAE,CAAC;gBACzB,mBAAmB,GAAG,IAAI,CAAC;gBAC3B,MAAM,CAAC,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;YAC3D,CAAC;YACD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;QAC3B,CAAC;QACD,IAAI,CAAC;YACH,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,GAAG,MAAM,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;YACpD,IAAI,CAAC,OAAO;gBAAE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;YAC/C,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;QAC3B,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,oEAAoE;YACpE,MAAM,CAAC,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC;YAChE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;QAC3B,CAAC;IACH,CAAC;IAED,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,CAAC;AAC5C,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@ttt-productions/rate-limit-core",
-    "version": "0.6.0",
+    "version": "0.8.0",
     "repository": {
         "type": "git",
         "url": "git+https://github.com/ttt-productions/ttt-packages.git",