@higher.archi/boe 1.0.0

package/src/functions/phonetic/caverphone2.ts

@@ -0,0 +1,172 @@
+/**
+ * Caverphone 2.0 Phonetic Algorithm
+ *
+ * Developed by the Caversham Project at the University of Otago, New Zealand.
+ * Designed specifically for matching names in databases, particularly for
+ * New Zealand and Australian accents.
+ *
+ * Returns a 10-character phonetic code. More complex than Soundex or NYSIIS,
+ * with 12 transformation steps.
+ *
+ * @param name - Name to encode
+ * @returns 10-character Caverphone2 code
+ *
+ * @example
+ * caverphone2('Thompson')  // Returns "TMPSN11111"
+ * caverphone2('Thomson')   // Returns "TMPSN11111" (same encoding)
+ * caverphone2('Smith')     // Returns "SMT1111111"
+ * caverphone2('Smythe')    // Returns "SMT1111111" (same encoding)
+ * caverphone2('Peter')     // Returns "PTA1111111"
+ * caverphone2('Peadar')    // Returns "PTA1111111" (same encoding)
+ */
+export function caverphone2(name: string): string {
+  if (!name || name.length === 0) {
+    return '1111111111';
+  }
+
+  // Convert to lowercase for processing
+  let code = name.toLowerCase().replace(/[^a-z]/g, '');
+
+  if (code.length === 0) {
+    return '1111111111';
+  }
+
+  // Step 1: Remove final e
+  if (code.endsWith('e')) {
+    code = code.slice(0, -1);
+  }
+
+  // Step 2: Handle special patterns at the start
+  // If starts with cough, rough, tough, enough → replace with gof, ruf, tuf, enuf
+  if (code.startsWith('cough')) {
+    code = 'gof' + code.slice(5);
+  }
+  if (code.startsWith('rough')) {
+    code = 'ruf' + code.slice(5);
+  }
+  if (code.startsWith('tough')) {
+    code = 'tuf' + code.slice(5);
+  }
+  if (code.startsWith('enough')) {
+    code = 'enuf' + code.slice(6);
+  }
+
+  // If starts with gn, replace with 2n
+  if (code.startsWith('gn')) {
+    code = '2n' + code.slice(2);
+  }
+
+  // Step 3: Replace mb at end with m2
+  if (code.endsWith('mb')) {
+    code = code.slice(0, -2) + 'm2';
+  }
+
+  // Step 4: Series of replacements
+  code = code.replace(/cq/g, '2q');
+  code = code.replace(/ci/g, 'si');
+  code = code.replace(/ce/g, 'se');
+  code = code.replace(/cy/g, 'sy');
+  code = code.replace(/tch/g, '2ch');
+  code = code.replace(/c/g, 'k');
+  code = code.replace(/q/g, 'k');
+  code = code.replace(/x/g, 'k');
+  code = code.replace(/v/g, 'f');
+  code = code.replace(/dg/g, '2g');
+  code = code.replace(/tio/g, 'sio');
+  code = code.replace(/tia/g, 'sia');
+  code = code.replace(/d/g, 't');
+  code = code.replace(/ph/g, 'fh');
+  code = code.replace(/b/g, 'p');
+  code = code.replace(/sh/g, 's2');
+  code = code.replace(/z/g, 's');
+
+  // Step 5: Replace initial vowel patterns
+  if (code.match(/^[aeiou]/)) {
+    code = 'A' + code.slice(1);
+  }
+
+  // Step 6: Replace all other vowels with 3
+  code = code.replace(/[aeiou]/g, '3');
+
+  // Step 7: Replace j with y
+  code = code.replace(/j/g, 'y');
+
+  // Step 8: Replace initial y3 with Y3, initial y with A
+  if (code.startsWith('y3')) {
+    code = 'Y3' + code.slice(2);
+  } else if (code.startsWith('y')) {
+    code = 'A' + code.slice(1);
+  }
+
+  // Step 9: Replace y with 3
+  code = code.replace(/y/g, '3');
+
+  // Step 10: Replace 3gh3 with 3kh3
+  code = code.replace(/3gh3/g, '3kh3');
+
+  // Step 11: Replace gh with 22
+  code = code.replace(/gh/g, '22');
+
+  // Step 12: Replace g with k
+  code = code.replace(/g/g, 'k');
+
+  // Step 13: Collapse groups of s, t, p, k, f, m, n
+  code = code.replace(/s+/g, 'S');
+  code = code.replace(/t+/g, 'T');
+  code = code.replace(/p+/g, 'P');
+  code = code.replace(/k+/g, 'K');
+  code = code.replace(/f+/g, 'F');
+  code = code.replace(/m+/g, 'M');
+  code = code.replace(/n+/g, 'N');
+
+  // Step 14: Convert back to lowercase
+  code = code.toLowerCase();
+
+  // Step 15: Remove all 2s, 3s, and h's
+  code = code.replace(/[23h]/g, '');
+
+  // Step 16: Replace r at end with 1
+  if (code.endsWith('r')) {
+    code = code.slice(0, -1) + '1';
+  }
+
+  // Step 17: Replace r with blank (remove)
+  code = code.replace(/r/g, '');
+
+  // Step 18: Replace l at end with 1
+  if (code.endsWith('l')) {
+    code = code.slice(0, -1) + '1';
+  }
+
+  // Step 19: Replace l with blank (remove)
+  code = code.replace(/l/g, '');
+
+  // Step 20: Replace w at end with 1
+  if (code.endsWith('w')) {
+    code = code.slice(0, -1) + '1';
+  }
+
+  // Step 21: Replace w with blank (remove)
+  code = code.replace(/w/g, '');
+
+  // Step 22: Pad with 1s or truncate to 10 characters
+  code = code.padEnd(10, '1').slice(0, 10);
+
+  return code.toUpperCase();
+}
+
+/**
+ * Compare two names using Caverphone2 encoding
+ *
+ * @param name1 - First name to compare
+ * @param name2 - Second name to compare
+ * @returns true if names sound similar (same Caverphone2 code)
+ *
+ * @example
+ * caverphone2Match('Thompson', 'Thomson')  // Returns true
+ * caverphone2Match('Smith', 'Smythe')      // Returns true
+ * caverphone2Match('Peter', 'Peadar')      // Returns true
+ */
+export function caverphone2Match(name1: string, name2: string): boolean {
+  return caverphone2(name1) === caverphone2(name2);
+}

