@superfunctions/middleware 0.1.0

package/dist/index.d.ts

@@ -0,0 +1 @@
+export * from './rate-limit.js';

package/dist/index.js

@@ -0,0 +1 @@
+export * from './rate-limit.js';

package/dist/index.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.test.js

@@ -0,0 +1,14 @@
+import { describe, it, expect } from 'vitest';
+import { createRateLimiter } from './rate-limit.js';
+describe('middleware', () => {
+    it('should create rate limiter', async () => {
+        const limiter = createRateLimiter({ windowMs: 60000, maxRequests: 100 });
+        const result = await limiter.check({ key: 'test' });
+        expect(result.allowed).toBe(true);
+    });
+    it('should export RateLimiter interface', async () => {
+        const limiter = createRateLimiter({ windowMs: 60000, maxRequests: 100 });
+        expect(typeof limiter.check).toBe('function');
+        expect(typeof limiter.reset).toBe('function');
+    });
+});

package/dist/rate-limit.d.ts

@@ -0,0 +1,30 @@
+import type { Adapter, KVStoreAdapter } from '@superfunctions/db';
+export { KVStoreAdapter };
+export type LegacyWindowAlgorithm = 'sliding-window' | 'fixed-window';
+export type RateLimitAlgorithm = LegacyWindowAlgorithm | 'token-bucket';
+export interface RateLimitConfig {
+    windowMs: number;
+    maxRequests: number;
+    keyPrefix?: string;
+    persistence?: Adapter | KVStoreAdapter;
+    algorithm?: RateLimitAlgorithm;
+    now?: () => number;
+}
+export interface RateLimitResult {
+    allowed: boolean;
+    remaining: number;
+    resetAt: string;
+    total: number;
+}
+export interface CheckLimitInput {
+    key: string;
+    windowSeconds?: number;
+    limit?: number;
+}
+export interface RateLimiter {
+    check(input: CheckLimitInput): Promise<RateLimitResult>;
+    reset(key: string): Promise<void>;
+}
+declare function createInMemoryKVStore(now?: () => number): KVStoreAdapter;
+export declare function createRateLimiter(config: RateLimitConfig): RateLimiter;
+export { createInMemoryKVStore };

package/dist/rate-limit.js

