elid 0.3.0 → 0.3.1

package/elid_bg.js

@@ -181,55 +181,34 @@ function handleError(f, args) {
     }
 }
 /**
- * Compute the OSA (Optimal String Alignment) distance between two strings.
+ * Compute the SimHash fingerprint of a string.
  *
- * Similar to Levenshtein but also considers transpositions as a single operation.
+ * Returns a 64-bit hash where similar strings produce similar numbers.
+ * Use this for database queries by storing the hash and querying by numeric range.
  *
  * # JavaScript Example
  *
  * ```javascript
- * import { osaDistance } from 'elid';
- *
- * const distance = osaDistance("ca", "ac");
- * console.log(distance); // 1 (transposition)
- * ```
- * @param {string} a
- * @param {string} b
- * @returns {number}
- */
-export function osaDistance(a, b) {
-    const ptr0 = passStringToWasm0(a, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
-    const len0 = WASM_VECTOR_LEN;
-    const ptr1 = passStringToWasm0(b, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
-    const len1 = WASM_VECTOR_LEN;
-    const ret = wasm.osaDistance(ptr0, len0, ptr1, len1);
-    return ret >>> 0;
-}
-
-/**
- * Compute the Levenshtein distance between two strings.
- *
- * Returns the minimum number of single-character edits needed to transform one string into another.
+ * import { simhash } from 'elid';
  *
- * # JavaScript Example
+ * const hash1 = simhash("iPhone 14");
+ * const hash2 = simhash("iPhone 15");
+ * const hash3 = simhash("Galaxy S23");
  *
- * ```javascript
- * import { levenshtein } from 'elid';
+ * // hash1 and hash2 will be numerically close
+ * // hash3 will be numerically distant
  *
- * const distance = levenshtein("kitten", "sitting");
- * console.log(distance); // 3
+ * // Store in database as bigint:
+ * // { name: "iPhone 14", simhash: hash1 }
  * ```
- * @param {string} a
- * @param {string} b
+ * @param {string} text
  * @returns {number}
  */
-export function levenshtein(a, b) {
-    const ptr0 = passStringToWasm0(a, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+export function simhash(text) {
+    const ptr0 = passStringToWasm0(text, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
     const len0 = WASM_VECTOR_LEN;
-    const ptr1 = passStringToWasm0(b, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
-    const len1 = WASM_VECTOR_LEN;
-    const ret = wasm.levenshtein(ptr0, len0, ptr1, len1);
-    return ret >>> 0;
+    const ret = wasm.simhash(ptr0, len0);
+    return ret;
 }
 
 function passArrayJsValueToWasm0(array, malloc) {
@@ -269,31 +248,6 @@ export function findMatchesAboveThreshold(query, candidates, threshold) {
     return ret;
 }
 
-/**
- * Compute the Hamming distance between two SimHash values.
- *
- * Returns the number of differing bits. Lower values = higher similarity.
- *
- * # JavaScript Example
- *
- * ```javascript
- * import { simhash, simhashDistance } from 'elid';
- *
- * const hash1 = simhash("iPhone 14");
- * const hash2 = simhash("iPhone 15");
- * const distance = simhashDistance(hash1, hash2);
- *
- * console.log(distance); // Low number = similar
- * ```
- * @param {number} hash1
- * @param {number} hash2
- * @returns {number}
- */
-export function simhashDistance(hash1, hash2) {
-    const ret = wasm.simhashDistance(hash1, hash2);
-    return ret >>> 0;
-}
-
 let cachedFloat64ArrayMemory0 = null;
 
 function getFloat64ArrayMemory0() {
@@ -316,45 +270,49 @@ function takeFromExternrefTable0(idx) {
     return value;
 }
 /**
- * Encode an embedding with a maximum output string length constraint.
+ * Encode an embedding for cross-dimensional comparison.
  *
- * Calculates the optimal precision and dimension settings to fit within
- * the specified character limit while maximizing fidelity.
+ * Projects the embedding to a common dimension space, allowing comparison
+ * between embeddings of different original dimensions (e.g., 256d vs 768d).
  *
  * # Parameters
  *
  * - `embedding`: Float64 array of embedding values (64-2048 dimensions)
- * - `max_chars`: Maximum output string length in characters
+ * - `common_dims`: Target dimension space (all vectors projected here)
  *
  * # Returns
  *
- * A base32hex-encoded ELID string guaranteed to be <= max_chars in length.
+ * A base32hex-encoded ELID string.
  *
  * # JavaScript Example
  *
  * ```javascript
- * import { encodeElidMaxLength } from 'elid';
+ * import { encodeElidCrossDimensional, decodeElidToEmbedding } from 'elid';
  *
- * const embedding = new Float64Array(768).fill(0.1);
+ * // Different sized embeddings from different models
+ * const embedding256 = new Float64Array(256).fill(0.1);
+ * const embedding768 = new Float64Array(768).fill(0.1);
  *
- * // Fit in 100 characters (e.g., for database column constraints)
- * const elid = encodeElidMaxLength(embedding, 100);
- * console.log(elid.length <= 100); // true
+ * // Project both to 128-dim common space
+ * const elid1 = encodeElidCrossDimensional(embedding256, 128);
+ * const elid2 = encodeElidCrossDimensional(embedding768, 128);
  *
- * // Fit in 50 characters (more compression)
- * const shortElid = encodeElidMaxLength(embedding, 50);
+ * // Now they can be compared directly (both decode to 128 dims)
+ * const dec1 = decodeElidToEmbedding(elid1);
+ * const dec2 = decodeElidToEmbedding(elid2);
+ * // Both have length 128
  * ```
  * @param {Float64Array} embedding
- * @param {number} max_chars
+ * @param {number} common_dims
  * @returns {string}
  */
-export function encodeElidMaxLength(embedding, max_chars) {
+export function encodeElidCrossDimensional(embedding, common_dims) {
     let deferred3_0;
     let deferred3_1;
     try {
         const ptr0 = passArrayF64ToWasm0(embedding, wasm.__wbindgen_malloc);
         const len0 = WASM_VECTOR_LEN;
-        const ret = wasm.encodeElidMaxLength(ptr0, len0, max_chars);
+        const ret = wasm.encodeElidCrossDimensional(ptr0, len0, common_dims);
         var ptr2 = ret[0];
         var len2 = ret[1];
         if (ret[3]) {
@@ -369,154 +327,303 @@ export function encodeElidMaxLength(embedding, max_chars) {
     }
 }
 
-function _assertClass(instance, klass) {
-    if (!(instance instanceof klass)) {
-        throw new Error(`expected instance of ${klass.name}`);
+let cachedUint32ArrayMemory0 = null;
+
+function getUint32ArrayMemory0() {
+    if (cachedUint32ArrayMemory0 === null || cachedUint32ArrayMemory0.byteLength === 0) {
+        cachedUint32ArrayMemory0 = new Uint32Array(wasm.memory.buffer);
     }
+    return cachedUint32ArrayMemory0;
+}
+
+function getArrayU32FromWasm0(ptr, len) {
+    ptr = ptr >>> 0;
+    return getUint32ArrayMemory0().subarray(ptr / 4, ptr / 4 + len);
 }
 /**
- * Compute Levenshtein distance with custom options.
+ * Find all hashes within a given distance threshold.
+ *
+ * Useful for database queries - pre-compute hashes, then find similar ones.
  *
  * # JavaScript Example
  *
  * ```javascript
- * import { levenshteinWithOpts, SimilarityOptions } from 'elid';
+ * import { simhash, findSimilarHashes } from 'elid';
  *
- * const opts = new SimilarityOptions();
- * opts.setCaseSensitive(false);
- * opts.setTrimWhitespace(true);
+ * const candidates = ["iPhone 14 Pro", "iPhone 13", "Galaxy S23"];
+ * const hashes = candidates.map(s => simhash(s));
  *
- * const distance = levenshteinWithOpts("  HELLO  ", "hello", opts);
- * console.log(distance); // 0
+ * const queryHash = simhash("iPhone 14");
+ * const matches = findSimilarHashes(queryHash, hashes, 10);
+ *
+ * console.log(matches); // [0, 1] - indices of similar items
  * ```
- * @param {string} a
- * @param {string} b
- * @param {SimilarityOptions} opts
- * @returns {number}
+ * @param {number} query_hash
+ * @param {Float64Array} candidate_hashes
+ * @param {number} max_distance
+ * @returns {Uint32Array}
  */
-export function levenshteinWithOpts(a, b, opts) {
-    const ptr0 = passStringToWasm0(a, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+export function findSimilarHashes(query_hash, candidate_hashes, max_distance) {
+    const ptr0 = passArrayF64ToWasm0(candidate_hashes, wasm.__wbindgen_malloc);
     const len0 = WASM_VECTOR_LEN;
-    const ptr1 = passStringToWasm0(b, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
-    const len1 = WASM_VECTOR_LEN;
-    _assertClass(opts, SimilarityOptions);
-    var ptr2 = opts.__destroy_into_raw();
-    const ret = wasm.levenshteinWithOpts(ptr0, len0, ptr1, len1, ptr2);
-    return ret >>> 0;
+    const ret = wasm.findSimilarHashes(query_hash, ptr0, len0, max_distance);
+    var v2 = getArrayU32FromWasm0(ret[0], ret[1]).slice();
+    wasm.__wbindgen_free(ret[0], ret[1] * 4, 4);
+    return v2;
 }
 
 /**
- * Check if an ELID can be decoded back to an embedding.
- *
- * Returns true if the ELID was encoded with a FullVector profile
- * (lossless, compressed, or max_length), false otherwise.
- *
- * # Parameters
- *
- * - `elid_str`: A valid ELID string (base32hex encoded)
- *
- * # Returns
+ * Compute the Jaro similarity between two strings.
  *
- * `true` if decodeElidToEmbedding will return an embedding, `false` otherwise.
+ * Returns a value between 0.0 (completely different) and 1.0 (identical).
+ * Particularly effective for short strings like names.
  *
  * # JavaScript Example
  *
  * ```javascript
- * import { encodeElid, encodeElidLossless, isElidReversible, ElidProfile } from 'elid';
- *
- * const embedding = new Float64Array(768).fill(0.1);
- *
- * // Mini128 is NOT reversible
- * const mini128Elid = encodeElid(embedding, ElidProfile.Mini128);
- * console.log(isElidReversible(mini128Elid)); // false
+ * import { jaro } from 'elid';
  *
- * // Lossless IS reversible
- * const losslessElid = encodeElidLossless(embedding);
- * console.log(isElidReversible(losslessElid)); // true
+ * const similarity = jaro("martha", "marhta");
+ * console.log(similarity); // ~0.944
  * ```
- * @param {string} elid_str
- * @returns {boolean}
+ * @param {string} a
+ * @param {string} b
+ * @returns {number}
  */
-export function isElidReversible(elid_str) {
-    const ptr0 = passStringToWasm0(elid_str, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+export function jaro(a, b) {
+    const ptr0 = passStringToWasm0(a, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
     const len0 = WASM_VECTOR_LEN;
-    const ret = wasm.isElidReversible(ptr0, len0);
-    if (ret[2]) {
-        throw takeFromExternrefTable0(ret[1]);
-    }
-    return ret[0] !== 0;
+    const ptr1 = passStringToWasm0(b, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    const len1 = WASM_VECTOR_LEN;
+    const ret = wasm.jaro(ptr0, len0, ptr1, len1);
+    return ret;
 }
 
 /**
- * Compute the SimHash fingerprint of a string.
+ * Compute the best matching similarity between two strings.
  *
- * Returns a 64-bit hash where similar strings produce similar numbers.
- * Use this for database queries by storing the hash and querying by numeric range.
+ * Runs multiple algorithms and returns the highest score.
  *
  * # JavaScript Example
  *
  * ```javascript
- * import { simhash } from 'elid';
- *
- * const hash1 = simhash("iPhone 14");
- * const hash2 = simhash("iPhone 15");
- * const hash3 = simhash("Galaxy S23");
- *
- * // hash1 and hash2 will be numerically close
- * // hash3 will be numerically distant
+ * import { bestMatch } from 'elid';
  *
- * // Store in database as bigint:
- * // { name: "iPhone 14", simhash: hash1 }
+ * const score = bestMatch("hello", "hallo");
+ * console.log(score); // ~0.8
  * ```
- * @param {string} text
+ * @param {string} a
+ * @param {string} b
  * @returns {number}
  */
-export function simhash(text) {
-    const ptr0 = passStringToWasm0(text, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+export function bestMatch(a, b) {
+    const ptr0 = passStringToWasm0(a, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
     const len0 = WASM_VECTOR_LEN;
-    const ret = wasm.simhash(ptr0, len0);
+    const ptr1 = passStringToWasm0(b, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    const len1 = WASM_VECTOR_LEN;
+    const ret = wasm.bestMatch(ptr0, len0, ptr1, len1);
     return ret;
 }
 
-function getArrayU8FromWasm0(ptr, len) {
-    ptr = ptr >>> 0;
-    return getUint8ArrayMemory0().subarray(ptr / 1, ptr / 1 + len);
-}
 /**
- * Decode an ELID string to raw bytes.
+ * Encode an embedding vector to an ELID string.
  *
- * Returns the raw byte representation of an ELID, including the header
- * and payload bytes. Useful for custom processing or debugging.
+ * Converts a high-dimensional embedding (64-2048 dimensions) into a compact,
+ * sortable identifier. The ELID preserves locality properties for efficient
+ * similarity search.
  *
  * # Parameters
  *
- * - `elid_str`: A valid ELID string (base32hex encoded)
+ * - `embedding`: Float64 array of embedding values (64-2048 dimensions)
+ * - `profile`: Encoding profile (Mini128, Morton10x10, or Hilbert10x10)
  *
  * # Returns
  *
- * A Uint8Array containing the raw bytes (header + payload).
+ * A base32hex-encoded ELID string suitable for storage and comparison.
  *
  * # JavaScript Example
  *
  * ```javascript
- * import { decodeElid } from 'elid';
+ * import { encodeElid, ElidProfile } from 'elid';
  *
- * const bytes = decodeElid("012345abcdef...");
- * console.log(bytes); // Uint8Array [...]
+ * // OpenAI embeddings are 1536 dimensions
+ * const embedding = await getEmbedding("Hello world");
+ * const elid = encodeElid(embedding, ElidProfile.Mini128);
+ * console.log(elid); // "012345abcdef..."
+ * ```
+ * @param {Float64Array} embedding
+ * @param {ElidProfile} profile
+ * @returns {string}
+ */
+export function encodeElid(embedding, profile) {
+    let deferred3_0;
+    let deferred3_1;
+    try {
+        const ptr0 = passArrayF64ToWasm0(embedding, wasm.__wbindgen_malloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.encodeElid(ptr0, len0, profile);
+        var ptr2 = ret[0];
+        var len2 = ret[1];
+        if (ret[3]) {
+            ptr2 = 0; len2 = 0;
+            throw takeFromExternrefTable0(ret[2]);
+        }
+        deferred3_0 = ptr2;
+        deferred3_1 = len2;
+        return getStringFromWasm0(ptr2, len2);
+    } finally {
+        wasm.__wbindgen_free(deferred3_0, deferred3_1, 1);
+    }
+}
+
+/**
+ * Compute the normalized SimHash similarity between two strings.
+ *
+ * Returns a value between 0.0 (completely different) and 1.0 (identical).
+ *
+ * # JavaScript Example
+ *
+ * ```javascript
+ * import { simhashSimilarity } from 'elid';
+ *
+ * const similarity = simhashSimilarity("iPhone 14", "iPhone 15");
+ * console.log(similarity); // ~0.9 (very similar)
+ *
+ * const similarity2 = simhashSimilarity("iPhone", "Galaxy");
+ * console.log(similarity2); // ~0.4 (different)
+ * ```
+ * @param {string} a
+ * @param {string} b
+ * @returns {number}
+ */
+export function simhashSimilarity(a, b) {
+    const ptr0 = passStringToWasm0(a, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    const len0 = WASM_VECTOR_LEN;
+    const ptr1 = passStringToWasm0(b, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    const len1 = WASM_VECTOR_LEN;
+    const ret = wasm.simhashSimilarity(ptr0, len0, ptr1, len1);
+    return ret;
+}
+
+/**
+ * Encode an embedding using lossless full vector encoding.
+ *
+ * Preserves the exact embedding values (32-bit float precision) and all dimensions.
+ * This produces the largest output but allows exact reconstruction.
+ *
+ * # Parameters
+ *
+ * - `embedding`: Float64 array of embedding values (64-2048 dimensions)
+ *
+ * # Returns
+ *
+ * A base32hex-encoded ELID string that can be decoded back to the original embedding.
+ *
+ * # JavaScript Example
+ *
+ * ```javascript
+ * import { encodeElidLossless, decodeElidToEmbedding } from 'elid';
+ *
+ * const embedding = new Float64Array(768).fill(0.1);
+ * const elid = encodeElidLossless(embedding);
+ *
+ * // Later, recover the exact embedding
+ * const recovered = decodeElidToEmbedding(elid);
+ * // recovered is identical to embedding
+ * ```
+ * @param {Float64Array} embedding
+ * @returns {string}
+ */
+export function encodeElidLossless(embedding) {
+    let deferred3_0;
+    let deferred3_1;
+    try {
+        const ptr0 = passArrayF64ToWasm0(embedding, wasm.__wbindgen_malloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.encodeElidLossless(ptr0, len0);
+        var ptr2 = ret[0];
+        var len2 = ret[1];
+        if (ret[3]) {
+            ptr2 = 0; len2 = 0;
+            throw takeFromExternrefTable0(ret[2]);
+        }
+        deferred3_0 = ptr2;
+        deferred3_1 = len2;
+        return getStringFromWasm0(ptr2, len2);
+    } finally {
+        wasm.__wbindgen_free(deferred3_0, deferred3_1, 1);
+    }
+}
+
+/**
+ * Compute the normalized Levenshtein similarity between two strings.
+ *
+ * Returns a value between 0.0 (completely different) and 1.0 (identical).
+ *
+ * # JavaScript Example
+ *
+ * ```javascript
+ * import { normalizedLevenshtein } from 'elid';
+ *
+ * const similarity = normalizedLevenshtein("hello", "hallo");
+ * console.log(similarity); // ~0.8
+ * ```
+ * @param {string} a
+ * @param {string} b
+ * @returns {number}
+ */
+export function normalizedLevenshtein(a, b) {
+    const ptr0 = passStringToWasm0(a, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    const len0 = WASM_VECTOR_LEN;
+    const ptr1 = passStringToWasm0(b, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    const len1 = WASM_VECTOR_LEN;
+    const ret = wasm.normalizedLevenshtein(ptr0, len0, ptr1, len1);
+    return ret;
+}
+
+/**
+ * Decode an ELID string back to an embedding vector.
+ *
+ * Only works for ELIDs encoded with a FullVector profile (lossless,
+ * compressed, or max_length). Returns null for non-reversible profiles
+ * like Mini128, Morton, or Hilbert.
+ *
+ * # Parameters
+ *
+ * - `elid_str`: A valid ELID string (base32hex encoded)
+ *
+ * # Returns
+ *
+ * A Float64Array containing the decoded embedding, or null if the ELID
+ * is not reversible.
+ *
+ * Note: If dimension reduction was used during encoding, the decoded
+ * embedding will be in the reduced dimension space, not the original.
+ *
+ * # JavaScript Example
+ *
+ * ```javascript
+ * import { encodeElidLossless, decodeElidToEmbedding, isElidReversible } from 'elid';
+ *
+ * const embedding = new Float64Array(768).fill(0.1);
+ * const elid = encodeElidLossless(embedding);
+ *
+ * if (isElidReversible(elid)) {
+ *     const recovered = decodeElidToEmbedding(elid);
+ *     console.log(recovered.length); // 768
+ * }
  * ```
  * @param {string} elid_str
- * @returns {Uint8Array}
+ * @returns {any}
  */
-export function decodeElid(elid_str) {
+export function decodeElidToEmbedding(elid_str) {
     const ptr0 = passStringToWasm0(elid_str, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
     const len0 = WASM_VECTOR_LEN;
-    const ret = wasm.decodeElid(ptr0, len0);
-    if (ret[3]) {
-        throw takeFromExternrefTable0(ret[2]);
+    const ret = wasm.decodeElidToEmbedding(ptr0, len0);
+    if (ret[2]) {
+        throw takeFromExternrefTable0(ret[1]);
     }
-    var v2 = getArrayU8FromWasm0(ret[0], ret[1]).slice();
-    wasm.__wbindgen_free(ret[0], ret[1] * 1, 1);
-    return v2;
+    return takeFromExternrefTable0(ret[0]);
 }
 
 /**
@@ -561,62 +668,149 @@ export function getElidMetadata(elid_str) {
     return takeFromExternrefTable0(ret[0]);
 }
 
+function getArrayU8FromWasm0(ptr, len) {
+    ptr = ptr >>> 0;
+    return getUint8ArrayMemory0().subarray(ptr / 1, ptr / 1 + len);
+}
 /**
- * Encode an embedding for cross-dimensional comparison.
+ * Decode an ELID string to raw bytes.
  *
- * Projects the embedding to a common dimension space, allowing comparison
- * between embeddings of different original dimensions (e.g., 256d vs 768d).
+ * Returns the raw byte representation of an ELID, including the header
+ * and payload bytes. Useful for custom processing or debugging.
  *
  * # Parameters
  *
- * - `embedding`: Float64 array of embedding values (64-2048 dimensions)
- * - `common_dims`: Target dimension space (all vectors projected here)
+ * - `elid_str`: A valid ELID string (base32hex encoded)
  *
  * # Returns
  *
- * A base32hex-encoded ELID string.
+ * A Uint8Array containing the raw bytes (header + payload).
  *
  * # JavaScript Example
  *
  * ```javascript
- * import { encodeElidCrossDimensional, decodeElidToEmbedding } from 'elid';
+ * import { decodeElid } from 'elid';
  *
- * // Different sized embeddings from different models
- * const embedding256 = new Float64Array(256).fill(0.1);
- * const embedding768 = new Float64Array(768).fill(0.1);
+ * const bytes = decodeElid("012345abcdef...");
+ * console.log(bytes); // Uint8Array [...]
+ * ```
+ * @param {string} elid_str
+ * @returns {Uint8Array}
+ */
+export function decodeElid(elid_str) {
+    const ptr0 = passStringToWasm0(elid_str, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    const len0 = WASM_VECTOR_LEN;
+    const ret = wasm.decodeElid(ptr0, len0);
+    if (ret[3]) {
+        throw takeFromExternrefTable0(ret[2]);
+    }
+    var v2 = getArrayU8FromWasm0(ret[0], ret[1]).slice();
+    wasm.__wbindgen_free(ret[0], ret[1] * 1, 1);
+    return v2;
+}
+
+/**
+ * Compute the Levenshtein distance between two strings.
  *
- * // Project both to 128-dim common space
- * const elid1 = encodeElidCrossDimensional(embedding256, 128);
- * const elid2 = encodeElidCrossDimensional(embedding768, 128);
+ * Returns the minimum number of single-character edits needed to transform one string into another.
  *
- * // Now they can be compared directly (both decode to 128 dims)
- * const dec1 = decodeElidToEmbedding(elid1);
- * const dec2 = decodeElidToEmbedding(elid2);
- * // Both have length 128
+ * # JavaScript Example
+ *
+ * ```javascript
+ * import { levenshtein } from 'elid';
+ *
+ * const distance = levenshtein("kitten", "sitting");
+ * console.log(distance); // 3
  * ```
- * @param {Float64Array} embedding
- * @param {number} common_dims
- * @returns {string}
+ * @param {string} a
+ * @param {string} b
+ * @returns {number}
  */
-export function encodeElidCrossDimensional(embedding, common_dims) {
-    let deferred3_0;
-    let deferred3_1;
-    try {
-        const ptr0 = passArrayF64ToWasm0(embedding, wasm.__wbindgen_malloc);
-        const len0 = WASM_VECTOR_LEN;
-        const ret = wasm.encodeElidCrossDimensional(ptr0, len0, common_dims);
-        var ptr2 = ret[0];
-        var len2 = ret[1];
-        if (ret[3]) {
-            ptr2 = 0; len2 = 0;
-            throw takeFromExternrefTable0(ret[2]);
-        }
-        deferred3_0 = ptr2;
-        deferred3_1 = len2;
-        return getStringFromWasm0(ptr2, len2);
-    } finally {
-        wasm.__wbindgen_free(deferred3_0, deferred3_1, 1);
+export function levenshtein(a, b) {
+    const ptr0 = passStringToWasm0(a, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    const len0 = WASM_VECTOR_LEN;
+    const ptr1 = passStringToWasm0(b, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    const len1 = WASM_VECTOR_LEN;
+    const ret = wasm.levenshtein(ptr0, len0, ptr1, len1);
+    return ret >>> 0;
+}
+
+/**
+ * Check if an ELID can be decoded back to an embedding.
+ *
+ * Returns true if the ELID was encoded with a FullVector profile
+ * (lossless, compressed, or max_length), false otherwise.
+ *
+ * # Parameters
+ *
+ * - `elid_str`: A valid ELID string (base32hex encoded)
+ *
+ * # Returns
+ *
+ * `true` if decodeElidToEmbedding will return an embedding, `false` otherwise.
+ *
+ * # JavaScript Example
+ *
+ * ```javascript
+ * import { encodeElid, encodeElidLossless, isElidReversible, ElidProfile } from 'elid';
+ *
+ * const embedding = new Float64Array(768).fill(0.1);
+ *
+ * // Mini128 is NOT reversible
+ * const mini128Elid = encodeElid(embedding, ElidProfile.Mini128);
+ * console.log(isElidReversible(mini128Elid)); // false
+ *
+ * // Lossless IS reversible
+ * const losslessElid = encodeElidLossless(embedding);
+ * console.log(isElidReversible(losslessElid)); // true
+ * ```
+ * @param {string} elid_str
+ * @returns {boolean}
+ */
+export function isElidReversible(elid_str) {
+    const ptr0 = passStringToWasm0(elid_str, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    const len0 = WASM_VECTOR_LEN;
+    const ret = wasm.isElidReversible(ptr0, len0);
+    if (ret[2]) {
+        throw takeFromExternrefTable0(ret[1]);
     }
+    return ret[0] !== 0;
+}
+
+function _assertClass(instance, klass) {
+    if (!(instance instanceof klass)) {
+        throw new Error(`expected instance of ${klass.name}`);
+    }
+}
+/**
+ * Compute Levenshtein distance with custom options.
+ *
+ * # JavaScript Example
+ *
+ * ```javascript
+ * import { levenshteinWithOpts, SimilarityOptions } from 'elid';
+ *
+ * const opts = new SimilarityOptions();
+ * opts.setCaseSensitive(false);
+ * opts.setTrimWhitespace(true);
+ *
+ * const distance = levenshteinWithOpts("  HELLO  ", "hello", opts);
+ * console.log(distance); // 0
+ * ```
+ * @param {string} a
+ * @param {string} b
+ * @param {SimilarityOptions} opts
+ * @returns {number}
+ */
+export function levenshteinWithOpts(a, b, opts) {
+    const ptr0 = passStringToWasm0(a, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    const len0 = WASM_VECTOR_LEN;
+    const ptr1 = passStringToWasm0(b, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    const len1 = WASM_VECTOR_LEN;
+    _assertClass(opts, SimilarityOptions);
+    var ptr2 = opts.__destroy_into_raw();
+    const ret = wasm.levenshteinWithOpts(ptr0, len0, ptr1, len1, ptr2);
+    return ret >>> 0;
 }
 
 /**
@@ -696,126 +890,100 @@ export function findBestMatch(query, candidates) {
 }
 
 /**
- * Encode an embedding with percentage-based compression.
- *
- * The retention percentage (0.0-1.0) controls how much information is preserved:
- * - 1.0 = lossless (Full32 precision, all dimensions)
- * - 0.5 = half precision and/or half dimensions
- * - 0.25 = quarter precision and/or quarter dimensions
- *
- * The algorithm optimizes for dimension reduction first (which preserves
- * more geometric relationships) before reducing precision.
- *
- * # Parameters
- *
- * - `embedding`: Float64 array of embedding values (64-2048 dimensions)
- * - `retention_pct`: Information retention percentage (0.0-1.0)
- *
- * # Returns
+ * Compute the OSA (Optimal String Alignment) distance between two strings.
  *
- * A base32hex-encoded ELID string.
+ * Similar to Levenshtein but also considers transpositions as a single operation.
  *
  * # JavaScript Example
  *
  * ```javascript
- * import { encodeElidCompressed } from 'elid';
- *
- * const embedding = new Float64Array(768).fill(0.1);
- *
- * // 50% retention - good balance of size and fidelity
- * const elid = encodeElidCompressed(embedding, 0.5);
+ * import { osaDistance } from 'elid';
  *
- * // 25% retention - smaller but less accurate
- * const smallElid = encodeElidCompressed(embedding, 0.25);
+ * const distance = osaDistance("ca", "ac");
+ * console.log(distance); // 1 (transposition)
  * ```
- * @param {Float64Array} embedding
- * @param {number} retention_pct
- * @returns {string}
+ * @param {string} a
+ * @param {string} b
+ * @returns {number}
  */
-export function encodeElidCompressed(embedding, retention_pct) {
-    let deferred3_0;
-    let deferred3_1;
-    try {
-        const ptr0 = passArrayF64ToWasm0(embedding, wasm.__wbindgen_malloc);
-        const len0 = WASM_VECTOR_LEN;
-        const ret = wasm.encodeElidCompressed(ptr0, len0, retention_pct);
-        var ptr2 = ret[0];
-        var len2 = ret[1];
-        if (ret[3]) {
-            ptr2 = 0; len2 = 0;
-            throw takeFromExternrefTable0(ret[2]);
-        }
-        deferred3_0 = ptr2;
-        deferred3_1 = len2;
-        return getStringFromWasm0(ptr2, len2);
-    } finally {
-        wasm.__wbindgen_free(deferred3_0, deferred3_1, 1);
-    }
+export function osaDistance(a, b) {
+    const ptr0 = passStringToWasm0(a, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    const len0 = WASM_VECTOR_LEN;
+    const ptr1 = passStringToWasm0(b, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    const len1 = WASM_VECTOR_LEN;
+    const ret = wasm.osaDistance(ptr0, len0, ptr1, len1);
+    return ret >>> 0;
 }
 
 /**
- * Compute the Jaro similarity between two strings.
+ * Compute the Hamming distance between two SimHash values.
  *
- * Returns a value between 0.0 (completely different) and 1.0 (identical).
- * Particularly effective for short strings like names.
+ * Returns the number of differing bits. Lower values = higher similarity.
  *
  * # JavaScript Example
  *
  * ```javascript
- * import { jaro } from 'elid';
+ * import { simhash, simhashDistance } from 'elid';
  *
- * const similarity = jaro("martha", "marhta");
- * console.log(similarity); // ~0.944
+ * const hash1 = simhash("iPhone 14");
+ * const hash2 = simhash("iPhone 15");
+ * const distance = simhashDistance(hash1, hash2);
+ *
+ * console.log(distance); // Low number = similar
  * ```
- * @param {string} a
- * @param {string} b
+ * @param {number} hash1
+ * @param {number} hash2
  * @returns {number}
  */
-export function jaro(a, b) {
-    const ptr0 = passStringToWasm0(a, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
-    const len0 = WASM_VECTOR_LEN;
-    const ptr1 = passStringToWasm0(b, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
-    const len1 = WASM_VECTOR_LEN;
-    const ret = wasm.jaro(ptr0, len0, ptr1, len1);
-    return ret;
+export function simhashDistance(hash1, hash2) {
+    const ret = wasm.simhashDistance(hash1, hash2);
+    return ret >>> 0;
 }
 
 /**
- * Encode an embedding using lossless full vector encoding.
+ * Encode an embedding with percentage-based compression.
  *
- * Preserves the exact embedding values (32-bit float precision) and all dimensions.
- * This produces the largest output but allows exact reconstruction.
+ * The retention percentage (0.0-1.0) controls how much information is preserved:
+ * - 1.0 = lossless (Full32 precision, all dimensions)
+ * - 0.5 = half precision and/or half dimensions
+ * - 0.25 = quarter precision and/or quarter dimensions
+ *
+ * The algorithm optimizes for dimension reduction first (which preserves
+ * more geometric relationships) before reducing precision.
  *
  * # Parameters
  *
  * - `embedding`: Float64 array of embedding values (64-2048 dimensions)
+ * - `retention_pct`: Information retention percentage (0.0-1.0)
  *
  * # Returns
  *
- * A base32hex-encoded ELID string that can be decoded back to the original embedding.
+ * A base32hex-encoded ELID string.
  *
  * # JavaScript Example
  *
  * ```javascript
- * import { encodeElidLossless, decodeElidToEmbedding } from 'elid';
+ * import { encodeElidCompressed } from 'elid';
  *
  * const embedding = new Float64Array(768).fill(0.1);
- * const elid = encodeElidLossless(embedding);
  *
- * // Later, recover the exact embedding
- * const recovered = decodeElidToEmbedding(elid);
- * // recovered is identical to embedding
+ * // 50% retention - good balance of size and fidelity
+ * const elid = encodeElidCompressed(embedding, 0.5);
+ *
+ * // 25% retention - smaller but less accurate
+ * const smallElid = encodeElidCompressed(embedding, 0.25);
  * ```
  * @param {Float64Array} embedding
+ * @param {number} retention_pct
  * @returns {string}
  */
-export function encodeElidLossless(embedding) {
+export function encodeElidCompressed(embedding, retention_pct) {
     let deferred3_0;
     let deferred3_1;
     try {
         const ptr0 = passArrayF64ToWasm0(embedding, wasm.__wbindgen_malloc);
         const len0 = WASM_VECTOR_LEN;
-        const ret = wasm.encodeElidLossless(ptr0, len0);
+        const ret = wasm.encodeElidCompressed(ptr0, len0, retention_pct);
         var ptr2 = ret[0];
         var len2 = ret[1];
         if (ret[3]) {
@@ -831,87 +999,45 @@ export function encodeElidLossless(embedding) {
 }
 
 /**
- * Decode an ELID string back to an embedding vector.
+ * Encode an embedding with a maximum output string length constraint.
  *
- * Only works for ELIDs encoded with a FullVector profile (lossless,
- * compressed, or max_length). Returns null for non-reversible profiles
- * like Mini128, Morton, or Hilbert.
+ * Calculates the optimal precision and dimension settings to fit within
+ * the specified character limit while maximizing fidelity.
  *
  * # Parameters
  *
- * - `elid_str`: A valid ELID string (base32hex encoded)
+ * - `embedding`: Float64 array of embedding values (64-2048 dimensions)
+ * - `max_chars`: Maximum output string length in characters
  *
  * # Returns
  *
- * A Float64Array containing the decoded embedding, or null if the ELID
- * is not reversible.
- *
- * Note: If dimension reduction was used during encoding, the decoded
- * embedding will be in the reduced dimension space, not the original.
+ * A base32hex-encoded ELID string guaranteed to be <= max_chars in length.
  *
  * # JavaScript Example
  *
  * ```javascript
- * import { encodeElidLossless, decodeElidToEmbedding, isElidReversible } from 'elid';
+ * import { encodeElidMaxLength } from 'elid';
  *
  * const embedding = new Float64Array(768).fill(0.1);
- * const elid = encodeElidLossless(embedding);
- *
- * if (isElidReversible(elid)) {
- *     const recovered = decodeElidToEmbedding(elid);
- *     console.log(recovered.length); // 768
- * }
- * ```
- * @param {string} elid_str
- * @returns {any}
- */
-export function decodeElidToEmbedding(elid_str) {
-    const ptr0 = passStringToWasm0(elid_str, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
-    const len0 = WASM_VECTOR_LEN;
-    const ret = wasm.decodeElidToEmbedding(ptr0, len0);
-    if (ret[2]) {
-        throw takeFromExternrefTable0(ret[1]);
-    }
-    return takeFromExternrefTable0(ret[0]);
-}
-
-/**
- * Encode an embedding vector to an ELID string.
- *
- * Converts a high-dimensional embedding (64-2048 dimensions) into a compact,
- * sortable identifier. The ELID preserves locality properties for efficient
- * similarity search.
- *
- * # Parameters
- *
- * - `embedding`: Float64 array of embedding values (64-2048 dimensions)
- * - `profile`: Encoding profile (Mini128, Morton10x10, or Hilbert10x10)
- *
- * # Returns
- *
- * A base32hex-encoded ELID string suitable for storage and comparison.
- *
- * # JavaScript Example
  *
- * ```javascript
- * import { encodeElid, ElidProfile } from 'elid';
+ * // Fit in 100 characters (e.g., for database column constraints)
+ * const elid = encodeElidMaxLength(embedding, 100);
+ * console.log(elid.length <= 100); // true
  *
- * // OpenAI embeddings are 1536 dimensions
- * const embedding = await getEmbedding("Hello world");
- * const elid = encodeElid(embedding, ElidProfile.Mini128);
- * console.log(elid); // "012345abcdef..."
+ * // Fit in 50 characters (more compression)
+ * const shortElid = encodeElidMaxLength(embedding, 50);
  * ```
  * @param {Float64Array} embedding
- * @param {ElidProfile} profile
+ * @param {number} max_chars
  * @returns {string}
  */
-export function encodeElid(embedding, profile) {
+export function encodeElidMaxLength(embedding, max_chars) {
     let deferred3_0;
     let deferred3_1;
     try {
         const ptr0 = passArrayF64ToWasm0(embedding, wasm.__wbindgen_malloc);
         const len0 = WASM_VECTOR_LEN;
-        const ret = wasm.encodeElid(ptr0, len0, profile);
+        const ret = wasm.encodeElidMaxLength(ptr0, len0, max_chars);
         var ptr2 = ret[0];
         var len2 = ret[1];
         if (ret[3]) {
@@ -927,31 +1053,29 @@ export function encodeElid(embedding, profile) {
 }
 
 /**
- * Compute the normalized SimHash similarity between two strings.
+ * Compute the Jaro-Winkler similarity between two strings.
  *
  * Returns a value between 0.0 (completely different) and 1.0 (identical).
+ * Gives more favorable ratings to strings with common prefixes.
  *
  * # JavaScript Example
  *
  * ```javascript
- * import { simhashSimilarity } from 'elid';
- *
- * const similarity = simhashSimilarity("iPhone 14", "iPhone 15");
- * console.log(similarity); // ~0.9 (very similar)
+ * import { jaroWinkler } from 'elid';
  *
- * const similarity2 = simhashSimilarity("iPhone", "Galaxy");
- * console.log(similarity2); // ~0.4 (different)
+ * const similarity = jaroWinkler("martha", "marhta");
+ * console.log(similarity); // ~0.961
  * ```
  * @param {string} a
  * @param {string} b
  * @returns {number}
  */
-export function simhashSimilarity(a, b) {
+export function jaroWinkler(a, b) {
     const ptr0 = passStringToWasm0(a, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
     const len0 = WASM_VECTOR_LEN;
     const ptr1 = passStringToWasm0(b, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
     const len1 = WASM_VECTOR_LEN;
-    const ret = wasm.simhashSimilarity(ptr0, len0, ptr1, len1);
+    const ret = wasm.jaroWinkler(ptr0, len0, ptr1, len1);
     return ret;
 }
 
@@ -985,130 +1109,6 @@ export function hamming(a, b) {
     return ret === 0x100000001 ? undefined : ret;
 }
 
-/**
- * Compute the best matching similarity between two strings.
- *
- * Runs multiple algorithms and returns the highest score.
- *
- * # JavaScript Example
- *
- * ```javascript
- * import { bestMatch } from 'elid';
- *
- * const score = bestMatch("hello", "hallo");
- * console.log(score); // ~0.8
- * ```
- * @param {string} a
- * @param {string} b
- * @returns {number}
- */
-export function bestMatch(a, b) {
-    const ptr0 = passStringToWasm0(a, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
-    const len0 = WASM_VECTOR_LEN;
-    const ptr1 = passStringToWasm0(b, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
-    const len1 = WASM_VECTOR_LEN;
-    const ret = wasm.bestMatch(ptr0, len0, ptr1, len1);
-    return ret;
-}
-
-/**
- * Compute the Jaro-Winkler similarity between two strings.
- *
- * Returns a value between 0.0 (completely different) and 1.0 (identical).
- * Gives more favorable ratings to strings with common prefixes.
- *
- * # JavaScript Example
- *
- * ```javascript
- * import { jaroWinkler } from 'elid';
- *
- * const similarity = jaroWinkler("martha", "marhta");
- * console.log(similarity); // ~0.961
- * ```
- * @param {string} a
- * @param {string} b
- * @returns {number}
- */
-export function jaroWinkler(a, b) {
-    const ptr0 = passStringToWasm0(a, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
-    const len0 = WASM_VECTOR_LEN;
-    const ptr1 = passStringToWasm0(b, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
-    const len1 = WASM_VECTOR_LEN;
-    const ret = wasm.jaroWinkler(ptr0, len0, ptr1, len1);
-    return ret;
-}
-
-/**
- * Compute the normalized Levenshtein similarity between two strings.
- *
- * Returns a value between 0.0 (completely different) and 1.0 (identical).
- *
- * # JavaScript Example
- *
- * ```javascript
- * import { normalizedLevenshtein } from 'elid';
- *
- * const similarity = normalizedLevenshtein("hello", "hallo");
- * console.log(similarity); // ~0.8
- * ```
- * @param {string} a
- * @param {string} b
- * @returns {number}
- */
-export function normalizedLevenshtein(a, b) {
-    const ptr0 = passStringToWasm0(a, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
-    const len0 = WASM_VECTOR_LEN;
-    const ptr1 = passStringToWasm0(b, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
-    const len1 = WASM_VECTOR_LEN;
-    const ret = wasm.normalizedLevenshtein(ptr0, len0, ptr1, len1);
-    return ret;
-}
-
-let cachedUint32ArrayMemory0 = null;
-
-function getUint32ArrayMemory0() {
-    if (cachedUint32ArrayMemory0 === null || cachedUint32ArrayMemory0.byteLength === 0) {
-        cachedUint32ArrayMemory0 = new Uint32Array(wasm.memory.buffer);
-    }
-    return cachedUint32ArrayMemory0;
-}
-
-function getArrayU32FromWasm0(ptr, len) {
-    ptr = ptr >>> 0;
-    return getUint32ArrayMemory0().subarray(ptr / 4, ptr / 4 + len);
-}
-/**
- * Find all hashes within a given distance threshold.
- *
- * Useful for database queries - pre-compute hashes, then find similar ones.
- *
- * # JavaScript Example
- *
- * ```javascript
- * import { simhash, findSimilarHashes } from 'elid';
- *
- * const candidates = ["iPhone 14 Pro", "iPhone 13", "Galaxy S23"];
- * const hashes = candidates.map(s => simhash(s));
- *
- * const queryHash = simhash("iPhone 14");
- * const matches = findSimilarHashes(queryHash, hashes, 10);
- *
- * console.log(matches); // [0, 1] - indices of similar items
- * ```
- * @param {number} query_hash
- * @param {Float64Array} candidate_hashes
- * @param {number} max_distance
- * @returns {Uint32Array}
- */
-export function findSimilarHashes(query_hash, candidate_hashes, max_distance) {
-    const ptr0 = passArrayF64ToWasm0(candidate_hashes, wasm.__wbindgen_malloc);
-    const len0 = WASM_VECTOR_LEN;
-    const ret = wasm.findSimilarHashes(query_hash, ptr0, len0, max_distance);
-    var v2 = getArrayU32FromWasm0(ret[0], ret[1]).slice();
-    wasm.__wbindgen_free(ret[0], ret[1] * 4, 4);
-    return v2;
-}
-
 /**
  * Dimension handling mode for full vector encoding.
  *