package/src/functions/phonetic/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Phonetic Encoding Functions
+ *
+ * Functions for encoding names into phonetic codes for matching similar-sounding names.
+ */
+
+export { soundex, soundexMatch } from './soundex';
+export { nysiis, nysiisMatch } from './nysiis';
+export { caverphone2, caverphone2Match } from './caverphone2';

package/src/functions/phonetic/nysiis.ts

@@ -0,0 +1,164 @@
+/**
+ * NYSIIS Phonetic Algorithm
+ *
+ * New York State Identification and Intelligence System (NYSIIS)
+ * Encodes names into a phonetic code for matching names that sound similar.
+ *
+ * Implementation by Kamau Washington based on Wikipedia specification:
+ * https://en.wikipedia.org/wiki/New_York_State_Identification_and_Intelligence_System
+ *
+ * Developed by the New York State Identification and Intelligence System in 1970.
+ * More accurate than Soundex for matching names with different spellings.
+ *
+ * @param input - Name to encode
+ * @returns NYSIIS phonetic code (max 6 characters), or empty string if no input
+ *
+ * @example
+ * nysiis('McDonald')   // Returns "MCDANA"
+ * nysiis('Macdonald')  // Returns "MCDANA" (same encoding)
+ * nysiis('Johnson')    // Returns "JANSAN"
+ * nysiis('Jonson')     // Returns "JANSAN" (same encoding)
+ * nysiis('Schmidt')    // Returns "SNAD"
+ * nysiis('Smith')      // Returns "SNAT" (different - they don't match)
+ */
+export function nysiis(input: string): string {
+  // Vowel array defined outside of processing loop
+  const vowels = ['A', 'E', 'I', 'O', 'U'];
+
+  // Helper function to replace character at an index
+  const replaceAt = (str: string, index: number, replace: string = ''): string => {
+    const deleteCount = replace.length || 1;
+    return str.slice(0, index) + replace + str.slice(index + deleteCount);
+  };
+
+  // Fail fast if there isn't an input value to code (code defensively)
+  if (!input || input.length === 0) {
+    return '';
+  }
+
+  // Strip leading and trailing whitespace
+  input = input.trim();
+
+  // Make input uppercase (wiki algorithm doesn't mention this as first step)
+  input = input.toUpperCase();
+
+  // Step 1: Prefix transformations
+  if (input.startsWith('MAC')) {
+    input = 'MCC' + input.slice(3);
+  } else if (input.startsWith('KN')) {
+    input = 'NN' + input.slice(2);
+  } else if (input.startsWith('K')) {
+    input = 'C' + input.slice(1);
+  } else if (input.startsWith('PH')) {
+    input = 'FF' + input.slice(2);
+  } else if (input.startsWith('PF')) {
+    input = 'FF' + input.slice(2);
+  } else if (input.startsWith('SCH')) {
+    input = 'SSS' + input.slice(3);
+  }
+
+  // Step 2: Suffix transformations
+  if (input.endsWith('EE')) {
+    input = input.slice(0, -2) + 'Y';
+  } else if (input.endsWith('IE')) {
+    input = input.slice(0, -2) + 'Y';
+  }
+
+  for (const item of ['DT', 'RT', 'RD', 'NT', 'ND']) {
+    if (input.endsWith(item)) {
+      input = input.slice(0, -2) + 'D';
+      break;
+    }
+  }
+
+  // Steps 3-4: Character-by-character processing
+  let idx = 1;
+
+  while (idx < input.length) {
+    // Step 5 (1): Only process letters, skip all other characters including spaces
+    if (!/[A-Za-z]/.test(input[idx])) {
+      input = replaceAt(input, idx);
+      // Keeps current index and restarts
+      continue;
+    }
+
+    // Step 5 (2): Vowel handling
+    if (vowels.includes(input[idx])) {
+      if (input.slice(idx, idx + 2) === 'EV') {
+        input = replaceAt(input, idx, 'EV');
+      } else {
+        input = replaceAt(input, idx, 'A');
+      }
+    }
+    // Step 5 (3): Q, Z, M transformations
+    else if (input[idx] === 'Q') {
+      input = replaceAt(input, idx, 'G');
+    } else if (input[idx] === 'Z') {
+      input = replaceAt(input, idx, 'S');
+    } else if (input[idx] === 'M') {
+      input = replaceAt(input, idx, 'N');
+    }
+    // Step 5 (4): KN and K transformations
+    else if (input.slice(idx, idx + 2) === 'KN') {
+      input = replaceAt(input, idx, 'N');
+    } else if (input[idx] === 'K') {
+      input = replaceAt(input, idx, 'C');
+    }
+    // Step 5 (5): PH transformation
+    else if (input.slice(idx, idx + 2) === 'PH') {
+      input = replaceAt(input, idx, 'FF');
+    }
+    // Step 5 (6): H transformation
+    // Replace H with previous char if (previous not vowel OR next not vowel)
+    else if (input[idx] === 'H' && (!vowels.includes(input[idx - 1]) || !vowels.includes(input[idx + 1] || ''))) {
+      input = replaceAt(input, idx, input[idx - 1]);
+    }
+    // Step 5 (7): W transformation
+    // Replace W with previous char if previous is a vowel
+    else if (input[idx] === 'W' && vowels.includes(input[idx - 1])) {
+      input = replaceAt(input, idx, input[idx - 1]);
+    }
+
+    // Step 6: Remove duplicate consecutive characters
+    if (input[idx] === input[idx - 1]) {
+      input = replaceAt(input, idx, '');
+      continue;
+    }
+
+    idx++;
+  }
+
+  // Step 7: Remove trailing S
+  if (input.endsWith('S')) {
+    input = input.slice(0, -1);
+  }
+
+  // Step 8: Handle AY ending
+  if (input.endsWith('AY')) {
+    input = input.slice(0, -2) + 'Y';
+  }
+
+  // Step 9: Remove trailing A
+  if (input.endsWith('A')) {
+    input = input.slice(0, -1);
+  }
+
+  // Return first 6 characters
+  return input.slice(0, 6);
+}
+
+/**
+ * Compare two names using NYSIIS encoding
+ *
+ * @param name1 - First name to compare
+ * @param name2 - Second name to compare
+ * @returns true if names sound similar (same NYSIIS code)
+ *
+ * @example
+ * nysiisMatch('McDonald', 'Macdonald')  // Returns true
+ * nysiisMatch('Johnson', 'Jonson')      // Returns true
+ * nysiisMatch('Schmidt', 'Smith')       // Returns false (different codes)
+ */
+export function nysiisMatch(name1: string, name2: string): boolean {
+  return nysiis(name1) === nysiis(name2);
+}

