cmpstr 3.0.3 → 3.1.0

package/dist/types/CmpStr.d.ts

@@ -12,6 +12,7 @@
  *  - Flexible normalization and filtering pipeline for all inputs
  *  - Batch, pairwise, and single string comparison with detailed results
  *  - Phonetic indexing and phonetic-aware search and comparison
+ *  - Structured data comparison by extracting properties from objects
  *  - Text analysis and unified diff utilities
  *  - Full TypeScript type safety and extensibility
  *
@@ -19,11 +20,12 @@
  * @author Paul Köhler (komed3)
  * @license MIT
  */
-import type { CmpStrOptions, CmpStrProcessors, CmpStrResult, NormalizeFlags, DiffOptions, PhoneticOptions, MetricRaw, MetricInput, MetricMode, MetricResult, MetricResultSingle, MetricResultBatch } from './utils/Types';
+import type { CmpStrOptions, CmpStrProcessors, CmpStrResult, NormalizeFlags, DiffOptions, PhoneticOptions, MetricRaw, MetricInput, MetricMode, MetricResult, MetricResultSingle, MetricResultBatch, StructuredDataBatchResult, StructuredDataOptions } from './utils/Types';
 import { TextAnalyzer } from './utils/TextAnalyzer';
 import { DiffChecker } from './utils/DiffChecker';
 import { Normalizer } from './utils/Normalizer';
 import { Filter } from './utils/Filter';
+import { StructuredData } from './utils/StructuredData';
 import { Metric } from './metric';
 import { Phonetic } from './phonetic';
 /**
@@ -207,6 +209,15 @@ export declare class CmpStr<R = MetricRaw> {
         algo: string;
         opt?: PhoneticOptions;
     }): MetricInput;
+    /**
+     * Creates a instance for processing structured data.
+     *
+     * @template T - The type of objects in the data array
+     * @param {T[]} data - The array of structured objects
+     * @param {keyof T} key - The property key to compare
+     * @returns {StructuredData<T, R>} - The lookup instance
+     */
+    protected structured<T = any>(data: T[], key: keyof T): StructuredData<T, R>;
     /**
      * Computes the metric result for the given inputs, applying normalization and
      * filtering as configured.
@@ -362,7 +373,7 @@ export declare class CmpStr<R = MetricRaw> {
      * @param {CmpStrOptions} [opt] - Optional options
      * @returns {T} - The metric result
      */
-    test<T extends CmpStrResult | MetricResultSingle<R>>(a: string, b: string, opt?: CmpStrOptions): T;
+    test<T extends CmpStrResult | MetricResultSingle<R> = any>(a: string, b: string, opt?: CmpStrOptions): T;
     /**
      * Performs a single metric comparison and returns only the numeric score.
      *
@@ -382,7 +393,7 @@ export declare class CmpStr<R = MetricRaw> {
      * @param {CmpStrOptions} [opt] - Optional options
      * @returns {T} - The batch metric results
      */
-    batchTest<T extends CmpStrResult[] | MetricResultBatch<R>>(a: MetricInput, b: MetricInput, opt?: CmpStrOptions): T;
+    batchTest<T extends CmpStrResult[] | MetricResultBatch<R> = any>(a: MetricInput, b: MetricInput, opt?: CmpStrOptions): T;
     /**
      * Performs a batch metric comparison and returns results sorted by score.
      *
@@ -393,7 +404,7 @@ export declare class CmpStr<R = MetricRaw> {
      * @param {CmpStrOptions} [opt] - Optional options
      * @returns {T} - The sorted batch results
      */
-    batchSorted<T extends CmpStrResult[] | MetricResultBatch<R>>(a: MetricInput, b: MetricInput, dir?: 'desc' | 'asc', opt?: CmpStrOptions): T;
+    batchSorted<T extends CmpStrResult[] | MetricResultBatch<R> = any>(a: MetricInput, b: MetricInput, dir?: 'desc' | 'asc', opt?: CmpStrOptions): T;
     /**
      * Performs a pairwise metric comparison between source and target strings
      * or array of strings.
@@ -407,7 +418,7 @@ export declare class CmpStr<R = MetricRaw> {
      * @param {CmpStrOptions} [opt] - Optional options
      * @returns {T} - The pairwise metric results
      */
