0
# Types
1

2
Complete TypeScript type definitions for RE2 interfaces and Buffer-specific types.
3

4
## Capabilities
5

6
### Constructor Interface
7

8
Complete TypeScript interface for the RE2 constructor function:
9

10
```typescript { .api }
11
/**
12
 * RE2 constructor interface extending RegExpConstructor
13
 */
14
interface RE2Constructor extends RegExpConstructor {
15
  // Constructor signatures
16
  new(pattern: string | Buffer | RegExp | RE2, flags?: string | Buffer): RE2;
17
  (pattern: string | Buffer | RegExp | RE2, flags?: string | Buffer): RE2;
18
  
19
  // Constructor prototype
20
  readonly prototype: RE2;
21
  
22
  // Static properties
23
  unicodeWarningLevel: 'nothing' | 'warnOnce' | 'warn' | 'throw';
24
  
25
  // Static utility methods
26
  getUtf8Length(value: string): number;
27
  getUtf16Length(value: Buffer): number;
28
}
29

30
declare const RE2: RE2Constructor;
31
```
32

33
### Instance Interface
34

35
Main RE2 instance interface extending the built-in RegExp:
36

37
```typescript { .api }
38
/**
39
 * RE2 instance interface extending RegExp
40
 */
41
interface RE2 extends RegExp {
42
  // Enhanced exec with Buffer support
43
  exec(str: string): RegExpExecArray | null;
44
  exec(str: Buffer): RE2BufferExecArray | null;
45
  
46
  // Enhanced test with Buffer support  
47
  test(str: string | Buffer): boolean;
48
  
49
  // Enhanced match with Buffer support
50
  match(str: string): RegExpMatchArray | null;
51
  match(str: Buffer): RE2BufferMatchArray | null;
52
  
53
  // Enhanced search with Buffer support
54
  search(str: string | Buffer): number;
55
  
56
  // Enhanced replace with Buffer support
57
  replace<K extends String | Buffer>(
58
    str: K, 
59
    replaceValue: string | Buffer
60
  ): K;
61
  replace<K extends String | Buffer>(
62
    str: K, 
63
    replacer: (substring: string, ...args: any[]) => string | Buffer
64
  ): K;
65
  
66
  // Enhanced split with Buffer support
67
  split<K extends String | Buffer>(str: K, limit?: number): K[];
68
}
69
```
70

71
### Buffer Result Types
72

73
Specialized result types for Buffer operations:
74

75
```typescript { .api }
76
/**
77
 * Result type for regex.exec() on Buffers
78
 */
79
interface RE2BufferExecArray extends Array<Buffer> {
80
  /** Match start position in bytes */
81
  index: number;
82
  
83
  /** Original Buffer input */
84
  input: Buffer;
85
  
86
  /** Full match as Buffer (same as [0]) */
87
  0: Buffer;
88
  
89
  /** Named capture groups as Buffers */
90
  groups?: {
91
    [key: string]: Buffer;
92
  };
93
}
94

95
/**
96
 * Result type for regex.match() on Buffers
97
 */
98
interface RE2BufferMatchArray extends Array<Buffer> {
99
  /** Match position in bytes (undefined for global matches) */
100
  index?: number;
101
  
102
  /** Original Buffer input (undefined for global matches) */
103
  input?: Buffer;
104
  
105
  /** Full match as Buffer (same as [0]) */
106
  0: Buffer;
107
  
108
  /** Named capture groups as Buffers */
109
  groups?: {
110
    [key: string]: Buffer;
111
  };
112
}
113
```
114

115
### Pattern Input Types
116

117
Union types for constructor pattern parameters:
118

119
```typescript { .api }
120
/**
121
 * Valid pattern input types for RE2 constructor
122
 */
123
type RE2Pattern = string | Buffer | RegExp | RE2;
124

125
/**
126
 * Valid flags input types for RE2 constructor
127
 */
128
type RE2Flags = string | Buffer;
129

130
/**
131
 * Input types for RE2 string methods
132
 */
133
type RE2Input = string | Buffer;
134
```
135

