⚡ Expressive low-level TypeScript type narrowing for integers, UUIDs, characters, etc.
| 🏋️ No casting necessary | 🚀 Type-narrowing for built-ins |
| 🍃 Zero dependencies | 🔮 0kB (fully erased at build time) |
let age: int = 22;
age = 10.25;
// ^ ❌ tsc(2322): Type '10.25' is not assignable to type 'int'.
let id: uuid = "01964bbf-a8b9-7710-9cea-3d6691b15689";
id = "abc-123";
// ^ ❌ tsc(2322): Type '"abc-123"' is not assignable to type 'uuid<v>'.Tip
Includes overloads and type-narrowing for built-ins like Math, Array, Date, Number, TypedArrays, and more.
Add package:
npm install primitive-types --save-devAdd types in tsconfig.json:
{
"compilerOptions": {
"types": [
"primitive-types"
]
}
}| type | Description | Method | Base type | |
|---|---|---|---|---|
| ✅ | uint8 | Any 8-bit unsigned integer (0 to 255). | Union type | number |
| ✅ | uint16 | Any 16-bit unsigned integer (0 to 65,535). | Union type | number |
| ✅* | uint32 or uint | Any 32-bit unsigned integer (0 to 4,294,967,295). |
Union type
|
number |
| ✅ | int8 | Any 8-bit signed integer (-128 to 127). | Union type | number |
| ✅ | int16 | Any 16-bit signed integer (-32,768 to 32,767). | Union type | number |
| ✅* | int32 or int | Any 32-bit signed integer (-2,147,483,648 to 2,147,483,647). |
Union type
|
number |
| ✅ | bit8 | Any individual 8-bit bitmask value (e.g. 1, 2, 4, 8, …). | Union type | number |
| ✅ | bit16 | Any individual 16-bit bitmask value (e.g. 1, 2, …, 256, 512, …). | Union type | number |
| ✅ | bit32 or bit | Any individual 32-bit bitmask value, excluding the int32 sign bit (e.g. 1, 2, …, 16777216, …). | Union type | number |
| ✅ | bit32_unsafe | Any individual 32-bit bitmask value, including the int32 sign bit (e.g. 1, 2, …, -2147483648). | Union type | number |
| ✅ | bitfield | Alias for 0b01111111111111111111111111111111 (or 2147483647). |
Alias | 2147483647 |
| ✅ | bitfield_unsafe | Alias for 0b11111111111111111111111111111111 (or -1). |
Alias | -1 |
| ✅ | float32 or float | Any 32-bit single-precision floating-point number. | Alias | number |
| ✅ | float64 or double | Any 64-bit single-precision floating-point number. | Alias | number |
| ✅ | char8 | Any ASCII range character (e.g. 'e', '3'). |
Union type | string |
| ✅ | char16 | Any UTF-16 range character (e.g. 'ѐ', '϶'). |
Union type | string |
| ✅ | str8 | Any string containing up to 1 byte. | Template literal type | string |
| ✅ | str16 | Any string containing up to 2 bytes. | Template literal type | |
| ✅ | uuid | Any UUID (e.g. "0196382e-cc57-43ce-88c7-a3e427bc2713").Strict UUID versions may be enforced using generics (e.g. uuid<4>). |
Template literal type | string |
| ✅ | hex | A single hexadecimal character (e.g. '0', '5', 'a', 'A'). |
Union type | string |
| ✅ | octet or bytestr | A 1-byte hexadecimal string representation (e.g. "00", "cb", "F7"). |
Template literal type | string |
| ✅ | byte | Any 1-byte integer or string (ASCII characters, code units in the UTF-8 character encoding). | Template literal type | number | string |
| ✅ | ubyte | Any 1-byte unsigned integer or string (ASCII characters, code units in the UTF-8 character encoding). | Template literal type | number | string |
| ✅ | word | Any 2-byte integer or string (UCS-2 characters, code units in the UTF-16 character encoding). | Template literal type | number | string |
| ✅ | uword | Any 2-byte unsigned integer or string (UCS-2 characters, code units in the UTF-16 character encoding). | Template literal type | number | string |
In JavaScript all numbers are stored as 64-bit floating-point numbers or a 32-bit
integers, and then represented as the dynamic number type.
The benefit of these opaque types is arithemetic is completely interchangable:
let a: uint8 = 10;
let b: int16 = -21_374;
let c: float64 = 4274.80;
let result = a * b / c;
// -50And in-place arithmetic will naturally coerce variables to the number type too:
function isOver18(value: int8) {
return value >= 18;
}
let age: int8 = 125;
isOver18(age)
age *= 2;
// 'age' is coerced to 'number'
isOver18(age);
// ^ ❌ tsc(2345): Argument of type 'number' is not assignable to parameter of type 'int8'.