-    pairs<T extends CmpStrResult[] | MetricResultBatch<R>>(a: MetricInput, b: MetricInput, opt?: CmpStrOptions): T;
+    pairs<T extends CmpStrResult[] | MetricResultBatch<R> = any>(a: MetricInput, b: MetricInput, opt?: CmpStrOptions): T;
     /**
      * Performs a batch comparison and returns only results above the threshold.
      *
@@ -418,7 +429,7 @@ export declare class CmpStr<R = MetricRaw> {
      * @param {CmpStrOptions} [opt] - Optional options
      * @returns {T} - The filtered batch results
      */
-    match<T extends CmpStrResult[] | MetricResultBatch<R>>(a: MetricInput, b: MetricInput, threshold: number, opt?: CmpStrOptions): T;
+    match<T extends CmpStrResult[] | MetricResultBatch<R> = any>(a: MetricInput, b: MetricInput, threshold: number, opt?: CmpStrOptions): T;
     /**
      * Returns the n closest matches from a batch comparison.
      *
@@ -429,7 +440,7 @@ export declare class CmpStr<R = MetricRaw> {
      * @param {CmpStrOptions} [opt] - Optional options
      * @returns {T} - The closest matches
      */
-    closest<T extends CmpStrResult[] | MetricResultBatch<R>>(a: MetricInput, b: MetricInput, n?: number, opt?: CmpStrOptions): T;
+    closest<T extends CmpStrResult[] | MetricResultBatch<R> = any>(a: MetricInput, b: MetricInput, n?: number, opt?: CmpStrOptions): T;
     /**
      * Returns the n furthest matches from a batch comparison.
      *
@@ -440,7 +451,7 @@ export declare class CmpStr<R = MetricRaw> {
      * @param {CmpStrOptions} [opt] - Optional options
      * @returns {T} - The furthest matches
      */
-    furthest<T extends CmpStrResult[] | MetricResultBatch<R>>(a: MetricInput, b: MetricInput, n?: number, opt?: CmpStrOptions): T;
+    furthest<T extends CmpStrResult[] | MetricResultBatch<R> = any>(a: MetricInput, b: MetricInput, n?: number, opt?: CmpStrOptions): T;
     /**
      * Performs a normalized and filtered substring search.
      *
@@ -469,4 +480,75 @@ export declare class CmpStr<R = MetricRaw> {
      * @returns {string} - The phonetic index as a string
      */
     phoneticIndex(input: string, algo?: string, opt?: PhoneticOptions): string;
