@fileverse-dev/formulajs 4.4.20-mod-1 → 4.4.20-mod-3

package/lib/esm/index.mjs

@@ -1439,115 +1439,392 @@ function VLOOKUP(lookup_value, table_array, col_index_num, range_lookup) {
   return result
 }
 
-function XLOOKUP(lookup_value, lookup_array, return_array, if_not_found, match_mode, search_mode) {
-  // Handle case where error object might not be defined
-  const ERROR_NA = '#N/A';
-  const ERROR_REF = '#REF!';
+function XLOOKUP(search_key, lookup_range, result_range, missing_value, isCol,match_mode, search_mode) {
+console.log('XLOOKUP parameters:', { search_key, lookup_range, result_range, missing_value, match_mode, search_mode, isCol });
+  
+  // Validate required parameters
+  if (search_key === undefined || search_key === null) {
+    console.log('Error: search_key is required');
+    return new Error('Error: search_key is required')
+  }
+  
+  if (!lookup_range || !result_range) {
+    console.log('Error: lookup_range and result_range are required');
+    return new Error('Error: lookup_range and result_range are required')
+  }
+  
+  // Validate and normalize lookup_range (must be singular row or column)
+  let lookup_array = normalizeLookupRange(lookup_range);
+  if (!lookup_array) {
+    console.log('Error: lookup_range must be a singular row or column');
+    return new Error('Error: lookup_range must be a singular row or column')
+  }
+  
+  // Validate and normalize result_range
+  let result_array = normalizeResultRange(result_range);
+  if (!result_array) {
+    console.log('Error: Invalid result_range');
+    return new Error('Error: Invalid result_range')
+  }
+  
+  // Validate that lookup and result ranges have compatible dimensions
+  // Exception: if result_range is a single row, it can be returned regardless of lookup_range length  
+result_array.map((row) => {
+    if (row.length !== lookup_array.length) {
+      console.log('Error: lookup_range and result_range must have the same number of columns');
+      return new Error('Error: lookup_range and result_range must have the same number of columns/rows')
+    }
+  });
+  
+  // Set default parameter values
+  missing_value = missing_value !== undefined ? missing_value : new Error("Error: Didn't find value in XLOOKUP evaluation");
+  match_mode = match_mode !== undefined ? match_mode : 0;
+  search_mode = search_mode !== undefined ? search_mode : 1;
+  isCol = isCol !== undefined ? isCol : false;
+  
+  // Validate match_mode
+  if (![0, 1, -1, 2].includes(match_mode)) {
+    console.log('Error: match_mode must be 0, 1, -1, or 2');
+    return new Error('Error: match_mode must be 0, 1, -1, or 2')
+  }
+  
+  // Validate search_mode
+  if (![1, -1, 2, -2].includes(search_mode)) {
+    console.log('Error: search_mode must be 1, -1, 2, or -2');
+    return new Error('Error: search_mode must be 1, -1, 2, or -2')
+  }
+  
+  // Validate binary search requirements
+  if (Math.abs(search_mode) === 2 && match_mode === 2) {
+    console.log('Error: Binary search (search_mode ±2) cannot be used with wildcard matching (match_mode 2)');
+    return new Error('Error: Binary search (search_mode ±2) cannot be used with wildcard matching (match_mode 2)')
+  }
+  
+  console.log('Normalized arrays:', { lookup_array, result_array });
+  
+  let res = performLookup(search_key, lookup_array, result_array, missing_value, match_mode, search_mode, isCol);
+  res = isCol ? Array.isArray(res)?res.map((item) => [item.toString()]):res : res;
+  return res
+}
+
+function normalizeLookupRange(lookup_range) {
+  if (!Array.isArray(lookup_range)) {
+    return null
+  }
+  
+  // If it's a 1D array, it's already a column
+  if (!Array.isArray(lookup_range[0])) {
+    return lookup_range
+  }
+  
+  // If it's a 2D array, check if it's a single row or single column
+  const rows = lookup_range.length;
+  const cols = lookup_range[0].length;
+  
+  if (rows === 1) {
+    // Single row - extract as array
+    return lookup_range[0]
+  } else if (cols === 1) {
+    // Single column - extract first element of each row
+    return lookup_range.map(row => row[0])
+  } else {
+    // Multiple rows and columns - not allowed
+    return null
+  }
+}
+
+function normalizeResultRange(result_range) {
+  if (!Array.isArray(result_range)) {
+    return null
+  }
+  
+  // If it's a 1D array, convert to 2D single column for consistency
+  if (!Array.isArray(result_range[0])) {
+    return result_range.map(value => [value])
+  }
+  
+  // If it's already 2D, return as is
+  return result_range
+}
 
-  console.log('XLOOKUP parameters:', { lookup_value, lookup_array, return_array, if_not_found, match_mode, search_mode });
+function performLookup(search_key, lookup_array, result_array, missing_value, match_mode, search_mode, isCol) {
   
-  console.log('XLOOKUP called with:', { lookup_value, lookup_array, return_array, if_not_found, match_mode, search_mode });
+  console.log('performLookup called with:', { search_key, lookup_array, result_array, missing_value, match_mode, search_mode, isCol });
   
-  // Handle VLOOKUP-style call: XLOOKUP("a", F7:G9, 2, "false")
-  if (typeof return_array === 'number' && Array.isArray(lookup_array) && Array.isArray(lookup_array[0])) {
-    console.log('Detected VLOOKUP-style call');
-    const table_array = lookup_array;
-    const col_index_num = return_array;
-    const range_lookup = !(if_not_found === "false" || if_not_found === false || if_not_found === 0);
+  let foundIndex = -1;
+  const isSingleResultRow = result_array.length === 1;
+  
+  // Handle different match modes
+  switch (match_mode) {
+    case 0: // Exact match
+      foundIndex = findExactMatch(search_key, lookup_array, search_mode);
+      break
+    case 1: // Exact match or next larger
+      foundIndex = findExactOrNextLarger(search_key, lookup_array, search_mode);
+      break
+    case -1: // Exact match or next smaller
+      foundIndex = findExactOrNextSmaller(search_key, lookup_array, search_mode);
+      break
+    case 2: // Wildcard match
+      foundIndex = findWildcardMatch(search_key, lookup_array, search_mode);
+      break
+  }
+  
+  if (foundIndex === -1) {
+        // Return missing_value (single value): "yoo"
+        return missing_value
+  }
+  
+  // Return the result
+  if (isSingleResultRow) {
+    // Single result row - return the entire row regardless of where match was found
+    const resultRow = result_array[0];
+    if (isCol) {
+      return resultRow.map(val => [val])
+    } else {
+      return resultRow
+    }
+  } else {
+    // Multiple result rows
+    if (isCol) {
+      // Return the foundIndex column from all rows: ["e", "r"]
+      const columnValues = result_array.map(row => row[foundIndex]);
+      return columnValues
+    } else {
+      // Return the entire matched row: ["e", 3, "s", "hj"]
+      return result_array[foundIndex]
+    }
+  }
+}
+
+function findExactMatch(search_key, lookup_array, search_mode) {
+  const processedSearchKey = typeof search_key === 'string' ? search_key.toLowerCase().trim() : search_key;
+  
+  if (Math.abs(search_mode) === 2) {
+    // Binary search
+    return binarySearchExact(processedSearchKey, lookup_array, search_mode > 0)
+  } else {
+    // Linear search
+    const indices = getSearchIndices(lookup_array.length, search_mode);
     
-    // Validate column index
-    if (col_index_num < 1 || col_index_num > table_array[0].length) {
-      return ERROR_REF
+    for (const i of indices) {
+      const value = lookup_array[i];
+      const processedValue = typeof value === 'string' ? value.toLowerCase().trim() : value;
+      
+      if (processedValue === processedSearchKey) {
+        console.log(`Exact match found at index ${i}:`, value);
+        return i
+      }
     }
+  }
+  
+  return -1
+}
+
+function findExactOrNextLarger(search_key, lookup_array, search_mode) {
+  const isNumber = typeof search_key === 'number';
+  const processedSearchKey = typeof search_key === 'string' ? search_key.toLowerCase().trim() : search_key;
+  
+  if (Math.abs(search_mode) === 2) {
+    // Binary search for exact or next larger
+    return binarySearchNextLarger(processedSearchKey, lookup_array, search_mode > 0)
+  }
+  
+  const indices = getSearchIndices(lookup_array.length, search_mode);
+  let bestIndex = -1;
+  
+  for (const i of indices) {
+    const value = lookup_array[i];
+    const processedValue = typeof value === 'string' ? value.toLowerCase().trim() : value;
     
-    // Extract lookup and return columns
-    const lookup_col = table_array.map(row => row[0]);
-    const return_col = table_array.map(row => row[col_index_num - 1]);
+    // Exact match
+    if (processedValue === processedSearchKey) {
+      return i
+    }
     
-    return performLookup(lookup_value, lookup_col, return_col, ERROR_NA, range_lookup ? -1 : 0)
+    // Next larger value
+    if (isNumber && typeof value === 'number' && value > search_key) {
+      if (bestIndex === -1 || value < lookup_array[bestIndex]) {
+        bestIndex = i;
+      }
+    } else if (!isNumber && typeof value === 'string' && processedValue > processedSearchKey) {
+      if (bestIndex === -1 || processedValue < (typeof lookup_array[bestIndex] === 'string' ? lookup_array[bestIndex].toLowerCase().trim() : lookup_array[bestIndex])) {
+        bestIndex = i;
+      }
+    }
   }
   
-  // Standard XLOOKUP call: XLOOKUP("a", F7:F9, G7:G9, "hahaha")
-  console.log('Detected standard XLOOKUP call');
+  return bestIndex
+}
+
+function findExactOrNextSmaller(search_key, lookup_array, search_mode) {
+  const isNumber = typeof search_key === 'number';
+  const processedSearchKey = typeof search_key === 'string' ? search_key.toLowerCase().trim() : search_key;
   
-  if (!lookup_array || !return_array) {
-    console.log('Missing lookup_array or return_array');
-    return ERROR_NA
+  if (Math.abs(search_mode) === 2) {
+    // Binary search for exact or next smaller
+    return binarySearchNextSmaller(processedSearchKey, lookup_array, search_mode > 0)
   }
   
-  // Handle case where arrays might be 2D (from Excel ranges)
-  let lookup_col = lookup_array;
-  let return_col = return_array;
+  const indices = getSearchIndices(lookup_array.length, search_mode);
+  let bestIndex = -1;
   
-  // If lookup_array is 2D, extract first column
-  if (Array.isArray(lookup_array) && Array.isArray(lookup_array[0])) {
-    lookup_col = lookup_array.map(row => row[0]);
-    console.log('Extracted lookup column from 2D array:', lookup_col);
+  for (const i of indices) {
+    const value = lookup_array[i];
+    const processedValue = typeof value === 'string' ? value.toLowerCase().trim() : value;
+    
+    // Exact match
+    if (processedValue === processedSearchKey) {
+      return i
+    }
+    
+    // Next smaller value
+    if (isNumber && typeof value === 'number' && value < search_key) {
+      if (bestIndex === -1 || value > lookup_array[bestIndex]) {
+        bestIndex = i;
+      }
+    } else if (!isNumber && typeof value === 'string' && processedValue < processedSearchKey) {
+      if (bestIndex === -1 || processedValue > (typeof lookup_array[bestIndex] === 'string' ? lookup_array[bestIndex].toLowerCase().trim() : lookup_array[bestIndex])) {
+        bestIndex = i;
+      }
+    }
   }
   
-  // If return_array is 2D, extract first column
-  if (Array.isArray(return_array) && Array.isArray(return_array[0])) {
-    return_col = return_array.map(row => row[0]);
-    console.log('Extracted return column from 2D array:', return_col);
+  return bestIndex
+}
+
+function findWildcardMatch(search_key, lookup_array, search_mode) {
+  if (typeof search_key !== 'string') {
+    return -1 // Wildcard only works with strings
   }
   
-  if (lookup_col.length !== return_col.length) {
-    console.log('Array length mismatch:', lookup_col.length, 'vs', return_col.length);
-    return ERROR_NA
-  }
+  // Convert wildcard pattern to regex
+  const pattern = search_key
+    .toLowerCase()
+    .replace(/\*/g, '.*')  // * matches any sequence of characters
+    .replace(/\?/g, '.')   // ? matches any single character
+    .replace(/[.*+?^${}()|[\]\\]/g, '\\$&') // Escape other regex chars
+    .replace(/\\\.\*/g, '.*')  // Restore our wildcards
+    .replace(/\\\./g, '.');
+  
+  const regex = new RegExp(`^${pattern}$`, 'i');
   
-  // Default parameters
-  if_not_found = if_not_found !== undefined ? if_not_found : ERROR_NA;
-  match_mode = match_mode || 0;  // 0 = exact match, -1 = exact or next smallest
-  search_mode = search_mode || 1;  // 1 = first to last, -1 = last to first
+  const indices = getSearchIndices(lookup_array.length, search_mode);
   
-  return performLookup(lookup_value, lookup_col, return_col, if_not_found, match_mode, search_mode)
+  for (const i of indices) {
+    const value = lookup_array[i];
+    if (typeof value === 'string' && regex.test(value)) {
+      console.log(`Wildcard match found at index ${i}:`, value);
+      return i
+    }
+  }
+  
+  return -1
 }
 
+function getSearchIndices(length, search_mode) {
+  if (search_mode === -1) {
+    // Last to first
+    return Array.from({ length }, (_, i) => length - 1 - i)
+  } else {
+    // First to last (default)
+    return Array.from({ length }, (_, i) => i)
+  }
+}
 
-function performLookup(lookup_value, lookup_array, return_array, if_not_found, match_mode, search_mode) {
-  const isNumberLookup = typeof lookup_value === 'number';
-  const lookupValue = typeof lookup_value === 'string' ? lookup_value.toLowerCase().trim() : lookup_value;
-  let bestMatchIndex = -1;
+function binarySearchExact(search_key, lookup_array, ascending) {
+  let left = 0;
+  let right = lookup_array.length - 1;
   
-  // Debug: Log what we're looking for and what we have
-  console.log('XLOOKUP Debug:', {
-    looking_for: lookup_value,
-    processed_lookup: lookupValue,
-    lookup_array: lookup_array,
-    return_array: return_array,
-    match_mode: match_mode
-  });
+  while (left <= right) {
+    const mid = Math.floor((left + right) / 2);
+    const midValue = lookup_array[mid];
+    const processedMidValue = typeof midValue === 'string' ? midValue.toLowerCase().trim() : midValue;
+    
+    if (processedMidValue === search_key) {
+      return mid
+    }
+    
+    const comparison = ascending ? 
+      (processedMidValue < search_key) : 
+      (processedMidValue > search_key);
+    
+    if (comparison) {
+      left = mid + 1;
+    } else {
+      right = mid - 1;
+    }
+  }
   
-  // Determine search direction
-  const startIndex = search_mode === -1 ? lookup_array.length - 1 : 0;
-  const endIndex = search_mode === -1 ? -1 : lookup_array.length;
-  const step = search_mode === -1 ? -1 : 1;
+  return -1
+}
+
+function binarySearchNextLarger(search_key, lookup_array, ascending) {
+  let left = 0;
+  let right = lookup_array.length - 1;
+  let result = -1;
   
-  for (let i = startIndex; i !== endIndex; i += step) {
-    const rawValue = lookup_array[i];
-    const arrayValue = typeof rawValue === 'string' ? rawValue.toLowerCase().trim() : rawValue;
+  while (left <= right) {
+    const mid = Math.floor((left + right) / 2);
+    const midValue = lookup_array[mid];
+    const processedMidValue = typeof midValue === 'string' ? midValue.toLowerCase().trim() : midValue;
     
-    console.log(`Comparing: "${lookupValue}" === "${arrayValue}" (types: ${typeof lookupValue} vs ${typeof arrayValue})`);
+    if (processedMidValue === search_key) {
+      return mid // Exact match
+    }
     
-    // Exact match
-    if (arrayValue === lookupValue) {
-      console.log(`Found match at index ${i}: ${return_array[i]}`);
-      return return_array[i]
+    if (ascending) {
+      if (processedMidValue > search_key) {
+        result = mid;
+        right = mid - 1;
+      } else {
+        left = mid + 1;
+      }
+    } else {
+      if (processedMidValue < search_key) {
+        result = mid;
+        left = mid + 1;
+      } else {
+        right = mid - 1;
+      }
     }
+  }
+  
+  return result
+}
+
+function binarySearchNextSmaller(search_key, lookup_array, ascending) {
+  let left = 0;
+  let right = lookup_array.length - 1;
+  let result = -1;
+  
+  while (left <= right) {
+    const mid = Math.floor((left + right) / 2);
+    const midValue = lookup_array[mid];
+    const processedMidValue = typeof midValue === 'string' ? midValue.toLowerCase().trim() : midValue;
     
-    // Approximate match (match_mode = -1, similar to VLOOKUP range_lookup = true)
-    if (match_mode === -1) {
-      if ((isNumberLookup && typeof arrayValue === 'number' && arrayValue <= lookup_value) ||
-          (!isNumberLookup && typeof arrayValue === 'string' && arrayValue.localeCompare(lookupValue) <= 0)) {
-        bestMatchIndex = i;
-        console.log(`Approximate match candidate at index ${i}: ${arrayValue}`);
+    if (processedMidValue === search_key) {
+      return mid // Exact match
+    }
+    
+    if (ascending) {
+      if (processedMidValue < search_key) {
+        result = mid;
+        left = mid + 1;
+      } else {
+        right = mid - 1;
+      }
+    } else {
+      if (processedMidValue > search_key) {
+        result = mid;
+        right = mid - 1;
+      } else {
+        left = mid + 1;
       }
     }
   }
   
-  console.log(`No exact match found. Returning: ${bestMatchIndex !== -1 ? return_array[bestMatchIndex] : if_not_found}`);
-  return bestMatchIndex !== -1 ? return_array[bestMatchIndex] : if_not_found
+  return result
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fileverse-dev/formulajs",
-  "version": "4.4.20-mod-1",
+  "version": "4.4.20-mod-3",
   "description": "JavaScript implementation of most Microsoft Excel formula functions",
   "author": "Formulajs",
   "publishConfig": {

package/types/cjs/index.d.cts

@@ -4522,7 +4522,7 @@ export function WORKDAY_INTL(start_date: any, days: any, weekend: any, holidays:
  * @returns
  */
 export function XIRR(values: any, dates: any, guess: any): any;
-export function XLOOKUP(lookup_value: any, lookup_array: any, return_array: any, if_not_found: any, match_mode: any, search_mode: any): any;
+export function XLOOKUP(search_key: any, lookup_range: any, result_range: any, missing_value: any, isCol: any, match_mode: any, search_mode: any): any;
 /**
  * Returns the net present value for a schedule of cash flows that is not necessarily periodic.
  *

package/types/esm/index.d.mts

@@ -4522,7 +4522,7 @@ export function WORKDAY_INTL(start_date: any, days: any, weekend: any, holidays:
  * @returns
  */
 export function XIRR(values: any, dates: any, guess: any): any;
-export function XLOOKUP(lookup_value: any, lookup_array: any, return_array: any, if_not_found: any, match_mode: any, search_mode: any): any;
+export function XLOOKUP(search_key: any, lookup_range: any, result_range: any, missing_value: any, isCol: any, match_mode: any, search_mode: any): any;
 /**
  * Returns the net present value for a schedule of cash flows that is not necessarily periodic.
  *