kitcn/dist/ratelimit/index.d.ts

kitcn - React Query integration and CLI tools for Convex

import { o as MiddlewareBuilder } from "../types-CnTpHR1F.js";
import { t as Plugin } from "../middleware-DrtexzF3.js";
import * as convex_server0 from "convex/server";

//#region src/ratelimit/duration.d.ts
type DurationUnit = 'ms' | 's' | 'm' | 'h' | 'd';
type DurationString = `${number} ${DurationUnit}` | `${number}${DurationUnit}`;
type Duration = number | DurationString;
declare function toMs(duration: Duration): number;
//#endregion
//#region src/ratelimit/types.d.ts
type RatelimitReason = 'timeout' | 'cacheBlock' | 'denyList';
type RatelimitResponse = {
  success: boolean;
  ok: boolean;
  limit: number;
  remaining: number;
  reset: number;
  pending: Promise<unknown>;
  reason?: RatelimitReason;
  deniedValue?: string;
};
type RemainingResponse = {
  remaining: number;
  reset: number;
  limit: number;
};
type DynamicLimitResponse = {
  dynamicLimit: number | null;
};
type RatelimitState = {
  value: number;
  ts: number;
  auxValue?: number;
  auxTs?: number;
};
type RatelimitSnapshot = {
  value: number;
  ts: number;
  shard: number;
  config: ResolvedAlgorithm;
};
type BaseAlgorithmOptions = {
  shards?: number;
  maxReserved?: number;
};
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 AlgorithmOptions = BaseAlgorithmOptions & {
  capacity?: number;
  start?: number;
};
type LimitRequest = {
  rate?: number;
  count?: number;
  reserve?: boolean;
  ip?: string;
  userAgent?: string;
  country?: string;
  geo?: unknown;
};
type CheckRequest = Omit<LimitRequest, 'reserve'> & {
  reserve?: boolean;
};
type FailureMode = 'closed' | 'open';
type ProtectionLists = {
  identifiers?: readonly string[];
  ips?: readonly string[];
  userAgents?: readonly string[];
  countries?: readonly string[];
};
type RatelimitConfig = {
  db?: ConvexRatelimitDbReader | ConvexRatelimitDbWriter;
  limiter: ResolvedAlgorithm;
  prefix?: string;
  dynamicLimits?: boolean;
  ephemeralCache?: Map<string, number> | false;
  timeout?: number;
  failureMode?: FailureMode;
  enableProtection?: boolean;
  denyListThreshold?: number;
  denyList?: ProtectionLists;
};
type RatelimitRow = {
  _id: string;
  _creationTime?: number;
  name: string;
  key?: string;
  shard: number;
  value: number;
  ts: number;
  auxValue?: number;
  auxTs?: number;
};
type ConvexQueryBuilder = {
  withIndex: (name: any, cb: any) => {
    unique: () => Promise<any>;
    collect: () => Promise<any[]>;
  };
};
type ConvexRatelimitDbReader = {
  query: (tableName: string) => ConvexQueryBuilder;
};
type ConvexRatelimitDbWriter = ConvexRatelimitDbReader & {
  insert: (...args: any[]) => Promise<any>;
  patch: (...args: any[]) => Promise<void>;
  delete: (...args: any[]) => Promise<void>;
};
type HookAPIOptions = {
  identifier?: string | ((ctx: unknown, fromClient?: string) => string | Promise<string>);
  sampleShards?: number;
};
type HookCheckValue = {
  value: number;
  ts: number;
  config: ResolvedAlgorithm;
  shard: number;
  ok: boolean;
  retryAt?: number;
};
//#endregion
//#region src/ratelimit/core/algorithms.d.ts
declare function fixedWindow(limit: number, window: Duration, options?: AlgorithmOptions): FixedWindowAlgorithm;
declare function slidingWindow(limit: number, window: Duration, options?: AlgorithmOptions): SlidingWindowAlgorithm;
declare function tokenBucket(refillRate: number, interval: Duration, maxTokens: number, options?: AlgorithmOptions): TokenBucketAlgorithm;
declare function applyDynamicLimit(algorithm: ResolvedAlgorithm, dynamicLimit: number | null): ResolvedAlgorithm;
//#endregion
//#region src/ratelimit/core/calculate-rate-limit.d.ts
type EvaluationResult = {
  state: RatelimitState;
  retryAfter?: number;
  remaining: number;
  reset: number;
  limit: number;
};
declare function calculateRatelimit(state: RatelimitState | null, algorithm: ResolvedAlgorithm, now: number, count: number): EvaluationResult;
//#endregion
//#region src/ratelimit/plugin.d.ts
type MaybePromise<T> = T | Promise<T>;
type RatelimitBuckets = Record<string, Record<string, ResolvedAlgorithm>>;
type BucketName<TBuckets extends RatelimitBuckets> = Extract<keyof TBuckets, string>;
type TierName<TBuckets extends RatelimitBuckets> = Extract<keyof TBuckets[BucketName<TBuckets>], string>;
type RatelimitResolvedArgs<TCtx, TMeta extends object, TUser, TBuckets extends RatelimitBuckets> = {
  ctx: TCtx;
  meta: TMeta;
  user: TUser;
  bucket: BucketName<TBuckets>;
  tier: TierName<TBuckets>;
  identifier: string;
};
type RatelimitPluginOptions<TCtx = unknown, TMeta extends object = object, TUser = unknown, TBuckets extends RatelimitBuckets = RatelimitBuckets> = {
  buckets: TBuckets;
  getBucket: (args: {
    ctx: TCtx;
    meta: TMeta;
  }) => MaybePromise<BucketName<TBuckets>>;
  getUser: (args: {
    ctx: TCtx;
    meta: TMeta;
  }) => MaybePromise<TUser>;
  getIdentifier: (args: {
    ctx: TCtx;
    meta: TMeta;
    user: TUser;
    bucket: BucketName<TBuckets>;
  }) => MaybePromise<string>;
  getTier: (user: TUser) => MaybePromise<TierName<TBuckets>>;
  getSignals: (args: RatelimitResolvedArgs<TCtx, TMeta, TUser, TBuckets>) => MaybePromise<LimitRequest | undefined>;
  prefix?: string | ((args: RatelimitResolvedArgs<TCtx, TMeta, TUser, TBuckets>) => MaybePromise<string>);
  failureMode?: 'closed' | 'open';
  enableProtection?: boolean;
  denyListThreshold?: number;
  message?: string | ((args: RatelimitResolvedArgs<TCtx, TMeta, TUser, TBuckets>) => MaybePromise<string>);
};
type AnyRatelimitPluginOptions = RatelimitPluginOptions<any, any, any, any>;
declare const RatelimitPlugin: Plugin<"ratelimit", AnyRatelimitPluginOptions, AnyRatelimitPluginOptions, unknown, Omit<{
  middleware: () => MiddlewareBuilder<any, any, {
    api: Record<string, unknown> & Record<"ratelimit", AnyRatelimitPluginOptions>;
  } | {
    [x: string]: any;
    [x: number]: any;
    [x: symbol]: any;
  }, unknown>;
}, "middleware">>;
//#endregion
//#region src/ratelimit/ratelimit.d.ts
declare class Ratelimit {
  private readonly config;
  static fixedWindow: typeof fixedWindow;
  static slidingWindow: typeof slidingWindow;
  static tokenBucket: typeof tokenBucket;
  private readonly store;
  private readonly prefix;
  private readonly timeout;
  private readonly dynamicLimits;
  private readonly failureMode;
  private readonly enableProtection;
  private readonly denyListThreshold;
  private readonly denyList?;
  private readonly limiter;
  private readonly blockCache?;
  private readonly blockCacheSource?;
  private readonly checkCache;
  constructor(config: RatelimitConfig);
  limit(identifier: string, request?: LimitRequest): Promise<RatelimitResponse>;
  check(identifier: string, request?: CheckRequest): Promise<RatelimitResponse>;
  blockUntilReady(identifier: string, timeoutMs: number): Promise<RatelimitResponse>;
  resetUsedTokens(identifier: string): Promise<void>;
  getRemaining(identifier: string): Promise<RemainingResponse>;
  getValue(identifier: string, options?: {
    sampleShards?: number;
  }): Promise<RatelimitSnapshot>;
  setDynamicLimit(options: {
    limit: number | false;
  }): Promise<void>;
  getDynamicLimit(): Promise<DynamicLimitResponse>;
  hookAPI(options?: HookAPIOptions): {
    getRatelimit: convex_server0.RegisteredQuery<"public", {
      identifier?: string | undefined;
      sampleShards?: number | undefined;
    }, Promise<RatelimitSnapshot>>;
    getServerTime: convex_server0.RegisteredMutation<"public", {}, Promise<number>>;
  };
  private withDb;
  private evaluate;
  private evaluateCandidates;
  private resolveAlgorithm;
  private rawLimit;
  private runWithTimeout;
  private timeoutResponse;
}
//#endregion
//#region src/ratelimit/store/convex-store.d.ts
declare const RATE_LIMIT_STATE_TABLE = "ratelimitState";
declare const RATE_LIMIT_DYNAMIC_TABLE = "ratelimitDynamicLimit";
declare const RATE_LIMIT_HIT_TABLE = "ratelimitProtectionHit";
//#endregion
//#region src/ratelimit/index.d.ts
declare const SECOND = 1000;
declare const MINUTE: number;
declare const HOUR: number;
declare const DAY: number;
declare const WEEK: number;
//#endregion
export { type CheckRequest, type ConvexQueryBuilder, type ConvexRatelimitDbReader, type ConvexRatelimitDbWriter, DAY, type Duration, type DurationString, type DurationUnit, type DynamicLimitResponse, type FixedWindowAlgorithm, HOUR, type HookAPIOptions, type HookCheckValue, type LimitRequest, MINUTE, RATE_LIMIT_DYNAMIC_TABLE, RATE_LIMIT_HIT_TABLE, RATE_LIMIT_STATE_TABLE, Ratelimit, type RatelimitConfig, RatelimitPlugin, type RatelimitPluginOptions, type RatelimitReason, type RatelimitResponse, type RatelimitRow, type RatelimitSnapshot, type RatelimitState, type RemainingResponse, type ResolvedAlgorithm, SECOND, type SlidingWindowAlgorithm, type TokenBucketAlgorithm, WEEK, applyDynamicLimit, calculateRatelimit, fixedWindow, slidingWindow, toMs, tokenBucket };