cmpstr 3.0.4 → 3.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (89) hide show
  1. package/README.md +2 -1
  2. package/dist/CmpStr.esm.js +345 -90
  3. package/dist/CmpStr.esm.js.map +1 -1
  4. package/dist/CmpStr.esm.min.js +3 -3
  5. package/dist/CmpStr.esm.min.js.map +1 -1
  6. package/dist/CmpStr.umd.js +342 -89
  7. package/dist/CmpStr.umd.js.map +1 -1
  8. package/dist/CmpStr.umd.min.js +3 -3
  9. package/dist/CmpStr.umd.min.js.map +1 -1
  10. package/dist/cjs/CmpStr.cjs +41 -1
  11. package/dist/cjs/CmpStr.cjs.map +1 -1
  12. package/dist/cjs/CmpStrAsync.cjs +38 -1
  13. package/dist/cjs/CmpStrAsync.cjs.map +1 -1
  14. package/dist/cjs/index.cjs +1 -1
  15. package/dist/cjs/metric/Cosine.cjs +1 -1
  16. package/dist/cjs/metric/DamerauLevenshtein.cjs +1 -1
  17. package/dist/cjs/metric/DiceSorensen.cjs +1 -1
  18. package/dist/cjs/metric/Hamming.cjs +1 -1
  19. package/dist/cjs/metric/Jaccard.cjs +1 -1
  20. package/dist/cjs/metric/JaroWinkler.cjs +1 -1
  21. package/dist/cjs/metric/LCS.cjs +1 -1
  22. package/dist/cjs/metric/Levenshtein.cjs +1 -1
  23. package/dist/cjs/metric/Metric.cjs +1 -1
  24. package/dist/cjs/metric/NeedlemanWunsch.cjs +1 -1
  25. package/dist/cjs/metric/SmithWaterman.cjs +1 -1
  26. package/dist/cjs/metric/qGram.cjs +1 -1
  27. package/dist/cjs/phonetic/Caverphone.cjs +1 -1
  28. package/dist/cjs/phonetic/Cologne.cjs +1 -1
  29. package/dist/cjs/phonetic/Metaphone.cjs +1 -1
  30. package/dist/cjs/phonetic/Phonetic.cjs +1 -1
  31. package/dist/cjs/phonetic/Soundex.cjs +1 -1
  32. package/dist/cjs/root.cjs +13 -1
  33. package/dist/cjs/root.cjs.map +1 -1
  34. package/dist/cjs/utils/DeepMerge.cjs +1 -1
  35. package/dist/cjs/utils/DiffChecker.cjs +1 -1
  36. package/dist/cjs/utils/Filter.cjs +1 -1
  37. package/dist/cjs/utils/HashTable.cjs +1 -1
  38. package/dist/cjs/utils/Normalizer.cjs +1 -1
  39. package/dist/cjs/utils/Pool.cjs +10 -1
  40. package/dist/cjs/utils/Pool.cjs.map +1 -1
  41. package/dist/cjs/utils/Profiler.cjs +1 -1
  42. package/dist/cjs/utils/Registry.cjs +1 -1
  43. package/dist/cjs/utils/StructuredData.cjs +145 -0
  44. package/dist/cjs/utils/StructuredData.cjs.map +1 -0
  45. package/dist/cjs/utils/TextAnalyzer.cjs +1 -1
  46. package/dist/esm/CmpStr.mjs +41 -1
  47. package/dist/esm/CmpStr.mjs.map +1 -1
  48. package/dist/esm/CmpStrAsync.mjs +38 -1
  49. package/dist/esm/CmpStrAsync.mjs.map +1 -1
  50. package/dist/esm/index.mjs +1 -1
  51. package/dist/esm/metric/Cosine.mjs +1 -1
  52. package/dist/esm/metric/DamerauLevenshtein.mjs +1 -1
  53. package/dist/esm/metric/DiceSorensen.mjs +1 -1
  54. package/dist/esm/metric/Hamming.mjs +1 -1
  55. package/dist/esm/metric/Jaccard.mjs +1 -1
  56. package/dist/esm/metric/JaroWinkler.mjs +1 -1
  57. package/dist/esm/metric/LCS.mjs +1 -1
  58. package/dist/esm/metric/Levenshtein.mjs +1 -1
  59. package/dist/esm/metric/Metric.mjs +1 -1
  60. package/dist/esm/metric/NeedlemanWunsch.mjs +1 -1
  61. package/dist/esm/metric/SmithWaterman.mjs +1 -1
  62. package/dist/esm/metric/qGram.mjs +1 -1
  63. package/dist/esm/phonetic/Caverphone.mjs +1 -1
  64. package/dist/esm/phonetic/Cologne.mjs +1 -1
  65. package/dist/esm/phonetic/Metaphone.mjs +1 -1
  66. package/dist/esm/phonetic/Phonetic.mjs +1 -1
  67. package/dist/esm/phonetic/Soundex.mjs +1 -1
  68. package/dist/esm/root.mjs +7 -1
  69. package/dist/esm/root.mjs.map +1 -1
  70. package/dist/esm/utils/DeepMerge.mjs +1 -1
  71. package/dist/esm/utils/DiffChecker.mjs +1 -1
  72. package/dist/esm/utils/Filter.mjs +1 -1
  73. package/dist/esm/utils/HashTable.mjs +1 -1
  74. package/dist/esm/utils/Normalizer.mjs +1 -1
  75. package/dist/esm/utils/Pool.mjs +10 -1
  76. package/dist/esm/utils/Pool.mjs.map +1 -1
  77. package/dist/esm/utils/Profiler.mjs +1 -1
  78. package/dist/esm/utils/Registry.mjs +1 -1
  79. package/dist/esm/utils/StructuredData.mjs +143 -0
  80. package/dist/esm/utils/StructuredData.mjs.map +1 -0
  81. package/dist/esm/utils/TextAnalyzer.mjs +1 -1
  82. package/dist/types/CmpStr.d.ts +90 -8
  83. package/dist/types/CmpStrAsync.d.ts +82 -8
  84. package/dist/types/index.d.ts +3 -2
  85. package/dist/types/root.d.ts +3 -2
  86. package/dist/types/utils/Pool.d.ts +2 -2
  87. package/dist/types/utils/StructuredData.d.ts +162 -0
  88. package/dist/types/utils/Types.d.ts +35 -1
  89. package/package.json +52 -17