+    /**
+     * ---------------------------------------------------------------------------------
+     * Public methods for structured data comparison
+     * ---------------------------------------------------------------------------------
+     *
+     * These methods provide interfaces for comparing arrays of structured objects
+     * by extracting and comparing specific properties.
+     */
+    /**
+     * Performs a batch comparison against structured data by extracting
+     * a specific property and returning results with original objects attached.
+     *
+     * @template T - The type of objects in the data array
+     * @param {string} query - The query string to compare against
+     * @param {T[]} data - The array of structured objects
+     * @param {keyof T} key - The property key to extract for comparison
+     * @param {StructuredDataOptions} [opt] - Optional lookup options
+     * @returns {StructuredDataBatchResult<T, R>|T[]} - Batch results with original objects
+     */
+    structuredLookup<T = any>(query: string, data: T[], key: keyof T, opt?: StructuredDataOptions): StructuredDataBatchResult<T, R> | T[];
+    /**
+     * Performs a batch comparison and returns only results above the threshold
+     * for structured data.
+     *
+     * @template T - The type of objects in the data array
+     * @param {string} query - The query string to compare against
+     * @param {T[]} data - The array of structured objects
+     * @param {keyof T} key - The property key to extract for comparison
+     * @param {number} threshold - The similarity threshold (0..1)
+     * @param {StructuredDataOptions} [opt] - Optional lookup options
+     * @returns {StructuredDataBatchResult<T, R>|T[]} - Filtered batch results with objects
+     */
+    structuredMatch<T = any>(query: string, data: T[], key: keyof T, threshold: number, opt?: StructuredDataOptions): StructuredDataBatchResult<T, R> | T[];
+    /**
+     * Returns the n closest matches from a batch comparison of structured data.
+     *
+     * @template T - The type of objects in the data array
+     * @param {string} query - The query string to compare against
+     * @param {T[]} data - The array of structured objects
+     * @param {keyof T} key - The property key to extract for comparison
+     * @param {number} [n=1] - Number of closest matches
+     * @param {StructuredDataOptions} [opt] - Optional lookup options
+     * @returns {StructuredDataBatchResult<T, R>|T[]} - Closest matches with objects
+     */
+    structuredClosest<T = any>(query: string, data: T[], key: keyof T, n?: number, opt?: StructuredDataOptions): StructuredDataBatchResult<T, R> | T[];
+    /**
+     * Returns the n furthest matches from a batch comparison of structured data.
+     *
+     * @template T - The type of objects in the data array
+     * @param {string} query - The query string to compare against
+     * @param {T[]} data - The array of structured objects
+     * @param {keyof T} key - The property key to extract for comparison
+     * @param {number} [n=1] - Number of furthest matches
+     * @param {StructuredDataOptions} [opt] - Optional lookup options
+     * @returns {StructuredDataBatchResult<T, R>|T[]} - Furthest matches with objects
+     */
+    structuredFurthest<T = any>(query: string, data: T[], key: keyof T, n?: number, opt?: StructuredDataOptions): StructuredDataBatchResult<T, R> | T[];
+    /**
+     * Performs a pairwise comparison between two arrays of structured objects
+     * by extracting specific properties and returning results with original objects attached.
+     *
+     * @template T - The type of objects in the arrays
+     * @template O - The type of objects in the other array
+     * @param {T[]} data - The array of structured objects
+     * @param {keyof T} key - The property key to extract for comparison
+     * @param {O[]} other - The other array of structured objects
+     * @param {keyof O} otherKey - The property key to extract from other array
+     * @param {StructuredDataOptions} [opt] - Optional lookup options
+     * @returns {StructuredDataBatchResult<T, R>|T[]} - Pairwise results with original objects
+     */
+    structuredPairs<T = any, O = any>(data: T[], key: keyof T, other: O[], otherKey: keyof O, opt?: StructuredDataOptions): StructuredDataBatchResult<T, R> | T[];
 }

package/dist/types/CmpStrAsync.d.ts

@@ -11,6 +11,7 @@
  *  - Asynchronous normalization, filtering, and metric computation
  *  - Async batch, pairwise, and single string comparison with detailed results
  *  - Async phonetic indexing and phonetic-aware search and comparison
+ * - Async structured data comparison by extracting object properties
  *  - Full compatibility with the synchronous CmpStr API
  *  - Designed for large-scale, high-performance, and server-side applications
  *
@@ -18,7 +19,7 @@
  * @author Paul Köhler (komed3)
  * @license MIT
  */
-import type { CmpStrOptions, CmpStrProcessors, CmpStrResult, NormalizeFlags, PhoneticOptions, MetricRaw, MetricInput, MetricMode, MetricResult, MetricResultSingle, MetricResultBatch } from './utils/Types';
+import type { CmpStrOptions, CmpStrProcessors, CmpStrResult, NormalizeFlags, PhoneticOptions, MetricRaw, MetricInput, MetricMode, MetricResult, MetricResultSingle, MetricResultBatch, StructuredDataBatchResult, StructuredDataOptions } from './utils/Types';
 import { CmpStr } from './CmpStr';
 /**
  * The CmpStrAsync class provides a fully asynchronous API for string comparison,
@@ -123,7 +124,7 @@ export declare class CmpStrAsync<R = MetricRaw> extends CmpStr<R> {
      * @param {CmpStrOptions} [opt] - Optional options
      * @returns {Promise<T>} - The metric result
      */
-    testAsync<T extends CmpStrResult | MetricResultSingle<R>>(a: string, b: string, opt?: CmpStrOptions): Promise<T>;
+    testAsync<T extends CmpStrResult | MetricResultSingle<R> = any>(a: string, b: string, opt?: CmpStrOptions): Promise<T>;
     /**
      * Asynchronously performs a single metric comparison returning the numeric score.
      *
@@ -143,7 +144,7 @@ export declare class CmpStrAsync<R = MetricRaw> extends CmpStr<R> {
      * @param {CmpStrOptions} [opt] - Optional options
      * @returns {Promise<T>} - The batch metric results
      */