136
### Flag Configuration Types
137

138
Types for regex flags and configuration:
139

140
```typescript { .api }
141
/**
142
 * Unicode warning level configuration
143
 */
144
type UnicodeWarningLevel = 'nothing' | 'warnOnce' | 'warn' | 'throw';
145

146
/**
147
 * Supported regex flags
148
 */
149
interface RE2Flags {
150
  /** Global matching */
151
  g?: boolean;
152
  
153
  /** Case insensitive */
154
  i?: boolean;
155
  
156
  /** Multiline mode */
157
  m?: boolean;
158
  
159
  /** Dot matches newlines */
160
  s?: boolean;
161
  
162
  /** Unicode mode (always true for RE2) */
163
  u?: boolean;
164
  
165
  /** Sticky matching */
166
  y?: boolean;
167
  
168
  /** Generate indices for submatches */
169
  d?: boolean;
170
}
171
```
172

173
### Generic Method Signatures
174

175
Generic type-safe method signatures preserving input/output types:
176

177
```typescript { .api }
178
/**
179
 * Type-preserving replace method
180
 * Input type K is preserved in output
181
 */
182
replace<K extends String | Buffer>(str: K, replacement: string | Buffer): K;
183
replace<K extends String | Buffer>(
184
  str: K, 
185
  replacer: (substring: string, ...args: any[]) => string | Buffer
186
): K;
187

188
/**
189
 * Type-preserving split method  
190
 * Input type K determines array element type
191
 */
192
split<K extends String | Buffer>(str: K, limit?: number): K[];
193
```
194

195
### Function Replacer Types
196

197
Detailed types for replacement function parameters:
198

199
```typescript { .api }
200
/**
201
 * String replacer function signature
202
 */
203
type StringReplacer = (
204
  /** The matched substring */
205
  substring: string,
206
  
207
  /** Captured groups (numbered) */
208
  ...groups: (string | undefined)[],
209
  
210
  /** Match offset in characters */
211
  offset: number,
212
  
213
  /** Full input string */
214
  string: string,
215
  
216
  /** Named capture groups */
217
  namedGroups?: { [key: string]: string }
218
) => string;
219

220
/**
221
 * Buffer replacer function signature
222
 * Set replacer.useBuffers = true to receive Buffer arguments
223
 */
224
interface BufferReplacer {
225
  (
226
    /** The matched substring as Buffer */
227
    substring: Buffer,
228
    
229
    /** Captured groups as Buffers */
230
    ...groups: (Buffer | undefined)[],
231
    
232
    /** Match offset in bytes */
233
    offset: number,
234
    
235
    /** Full input Buffer */
236
    buffer: Buffer,
237
    
238
    /** Named capture groups as Buffers */
239
    namedGroups?: { [key: string]: Buffer }
240
  ): Buffer;
241
  
242
  /** Set to true to receive Buffer arguments */
243
  useBuffers?: boolean;
244
}
245
```
246

247
### Error Types
248

249
Error types that may be thrown by RE2 operations:
250

251
```typescript { .api }
252
/**
253
 * Constructor errors
254
 */
255
interface RE2TypeError extends TypeError {
256
  /** Thrown for invalid input types */
257
  message: string;
258
}
259

260
interface RE2SyntaxError extends SyntaxError {
261
  /** Thrown for invalid patterns or unsupported features */
262
  message: string;
263
}
264

265
/**
266
 * Method errors
267
 */
268
interface RE2MatchAllError extends TypeError {
269
  /** Thrown when using matchAll with non-global regex */
270
  message: 'String.prototype.matchAll() is called with a non-global RE2 argument';
271
}
272
```
273

274
### Module Declaration
275

276
Complete module declaration for TypeScript:
277

