cmpstr 2.0.2 → 3.0.0

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

@@ -0,0 +1,313 @@
+/**
+ * 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;
+}

package/package.json

@@ -1,49 +1,62 @@
-{
-  "name": "cmpstr",
-  "description": "lightweight npm package to calculate string similarity",
-  "author": {
-    "name" : "komed3 (Paul Köhler)",
-    "email" : "webmaster@komed3.de",
-    "url" : "https://komed3.de"
-  },
-  "homepage": "https://github.com/komed3/cmpstr#readme",
-  "version": "2.0.2",
-  "main": "src/index.js",
-  "types": "src/index.d.ts",
-  "license": "MIT",
-  "keywords": [
-    "string-similarity",
-    "string-comparison",
-    "similarity-algorithms",
-    "phonetic-search",
-    "soundex",
-    "levenshtein-distance",
-    "damerau-levenshtein",
-    "jaro-winkler",
-    "cosine-similarity",
-    "dice-coefficient",
-    "jaccard-index",
-    "hamming-distance",
-    "longest-common-subsequence",
-    "needleman-wunsch",
-    "smith-waterman",
-    "q-gram",
-    "similarity-matrix",
-    "batch-operations",
-    "normalization",
-    "asynchronous",
-    "custom-algorithms",
-    "text-processing",
-    "fuzzy-matching",
-    "string-matching",
-    "text-similarity",
-    "typescript-definitions"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/komed3/cmpstr.git"
-  },
-  "bugs": {
-    "url": "https://github.com/komed3/cmpstr/issues"
-  }
-}
+{
+  "name": "cmpstr",
+  "description": "CmpStr is a lightweight, fast and well performing package for calculating string similarity",
+  "license": "MIT",
+  "version": "3.0.0",
+  "author": {
+    "name": "komed3 (Paul Köhler)",
+    "email": "webmaster@komed3.de",
+    "url": "https://komed3.de"
+  },
+  "homepage": "https://github.com/komed3/cmpstr",
+  "keywords": [
+    "string-similarity", "string-comparison", "fuzzy-matching", "phonetic-search",
+    "phonetic-algorithms", "similarity-metrics", "batch-processing", "text-search",
+    "pairwise-comparison", "normalization", "filtering", "text-analysis", "diff",
+    "diffing", "typescript", "asynchronous", "custom-algorithms", "metrics",
+    "algorithms", "levenshtein", "damerau-levenshtein", "jaro-winkler", "cosine",
+    "dice-coefficient", "hamming-distance", "jaccard-index", "needleman-wunsch",
+    "lcs", "smith-waterman", "q-gram", "soundex", "metaphone", "cologne-phonetic",
+    "profiling", "extensible"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/komed3/cmpstr.git"
+  },
+  "bugs": {
+    "url": "https://github.com/komed3/cmpstr/issues"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "main": "dist/cjs/index.js",
+  "types": "dist/types/index.d.ts",
+  "module": "dist/esm/index.js",
+  "browser": "dist/CmpStr.umd.min.js",
+  "exports": {
+    "require": "./dist/cjs/index.js",
+    "import": "./dist/esm/index.js"
+  },
+  "type": "module",
+  "scripts": {
+    "test": "vitest run",
+    "build": "rollup -c && tsc --project tsconfig.build.json",
+    "lint": "tsc --project tsconfig.lint.json",
+    "clean": "rm -rf dist"
+  },
+  "devDependencies": {
+    "@rollup/plugin-commonjs": "^28.0.3",
+    "@rollup/plugin-node-resolve": "^16.0.1",
+    "@rollup/plugin-terser": "^0.4.4",
+    "@rollup/plugin-typescript": "^12.1.2",
+    "@types/node": "^22.15.23",
+    "prettier": "^3.5.3",
+    "rollup": "^4.41.1",
+    "rollup-plugin-prettier": "^4.1.2",
+    "tslib": "^2.8.1",
+    "typescript": "^5.8.3",
+    "vitest": "^3.2.2"
+  }
+}

package/src/CmpStr.d.ts

@@ -1,70 +0,0 @@
-export interface Config {
-    flags?: string;
-    threshold?: number;
-    options?: Record<string, any>;
-}
-
-export interface BatchResult {
-    target: string;
-    match: number | any;
-}
-
-export declare class CmpStr {
-
-    constructor ( algo?: string, str?: string );
-
-    isReady () : boolean;
-
-    setStr ( str: string ) : boolean;
-
-    getStr () : string;
-
-    listAlgo ( loadedOnly?: boolean ) : string[];
-
-    isAlgo ( algo: string ) : boolean;
-
-    setAlgo ( algo: string ) : boolean;
-
-    getAlgo () : string;
-
-    addAlgo ( algo: string, callback: (
-        a: string, b: string, ...args : any
-    ) => number | any, useIt?: boolean ) : boolean;
-
-    rmvAlgo( algo: string ) : boolean;
-
-    listFilter () : string[];
-
-    addFilter ( name: string, callback: (
-        str: string
-    ) => string, priority?: number ) : boolean;
-
-    rmvFilter ( name: string ) : boolean;
-
-    pauseFilter ( name: string ) : boolean;
-
-    resumeFilter ( name: string ) : boolean;
-
-    clearFilter () : boolean;
-
-    setFlags( flags: string ) : void;
-
-    getFlags () : string;
-
-    normalize ( input: string|string[], flags?: string ) : string|string[];
-
-    clearCache () : boolean;
-
-    compare ( algo: string, a: string, b: string, config?: Config ) : number | any;
-
-    test ( str: string, config?: Config ) : number | any;
-
-    batchTest ( arr: string[], config?: Config ) : BatchResult[];
-
-    match ( arr: string[], config?: Config ) : BatchResult[];
-
-    closest ( arr: string[], config?: Config ) : string | undefined;
-
-    similarityMatrix ( algo: string, arr: string[], config?: Config ) : number[][];
-
-}