@@ -11,6 +11,7 @@
11
11
  * - Asynchronous normalization, filtering, and metric computation
12
12
  * - Async batch, pairwise, and single string comparison with detailed results
13
13
  * - Async phonetic indexing and phonetic-aware search and comparison
14
+ * - Async structured data comparison by extracting object properties
14
15
  * - Full compatibility with the synchronous CmpStr API
15
16
  * - Designed for large-scale, high-performance, and server-side applications
16
17
  *
@@ -18,7 +19,7 @@
18
19
  * @author Paul Köhler (komed3)
19
20
  * @license MIT
20
21
  */
21
- import type { CmpStrOptions, CmpStrProcessors, CmpStrResult, NormalizeFlags, PhoneticOptions, MetricRaw, MetricInput, MetricMode, MetricResult, MetricResultSingle, MetricResultBatch } from './utils/Types';
22
+ import type { CmpStrOptions, CmpStrProcessors, CmpStrResult, NormalizeFlags, PhoneticOptions, MetricRaw, MetricInput, MetricMode, MetricResult, MetricResultSingle, MetricResultBatch, StructuredDataBatchResult, StructuredDataOptions } from './utils/Types';
22
23
  import { CmpStr } from './CmpStr';
23
24
  /**
24
25
  * The CmpStrAsync class provides a fully asynchronous API for string comparison,
@@ -123,7 +124,7 @@ export declare class CmpStrAsync<R = MetricRaw> extends CmpStr<R> {
123
124
  * @param {CmpStrOptions} [opt] - Optional options
124
125
  * @returns {Promise<T>} - The metric result
125
126
  */
126
- testAsync<T extends CmpStrResult | MetricResultSingle<R>>(a: string, b: string, opt?: CmpStrOptions): Promise<T>;
127
+ testAsync<T extends CmpStrResult | MetricResultSingle<R> = any>(a: string, b: string, opt?: CmpStrOptions): Promise<T>;
127
128
  /**
128
129
  * Asynchronously performs a single metric comparison returning the numeric score.
129
130
  *
@@ -143,7 +144,7 @@ export declare class CmpStrAsync<R = MetricRaw> extends CmpStr<R> {
143
144
  * @param {CmpStrOptions} [opt] - Optional options
144
145
  * @returns {Promise<T>} - The batch metric results
145
146
  */
