0
# Timeout Management
1

2
Promise timeout handling with custom error types and wrapper functions for time-limited operations, essential for preventing hanging operations in network requests and long-running tasks.
3

4
## Capabilities
5

6
### Timeout Error Class
7

8
Custom error class for timeout operations with timeout value preservation.
9

10
```typescript { .api }
11
/**
12
 * Custom error class for timeout operations
13
 */
14
class TimeoutError extends Error {
15
  timeout: number;
16
  
17
  constructor(timeout: number);
18
}
19
```
20

21
**Usage Examples:**
22

23
```typescript
24
import { TimeoutError } from "utility";
25

26
// Create timeout error
27
const error = new TimeoutError(5000);
28
console.log(error.message); // "Timed out after 5000ms"
29
console.log(error.timeout); // 5000
30
console.log(error.name);    // "TimeoutError"
31

32
// Error handling
33
try {
34
  throw new TimeoutError(3000);
35
} catch (err) {
36
  if (err instanceof TimeoutError) {
37
    console.log(`Operation timed out after ${err.timeout}ms`);
38
  }
39
}
40
```
41

42
### Promise Timeout
43

44
Add timeout functionality to any promise with automatic cleanup.
45

46
```typescript { .api }
47
/**
48
 * Add timeout to a promise with automatic cleanup
49
 * @param promiseArg - Promise to add timeout to
50
 * @param timeout - Timeout in milliseconds
51
 * @returns Promise that rejects with TimeoutError if timeout exceeded
52
 */
53
function promiseTimeout<T>(promiseArg: Promise<T>, timeout: number): Promise<T>;
54
```
55

56
**Usage Examples:**
57

58
```typescript
59
import { promiseTimeout, TimeoutError } from "utility";
60

61
// Basic timeout usage
62
const fetchWithTimeout = promiseTimeout(
63
  fetch('https://api.example.com/data'),
64
  5000
65
);
66

67
try {
68
  const response = await fetchWithTimeout;
69
  const data = await response.json();
70
} catch (error) {
71
  if (error instanceof TimeoutError) {
72
    console.log('Request timed out after 5 seconds');
73
  }
74
}
75

76
// Database query with timeout
77
const query = promiseTimeout(
78
  database.query('SELECT * FROM users'),
79
  10000
80
);
81

82
// File operation with timeout
83
const fileRead = promiseTimeout(
84
  fs.readFile('large-file.txt', 'utf8'),
85
  30000
86
);
87

88
// Chain with other operations
89
const result = await promiseTimeout(
90
  someAsyncOperation().then(data => processData(data)),
91
  15000
92
);
93
```
94

95
### Run with Timeout
96

97
Wrapper function that creates and times out a promise-returning function.
98

99
```typescript { .api }
100
/**
101
 * Run a promise-returning function with timeout
102
 * @param scope - Function that returns a promise
103
 * @param timeout - Timeout in milliseconds
104
 * @returns Promise that rejects with TimeoutError if timeout exceeded
105
 */
106
function runWithTimeout<T>(scope: () => Promise<T>, timeout: number): Promise<T>;
107
```
108

109
**Usage Examples:**
110

111
```typescript
112
import { runWithTimeout, TimeoutError } from "utility";
113

114
// Simple async operation with timeout
115
const result = await runWithTimeout(async () => {
116
  const response = await fetch('https://api.example.com/slow-endpoint');
117
  return response.json();
118
}, 8000);
119

120
// Complex operation with timeout
121
const processedData = await runWithTimeout(async () => {
122
  const data = await fetchLargeDataset();
123
  const processed = await processInBackground(data);
124
  const validated = await validateResults(processed);
125
  return validated;
126
}, 60000);
127

128
// Error handling
129
try {
130
  const result = await runWithTimeout(async () => {
131
    await new Promise(resolve => setTimeout(resolve, 10000)); // 10 second delay
132
    return 'completed';
133
  }, 5000); // 5 second timeout
134
} catch (error) {
135
  if (error instanceof TimeoutError) {
136
    console.log('Operation took too long');
137
  }
138
}
139

140
// Retry with timeout
141
async function retryWithTimeout<T>(
142
  operation: () => Promise<T>, 
143
  maxRetries: number = 3, 
144
  timeout: number = 5000
145
): Promise<T> {
146
  for (let i = 0; i < maxRetries; i++) {
147
    try {
148
      return await runWithTimeout(operation, timeout);
149
    } catch (error) {
150
      if (error instanceof TimeoutError && i < maxRetries - 1) {
151
        console.log(`Attempt ${i + 1} timed out, retrying...`);
152
        continue;
153
      }
154
      throw error;
155
    }
156
  }
157
  throw new Error('All retries failed');
158
}
159
```