0
# Function Module
1

2
Advanced function manipulation including composition, currying, piping, and parameter extraction with sophisticated type-level programming support.
3

4
## Capabilities
5

6
### Function Type Basics
7

8
Core function type utilities for parameter and return type extraction.
9

10
```typescript { .api }
11
/**
12
 * Base function type
13
 * @param P - Parameter types as tuple
14
 * @param R - Return type
15
 */
16
type Function<P extends readonly any[] = any, R = any> = (...args: P) => R;
17

18
/**
19
 * Extract parameter types from function
20
 * @param F - Function to extract parameters from
21
 * @returns Tuple of parameter types
22
 */
23
type Parameters<F extends Function> = F extends Function<infer P> ? P : never;
24

25
/**
26
 * Extract return type from function
27
 * @param F - Function to extract return type from
28
 * @returns Return type of function
29
 */
30
type Return<F extends Function> = F extends Function<any, infer R> ? R : never;
31

32
/**
33
 * Get length of function parameters
34
 * @param F - Function to get parameter length from
35
 * @returns Number of parameters
36
 */
37
type Length<F extends Function> = Parameters<F>['length'];
38
```
39

40
**Usage Examples:**
41

42
```typescript
43
import { F } from "ts-toolbelt";
44

45
type MyFunction = (a: string, b: number, c?: boolean) => void;
46

47
type Params = F.Parameters<MyFunction>; // [string, number, boolean?]
48
type ReturnType = F.Return<MyFunction>; // void
49
type ParamCount = F.Length<MyFunction>; // 3
50

51
// With arrow functions
52
type ArrowFn = (x: number) => string;
53
type ArrowParams = F.Parameters<ArrowFn>; // [number]
54
type ArrowReturn = F.Return<ArrowFn>; // string
55
```
56

57
### Function Currying
58

59
Advanced currying with placeholder support for partial application.
60

61
```typescript { .api }
62
/**
63
 * Transform function into curried version with placeholder support
64
 * @param F - Function to curry
65
 * @returns Curried function that accepts partial arguments
66
 */
67
type Curry<F extends Function> = F extends Function<infer P, infer R> 
68
  ? P extends readonly [] 
69
    ? () => R 
70
    : CurryImpl<P, R> 
71
  : never;
72

73
/**
74
 * Reverse curry operation - flatten curried function back to regular function
75
 * @param F - Curried function to uncurry
76
 * @returns Regular function with all parameters
77
 */
78
type UnCurry<F extends Function> = UnCurryImpl<F>;
79

80
/**
81
 * Placeholder type for currying - represents unfilled argument position
82
 */
83
type _ = any;
84
```
85

86
**Usage Examples:**
87

88
```typescript
89
import { F } from "ts-toolbelt";
90

91
// Basic currying
92
type Add = (a: number, b: number, c: number) => number;
93
type CurriedAdd = F.Curry<Add>; 
94
// (a: number) => (b: number) => (c: number) => number
95
// OR (a: number, b: number) => (c: number) => number  
96
// OR (a: number, b: number, c: number) => number
97

98
// Using placeholders
99
type CurriedWithPlaceholder = F.Curry<Add>;
100
// Can be called as: fn(_, 2, _) then fn(1, 3) to get result
101

102
// Uncurrying
103
type RegularAdd = F.UnCurry<CurriedAdd>; // (a: number, b: number, c: number) => number
104

105
// Complex function currying  
106
type ComplexFn = (a: string, b: number, c: boolean, d: object) => string[];
107
type CurriedComplex = F.Curry<ComplexFn>;
108
// Supports partial application at any level with placeholders
109
```
110

111
### Function Composition
112

113
Compose functions together for pipeline-style programming.
114

115
```typescript { .api }
116
/**
117
 * Compose functions right-to-left (mathematical composition)
118
 * @param Fns - Array of functions to compose
119
 * @returns Single composed function
120
 */
121
type Compose<Fns extends readonly Function[]> = ComposeImpl<Fns>;
122

123
/**
124
 * Pipe functions left-to-right (pipeline composition)
125
 * @param F - Initial function
126
 * @param Fns - Array of functions to pipe through
127
 * @returns Single piped function
128
 */
129
type Pipe<F extends Function, Fns extends readonly Function[]> = PipeImpl<F, Fns>;
130
```
131

132
**Usage Examples:**
133

