@nlptools/distance 0.0.2 → 0.0.4

package/dist/index.mjs

@@ -1,6 +1,1134 @@
-export * from '@nlptools/distance-wasm';
-import { distance } from 'fastest-levenshtein';
-
-const fastest_levenshtein = distance;
-
-export { fastest_levenshtein };
+import { distance } from "fastest-levenshtein";
+import { lcs_dp, lcs_myers_linear_space, lcs_size_dp, lcs_size_myers_linear_space } from "@algorithm.ts/lcs";
+import { DiffType, diff } from "@algorithm.ts/diff";
+//#region src/utils.ts
+/**
+* Generate character n-grams from a string.
+*
+* @param str - Input string
+* @param n - N-gram size (default: 2 for bigrams)
+*/
+function ngrams(str, n = 2) {
+	const result = [];
+	for (let i = 0; i <= str.length - n; i++) result.push(str.slice(i, i + n));
+	return result;
+}
+/**
+* Build an n-gram frequency map using integer-encoded keys.
+* Encodes n characters into a single number to avoid string allocation
+* and speed up Map hashing.
+*
+* For ASCII bigrams: key = (c1 << 8) | c2 (fits in 16 bits).
+* For non-ASCII or n > 2: falls back to string keys.
+*/
+function ngramFrequencyMap(str, n = 2) {
+	const len = str.length;
+	if (len < n) return /* @__PURE__ */ new Map();
+	if (n === 2) {
+		const map = /* @__PURE__ */ new Map();
+		for (let i = 0; i <= len - 2; i++) {
+			const c1 = str.charCodeAt(i);
+			const c2 = str.charCodeAt(i + 1);
+			if (c1 >= 128 || c2 >= 128) return null;
+			const key = c1 << 8 | c2;
+			map.set(key, (map.get(key) ?? 0) + 1);
+		}
+		return map;
+	}
+	return null;
+}
+/**
+* Build a frequency map (Counter/multiset) from an iterable of tokens.
+* Matches the behavior of Rust's textdistance Counter.
+*/
+function frequencyMap(tokens) {
+	const map = /* @__PURE__ */ new Map();
+	for (const token of tokens) map.set(token, (map.get(token) ?? 0) + 1);
+	return map;
+}
+/**
+* Build a character-level frequency map from a string.
+* This is the default tokenization strategy used by textdistance.
+*/
+function charFrequencyMap(str) {
+	return frequencyMap(str);
+}
+/**
+* Build a character frequency array from a string.
+* Returns false if any character is non-ASCII (charCode >= 128).
+* The caller must zero the array before use.
+*/
+function buildCharFreqArray(arr, str) {
+	for (let i = 0; i < str.length; i++) {
+		const code = str.charCodeAt(i);
+		if (code >= 128) return false;
+		arr[code]++;
+	}
+	return true;
+}
+/**
+* Count intersect size between two frequency maps.
+* For each key, takes the minimum count (multiset intersection).
+*/
+function intersectCount(a, b) {
+	let count = 0;
+	const [smaller, larger] = a.size <= b.size ? [a, b] : [b, a];
+	for (const [key, countA] of smaller) {
+		const countB = larger.get(key);
+		if (countB !== void 0) count += countA < countB ? countA : countB;
+	}
+	return count;
+}
+/**
+* Count union size between two frequency maps.
+* For each key, takes the maximum count (multiset union).
+*/
+function unionCount(a, b) {
+	let count = 0;
+	const [smaller, larger] = a.size <= b.size ? [a, b] : [b, a];
+	for (const [key, countA] of smaller) {
+		const countB = larger.get(key);
+		if (countB !== void 0) count += countA > countB ? countA : countB;
+		else count += countA;
+	}
+	for (const [key, countB] of larger) if (!smaller.has(key)) count += countB;
+	return count;
+}
+/**
+* Get total token count from a frequency map.
+*/
+function totalCount(map) {
+	let count = 0;
+	for (const c of map.values()) count += c;
+	return count;
+}
+function intersectCountInt(a, b) {
+	let count = 0;
+	const [smaller, larger] = a.size <= b.size ? [a, b] : [b, a];
+	for (const [key, countA] of smaller) {
+		const countB = larger.get(key);
+		if (countB !== void 0) count += Math.min(countA, countB);
+	}
+	return count;
+}
+function unionCountInt(a, b) {
+	let count = 0;
+	const [smaller, larger] = a.size <= b.size ? [a, b] : [b, a];
+	for (const [key, countA] of smaller) {
+		const countB = larger.get(key);
+		if (countB !== void 0) count += Math.max(countA, countB);
+		else count += countA;
+	}
+	for (const [key, countB] of larger) if (!smaller.has(key)) count += countB;
+	return count;
+}
+function totalCountInt(map) {
+	let count = 0;
+	for (const c of map.values()) count += c;
+	return count;
+}
+/**
+* Normalize a raw distance to a similarity score in [0, 1].
+*
+* @param distance - Raw distance value
+* @param maxDistance - Maximum possible distance (usually max(len(a), len(b)))
+*/
+function normalize(distance, maxDistance) {
+	if (maxDistance === 0) return 1;
+	return Math.max(0, 1 - distance / maxDistance);
+}
+/**
+* FNV-1a hash for strings. Fast, good distribution for hash-based algorithms.
+*/
+function fnv1a(str) {
+	let hash = 2166136261;
+	for (let i = 0; i < str.length; i++) {
+		hash ^= str.charCodeAt(i);
+		hash = Math.imul(hash, 16777619);
+	}
+	return hash >>> 0;
+}
+//#endregion
+//#region src/edit/levenshtein.ts
+/**
+* Compute the Levenshtein edit distance between two strings.
+*
+* Time: O(m * n), Space: O(min(m, n))
+*
+* @param a - First string
+* @param b - Second string
+* @returns Edit distance (non-negative integer)
+*/
+function levenshtein(a, b) {
+	return distance(a, b);
+}
+/**
+* Compute the normalized Levenshtein similarity in [0, 1].
+*
+* @param a - First string
+* @param b - Second string
+* @returns Similarity score where 1 means identical
+*/
+function levenshteinNormalized(a, b) {
+	return normalize(levenshtein(a, b), Math.max(a.length, b.length));
+}
+//#endregion
+//#region src/edit/lcs.ts
+/**
+* Internal helper: create an equals callback using pre-built CharCode arrays.
+* Avoids repeated string indexing inside the hot LCS loop.
+*/
+function stringEquals(a, b) {
+	const ca = new Uint8Array(a.length);
+	const cb = new Uint8Array(b.length);
+	for (let i = 0; i < a.length; i++) ca[i] = a.charCodeAt(i);
+	for (let i = 0; i < b.length; i++) cb[i] = b.charCodeAt(i);
+	return (x, y) => ca[x] === cb[y];
+}
+/**
+* Compute the LCS distance: len(a) + len(b) - 2 * lcsLength.
+*
+* @param a - First string
+* @param b - Second string
+* @param algorithm - 'myers' (default, better for sparse diffs) | 'dp'
+* @returns LCS distance (non-negative integer)
+*/
+function lcsDistance(a, b, algorithm = "myers") {
+	const lcsLen = (algorithm === "dp" ? lcs_size_dp : lcs_size_myers_linear_space)(a.length, b.length, stringEquals(a, b));
+	return a.length + b.length - 2 * lcsLen;
+}
+/**
+* Compute the normalized LCS similarity in [0, 1].
+*
+* @param a - First string
+* @param b - Second string
+* @param algorithm - 'myers' | 'dp'
+* @returns Similarity score where 1 means identical
+*/
+function lcsNormalized(a, b, algorithm = "myers") {
+	return normalize(lcsDistance(a, b, algorithm), a.length + b.length);
+}
+/**
+* Get the length of the Longest Common Subsequence.
+*
+* @param a - First string
+* @param b - Second string
+* @param algorithm - 'myers' | 'dp'
+* @returns LCS length
+*/
+function lcsLength(a, b, algorithm = "myers") {
+	return (algorithm === "dp" ? lcs_size_dp : lcs_size_myers_linear_space)(a.length, b.length, stringEquals(a, b));
+}
+/**
+* Get the matching index pairs of the Longest Common Subsequence.
+*
+* @param a - First string
+* @param b - Second string
+* @param algorithm - 'myers' | 'dp'
+* @returns Array of [indexInA, indexInB] pairs
+*/
+function lcsPairs(a, b, algorithm = "myers") {
+	return (algorithm === "dp" ? lcs_dp : lcs_myers_linear_space)(a.length, b.length, stringEquals(a, b));
+}
+//#endregion
+//#region src/token/jaccard.ts
+const _freqA$2 = new Int32Array(128);
+const _freqB$2 = new Int32Array(128);
+/**
+* Jaccard similarity between two strings based on character-level multiset.
+*
+* J(A, B) = |A ∩ B| / |A ∪ B|
+*
+* Uses Counter (frequency map) for multiset semantics,
+* matching the textdistance crate behavior.
+*
+* Time: O(m + n)
+*
+* @param a - First string
+* @param b - Second string
+* @returns Jaccard similarity in [0, 1]
+*/
+function jaccard(a, b) {
+	_freqA$2.fill(0);
+	_freqB$2.fill(0);
+	if (buildCharFreqArray(_freqA$2, a) && buildCharFreqArray(_freqB$2, b)) {
+		let ic = 0;
+		let uc = 0;
+		for (let i = 0; i < 128; i++) {
+			const va = _freqA$2[i];
+			const vb = _freqB$2[i];
+			ic += Math.min(va, vb);
+			uc += Math.max(va, vb);
+		}
+		return uc === 0 ? 1 : ic / uc;
+	}
+	const freqAMap = charFrequencyMap(a);
+	const freqBMap = charFrequencyMap(b);
+	const ic = intersectCount(freqAMap, freqBMap);
+	const uc = unionCount(freqAMap, freqBMap);
+	if (uc === 0) return 1;
+	return ic / uc;
+}
+/**
+* Jaccard similarity based on character bigrams.
+*
+* @param a - First string
+* @param b - Second string
+* @param n - N-gram size (default: 2)
+* @returns Bigram Jaccard similarity in [0, 1]
+*/
+function jaccardNgram(a, b, n = 2) {
+	const freqAInt = ngramFrequencyMap(a, n);
+	const freqBInt = ngramFrequencyMap(b, n);
+	if (freqAInt !== null && freqBInt !== null) {
+		const ic = intersectCountInt(freqAInt, freqBInt);
+		const uc = unionCountInt(freqAInt, freqBInt);
+		return uc === 0 ? 1 : ic / uc;
+	}
+	const freqA = frequencyMap(ngrams(a, n));
+	const freqB = frequencyMap(ngrams(b, n));
+	const ic = intersectCount(freqA, freqB);
+	const uc = unionCount(freqA, freqB);
+	if (uc === 0) return 1;
+	return ic / uc;
+}
+//#endregion
+//#region src/token/cosine.ts
+const _freqA$1 = new Int32Array(128);
+const _freqB$1 = new Int32Array(128);
+/**
+* Cosine similarity between two strings based on character-level multiset.
+*
+* cos(A, B) = (A · B) / (|A| * |B|)
+*
+* Uses Counter (frequency map) for multiset semantics,
+* matching the textdistance crate behavior.
+*
+* Time: O(m + n)
+*
+* @param a - First string
+* @param b - Second string
+* @returns Cosine similarity in [0, 1]
+*/
+function cosine(a, b) {
+	_freqA$1.fill(0);
+	_freqB$1.fill(0);
+	if (buildCharFreqArray(_freqA$1, a) && buildCharFreqArray(_freqB$1, b)) {
+		let dot = 0;
+		let normA = 0;
+		let normB = 0;
+		for (let i = 0; i < 128; i++) {
+			const va = _freqA$1[i];
+			const vb = _freqB$1[i];
+			dot += va * vb;
+			normA += va * va;
+			normB += vb * vb;
+		}
+		const denominator = Math.sqrt(normA) * Math.sqrt(normB);
+		return denominator === 0 ? 1 : dot / denominator;
+	}
+	const freqAMap = charFrequencyMap(a);
+	const freqBMap = charFrequencyMap(b);
+	let dotProduct = 0;
+	let normA = 0;
+	let normB = 0;
+	const [smaller, larger] = freqAMap.size <= freqBMap.size ? [freqAMap, freqBMap] : [freqBMap, freqAMap];
+	for (const [char, countA] of smaller) {
+		const countB = larger.get(char) ?? 0;
+		dotProduct += countA * countB;
+		normA += countA * countA;
+	}
+	for (const [, count] of larger) normB += count * count;
+	if (freqAMap.size > freqBMap.size) {
+		const tmp = normA;
+		normA = normB;
+		normB = tmp;
+	}
+	const denominator = Math.sqrt(normA) * Math.sqrt(normB);
+	if (denominator === 0) return 1;
+	return dotProduct / denominator;
+}
+/**
+* Cosine similarity based on character n-grams.
+*
+* @param a - First string
+* @param b - Second string
+* @param n - N-gram size (default: 2)
+* @returns N-gram Cosine similarity in [0, 1]
+*/
+function cosineNgram(a, b, n = 2) {
+	const freqAInt = ngramFrequencyMap(a, n);
+	const freqBInt = ngramFrequencyMap(b, n);
+	if (freqAInt !== null && freqBInt !== null) {
+		let dotProduct = 0;
+		let normA = 0;
+		let normB = 0;
+		for (const [id, countA] of freqAInt) {
+			const countB = freqBInt.get(id) ?? 0;
+			dotProduct += countA * countB;
+			normA += countA * countA;
+		}
+		for (const [, count] of freqBInt) normB += count * count;
+		const denominator = Math.sqrt(normA) * Math.sqrt(normB);
+		return denominator === 0 ? 1 : dotProduct / denominator;
+	}
+	const freqA = frequencyMap(ngrams(a, n));
+	const freqB = frequencyMap(ngrams(b, n));
+	let dotProduct = 0;
+	let normA = 0;
+	let normB = 0;
+	for (const [token, countA] of freqA) {
+		const countB = freqB.get(token) ?? 0;
+		dotProduct += countA * countB;
+		normA += countA * countA;
+	}
+	for (const [, count] of freqB) normB += count * count;
+	const denominator = Math.sqrt(normA) * Math.sqrt(normB);
+	if (denominator === 0) return 1;
+	return dotProduct / denominator;
+}
+//#endregion
+//#region src/token/sorensen.ts
+const _freqA = new Int32Array(128);
+const _freqB = new Int32Array(128);
+/**
+* Sørensen-Dice coefficient between two strings based on character-level multiset.
+*
+* DSC(A, B) = 2 * |A ∩ B| / (|A| + |B|)
+*
+* Uses Counter (frequency map) for multiset semantics,
+* matching the textdistance crate behavior.
+*
+* Time: O(m + n)
+*
+* @param a - First string
+* @param b - Second string
+* @returns Sørensen-Dice coefficient in [0, 1]
+*/
+function sorensen(a, b) {
+	_freqA.fill(0);
+	_freqB.fill(0);
+	if (buildCharFreqArray(_freqA, a) && buildCharFreqArray(_freqB, b)) {
+		let ic = 0;
+		for (let i = 0; i < 128; i++) ic += Math.min(_freqA[i], _freqB[i]);
+		const total = a.length + b.length;
+		return total === 0 ? 1 : 2 * ic / total;
+	}
+	const freqAMap = charFrequencyMap(a);
+	const freqBMap = charFrequencyMap(b);
+	const ic = intersectCount(freqAMap, freqBMap);
+	const total = totalCount(freqAMap) + totalCount(freqBMap);
+	if (total === 0) return 1;
+	return 2 * ic / total;
+}
+/**
+* Sørensen-Dice coefficient based on character n-grams.
+*
+* @param a - First string
+* @param b - Second string
+* @param n - N-gram size (default: 2)
+* @returns Bigram Sørensen-Dice coefficient in [0, 1]
+*/
+function sorensenNgram(a, b, n = 2) {
+	const freqAInt = ngramFrequencyMap(a, n);
+	const freqBInt = ngramFrequencyMap(b, n);
+	if (freqAInt !== null && freqBInt !== null) {
+		const ic = intersectCountInt(freqAInt, freqBInt);
+		const total = totalCountInt(freqAInt) + totalCountInt(freqBInt);
+		return total === 0 ? 1 : 2 * ic / total;
+	}
+	const freqA = frequencyMap(ngrams(a, n));
+	const freqB = frequencyMap(ngrams(b, n));
+	const ic = intersectCount(freqA, freqB);
+	const total = totalCount(freqA) + totalCount(freqB);
+	if (total === 0) return 1;
+	return 2 * ic / total;
+}
+//#endregion
+//#region src/hash/simhash.ts
+/**
+* Generate a 64-bit fingerprint for a collection of features.
+*
+* SimHash maps a set of features to a fixed-length binary fingerprint such that
+* similar documents produce similar fingerprints. The similarity between two
+* fingerprints is measured by Hamming distance.
+*
+* Algorithm:
+* 1. Initialize a vector V of length `bits` to all zeros
+* 2. For each feature, compute its hash and set the i-th bit
+* 3. For each bit position i: if hash[i] = 1, V[i] += weight; else V[i] -= weight
+* 4. The final fingerprint: bit i = 1 if V[i] > 0, else 0
+*
+* Time: O(features * bits)
+*
+* @param features - Array of feature strings (e.g., words, n-grams, shingles)
+* @param options - Configuration
+* @returns 64-bit fingerprint as a bigint
+*/
+function simhash(features, options = {}) {
+	const bits = options.bits ?? 64;
+	const hashFn = options.hashFn ?? fnv1a;
+	const v = new Float64Array(bits);
+	for (const feature of features) {
+		const h = hashFn(feature);
+		for (let i = 0; i < bits; i++) if (h & 1 << i) v[i] += 1;
+		else v[i] -= 1;
+	}
+	let fingerprint = 0n;
+	for (let i = 0; i < bits; i++) if (v[i] > 0) fingerprint |= 1n << BigInt(i);
+	return fingerprint;
+}
+/**
+* Compute the Hamming distance between two SimHash fingerprints.
+*
+* The Hamming distance is the number of differing bits.
+* For 64-bit fingerprints, a distance ≤ 3 typically indicates near-duplicate content.
+*
+* Time: O(bits)
+*
+* @param a - First fingerprint
+* @param b - Second fingerprint
+* @returns Hamming distance (non-negative integer)
+*/
+function hammingDistance(a, b) {
+	return bitCount(a ^ b);
+}
+/**
+* Compute normalized Hamming similarity in [0, 1].
+*
+* @param a - First fingerprint
+* @param b - Second fingerprint
+* @param bits - Bit length of the fingerprints (default: 64)
+*/
+function hammingSimilarity(a, b, bits = 64) {
+	return 1 - hammingDistance(a, b) / bits;
+}
+/**
+* Count the number of set bits in a bigint using a lookup table.
+* Processes 8 bits at a time instead of 1, reducing iterations from 64 to 8.
+*/
+const POPCOUNT_TABLE = new Uint8Array(256);
+for (let i = 0; i < 256; i++) POPCOUNT_TABLE[i] = (i & 1) + (i >> 1 & 1) + (i >> 2 & 1) + (i >> 3 & 1) + (i >> 4 & 1) + (i >> 5 & 1) + (i >> 6 & 1) + (i >> 7 & 1);
+function bitCount(n) {
+	let count = 0;
+	while (n > 0n) {
+		count += POPCOUNT_TABLE[Number(n & 255n)];
+		n >>= 8n;
+	}
+	return count;
+}
+/**
+* SimHasher class for convenient document fingerprinting.
+*
+* @example
+* ```ts
+* const hasher = new SimHasher();
+* const fp1 = hasher.hash(['hello', 'world']);
+* const fp2 = hasher.hash(['hello', 'earth']);
+* console.log(hasher.distance(fp1, fp2)); // small number = similar
+* ```
+*/
+var SimHasher = class {
+	bits;
+	hashFn;
+	constructor(options = {}) {
+		this.bits = options.bits ?? 64;
+		this.hashFn = options.hashFn ?? fnv1a;
+	}
+	/**
+	* Generate a fingerprint from features.
+	*/
+	hash(features) {
+		return simhash(features, {
+			bits: this.bits,
+			hashFn: this.hashFn
+		});
+	}
+	/**
+	* Compute Hamming distance between two fingerprints.
+	*/
+	distance(a, b) {
+		return hammingDistance(a, b);
+	}
+	/**
+	* Compute similarity between two fingerprints.
+	*/
+	similarity(a, b) {
+		return hammingSimilarity(a, b, this.bits);
+	}
+	/**
+	* Check if two fingerprints are likely near-duplicates.
+	*
+	* @param threshold - Maximum Hamming distance to consider as duplicate (default: 3)
+	*/
+	isDuplicate(a, b, threshold = 3) {
+		return this.distance(a, b) <= threshold;
+	}
+};
+//#endregion
+//#region src/hash/minhash.ts
+/**
+* MinHash estimator for Jaccard similarity.
+*
+* Instead of computing the exact Jaccard index (which requires set intersection/union
+* on potentially large sets), MinHash generates a fixed-size signature for each set.
+* The Jaccard similarity is then estimated by comparing the fraction of matching
+* positions in the signatures.
+*
+* Time:
+* - Update: O(k) per element, where k = numHashes
+* - Estimate: O(k)
+*
+* @example
+* ```ts
+* const mh = new MinHash({ numHashes: 128 });
+* mh.update('hello');
+* mh.update('world');
+* const sig1 = mh.digest();
+*
+* const mh2 = new MinHash({ numHashes: 128 });
+* mh2.update('hello');
+* mh2.update('earth');
+* const sig2 = mh2.digest();
+*
+* console.log(MinHash.estimate(sig1, sig2)); // ~0.67
+* ```
+*/
+var MinHash = class MinHash {
+	numHashes;
+	hashParams;
+	maxHash;
+	signature;
+	dirty;
+	constructor(options = {}) {
+		this.numHashes = options.numHashes ?? 128;
+		const seed = options.seed ?? 42;
+		const p = 4294967311;
+		this.maxHash = p - 1;
+		this.hashParams = [];
+		let rng = seed;
+		for (let i = 0; i < this.numHashes; i++) {
+			rng = rng * 1103515245 + 12345 & 2147483647;
+			const a = rng % (p - 1) + 1;
+			rng = rng * 1103515245 + 12345 & 2147483647;
+			const b = rng % p;
+			this.hashParams.push({
+				a,
+				b,
+				p
+			});
+		}
+		this.signature = new Uint32Array(this.numHashes).fill(4294967295);
+		this.dirty = false;
+	}
+	/**
+	* Add a feature to the set.
+	*/
+	update(feature) {
+		const h = fnv1a(feature);
+		for (let i = 0; i < this.numHashes; i++) {
+			const { a, b, p } = this.hashParams[i];
+			const hash = ((a * h + b) % p + p) % p;
+			if (hash < this.signature[i]) this.signature[i] = hash;
+		}
+		this.dirty = true;
+	}
+	/**
+	* Get the MinHash signature.
+	* The signature is a fixed-size array that represents the set.
+	*/
+	digest() {
+		return new Uint32Array(this.signature);
+	}
+	/**
+	* Estimate Jaccard similarity between two MinHash signatures.
+	*
+	* @param sig1 - First MinHash signature
+	* @param sig2 - Second MinHash signature
+	* @returns Estimated Jaccard similarity in [0, 1]
+	*/
+	static estimate(sig1, sig2) {
+		if (sig1.length !== sig2.length) throw new Error("Signature lengths must match");
+		let matches = 0;
+		for (let i = 0; i < sig1.length; i++) if (sig1[i] === sig2[i]) matches++;
+		return matches / sig1.length;
+	}
+	/**
+	* Estimate Jaccard similarity between this and another MinHash instance.
+	*/
+	estimate(other) {
+		return MinHash.estimate(this.digest(), other.digest());
+	}
+};
+//#endregion
+//#region src/hash/lsh.ts
+/**
+* LSH (Locality-Sensitive Hashing) index for fast approximate nearest neighbor search.
+*
+* Uses the MinHash + banding technique:
+* 1. Divide each MinHash signature into `numBands` bands
+* 2. Hash each band to a bucket
+* 3. Items sharing at least one bucket are candidates for similarity
+*
+* The probability of two items with Jaccard similarity `s` being compared is:
+*   P = 1 - (1 - s^r)^b
+* where r = rows per band, b = numBands.
+*
+* @example
+* ```ts
+* const lsh = new LSH({ numBands: 16, numHashes: 128 });
+*
+* // Index documents
+* const mh1 = new MinHash({ numHashes: 128 });
+* mh1.update('hello');
+* mh1.update('world');
+* lsh.insert('doc1', mh1.digest());
+*
+* const mh2 = new MinHash({ numHashes: 128 });
+* mh2.update('hello');
+* mh2.update('earth');
+* lsh.insert('doc2', mh2.digest());
+*
+* // Query for similar documents
+* const mh3 = new MinHash({ numHashes: 128 });
+* mh3.update('hello');
+* mh3.update('earth');
+* const candidates = lsh.query(mh3.digest());
+* ```
+*/
+var LSH = class {
+	numBands;
+	rowsPerBand;
+	numHashes;
+	/**
+	* Map from band index → bucket hash → set of document IDs
+	*/
+	bands;
+	/**
+	* All indexed document signatures for exact similarity estimation.
+	*/
+	signatures;
+	constructor(options = {}) {
+		this.numHashes = options.numHashes ?? 128;
+		this.numBands = options.numBands ?? 16;
+		this.rowsPerBand = Math.floor(this.numHashes / this.numBands);
+		if (this.numBands > this.numHashes) throw new Error("numBands must be <= numHashes");
+		this.bands = [];
+		for (let i = 0; i < this.numBands; i++) this.bands.push(/* @__PURE__ */ new Map());
+		this.signatures = /* @__PURE__ */ new Map();
+	}
+	/**
+	* Insert a document into the index.
+	*
+	* @param id - Document identifier
+	* @param signature - MinHash signature (from MinHash.digest())
+	*/
+	insert(id, signature) {
+		if (signature.length !== this.numHashes) throw new Error(`Signature length ${signature.length} does not match numHashes ${this.numHashes}`);
+		this.signatures.set(id, signature);
+		for (let band = 0; band < this.numBands; band++) {
+			const start = band * this.rowsPerBand;
+			const end = start + this.rowsPerBand;
+			const bucketKey = bandHash(signature.slice(start, end));
+			let bucket = this.bands[band].get(bucketKey);
+			if (!bucket) {
+				bucket = /* @__PURE__ */ new Set();
+				this.bands[band].set(bucketKey, bucket);
+			}
+			bucket.add(id);
+		}
+	}
+	/**
+	* Query for candidate documents similar to the given signature.
+	*
+	* @param signature - Query MinHash signature
+	* @param threshold - Optional: minimum Jaccard similarity to return (default: return all candidates)
+	* @returns Array of [docId, estimatedJaccard] pairs, sorted by similarity descending
+	*/
+	query(signature, threshold) {
+		if (signature.length !== this.numHashes) throw new Error(`Signature length ${signature.length} does not match numHashes ${this.numHashes}`);
+		const candidates = /* @__PURE__ */ new Set();
+		for (let band = 0; band < this.numBands; band++) {
+			const start = band * this.rowsPerBand;
+			const end = start + this.rowsPerBand;
+			const bucketKey = bandHash(signature.slice(start, end));
+			const bucket = this.bands[band].get(bucketKey);
+			if (bucket) for (const id of bucket) candidates.add(id);
+		}
+		const results = [];
+		for (const id of candidates) {
+			const sig = this.signatures.get(id);
+			const similarity = MinHash.estimate(signature, sig);
+			if (threshold === void 0 || similarity >= threshold) results.push([id, similarity]);
+		}
+		results.sort((a, b) => b[1] - a[1]);
+		return results;
+	}
+	/**
+	* Remove a document from the index.
+	*/
+	remove(id) {
+		const sig = this.signatures.get(id);
+		if (!sig) return false;
+		this.signatures.delete(id);
+		for (let band = 0; band < this.numBands; band++) {
+			const start = band * this.rowsPerBand;
+			const end = start + this.rowsPerBand;
+			const bucketKey = bandHash(sig.slice(start, end));
+			const bucket = this.bands[band].get(bucketKey);
+			if (bucket) {
+				bucket.delete(id);
+				if (bucket.size === 0) this.bands[band].delete(bucketKey);
+			}
+		}
+		return true;
+	}
+	/**
+	* Get the number of indexed documents.
+	*/
+	get size() {
+		return this.signatures.size;
+	}
+};
+/**
+* Hash a band slice to a bucket key string.
+* Uses a simple but effective hash combining approach.
+*/
+function bandHash(slice) {
+	let hash = 0;
+	for (let i = 0; i < slice.length; i++) hash = hash * 31 + slice[i] | 0;
+	return hash.toString(36);
+}
+//#endregion
+//#region src/search.ts
+const BUILTIN_ALGORITHMS = {
+	levenshtein: levenshteinNormalized,
+	lcs: lcsNormalized,
+	jaccard,
+	jaccardNgram,
+	cosine,
+	cosineNgram,
+	sorensen,
+	sorensenNgram
+};
+function resolveKeys(rawKeys) {
+	if (rawKeys.length === 0) return [];
+	const totalWeight = rawKeys.reduce((sum, k) => sum + (k.weight ?? 1), 0);
+	return rawKeys.map((k) => ({
+		...k,
+		normalizedWeight: totalWeight > 0 ? (k.weight ?? 1) / totalWeight : 1 / rawKeys.length
+	}));
+}
+function resolveAlgorithm(algo) {
+	if (algo === void 0) return BUILTIN_ALGORITHMS.levenshtein;
+	if (typeof algo === "function") return algo;
+	return BUILTIN_ALGORITHMS[algo];
+}
+/**
+* Fuzzy search engine for finding similar items in a collection.
+*
+* Supports both string arrays and object arrays with weighted multi-key search.
+* Uses any similarity algorithm from @nlptools/distance, with optional LSH
+* acceleration for large datasets.
+*
+* @example
+* ```ts
+* // String array search
+* const search = new FuzzySearch(["apple", "banana", "cherry"]);
+* const results = search.search("aple"); // [{ item: "apple", score: 0.75, index: 0 }]
+*
+* // Object array with weighted keys
+* const books = [
+*   { title: "Old Man's War", author: "John Scalzi" },
+*   { title: "The Lock Artist", author: "Steve Hamilton" },
+* ];
+* const bookSearch = new FuzzySearch(books, {
+*   keys: [
+*     { name: "title", weight: 0.7 },
+*     { name: "author", weight: 0.3 },
+*   ],
+*   algorithm: "cosine",
+* });
+* const results = bookSearch.search("old man"); // finds "Old Man's War"
+* ```
+*/
+var FuzzySearch = class {
+	similarityFn;
+	keys;
+	threshold;
+	limit;
+	caseSensitive;
+	includeMatchDetails;
+	isObjectArray;
+	collection;
+	useLSH;
+	lshNumHashes;
+	lshNumBands;
+	lshIndex;
+	minHashSignatures;
+	constructor(collection, options = {}) {
+		this.similarityFn = resolveAlgorithm(options.algorithm);
+		this.keys = resolveKeys(options.keys ?? []);
+		this.isObjectArray = this.keys.length > 0;
+		this.threshold = options.threshold ?? 0;
+		this.limit = options.limit ?? Infinity;
+		this.caseSensitive = options.caseSensitive ?? false;
+		this.includeMatchDetails = options.includeMatchDetails ?? false;
+		this.collection = [...collection];
+		const lshOpts = options.lsh;
+		this.useLSH = lshOpts !== void 0;
+		this.lshNumHashes = lshOpts?.numHashes ?? 128;
+		this.lshNumBands = lshOpts?.numBands ?? 16;
+		this.lshIndex = null;
+		this.minHashSignatures = /* @__PURE__ */ new Map();
+		if (this.useLSH && this.collection.length > 0) this.buildLSHIndex();
+	}
+	/**
+	* Search the collection for items similar to the query.
+	*
+	* @param query - The search query string
+	* @param limit - Optional per-query limit override
+	* @returns Array of results sorted by score descending
+	*/
+	search(query, limit) {
+		const effectiveLimit = limit ?? this.limit;
+		if (effectiveLimit === 0 || this.collection.length === 0) return [];
+		const normalizedQuery = this.normalizeString(query);
+		if (this.useLSH && this.lshIndex !== null) return this.searchWithLSH(normalizedQuery, effectiveLimit);
+		return this.searchLinear(normalizedQuery, effectiveLimit);
+	}
+	/**
+	* Add an item to the collection.
+	* If LSH is enabled, the index is updated incrementally.
+	*/
+	add(item) {
+		const index = this.collection.length;
+		this.collection.push(item);
+		if (this.useLSH && this.lshIndex !== null) {
+			const text = this.extractSearchText(item);
+			const sig = this.buildMinHashSignature(text);
+			this.minHashSignatures.set(index, sig);
+			this.lshIndex.insert(String(index), sig);
+		}
+	}
+	/**
+	* Remove an item from the collection by index.
+	* If LSH is enabled, the index is rebuilt (O(n)).
+	*
+	* @returns true if the item was found and removed
+	*/
+	remove(index) {
+		if (index < 0 || index >= this.collection.length) return false;
+		this.collection.splice(index, 1);
+		if (this.useLSH) this.buildLSHIndex();
+		return true;
+	}
+	/**
+	* Replace the entire collection.
+	* If LSH is enabled, the index is rebuilt.
+	*/
+	setCollection(collection) {
+		this.collection = [...collection];
+		if (this.useLSH && this.collection.length > 0) this.buildLSHIndex();
+		else if (this.useLSH) {
+			this.lshIndex = null;
+			this.minHashSignatures.clear();
+		}
+	}
+	/**
+	* Get the current collection.
+	*/
+	getCollection() {
+		return this.collection;
+	}
+	/**
+	* Get the number of items in the collection.
+	*/
+	get size() {
+		return this.collection.length;
+	}
+	/**
+	* Clear the collection and any LSH index.
+	*/
+	clear() {
+		this.collection = [];
+		this.lshIndex = null;
+		this.minHashSignatures.clear();
+	}
+	searchLinear(normalizedQuery, limit) {
+		const candidates = [];
+		for (let i = 0; i < this.collection.length; i++) {
+			const item = this.collection[i];
+			if (this.isObjectArray) if (this.includeMatchDetails) {
+				const { score, matches } = this.computeDetailedScore(normalizedQuery, item);
+				if (score >= this.threshold) candidates.push({
+					item,
+					score,
+					index: i,
+					matches
+				});
+			} else {
+				const score = this.computeItemScore(normalizedQuery, item);
+				if (score >= this.threshold) candidates.push({
+					item,
+					score,
+					index: i
+				});
+			}
+			else {
+				const itemStr = this.normalizeString(item);
+				const score = this.similarityFn(normalizedQuery, itemStr);
+				if (score >= this.threshold) candidates.push({
+					item,
+					score,
+					index: i
+				});
+			}
+		}
+		candidates.sort((a, b) => b.score - a.score);
+		if (candidates.length <= limit) return candidates;
+		return candidates.slice(0, limit);
+	}
+	searchWithLSH(normalizedQuery, limit) {
+		const queryText = this.isObjectArray ? normalizedQuery : normalizedQuery;
+		const querySig = this.buildMinHashSignature(queryText);
+		const candidateIds = this.lshIndex.query(querySig, this.threshold);
+		const candidates = [];
+		for (const [id] of candidateIds) {
+			const idx = parseInt(id, 10);
+			if (idx < 0 || idx >= this.collection.length) continue;
+			const item = this.collection[idx];
+			if (this.isObjectArray) if (this.includeMatchDetails) {
+				const { score, matches } = this.computeDetailedScore(normalizedQuery, item);
+				if (score >= this.threshold) candidates.push({
+					item,
+					score,
+					index: idx,
+					matches
+				});
+			} else {
+				const score = this.computeItemScore(normalizedQuery, item);
+				if (score >= this.threshold) candidates.push({
+					item,
+					score,
+					index: idx
+				});
+			}
+			else {
+				const itemStr = this.normalizeString(item);
+				const score = this.similarityFn(normalizedQuery, itemStr);
+				if (score >= this.threshold) candidates.push({
+					item,
+					score,
+					index: idx
+				});
+			}
+		}
+		candidates.sort((a, b) => b.score - a.score);
+		if (candidates.length <= limit) return candidates;
+		return candidates.slice(0, limit);
+	}
+	buildLSHIndex() {
+		this.lshIndex = new LSH({
+			numBands: this.lshNumBands,
+			numHashes: this.lshNumHashes
+		});
+		this.minHashSignatures.clear();
+		for (let i = 0; i < this.collection.length; i++) {
+			const text = this.extractSearchText(this.collection[i]);
+			const sig = this.buildMinHashSignature(text);
+			this.minHashSignatures.set(i, sig);
+			this.lshIndex.insert(String(i), sig);
+		}
+	}
+	buildMinHashSignature(text) {
+		const mh = new MinHash({ numHashes: this.lshNumHashes });
+		const grams = ngrams(text, 2);
+		for (const g of grams) mh.update(g);
+		return mh.digest();
+	}
+	computeItemScore(normalizedQuery, item) {
+		let score = 0;
+		for (const key of this.keys) {
+			const value = this.extractKeyValue(item, key);
+			const normalizedValue = this.normalizeString(value);
+			score += key.normalizedWeight * this.similarityFn(normalizedQuery, normalizedValue);
+		}
+		return score;
+	}
+	computeDetailedScore(normalizedQuery, item) {
+		let score = 0;
+		const matches = {};
+		for (const key of this.keys) {
+			const value = this.extractKeyValue(item, key);
+			const normalizedValue = this.normalizeString(value);
+			const s = this.similarityFn(normalizedQuery, normalizedValue);
+			matches[key.name] = s;
+			score += key.normalizedWeight * s;
+		}
+		return {
+			score,
+			matches
+		};
+	}
+	extractSearchText(item) {
+		if (this.isObjectArray) return this.keys.map((k) => this.extractKeyValue(item, k)).join(" ");
+		return this.normalizeString(item);
+	}
+	extractKeyValue(item, key) {
+		if (key.getter) {
+			const value = key.getter(item);
+			return typeof value === "string" ? value : "";
+		}
+		const value = item[key.name];
+		return typeof value === "string" ? value : "";
+	}
+	normalizeString(str) {
+		return this.caseSensitive ? str : str.toLowerCase();
+	}
+};
+/**
+* Find the single best match for a query against a collection.
+*
+* This is a convenience wrapper around {@link FuzzySearch} for one-shot queries.
+* For repeated searches against the same collection, prefer creating a
+* {@link FuzzySearch} instance directly.
+*
+* Time: O(n * k) where n = collection size, k = number of keys
+*
+* @param query - The search query string
+* @param collection - Array of strings or objects to search
+* @param options - Search configuration
+* @returns The best matching result, or null if nothing meets the threshold
+*
+* @example
+* ```ts
+* // String array
+* const result = findBestMatch("kitten", ["sitting", "kit", "mitten"]);
+* console.log(result?.item); // "kit"
+* console.log(result?.score); // 0.5
+*
+* // Object array with weighted keys
+* const books = [
+*   { title: "The Great Gatsby", author: "F. Scott Fitzgerald" },
+*   { title: "Great Expectations", author: "Charles Dickens" },
+* ];
+* const result = findBestMatch("grate gatsbi", books, {
+*   keys: [
+*     { name: "title", weight: 0.7 },
+*     { name: "author", weight: 0.3 },
+*   ],
+* });
+* ```
+*/
+function findBestMatch(query, collection, options = {}) {
+	const results = new FuzzySearch(collection, {
+		algorithm: options.algorithm,
+		keys: options.keys,
+		threshold: options.threshold,
+		caseSensitive: options.caseSensitive
+	}).search(query, 1);
+	return results.length > 0 ? results[0] : null;
+}
+//#endregion
+export { DiffType, FuzzySearch, LSH, MinHash, SimHasher, cosine, cosineNgram, diff, findBestMatch, hammingDistance, hammingSimilarity, jaccard, jaccardNgram, lcsDistance, lcsLength, lcsNormalized, lcsPairs, levenshtein, levenshteinNormalized, simhash, sorensen, sorensenNgram, stringEquals };