-    batchTestAsync<T extends CmpStrResult[] | MetricResultBatch<R>>(a: MetricInput, b: MetricInput, opt?: CmpStrOptions): Promise<T>;
+    batchTestAsync<T extends CmpStrResult[] | MetricResultBatch<R> = any>(a: MetricInput, b: MetricInput, opt?: CmpStrOptions): Promise<T>;
     /**
      * Asynchronously performs a batch metric comparison and returns results sorted by score.
      *
@@ -154,7 +155,7 @@ export declare class CmpStrAsync<R = MetricRaw> extends CmpStr<R> {
      * @param {CmpStrOptions} [opt] - Optional options
      * @returns {Promise<T>} - The sorted batch results
      */
-    batchSortedAsync<T extends CmpStrResult[] | MetricResultBatch<R>>(a: MetricInput, b: MetricInput, dir?: 'desc' | 'asc', opt?: CmpStrOptions): Promise<T>;
+    batchSortedAsync<T extends CmpStrResult[] | MetricResultBatch<R> = any>(a: MetricInput, b: MetricInput, dir?: 'desc' | 'asc', opt?: CmpStrOptions): Promise<T>;
     /**
      * Asynchronously performs a pairwise metric comparison between source and target
      * strings or array of strings.
@@ -168,7 +169,7 @@ export declare class CmpStrAsync<R = MetricRaw> extends CmpStr<R> {
      * @param {CmpStrOptions} [opt] - Optional options
      * @returns {Promise<T>} - The pairwise metric results
      */
-    pairsAsync<T extends CmpStrResult[] | MetricResultBatch<R>>(a: MetricInput, b: MetricInput, opt?: CmpStrOptions): Promise<T>;
+    pairsAsync<T extends CmpStrResult[] | MetricResultBatch<R> = any>(a: MetricInput, b: MetricInput, opt?: CmpStrOptions): Promise<T>;
     /**
      * Asynchronously performs a batch comparison and returns only results above the threshold.
      *
@@ -179,7 +180,7 @@ export declare class CmpStrAsync<R = MetricRaw> extends CmpStr<R> {
      * @param {CmpStrOptions} [opt] - Optional options
      * @returns {Promise<T>} - The filtered batch results
      */
-    matchAsync<T extends CmpStrResult[] | MetricResultBatch<R>>(a: MetricInput, b: MetricInput, threshold: number, opt?: CmpStrOptions): Promise<T>;
+    matchAsync<T extends CmpStrResult[] | MetricResultBatch<R> = any>(a: MetricInput, b: MetricInput, threshold: number, opt?: CmpStrOptions): Promise<T>;
     /**
      * Asynchronously returns the n closest matches from a batch comparison.
      *
@@ -190,7 +191,7 @@ export declare class CmpStrAsync<R = MetricRaw> extends CmpStr<R> {
      * @param {CmpStrOptions} [opt] - Optional options
      * @returns {Promise<T>} - The closest matches
      */
-    closestAsync<T extends CmpStrResult[] | MetricResultBatch<R>>(a: MetricInput, b: MetricInput, n?: number, opt?: CmpStrOptions): Promise<T>;
+    closestAsync<T extends CmpStrResult[] | MetricResultBatch<R> = any>(a: MetricInput, b: MetricInput, n?: number, opt?: CmpStrOptions): Promise<T>;
     /**
      * Asynchronously returns the n furthest matches from a batch comparison.
      *
@@ -201,7 +202,7 @@ export declare class CmpStrAsync<R = MetricRaw> extends CmpStr<R> {
      * @param {CmpStrOptions} [opt] - Optional options
      * @returns {Promise<T>} - The furthest matches
      */
-    furthestAsync<T extends CmpStrResult[] | MetricResultBatch<R>>(a: MetricInput, b: MetricInput, n?: number, opt?: CmpStrOptions): Promise<T>;
+    furthestAsync<T extends CmpStrResult[] | MetricResultBatch<R> = any>(a: MetricInput, b: MetricInput, n?: number, opt?: CmpStrOptions): Promise<T>;
     /**
      * Asynchronously performs a normalized and filtered substring search.
      *
@@ -230,4 +231,77 @@ export declare class CmpStrAsync<R = MetricRaw> extends CmpStr<R> {
      * @returns {Promise<string>} - The phonetic index as a string
      */
     phoneticIndexAsync(input: string, algo?: string, opt?: PhoneticOptions): Promise<string>;
