number()
Creates a validator that accepts number values. Also accepts numeric strings (coerces to number).
Signature
function number(): NumberValidatorAccepted Values
| Input | Result | Notes |
|---|---|---|
42 | ✅ 42 | Actual number |
"42" | ✅ 42 | Numeric string, coerced |
"3.14" | ✅ 3.14 | Float string, coerced |
"" | ❌ Type error | Empty string |
"abc" | ❌ Type error | Non-numeric |
NaN | ❌ Invalid | Non-finite |
Infinity | ❌ Invalid | Non-finite |
true | ❌ Type error | Boolean |
null | ❌ Type error | Not a number |
Refinements
.int()
Requires the number to be an integer:
const env = defineEnv({
MAX_CONNECTIONS: number().int(),
})
// ✅ 10
// ❌ 10.5
// ❌ "10.5".positive()
Requires the number to be greater than zero:
const env = defineEnv({
RATE_LIMIT: number().positive(),
})
// ✅ 1
// ✅ 100
// ❌ 0
// ❌ -5.port()
Requires the number to be a valid port (1-65535, integer):
const env = defineEnv({
PORT: number().port(),
})
// ✅ 3000
// ✅ 65535
// ❌ 0
// ❌ 70000
// ❌ 3000.5.min(value)
Requires the number to be greater than or equal to value:
const env = defineEnv({
WORKERS: number().min(1),
})
// ✅ 1
// ✅ 4
// ❌ 0.max(value)
Requires the number to be less than or equal to value:
const env = defineEnv({
TIMEOUT: number().max(30000),
})
// ✅ 5000
// ✅ 30000
// ❌ 35000Chaining
number().int().positive().min(1).max(100).default(50)
number().port()
number().min(0).optional()Examples
Basic number
const env = defineEnv({
MAX_RETRIES: number().int().min(0).max(10).default(3),
})
// env.MAX_RETRIES: number (default: 3)Number with coercion
const env = defineEnv({
PORT: number().port(),
})
// With process.env.PORT = "4000"
// env.PORT → 4000 (coerced from "4000")Optional number
const env = defineEnv({
CACHE_TTL: number().positive().optional(),
})
// env.CACHE_TTL: number | undefined