cmpstr/dist/types/utils/Types.d.ts

CmpStr is a lightweight, fast and well performing package for calculating string similarity

/**
 * Types and Interfaces for CmpStr
 * src/utils/Types.ts
 *
 * This file defines all core types, interfaces, and utility type aliases used throughout
 * the CmpStr package. It provides type safety and documentation for all major components,
 * including metrics, phonetic algorithms, filters, normalization, diffing, and profiling.
 *
 * All interfaces are designed for extensibility and clarity, supporting both internal
 * implementation and external usage in user code.
 *
 * @module Utils/Types
 * @author Paul Köhler (komed3)
 * @license MIT
 */
/**
 * ProfilerEntry represents a single profiling result, including execution time,
 * memory usage, the result of the profiled function, and optional metadata.
 *
 * @template T - The type of the profiled result
 */
export interface ProfilerEntry<T> {
    time: number;
    mem: number;
    res: T;
    meta?: Record<string, any>;
}
/**
 * ProfilerService defines the API for the Profiler utility, providing methods
 * to enable/disable profiling, clear results, retrieve reports, and get totals.
 *
 * @template T - The type of the profiled result
 */
export interface ProfilerService<T> {
    enable: () => void;
    disable: () => void;
    clear: () => void;
    report: () => ProfilerEntry<T>[];
    last: () => ProfilerEntry<T> | undefined;
    total: () => {
        time: number;
        mem: number;
    };
}
/**
 * PoolType enumerates the supported buffer types for the Pool utility.
 */
export type PoolType = 'uint16' | 'number[]' | 'set' | 'map';
/**
 * PoolConfig defines the configuration for a buffer pool.
 */
export interface PoolConfig {
    type: PoolType;
    maxSize: number;
    maxItemSize: number;
    allowOversize: boolean;
}
/**
 * PoolBuffer represents a buffer and its size in the pool.
 *
 * @template T - The buffer type
 */
export interface PoolBuffer<T> {
    buffer: T;
    size: number;
}
/**
 * NormalizerFn defines the signature for a normalization function.
 * It takes a string and returns a normalized string.
 */
export type NormalizerFn = (input: string) => string;
/**
 * NormalizeFlags is a string representing a sequence of normalization steps.
 * Each character or substring corresponds to a specific normalization operation.
 */
export type NormalizeFlags = string;
/**
 * FilterFn defines the signature for a filter function.
 * It takes a string and returns the filtered string.
 */
export type FilterFn = (input: string) => string;
/**
 * FilterOptions configures the behavior of a filter entry.
 */
export interface FilterOptions {
    priority?: number;
    active?: boolean;
    overrideable?: boolean;
}
/**
 * FilterEntry represents a single filter in the filter system.
 */
export interface FilterEntry {
    id: string;
    fn: FilterFn;
    priority: number;
    active: boolean;
    overrideable: boolean;
}
/**
 * RegistryConstructor is a type alias for a class constructor used in registries.
 *
 * @template T - The class type
 */
export type RegistryConstructor<T> = abstract new (...args: any[]) => T;
/**
 * RegistryService defines the API for a generic registry of classes.
 *
 * @template T - The class type managed by the registry
 */
export interface RegistryService<T> {
    add: (name: string, cls: RegistryConstructor<T>, update?: boolean) => void;
    remove: (name: string) => void;
    has: (name: string) => boolean;
    get: (name: string) => RegistryConstructor<T>;
    list: () => string[];
}
/**
 * MetricInput represents the input for metric computations.
 * It can be a single string or an array of strings.
 */
export type MetricInput = string | string[];
/**
 * MetricMode specifies the computation mode for metrics.
 *  - 'default': single or batch comparison related to input
 *  - 'batch': compare multiple strings
 *  - 'single': runs a single comparison
 *  - 'pairwise': compare arrays element-wise
 */
export type MetricMode = 'default' | 'batch' | 'single' | 'pairwise';
/**
 * MetricOptions configures the behavior of metric computations.
 */
export interface MetricOptions {
    mode?: MetricMode;
    delimiter?: string;
    pad?: string;
    q?: number;
    match?: number;
    mismatch?: number;
    gap?: number;
}
/**
 * MetricRaw is a generic record for storing raw metric-specific data.
 */
export type MetricRaw = Record<string, any>;
/**
 * MetricCompute represents the result of a metric computation.
 *
 * @template R - The type of the raw result
 */
