Types Reference

Complete TypeScript type definitions for logpare.

Core Types

CompressionResult

Result object returned by compress() and compressText().

interface CompressionResult {
  templates: Template[];
  stats: CompressionStats;
  formatted: string;
}

Fields:

• templates - Array of discovered templates, sorted by occurrence count (descending)
• stats - Compression statistics
• formatted - String representation in the requested format

Template

Represents a discovered log template with metadata.

interface Template {
  id: string;
  pattern: string;
  occurrences: number;
  sampleVariables: string[][];
  firstSeen: number;
  lastSeen: number;
  severity: Severity;
  urlSamples: string[];
  fullUrlSamples: string[];
  statusCodeSamples: number[];
  correlationIdSamples: string[];
  durationSamples: string[];
  isStackFrame: boolean;
}

Fields:

• id - Unique template identifier
• pattern - Template pattern with <*> wildcards for variables
• occurrences - Number of log lines matching this template
• sampleVariables - Sample values captured from variables (limited by maxSamples). Serialized as samples in JSON output.
• firstSeen - Zero-based line index where the template was first seen. The detailed formatter displays this as a one-based line number.
• lastSeen - Zero-based line index where the template was last seen
• severity - Severity level: 'error', 'warning', or 'info'
• urlSamples - Extracted hostnames from URLs
• fullUrlSamples - Complete URLs found in matching logs
• statusCodeSamples - HTTP status codes (e.g., [200, 404, 500])
• correlationIdSamples - Trace/request IDs for distributed tracing
• durationSamples - Timing values (e.g., ["45ms", "1.5s"])
• isStackFrame - Whether this template represents a stack frame

CompressionStats

Statistics about the compression operation. This is the inline type of CompressionResult['stats'] — logpare does not export a CompressionStats name, so write CompressionResult['stats'] when you need to refer to it.

// Shape of CompressionResult['stats']
interface CompressionStats {
  inputLines: number;
  uniqueTemplates: number;
  compressionRatio: number;
  estimatedTokenReduction: number;
  droppedLines?: number;
  processingTimeMs?: number;
}

Fields:

• inputLines - Non-blank input log lines processed. Blank and whitespace-only lines are excluded, so a trailing newline does not change this figure.
• uniqueTemplates - Number of unique templates discovered, before maxTemplates truncation
• compressionRatio - 1 - (uniqueTemplates / inputLines), clamped to 0.0–1.0. Higher means more compression.
• estimatedTokenReduction - Estimated saving as a ratio between 0 and 1, not a percentage. Character-count proxy: each pattern's length times its occurrences, versus the pattern printed once.
• droppedLines - Lines discarded because maxClusters was reached. Non-zero means the output is incomplete and compressionRatio overstates the real result. Optional on the interface for backwards compatibility; logpare itself always populates it.
• processingTimeMs - Wall-clock processing time. Populated by compress() and compressText(), not by Drain.getResult().

Options Types

CompressOptions

Options for compress() and compressText().

interface CompressOptions {
  format?: OutputFormat;
  maxTemplates?: number;
  /** Drain algorithm options are nested, not inherited */
  drain?: DrainOptions;
}

Fields:

• format - Output format: 'summary', 'detailed', 'json', or 'json-stable' (default: 'summary'). 'json-stable' emits the same data as 'json' with recursively sorted keys and no whitespace, for stable diffs and LLM KV-cache hits.
• maxTemplates - Maximum templates in formatted output (default: 50)
• drain - Nested DrainOptions. These are not accepted at the top level — pass them as { drain: { depth: 5 } }.

DrainOptions

Configuration for the Drain algorithm.

interface DrainOptions {
  depth?: number;
  simThreshold?: number;
  maxChildren?: number;
  maxClusters?: number;
  maxSamples?: number;
  preprocessing?: ParsingStrategy;
  onProgress?: ProgressCallback;
}

Fields:

• depth - Parse tree depth (default: 4)
• simThreshold - Similarity threshold 0-1 (default: 0.4). When omitted, the parsing strategy stays authoritative and may vary the threshold by depth; when supplied, it overrides the strategy at every depth.
• maxChildren - Max children per tree node (default: 100)
• maxClusters - Max total templates (default: 1000). Once reached, unmatched lines are discarded and counted in stats.droppedLines.
• maxSamples - Sample variables per template (default: 3)
• preprocessing - Custom preprocessing strategy
• onProgress - Progress reporting callback

Preprocessing Types

ParsingStrategy

Strategy for preprocessing and tokenizing log lines.

interface ParsingStrategy {
  preprocess(line: string): string;
  tokenize(line: string): string[];
  getSimThreshold(depth: number): number;
}

Methods:

• preprocess(line) - Preprocess a log line (mask variables, normalize, etc.)
• tokenize(line) - Split preprocessed line into tokens
• getSimThreshold(depth) - Get similarity threshold for a given tree depth

Example:

import { defineStrategy, DEFAULT_PATTERNS, WILDCARD } from 'logpare';

const customStrategy: ParsingStrategy = defineStrategy({
  preprocess(line: string): string {
    let result = line;
    for (const [, pattern] of Object.entries(DEFAULT_PATTERNS)) {
      result = result.replace(pattern, WILDCARD);
    }
    return result;
  },

  tokenize(line: string): string[] {
    return line.split(/\s+/).filter(Boolean);
  },

  getSimThreshold(depth: number): number {
    return depth <= 2 ? 0.3 : 0.4;
  }
});

Progress Types

ProgressCallback

Callback function for progress updates.

type ProgressCallback = (event: ProgressEvent) => void;

ProgressEvent

Progress event data.

