kitcn 0.0.1 → 0.12.1

package/dist/ratelimit/react/index.d.ts

@@ -0,0 +1,76 @@
+'use client';
+import { FunctionReference } from "convex/server";
+
+//#region src/ratelimit/types.d.ts
+type RatelimitSnapshot = {
+  value: number;
+  ts: number;
+  shard: number;
+  config: ResolvedAlgorithm;
+};
+type FixedWindowAlgorithm = {
+  kind: 'fixedWindow';
+  limit: number;
+  window: number;
+  capacity: number;
+  start?: number;
+  maxReserved?: number;
+  shards: number;
+};
+type SlidingWindowAlgorithm = {
+  kind: 'slidingWindow';
+  limit: number;
+  window: number;
+  maxReserved?: number;
+  shards: number;
+};
+type TokenBucketAlgorithm = {
+  kind: 'tokenBucket';
+  refillRate: number;
+  interval: number;
+  maxTokens: number;
+  maxReserved?: number;
+  shards: number;
+};
+type ResolvedAlgorithm = FixedWindowAlgorithm | SlidingWindowAlgorithm | TokenBucketAlgorithm;
+type HookCheckValue = {
+  value: number;
+  ts: number;
+  config: ResolvedAlgorithm;
+  shard: number;
+  ok: boolean;
+  retryAt?: number;
+};
+//#endregion
+//#region src/ratelimit/react/use-rate-limit.d.ts
+type GetRatelimitValueQueryRef = FunctionReference<'query', 'public', {
+  identifier?: string;
+  sampleShards?: number;
+}, RatelimitSnapshot>;
+type GetServerTimeMutationRef = FunctionReference<'mutation', 'public', Record<string, never>, number>;
+type GetRatelimitValueQuery = GetRatelimitValueQueryRef | string;
+type GetServerTimeMutation = GetServerTimeMutationRef | string;
+type UseRatelimitOptions = {
+  identifier?: string;
+  count?: number;
+  sampleShards?: number;
+  getServerTimeMutation?: GetServerTimeMutation;
+};
+declare function useRatelimit(getRatelimitValueQuery: GetRatelimitValueQuery, options?: UseRatelimitOptions): {
+  status: undefined;
+  check: (ts?: number, requestedCount?: number) => HookCheckValue | undefined;
+} | {
+  status: {
+    ok: false;
+    retryAt: number;
+  };
+  check: (ts?: number, requestedCount?: number) => HookCheckValue | undefined;
+} | {
+  status: {
+    ok: true;
+    retryAt: undefined;
+  };
+  check: (ts?: number, requestedCount?: number) => HookCheckValue | undefined;
+};
+//#endregion
+export { GetRatelimitValueQuery, GetRatelimitValueQueryRef, GetServerTimeMutation, GetServerTimeMutationRef, UseRatelimitOptions, useRatelimit };

package/dist/ratelimit/react/index.js