+    /**
+     * ---------------------------------------------------------------------------------
+     * Public asynchronous methods for structured data comparison
+     * ---------------------------------------------------------------------------------
+     *
+     * These methods provide asynchronous interfaces for comparing arrays of
+     * structured objects by extracting and comparing specific properties.
+     */
+    /**
+     * Asynchronously performs a batch comparison against structured data by extracting
+     * a specific property and returning results with original objects attached.
+     *
+     * @template T - The type of objects in the data array
+     * @param {string} query - The query string to compare against
+     * @param {T[]} data - The array of structured objects
+     * @param {keyof T} key - The property key to extract for comparison
+     * @param {StructuredDataOptions} [opt] - Optional lookup options
+     * @returns {Promise<StructuredDataBatchResult<T, R>|T[]>} - Async batch results with original objects
+     */
+    structuredLookupAsync<T = any>(query: string, data: T[], key: keyof T, opt?: StructuredDataOptions): Promise<StructuredDataBatchResult<T, R> | T[]>;
+    /**
+     * Asynchronously performs a batch comparison and returns only results above
+     * the threshold for structured data.
+     *
+     * @template T - The type of objects in the data array
+     * @param {string} query - The query string to compare against
+     * @param {T[]} data - The array of structured objects
+     * @param {keyof T} key - The property key to extract for comparison
+     * @param {number} threshold - The similarity threshold (0..1)
+     * @param {StructuredDataLookupOptions} [opt] - Optional lookup options
+     * @returns {Promise<StructuredDataBatchResult<T, R>|T[]>} - Async filtered batch results
+     */
+    structuredMatchAsync<T = any>(query: string, data: T[], key: keyof T, threshold: number, opt?: StructuredDataOptions): Promise<StructuredDataBatchResult<T, R> | T[]>;
+    /**
+     * Asynchronously returns the n closest matches from a batch comparison
+     * of structured data.
+     *
+     * @template T - The type of objects in the data array
+     * @param {string} query - The query string to compare against
+     * @param {T[]} data - The array of structured objects
+     * @param {keyof T} key - The property key to extract for comparison
+     * @param {number} [n=1] - Number of closest matches
+     * @param {StructuredDataOptions} [opt] - Optional lookup options
+     * @returns {Promise<StructuredDataBatchResult<T, R>|T[]>} - Async closest matches
+     */
+    structuredClosestAsync<T = any>(query: string, data: T[], key: keyof T, n?: number, opt?: StructuredDataOptions): Promise<StructuredDataBatchResult<T, R> | T[]>;
+    /**
+     * Asynchronously returns the n furthest matches from a batch comparison
+     * of structured data.
+     *
+     * @template T - The type of objects in the data array
+     * @param {string} query - The query string to compare against
+     * @param {T[]} data - The array of structured objects
+     * @param {keyof T} key - The property key to extract for comparison
+     * @param {number} [n=1] - Number of furthest matches
+     * @param {StructuredDataOptions} [opt] - Optional lookup options
+     * @returns {Promise<StructuredDataBatchResult<T, R>|T[]>} - Async furthest matches
+     */
+    structuredFurthestAsync<T = any>(query: string, data: T[], key: keyof T, n?: number, opt?: StructuredDataOptions): Promise<StructuredDataBatchResult<T, R> | T[]>;
+    /**
+     * Asynchronously performs a pairwise comparison between two arrays of structured objects
+     * by extracting specific properties and returning results with original objects attached.
+     *
+     * @template T - The type of objects in the arrays
+     * @template O - The type of objects in the other array
+     * @param {T[]} data - The array of structured objects
+     * @param {keyof T} key - The property key to extract for comparison
+     * @param {T[]} other - The other array of structured objects
+     * @param {keyof T} otherKey - The property key to extract from other array
+     * @param {StructuredDataOptions} [opt] - Optional lookup options
+     * @returns {Promise<StructuredDataBatchResult<T, R>|T[]>} - Async pairwise results with original objects
+     */
+    structuredPairsAsync<T = any, O = any>(data: T[], key: keyof T, other: O[], otherKey: keyof O, opt?: StructuredDataOptions): Promise<StructuredDataBatchResult<T, R> | T[]>;
 }

