https://github.com/reececomo/primitive-types
Expressive low-level TypeScript types for integers, UUIDs, characters, etc.
https://github.com/reececomo/primitive-types
Last synced: 5 months ago
JSON representation
Expressive low-level TypeScript types for integers, UUIDs, characters, etc.
- Host: GitHub
- URL: https://github.com/reececomo/primitive-types
- Owner: reececomo
- License: mit
- Created: 2025-04-15T09:05:11.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-04-20T08:47:11.000Z (about 1 year ago)
- Last Synced: 2025-09-23T17:17:20.785Z (9 months ago)
- Homepage: https://npmjs.com/primitive-types
- Size: 323 KB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 🔌 primitive-types [](https://www.npmjs.com/package/primitive-types) [](https://bundlephobia.com/package/primitive-types) [](https://www.npmjs.com/package/primitive-types) [](https://github.com/reececomo/primitive-types/blob/main/LICENSE)
⚡ 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) |
```ts
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'.
```
> [!TIP]
> Includes overloads and type-narrowing for built-ins like Math, Array, Date,
> Number, TypedArrays, and more.
## 💿 Install
Add package:
```sh
npm install primitive-types --save-dev
```
Add types in `tsconfig.json`:
```json
{
"compilerOptions": {
"types": [
"primitive-types"
]
}
}
```
## 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
⚠️ *partial constants support beyond `uint16` range.
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
⚠️ *partial constants support beyond `int16` range.
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
string
✅
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
## Arithmetic operations
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:
```ts
let a: uint8 = 10;
let b: int16 = -21_374;
let c: float64 = 4274.80;
let result = a * b / c;
// -50
```
And in-place arithmetic will naturally coerce variables to the `number` type too:
```ts
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'.
```