hitlimit() Function

The main function to create rate limiting middleware.

Function Signature

function hitlimit(options: HitlimitOptions): Middleware

Parameters

Parameter	Type	Required	Description
`options`	HitlimitOptions	Yes	Configuration object

Options Object

Property	Type	Default	Description
`limit`	number	100	Max requests per window
`window`	string \| number	'1m'	Time window duration
`key`	(req) => string	req.ip	Key extraction function
`store`	Store	memoryStore()	Storage backend
`skip`	(req) => boolean	undefined	Skip rate limiting
`headers`	boolean	true	Include rate limit headers
`statusCode`	number	429	Status code when limited
`response`	object \| function	-	Custom error response

Return Value

Returns a middleware function compatible with Express, Hono, and other frameworks.

type Middleware = (req: Request, res: Response, next: NextFunction) => void

Basic Example

import { hitlimit } from '@joint-ops/hitlimit'

// 100 requests per minute
const limiter = hitlimit({
  limit: 100,
  window: '1m'
})

Advanced Example

import { hitlimit } from '@joint-ops/hitlimit'
import { redisStore } from '@joint-ops/hitlimit/stores/redis'

const limiter = hitlimit({
  limit: 1000,
  window: '1h',
  key: (req) => req.headers['x-api-key'] || req.ip,
  store: redisStore({ url: 'redis://localhost:6379' }),
  skip: (req) => req.path === '/health',
  headers: true,
  statusCode: 429,
  response: (req, res) => ({
    error: 'Rate limit exceeded',
    retryAfter: res.getHeader('Retry-After')
  })
})

Error Handling

When rate limited, the middleware responds with:

HTTP/1.1 429 Too Many Requests
RateLimit-Limit: 100
RateLimit-Remaining: 0
RateLimit-Reset: 1640000060
Retry-After: 60

{ "error": "Too Many Requests" }