0
# ts-essentials
1

2
ts-essentials is a comprehensive collection of essential TypeScript utility types that enhance type safety and developer productivity. It provides over 70 carefully crafted utility types organized into categories such as basic types, utility types, mark wrapper types, deep wrapper types, and more.
3

4
## Package Information
5

6
- **Package Name**: ts-essentials
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install --save-dev ts-essentials`
10
- **TypeScript Version**: >=4.5.0 required
11
- **Requirements**: strictNullChecks must be enabled
12

13
## Core Imports
14

15
```typescript
16
import type { Prettify, StrictOmit, DeepPartial, NonEmptyArray, CamelCase, DeepCamelCaseProperties } from "ts-essentials";
17
```
18

19
For CommonJS:
20

21
```javascript
22
const { Prettify, StrictOmit, DeepPartial, NonEmptyArray, CamelCase, DeepCamelCaseProperties } = require("ts-essentials");
23
```
24

25
All types are imported directly from the main module - no need for deep imports.
26

27
## Basic Usage
28

29
```typescript
30
import type { 
31
  Prettify, 
32
  StrictOmit, 
33
  Merge, 
34
  DeepPartial, 
35
  NonEmptyArray,
36
  Opaque 
37
} from "ts-essentials";
38

39
// Basic type manipulation
40
type User = { id: number; name: string; email: string; };
41
type PublicUser = StrictOmit<User, "email">; // { id: number; name: string; }
42

43
// Merging types
44
type Settings = { theme: string; };
45
type UserWithSettings = Merge<User, Settings>; // Combined type
46

47
// Deep operations
48
type PartialUser = DeepPartial<User>; // All properties optional recursively
49

50
// Array constraints
51
type UserList = NonEmptyArray<User>; // Array with at least one User
52

53
// Branded types
54
type UserId = Opaque<number, "UserId">;
55
const userId: UserId = 123 as UserId;
56

57
// Case transformations
58
type ApiField = CamelCase<"user_name">; // "userName"
59
type TransformedApi = DeepCamelCaseProperties<{ user_id: number; user_name: string; }>; 
60
// { userId: number; userName: string; }
61
```
62

63
## Architecture
64

65
ts-essentials is organized into logical categories of type utilities:
66

67
- **Basic Types**: Core building blocks like `Primitive`, `Prettify`, and strict versions of built-in utilities
68
- **Utility Types**: Advanced type operations for objects, unions, and transformations  
69
- **Mark Wrapper Types**: Modify specific properties (optional, readonly, required, writable)
70
- **Deep Wrapper Types**: Recursive type transformations that work on nested structures
71
- **Key Types**: Extract and work with object property keys
72
- **Type Checkers**: Conditional types for type validation and detection
73
- **Array & Tuple Types**: Specialized types for array and tuple operations
74
- **Change Case Types**: String case transformation utilities for different naming conventions
75
- **Function Types**: Type utilities for function signatures and predicates  
76
- **Utility Functions**: Runtime functions that complement the type system
77

78
## Capabilities
79

80
### Basic Types
81

82
Core TypeScript utility types providing strict alternatives to built-in utilities and essential building blocks.
83

84
```typescript { .api }
85
type Primitive = string | number | boolean | bigint | symbol | undefined | null;
86
type Prettify<Type> = Type extends Function ? Type : { [Key in keyof Type]: Type[Key] };
87
type StrictOmit<Type extends Record<string | number | symbol, any>, Keys extends keyof Type> = 
88
  Type extends Array<any> ? never : Omit<Type, Keys>;
