cmpstr 2.0.2 → 3.0.0

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

@@ -0,0 +1,76 @@
+/**
+ * Normalizer Utility
+ * src/utils/Normalizer.ts
+ *
+ * @see https://en.wikipedia.org/wiki/Text_normalization
+ * @see https://en.wikipedia.org/wiki/Unicode_equivalence
+ *
+ * This module provides a Normalizer class that allows for string normalization based
+ * on various flags. It uses a pipeline of normalization functions that can be reused
+ * and cached for efficiency. The Normalizer can handle both single strings and arrays
+ * of strings, and supports synchronous and asynchronous normalization.
+ *
+ * Supported flags:
+ *  'd' :: Normalize to NFD (Normalization Form Decomposed)
+ *  'u' :: Normalize to NFC (Normalization Form Composed)
+ *  'x' :: Normalize to NFKC (Normalization Form Compatibility Composed)
+ *  'w' :: Collapse whitespace
+ *  't' :: Remove leading and trailing whitespace
+ *  'r' :: Remove double characters
+ *  's' :: Remove punctuation / special characters
+ *  'k' :: Remove non-letter characters
+ *  'n' :: Remove non-number characters
+ *  'i' :: Case insensitive (convert to lowercase)
+ *
+ * @module Utils/Normalizer
+ * @author Paul Köhler (komed3)
+ * @license MIT
+ */
+import type { NormalizeFlags } from './Types';
+/**
+ * The Normalizer class providing methods to normalize strings based on various flags.
+ */
+export declare class Normalizer {
+    /**
+     * A map that holds normalization functions based on the flags.
+     * This allows for reusing normalization logic without recomputing it.
+     */
+    private static pipeline;
+    /**
+     * A cache to store normalized strings based on the flags and input.
+     * This helps avoid recomputing normalization for the same input and flags.
+     */
+    private static cache;
+    /**
+     * Returns a normalization function based on the provided flags.
+     * The flags are a string of characters that define the normalization steps.
+     *
+     * @param {NormalizeFlags} flags - A string of characters representing the normalization steps
+     * @returns {NormalizerFn} - A function that normalizes a string based on the provided flags
+     */
+    private static getPipeline;
+    /**
+     * Normalizes the input string or array of strings based on the provided flags.
+     * The flags are a string of characters that define the normalization steps.
+     *
+     * @param {string|string[]} input - The string or array of strings to normalize
+     * @param {NormalizeFlags} flags - A string of characters representing the normalization steps
+     * @returns {string|string[]} - The normalized string(s)
+     */
+    static normalize(input: string | string[], flags: NormalizeFlags): string | string[];
+    /**
+     * Asynchronously normalizes the input string or array of strings based on the
+     * provided flags. This method is useful for handling large inputs or when
+     * normalization needs to be done in a non-blocking way.
+     *
+     * @param {string|string[]} input - The string or array of strings to normalize
+     * @param {NormalizeFlags} flags - A string of characters representing the normalization steps
+     * @returns {Promise<string|string[]>} - A promise that resolves to the normalized string(s)
+     */
+    static normalizeAsync(input: string | string[], flags: NormalizeFlags): Promise<string | string[]>;
+    /**
+     * Clears the normalization pipeline and cache.
+     * This is useful for resetting the state of the Normalizer.
+     */
+    static clear(): void;
+}

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