package/src/functions/phonetic/soundex.ts

@@ -0,0 +1,111 @@
+/**
+ * Soundex Phonetic Algorithm
+ *
+ * Encodes names into a 4-character phonetic code (1 letter + 3 digits).
+ * Names that sound similar will have the same Soundex code.
+ *
+ * Developed by Robert C. Russell and Margaret King Odell in 1918-1922.
+ * Widely used in genealogy, census data, and name matching.
+ *
+ * Algorithm:
+ * 1. Keep the first letter
+ * 2. Replace consonants with digits based on phonetic similarity:
+ *    - B, F, P, V → 1
+ *    - C, G, J, K, Q, S, X, Z → 2
+ *    - D, T → 3
+ *    - L → 4
+ *    - M, N → 5
+ *    - R → 6
+ * 3. Remove adjacent duplicate digits
+ * 4. Remove all occurrences of A, E, I, O, U, H, W, Y (except first letter)
+ * 5. Pad with zeros or truncate to 4 characters
+ *
+ * @param name - Name to encode
+ * @returns 4-character Soundex code (e.g., "R163" for "Robert")
+ *
+ * @example
+ * soundex('Robert')    // Returns "R163"
+ * soundex('Rupert')    // Returns "R163" (sounds similar)
+ * soundex('Smith')     // Returns "S530"
+ * soundex('Smythe')    // Returns "S530" (sounds similar)
+ * soundex('Johnson')   // Returns "J525"
+ * soundex('Jonson')    // Returns "J525" (sounds similar)
+ */
+export function soundex(name: string): string {
+  if (!name || name.length === 0) {
+    return '0000';
+  }
+
+  // Convert to uppercase and remove non-alphabetic characters
+  const cleaned = name.toUpperCase().replace(/[^A-Z]/g, '');
+
+  if (cleaned.length === 0) {
+    return '0000';
+  }
+
+  // Keep first letter
+  const firstLetter = cleaned[0];
+
+  // Soundex digit mapping
+  const soundexMap: Record<string, string> = {
+    'B': '1', 'F': '1', 'P': '1', 'V': '1',
+    'C': '2', 'G': '2', 'J': '2', 'K': '2', 'Q': '2', 'S': '2', 'X': '2', 'Z': '2',
+    'D': '3', 'T': '3',
+    'L': '4',
+    'M': '5', 'N': '5',
+    'R': '6',
+    // A, E, I, O, U, H, W, Y → removed (mapped to '0')
+    'A': '0', 'E': '0', 'I': '0', 'O': '0', 'U': '0', 'H': '0', 'W': '0', 'Y': '0'
+  };
+
+  // Convert all characters to Soundex digits
+  let code = firstLetter;
+  let prevDigit = soundexMap[firstLetter] || '0';
+
+  for (let i = 1; i < cleaned.length; i++) {
+    const char = cleaned[i];
+    const digit = soundexMap[char] || '0';
+
+    // Skip if same as previous digit (remove adjacent duplicates)
+    if (digit === prevDigit) {
+      continue;
+    }
+
+    // Skip zeros (vowels and H, W, Y)
+    if (digit === '0') {
+      prevDigit = digit;
+      continue;
+    }
+
+    code += digit;
+    prevDigit = digit;
+
+    // Stop when we have 4 characters
+    if (code.length === 4) {
+      break;
+    }
+  }
+
+  // Pad with zeros if needed
+  while (code.length < 4) {
+    code += '0';
+  }
+
+  return code;
+}
+
+/**
+ * Compare two names using Soundex encoding
+ *
+ * @param name1 - First name to compare
+ * @param name2 - Second name to compare
+ * @returns true if names sound similar (same Soundex code)
+ *
+ * @example
+ * soundexMatch('Robert', 'Rupert')  // Returns true
+ * soundexMatch('Smith', 'Smythe')   // Returns true
+ * soundexMatch('Johnson', 'Jackson') // Returns false
+ */
+export function soundexMatch(name1: string, name2: string): boolean {
+  return soundex(name1) === soundex(name2);
+}

