Quota Management
Per-tenant resource usage tracking and limit enforcement with daily, calendar-month, and lifetime periods plus warning and exceeded events.
On this page8
Overview
QuotaManager tracks per-tenant resource consumption in memory and enforces
configurable limits with automatic period rollover. It emits warning and
exceeded events on the global event bus from @axiljs/events.
Configuration
1import { quotas } from '@axiljs/cloud'
2
3quotas.configure({
4 tenantId: 'acme-corp',
5 limits: [
6 { metric: 'api_calls', max: 100_000, period: 'monthly' },
7 { metric: 'storage_bytes', max: 5_000_000_000, period: 'lifetime' },
8 { metric: 'users', max: 500, period: 'lifetime' },
9 ],
10})quotas is a shared instance; new QuotaManager() creates an isolated one.
Tenants or metrics with no configured limit are unlimited: increment() and
check() return true.
Tracking Usage
increment(tenantId, metric, amount = 1) adds to the counter and returns true
while usage is at or below max, false once it goes over. The amount is
recorded either way.
1const allowed = quotas.increment('acme-corp', 'api_calls')
2
3if (!allowed) {
4 res.status(429).json({ error: 'API quota exceeded' })
5 return
6}Checking Without Incrementing
check(tenantId, metric) returns true while current usage is below max.
if (!quotas.check('acme-corp', 'api_calls')) {
// Quota exhausted: block the request
}Usage Reports
1const usage = quotas.getUsage('acme-corp')
2// [
3// { metric: 'api_calls', current: 45200, limit: 100000, period: 'monthly',
4// resetAt: '2026-12-01T00:00:00.000Z', percentUsed: 45 },
5// { metric: 'users', current: 120, limit: 500, period: 'lifetime',
6// resetAt: undefined, percentUsed: 24 },
7// ]getUsage() returns [] for a tenant with no configuration. resetAt is set
only for daily and monthly limits that have recorded usage.
Event Notifications
1import { getGlobalEventBus } from '@axiljs/events'
2
3// Emitted on each increment that leaves usage at 90% or more of max (but not over)
4getGlobalEventBus().on('quota.warning', ({ tenantId, metric, current, limit, percentUsed }) => {
5 notifyAdmin(`${tenantId} is at ${percentUsed}% of ${metric}`)
6})
7
8// Emitted on each increment that takes usage over max
9getGlobalEventBus().on('quota.exceeded', ({ tenantId, metric, current, limit, period }) => {
10 alertTeam(`${tenantId} exceeded ${metric}: ${current}/${limit}`)
11})Supported Metrics
| Metric | Description |
|---|---|
api_calls | Number of API requests |
storage_bytes | Storage consumption |
users | Number of user accounts |
projects | Number of projects |
custom | Any custom metric |
Periods
| Period | Rollover |
|---|---|
daily | 24 hours after the period started (rolling) |
monthly | At 00:00 UTC on the first day of the next calendar month |
lifetime (default) | Never resets |
Note
monthly follows the calendar month in UTC. Older docs described it as a
rolling 30 days; usage recorded on 31 January resets on 1 February, and usage
recorded on 1 March is not reset on 31 March.
Was this page helpful?