146
- batchTestAsync<T extends CmpStrResult[] | MetricResultBatch<R>>(a: MetricInput, b: MetricInput, opt?: CmpStrOptions): Promise<T>;
147
+ batchTestAsync<T extends CmpStrResult[] | MetricResultBatch<R> = any>(a: MetricInput, b: MetricInput, opt?: CmpStrOptions): Promise<T>;
147
148
  /**
148
149
  * Asynchronously performs a batch metric comparison and returns results sorted by score.
149
150
  *
@@ -154,7 +155,7 @@ export declare class CmpStrAsync<R = MetricRaw> extends CmpStr<R> {
154
155
  * @param {CmpStrOptions} [opt] - Optional options
155
156
  * @returns {Promise<T>} - The sorted batch results
156
157
  */
157
- batchSortedAsync<T extends CmpStrResult[] | MetricResultBatch<R>>(a: MetricInput, b: MetricInput, dir?: 'desc' | 'asc', opt?: CmpStrOptions): Promise<T>;
158
+ batchSortedAsync<T extends CmpStrResult[] | MetricResultBatch<R> = any>(a: MetricInput, b: MetricInput, dir?: 'desc' | 'asc', opt?: CmpStrOptions): Promise<T>;
158
159
  /**
159
160
  * Asynchronously performs a pairwise metric comparison between source and target
160
161
  * strings or array of strings.
@@ -168,7 +169,7 @@ export declare class CmpStrAsync<R = MetricRaw> extends CmpStr<R> {
168
169
  * @param {CmpStrOptions} [opt] - Optional options
169
170
  * @returns {Promise<T>} - The pairwise metric results
170
171
  */
171
- pairsAsync<T extends CmpStrResult[] | MetricResultBatch<R>>(a: MetricInput, b: MetricInput, opt?: CmpStrOptions): Promise<T>;
172
+ pairsAsync<T extends CmpStrResult[] | MetricResultBatch<R> = any>(a: MetricInput, b: MetricInput, opt?: CmpStrOptions): Promise<T>;
172
173
  /**
173
174
  * Asynchronously performs a batch comparison and returns only results above the threshold.
174
175
  *
@@ -179,7 +180,7 @@ export declare class CmpStrAsync<R = MetricRaw> extends CmpStr<R> {
179
180
  * @param {CmpStrOptions} [opt] - Optional options
180
181
  * @returns {Promise<T>} - The filtered batch results
181
182
  */
182
- matchAsync<T extends CmpStrResult[] | MetricResultBatch<R>>(a: MetricInput, b: MetricInput, threshold: number, opt?: CmpStrOptions): Promise<T>;
183
+ matchAsync<T extends CmpStrResult[] | MetricResultBatch<R> = any>(a: MetricInput, b: MetricInput, threshold: number, opt?: CmpStrOptions): Promise<T>;
183
184
  /**
184
185
  * Asynchronously returns the n closest matches from a batch comparison.
185
186
  *
@@ -190,7 +191,7 @@ export declare class CmpStrAsync<R = MetricRaw> extends CmpStr<R> {
190
191
  * @param {CmpStrOptions} [opt] - Optional options
191
192
  * @returns {Promise<T>} - The closest matches
192
193
  */
193
- closestAsync<T extends CmpStrResult[] | MetricResultBatch<R>>(a: MetricInput, b: MetricInput, n?: number, opt?: CmpStrOptions): Promise<T>;
194
+ closestAsync<T extends CmpStrResult[] | MetricResultBatch<R> = any>(a: MetricInput, b: MetricInput, n?: number, opt?: CmpStrOptions): Promise<T>;
194
195
  /**
195
196
  * Asynchronously returns the n furthest matches from a batch comparison.
196
197
  *
@@ -201,7 +202,7 @@ export declare class CmpStrAsync<R = MetricRaw> extends CmpStr<R> {
201
202
  * @param {CmpStrOptions} [opt] - Optional options
202
203
  * @returns {Promise<T>} - The furthest matches
203
204
  */
204
- furthestAsync<T extends CmpStrResult[] | MetricResultBatch<R>>(a: MetricInput, b: MetricInput, n?: number, opt?: CmpStrOptions): Promise<T>;
205
+ furthestAsync<T extends CmpStrResult[] | MetricResultBatch<R> = any>(a: MetricInput, b: MetricInput, n?: number, opt?: CmpStrOptions): Promise<T>;
205
206
  /**
206
207
  * Asynchronously performs a normalized and filtered substring search.
207
208
  *
@@ -230,4 +231,77 @@ export declare class CmpStrAsync<R = MetricRaw> extends CmpStr<R> {
230
231
  * @returns {Promise<string>} - The phonetic index as a string
231
232
  */
