Cloud

Quota Management

Per-tenant resource usage tracking and limit enforcement with daily, calendar-month, and lifetime periods plus warning and exceeded events.

3 min readUpdated DocumentationEdit this page
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

TypeScript
TS
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.

TypeScript
TS
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.

TypeScript
TS
if (!quotas.check('acme-corp', 'api_calls')) {
  // Quota exhausted: block the request
}

Usage Reports

TypeScript
TS
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

TypeScript
TS
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

MetricDescription
api_callsNumber of API requests
storage_bytesStorage consumption
usersNumber of user accounts
projectsNumber of projects
customAny custom metric

Periods

PeriodRollover
daily24 hours after the period started (rolling)
monthlyAt 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?

Help improve the documentation

AxilJS is open source and documentation improvements are welcome.

AxilJS DocumentationMIT License · Built by SyntaxilitY