Quick Start

Get up and running with hitlimit in under 5 minutes.

Basic Usage

The simplest way to add rate limiting to your Express app:

app.ts
import express from 'express'
import { hitlimit } from '@joint-ops/hitlimit'

const app = express()

// 100 requests per minute per IP
app.use(hitlimit({ limit: 100, window: '1m' }))

app.get('/api/data', (req, res) => {
  res.json({ message: 'Hello World!' })
})

app.listen(3000)

Time Windows

Use human-readable time strings:

hitlimit({ limit: 100, window: '1m' })   // 100 per minute
hitlimit({ limit: 1000, window: '1h' })  // 1000 per hour
hitlimit({ limit: 10000, window: '1d' }) // 10000 per day

Custom Key

Rate limit by user ID, API key, or any identifier:

// By user ID
hitlimit({
  limit: 100,
  window: '1m',
  key: (req) => req.user?.id || req.ip
})

Using Stores

Choose the right store for your use case:

import { hitlimit, memoryStore } from '@joint-ops/hitlimit'
import { sqliteStore } from '@joint-ops/hitlimit/stores/sqlite'

// Memory (default, single instance)
hitlimit({ limit: 100, window: '1m' })

// SQLite (persistent)
hitlimit({
  limit: 100,
  window: '1m',
  store: sqliteStore({ path: './rate-limits.db' })
})

Response Headers

hitlimit automatically adds rate limit headers:

RateLimit-Limit: 100
RateLimit-Remaining: 73
RateLimit-Reset: 1640000000
Retry-After: 27  (only when rate limited)

Next Steps