rate-limiter.schemas

(no submodules)

Purpose

Provides Zod v4 validation schemas for all configuration objects in @suaveplan/rate-limiter. These schemas enable runtime validation of user-supplied configuration, safe parsing of stored state from external sources, and documentation of valid value ranges. They are tree-shakeable — import only the schemas you need.

Non-serialisable fields (clock, bus, logger, storage) are intentionally omitted from RateLimiterOptionsSchema since they cannot be represented in Zod.

Features

RateLimitConfigSchema — validates limit, window, optional id and description
RateLimitConditionSchema — validates five-operator condition objects
RateLimitRuleSchema — extends config with priority, conditions, bypass
RateLimitContextSchema — validates per-request context objects
RateLimiterOptionsSchema — partial options schema for serialisable fields
TokenBucketOptionsSchema, SlidingWindowOptionsSchema, FixedWindowOptionsSchema — algorithm options
MemoryStorageOptionsSchema — storage options

Usage: Basic Example

import { RateLimitConfigSchema } from "@suaveplan/rate-limiter/schemas";

const result = RateLimitConfigSchema.safeParse({ limit: 100, window: 60_000 });
if (!result.success) {
  console.error(result.error.issues);
}

Usage: Advanced Example

import {
  RateLimiterOptionsSchema,
  RateLimitRuleSchema,
} from "@suaveplan/rate-limiter/schemas";

const raw = JSON.parse(configJson);
const opts = RateLimiterOptionsSchema.parse(raw);

// Validate individual rules from an API payload:
const rules = z.array(RateLimitRuleSchema).parse(payload.rules);

API Reference

Schema	Validates
`RateLimitConfigSchema`	`{ limit, window, id?, description? }`
`RateLimitConditionSchema`	`{ field, operator, value }`
`RateLimitRuleSchema`	`RateLimitConfig + { priority?, conditions?, bypass? }`
`RateLimitContextSchema`	`{ key, tenantId?, userId?, ip?, path?, method?, metadata? }`
`RateLimiterOptionsSchema`	Serialisable subset of `RateLimiterOptions`
`TokenBucketOptionsSchema`	`{ capacity, refillRate, initialTokens? }`
`SlidingWindowOptionsSchema`	`{ limit, windowMs }`
`FixedWindowOptionsSchema`	`{ limit, windowMs }`
`MemoryStorageOptionsSchema`	`{ maxSize? }`

Implementation Notes

z.record(z.string(), z.unknown()) is used for metadata and tenantMultipliers fields, which requires both key and value type arguments in Zod v4. All integer fields use .int() to prevent floating-point surprises in window calculations.

2.6 KiB Raw Blame History