export interface MetricCompute<R = MetricRaw> {
    res: number;
    raw?: R;
}
/**
 * MetricResultSingle represents the result of a single metric comparison.
 *
 * @template R - The type of the raw result
 */
export interface MetricResultSingle<R = MetricRaw> {
    metric: string;
    a: string;
    b: string;
    res: number;
    raw?: R;
}
/**
 * MetricResultBatch is an array of single metric results for batch operations.
 *
 * @template R - The type of the raw result
 */
export type MetricResultBatch<R = MetricRaw> = MetricResultSingle<R>[];
/**
 * MetricResult is a union of single and batch metric results.
 *
 * @template R - The type of the raw result
 */
export type MetricResult<R = MetricRaw> = MetricResultSingle<R> | MetricResultBatch<R>;
/**
 * PhoneticOptions configures the behavior of phonetic algorithms.
 */
export interface PhoneticOptions {
    map?: string;
    delimiter?: string;
    length?: number;
    pad?: string;
    dedupe?: boolean;
}
/**
 * PhoneticRule defines a single rule for phonetic mapping.
 */
export interface PhoneticRule {
    char: string;
    code: string;
    position?: 'start' | 'middle' | 'end';
    prev?: string[];
    prevNot?: string[];
    prev2?: string[];
    prev2Not?: string[];
    next?: string[];
    nextNot?: string[];
    next2?: string[];
    next2Not?: string[];
    leading?: string;
    trailing?: string;
    match?: string[];
}
/**
 * PhoneticMap defines a mapping for a specific phonetic algorithm and language.
 */
export interface PhoneticMap {
    map: Record<string, string>;
    ruleset?: PhoneticRule[];
    ignore?: string[];
}
/**
 * PhoneticMapping is a record of named phonetic maps for an algorithm.
 */
export type PhoneticMapping = Record<string, PhoneticMap>;
/**
 * PhoneticMappingService defines the API for managing phonetic mappings.
 */
export interface PhoneticMappingService {
    add: (algo: string, id: string, map: PhoneticMap, update?: boolean) => void;
    remove: (algo: string, id: string) => void;
    has: (algo: string, id: string) => boolean;
    get: (algo: string, id: string) => PhoneticMap | undefined;
    list: (algo: string) => string[];
}
/**
 * DiffMode specifies the granularity for diffing.
 *  - 'line': line-based diff
 *  - 'word': word-based diff
 */
export type DiffMode = 'line' | 'word';
/**
 * DiffOptions configures the behavior of the DiffChecker utility.
 */
export interface DiffOptions {
    mode?: DiffMode;
    caseInsensitive?: boolean;
    contextLines?: number;
    groupedLines?: boolean;
    expandLines?: boolean;
    showChangeMagnitude?: boolean;
    maxMagnitudeSymbols?: number;
    lineBreak?: string;
}
/**
 * DiffEntry represents a single change (insertion or deletion) in a diff.
 */
export interface DiffEntry {
    posA: number;
    posB: number;
    del: string;
    ins: string;
    size: number;
}
/**
 * DiffLine represents the diff for a single line, including all changes.
 */
export interface DiffLine {
    line: number;
    diffs: DiffEntry[];
    delSize: number;
    insSize: number;
    totalSize: number;
    baseLen: number;
    magnitude: string;
}
/**
 * DiffGroup represents a group of adjacent changed lines in a diff.
 */
export interface DiffGroup {
    line: number;
    start: number;
    end: number;
    entries: DiffLine[];
    delSize: number;
    insSize: number;
    totalSize: number;
    magnitude: string;
}
/**
 * CmpStrProcessors defines pre-processors for input strings before comparison.
 */
export interface CmpStrProcessors {
    phonetic?: {
        algo: string;
        opt?: PhoneticOptions;
    };
}
/**
 * CmpStrOptions configures the behavior of a CmpStr instance.
 */
export interface CmpStrOptions {
    raw?: boolean;
    removeZero?: boolean;
    flags?: NormalizeFlags;
    metric?: string;
    opt?: MetricOptions;
    processors?: CmpStrProcessors;
    output?: 'orig' | 'prep';
}
/**
 * CmpStrResult represents a simplified result for user-facing API methods.
 */
export interface CmpStrResult {
    source: string;
    target: string;
    match: number;
}