@@ -0,0 +1,63 @@
+/**
+ * Pool Utility
+ * src/utils/Pool.ts
+ *
+ * @see https://en.wikipedia.org/wiki/Circular_buffer
+ *
+ * The Pool class provides a simple and efficient buffer pool for dynamic programming
+ * algorithms that require temporary arrays (such as Levenshtein, LCS, etc.).
+ * By reusing pre-allocated typed arrays, it reduces memory allocations and garbage
+ * collection overhead, especially for repeated or batch computations.
+ *
+ * It supports different types of buffers (Uint16Array, number[], Set, Map) and allows
+ * for acquiring buffers of specific sizes while managing a maximum pool size.
+ *
+ * @module Utils/Pool
+ * @author Paul Köhler (komed3)
+ * @license MIT
+ */
+import type { PoolType } from './Types';
+/**
+ * The Pool class provides a buffer pool for dynamic programming algorithms.
+ *
+ * It allows for efficient reuse of buffers (Uint16Array, number[], Set, Map)
+ * to reduce memory allocations and garbage collection overhead.
+ */
+export declare class Pool {
+    private static readonly CONFIG;
+    private static readonly POOLS;
+    /**
+     * Allocates a new buffer of the specified type and size.
+     *
+     * @param {PoolType} type - The type of buffer to allocate
+     * @param {number} size - The size of the buffer to allocate
+     * @return {any} - The newly allocated buffer
+     */
+    private static allocate;
+    /**
+     * Acquires a buffer of the specified type and size from the pool.
+     * If no suitable buffer is available, it allocates a new one.
+     *
+     * @param {PoolType} type - The type of buffer to acquire (e.g., 'uint16', 'number[]', 'set', 'map')
+     * @param {number} size - The size of the buffer to acquire
+     * @return {T} - The acquired buffer of the specified type
+     */
+    static acquire<T = any>(type: PoolType, size: number): T;
+    /**
+     * Acquires multiple buffers of the specified type and sizes from the pool.
+     *
+     * @param {PoolType} type - The type of buffers to acquire
+     * @param {number[]} sizes - An array of sizes for each buffer to acquire
+     * @return {T[]} - An array of acquired buffers of the specified type
+     */
+    static acquireMany<T = any>(type: PoolType, sizes: number[]): T[];
+    /**
+     * Releases a buffer back to the pool.
+     * If the size of the buffer is larger than the maximum item size, it will not be released.
+     *
+     * @param {PoolType} type - The type of buffer to release
+     * @param {T} buffer - The buffer to release
+     * @param {number} size - The size of the buffer
+     */
+    static release<T = any>(type: PoolType, buffer: T, size: number): void;
+}

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