232
233
  phoneticIndexAsync(input: string, algo?: string, opt?: PhoneticOptions): Promise<string>;
234
+ /**
235
+ * ---------------------------------------------------------------------------------
236
+ * Public asynchronous methods for structured data comparison
237
+ * ---------------------------------------------------------------------------------
238
+ *
239
+ * These methods provide asynchronous interfaces for comparing arrays of
240
+ * structured objects by extracting and comparing specific properties.
241
+ */
242
+ /**
243
+ * Asynchronously performs a batch comparison against structured data by extracting
244
+ * a specific property and returning results with original objects attached.
245
+ *
246
+ * @template T - The type of objects in the data array
247
+ * @param {string} query - The query string to compare against
248
+ * @param {T[]} data - The array of structured objects
249
+ * @param {keyof T} key - The property key to extract for comparison
250
+ * @param {StructuredDataOptions} [opt] - Optional lookup options
251
+ * @returns {Promise<StructuredDataBatchResult<T, R>|T[]>} - Async batch results with original objects
252
+ */
253
+ structuredLookupAsync<T = any>(query: string, data: T[], key: keyof T, opt?: StructuredDataOptions): Promise<StructuredDataBatchResult<T, R> | T[]>;
254
+ /**
255
+ * Asynchronously performs a batch comparison and returns only results above
256
+ * the threshold for structured data.
257
+ *
258
+ * @template T - The type of objects in the data array
259
+ * @param {string} query - The query string to compare against
260
+ * @param {T[]} data - The array of structured objects
261
+ * @param {keyof T} key - The property key to extract for comparison
262
+ * @param {number} threshold - The similarity threshold (0..1)
263
+ * @param {StructuredDataLookupOptions} [opt] - Optional lookup options
264
+ * @returns {Promise<StructuredDataBatchResult<T, R>|T[]>} - Async filtered batch results
265
+ */
266
+ structuredMatchAsync<T = any>(query: string, data: T[], key: keyof T, threshold: number, opt?: StructuredDataOptions): Promise<StructuredDataBatchResult<T, R> | T[]>;
267
+ /**
268
+ * Asynchronously returns the n closest matches from a batch comparison
269
+ * of structured data.
270
+ *
271
+ * @template T - The type of objects in the data array
272
+ * @param {string} query - The query string to compare against
273
+ * @param {T[]} data - The array of structured objects
274
+ * @param {keyof T} key - The property key to extract for comparison
275
+ * @param {number} [n=1] - Number of closest matches
276
+ * @param {StructuredDataOptions} [opt] - Optional lookup options
277
+ * @returns {Promise<StructuredDataBatchResult<T, R>|T[]>} - Async closest matches
278
+ */
279
+ structuredClosestAsync<T = any>(query: string, data: T[], key: keyof T, n?: number, opt?: StructuredDataOptions): Promise<StructuredDataBatchResult<T, R> | T[]>;
280
+ /**
281
+ * Asynchronously returns the n furthest matches from a batch comparison
282
+ * of structured data.
283
+ *
284
+ * @template T - The type of objects in the data array
285
+ * @param {string} query - The query string to compare against
286
+ * @param {T[]} data - The array of structured objects
287
+ * @param {keyof T} key - The property key to extract for comparison
288
+ * @param {number} [n=1] - Number of furthest matches
289
+ * @param {StructuredDataOptions} [opt] - Optional lookup options
290
+ * @returns {Promise<StructuredDataBatchResult<T, R>|T[]>} - Async furthest matches
291
+ */
292
+ structuredFurthestAsync<T = any>(query: string, data: T[], key: keyof T, n?: number, opt?: StructuredDataOptions): Promise<StructuredDataBatchResult<T, R> | T[]>;
293
+ /**
294
+ * Asynchronously performs a pairwise comparison between two arrays of structured objects
295
+ * by extracting specific properties and returning results with original objects attached.
296
+ *
297
+ * @template T - The type of objects in the arrays
298
+ * @template O - The type of objects in the other array
299
+ * @param {T[]} data - The array of structured objects
300
+ * @param {keyof T} key - The property key to extract for comparison
301
+ * @param {T[]} other - The other array of structured objects
302
+ * @param {keyof T} otherKey - The property key to extract from other array
303
+ * @param {StructuredDataOptions} [opt] - Optional lookup options
304
+ * @returns {Promise<StructuredDataBatchResult<T, R>|T[]>} - Async pairwise results with original objects
305
+ */
306
+ structuredPairsAsync<T = any, O = any>(data: T[], key: keyof T, other: O[], otherKey: keyof O, opt?: StructuredDataOptions): Promise<StructuredDataBatchResult<T, R> | T[]>;
233
307
  }