package/dist/types/index.d.ts

@@ -7,7 +7,7 @@
  * filtering, and text analysis. It is designed for both high-level application development
  * and research, offering a unified API for single, batch, and pairwise operations.
  *
- * Version: 3.0.3
+ * Version: 3.1.0
  * Author: Paul Köhler (komed3)
  * License: MIT
  *
@@ -21,6 +21,7 @@
  *  - Batch, pairwise, and single comparison with detailed, type-safe results
  *  - Safe-mode for handling empty inputs gracefully
  *  - Phonetic-aware search, indexing, and comparison
+ *  - Structured data comparison by extracting properties from objects
  *  - Readability and text analysis utilities (syllables, word stats, etc.)
  *  - Unified diff and difference reporting (line/word, ASCII/CLI)
  *  - Full TypeScript type safety, extensibility, and profiling support
@@ -40,7 +41,7 @@
  * For asynchronous workloads, use `CmpStrAsync`, which provides the same API with
  * Promise-based, non-blocking methods for large-scale or I/O-bound operations.
  *
- * @version 3.0.3
+ * @version 3.1.0
  * @author Paul Köhler (komed3)
  * @license MIT
  */

package/dist/types/root.d.ts

@@ -0,0 +1,39 @@
+/**
+ * CmpStr Development Entry Point
+ * src/root.ts
+ *
+ * This entry point is intended for development and extension of the CmpStr library. It exposes
+ * core components and utilities that allow developers to create new metrics, phonetic algorithms,
+ * and other extensions to the library.
+ *
+ * Please visit CmpStr's documentation for more information:
+ * https://github.com/komed3/cmpstr/wiki/Extending-CmpStr
+ *
+ * @version 3.1.0
+ * @author Paul Köhler (komed3)
+ * @license MIT
+ */
+export * from './index';
+/**
+ * Export utils to implement new metrics
+ *
+ *  - MetricRegistry: Metric registry service for managing metric implementations.
+ *  - Metric: Abstract class representing a generic string metric.
+ *  - MetricCls: Type definition for a class constructor that extends the Metric class.
+ */
+export { MetricRegistry, Metric, MetricCls } from './metric';
+/**
+ * Export utils to implement new phonetic algorithms
+ *
+ *  - PhoneticRegistry: Phonetic registry service for managing phonetic algorithm implementations.
+ *  - PhoneticMappingRegistry: Registry for managing phonetic character mappings.
+ *  - Phonetic: Abstract class representing a generic phonetic algorithm.
+ *  - PhoneticCls: Type definition for a class constructor that extends the Phonetic class.
+ */
+export { PhoneticRegistry, PhoneticMappingRegistry, Phonetic, PhoneticCls } from './phonetic';
+export * as DeepMerge from './utils/DeepMerge';
+export { Filter } from './utils/Filter';
+export { HashTable } from './utils/HashTable';
+export { Pool } from './utils/Pool';
+export { Profiler } from './utils/Profiler';
+export { StructuredData } from './utils/StructuredData';

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

@@ -9,8 +9,8 @@
  * 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.
+ * It supports different types of buffers (Uint16Array, number[], string[], Set, Map)
+ * and allows for acquiring buffers of specific sizes while managing a max pool size.
  *
  * @module Utils/Pool
  * @author Paul Köhler (komed3)

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