@@ -0,0 +1,129 @@
+/**
+ * Profiler Utility
+ * src/utils/profiler.ts
+ *
+ * @see https://en.wikipedia.org/wiki/Profiling_(computer_programming)
+ *
+ * This class provides methods to run synchronous and asynchronous functions, capturing
+ * their execution time and memory usage, and storing the results in a set of profiler
+ * entries. It supports both Node.js and browser environments, detecting the environment
+ * automatically.
+ *
+ * The class is optimized for minimal overhead and can be used for fine-grained
+ * performance profiling.
+ *
+ * @module Utils/Profiler
+ * @author Paul Köhler (komed3)
+ * @license MIT
+ */
+import type { ProfilerEntry, ProfilerService } from './Types';
+/**
+ * Profiler class for measuring execution time and memory usage of functions.
+ */
+export declare class Profiler {
+    private static ENV;
+    private static instance;
+    private store;
+    private totalTime;
+    private totalMem;
+    private active;
+    /**
+     * Sets the environment based on the available global objects.
+     * Detects if running in Node.js or browser and sets the ENV property accordingly.
+     */
+    protected static detectEnv(): void;
+    /**
+     * Returns the singleton instance of the Perf class.
+     * If the instance does not exist, it creates a new one.
+     *
+     * @param {boolean} [enable=false] - Optional parameter to enable the profiler upon instantiation
+     * @returns {Profiler} - Singleton Profiler instance
+     */
+    static getInstance(enable?: boolean): Profiler;
+    /**
+     * Private constructor to enforce singleton pattern.
+     * Initializes the store for profiler entries.
+     *
+     * @param {boolean} [enable=false] - Optional parameter to enable the profiler
+     */
+    private constructor();
+    /**
+     * Gets the current time based on the environment.
+     *
+     * Uses process.hrtime.bigint() for Node.js, performance.now() for browsers,
+     * and Date.now() as a fallback.
+     *
+     * @returns {number} - Current time in milliseconds
+     */
+    private now;
+    /**
+     * Gets the current memory usage based on the environment.
+     *
+     * Uses process.memoryUsage().heapUsed for Node.js, performance.memory.usedJSHeapSize
+     * for browsers, and returns 0 as a fallback.
+     *
+     * @returns {number} - Current memory usage in bytes
+     */
+    private mem;
+    /**
+     * Enables the profiler.
+     * Sets the active state to true, allowing profiling to occur.
+     */
+    enable(): void;
+    /**
+     * Disables the profiler.
+     * Sets the active state to false, preventing further profiling.
+     */
+    disable(): void;
+    /**
+     * Resets the profiler by clearing the store, total time and memory consumption.
+     * This method is useful for starting a new profiling session.
+     */
+    clear(): void;
+    /**
+     * Runs a synchronous function and profiles its execution time and memory usage.
+     * If the profiler is not active, it simply executes the function without profiling.
+     *
+     * @param {() => T} fn - Function to be executed and profiled
+     * @param {Record<string, any>} meta - Metadata to be associated with the profiling entry
+     * @returns {T} - The result of the executed function
+     */
+    run<T>(fn: () => T, meta?: Record<string, any>): T;
+    /**
+     * Runs an asynchronous function and profiles its execution time and memory usage.
+     * If the profiler is not active, it simply executes the function without profiling.
+     *
+     * @param {() => Promise<T>} fn - Asynchronous function to be executed and profiled
+     * @param {Record<string, any>} meta - Metadata to be associated with the profiling entry
+     * @returns {Promise<T>} - A promise that resolves to the result of the executed function
+     */
+    runAsync<T>(fn: () => Promise<T>, meta?: Record<string, any>): Promise<T>;
+    /**
+     * Retrieves all profiler entries stored in the profiler.
+     *
+     * @returns {ProfilerEntry<any>[]} - An array of profiler entries
+     */
+    getAll(): ProfilerEntry<any>[];
+    /**
+     * Retrieves the last profiler entry stored in the profiler.
+     *
+     * @returns {ProfilerEntry<any> | undefined} - The last profiler entry or undefined if no entries exist
+     */
+    getLast(): ProfilerEntry<any> | undefined;
+    /**
+     * Retrieves the total time and memory consumption recorded by the profiler.
+     *
+     * @returns {{ time: number, mem: number }} - An object containing total time and memory usage
+     */
+    getTotal(): {
+        time: number;
+        mem: number;
+    };
+    /**
+     * Returns the services provided by the Profiler class.
+     * This allows for easy access to the profiler's methods.
+     *
+     * @returns {ProfilerService<any>} - An object containing methods to control the profiler
+     */
+    services: ProfilerService<any>;
+}

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

@@ -0,0 +1,57 @@
+/**
+ * Registry Utility
+ * src/utils/Registry.ts
+ *
+ * This module provides a Registry function that allows for registering,
+ * removing, checking, getting, and listing class constructors.
+ *
+ * It is designed to manage class extensions, ensuring that all registered
+ * classes extend a specified base constructor.
+ *
+ * @module Utils/Registry
+ * @author Paul Köhler (komed3)
+ * @license MIT
+ */
+import type { RegistryService, RegistryConstructor } from './Types';
+/**
+ * Global registry object to hold multiple registries.
+ * Each registry is keyed by a string identifier.
+ *
+ * @type {Record<string, RegistryService<any>>}
+ */
+export declare const registry: Record<string, RegistryService<any>>;
+/**
+ * Factory object to hold factory functions for creating instances.
+ * This is used to create instances of registered classes.
+ *
+ * @type {Record<string, ( cls: string, ...args: any[] ) => InstanceType<any>>}
+ */
+export declare const factory: Record<string, (cls: string, ...args: any[]) => InstanceType<any>>;
+/**
+ * Registry function to create a service for managing class constructors.
+ *
+ * @param {string} reg - The name of the registry
+ * @param {RegistryConstructor<T>} ctor - The base constructor that all registered classes must extend
+ * @returns {RegistryService<T>} - An object with methods to register, remove, check, get, and list classes
+ * @throws {Error} If the registry already exists (overwriting is forbidden)
+ */
+export declare function Registry<T>(reg: string, ctor: RegistryConstructor<T>): RegistryService<T>;
+/**
+ * Resolve a class constructor from a specific registry.
+ *
+ * @param {string} reg - The name of the registry
+ * @param {T|string} cls - The class itself or name of the class to resolve
+ * @returns {T|undefined} - The class constructor if found, otherwise undefined
+ * @throws {ReferenceError} If the registry does not exist
+ */
+export declare function resolveCls<T extends RegistryConstructor<any>>(reg: string, cls: T | string): T;
+/**
+ * Create an instance of a class from a specific registry.
+ *
+ * @param {string} reg - The name of the registry
+ * @param {T|string} cls - The class itself or name of the class to instantiate
+ * @param {...any} args - Arguments to pass to the class constructor
+ * @returns {T} - An instance of the class
+ * @throws {Error} If the class cannot be instantiated
+ */
+export declare function createFromRegistry<T extends RegistryConstructor<any>>(reg: string, cls: T | string, ...args: any[]): InstanceType<T>;

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