interface ProgressEvent {
  processedLines: number;
  totalLines?: number;
  currentPhase: 'parsing' | 'clustering' | 'finalizing';
  percentComplete?: number;
}

Fields:

• processedLines - Number of lines processed so far
• totalLines - Total lines to process (if known)
• currentPhase - Current processing phase
• percentComplete - Completion percentage 0-100 (only if totalLines known)

Processing phase

currentPhase is an inline union on ProgressEvent; there is no exported ProcessingPhase alias.

'parsing' | 'clustering' | 'finalizing'

Enum Types

Severity

Log severity level.

type Severity = 'error' | 'warning' | 'info';

Automatically detected from log content:

• 'error' - ERROR, FATAL, Exception, Failed, TypeError, etc.
• 'warning' - WARN, Warning, Deprecated, [Violation]
• 'info' - Default for other logs

OutputFormat

Output format for compression results.

type OutputFormat = 'summary' | 'detailed' | 'json' | 'json-stable';

• 'summary' - Compact template list with frequencies
• 'detailed' - Full templates with all metadata
• 'json' - Machine-readable JSON, pretty printed
• 'json-stable' - The same JSON with recursively sorted keys and no whitespace, for maximum LLM KV-cache hits and stable diffs

Both JSON formats emit version, a four-field stats object (inputLines, uniqueTemplates, compressionRatio, estimatedTokenReduction, each ratio rounded to three decimals), and templates. processingTimeMs and droppedLines are not included in JSON output — read them from result.stats instead.

Constants

WILDCARD

The wildcard placeholder used in templates.

const WILDCARD: '<*>';

Example:

import { WILDCARD } from 'logpare';

const pattern = `ERROR Connection to ${WILDCARD} failed`;

DEFAULT_PATTERNS

Built-in regex patterns for common log variables.

const DEFAULT_PATTERNS: Record<string, RegExp>;

Insertion order matters — patterns are applied in sequence, and more specific patterns run first so they are not fragmented by broader ones. The keys, in application order:

Example:

import { DEFAULT_PATTERNS } from 'logpare';

// Use in custom preprocessing
const masked = line.replace(DEFAULT_PATTERNS.ipv4, '<*>');

SEVERITY_PATTERNS

Regex patterns for severity detection.

const SEVERITY_PATTERNS: {
  error: RegExp;
  warning: RegExp;
};

STACK_FRAME_PATTERNS

Readonly array of regex patterns for stack frame detection — V8/Node, Firefox (bare and named), Chrome DevTools anonymous, and functionName @ file.js:123 forms.

const STACK_FRAME_PATTERNS: readonly RegExp[];

import { STACK_FRAME_PATTERNS } from 'logpare';

const isFrame = STACK_FRAME_PATTERNS.some((p) => p.test(line));

Utility Functions

detectSeverity()

Detect severity level from a log line.

function detectSeverity(line: string): Severity;

Example:

import { detectSeverity } from 'logpare';

detectSeverity('ERROR Connection failed');  // 'error'
detectSeverity('WARN Deprecated API');      // 'warning'
detectSeverity('INFO Request completed');   // 'info'

isStackFrame()

Check if a line is a stack frame.

function isStackFrame(line: string): boolean;

Example:

import { isStackFrame } from 'logpare';

isStackFrame('    at Function.name (file.js:123:45)');  // true
isStackFrame('ERROR Connection failed');                 // false

extractUrls()

Extract URLs/hostnames from a log line.

function extractUrls(line: string): string[];

Example:

import { extractUrls } from 'logpare';

extractUrls('GET https://api.example.com/users');
// ['api.example.com']

extractUrls('Fetched http://cdn.example.com/image.png');
// ['cdn.example.com']

Other diagnostic extractors

These back the corresponding Template.*Samples fields and are exported for direct use.

function extractFullUrls(line: string): string[];       // complete URLs, not just hostnames
function extractStatusCodes(line: string): number[];    // status 404, HTTP/1.1 500, code=200
function extractCorrelationIds(line: string): string[]; // trace-id: xxx, request-id: xxx, UUIDs
function extractDurations(line: string): string[];      // ms, s, sec, µs, us, ns, min, h, hr

Run them on the raw line, before masking — the default patterns replace most of what they look for with <*>.

Classes

Drain

The Drain instance class, exported alongside createDrain() for instanceof checks and subclassing.

class Drain {
  constructor(options?: DrainOptions);
  addLogLine(line: string): LogCluster | null;
  addLogLines(lines: string[]): void;
  getTemplates(): Template[];
  getResult(format?: OutputFormat, maxTemplates?: number): CompressionResult;
  get totalLines(): number;
  get totalClusters(): number;
}

LogCluster is internal and is not exported from logpare. Read templates through getTemplates() or getResult().

Strategy Helpers

defineStrategy()

Create a custom preprocessing strategy.

function defineStrategy(
  overrides: Partial<ParsingStrategy> & { patterns?: Record<string, RegExp> }
): ParsingStrategy;

Anything you do not override falls back to the default strategy. The extra patterns key is a shortcut: supply additional regexes and they are merged over DEFAULT_PATTERNS once, at definition time, and used to build preprocess for you. Supplying your own preprocess takes precedence and ignores patterns.

Example:

import { defineStrategy } from 'logpare';

// Custom tokenization, default masking
const csv = defineStrategy({
  tokenize: (line) => line.split(','),
  getSimThreshold: () => 0.5,
});

// Default masking plus your own patterns
const withIds = defineStrategy({
  patterns: {
    orderId: /order-[A-Z0-9]{8}/g,
    sessionId: /sess_[a-f0-9]{32}/gi,
  },
});

See Also

• compress() API
• compressText() API
• createDrain() API
• Custom Preprocessing Guide