@@ -0,0 +1,162 @@
+/**
+ * StructuredData - Structured Data Processing Utility
+ * src/utils/StructuredData.ts
+ *
+ * This utility provides a factory for processing arrays of structured objects,
+ * enabling efficient lookups and comparisons on specific object properties.
+ *
+ * Features:
+ *  - Support for arbitrary object structures and property keys
+ *  - Flexible extraction and transformation of object properties
+ *  - Batch comparison with original object reconstruction
+ *  - Full TypeScript type safety with generics
+ *  - Integration with CmpStr comparison methods
+ *  - Optional "objects-only" output mode for minimal result structure
+ *
+ * @module Utils/StructuredData
+ * @author Paul Köhler (komed3)
+ * @license MIT
+ */
+import type { CmpFnResult, CmpStrOptions, MetricRaw, StructuredDataBatchResult, StructuredDataOptions } from './Types';
+/**
+ * The StructuredData class provides factory methods for processing arrays of
+ * structured objects with string comparison capabilities.
+ *
+ * @template T - The type of objects in the data array
+ * @template R - The type of the metric raw result
+ */
+export declare class StructuredData<T = any, R = MetricRaw> {
+    /**
+     * Creates a new StructuredData instance for processing structured data.
+     *
+     * @param {T[]} data - The array of objects to process
+     * @param {string|number|symbol} key - The property key to extract for comparison
+     * @returns {StructuredData<T, R>} - A new class instance
+     */
+    static create<T = any, R = MetricRaw>(data: T[], key: keyof T): StructuredData<T, R>;
+    protected data: T[];
+    protected key: keyof T;
+    /**
+     * Creates a new StructuredData instance.
+     *
+     * @param {T[]} data - The array of objects to process
+     * @param {keyof T} key - The property key to extract for comparison
+     */
+    private constructor();
+    /**
+     * Extracts properties from another array.
+     *
+     * @template A - The type of objects in the array
+     * @param {A[]} arr - The array to extract from
+     * @param {keyof A} key - The property key
+     * @returns {string[]} - Array of extracted strings
+     */
+    private extractFrom;
+    /**
+     * Extracts string values from the data array using the configured key.
+     *
+     * @returns {string[]} - Array of extracted strings
+     */
+    private extract;
+    /**
+     * Type guard to check if a value is MetricResultSingle<R>.
+     *
+     * @param {unknown} v - The value to check
+     * @returns {v is MetricResultSingle<R>} - True if v is MetricResultSingle<R>
+     */
+    private isMetricResult;
+    /**
+     * Type guard to check if a value is CmpStrResult & { raw?: R }.
+     *
+     * @param {unknown} v - The value to check
+     * @returns {v is CmpStrResult & { raw?: R }
+     */
+    private isCmpStrResult;
+    /**
+     * Normalizes metric results to a consistent format.
+     * Handles both CmpStrResult[] and MetricResultBatch<R> formats.
+     *
+     * @param {any} results - The raw metric results
+     * @returns {MetricResultSingle<R>[]} - Normalized single results array
+     */
+    private normalizeResults;
+    /**
+     * Rebuilds results with original objects attached.
+     * IMPORTANT: Results are assumed to be in the same order as sourceData,
+     * or they must include index information via the source/target mapping.
+     *
+     * @param {MetricResultSingle<R>[]} results - The normalized metric results
+     * @param {T[]} sourceData - The source data array for object attachment
+     * @param {string[]} extractedStrings - The extracted strings array for index mapping
+     * @param {boolean} [removeZero] - Whether to remove zero similarity results
+     * @param {boolean} [objectsOnly] - Return only objects without metadata
+     * @returns {StructuredDataResult<T, R>[] | T[]} - Results with objects (or just objects if objectsOnly=true)
+     */
+    private rebuild;
+    /**
+     * Sorts results in-place by match score.
+     *
+     * @param {MetricResultSingle<R>[]} results - The results to sort
+     * @param {string|boolean} [sort] - Sort direction (asc, desc, or boolean true=desc)
+     * @returns {MetricResultSingle<R>[]} - Sorted results
+     */
+    private sort;
+    /**
+     * Performs a lookup with a synchronous comparison function.
+     *
+     * @param {() => CmpFnResult<R>} fn - The comparison function
+     * @param {string[]} extractedStrings - The extracted strings for index mapping
+     * @param {StructuredDataOptions} [opt] - Additional options
+     * @returns {StructuredDataBatchResult<T, R>|T[]} - The lookup results
+     */
+    private performLookup;
+    /**
+     * Performs a lookup with an asynchronous comparison function.
+     *
+     * @param {() => Promise<CmpFnResult<R>>} fn - The async comparison function
+     * @param {string[]} extractedStrings - The extracted strings for index mapping
+     * @param {StructuredDataOptions} [opt] - Additional options
+     * @returns {Promise<StructuredDataBatchResult<T, R>|T[]>} - The async lookup results
+     */
+    private performLookupAsync;
+    /**
+     * Performs a batch comparison against a query string.
+     *
+     * @param {() => CmpFnResult<R>} fn - The comparison function
+     * @param {string} query - The query string to compare against
+     * @param {StructuredDataOptions} [opt] - Optional lookup options
+     * @returns {StructuredDataBatchResult<T, R>|T[]} - Results with objects or just objects
+     */
+    lookup(fn: (a: string, b: string[], opt?: CmpStrOptions) => CmpFnResult<R>, query: string, opt?: StructuredDataOptions): StructuredDataBatchResult<T, R> | T[];
+    /**
+     * Performs a pairwise comparison against another array of objects.
+     *
+     * @template O - The type of objects in the other array
+     * @param {() => CmpFnResult<R>} fn - The comparison function
+     * @param {O[]} other - The other array of objects
+     * @param {keyof O} otherKey - The property key in the other array
+     * @param {StructuredDataOptions} [opt] - Optional lookup options
+     * @returns {StructuredDataBatchResult<T, R> | T[]} - Results with objects or just objects
+     */
+    lookupPairs<O = any>(fn: (a: string[], b: string[], opt?: CmpStrOptions) => CmpFnResult<R>, other: O[], otherKey: keyof O, opt?: StructuredDataOptions): StructuredDataBatchResult<T, R> | T[];
+    /**
+     * Asynchronously performs a batch comparison against a query string.
+     *
+     * @param {() => Promise<CmpFnResult<R>>} fn - The async comparison function
+     * @param {string} query - The query string to compare against
+     * @param {StructuredDataOptions} [opt] - Optional lookup options
+     * @returns {Promise<StructuredDataBatchResult<T, R> | T[]>} - Async results
+     */
+    lookupAsync(fn: (a: string, b: string[], opt?: CmpStrOptions) => Promise<CmpFnResult<R>>, query: string, opt?: StructuredDataOptions): Promise<StructuredDataBatchResult<T, R> | T[]>;
+    /**
+     * Asynchronously performs a pairwise comparison against another array of objects.
+     *
+     * @template O - The type of objects in the other array
+     * @param {() => Promise<CmpFnResult<R>>} fn - The async comparison function
+     * @param {O[]} other - The other array of objects
+     * @param {keyof O} otherKey - The property key in the other array
+     * @param {StructuredDataOptions} [opt] - Optional lookup options
+     * @returns {Promise<StructuredDataBatchResult<T, R> | T[]>} - Async results
+     */
+    lookupPairsAsync<O = any>(fn: (a: string[], b: string[], opt?: CmpStrOptions) => Promise<CmpFnResult<R>>, other: O[], otherKey: keyof O, opt?: StructuredDataOptions): Promise<StructuredDataBatchResult<T, R> | T[]>;
+}

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

