Types

TypeScript types for rate limiting

This page documents all exported TypeScript types for the Convex Rate Limiter.

RateLimitConfig

A union type representing the configuration for a rate limit. Can be either a token bucket or fixed window configuration.

type RateLimitConfig =
  | Infer<typeof tokenBucketValidator>
  | Infer<typeof fixedWindowValidator>;

Token Bucket Configuration

A token bucket limits the rate of requests by continuously adding tokens to be consumed when servicing requests.

{
  kind: "token bucket",
  rate: number,
  period: number,
  capacity?: number,
  maxReserved?: number,
  shards?: number,
  start?: null
}

Show Properties

kind · literal · required

Must be "token bucket"

rate · number · required

The number of tokens added per period

period · number · required

The time period in milliseconds over which tokens are added

capacity · number

The maximum number of tokens that can accumulate. Defaults to rate if not specified.

maxReserved · number

The maximum number of tokens that can be reserved ahead of time

shards · number

The number of shards to distribute the rate limit across for better performance

start · null

Optional start time (always null for token bucket)

Example:

const config: RateLimitConfig = {
  kind: "token bucket",
  rate: 10,
  period: MINUTE,
  capacity: 20
};

Fixed Window Configuration

A fixed window rate limit adds a set number of tokens at the start of each fixed window of time.

{
  kind: "fixed window",
  rate: number,
  period: number,
  capacity?: number,
  maxReserved?: number,
  shards?: number,
  start?: number
}

Show Properties

kind · literal · required

Must be "fixed window"

rate · number · required

The number of tokens added at the start of each window

period · number · required

The window duration in milliseconds

capacity · number

The maximum number of tokens that can accumulate. Defaults to rate if not specified.

maxReserved · number

The maximum number of tokens that can be reserved ahead of time

shards · number

The number of shards to distribute the rate limit across for better performance

start · number

Determines what the windows are relative to in UTC time. If not provided, it will be a random number between 0 and period.

Example:

const config: RateLimitConfig = {
  kind: "fixed window",
  rate: 100,
  period: HOUR,
  start: 0
};

---

RateLimitArgs

Arguments for rate limiting operations.

type RateLimitArgs = {
  /** The name of the rate limit. */
  name: string;
  /** The key to use for the rate limit. If not provided, the rate limit
   * is a single shared value.  */
  key?: string;
  /**  The number of tokens to consume. Defaults to 1. */
  count?: number;
  /**  Whether to reserve the tokens ahead of time. Defaults to false. */
  reserve?: boolean;
  /**  Whether to throw an error if the rate limit is exceeded.
   * By default, check/consume will just return { ok: false, retryAfter: number }.
   */
  throws?: boolean;
  /** The rate limit configuration. See {@link RateLimitConfig}. */
  config: RateLimitConfig;
};

Show Properties

name · string · required

The name of the rate limit

key · string

The key to use for the rate limit. If not provided, the rate limit is a single shared value.

count · number

The number of tokens to consume. Defaults to 1.

reserve · boolean

Whether to reserve the tokens ahead of time. Defaults to false.

throws · boolean

Whether to throw an error if the rate limit is exceeded. By default, check/consume will just return { ok: false, retryAfter: number }.

config · RateLimitConfig · required

The rate limit configuration. See RateLimitConfig.

Example:

const args: RateLimitArgs = {
  name: "sendMessage",
  key: userId,
  count: 1,
  throws: true,
  config: {
    kind: "token bucket",
    rate: 10,
    period: MINUTE
  }
};

---

RateLimitReturns

Return value from rate limiting operations.

type RateLimitReturns = 
  | {
      ok: true,
      retryAfter?: number
    }
  | {
      ok: false,
      retryAfter: number
    };

Show Success Response

ok · true · required

Indicates the request is allowed

retryAfter · number

Optional duration in milliseconds to wait before executing reserved work. Only present when using reserve: true.

Show Failure Response

ok · false · required

Indicates the rate limit was exceeded

retryAfter · number · required

Duration in milliseconds when retrying could succeed

Example:

const result = await rateLimiter.limit(ctx, "sendMessage", { key: userId });

if (result.ok) {
  // Request allowed
  if (result.retryAfter) {
    // For reserved tokens, schedule work
    await ctx.scheduler.runAfter(result.retryAfter, internal.sendMessage, {...});
  }
} else {
  // Rate limited - retry after result.retryAfter ms
  console.log(`Rate limited. Retry after ${result.retryAfter}ms`);
}

