@bitbaum/limitkit 0.0.0-stage → 0.2.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Mao Nakamoto
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,105 @@
1
- # Temporary Holding Version
1
+ # @bitbaum/limitkit
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Rate limiting as a **decision**, not a middleware.
4
+
5
+ ```bash
6
+ pnpm add @bitbaum/limitkit
7
+ ```
8
+
9
+ ## Why this exists
10
+
11
+ Twelve near-identical rate limiters were found across nine repos of one fleet —
12
+ orangecat alone carried four, and its ADR to unify them sat **"Proposed" for
13
+ seven months** while the count doubled. What actually varied between the twelve
14
+ was one thing: *where the counts live*. Everything else — the window
15
+ arithmetic, the refusal shape, the headers, the client-IP dance — was the same
16
+ idea written twelve slightly different ways, with independently re-invented
17
+ bugs (one kept an unbounded `Map` keyed by stranger IPs: a slow memory leak
18
+ fed by the public internet).
19
+
20
+ So the algorithm is fixed and the store is the seam.
21
+
22
+ ## Use
23
+
24
+ ```ts
25
+ import { slidingWindow, clientIp, toHeaders } from '@bitbaum/limitkit';
26
+
27
+ const loginLimiter = slidingWindow({ limit: 5, windowMs: 15 * 60_000 });
28
+
29
+ export async function POST(req: Request) {
30
+ const result = loginLimiter.check(`login:${clientIp(req.headers)}`);
31
+ if (!result.allowed) {
32
+ return Response.json(
33
+ { error: 'Too many attempts' },
34
+ { status: 429, headers: toHeaders(result) },
35
+ );
36
+ }
37
+ // ... the actual work, with toHeaders(result) on the success path too if you like
38
+ }
39
+ ```
40
+
41
+ - **`slidingWindow(rule, store?)`** — N hits per *trailing* window. The default;
42
+ it is what most hand-rolled "fixed" windows actually meant.
43
+ - **`fixedWindow(rule, store?)`** — N hits per aligned bucket. Cheaper, burstier
44
+ at the boundary (up to 2N around a roll). Choose it by name, not by accident.
45
+ - **`check`** counts the hit when allowed and **counts nothing when refused** —
46
+ a hammered key recovers the moment the attacker stops, instead of locking the
47
+ legitimate user behind the same NAT out forever.
48
+ - The refusal's `retryAfterSeconds` is **derived from the actual oldest hit**,
49
+ never fabricated. "Try again shortly" on a window that opens in an hour is a
50
+ lie; this package refuses to tell it.
51
+
52
+ ## The store seam
53
+
54
+ ```ts
55
+ interface Store {
56
+ get(key: string): { hits: number[] } | undefined;
57
+ set(key: string, state: { hits: number[] }): void;
58
+ }
59
+ ```
60
+
61
+ The default `MemoryStore` is **bounded** (LRU past `maxKeys`, default 5 000) —
62
+ the unbounded-Map leak is impossible by construction. It is per-process:
63
+ behind N workers the effective limit multiplies by N, which is fine for
64
+ blunting scripted abuse and wrong for billing enforcement. For shared state,
65
+ implement those two methods over Redis/Postgres — an adapter is a dozen lines,
66
+ because the store holds and the algorithm decides.
67
+
68
+ ## HTTP edges
69
+
70
+ - **`toHeaders(result)`** — `X-RateLimit-Limit` / `-Remaining` / `-Reset`, plus
71
+ `Retry-After` on refusals only. A plain object you spread into your own
72
+ response; constructing a `Response` would mean choosing your framework for
73
+ you.
74
+ - **`clientIp(headers, { trustedProxies = 1 })`** — the forwarded hop your own
75
+ proxy wrote, then `x-real-ip`, then `"unknown"`. A proxy **appends** to
76
+ `X-Forwarded-For`, so the header reads `<what the client sent>, <what the
77
+ proxy saw>` and only the **last** entry is unforgeable. Reading the first
78
+ one — which this did before v0.2.0 — lets a caller vary the header per
79
+ request, mint a fresh bucket each time and never trip the limit at all.
80
+ Set `trustedProxies: 2` when a CDN sits in front of your proxy, or `0` when
81
+ the server is exposed directly and no forwarded header can be believed.
82
+ - **No HTTP client, no middleware, no framework types** — the package supplies
83
+ the decision; your app keeps its conventions.
84
+ - **No limit values** — how many attempts a login route allows is app
85
+ semantics. Centralize the rule; assert the numbers locally.
86
+ - **No distributed store** — that is *your* Redis and *your* ops posture. The
87
+ seam is two methods.
88
+
89
+ Everything takes `now` as an argument, so all of it is testable without
90
+ sleeping — which is why this package has tests and the twelve files it
91
+ replaces, collectively, had almost none.
92
+
93
+ ## Development
94
+
95
+ ```bash
96
+ pnpm run verify # lint + typecheck + build + test (tests import by package name)
97
+ ```
98
+
99
+ MIT.
100
+
101
+ ---
102
+
103
+ Part of **[bitbaum](https://bitbaum.orangecat.ch)** — AI-native products on open
104
+ infrastructure, built in Zürich. Every package here lists the apps that use it:
105
+ **[which apps use limitkit](https://bitbaum.orangecat.ch/packages/#limitkit)**.
package/dist/http.d.ts ADDED
@@ -0,0 +1,59 @@
1
+ /**
2
+ * The HTTP-facing edges — headers out, client identity in — shared because
3
+ * they were the two things every replaced implementation ALSO wrote, each
4
+ * slightly differently.
5
+ *
6
+ * No framework types. Both helpers speak the WHATWG `Headers` `get` shape,
7
+ * which Next/Remix/undici requests all satisfy, so the package needs no
8
+ * dependency and no per-framework adapter.
9
+ */
10
+ import type { LimitResult } from "./limit.js";
11
+ /**
12
+ * The standard rate-limit response headers, as orangecat's ADR-0002 specified
13
+ * seven months before anything enforced it: X-RateLimit-Limit, -Remaining,
14
+ * -Reset (epoch seconds), plus Retry-After on refusals only.
15
+ *
16
+ * Returned as a plain object so the caller spreads it into whatever response
17
+ * type it owns — a package that constructed a `Response` would be choosing a
18
+ * framework, and choosing a framework is how a shared package stops being
19
+ * adoptable.
20
+ */
21
+ export declare function toHeaders(result: LimitResult): Record<string, string>;
22
+ /** The `get` half of WHATWG Headers — what every framework request exposes. */
23
+ export type HeadersLike = {
24
+ get(name: string): string | null;
25
+ };
26
+ /**
27
+ * Best-effort client identity for keying a limiter.
28
+ *
29
+ * WHICH HOP, AND WHY IT IS NOT THE FIRST ONE
30
+ *
31
+ * `X-Forwarded-For` is a LIST, and a reverse proxy APPENDS to it. Caddy and
32
+ * nginx both do. So for a request that arrived through one proxy the header
33
+ * reads `<whatever the client sent>, <what the proxy actually saw>` — and the
34
+ * only entry the client could not forge is the LAST one.
35
+ *
36
+ * This function used to return the first, with a comment asserting that was
37
+ * "what the proxy saw", and a test pinning it. Both were wrong in the same
38
+ * direction. The effect was that every limiter keyed on this — across every
39
+ * adopter — could be bypassed completely by sending a random
40
+ * `X-Forwarded-For` with each request: a new header value is a new bucket, so
41
+ * no bucket ever fills. A limiter that cannot be tripped is not a limiter.
42
+ * Found in orangecat's payments audit (bitbaum/orangecat#563, finding 2).
43
+ *
44
+ * `trustedProxies` is how many proxies of your own sit in front. Default 1 —
45
+ * one reverse proxy is the overwhelmingly common shape and the only one where
46
+ * a default can be safe. Two proxies (a CDN in front of your own) means 2, and
47
+ * the answer moves one further left.
48
+ *
49
+ * `trustedProxies: 0` means the server is exposed directly, so EVERY forwarded
50
+ * header is written by the client and none can be believed: the result is
51
+ * "unknown" rather than a number that looks like evidence.
52
+ *
53
+ * Falls back to "unknown" rather than throwing: a limiter keyed on "unknown"
54
+ * throttles the anonymous bucket collectively, which is the right failure mode
55
+ * for the abuse this exists to blunt.
56
+ */
57
+ export declare function clientIp(headers: HeadersLike, opts?: {
58
+ trustedProxies?: number;
59
+ }): string;
package/dist/http.js ADDED
@@ -0,0 +1,77 @@
1
+ /**
2
+ * The HTTP-facing edges — headers out, client identity in — shared because
3
+ * they were the two things every replaced implementation ALSO wrote, each
4
+ * slightly differently.
5
+ *
6
+ * No framework types. Both helpers speak the WHATWG `Headers` `get` shape,
7
+ * which Next/Remix/undici requests all satisfy, so the package needs no
8
+ * dependency and no per-framework adapter.
9
+ */
10
+ /**
11
+ * The standard rate-limit response headers, as orangecat's ADR-0002 specified
12
+ * seven months before anything enforced it: X-RateLimit-Limit, -Remaining,
13
+ * -Reset (epoch seconds), plus Retry-After on refusals only.
14
+ *
15
+ * Returned as a plain object so the caller spreads it into whatever response
16
+ * type it owns — a package that constructed a `Response` would be choosing a
17
+ * framework, and choosing a framework is how a shared package stops being
18
+ * adoptable.
19
+ */
20
+ export function toHeaders(result) {
21
+ const headers = {
22
+ "X-RateLimit-Limit": String(result.limit),
23
+ "X-RateLimit-Remaining": String(result.remaining),
24
+ "X-RateLimit-Reset": String(Math.ceil(result.resetAt / 1000)),
25
+ };
26
+ if (!result.allowed) {
27
+ headers["Retry-After"] = String(result.retryAfterSeconds);
28
+ }
29
+ return headers;
30
+ }
31
+ /**
32
+ * Best-effort client identity for keying a limiter.
33
+ *
34
+ * WHICH HOP, AND WHY IT IS NOT THE FIRST ONE
35
+ *
36
+ * `X-Forwarded-For` is a LIST, and a reverse proxy APPENDS to it. Caddy and
37
+ * nginx both do. So for a request that arrived through one proxy the header
38
+ * reads `<whatever the client sent>, <what the proxy actually saw>` — and the
39
+ * only entry the client could not forge is the LAST one.
40
+ *
41
+ * This function used to return the first, with a comment asserting that was
42
+ * "what the proxy saw", and a test pinning it. Both were wrong in the same
43
+ * direction. The effect was that every limiter keyed on this — across every
44
+ * adopter — could be bypassed completely by sending a random
45
+ * `X-Forwarded-For` with each request: a new header value is a new bucket, so
46
+ * no bucket ever fills. A limiter that cannot be tripped is not a limiter.
47
+ * Found in orangecat's payments audit (bitbaum/orangecat#563, finding 2).
48
+ *
49
+ * `trustedProxies` is how many proxies of your own sit in front. Default 1 —
50
+ * one reverse proxy is the overwhelmingly common shape and the only one where
51
+ * a default can be safe. Two proxies (a CDN in front of your own) means 2, and
52
+ * the answer moves one further left.
53
+ *
54
+ * `trustedProxies: 0` means the server is exposed directly, so EVERY forwarded
55
+ * header is written by the client and none can be believed: the result is
56
+ * "unknown" rather than a number that looks like evidence.
57
+ *
58
+ * Falls back to "unknown" rather than throwing: a limiter keyed on "unknown"
59
+ * throttles the anonymous bucket collectively, which is the right failure mode
60
+ * for the abuse this exists to blunt.
61
+ */
62
+ export function clientIp(headers, opts = {}) {
63
+ const trusted = opts.trustedProxies ?? 1;
64
+ if (trusted > 0) {
65
+ const hops = (headers.get("x-forwarded-for") ?? "")
66
+ .split(",")
67
+ .map((hop) => hop.trim())
68
+ .filter(Boolean);
69
+ // Count from the RIGHT: the rightmost hop was written by the proxy nearest
70
+ // us. Clamped, because a shorter chain than configured means fewer proxies
71
+ // ran than expected — the leftmost is then the only candidate we have, and
72
+ // it is still the one our own proxy wrote.
73
+ if (hops.length > 0)
74
+ return hops[Math.max(0, hops.length - trusted)];
75
+ }
76
+ return headers.get("x-real-ip")?.trim() || "unknown";
77
+ }
@@ -0,0 +1,23 @@
1
+ /**
2
+ * limitkit — rate limiting as a DECISION, not a middleware.
3
+ *
4
+ * Extracted 2026-08-20 from twelve near-identical implementations across nine
5
+ * repos (orangecat alone carried four, and its ADR to unify them sat
6
+ * "Proposed" for seven months while the count doubled). What actually varied
7
+ * was one thing — where the counts live — so that is the one injectable seam:
8
+ *
9
+ * slidingWindow / fixedWindow — the algorithms, pure over store + clock
10
+ * Store / MemoryStore — the seam, with a BOUNDED default (one of
11
+ * the replaced implementations leaked memory
12
+ * via an unbounded Map keyed by stranger IPs)
13
+ * toHeaders / clientIp — the HTTP edges everyone also rewrote
14
+ *
15
+ * Deliberately NOT included, per the fleet's extraction rules: no HTTP client,
16
+ * no framework middleware, no Response construction. The package supplies the
17
+ * decision; the app keeps its own conventions. And no LIMITS — how many
18
+ * requests a login route allows is app semantics, asserted locally, exactly
19
+ * like which model id is a paid one (see ai-ration's modelCost).
20
+ */
21
+ export { type LimitRule, type LimitResult, type Limiter, slidingWindow, fixedWindow, } from "./limit.js";
22
+ export { type Store, type WindowState, MemoryStore } from "./store.js";
23
+ export { type HeadersLike, toHeaders, clientIp } from "./http.js";
package/dist/index.js ADDED
@@ -0,0 +1,23 @@
1
+ /**
2
+ * limitkit — rate limiting as a DECISION, not a middleware.
3
+ *
4
+ * Extracted 2026-08-20 from twelve near-identical implementations across nine
5
+ * repos (orangecat alone carried four, and its ADR to unify them sat
6
+ * "Proposed" for seven months while the count doubled). What actually varied
7
+ * was one thing — where the counts live — so that is the one injectable seam:
8
+ *
9
+ * slidingWindow / fixedWindow — the algorithms, pure over store + clock
10
+ * Store / MemoryStore — the seam, with a BOUNDED default (one of
11
+ * the replaced implementations leaked memory
12
+ * via an unbounded Map keyed by stranger IPs)
13
+ * toHeaders / clientIp — the HTTP edges everyone also rewrote
14
+ *
15
+ * Deliberately NOT included, per the fleet's extraction rules: no HTTP client,
16
+ * no framework middleware, no Response construction. The package supplies the
17
+ * decision; the app keeps its own conventions. And no LIMITS — how many
18
+ * requests a login route allows is app semantics, asserted locally, exactly
19
+ * like which model id is a paid one (see ai-ration's modelCost).
20
+ */
21
+ export { slidingWindow, fixedWindow, } from "./limit.js";
22
+ export { MemoryStore } from "./store.js";
23
+ export { toHeaders, clientIp } from "./http.js";
@@ -0,0 +1,78 @@
1
+ /**
2
+ * The decision: may this key take another hit right now?
3
+ *
4
+ * Pure over its inputs — the store and the clock are arguments — for the same
5
+ * reason ai-ration's fair-share is: the behaviour worth testing ("a full
6
+ * window refuses with an honest retry time") must be provable without a
7
+ * server, a database, or a real minute passing. Every replaced implementation
8
+ * baked `Date.now()` in, so none of them could test the one thing they were
9
+ * for without sleeping through it.
10
+ *
11
+ * Two window shapes, because the fleet genuinely used both and they refuse
12
+ * differently:
13
+ *
14
+ * FIXED — N hits per aligned window; the whole allowance reappears when
15
+ * the window rolls. Cheaper (one counter), burstier at the edge:
16
+ * 2N hits can land in moments around a boundary.
17
+ * SLIDING — N hits per trailing window, measured from each hit. Smoother,
18
+ * costs the timestamps. This is what most of the fleet meant even
19
+ * when it implemented fixed.
20
+ *
21
+ * The refusal carries `retryAfterSeconds` computed from the actual state —
22
+ * when the OLDEST counted hit ages out — not a guess. "Try again shortly" on
23
+ * a window that will not open for an hour is the same lie the 429 classifier
24
+ * in ai-ration exists to prevent, one layer down.
25
+ */
26
+ import type { Store } from "./store.js";
27
+ export type LimitRule = {
28
+ /** Max hits inside the window. */
29
+ limit: number;
30
+ /** Window length in milliseconds. */
31
+ windowMs: number;
32
+ };
33
+ export type LimitResult = {
34
+ allowed: boolean;
35
+ /** The rule's ceiling, echoed for headers. */
36
+ limit: number;
37
+ /** Hits still available in this window (0 when refused). */
38
+ remaining: number;
39
+ /** Epoch ms when the window opens again (when the next hit would be allowed). */
40
+ resetAt: number;
41
+ /** Whole seconds until then; 0 when allowed. Never fabricated — derived
42
+ * from the oldest counted hit. */
43
+ retryAfterSeconds: number;
44
+ };
45
+ /**
46
+ * A limiter bound to one rule and one store.
47
+ *
48
+ * `check` counts the hit when allowed and counts NOTHING when refused: a
49
+ * refused request must not extend its own punishment, or a steady attacker
50
+ * locks a key shut forever and the legitimate user behind the same NAT never
51
+ * gets back in.
52
+ */
53
+ export type Limiter = {
54
+ check(key: string, now?: number): LimitResult;
55
+ /** Read-only view: what would happen, counting nothing either way. */
56
+ peek(key: string, now?: number): LimitResult;
57
+ };
58
+ /**
59
+ * Sliding window: N hits per trailing `windowMs`, measured from each hit.
60
+ *
61
+ * The default, because it is what nearly every replaced implementation was
62
+ * reaching for: "no more than N in any M minutes", not "N per wall-clock
63
+ * bucket".
64
+ */
65
+ export declare function slidingWindow(rule: LimitRule, store?: Store): Limiter;
66
+ /**
67
+ * Fixed window: N hits per aligned `windowMs` bucket.
68
+ *
69
+ * Kept because three of the replaced implementations chose it deliberately
70
+ * for cheapness, and because its edge-burst behaviour (up to 2N around a
71
+ * boundary) is sometimes fine and sometimes the whole objection — the choice
72
+ * should be named at the call site, not implied by whichever file got copied.
73
+ *
74
+ * Implemented on the same store contract: the bucket is represented as one
75
+ * synthetic hit timestamp (the bucket start) repeated per hit, so a remote
76
+ * Store needs no second schema.
77
+ */
78
+ export declare function fixedWindow(rule: LimitRule, store?: Store): Limiter;
package/dist/limit.js ADDED
@@ -0,0 +1,112 @@
1
+ /**
2
+ * The decision: may this key take another hit right now?
3
+ *
4
+ * Pure over its inputs — the store and the clock are arguments — for the same
5
+ * reason ai-ration's fair-share is: the behaviour worth testing ("a full
6
+ * window refuses with an honest retry time") must be provable without a
7
+ * server, a database, or a real minute passing. Every replaced implementation
8
+ * baked `Date.now()` in, so none of them could test the one thing they were
9
+ * for without sleeping through it.
10
+ *
11
+ * Two window shapes, because the fleet genuinely used both and they refuse
12
+ * differently:
13
+ *
14
+ * FIXED — N hits per aligned window; the whole allowance reappears when
15
+ * the window rolls. Cheaper (one counter), burstier at the edge:
16
+ * 2N hits can land in moments around a boundary.
17
+ * SLIDING — N hits per trailing window, measured from each hit. Smoother,
18
+ * costs the timestamps. This is what most of the fleet meant even
19
+ * when it implemented fixed.
20
+ *
21
+ * The refusal carries `retryAfterSeconds` computed from the actual state —
22
+ * when the OLDEST counted hit ages out — not a guess. "Try again shortly" on
23
+ * a window that will not open for an hour is the same lie the 429 classifier
24
+ * in ai-ration exists to prevent, one layer down.
25
+ */
26
+ import { MemoryStore } from "./store.js";
27
+ function decide(rule, hits, now) {
28
+ const live = hits.filter((t) => t > now - rule.windowMs);
29
+ const allowed = live.length < rule.limit;
30
+ const oldest = live[0];
31
+ const resetAt = live.length === 0 ? now : (oldest ?? now) + rule.windowMs;
32
+ return {
33
+ allowed,
34
+ result: {
35
+ allowed,
36
+ limit: rule.limit,
37
+ remaining: Math.max(0, rule.limit - live.length - (allowed ? 1 : 0)),
38
+ resetAt,
39
+ retryAfterSeconds: allowed ? 0 : Math.max(1, Math.ceil((resetAt - now) / 1000)),
40
+ },
41
+ };
42
+ }
43
+ /**
44
+ * Sliding window: N hits per trailing `windowMs`, measured from each hit.
45
+ *
46
+ * The default, because it is what nearly every replaced implementation was
47
+ * reaching for: "no more than N in any M minutes", not "N per wall-clock
48
+ * bucket".
49
+ */
50
+ export function slidingWindow(rule, store = new MemoryStore()) {
51
+ return {
52
+ check(key, now = Date.now()) {
53
+ const state = store.get(key) ?? { hits: [] };
54
+ const live = state.hits.filter((t) => t > now - rule.windowMs);
55
+ const { allowed, result } = decide(rule, live, now);
56
+ // Counted only when allowed; a refusal writes back only the prune, so a
57
+ // hammered key still recovers the moment the attacker stops.
58
+ store.set(key, { hits: allowed ? [...live, now] : live });
59
+ return result;
60
+ },
61
+ peek(key, now = Date.now()) {
62
+ const state = store.get(key) ?? { hits: [] };
63
+ return decide(rule, state.hits, now).result;
64
+ },
65
+ };
66
+ }
67
+ /**
68
+ * Fixed window: N hits per aligned `windowMs` bucket.
69
+ *
70
+ * Kept because three of the replaced implementations chose it deliberately
71
+ * for cheapness, and because its edge-burst behaviour (up to 2N around a
72
+ * boundary) is sometimes fine and sometimes the whole objection — the choice
73
+ * should be named at the call site, not implied by whichever file got copied.
74
+ *
75
+ * Implemented on the same store contract: the bucket is represented as one
76
+ * synthetic hit timestamp (the bucket start) repeated per hit, so a remote
77
+ * Store needs no second schema.
78
+ */
79
+ export function fixedWindow(rule, store = new MemoryStore()) {
80
+ const bucketStart = (now) => now - (now % rule.windowMs);
81
+ return {
82
+ check(key, now = Date.now()) {
83
+ const start = bucketStart(now);
84
+ const state = store.get(key) ?? { hits: [] };
85
+ const live = state.hits.filter((t) => t === start);
86
+ const allowed = live.length < rule.limit;
87
+ store.set(key, { hits: allowed ? [...live, start] : live });
88
+ const resetAt = start + rule.windowMs;
89
+ return {
90
+ allowed,
91
+ limit: rule.limit,
92
+ remaining: Math.max(0, rule.limit - live.length - (allowed ? 1 : 0)),
93
+ resetAt,
94
+ retryAfterSeconds: allowed ? 0 : Math.max(1, Math.ceil((resetAt - now) / 1000)),
95
+ };
96
+ },
97
+ peek(key, now = Date.now()) {
98
+ const start = bucketStart(now);
99
+ const state = store.get(key) ?? { hits: [] };
100
+ const live = state.hits.filter((t) => t === start);
101
+ const allowed = live.length < rule.limit;
102
+ const resetAt = start + rule.windowMs;
103
+ return {
104
+ allowed,
105
+ limit: rule.limit,
106
+ remaining: Math.max(0, rule.limit - live.length),
107
+ resetAt,
108
+ retryAfterSeconds: allowed ? 0 : Math.max(1, Math.ceil((resetAt - now) / 1000)),
109
+ };
110
+ },
111
+ };
112
+ }
@@ -0,0 +1,54 @@
1
+ /**
2
+ * Where the counts live — the ONE thing the fleet's implementations genuinely
3
+ * disagreed on, so it is the one thing left injectable.
4
+ *
5
+ * Of the twelve implementations this package replaces, eleven kept counts in
6
+ * process memory and one (orangecat) in Upstash Redis. Everything around the
7
+ * store — the window arithmetic, the refusal shape, the headers — was the same
8
+ * idea written twelve slightly different ways. So the algorithm is fixed and
9
+ * the store is a seam: an app that outgrows one process implements these two
10
+ * methods over Redis/Postgres and changes nothing else.
11
+ *
12
+ * The store speaks in WINDOWS, not in "check" calls, so a remote
13
+ * implementation is one round trip: read-modify-write of a single small value
14
+ * under a key. No store method ever decides anything — deciding is the
15
+ * algorithm's job, and keeping the store dumb is what makes an adapter a
16
+ * dozen lines instead of a re-implementation.
17
+ */
18
+ /** One key's state: hit timestamps (ms) inside the current horizon. */
19
+ export type WindowState = {
20
+ /** Timestamps of counted hits, milliseconds. The algorithm prunes; the
21
+ * store just holds. */
22
+ hits: number[];
23
+ };
24
+ export interface Store {
25
+ /** The state for `key`, or undefined if none is held. */
26
+ get(key: string): WindowState | undefined;
27
+ /** Replace the state for `key`. An empty `hits` MAY be dropped entirely. */
28
+ set(key: string, state: WindowState): void;
29
+ }
30
+ /**
31
+ * The default store: in-process, and BOUNDED.
32
+ *
33
+ * Bounded is the point, not an optimisation. One of the twelve replaced
34
+ * implementations kept a bare `Map` that only ever grew — every distinct key
35
+ * (an IP, in practice) left an entry forever, which is a slow memory leak fed
36
+ * by strangers. Two others solved it independently (a prune pass, an LRU).
37
+ * This store evicts the oldest-touched key past `maxKeys`, so the failure mode
38
+ * is "a very old bucket forgets", never "the process grows without bound".
39
+ *
40
+ * Scope, stated plainly: per-process. Behind N workers each holds its own
41
+ * counts and the effective limit multiplies by N. That is acceptable for
42
+ * blunting scripted abuse (what every replaced implementation was actually
43
+ * for) and wrong for billing enforcement — for that, implement `Store` over
44
+ * something shared.
45
+ */
46
+ export declare class MemoryStore implements Store {
47
+ private maxKeys;
48
+ private map;
49
+ constructor(maxKeys?: number);
50
+ get(key: string): WindowState | undefined;
51
+ set(key: string, state: WindowState): void;
52
+ /** How many keys are currently held. Exposed for tests and monitoring. */
53
+ get size(): number;
54
+ }
package/dist/store.js ADDED
@@ -0,0 +1,69 @@
1
+ /**
2
+ * Where the counts live — the ONE thing the fleet's implementations genuinely
3
+ * disagreed on, so it is the one thing left injectable.
4
+ *
5
+ * Of the twelve implementations this package replaces, eleven kept counts in
6
+ * process memory and one (orangecat) in Upstash Redis. Everything around the
7
+ * store — the window arithmetic, the refusal shape, the headers — was the same
8
+ * idea written twelve slightly different ways. So the algorithm is fixed and
9
+ * the store is a seam: an app that outgrows one process implements these two
10
+ * methods over Redis/Postgres and changes nothing else.
11
+ *
12
+ * The store speaks in WINDOWS, not in "check" calls, so a remote
13
+ * implementation is one round trip: read-modify-write of a single small value
14
+ * under a key. No store method ever decides anything — deciding is the
15
+ * algorithm's job, and keeping the store dumb is what makes an adapter a
16
+ * dozen lines instead of a re-implementation.
17
+ */
18
+ /**
19
+ * The default store: in-process, and BOUNDED.
20
+ *
21
+ * Bounded is the point, not an optimisation. One of the twelve replaced
22
+ * implementations kept a bare `Map` that only ever grew — every distinct key
23
+ * (an IP, in practice) left an entry forever, which is a slow memory leak fed
24
+ * by strangers. Two others solved it independently (a prune pass, an LRU).
25
+ * This store evicts the oldest-touched key past `maxKeys`, so the failure mode
26
+ * is "a very old bucket forgets", never "the process grows without bound".
27
+ *
28
+ * Scope, stated plainly: per-process. Behind N workers each holds its own
29
+ * counts and the effective limit multiplies by N. That is acceptable for
30
+ * blunting scripted abuse (what every replaced implementation was actually
31
+ * for) and wrong for billing enforcement — for that, implement `Store` over
32
+ * something shared.
33
+ */
34
+ export class MemoryStore {
35
+ maxKeys;
36
+ map = new Map();
37
+ constructor(maxKeys = 5_000) {
38
+ this.maxKeys = maxKeys;
39
+ }
40
+ get(key) {
41
+ const state = this.map.get(key);
42
+ if (state) {
43
+ // Refresh recency so eviction tracks use, not insertion order.
44
+ this.map.delete(key);
45
+ this.map.set(key, state);
46
+ }
47
+ return state;
48
+ }
49
+ set(key, state) {
50
+ if (state.hits.length === 0) {
51
+ this.map.delete(key);
52
+ return;
53
+ }
54
+ this.map.delete(key);
55
+ this.map.set(key, state);
56
+ // Map iteration order is insertion order, so the first key is the
57
+ // least-recently-touched — evicting it is LRU without a dependency.
58
+ while (this.map.size > this.maxKeys) {
59
+ const oldest = this.map.keys().next().value;
60
+ if (oldest === undefined)
61
+ break;
62
+ this.map.delete(oldest);
63
+ }
64
+ }
65
+ /** How many keys are currently held. Exposed for tests and monitoring. */
66
+ get size() {
67
+ return this.map.size;
68
+ }
69
+ }
package/package.json CHANGED
@@ -1,6 +1,59 @@
1
1
  {
2
2
  "name": "@bitbaum/limitkit",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
3
+ "version": "0.2.2",
4
+ "description": "Rate limiting as a decision, not a middleware: fixed and sliding windows over an injectable store, a bounded in-memory store, standard RateLimit headers, and client-IP extraction. No HTTP client, no framework.",
5
+ "license": "MIT",
6
+ "author": "Mao Nakamoto",
7
+ "homepage": "https://github.com/bitbaum/limitkit#readme",
8
+ "repository": {
9
+ "type": "git",
10
+ "url": "git+https://github.com/bitbaum/limitkit.git"
11
+ },
12
+ "bugs": {
13
+ "url": "https://github.com/bitbaum/limitkit/issues"
14
+ },
15
+ "keywords": [
16
+ "rate-limit",
17
+ "rate-limiting",
18
+ "sliding-window",
19
+ "fixed-window",
20
+ "throttle",
21
+ "headless"
22
+ ],
23
+ "type": "module",
24
+ "sideEffects": false,
25
+ "engines": {
26
+ "node": ">=20"
27
+ },
28
+ "publishConfig": {
29
+ "access": "public",
30
+ "provenance": true
31
+ },
32
+ "files": [
33
+ "dist"
34
+ ],
35
+ "exports": {
36
+ ".": {
37
+ "types": "./dist/index.d.ts",
38
+ "default": "./dist/index.js"
39
+ }
40
+ },
41
+ "devDependencies": {
42
+ "@eslint/js": "^10.0.1",
43
+ "@types/node": "^26.4.1",
44
+ "eslint": "^10.9.1",
45
+ "globals": "^17.12.0",
46
+ "prettier": "3.10.0",
47
+ "typescript": "^6.0.3",
48
+ "typescript-eslint": "^8.69.0"
49
+ },
50
+ "scripts": {
51
+ "build": "tsc -p tsconfig.json",
52
+ "lint": "eslint .",
53
+ "typecheck": "tsc -p tsconfig.json --noEmit",
54
+ "test": "node --test test/*.test.js",
55
+ "verify": "pnpm run format:check && pnpm run lint && pnpm run typecheck && pnpm run build && pnpm test",
56
+ "format": "prettier --write .",
57
+ "format:check": "prettier --check ."
58
+ }
6
59
  }