package/src/functions/similarity/cosine-similarity.ts

@@ -0,0 +1,83 @@
+/**
+ * Cosine Similarity
+ *
+ * Compares two text inputs using word-frequency vectors.
+ * Returns a similarity score between 0 and 1, where:
+ * - 0 = completely dissimilar
+ * - 1 = identical
+ *
+ * Algorithm:
+ * 1. Tokenize both inputs into words
+ * 2. Build frequency vectors for each word across both inputs
+ * 3. Calculate dot product of vectors
+ * 4. Calculate magnitude (length) of each vector
+ * 5. Return: dot_product / (magnitude1 * magnitude2)
+ *
+ * @param text1 - First text to compare
+ * @param text2 - Second text to compare
+ * @returns Similarity score rounded to 2 decimal places (0.00 - 1.00)
+ *
+ * @example
+ * cosineSimilarity('the quick brown fox', 'the lazy brown dog')
+ * // Returns 0.50 (50% similar - shared words: 'the', 'brown')
+ *
+ * cosineSimilarity('hello world', 'hello world')
+ * // Returns 1.00 (100% identical)
+ *
+ * cosineSimilarity('foo bar', 'baz qux')
+ * // Returns 0.00 (0% similar - no shared words)
+ */
+export function cosineSimilarity(text1: string, text2: string): number {
+  // Tokenize inputs into words
+  const words1 = text1.toLowerCase().split(/\s+/).filter(w => w.length > 0);
+  const words2 = text2.toLowerCase().split(/\s+/).filter(w => w.length > 0);
+
+  // Build combined vocabulary (all unique words from both texts)
+  const vocabulary = new Set([...words1, ...words2]);
+
+  // Build frequency vectors
+  const vector1: Record<string, number> = {};
+  const vector2: Record<string, number> = {};
+
+  for (const word of vocabulary) {
+    vector1[word] = 0;
+    vector2[word] = 0;
+  }
+
+  for (const word of words1) {
+    vector1[word]++;
+  }
+
+  for (const word of words2) {
+    vector2[word]++;
+  }
+
+  // Calculate dot product
+  let dotProduct = 0;
+  for (const word of vocabulary) {
+    dotProduct += vector1[word] * vector2[word];
+  }
+
+  // Calculate magnitudes
+  let magnitude1 = 0;
+  let magnitude2 = 0;
+
+  for (const word of vocabulary) {
+    magnitude1 += vector1[word] ** 2;
+    magnitude2 += vector2[word] ** 2;
+  }
+
+  magnitude1 = Math.sqrt(magnitude1);
+  magnitude2 = Math.sqrt(magnitude2);
+
+  // Handle division by zero (empty inputs)
+  if (magnitude1 === 0 || magnitude2 === 0) {
+    return 0.0;
+  }
+
+  // Calculate cosine similarity
+  const similarity = dotProduct / (magnitude1 * magnitude2);
+
+  // Round to 2 decimal places
+  return Math.round(similarity * 100) / 100;
+}

package/src/functions/similarity/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Text Similarity Functions
+ *
+ * Functions for measuring similarity between text strings.
+ */
+
+export { cosineSimilarity } from './cosine-similarity';