type-fest
Version:
A collection of essential TypeScript types
97 lines (69 loc) • 3.49 kB
TypeScript
import type {UnwrapBrandedPrimitive} from './unwrap-branded-primitive.d.ts';
import type {NonNegativeInteger} from './numeric.d.ts'; // For `@link`
import type {StringToNumber} from './string-to-number.d.ts'; // For `@link`
import type {Tagged} from './tagged.d.ts'; // For `@link`
/**
A `string` that represents a non-negative integer, like `'42'`.
The underlying string must consist only of the decimal digits `0`-`9`. Leading zeros are allowed, since `'007'` is still a non-negative integer written as a string. A sign, a decimal point, an exponent, a numeric separator, whitespace, a non-ASCII digit, or an empty string is rejected. A union is kept only when every member is valid, so `'1' | 'a'` is rejected. A valid branded string retains its brand.
Use-cases:
- Validate a string that must hold a numeric ID, like a Discord snowflake or a 64-bit integer from an API. A `number` would lose precision above `Number.MAX_SAFE_INTEGER`.
- Validate a zero-padded value from a form field or a JSON response, like `'0930'`, without allowing a sign or a decimal point.
Note: A wide `string` can't be proven to hold only digits, so it is rejected. To accept a value that is only known at runtime, check it at runtime and accept a {@link Tagged} brand next to `NonNegativeIntegerString<Value>`, as in the last example.
@example
```
import type {NonNegativeIntegerString} from 'type-fest';
type A = NonNegativeIntegerString<'42'>;
//=> '42'
type B = NonNegativeIntegerString<'007'>;
//=> '007'
type C = NonNegativeIntegerString<'-1'>;
//=> never
type D = NonNegativeIntegerString<'1.5'>;
//=> never
type E = NonNegativeIntegerString<'1e3'>;
//=> never
type F = NonNegativeIntegerString<' 42'>;
//=> never
type G = NonNegativeIntegerString<string>;
//=> never
```
@example
```
import type {NonNegativeIntegerString} from 'type-fest';
declare function setCount<T extends string>(count: NonNegativeIntegerString<T>): void;
setCount('42');
// @ts-expect-error
setCount('-1');
```
@example
```
import type {NonNegativeIntegerString, Tagged} from 'type-fest';
type UserId = Tagged<string, 'UserId'>;
function isUserId(value: string): value is UserId {
return /^\d+$/v.test(value);
}
declare function getUser<T extends string>(userId: NonNegativeIntegerString<T> | UserId): void;
getUser('42');
declare const input: string;
if (isUserId(input)) {
getUser(input);
}
```
The built-in `${number}` is not enough because it also matches `'-1'`, `'1.5'`, `'1e3'`, `'0x10'`, and `' 42'`, and `${bigint}` also matches `'-1'` and `'0x10'` while rejecting `'007'`. Prefixing the string with `'1'` forces a decimal bigint spelling, so leading zeros are allowed while signs and non-decimal syntax are rejected. This validates the whole string without per-character type recursion. The string is kept as is, so no precision is lost.
@see {@link NonNegativeInteger}
@see {@link StringToNumber}
@category Numeric
@category String
@category Template literal
*/
export type NonNegativeIntegerString<Value extends string> =
// Plain strings need no unwrapping; normalize a branded input once before validating its complete spelling.
(Value extends object ? UnwrapBrandedPrimitive<Value> : Value) extends infer Input extends string
// The prefixed '1' is valid even for an empty input. Include enum values without losing the constraint on generic strings.
? '' extends Input | `${Input}`
? never
: `1${Input}` extends `${bigint}`
? Value
: never
: never;
export {};