@@ -7,7 +7,7 @@
7
7
  * filtering, and text analysis. It is designed for both high-level application development
8
8
  * and research, offering a unified API for single, batch, and pairwise operations.
9
9
  *
10
- * Version: 3.0.4
10
+ * Version: 3.1.0
11
11
  * Author: Paul Köhler (komed3)
12
12
  * License: MIT
13
13
  *
@@ -21,6 +21,7 @@
21
21
  * - Batch, pairwise, and single comparison with detailed, type-safe results
22
22
  * - Safe-mode for handling empty inputs gracefully
23
23
  * - Phonetic-aware search, indexing, and comparison
24
+ * - Structured data comparison by extracting properties from objects
24
25
  * - Readability and text analysis utilities (syllables, word stats, etc.)
25
26
  * - Unified diff and difference reporting (line/word, ASCII/CLI)
26
27
  * - Full TypeScript type safety, extensibility, and profiling support
@@ -40,7 +41,7 @@
40
41
  * For asynchronous workloads, use `CmpStrAsync`, which provides the same API with
41
42
  * Promise-based, non-blocking methods for large-scale or I/O-bound operations.
42
43
  *
43
- * @version 3.0.4
44
+ * @version 3.1.0
44
45
  * @author Paul Köhler (komed3)
45
46
  * @license MIT
46
47
  */
@@ -9,11 +9,11 @@
9
9
  * Please visit CmpStr's documentation for more information:
10
10
  * https://github.com/komed3/cmpstr/wiki/Extending-CmpStr
11
11
  *
12
- * @version 3.0.4
12
+ * @version 3.1.0
13
13
  * @author Paul Köhler (komed3)
14
14
  * @license MIT
15
15
  */