@@ -0,0 +1,202 @@
+function createInMemoryKVStore(now = Date.now) {
+    const store = new Map();
+    return {
+        async get(key) {
+            const entry = store.get(key);
+            if (!entry)
+                return null;
+            if (entry.expiresAt && now() > entry.expiresAt) {
+                store.delete(key);
+                return null;
+            }
+            return entry.value;
+        },
+        async set(input) {
+            store.set(input.key, {
+                value: input.value,
+                expiresAt: input.ttlSeconds ? now() + input.ttlSeconds * 1000 : undefined,
+            });
+        },
+        async delete(key) {
+            store.delete(key);
+        },
+    };
+}
+function isAdapter(p) {
+    return !!p && typeof p === 'object' && 'findOne' in p && 'create' in p;
+}
+function ensureKV(p, now) {
+    if (isAdapter(p)) {
+        return {
+            async get(key) {
+                const res = await p.findOne({
+                    model: 'rate_limits',
+                    where: [{ field: 'key', operator: 'eq', value: key }],
+                });
+                if (!res)
+                    return null;
+                if (res.expiresAt && new Date(res.expiresAt).getTime() < now()) {
+                    await p.delete({ model: 'rate_limits', where: [{ field: 'key', operator: 'eq', value: key }] });
+                    return null;
+                }
+                return res.value;
+            },
+            async set(input) {
+                const expiresAt = input.ttlSeconds
+                    ? new Date(now() + input.ttlSeconds * 1000).toISOString()
+                    : undefined;
+                await p.upsert({
+                    model: 'rate_limits',
+                    where: [{ field: 'key', operator: 'eq', value: input.key }],
+                    create: { key: input.key, value: input.value, expiresAt },
+                    update: { value: input.value, expiresAt },
+                });
+            },
+            async delete(key) {
+                await p.delete({ model: 'rate_limits', where: [{ field: 'key', operator: 'eq', value: key }] });
+            },
+        };
+    }
+    return p;
+}
+async function getState(kv, key) {
+    const data = await kv.get(key);
+    if (!data)
+        return null;
+    try {
+        return JSON.parse(data);
+    }
+    catch {
+        return null;
+    }
+}
+async function setState(kv, key, state, ttlMs) {
+    if (ttlMs <= 0) {
+        return;
+    }
+    await kv.set({
+        key,
+        value: JSON.stringify(state),
+        ttlSeconds: Math.ceil(ttlMs / 1000),
+    });
+}
+export function createRateLimiter(config) {
+    const now = config.now ?? Date.now;
+    const { windowMs, maxRequests, keyPrefix = 'ratelimit:', persistence = createInMemoryKVStore(now), algorithm = 'fixed-window', } = config;
+    const kv = ensureKV(persistence, now);
+    const keyLocks = new Map();
+    async function withKeyLock(key, work) {
+        const prior = keyLocks.get(key) ?? Promise.resolve();
+        let resolveLock;
+        const current = new Promise((resolve) => {
+            resolveLock = resolve;
+        });
+        const queued = prior.then(() => current);
+        keyLocks.set(key, queued);
+        await prior;
+        try {
+            return await work();
+        }
+        finally {
+            resolveLock();
+            if (keyLocks.get(key) === queued) {
+                keyLocks.delete(key);
+            }
+        }
+    }
+    return {
+        async check(input) {
+            const key = `${keyPrefix}${input.key}`;
+            return withKeyLock(key, async () => {
+                const effectiveWindowMs = (input.windowSeconds !== undefined ? input.windowSeconds * 1000 : undefined) ?? windowMs;
+                const effectiveLimit = input.limit ?? maxRequests;
+                const currentTime = now();
+                if (!Number.isFinite(effectiveWindowMs) || effectiveWindowMs <= 0) {
+                    throw new Error('RATE_LIMIT_WINDOW_INVALID');
+                }
+                if (!Number.isFinite(effectiveLimit) || effectiveLimit < 0) {
+                    throw new Error('RATE_LIMIT_LIMIT_INVALID');
+                }
+                if (algorithm === 'sliding-window') {
+                    const state = (await getState(kv, key)) ?? { timestamps: [] };
+                    const floor = currentTime - effectiveWindowMs;
+                    state.timestamps = state.timestamps.filter((timestamp) => timestamp > floor);
+                    const allowed = state.timestamps.length < effectiveLimit;
+                    if (allowed) {
+                        state.timestamps.push(currentTime);
+                    }
+                    const oldest = state.timestamps[0] ?? currentTime;
+                    const resetAt = oldest + effectiveWindowMs;
+                    const ttlMs = Math.max(1, resetAt - currentTime);
+                    await setState(kv, key, state, ttlMs);
+                    return {
+                        allowed,
+                        remaining: Math.max(0, effectiveLimit - state.timestamps.length),
+                        resetAt: new Date(resetAt).toISOString(),
+                        total: effectiveLimit,
+                    };
+                }
+                if (algorithm === 'token-bucket') {
+                    if (effectiveLimit <= 0) {
+                        const resetAt = currentTime + Math.max(0, effectiveWindowMs);
+                        return {
+                            allowed: false,
+                            remaining: 0,
+                            resetAt: new Date(resetAt).toISOString(),
+                            total: effectiveLimit,
+                        };
+                    }
+                    const refillRatePerMs = effectiveLimit / effectiveWindowMs;
+                    const state = (await getState(kv, key)) ?? {
+                        tokens: effectiveLimit,
+                        lastRefill: currentTime,
+                    };
+                    const elapsed = Math.max(0, currentTime - state.lastRefill);
+                    state.tokens = Math.min(effectiveLimit, state.tokens + elapsed * refillRatePerMs);
+                    state.lastRefill = currentTime;
+                    const allowed = state.tokens >= 1;
+                    if (allowed) {
+                        state.tokens -= 1;
+                    }
+                    const msUntilNextToken = state.tokens >= 1 ? 0 : Math.ceil((1 - state.tokens) / refillRatePerMs);
+                    const msUntilFull = Math.ceil((effectiveLimit - state.tokens) / refillRatePerMs);
+                    const resetAt = currentTime + msUntilNextToken;
+                    await setState(kv, key, state, Math.max(1, msUntilFull));
+                    return {
+                        allowed,
+                        remaining: Math.max(0, Math.floor(state.tokens)),
+                        resetAt: new Date(resetAt).toISOString(),
+                        total: effectiveLimit,
+                    };
+                }
+                const state = (await getState(kv, key)) ?? {
+                    count: 0,
+                    windowStart: currentTime,
+                };
+                if (currentTime >= state.windowStart + effectiveWindowMs) {
+                    state.count = 0;
+                    state.windowStart = currentTime;
+                }
+                const allowed = state.count < effectiveLimit;
+                if (allowed) {
+                    state.count += 1;
+                }
+                const resetAt = state.windowStart + effectiveWindowMs;
+                await setState(kv, key, state, Math.max(1, resetAt - currentTime));
+                return {
+                    allowed,
+                    remaining: Math.max(0, effectiveLimit - state.count),
+                    resetAt: new Date(resetAt).toISOString(),
+                    total: effectiveLimit,
+                };
+            });
+        },
+        async reset(key) {
+            const namespacedKey = `${keyPrefix}${key}`;
+            await withKeyLock(namespacedKey, async () => {
+                await kv.delete(namespacedKey);
+            });
+        },
+    };
+}
+export { createInMemoryKVStore };

