0
# Basic Types
1

2
Core TypeScript utility types providing strict alternatives to built-in utilities and essential building blocks for type manipulation.
3

4
## Capabilities
5

6
### Primitive
7

8
Matches any primitive value type including all JavaScript primitive types.
9

10
```typescript { .api }
11
type Primitive = string | number | boolean | bigint | symbol | undefined | null;
12
```
13

14
**Usage Example:**
15

16
```typescript
17
import type { Primitive } from "ts-essentials";
18

19
function isPrimitive(value: unknown): value is Primitive {
20
  return value !== Object(value);
21
}
22

23
type Config = {
24
  [key: string]: Primitive | Primitive[];
25
};
26
```
27

28
### Builtin
29

30
Matches primitive, function, date, error, or regular expression types.
31

32
```typescript { .api }
33
type Builtin = Primitive | Function | Date | Error | RegExp;
34
```
35

36
### KeyofBase
37

38
A `keyofStringsOnly`-tolerant analogue for `PropertyKey`, used as a base type for object keys.
39

40
```typescript { .api }
41
type KeyofBase = string | number | symbol;
42
```
43

44
### Prettify
45

46
Flattens type definitions to make them more readable in IDE hover tooltips and error messages.
47

48
```typescript { .api }
49
type Prettify<Type> = Type extends Function
50
  ? Type
51
  : Extract<
52
      {
53
        [Key in keyof Type]: Type[Key];
54
      },
55
      Type
56
    >;
57
```
58

59
**Usage Example:**
60

61
```typescript
62
import type { Prettify, Merge } from "ts-essentials";
63

64
type User = { id: number; name: string; };
65
type Settings = { theme: string; lang: string; };
66

67
// Without Prettify: complex intersection type display
68
type UserSettings = User & Settings;
69

70
// With Prettify: clean, flat type display
71
type CleanUserSettings = Prettify<Merge<User, Settings>>;
72
// Result: { id: number; name: string; theme: string; lang: string; }
73
```
74

75
### StrictExclude
76

77
Constructs a type by excluding from `UnionType` all union members that are assignable to `ExcludedMembers`. This is a stricter version of TypeScript's built-in `Exclude`.
78

79
```typescript { .api }
80
type StrictExclude<UnionType, ExcludedMembers> = UnionType extends ExcludedMembers
81
  ? never
82
  : UnionType;
83
```
84

85
**Usage Example:**
86

87
```typescript
88
import type { StrictExclude } from "ts-essentials";
89

90
type Colors = "red" | "green" | "blue" | "yellow";
91
type PrimaryColors = StrictExclude<Colors, "yellow">;
92
// Result: "red" | "green" | "blue"
93
```
94

95
### StrictExtract
96

97
Constructs a type by extracting from `Type` all union members that are assignable to `Union`. This is a stricter version of TypeScript's built-in `Extract`.
98

99
```typescript { .api }
100
type StrictExtract<Type, Union> = Type extends Union ? Type : never;
101
```
102

103
**Usage Example:**
104

105
```typescript
106
import type { StrictExtract } from "ts-essentials";
107

108
type AllEvents = "click" | "hover" | "focus" | "scroll";
109
type MouseEvents = StrictExtract<AllEvents, "click" | "hover">;
110
// Result: "click" | "hover"
111
```
112

113
### StrictOmit
114

115
Constructs a type by picking all properties from `Type` and then removing `Keys`. This is a stricter version of TypeScript's built-in `Omit` that prevents omitting from array types.
116

117
```typescript { .api }
118
type StrictOmit<Type extends Record<string | number | symbol, any>, Keys extends keyof Type> = 
119
  Type extends Array<any> ? never : Omit<Type, Keys>;
120
```
121

122
**Usage Example:**
123

124
```typescript
125
import type { StrictOmit } from "ts-essentials";
126

127
type User = {
128
  id: number;
129
  name: string;
130
  email: string;
131
  password: string;
132
};
133

134
type PublicUser = StrictOmit<User, "password" | "email">;
135
// Result: { id: number; name: string; }
136

137
// This would cause a compile error (preventing array omission):
138
// type InvalidArray = StrictOmit<string[], "length">; // never
139
```
140

141
### Writable
142

143
Constructs a type with all `readonly` properties of `Type` converted to mutable, meaning the properties can be reassigned.
144

145
```typescript { .api }
146
type Writable<Type> = {
147
  -readonly [Key in keyof Type]: Type[Key];
148
};
149
```
150

151
**Usage Example:**
152

153
```typescript
154
import type { Writable } from "ts-essentials";
155

156
type ReadonlyUser = {
157
  readonly id: number;
158
  readonly name: string;
159
  email: string;
160
};
161

162
type MutableUser = Writable<ReadonlyUser>;
163
// Result: { id: number; name: string; email: string; }
164

165
const user: MutableUser = { id: 1, name: "Alice", email: "alice@example.com" };
166
user.id = 2; // OK - no longer readonly
167
user.name = "Bob"; // OK - no longer readonly
168
```
169

170
### Awaited
171

172
A re-export of TypeScript's built-in `Awaited` utility type for recursively unwrapping Promise types.
173

174
```typescript { .api }
175
/** @deprecated Use built-in Awaited instead */
176
type Awaited<Type> = Type extends PromiseLike<infer Value> ? Value : never;
177
```
178

179
**Usage Example:**
180

181
```typescript
182
import type { Awaited } from "ts-essentials";
183

184
// Use built-in Awaited instead
185
type Result = Awaited<Promise<string>>; // string
186
type NestedResult = Awaited<Promise<Promise<number>>>; // number
187
```
188

189