@@ -45,7 +45,7 @@ export interface ProfilerService<T> {
 /**
  * PoolType enumerates the supported buffer types for the Pool utility.
  */
-export type PoolType = 'uint16' | 'number[]' | 'set' | 'map';
+export type PoolType = 'uint16' | 'number[]' | 'string[]' | 'set' | 'map';
 /**
  * PoolConfig defines the configuration for a buffer pool.
  */
@@ -323,3 +323,37 @@ export interface CmpStrResult {
     target: string;
     match: number;
 }
+/**
+ * CompareFnResult represents the possible return types for comparison functions.
+ *
+ * @template R - The type of the raw result
+ */
+export type CmpFnResult<R> = MetricResultSingle<R>[] | (CmpStrResult & {
+    raw?: R;
+})[] | null | undefined;
+/**
+ * StructuredDataResult represents a lookup result with original object attached.
+ *
+ * @template T - The type of the original object
+ * @template R - The type of the metric raw result
+ */
+export interface StructuredDataResult<T = any, R = MetricRaw> {
+    obj: T;
+    key: string | number | symbol;
+    result: CmpStrResult;
+    raw?: R;
+}
+/**
+ * StructuredDataBatchResult is an array of lookup results.
+ *
+ * @template T - The type of the original object
+ * @template R - The type of the metric raw result
+ */
+export type StructuredDataBatchResult<T = any, R = MetricRaw> = StructuredDataResult<T, R>[];
+/**
+ * StructuredDataOptions configures the lookup behavior.
+ */
+export interface StructuredDataOptions extends Omit<CmpStrOptions, 'raw'> {
+    sort?: boolean | 'asc' | 'desc';
+    objectsOnly?: boolean;
+}