---

RateLimitError

Error type thrown when throws: true is used and the rate limit is exceeded.

type RateLimitError = {
  kind: "RateLimited";
  name: string;
  retryAfter: number;
};

kind · literal · required

Always "RateLimited" to identify this error type

name · string · required

The name of the rate limit that was exceeded

retryAfter · number · required

Duration in milliseconds when retrying could succeed

Example:

import { isRateLimitError } from "@convex-dev/rate-limiter";

try {
  await rateLimiter.limit(ctx, "sendMessage", { 
    key: userId, 
    throws: true 
  });
} catch (error) {
  if (isRateLimitError(error)) {
    console.log(`Rate limited on ${error.data.name}`);
    console.log(`Retry after ${error.data.retryAfter}ms`);
  }
}

---

GetValueArgs

Arguments for getting the current value of a rate limit.

type GetValueArgs = {
  name?: string;
  key?: string;
  sampleShards?: number;
  config?: RateLimitConfig;
};

name · string

The name of the rate limit

key · string

The key to check. If not provided, checks the shared value.

sampleShards · number

The number of shards to sample when checking the value

config · RateLimitConfig

The rate limit configuration if not using a pre-defined limit

Example:

const value = await rateLimiter.getValue(ctx, "sendMessage", {
  key: userId,
  sampleShards: 1
});

---

GetValueReturns

Return value from getting the current rate limit value.

type GetValueReturns = {
  value: number;
  ts: number;
  shard: number;
  config: RateLimitConfig;
};

value · number · required

The current number of available tokens

ts · number · required

The timestamp of the last update (in milliseconds)

shard · number · required

The shard number that was sampled

config · RateLimitConfig · required

The rate limit configuration

Example:

const { value, ts, shard, config } = await rateLimiter.getValue(
  ctx, 
  "sendMessage", 
  { key: userId }
);

console.log(`${value} tokens available at ${new Date(ts)}`);

---

Validators

Convex validators for rate limit configurations.

tokenBucketValidator

const tokenBucketValidator = v.object({
  kind: v.literal("token bucket"),
  rate: v.number(),
  period: v.number(),
  capacity: v.optional(v.number()),
  maxReserved: v.optional(v.number()),
  shards: v.optional(v.number()),
  start: v.optional(v.null()),
});

Convex validator for token bucket configurations. Use with Infer<typeof tokenBucketValidator> to get the TypeScript type.

fixedWindowValidator

const fixedWindowValidator = v.object({
  kind: v.literal("fixed window"),
  rate: v.number(),
  period: v.number(),
  capacity: v.optional(v.number()),
  maxReserved: v.optional(v.number()),
  shards: v.optional(v.number()),
  start: v.optional(v.number()),
});

Convex validator for fixed window configurations. Use with Infer<typeof fixedWindowValidator> to get the TypeScript type.

---

Context Types

Context types used by the RateLimiter methods to specify which Convex operations are available.

RunQueryCtx

A context that provides access to runQuery. Used by non-mutating operations like check() and getValue().

type RunQueryCtx = {
  runQuery: <Query extends FunctionReference<"query", "internal">>(
    query: Query,
    args: FunctionArgs<Query>,
  ) => Promise<FunctionReturnType<Query>>;
};

Example:

// Any Convex query or mutation context works
export const checkLimit = query({
  handler: async (ctx, args) => {
    // ctx implements RunQueryCtx
    const status = await rateLimiter.check(ctx, "myLimit");
    return status;
  }
});

RunMutationCtx

A context that extends RunQueryCtx and provides access to both runQuery and runMutation. Used by mutating operations like limit() and reset().

type RunMutationCtx = RunQueryCtx & {
  runMutation: <Mutation extends FunctionReference<"mutation", "internal">>(
    mutation: Mutation,
    args: FunctionArgs<Mutation>,
  ) => Promise<FunctionReturnType<Mutation>>;
};

Example:

// Any Convex mutation context works
export const sendMessage = mutation({
  handler: async (ctx, args) => {
    // ctx implements RunMutationCtx
    await rateLimiter.limit(ctx, "sendMessage", { key: userId });
    // ... rest of logic
  }
});

These types are satisfied by the standard Convex QueryCtx and MutationCtx types, so you typically don’t need to reference them directly. They’re used internally to ensure type safety.