134
```typescript
135
import { F } from "ts-toolbelt";
136

137
// Function composition (right-to-left)
138
type StringToNumber = (s: string) => number;
139
type NumberToBoolean = (n: number) => boolean;
140
type BooleanToString = (b: boolean) => string;
141

142
type Composed = F.Compose<[BooleanToString, NumberToBoolean, StringToNumber]>;
143
// (s: string) => string
144
// Applies: string -> number -> boolean -> string
145

146
// Function piping (left-to-right)  
147
type Piped = F.Pipe<StringToNumber, [NumberToBoolean, BooleanToString]>;
148
// (s: string) => string
149
// Applies: string -> number -> boolean -> string
150

151
// Complex pipeline
152
type ParseInt = (s: string) => number;
153
type IsEven = (n: number) => boolean;
154
type BoolToString = (b: boolean) => string;
155
type ToUpperCase = (s: string) => string;
156

157
type Pipeline = F.Pipe<ParseInt, [IsEven, BoolToString, ToUpperCase]>;
158
// (s: string) => string
159
```
160

161
### Function Transformation
162

163
Transform and modify function types in various ways.
164

165
```typescript { .api }
166
/**
167
 * Make function parameters narrower (more specific)
168
 * @param F - Function to narrow
169
 * @param N - Narrowing specification
170
 * @returns Function with narrowed parameters
171
 */
172
type Narrow<F extends Function, N> = NarrowImpl<F, N>;
173

174
/**
175
 * Make function exact - prevent excess properties
176
 * @param F - Function to make exact
177
 * @returns Exact function type
178
 */
179
type Exact<F extends Function> = ExactImpl<F>;
180

181
/**
182
 * Convert function to return promises
183
 * @param F - Function to promisify
184
 * @returns Function that returns Promise of original return type
185
 */
186
type Promisify<F extends Function> = F extends Function<infer P, infer R> 
187
  ? Function<P, Promise<R>>
188
  : never;
189

190
/**
191
 * Prevent type inference for function parameters
192
 * @param F - Function to prevent inference on
193
 * @returns Function with inference prevented
194
 */
195
type NoInfer<F extends Function> = NoInferImpl<F>;
196
```
197

198
**Usage Examples:**
199

200
```typescript
201
import { F } from "ts-toolbelt";
202

203
// Promisify function
204
type SyncFunction = (x: number) => string;
205
type AsyncFunction = F.Promisify<SyncFunction>; // (x: number) => Promise<string>
206

207
// Narrow function parameters
208
type GenericFn = (obj: { a: any; b: any }) => void;
209
type NarrowedFn = F.Narrow<GenericFn, { a: string; b: number }>; 
210
// (obj: { a: string; b: number }) => void
211

212
// Exact function parameters
213
type LooseFn = (obj: { a: string }) => void;
214
type ExactFn = F.Exact<LooseFn>; // Prevents excess properties in obj
215

216
// Prevent inference
217
type InferenceFn<T> = (x: T) => T;
218
type NoInferenceFn<T> = F.NoInfer<InferenceFn<T>>; // T won't be inferred from usage
219
```
220

221
### Path Operations
222

223
Generate and validate paths through function parameter structures.
224

225
```typescript { .api }
226
/**
227
 * Automatically generate valid paths for function parameters
228
 * @param F - Function to generate paths for
229
 * @returns Valid path types for function parameters
230
 */
231
type AutoPath<F extends Function> = AutoPathImpl<F>;
232

233
/**
234
 * Validate that paths are valid for function parameters
235
 * @param F - Function to validate paths against
236
 * @param Path - Path to validate
237
 * @returns 1 if path is valid, 0 otherwise
238
 */
239
type ValidPath<F extends Function, Path extends string> = ValidPathImpl<F, Path>;
240
```
241

242
**Usage Examples:**
243

244
```typescript
245
import { F } from "ts-toolbelt";
246

247
type ComplexFn = (user: { 
248
  profile: { 
249
    name: string; 
250
    details: { age: number; address: { city: string } } 
251
  }; 
252
  settings: { theme: string } 
253
}) => void;
254

255
type ValidPaths = F.AutoPath<ComplexFn>; 
256
// "0" | "0.profile" | "0.profile.name" | "0.profile.details" | 
257
// "0.profile.details.age" | "0.profile.details.address" | 
258
// "0.profile.details.address.city" | "0.settings" | "0.settings.theme"
259

260
type IsValidPath1 = F.ValidPath<ComplexFn, "0.profile.name">; // 1
261
type IsValidPath2 = F.ValidPath<ComplexFn, "0.invalid.path">; // 0
262
```
263

264
## Types
265

266
```typescript { .api }
267
// Core types used by Function module
268
type Function<P extends readonly any[] = any, R = any> = (...args: P) => R;
269
type _ = any; // Placeholder for currying
270
```