278
```typescript { .api }
279
/**
280
 * Complete RE2 module declaration
281
 */
282
declare module 're2' {
283
  // Type definitions
284
  interface RE2BufferExecArray extends Array<Buffer> {
285
    index: number;
286
    input: Buffer;
287
    0: Buffer;
288
    groups?: { [key: string]: Buffer };
289
  }
290

291
  interface RE2BufferMatchArray extends Array<Buffer> {
292
    index?: number;
293
    input?: Buffer;
294
    0: Buffer;
295
    groups?: { [key: string]: Buffer };
296
  }
297

298
  interface RE2 extends RegExp {
299
    exec(str: string): RegExpExecArray | null;
300
    exec(str: Buffer): RE2BufferExecArray | null;
301
    
302
    match(str: string): RegExpMatchArray | null;
303
    match(str: Buffer): RE2BufferMatchArray | null;
304
    
305
    test(str: string | Buffer): boolean;
306
    
307
    replace<K extends String | Buffer>(
308
      str: K, 
309
      replaceValue: string | Buffer
310
    ): K;
311
    replace<K extends String | Buffer>(
312
      str: K, 
313
      replacer: (substring: string, ...args: any[]) => string | Buffer
314
    ): K;
315
    
316
    search(str: string | Buffer): number;
317
    split<K extends String | Buffer>(str: K, limit?: number): K[];
318
  }
319

320
  interface RE2Constructor extends RegExpConstructor {
321
    new(pattern: string | Buffer | RegExp | RE2, flags?: string | Buffer): RE2;
322
    (pattern: string | Buffer | RegExp | RE2, flags?: string | Buffer): RE2;
323
    readonly prototype: RE2;
324
    
325
    unicodeWarningLevel: 'nothing' | 'warnOnce' | 'warn' | 'throw';
326
    getUtf8Length(value: string): number;
327
    getUtf16Length(value: Buffer): number;
328
  }
329

330
  const RE2: RE2Constructor;
331
  export = RE2;
332
}
333
```
334

335
### Usage Examples
336

337
TypeScript usage examples demonstrating type safety:
338

339
```typescript
340
import RE2 from 're2';
341

342
// Constructor with type inference
343
const stringRegex: RE2 = new RE2("\\d+", "g");
344
const bufferRegex: RE2 = new RE2(Buffer.from("test"), "i");
345
const fromRegexp: RE2 = new RE2(/hello/gi);
346

347
// Method calls with proper return types
348
const text = "test 123";
349
const buffer = Buffer.from(text, "utf8");
350

351
// String operations return string types
352
const stringMatch: RegExpExecArray | null = stringRegex.exec(text);
353
const stringSearch: number = stringRegex.search(text);
354

355
// Buffer operations return Buffer types  
356
const bufferMatch: RE2BufferExecArray | null = stringRegex.exec(buffer);
357
const bufferReplace: Buffer = stringRegex.replace(buffer, "XXX");
358

359
// Type-preserving operations
360
const stringParts: string[] = stringRegex.split(text);
361
const bufferParts: Buffer[] = stringRegex.split(buffer);
362

363
// Generic constraints
364
function processInput<T extends string | Buffer>(
365
  input: T, 
366
  regex: RE2
367
): T {
368
  return regex.replace(input, "replacement") as T;
369
}
370

371
// Named groups with proper typing
372
const namedRegex = new RE2("(?<word>\\w+)");
373
const namedMatch = namedRegex.exec("hello");
374
if (namedMatch?.groups) {
375
  const word: string = namedMatch.groups.word; // Type-safe access
376
}
377

378
// Buffer named groups
379
const bufferNamedMatch = namedRegex.exec(buffer);
380
if (bufferNamedMatch?.groups) {
381
  const wordBuffer: Buffer = bufferNamedMatch.groups.word; // Buffer type
382
}
383

384
// Static method usage
385
const utf8Length: number = RE2.getUtf8Length("Hello 世界");
386
const utf16Length: number = RE2.getUtf16Length(Buffer.from("test", "utf8"));
387

388
// Configuration
389
RE2.unicodeWarningLevel = 'warn'; // Type-checked values
390
```