@@ -0,0 +1,183 @@
+'use client';
+import { useConvex, useQuery } from "convex/react";
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { makeFunctionReference } from "convex/server";
+
+//#region src/ratelimit/core/calculate-rate-limit.ts
+function calculateRatelimit(state, algorithm, now, count) {
+	if (algorithm.kind === "fixedWindow") return calculateFixedWindow(state, algorithm, now, count);
+	if (algorithm.kind === "tokenBucket") return calculateTokenBucket(state, algorithm, now, count);
+	return calculateSlidingWindow(state, algorithm, now, count);
+}
+function calculateTokenBucket(state, config, now, count) {
+	const ratePerMs = config.refillRate / config.interval;
+	const initial = state ?? {
+		value: config.maxTokens,
+		ts: now
+	};
+	const elapsed = Math.max(0, now - initial.ts);
+	const nextValue = Math.min(initial.value + elapsed * ratePerMs, config.maxTokens) - count;
+	const retryAfter = nextValue < 0 ? Math.ceil(-nextValue / ratePerMs) : void 0;
+	return {
+		state: {
+			value: nextValue,
+			ts: now
+		},
+		retryAfter,
+		remaining: Math.max(0, Math.floor(nextValue)),
+		reset: retryAfter ? now + retryAfter : now,
+		limit: config.maxTokens
+	};
+}
+function calculateFixedWindow(state, config, now, count) {
+	const windowStart = alignWindowStart(now, config.window, config.start);
+	const initial = state ?? {
+		value: config.capacity,
+		ts: windowStart
+	};
+	const elapsedWindows = Math.max(0, Math.floor((now - initial.ts) / config.window));
+	const replenished = Math.min(initial.value + config.limit * elapsedWindows, config.capacity);
+	const ts = initial.ts + elapsedWindows * config.window;
+	const nextValue = replenished - count;
+	const retryAfter = nextValue < 0 ? ts + config.window * Math.ceil(-nextValue / config.limit) - now : void 0;
+	return {
+		state: {
+			value: nextValue,
+			ts
+		},
+		retryAfter,
+		remaining: Math.max(0, Math.floor(nextValue)),
+		reset: ts + config.window,
+		limit: config.limit
+	};
+}
+function calculateSlidingWindow(state, config, now, count) {
+	const windowStart = alignWindowStart(now, config.window);
+	const previousWindowStart = windowStart - config.window;
+	const elapsedInWindow = now - windowStart;
+	const previousWeight = Math.max(0, (config.window - elapsedInWindow) / config.window);
+	let currentCount = 0;
+	let previousCount = 0;
+	if (state) {
+		if (state.ts === windowStart) {
+			currentCount = Math.max(0, state.value);
+			if (state.auxTs === previousWindowStart) previousCount = Math.max(0, state.auxValue ?? 0);
+		} else if (state.ts === previousWindowStart) previousCount = Math.max(0, state.value);
+	}
+	const projectedCurrent = currentCount + count;
+	const projectedUsed = projectedCurrent + previousCount * previousWeight;
+	const remaining = config.limit - projectedUsed;
+	const retryAfter = remaining < 0 ? Math.max(1, config.window - elapsedInWindow) : void 0;
+	return {
+		state: {
+			value: projectedCurrent,
+			ts: windowStart,
+			auxValue: previousCount,
+			auxTs: previousWindowStart
+		},
+		retryAfter,
+		remaining: Math.max(0, Math.floor(remaining)),
+		reset: windowStart + config.window,
+		limit: config.limit
+	};
+}
+function alignWindowStart(now, window, start = 0) {
+	const offsetNow = now - start;
+	return start + Math.floor(offsetNow / window) * window;
+}
+
+//#endregion
+//#region src/ratelimit/react/use-rate-limit.ts
+function useRatelimit(getRatelimitValueQuery, options) {
+	const [timeOffset, setTimeOffset] = useState(0);
+	const [now, setNow] = useState(() => Date.now());
+	const convex = useConvex();
+	const getRatelimitValueQueryRef = useMemo(() => resolveGetRatelimitValueQuery(getRatelimitValueQuery), [getRatelimitValueQuery]);
+	const { getServerTimeMutation, count, identifier, sampleShards } = options ?? {};
+	const getServerTimeMutationRef = useMemo(() => getServerTimeMutation ? resolveGetServerTimeMutation(getServerTimeMutation) : void 0, [getServerTimeMutation]);
+	useEffect(() => {
+		if (!getServerTimeMutationRef) return;
+		const clientTime = Date.now();
+		convex.mutation(getServerTimeMutationRef, {}).then((serverTime) => {
+			const latency = Date.now() - clientTime;
+			setTimeOffset(serverTime - clientTime - latency / 2);
+		});
+	}, [convex, getServerTimeMutationRef]);
+	const ratelimitData = useQuery(getRatelimitValueQueryRef, {
+		identifier,
+		sampleShards
+	});
+	const check = useCallback((ts, requestedCount) => {
+		if (!ratelimitData) return;
+		const serverTs = (ts ?? Date.now()) + timeOffset;
+		const evaluation = evaluateSnapshot(ratelimitData, serverTs, requestedCount ?? count ?? 1);
+		return {
+			value: evaluation.value,
+			ts: evaluation.ts - timeOffset,
+			config: ratelimitData.config,
+			shard: ratelimitData.shard,
+			ok: evaluation.value >= 0,
+			retryAt: evaluation.retryAfter ? serverTs + evaluation.retryAfter - timeOffset : void 0
+		};
+	}, [
+		count,
+		ratelimitData,
+		timeOffset
+	]);
+	const current = check(now, count ?? 1);
+	const response = useMemo(() => {
+		if (!current) return {
+			status: void 0,
+			check
+		};
+		if (current.value < 0) return {
+			status: {
+				ok: false,
+				retryAt: current.retryAt
+			},
+			check
+		};
+		return {
+			status: {
+				ok: true,
+				retryAt: void 0
+			},
+			check
+		};
+	}, [check, current]);
+	useEffect(() => {
+		if (response.status?.ok !== false || !response.status.retryAt) return;
+		const timeout = setTimeout(() => setNow(Date.now()), Math.max(0, response.status.retryAt - now));
+		return () => clearTimeout(timeout);
+	}, [
+		now,
+		response.status?.ok,
+		response.status?.retryAt
+	]);
+	return response;
+}
+function resolveGetRatelimitValueQuery(ref) {
+	if (typeof ref === "string") return makeFunctionReference(ref);
+	return ref;
+}
+function resolveGetServerTimeMutation(ref) {
+	if (typeof ref === "string") return makeFunctionReference(ref);
+	return ref;
+}
+function evaluateSnapshot(snapshot, now, count) {
+	const evaluated = calculateRatelimit(snapshot.config.kind === "slidingWindow" ? {
+		value: Math.max(0, snapshot.config.limit - snapshot.value),
+		ts: snapshot.ts
+	} : {
+		value: snapshot.value,
+		ts: snapshot.ts
+	}, snapshot.config, now, count);
+	return {
+		value: snapshot.config.kind === "slidingWindow" ? evaluated.retryAfter !== void 0 ? -1 : evaluated.remaining : evaluated.state.value,
+		ts: evaluated.state.ts,
+		retryAfter: evaluated.retryAfter
+	};
+}
+
+//#endregion
+export { useRatelimit };