89
/** @deprecated Use built-in Awaited instead */
90
type Awaited<Type> = Type extends PromiseLike<infer Value> ? Value : never;
91
```
92

93
[Basic Types](./basic-types.md)
94

95
### Utility Types  
96

97
Advanced type operations for merging, transforming, and manipulating complex type structures.
98

99
```typescript { .api }
100
type Dictionary<Type, Keys extends KeyofBase = string> = { [key in Keys]: Type };
101
type Merge<Object1, Object2> = Prettify<Omit<Object1, keyof Object2> & Object2>;
102
type Opaque<Type, Token> = Type & { readonly __opaque__: Token };
103
```
104

105
[Utility Types](./utility-types.md)
106

107
### Mark Wrapper Types
108

109
Transform specific properties of objects by changing their modifiers (optional, readonly, required, writable).
110

111
```typescript { .api }
112
type MarkOptional<Type, Keys extends keyof Type> = Prettify<Omit<Type, Keys> & Partial<Pick<Type, Keys>>>;
113
type MarkRequired<Type, Keys extends keyof Type> = Prettify<Omit<Type, Keys> & Required<Pick<Type, Keys>>>;
114
```
115

116
[Mark Wrapper Types](./mark-wrapper-types.md)
117

118
### Deep Wrapper Types
119

120
Recursive type transformations that apply operations to nested object structures at any depth.
121

122
```typescript { .api }
123
type DeepPartial<Type> = Type extends Function 
124
  ? Type 
125
  : Type extends Array<infer U> 
126
    ? Array<DeepPartial<U>>
127
    : Type extends ReadonlyArray<infer U>
128
      ? ReadonlyArray<DeepPartial<U>>
129
      : { [K in keyof Type]?: DeepPartial<Type[K]> };
130

131
type DeepReadonly<Type> = Type extends Function
132
  ? Type
133
  : Type extends Array<infer U>
134
    ? ReadonlyArray<DeepReadonly<U>>
135
    : { readonly [K in keyof Type]: DeepReadonly<Type[K]> };
136
```
137

138
[Deep Wrapper Types](./deep-wrapper-types.md)
139

140
### Key Types
141

142
Extract and work with object property keys based on their characteristics (optional, required, readonly, writable).
143

144
```typescript { .api }
145
type OptionalKeys<Type> = { [K in keyof Type]-?: {} extends Pick<Type, K> ? K : never }[keyof Type];
146
type RequiredKeys<Type> = { [K in keyof Type]-?: {} extends Pick<Type, K> ? never : K }[keyof Type];
147
```
148

149
[Key Types](./key-types.md)
150

151
### Type Checkers
152

153
Conditional types for runtime type validation and compile-time type detection.
154

155
```typescript { .api }
156
type IsAny<Type> = 0 extends 1 & Type ? true : false;
157
type IsNever<Type> = [Type] extends [never] ? true : false;
158
type Exact<Type, Shape> = [Type] extends [Shape] ? [Shape] extends [Type] ? Type : never : never;
159
```
160

161
[Type Checkers](./type-checkers.md)
162

163
### Array & Tuple Types
164

165
Specialized types for working with arrays, tuples, and array-like structures with type safety.
166

167
```typescript { .api }
168
type NonEmptyArray<Type> = [Type, ...Type[]];
169
type ElementOf<Type> = Type extends ReadonlyArray<infer U> ? U : never;
170
type Head<Type extends ReadonlyArray<any>> = Type extends readonly [infer H, ...any[]] ? H : never;
171
```
172

173
[Array & Tuple Types](./array-tuple-types.md)
174

175
### Change Case Types
176

177
String case transformation utilities for converting between different naming conventions at the type level.
178

179
```typescript { .api }
180
type CamelCase<Type> = Type extends string ? /* converts any case to camelCase */ : Type;
181
type DeepCamelCaseProperties<Type> = Type extends Record<string, unknown>
182
  ? { [Key in keyof Type as CamelCase<Key>]: DeepCamelCaseProperties<Type[Key]> }
183
  : Type;
184
```
185

186
[Change Case Types](./change-case-types.md)
187

188
### Function Types
189

190
Type utilities for function signatures, predicates, and function-related operations.
191

192
```typescript { .api }
193
type AnyFunction<Args extends ReadonlyArray<any> = any[], ReturnType = any> = (...args: Args) => ReturnType;
194
type PredicateFunction = <T, U extends T>(arg: T) => arg is U;
195
```
196

197
[Function Types](./function-types.md)
198

199
### Utility Functions
200

201
Runtime functions that complement the type system, providing assertions, factories, and helper utilities.
202

203
```typescript { .api }
204
function assert(condition: any, message?: string): asserts condition;
205
class UnreachableCaseError extends Error {
206
  constructor(value: never);
207
}
208
function noop(..._args: any[]): void;
209
```
210

211
[Utility Functions](./utility-functions.md)