@nlptools/distance 0.0.1 → 0.0.3

package/dist/index.d.mts

@@ -1,5 +1,392 @@
-export * from '@nlptools/distance-wasm';
+import { DiffType, IDiffItem, IDiffOptions, ILcs, ILcsAlgorithm, diff } from "@algorithm.ts/diff";
 
-declare const fastest_levenshtein: (a: string, b: string) => number;
-
-export { fastest_levenshtein };
+//#region src/edit/levenshtein.d.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)
+ */
+declare function levenshtein(a: string, b: string): number;
+/**
+ * Compute the normalized Levenshtein similarity in [0, 1].
+ *
+ * @param a - First string
+ * @param b - Second string
+ * @returns Similarity score where 1 means identical
+ */
+declare function levenshteinNormalized(a: string, b: string): number;
+//#endregion
+//#region src/edit/lcs.d.ts
+type LcsSizeFunc = (N1: number, N2: number, equals: (x: number, y: number) => boolean) => number;
+type LcsPairsFunc = (N1: number, N2: number, equals: (x: number, y: number) => boolean) => Array<[number, number]>;
+/**
+ * Internal helper: create an equals callback using pre-built CharCode arrays.
+ * Avoids repeated string indexing inside the hot LCS loop.
+ */
+declare function stringEquals(a: string, b: string): (x: number, y: number) => boolean;
+/**
+ * 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)
+ */
+declare function lcsDistance(a: string, b: string, algorithm?: "myers" | "dp"): number;
+/**
+ * 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
+ */
+declare function lcsNormalized(a: string, b: string, algorithm?: "myers" | "dp"): number;
+/**
+ * Get the length of the Longest Common Subsequence.
+ *
+ * @param a - First string
+ * @param b - Second string
+ * @param algorithm - 'myers' | 'dp'
+ * @returns LCS length
+ */
+declare function lcsLength(a: string, b: string, algorithm?: "myers" | "dp"): number;
+/**
+ * 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
+ */
+declare function lcsPairs(a: string, b: string, algorithm?: "myers" | "dp"): Array<[number, number]>;
+//#endregion
+//#region src/token/jaccard.d.ts
+/**
+ * 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]
+ */
+declare function jaccard(a: string, b: string): number;
+/**
+ * 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]
+ */
+declare function jaccardNgram(a: string, b: string, n?: number): number;
+//#endregion
+//#region src/token/cosine.d.ts
+/**
+ * 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]
+ */
+declare function cosine(a: string, b: string): number;
+/**
+ * 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]
+ */
+declare function cosineNgram(a: string, b: string, n?: number): number;
+//#endregion
+//#region src/token/sorensen.d.ts
+/**
+ * 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]
+ */
+declare function sorensen(a: string, b: string): number;
+/**
+ * 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]
+ */
+declare function sorensenNgram(a: string, b: string, n?: number): number;
+//#endregion
+//#region src/hash/simhash.d.ts
+interface ISimHashOptions {
+  /**
+   * Bit length of the fingerprint.
+   * @default 64
+   */
+  bits?: number;
+  /**
+   * Hash function to use for feature hashing.
+   * Defaults to a built-in FNV-1a implementation.
+   */
+  hashFn?: (feature: string) => number;
+}
+/**
+ * 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
+ */
+declare function simhash(features: string[], options?: ISimHashOptions): bigint;
+/**
+ * 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)
+ */
+declare function hammingDistance(a: bigint, b: bigint): number;
+/**
+ * Compute normalized Hamming similarity in [0, 1].
+ *
+ * @param a - First fingerprint
+ * @param b - Second fingerprint
+ * @param bits - Bit length of the fingerprints (default: 64)
+ */
+declare function hammingSimilarity(a: bigint, b: bigint, bits?: number): number;
+/**
+ * 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
+ * ```
+ */
+declare class SimHasher {
+  private readonly bits;
+  private readonly hashFn;
+  constructor(options?: ISimHashOptions);
+  /**
+   * Generate a fingerprint from features.
+   */
+  hash(features: string[]): bigint;
+  /**
+   * Compute Hamming distance between two fingerprints.
+   */
+  distance(a: bigint, b: bigint): number;
+  /**
+   * Compute similarity between two fingerprints.
+   */
+  similarity(a: bigint, b: bigint): number;
+  /**
+   * Check if two fingerprints are likely near-duplicates.
+   *
+   * @param threshold - Maximum Hamming distance to consider as duplicate (default: 3)
+   */
+  isDuplicate(a: bigint, b: bigint, threshold?: number): boolean;
+}
+//#endregion
+//#region src/hash/minhash.d.ts
+interface IMinHashOptions {
+  /**
+   * Number of hash functions / signature size.
+   * Larger values give more accurate Jaccard estimates.
+   * @default 128
+   */
+  numHashes?: number;
+  /**
+   * Seed for the random number generator.
+   * @default 42
+   */
+  seed?: number;
+}
+/**
+ * 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
+ * ```
+ */
+declare class MinHash {
+  private readonly numHashes;
+  private readonly hashParams;
+  private readonly maxHash;
+  private signature;
+  private dirty;
+  constructor(options?: IMinHashOptions);
+  /**
+   * Add a feature to the set.
+   */
+  update(feature: string): void;
+  /**
+   * Get the MinHash signature.
+   * The signature is a fixed-size array that represents the set.
+   */
+  digest(): Uint32Array;
+  /**
+   * 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: Uint32Array, sig2: Uint32Array): number;
+  /**
+   * Estimate Jaccard similarity between this and another MinHash instance.
+   */
+  estimate(other: MinHash): number;
+}
+//#endregion
+//#region src/hash/lsh.d.ts
+interface ILSHOptions {
+  /**
+   * Number of bands (rows per band = numHashes / numBands).
+   * More bands → higher recall, lower precision.
+   * @default 16
+   */
+  numBands?: number;
+  /**
+   * Number of hash functions (must match MinHash signature size).
+   * @default 128
+   */
+  numHashes?: number;
+}
+/**
+ * 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());
+ * ```
+ */
+declare class LSH {
+  private readonly numBands;
+  private readonly rowsPerBand;
+  private readonly numHashes;
+  /**
+   * Map from band index → bucket hash → set of document IDs
+   */
+  private readonly bands;
+  /**
+   * All indexed document signatures for exact similarity estimation.
+   */
+  private readonly signatures;
+  constructor(options?: ILSHOptions);
+  /**
+   * Insert a document into the index.
+   *
+   * @param id - Document identifier
+   * @param signature - MinHash signature (from MinHash.digest())
+   */
+  insert(id: string, signature: Uint32Array): void;
+  /**
+   * 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: Uint32Array, threshold?: number): Array<[string, number]>;
+  /**
+   * Remove a document from the index.
+   */
+  remove(id: string): boolean;
+  /**
+   * Get the number of indexed documents.
+   */
+  get size(): number;
+}
+//#endregion
+export { DiffType, type IDiffItem, type IDiffOptions, ILSHOptions, type ILcs, type ILcsAlgorithm, IMinHashOptions, ISimHashOptions, LSH, LcsPairsFunc, LcsSizeFunc, MinHash, SimHasher, cosine, cosineNgram, diff, hammingDistance, hammingSimilarity, jaccard, jaccardNgram, lcsDistance, lcsLength, lcsNormalized, lcsPairs, levenshtein, levenshteinNormalized, simhash, sorensen, sorensenNgram, stringEquals };