tessl/npm-re2

Bindings for RE2: fast, safe alternative to backtracking regular expression engines.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Types

Name: tessl/npm-re2
Author: tessl

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

Capabilities

Constructor Interface

Complete TypeScript interface for the RE2 constructor function:

/**
 * RE2 constructor interface extending RegExpConstructor
 */
interface RE2Constructor extends RegExpConstructor {
  // Constructor signatures
  new(pattern: string | Buffer | RegExp | RE2, flags?: string | Buffer): RE2;
  (pattern: string | Buffer | RegExp | RE2, flags?: string | Buffer): RE2;
  
  // Constructor prototype
  readonly prototype: RE2;
  
  // Static properties
  unicodeWarningLevel: 'nothing' | 'warnOnce' | 'warn' | 'throw';
  
  // Static utility methods
  getUtf8Length(value: string): number;
  getUtf16Length(value: Buffer): number;
}

declare const RE2: RE2Constructor;

Instance Interface

Main RE2 instance interface extending the built-in RegExp:

/**
 * RE2 instance interface extending RegExp
 */
interface RE2 extends RegExp {
  // Enhanced exec with Buffer support
  exec(str: string): RegExpExecArray | null;
  exec(str: Buffer): RE2BufferExecArray | null;
  
  // Enhanced test with Buffer support  
  test(str: string | Buffer): boolean;
  
  // Enhanced match with Buffer support
  match(str: string): RegExpMatchArray | null;
  match(str: Buffer): RE2BufferMatchArray | null;
  
  // Enhanced search with Buffer support
  search(str: string | Buffer): number;
  
  // Enhanced replace with Buffer support
  replace<K extends String | Buffer>(
    str: K, 
    replaceValue: string | Buffer
  ): K;
  replace<K extends String | Buffer>(
    str: K, 
    replacer: (substring: string, ...args: any[]) => string | Buffer
  ): K;
  
  // Enhanced split with Buffer support
  split<K extends String | Buffer>(str: K, limit?: number): K[];
}

Buffer Result Types

Specialized result types for Buffer operations:

/**
 * Result type for regex.exec() on Buffers
 */
interface RE2BufferExecArray extends Array<Buffer> {
  /** Match start position in bytes */
  index: number;
  
  /** Original Buffer input */
  input: Buffer;
  
  /** Full match as Buffer (same as [0]) */
  0: Buffer;
  
  /** Named capture groups as Buffers */
  groups?: {
    [key: string]: Buffer;
  };
}

/**
 * Result type for regex.match() on Buffers
 */
interface RE2BufferMatchArray extends Array<Buffer> {
  /** Match position in bytes (undefined for global matches) */
  index?: number;
  
  /** Original Buffer input (undefined for global matches) */
  input?: Buffer;
  
  /** Full match as Buffer (same as [0]) */
  0: Buffer;
  
  /** Named capture groups as Buffers */
  groups?: {
    [key: string]: Buffer;
  };
}

Pattern Input Types

Union types for constructor pattern parameters:

/**
 * Valid pattern input types for RE2 constructor
 */
type RE2Pattern = string | Buffer | RegExp | RE2;

/**
 * Valid flags input types for RE2 constructor
 */
type RE2Flags = string | Buffer;

/**
 * Input types for RE2 string methods
 */
type RE2Input = string | Buffer;

Flag Configuration Types

Types for regex flags and configuration:

/**
 * Unicode warning level configuration
 */
type UnicodeWarningLevel = 'nothing' | 'warnOnce' | 'warn' | 'throw';

/**
 * Supported regex flags
 */
interface RE2Flags {
  /** Global matching */
  g?: boolean;
  
  /** Case insensitive */
  i?: boolean;
  
  /** Multiline mode */
  m?: boolean;
  
  /** Dot matches newlines */
  s?: boolean;
  
  /** Unicode mode (always true for RE2) */
  u?: boolean;
  
  /** Sticky matching */
  y?: boolean;
  
  /** Generate indices for submatches */
  d?: boolean;
}

Generic Method Signatures

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

/**
 * Type-preserving replace method
 * Input type K is preserved in output
 */
replace<K extends String | Buffer>(str: K, replacement: string | Buffer): K;
replace<K extends String | Buffer>(
  str: K, 
  replacer: (substring: string, ...args: any[]) => string | Buffer
): K;

