1/**
2 * TypeScript Utility Types Library
3 * 
4 * A collection of commonly used utility types for TypeScript projects.
5 * Copy and use as needed in your projects.
6 */
7 
8// =============================================================================
9// BRANDED TYPES
10// =============================================================================
11 
12/**
13 * Create nominal/branded types to prevent primitive obsession.
14 * 
15 * @example
16 * type UserId = Brand<string, 'UserId'>
17 * type OrderId = Brand<string, 'OrderId'>
18 */
19export type Brand<K, T> = K & { readonly __brand: T }
20 
21// Branded type constructors
22export type UserId = Brand<string, 'UserId'>
23export type Email = Brand<string, 'Email'>
24export type UUID = Brand<string, 'UUID'>
25export type Timestamp = Brand<number, 'Timestamp'>
26export type PositiveNumber = Brand<number, 'PositiveNumber'>
27 
28// =============================================================================
29// RESULT TYPE (Error Handling)
30// =============================================================================
31 
32/**
33 * Type-safe error handling without exceptions.
34 */
35export type Result<T, E = Error> =
36    | { success: true; data: T }
37    | { success: false; error: E }
38 
39export const ok = <T>(data: T): Result<T, never> => ({
40    success: true,
41    data
42})
43 
44export const err = <E>(error: E): Result<never, E> => ({
45    success: false,
46    error
47})
48 
49// =============================================================================
50// OPTION TYPE (Nullable Handling)  
51// =============================================================================
52 
53/**
54 * Explicit optional value handling.
55 */
56export type Option<T> = Some<T> | None
57 
58export type Some<T> = { type: 'some'; value: T }
59export type None = { type: 'none' }
60 
61export const some = <T>(value: T): Some<T> => ({ type: 'some', value })
62export const none: None = { type: 'none' }
63 
64// =============================================================================
65// DEEP UTILITIES
66// =============================================================================
67 
68/**
69 * Make all properties deeply readonly.
70 */
71export type DeepReadonly<T> = T extends (...args: any[]) => any
72    ? T
73    : T extends object
74    ? { readonly [K in keyof T]: DeepReadonly<T[K]> }
75    : T
76 
77/**
78 * Make all properties deeply optional.
79 */
80export type DeepPartial<T> = T extends object
81    ? { [K in keyof T]?: DeepPartial<T[K]> }
82    : T
83 
84/**
85 * Make all properties deeply required.
86 */
87export type DeepRequired<T> = T extends object
88    ? { [K in keyof T]-?: DeepRequired<T[K]> }
89    : T
90 
91/**
92 * Make all properties deeply mutable (remove readonly).
93 */
94export type DeepMutable<T> = T extends object
95    ? { -readonly [K in keyof T]: DeepMutable<T[K]> }
96    : T
97 
98// =============================================================================
99// OBJECT UTILITIES
100// =============================================================================
101 
102/**
103 * Get keys of object where value matches type.
104 */
105export type KeysOfType<T, V> = {
106    [K in keyof T]: T[K] extends V ? K : never
107}[keyof T]
108 
109/**
110 * Pick properties by value type.
111 */
112export type PickByType<T, V> = Pick<T, KeysOfType<T, V>>
113 
114/**
115 * Omit properties by value type.
116 */
117export type OmitByType<T, V> = Omit<T, KeysOfType<T, V>>
118 
119/**
120 * Make specific keys optional.
121 */
122export type PartialBy<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>
123 
124/**
125 * Make specific keys required.
126 */
127export type RequiredBy<T, K extends keyof T> = Omit<T, K> & Required<Pick<T, K>>
128 
129/**
130 * Make specific keys readonly.
131 */
132export type ReadonlyBy<T, K extends keyof T> = Omit<T, K> & Readonly<Pick<T, K>>
133 
134/**
135 * Merge two types (second overrides first).
136 */
137export type Merge<T, U> = Omit<T, keyof U> & U
138 
139// =============================================================================
140// ARRAY UTILITIES
141// =============================================================================
142 
143/**
144 * Get element type from array.
145 */
146export type ElementOf<T> = T extends (infer E)[] ? E : never
147 
148/**
149 * Tuple of specific length.
150 */
151export type Tuple<T, N extends number> = N extends N
152    ? number extends N
153    ? T[]
154    : _TupleOf<T, N, []>
155    : never
156 
157type _TupleOf<T, N extends number, R extends unknown[]> = R['length'] extends N
158    ? R
159    : _TupleOf<T, N, [T, ...R]>
160 
161/**
162 * Non-empty array.
163 */
164export type NonEmptyArray<T> = [T, ...T[]]
165 
166/**
167 * At least N elements.
168 */
169export type AtLeast<T, N extends number> = [...Tuple<T, N>, ...T[]]
170 
171// =============================================================================
172// FUNCTION UTILITIES
173// =============================================================================
174 
175/**
176 * Get function arguments as tuple.
177 */
178export type Arguments<T> = T extends (...args: infer A) => any ? A : never
179 
180/**
181 * Get first argument of function.
182 */
183export type FirstArgument<T> = T extends (first: infer F, ...args: any[]) => any
184    ? F
185    : never
186 
187/**
188 * Async version of function.
189 */
190export type AsyncFunction<T extends (...args: any[]) => any> = (
191    ...args: Parameters<T>
192) => Promise<Awaited<ReturnType<T>>>
193 
194/**
195 * Promisify return type.
196 */
197export type Promisify<T> = T extends (...args: infer A) => infer R
198    ? (...args: A) => Promise<Awaited<R>>
199    : never
200 
201// =============================================================================
202// STRING UTILITIES
203// =============================================================================
204 
205/**
206 * Split string by delimiter.
207 */
208export type Split<S extends string, D extends string> =
209    S extends `${infer T}${D}${infer U}`
210    ? [T, ...Split<U, D>]
211    : [S]
212 
213/**
214 * Join tuple to string.
215 */
216export type Join<T extends string[], D extends string> =
217    T extends []
218    ? ''
219    : T extends [infer F extends string]
220    ? F
221    : T extends [infer F extends string, ...infer R extends string[]]
222    ? `${F}${D}${Join<R, D>}`
223    : never
224 
225/**
226 * Path to nested object.
227 */
228export type PathOf<T, K extends keyof T = keyof T> = K extends string
229    ? T[K] extends object
230    ? K | `${K}.${PathOf<T[K]>}`
231    : K
232    : never
233 
234// =============================================================================
235// UNION UTILITIES
236// =============================================================================
237 
238/**
239 * Last element of union.
240 */
241export type UnionLast<T> = UnionToIntersection<
242    T extends any ? () => T : never
243> extends () => infer R
244    ? R
245    : never
246 
247/**
248 * Union to intersection.
249 */
250export type UnionToIntersection<U> = (
251    U extends any ? (k: U) => void : never
252) extends (k: infer I) => void
253    ? I
254    : never
255 
256/**
257 * Union to tuple.
258 */
259export type UnionToTuple<T, L = UnionLast<T>> = [T] extends [never]
260    ? []
261    : [...UnionToTuple<Exclude<T, L>>, L]
262 
263// =============================================================================
264// VALIDATION UTILITIES
265// =============================================================================
266 
267/**
268 * Assert type at compile time.
269 */
270export type AssertEqual<T, U> =
271    (<V>() => V extends T ? 1 : 2) extends (<V>() => V extends U ? 1 : 2)
272    ? true
273    : false
274 
275/**
276 * Ensure type is not never.
277 */
278export type IsNever<T> = [T] extends [never] ? true : false
279 
280/**
281 * Ensure type is any.
282 */
283export type IsAny<T> = 0 extends 1 & T ? true : false
284 
285/**
286 * Ensure type is unknown.
287 */
288export type IsUnknown<T> = IsAny<T> extends true
289    ? false
290    : unknown extends T
291    ? true
292    : false
293 
294// =============================================================================
295// JSON UTILITIES
296// =============================================================================
297 
298/**
299 * JSON-safe types.
300 */
301export type JsonPrimitive = string | number | boolean | null
302export type JsonArray = JsonValue[]
303export type JsonObject = { [key: string]: JsonValue }
304export type JsonValue = JsonPrimitive | JsonArray | JsonObject
305 
306/**
307 * Make type JSON-serializable.
308 */
309export type Jsonify<T> = T extends JsonPrimitive
310    ? T
311    : T extends undefined | ((...args: any[]) => any) | symbol
312    ? never
313    : T extends { toJSON(): infer R }
314    ? R
315    : T extends object
316    ? { [K in keyof T]: Jsonify<T[K]> }
317    : never
318 
319// =============================================================================
320// EXHAUSTIVE CHECK
321// =============================================================================
322 
323/**
324 * Ensure all cases are handled in switch/if.
325 */
326export function assertNever(value: never, message?: string): never {
327    throw new Error(message ?? `Unexpected value: ${value}`)
328}
329 
330/**
331 * Exhaustive check without throwing.
332 */
333export function exhaustiveCheck(_value: never): void {
334    // This function should never be called
335}
336