package/dist/rate-limit.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/rate-limit.test.js

@@ -0,0 +1,200 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { createRateLimiter, createInMemoryKVStore } from './rate-limit.js';
+describe('rate-limit', () => {
+    beforeEach(() => {
+        vi.useRealTimers();
+    });
+    describe('createRateLimiter', () => {
+        it('allows requests within fixed-window limit', async () => {
+            const limiter = createRateLimiter({
+                windowMs: 60000,
+                maxRequests: 3,
+                algorithm: 'fixed-window',
+            });
+            const r1 = await limiter.check({ key: 'user1' });
+            expect(r1.allowed).toBe(true);
+            expect(r1.remaining).toBe(2);
+            const r2 = await limiter.check({ key: 'user1' });
+            expect(r2.allowed).toBe(true);
+            expect(r2.remaining).toBe(1);
+            const r3 = await limiter.check({ key: 'user1' });
+            expect(r3.allowed).toBe(true);
+            expect(r3.remaining).toBe(0);
+            const r4 = await limiter.check({ key: 'user1' });
+            expect(r4.allowed).toBe(false);
+        });
+        it('enforces sliding-window behavior based on timestamp eviction (TV-REUSE-011-P)', async () => {
+            vi.useFakeTimers();
+            vi.setSystemTime(new Date('2026-03-12T00:00:00.000Z'));
+            const limiter = createRateLimiter({
+                windowMs: 1000,
+                maxRequests: 5,
+                algorithm: 'sliding-window',
+            });
+            for (let i = 0; i < 5; i += 1) {
+                const result = await limiter.check({ key: 'sliding-user' });
+                expect(result.allowed).toBe(true);
+                vi.setSystemTime(Date.now() + 100);
+            }
+            const blockedAt500 = await limiter.check({ key: 'sliding-user' });
+            expect(blockedAt500.allowed).toBe(false);
+            vi.setSystemTime(Date.now() + 500);
+            const allowedAt1000 = await limiter.check({ key: 'sliding-user' });
+            expect(allowedAt1000.allowed).toBe(true);
+        });
+        it('enforces token-bucket behavior distinctly from fixed-window (TV-REUSE-011-N)', async () => {
+            vi.useFakeTimers();
+            vi.setSystemTime(new Date('2026-03-12T00:00:00.000Z'));
+            const tokenBucket = createRateLimiter({
+                windowMs: 1000,
+                maxRequests: 2,
+                algorithm: 'token-bucket',
+            });
+            expect((await tokenBucket.check({ key: 'tb-user' })).allowed).toBe(true);
+            expect((await tokenBucket.check({ key: 'tb-user' })).allowed).toBe(true);
+            expect((await tokenBucket.check({ key: 'tb-user' })).allowed).toBe(false);
+            // Token bucket refills continuously; fixed-window would still block at +500ms.
+            vi.setSystemTime(Date.now() + 500);
+            const tokenBucketAtHalfWindow = await tokenBucket.check({ key: 'tb-user' });
+            expect(tokenBucketAtHalfWindow.allowed).toBe(true);
+            const fixedWindow = createRateLimiter({
+                windowMs: 1000,
+                maxRequests: 2,
+                algorithm: 'fixed-window',
+            });
+            expect((await fixedWindow.check({ key: 'fw-user' })).allowed).toBe(true);
+            expect((await fixedWindow.check({ key: 'fw-user' })).allowed).toBe(true);
+            expect((await fixedWindow.check({ key: 'fw-user' })).allowed).toBe(false);
+            vi.setSystemTime(Date.now() + 500);
+            const fixedAtHalfWindow = await fixedWindow.check({ key: 'fw-user' });
+            expect(fixedAtHalfWindow.allowed).toBe(false);
+        });
+        it('returns a clean denial for zero-limit token buckets instead of crashing', async () => {
+            vi.useFakeTimers();
+            vi.setSystemTime(new Date('2026-03-12T00:00:00.000Z'));
+            const limiter = createRateLimiter({
+                windowMs: 1000,
+                maxRequests: 0,
+                algorithm: 'token-bucket',
+            });
+            await expect(limiter.check({ key: 'tb-zero' })).resolves.toMatchObject({
+                allowed: false,
+                remaining: 0,
+                total: 0,
+            });
+        });
+        it('rejects non-positive effective windows before computing bucket math', async () => {
+            const limiter = createRateLimiter({
+                windowMs: 1000,
+                maxRequests: 1,
+                algorithm: 'token-bucket',
+            });
+            await expect(limiter.check({ key: 'tb-invalid-window', windowSeconds: 0 })).rejects.toThrow('RATE_LIMIT_WINDOW_INVALID');
+        });
+        it('rejects non-finite or negative effective limits before rate-limit calculations', async () => {
+            const limiter = createRateLimiter({
+                windowMs: 1000,
+                maxRequests: 1,
+                algorithm: 'token-bucket',
+            });
+            await expect(limiter.check({ key: 'tb-invalid-limit', limit: Number.NaN })).rejects.toThrow('RATE_LIMIT_LIMIT_INVALID');
+            await expect(limiter.check({ key: 'tb-negative-limit', limit: -1 })).rejects.toThrow('RATE_LIMIT_LIMIT_INVALID');
+        });
+        it('tracks different keys separately', async () => {
+            const limiter = createRateLimiter({
+                windowMs: 60000,
+                maxRequests: 1,
+            });
+            expect((await limiter.check({ key: 'user1' })).allowed).toBe(true);
+            expect((await limiter.check({ key: 'user2' })).allowed).toBe(true);
+            expect((await limiter.check({ key: 'user1' })).allowed).toBe(false);
+        });
+        it('resets key state', async () => {
+            const limiter = createRateLimiter({
+                windowMs: 60000,
+                maxRequests: 1,
+            });
+            await limiter.check({ key: 'user1' });
+            expect((await limiter.check({ key: 'user1' })).allowed).toBe(false);
+            await limiter.reset('user1');
+            expect((await limiter.check({ key: 'user1' })).allowed).toBe(true);
+        });
+        it('includes reset time in result', async () => {
+            const now = Date.now();
+            const windowMs = 60000;
+            const limiter = createRateLimiter({
+                windowMs,
+                maxRequests: 10,
+            });
+            const result = await limiter.check({ key: 'user1' });
+            const resetAtTs = new Date(result.resetAt).getTime();
+            expect(resetAtTs).toBeGreaterThanOrEqual(now);
+            expect(resetAtTs).toBeLessThanOrEqual(now + windowMs + 100);
+        });
+        it('respects check overrides', async () => {
+            const limiter = createRateLimiter({
+                windowMs: 60000,
+                maxRequests: 10,
+            });
+            expect((await limiter.check({ key: 'user_override', limit: 1 })).allowed).toBe(true);
+            expect((await limiter.check({ key: 'user_override', limit: 1 })).allowed).toBe(false);
+        });
+        it('uses custom key prefix', async () => {
+            const store = createInMemoryKVStore();
+            const limiter = createRateLimiter({
+                windowMs: 60000,
+                maxRequests: 5,
+                keyPrefix: 'custom:',
+                persistence: store,
+            });
+            await limiter.check({ key: 'test' });
+            const value = await store.get('custom:test');
+            expect(value).not.toBeNull();
+        });
+        it('accepts external persistence', async () => {
+            const internalStore = new Map();
+            const customStore = {
+                async get(key) {
+                    return internalStore.get(key) ?? null;
+                },
+                async set(input) {
+                    internalStore.set(input.key, input.value);
+                },
+                async delete(key) {
+                    internalStore.delete(key);
+                },
+            };
+            const limiter = createRateLimiter({
+                windowMs: 60000,
+                maxRequests: 2,
+                persistence: customStore,
+            });
+            await limiter.check({ key: 'user1' });
+            expect(internalStore.size).toBe(1);
+        });
+    });
+    describe('createInMemoryKVStore', () => {
+        let store;
+        beforeEach(() => {
+            store = createInMemoryKVStore();
+        });
+        it('gets and sets values', async () => {
+            await store.set({ key: 'key1', value: 'value1' });
+            expect(await store.get('key1')).toBe('value1');
+        });
+        it('returns null for missing keys', async () => {
+            expect(await store.get('missing')).toBeNull();
+        });
+        it('deletes keys', async () => {
+            await store.set({ key: 'key1', value: 'value1' });
+            await store.delete('key1');
+            expect(await store.get('key1')).toBeNull();
+        });
+        it('expires keys after TTL', async () => {
+            await store.set({ key: 'key1', value: 'value1', ttlSeconds: 0.01 });
+            expect(await store.get('key1')).toBe('value1');
+            await new Promise((resolve) => setTimeout(resolve, 20));
+            expect(await store.get('key1')).toBeNull();
+        });
+    });
+});

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@superfunctions/middleware",
+  "version": "0.1.0",
+  "description": "Shared middleware utilities for Superfunctions",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./rate-limit": {
+      "types": "./dist/rate-limit.d.ts",
+      "default": "./dist/rate-limit.js"
+    }
+  },
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest",
+    "test:watch": "vitest --watch",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "keywords": ["middleware", "rate-limit", "superfunctions"],
+  "author": "21n",
+  "license": "MIT",
+  "bugs": { "url": "https://github.com/21nCo/super-functions/issues" },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/21nCo/super-functions.git",
+    "directory": "packages/middleware"
+  },
+  "publishConfig": { "access": "public" },
+  "peerDependencies": {
+    "@superfunctions/db": "0.1.4"
+  },
+  "peerDependenciesMeta": {
+    "@superfunctions/db": { "optional": true }
+  },
+  "devDependencies": {
+    "@superfunctions/db": "^0.1.3",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0",
+    "vitest": "^3.2.4"
+  }
+}