@@ -0,0 +1,199 @@
+/**
+ * TextAnalyzer Utility
+ * src/utils/TextAnalyzer.ts
+ *
+ * The TextAnalyzer class provides a comprehensive set of methods for analyzing and
+ * extracting statistics from a given text. It supports word and sentence tokenization,
+ * character and word frequency analysis, syllable estimation, readability metrics
+ * (Flesch, Kincaid, LIX, WSTF), and various ratios and histograms. Designed for
+ * efficiency and flexibility, it is suitable for linguistic research, readability
+ * scoring, and text preprocessing tasks.
+ *
+ * @module Utils/TextAnalyzer
+ * @author Paul Köhler (komed3)
+ * @license MIT
+ */
+export declare class TextAnalyzer {
+    private readonly text;
+    private words;
+    private sentences;
+    private charFrequency;
+    private wordHistogram;
+    private syllableCache;
+    /**
+     * Constructs a new TextAnalyzer instance with the provided input text.
+     *
+     * @param {string} input - The text to analyze
+     */
+    constructor(input: string);
+    /**
+     * Tokenizes the input text into words and sentences.
+     */
+    private tokenize;
+    /**
+     * Computes character and word frequencies from the tokenized text.
+     */
+    private computeFrequencies;
+    /**
+     * Estimates the number of syllables in a word using a simple heuristic.
+     *
+     * @param {string} word - The word to estimate syllables for
+     * @returns {number} - Estimated syllable count
+     */
+    private estimateSyllables;
+    /**
+     * Gets the original text length in characters.
+     *
+     * @return {number} - Length of the text
+     */
+    getLength(): number;
+    /**
+     * Gets the number of words in the text.
+     *
+     * @return {number} - Count of words
+     */
+    getWordCount(): number;
+    /**
+     * Gets the number of sentences in the text.
+     *
+     * @return {number} - Count of sentences
+     */
+    getSentenceCount(): number;
+    /**
+     * Gets the average word length in the text.
+     *
+     * @return {number} - Average length of words
+     */
+    getAvgWordLength(): number;
+    /**
+     * Gets the average sentence length in words.
+     *
+     * @return {number} - Average length of sentences
+     */
+    getAvgSentenceLength(): number;
+    /**
+     * Gets a histogram of word frequencies in the text.
+     *
+     * @returns {Record<string, number>} - A histogram of word frequencies
+     */
+    getWordHistogram(): Record<string, number>;
+    /**
+     * Gets the most common words in the text, limited to a specified number.
+     *
+     * @param {number} [limit=5] - Maximum number of common words to return
+     * @returns {string[]} - Array of the most common words
+     */
+    getMostCommonWords(limit?: number): string[];
+    /**
+     * Gets the least common words (hapax legomena) in the text.
+     *
+     * Hapax legomena are words that occur only once in the text.
+     *
+     * @returns {string[]} - Array of hapax legomena
+     */
+    getHapaxLegomena(): string[];
+    /**
+     * Checks if the text contains any numbers.
+     *
+     * @returns {boolean} - True if numbers are present, false otherwise
+     */
+    hasNumbers(): boolean;
+    /**
+     * Calculates the ratio of uppercase letters to total letters in the text.
+     *
+     * @return {number} - Ratio of uppercase letters to total letters
+     */
+    getUpperCaseRatio(): number;
+    /**
+     * Gets the frequency of each character in the text.
+     *
+     * @returns {Record<string, number>} - A record of character frequencies
+     */
+    getCharFrequency(): Record<string, number>;
+    /**
+     * Gets the frequency of each Unicode block in the text.
+     *
+     * @returns {Record<string, number>} - A record of Unicode block frequencies
+     */
+    getUnicodeStats(): Record<string, number>;
+    /**
+     * Gets the ratio of long words (words with length >= len) to total words.
+     *
+     * @param {number} [len=7] - Minimum length for a word to be considered long
+     * @returns {number} - Ratio of long words to total words
+     */
+    getLongWordRatio(len?: number): number;
+    /**
+     * Gets the ratio of short words (words with length <= len) to total words.
+     *
+     * @param {number} [len=3] - Maximum length for a word to be considered short
+     * @returns {number} - Ratio of short words to total words
+     */
+    getShortWordRatio(len?: number): number;
+    /**
+     * Estimates the number of syllables in the text.
+     *
+     * @returns {number} - Total estimated syllable count
+     */
+    getSyllablesCount(): number;
+    /**
+     * Gets the number of monosyllabic words (words with exactly one syllable).
+     *
+     * @returns {number} - Count of monosyllabic words
+     */
+    getMonosyllabicWordCount(): number;
+    /**
+     * Gets the number of words with at least a specified minimum syllable count.
+     *
+     * @param {number} min - Minimum syllable count for a word to be included
+     * @returns {number} - Count of words meeting the syllable criteria
+     */
+    getMinSyllablesWordCount(min: number): number;
+    /**
+     * Gets the number of words with at most a specified maximum syllable count.
+     *
+     * @param {number} max - Maximum syllable count for a word to be included
+     * @returns {number} - Count of words meeting the syllable criteria
+     */
+    getMaxSyllablesWordCount(max: number): number;
+    /**
+     * Calculates the Honore's R statistic for the text as a measure of lexical richness.
+     *
+     * @returns {number} - The Honore's R statistic
+     */
+    getHonoresR(): number;
+    /**
+     * Estimates the reading time for the text based on words per minute (WPM).
+     *
+     * @param {number} [wpm=200] - Words per minute for the calculation
+     * @returns {number} - Estimated reading time in minutes
+     */
+    getReadingTime(wpm?: number): number;
+    /**
+     * Calculates various readability scores based on the text.
+     *
+     * This method supports multiple readability metrics:
+     *  - Flesch Reading Ease
+     *  - Flesch-Kincaid Grade Level
+     *
+     * @param {'flesch'|'fleschde'|'kincaid'} [metric='flesch'] - The readability metric to calculate
+     * @returns {number} - The calculated readability score
+     */
+    getReadabilityScore(metric?: 'flesch' | 'fleschde' | 'kincaid'): number;
+    /**
+     * Calculates the LIX (Lesbarhetsindex) score for the text.
+     *
+     * The LIX score is a readability index that combines average word length and sentence length.
+     *
+     * @returns {number} - The LIX score
+     */
+    getLIXScore(): number;
+    /**
+     * Calculates the Wiener Sachtextformel (WSTF) scores for the text.
+     *
+     * The WSTF scores are a set of readability metrics based on word and sentence characteristics.
+     *
+     * @returns {[number, number, number, number]} - An array of WSTF scores
+     */
+    getWSTFScore(): [number, number, number, number];
+}