/**
 * Type-preserving split method  
 * Input type K determines array element type
 */
split<K extends String | Buffer>(str: K, limit?: number): K[];

Function Replacer Types

Detailed types for replacement function parameters:

/**
 * String replacer function signature
 */
type StringReplacer = (
  /** The matched substring */
  substring: string,
  
  /** Captured groups (numbered) */
  ...groups: (string | undefined)[],
  
  /** Match offset in characters */
  offset: number,
  
  /** Full input string */
  string: string,
  
  /** Named capture groups */
  namedGroups?: { [key: string]: string }
) => string;

/**
 * Buffer replacer function signature
 * Set replacer.useBuffers = true to receive Buffer arguments
 */
interface BufferReplacer {
  (
    /** The matched substring as Buffer */
    substring: Buffer,
    
    /** Captured groups as Buffers */
    ...groups: (Buffer | undefined)[],
    
    /** Match offset in bytes */
    offset: number,
    
    /** Full input Buffer */
    buffer: Buffer,
    
    /** Named capture groups as Buffers */
    namedGroups?: { [key: string]: Buffer }
  ): Buffer;
  
  /** Set to true to receive Buffer arguments */
  useBuffers?: boolean;
}

Error Types

Error types that may be thrown by RE2 operations:

/**
 * Constructor errors
 */
interface RE2TypeError extends TypeError {
  /** Thrown for invalid input types */
  message: string;
}

interface RE2SyntaxError extends SyntaxError {
  /** Thrown for invalid patterns or unsupported features */
  message: string;
}

/**
 * Method errors
 */
interface RE2MatchAllError extends TypeError {
  /** Thrown when using matchAll with non-global regex */
  message: 'String.prototype.matchAll() is called with a non-global RE2 argument';
}

Module Declaration

Complete module declaration for TypeScript:

/**
 * Complete RE2 module declaration
 */
declare module 're2' {
  // Type definitions
  interface RE2BufferExecArray extends Array<Buffer> {
    index: number;
    input: Buffer;
    0: Buffer;
    groups?: { [key: string]: Buffer };
  }

  interface RE2BufferMatchArray extends Array<Buffer> {
    index?: number;
    input?: Buffer;
    0: Buffer;
    groups?: { [key: string]: Buffer };
  }

  interface RE2 extends RegExp {
    exec(str: string): RegExpExecArray | null;
    exec(str: Buffer): RE2BufferExecArray | null;
    
    match(str: string): RegExpMatchArray | null;
    match(str: Buffer): RE2BufferMatchArray | null;
    
    test(str: string | Buffer): boolean;
    
    replace<K extends String | Buffer>(
      str: K, 
      replaceValue: string | Buffer
    ): K;
    replace<K extends String | Buffer>(
      str: K, 
      replacer: (substring: string, ...args: any[]) => string | Buffer
    ): K;
    
    search(str: string | Buffer): number;
    split<K extends String | Buffer>(str: K, limit?: number): K[];
  }

  interface RE2Constructor extends RegExpConstructor {
    new(pattern: string | Buffer | RegExp | RE2, flags?: string | Buffer): RE2;
    (pattern: string | Buffer | RegExp | RE2, flags?: string | Buffer): RE2;
    readonly prototype: RE2;
    
    unicodeWarningLevel: 'nothing' | 'warnOnce' | 'warn' | 'throw';
    getUtf8Length(value: string): number;
    getUtf16Length(value: Buffer): number;
  }

  const RE2: RE2Constructor;
  export = RE2;
}

Usage Examples

TypeScript usage examples demonstrating type safety:

import RE2 from 're2';

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

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

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

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

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

// Generic constraints
function processInput<T extends string | Buffer>(
  input: T, 
  regex: RE2
): T {
  return regex.replace(input, "replacement") as T;
}

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

// Buffer named groups
const bufferNamedMatch = namedRegex.exec(buffer);
if (bufferNamedMatch?.groups) {
  const wordBuffer: Buffer = bufferNamedMatch.groups.word; // Buffer type
}

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

// Configuration
RE2.unicodeWarningLevel = 'warn'; // Type-checked values

Install with Tessl CLI