16
- export * from './utils/Types';
16
+ export * from './index';
17
17
  /**
18
18
  * Export utils to implement new metrics
19
19
  *
@@ -36,3 +36,4 @@ export { Filter } from './utils/Filter';
36
36
  export { HashTable } from './utils/HashTable';
37
37
  export { Pool } from './utils/Pool';
38
38
  export { Profiler } from './utils/Profiler';
39
+ export { StructuredData } from './utils/StructuredData';
@@ -9,8 +9,8 @@
9
9
  * By reusing pre-allocated typed arrays, it reduces memory allocations and garbage
10
10
  * collection overhead, especially for repeated or batch computations.
11
11
  *
12
- * It supports different types of buffers (Uint16Array, number[], Set, Map) and allows
13
- * for acquiring buffers of specific sizes while managing a maximum pool size.
12
+ * It supports different types of buffers (Uint16Array, number[], string[], Set, Map)
13
+ * and allows for acquiring buffers of specific sizes while managing a max pool size.
14
14
  *
15
15
  * @module Utils/Pool
16
16
  * @author Paul Köhler (komed3)
@@ -0,0 +1,162 @@
1
+ /**
2
+ * StructuredData - Structured Data Processing Utility
3
+ * src/utils/StructuredData.ts
4
+ *
5
+ * This utility provides a factory for processing arrays of structured objects,
6
+ * enabling efficient lookups and comparisons on specific object properties.
7
+ *
8
+ * Features:
9
+ * - Support for arbitrary object structures and property keys
10
+ * - Flexible extraction and transformation of object properties
11
+ * - Batch comparison with original object reconstruction
12
+ * - Full TypeScript type safety with generics
13
+ * - Integration with CmpStr comparison methods
14
+ * - Optional "objects-only" output mode for minimal result structure
15
+ *
16
+ * @module Utils/StructuredData
17
+ * @author Paul Köhler (komed3)
18
+ * @license MIT
19
+ */
20
+ import type { CmpFnResult, CmpStrOptions, MetricRaw, StructuredDataBatchResult, StructuredDataOptions } from './Types';
21
+ /**
22
+ * The StructuredData class provides factory methods for processing arrays of
23
+ * structured objects with string comparison capabilities.
24
+ *
25
+ * @template T - The type of objects in the data array
26
+ * @template R - The type of the metric raw result
27
+ */
28
+ export declare class StructuredData<T = any, R = MetricRaw> {
29
+ /**
30
+ * Creates a new StructuredData instance for processing structured data.
31
+ *
32
+ * @param {T[]} data - The array of objects to process
33
+ * @param {string|number|symbol} key - The property key to extract for comparison
34
+ * @returns {StructuredData<T, R>} - A new class instance
35
+ */
36
+ static create<T = any, R = MetricRaw>(data: T[], key: keyof T): StructuredData<T, R>;
37
+ protected data: T[];
38
+ protected key: keyof T;
39
+ /**
40
+ * Creates a new StructuredData instance.
41
+ *
42
+ * @param {T[]} data - The array of objects to process
43
+ * @param {keyof T} key - The property key to extract for comparison
44
+ */
45
+ private constructor();
46
+ /**
47
+ * Extracts properties from another array.
48
+ *
49
+ * @template A - The type of objects in the array
50
+ * @param {A[]} arr - The array to extract from
51
+ * @param {keyof A} key - The property key
52
+ * @returns {string[]} - Array of extracted strings
53
+ */
54
+ private extractFrom;
55
+ /**
56
+ * Extracts string values from the data array using the configured key.
57
+ *
58
+ * @returns {string[]} - Array of extracted strings
59
+ */
60
+ private extract;
61
+ /**
62
+ * Type guard to check if a value is MetricResultSingle<R>.
63
+ *
64
+ * @param {unknown} v - The value to check
65
+ * @returns {v is MetricResultSingle<R>} - True if v is MetricResultSingle<R>
66
+ */
67
+ private isMetricResult;
68
+ /**
69
+ * Type guard to check if a value is CmpStrResult & { raw?: R }.
70
+ *
71
+ * @param {unknown} v - The value to check
72
+ * @returns {v is CmpStrResult & { raw?: R }
73
+ */
74
+ private isCmpStrResult;
75
+ /**
76
+ * Normalizes metric results to a consistent format.
77
+ * Handles both CmpStrResult[] and MetricResultBatch<R> formats.
78
+ *
79
+ * @param {any} results - The raw metric results
80
+ * @returns {MetricResultSingle<R>[]} - Normalized single results array
81
+ */
82
+ private normalizeResults;
83
+ /**
84
+ * Rebuilds results with original objects attached.
85
+ * IMPORTANT: Results are assumed to be in the same order as sourceData,
86
+ * or they must include index information via the source/target mapping.
87
+ *
88
+ * @param {MetricResultSingle<R>[]} results - The normalized metric results
89
+ * @param {T[]} sourceData - The source data array for object attachment
90
+ * @param {string[]} extractedStrings - The extracted strings array for index mapping
91
+ * @param {boolean} [removeZero] - Whether to remove zero similarity results
92
+ * @param {boolean} [objectsOnly] - Return only objects without metadata
93
+ * @returns {StructuredDataResult<T, R>[] | T[]} - Results with objects (or just objects if objectsOnly=true)
94
+ */
95
+ private rebuild;
96
+ /**
97
+ * Sorts results in-place by match score.
98
+ *
99
+ * @param {MetricResultSingle<R>[]} results - The results to sort
100
+ * @param {string|boolean} [sort] - Sort direction (asc, desc, or boolean true=desc)
101
+ * @returns {MetricResultSingle<R>[]} - Sorted results
102
+ */
103
+ private sort;
104
+ /**
105
+ * Performs a lookup with a synchronous comparison function.
106
+ *
107
+ * @param {() => CmpFnResult<R>} fn - The comparison function
108
+ * @param {string[]} extractedStrings - The extracted strings for index mapping
109
+ * @param {StructuredDataOptions} [opt] - Additional options
110
+ * @returns {StructuredDataBatchResult<T, R>|T[]} - The lookup results
111
+ */
112
+ private performLookup;
113
+ /**
114
+ * Performs a lookup with an asynchronous comparison function.
115
+ *
116
+ * @param {() => Promise<CmpFnResult<R>>} fn - The async comparison function
117
+ * @param {string[]} extractedStrings - The extracted strings for index mapping
118
+ * @param {StructuredDataOptions} [opt] - Additional options
119
+ * @returns {Promise<StructuredDataBatchResult<T, R>|T[]>} - The async lookup results
120
+ */
121
+ private performLookupAsync;
122
+ /**
123
+ * Performs a batch comparison against a query string.
124
+ *
125
+ * @param {() => CmpFnResult<R>} fn - The comparison function
126
+ * @param {string} query - The query string to compare against
127
+ * @param {StructuredDataOptions} [opt] - Optional lookup options
128
+ * @returns {StructuredDataBatchResult<T, R>|T[]} - Results with objects or just objects
129
+ */
130
+ lookup(fn: (a: string, b: string[], opt?: CmpStrOptions) => CmpFnResult<R>, query: string, opt?: StructuredDataOptions): StructuredDataBatchResult<T, R> | T[];
131
+ /**
132
+ * Performs a pairwise comparison against another array of objects.
133
+ *
134
+ * @template O - The type of objects in the other array
135
+ * @param {() => CmpFnResult<R>} fn - The comparison function
136
+ * @param {O[]} other - The other array of objects
137
+ * @param {keyof O} otherKey - The property key in the other array
138
+ * @param {StructuredDataOptions} [opt] - Optional lookup options
139
+ * @returns {StructuredDataBatchResult<T, R> | T[]} - Results with objects or just objects
140
+ */
141
+ lookupPairs<O = any>(fn: (a: string[], b: string[], opt?: CmpStrOptions) => CmpFnResult<R>, other: O[], otherKey: keyof O, opt?: StructuredDataOptions): StructuredDataBatchResult<T, R> | T[];
142
+ /**
143
+ * Asynchronously performs a batch comparison against a query string.
144
+ *
145
+ * @param {() => Promise<CmpFnResult<R>>} fn - The async comparison function
146
+ * @param {string} query - The query string to compare against
147
+ * @param {StructuredDataOptions} [opt] - Optional lookup options
148
+ * @returns {Promise<StructuredDataBatchResult<T, R> | T[]>} - Async results
149
+ */
150
+ lookupAsync(fn: (a: string, b: string[], opt?: CmpStrOptions) => Promise<CmpFnResult<R>>, query: string, opt?: StructuredDataOptions): Promise<StructuredDataBatchResult<T, R> | T[]>;
151
+ /**
152
+ * Asynchronously performs a pairwise comparison against another array of objects.
153
+ *
154
+ * @template O - The type of objects in the other array
155
+ * @param {() => Promise<CmpFnResult<R>>} fn - The async comparison function
156
+ * @param {O[]} other - The other array of objects
157
+ * @param {keyof O} otherKey - The property key in the other array
158
+ * @param {StructuredDataOptions} [opt] - Optional lookup options
159
+ * @returns {Promise<StructuredDataBatchResult<T, R> | T[]>} - Async results
160
+ */
161
+ 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[]>;
162
+ }
@@ -45,7 +45,7 @@ export interface ProfilerService<T> {
45
45
  /**
46
46
  * PoolType enumerates the supported buffer types for the Pool utility.
47
47
  */
48
- export type PoolType = 'uint16' | 'number[]' | 'set' | 'map';
48
+ export type PoolType = 'uint16' | 'number[]' | 'string[]' | 'set' | 'map';
49
49
  /**
50
50
  * PoolConfig defines the configuration for a buffer pool.
51
51
  */
@@ -323,3 +323,37 @@ export interface CmpStrResult {
323
323
  target: string;
324
324
  match: number;
325
325
  }
326
+ /**
327
+ * CompareFnResult represents the possible return types for comparison functions.
328
+ *
329
+ * @template R - The type of the raw result
330
+ */
331
+ export type CmpFnResult<R> = MetricResultSingle<R>[] | (CmpStrResult & {
332
+ raw?: R;
333
+ })[] | null | undefined;
334
+ /**
335
+ * StructuredDataResult represents a lookup result with original object attached.
336
+ *
337
+ * @template T - The type of the original object
338
+ * @template R - The type of the metric raw result
339
+ */
340
+ export interface StructuredDataResult<T = any, R = MetricRaw> {
341
+ obj: T;
342
+ key: string | number | symbol;
343
+ result: CmpStrResult;
344
+ raw?: R;
345
+ }
346
+ /**
347
+ * StructuredDataBatchResult is an array of lookup results.
348
+ *
349
+ * @template T - The type of the original object
350
+ * @template R - The type of the metric raw result
351
+ */
352
+ export type StructuredDataBatchResult<T = any, R = MetricRaw> = StructuredDataResult<T, R>[];
353
+ /**
354
+ * StructuredDataOptions configures the lookup behavior.
355
+ */
356
+ export interface StructuredDataOptions extends Omit<CmpStrOptions, 'raw'> {
357
+ sort?: boolean | 'asc' | 'desc';
358
+ objectsOnly?: boolean;
359
+ }
package/package.json CHANGED
@@ -2,7 +2,7 @@
2
2
  "name": "cmpstr",
3
3
  "description": "CmpStr is a lightweight, fast and well performing package for calculating string similarity",
4
4
  "license": "MIT",
5
- "version": "3.0.4",
5
+ "version": "3.1.0",
6
6
  "author": {
7
7
  "name": "komed3 (Paul Köhler)",
8
8
  "email": "webmaster@komed3.de",
@@ -10,14 +10,49 @@
10
10
  },
11
11
  "homepage": "https://github.com/komed3/cmpstr",
12
12
  "keywords": [
13
- "string-similarity", "string-comparison", "fuzzy-matching", "phonetic-search",
14
- "phonetic-algorithms", "similarity-metrics", "batch-processing", "text-search",
15
- "pairwise-comparison", "normalization", "filtering", "text-analysis", "diff",
16
- "diffing", "typescript", "asynchronous", "custom-algorithms", "metrics",
17
- "algorithms", "levenshtein", "damerau-levenshtein", "jaro-winkler", "cosine",
18
- "dice-coefficient", "hamming-distance", "jaccard-index", "needleman-wunsch",
19
- "lcs", "smith-waterman", "q-gram", "soundex", "metaphone", "cologne-phonetic",
20
- "caverphone", "profiling", "extensible"
13
+ "string-similarity",
14
+ "string-comparison",
15
+ "fuzzy-matching",
16
+ "phonetic-search",
17
+ "phonetic-algorithms",
18
+ "similarity-metrics",
19
+ "batch-processing",
20
+ "text-search",
21
+ "pairwise-comparison",
22
+ "normalization",
23
+ "filtering",
24
+ "text-analysis",
25
+ "diff",
26
+ "diffing",
27
+ "typescript",
28
+ "asynchronous",
29
+ "custom-algorithms",
30
+ "metrics",
31
+ "algorithms",
32
+ "levenshtein",
33
+ "damerau-levenshtein",
34
+ "jaro-winkler",
35
+ "cosine",
36
+ "dice-coefficient",
37
+ "hamming-distance",
38
+ "jaccard-index",
39
+ "needleman-wunsch",
40
+ "lcs",
41
+ "smith-waterman",
42
+ "q-gram",
43
+ "soundex",
44
+ "metaphone",
45
+ "cologne-phonetic",
46
+ "caverphone",
47
+ "profiling",
48
+ "extensible",
49
+ "lightweight",
50
+ "fast",
51
+ "performance",
52
+ "npm",
53
+ "nodejs",
54
+ "browser",
55
+ "structured-data"
21
56
  ],
22
57
  "repository": {
23
58
  "type": "git",
@@ -57,17 +92,17 @@
57
92
  "clean": "rm -rf dist"
58
93
  },
59
94
  "devDependencies": {
60
- "@rollup/plugin-commonjs": "^28.0.6",
61
- "@rollup/plugin-node-resolve": "^16.0.1",
95
+ "@rollup/plugin-commonjs": "^29.0.0",
96
+ "@rollup/plugin-node-resolve": "^16.0.3",
62
97
  "@rollup/plugin-terser": "^0.4.4",
63
- "@rollup/plugin-typescript": "^12.1.4",
64
- "@types/node": "^24.4.0",
65
- "prettier": "^3.6.2",
66
- "rollup": "^4.50.2",
98
+ "@rollup/plugin-typescript": "^12.3.0",
99
+ "@types/node": "^25.0.9",
100
+ "prettier": "^3.8.0",
101
+ "rollup": "^4.55.1",
67
102
  "rollup-plugin-cleanup": "^3.2.1",
68
103
  "rollup-plugin-prettier": "^4.1.2",
69
104
  "tslib": "^2.8.1",
70
- "typescript": "^5.9.2",
71
- "vitest": "^3.2.4"
105
+ "typescript": "^5.9.3",
106
+ "vitest": "^4.0.17"
72
107
  }
73
108
  }