@fileverse-dev/formulajs 4.4.18 → 4.4.20

package/lib/cjs/index.cjs

@@ -1270,75 +1270,79 @@ function ROWS(array) {
  * @param {*} by_col Optional. A logical value indicating the desired sort direction; FALSE to sort by row (default), TRUE to sort by column
  * @returns
  */
-function SORT(array, sort_index = 1, is_ascending, by_col = false) {
-  if (!array || !Array.isArray(array)) return na;
-  if (array.length === 0) return 0;
+function SORT(inputArray, sortIndex = 1, isAscending, sortByColumn = false) {
+  if (!inputArray || !Array.isArray(inputArray)) return na;
+  if (inputArray.length === 0) return 0;
 
-  let idx = parseNumber(sort_index);
-  if (!idx || idx < 1) return value;
-  idx = idx - 1;
+  let sortColumnIndex = parseNumber(sortIndex);
+  if (!sortColumnIndex || sortColumnIndex < 1) return value;
+  sortColumnIndex = sortColumnIndex - 1;
 
-  const sortOrderNumber = is_ascending  === 'FALSE' ?  -1 : 1;
-  let order = parseNumber(sortOrderNumber);
-  if (order !== 1 && order !== -1) return value;
+  const sortDirection = isAscending?.toLowerCase() === 'false' ? -1 : 1;
+  const parsedSortDirection = parseNumber(sortDirection);
+  if (parsedSortDirection !== 1 && parsedSortDirection !== -1) return value;
 
-  const byCol = parseBool(by_col);
-  if (typeof byCol !== "boolean") return name;
 
-  // Rectangularize then orient
-  const matrix = fillMatrix(array);
-  const working = byCol ? transpose(matrix) : matrix;
+  const isSortByColumn = parseBool(sortByColumn);
+  if (typeof isSortByColumn !== "boolean") return name;
+
+
+  const normalizedMatrix = fillMatrix(inputArray);
+  const orientedMatrix = isSortByColumn
+    ? transpose(normalizedMatrix)
+    : normalizedMatrix;
 
-  if (!working.length || !working[0] || idx >= working[0].length) {
-    return value; // out of bounds
+  if (!orientedMatrix.length || !orientedMatrix[0] || sortColumnIndex >= orientedMatrix[0].length) {
+    return value;
   }
 
-  // Helpers (aiming for spreadsheet-ish behavior)
-  const isBlank = (v) => v === "" || v === null || v === undefined;
+  const isBlank = (value) => value === "" || value === null || value === undefined;
 
-  const cmp = (a, b) => {
-    // Blanks last (ascending); we'll multiply by order later for descending.
+  // Comparator for sorting values
+  const compareValues = (a, b) => {
     const aBlank = isBlank(a);
     const bBlank = isBlank(b);
     if (aBlank && bBlank) return 0;
     if (aBlank) return 1;
     if (bBlank) return -1;
 
-    // If both parse as finite numbers, compare numerically
-    const na = parseNumber(a);
-    const nb = parseNumber(b);
-    const aNum = Number.isFinite(na);
-    const bNum = Number.isFinite(nb);
+    // Numeric comparison if possible
+    const parsedA = parseNumber(a);
+    const parsedB = parseNumber(b);
+    const isANumber = Number.isFinite(parsedA);
+    const isBNumber = Number.isFinite(parsedB);
 
-    if (aNum && bNum) {
-      if (na < nb) return -1;
-      if (na > nb) return 1;
+    if (isANumber && isBNumber) {
+      if (parsedA < parsedB) return -1;
+      if (parsedA > parsedB) return 1;
       return 0;
     }
 
-    // Fallback: case-insensitive string compare
-    const sa = (parseString(a) ?? "").toString().toLowerCase();
-    const sb = (parseString(b) ?? "").toString().toLowerCase();
-    if (sa < sb) return -1;
-    if (sa > sb) return 1;
+    // Fallback: case-insensitive string comparison
+    const stringA = (parseString(a) ?? "").toString().toLowerCase();
+    const stringB = (parseString(b) ?? "").toString().toLowerCase();
+    if (stringA < stringB) return -1;
+    if (stringA > stringB) return 1;
     return 0;
   };
 
-  // Stable sort: decorate with original index
-  const decorated = working.map((row, i) => ({ row, i }));
+  const rowsWithOriginalIndex = orientedMatrix.map((row, rowIndex) => ({ row, rowIndex }));
 
-  decorated.sort((A, B) => {
-    const base = cmp(A.row[idx], B.row[idx]);
-    if (base !== 0) return base * order;
-    // stable tiebreaker: original order
-    return A.i - B.i;
+  rowsWithOriginalIndex.sort((rowA, rowB) => {
+    const baseComparison = compareValues(rowA.row[sortColumnIndex], rowB.row[sortColumnIndex]);
+    if (baseComparison !== 0) return baseComparison * parsedSortDirection;
+    return rowA.rowIndex - rowB.rowIndex;
   });
 
-  const sorted = decorated.map((d) => d.row);
-  return byCol ? transpose(sorted) : sorted;
+  // Extract sorted rows
+  const sortedMatrix = rowsWithOriginalIndex.map((item) => item.row);
+
+  // Return rows or columns depending on orientation
+  return isSortByColumn ? transpose(sortedMatrix) : sortedMatrix;
 }
 
 
+
 /**
  * Returns the transpose of an array.
  *

package/lib/esm/index.mjs

@@ -1268,75 +1268,79 @@ function ROWS(array) {
  * @param {*} by_col Optional. A logical value indicating the desired sort direction; FALSE to sort by row (default), TRUE to sort by column
  * @returns
  */
-function SORT(array, sort_index = 1, is_ascending, by_col = false) {
-  if (!array || !Array.isArray(array)) return na;
-  if (array.length === 0) return 0;
+function SORT(inputArray, sortIndex = 1, isAscending, sortByColumn = false) {
+  if (!inputArray || !Array.isArray(inputArray)) return na;
+  if (inputArray.length === 0) return 0;
 
-  let idx = parseNumber(sort_index);
-  if (!idx || idx < 1) return value;
-  idx = idx - 1;
+  let sortColumnIndex = parseNumber(sortIndex);
+  if (!sortColumnIndex || sortColumnIndex < 1) return value;
+  sortColumnIndex = sortColumnIndex - 1;
 
-  const sortOrderNumber = is_ascending  === 'FALSE' ?  -1 : 1;
-  let order = parseNumber(sortOrderNumber);
-  if (order !== 1 && order !== -1) return value;
+  const sortDirection = isAscending?.toLowerCase() === 'false' ? -1 : 1;
+  const parsedSortDirection = parseNumber(sortDirection);
+  if (parsedSortDirection !== 1 && parsedSortDirection !== -1) return value;
 
-  const byCol = parseBool(by_col);
-  if (typeof byCol !== "boolean") return name;
 
-  // Rectangularize then orient
-  const matrix = fillMatrix(array);
-  const working = byCol ? transpose(matrix) : matrix;
+  const isSortByColumn = parseBool(sortByColumn);
+  if (typeof isSortByColumn !== "boolean") return name;
+
+
+  const normalizedMatrix = fillMatrix(inputArray);
+  const orientedMatrix = isSortByColumn
+    ? transpose(normalizedMatrix)
+    : normalizedMatrix;
 
-  if (!working.length || !working[0] || idx >= working[0].length) {
-    return value; // out of bounds
+  if (!orientedMatrix.length || !orientedMatrix[0] || sortColumnIndex >= orientedMatrix[0].length) {
+    return value;
   }
 
-  // Helpers (aiming for spreadsheet-ish behavior)
-  const isBlank = (v) => v === "" || v === null || v === undefined;
+  const isBlank = (value) => value === "" || value === null || value === undefined;
 
-  const cmp = (a, b) => {
-    // Blanks last (ascending); we'll multiply by order later for descending.
+  // Comparator for sorting values
+  const compareValues = (a, b) => {
     const aBlank = isBlank(a);
     const bBlank = isBlank(b);
     if (aBlank && bBlank) return 0;
     if (aBlank) return 1;
     if (bBlank) return -1;
 
-    // If both parse as finite numbers, compare numerically
-    const na = parseNumber(a);
-    const nb = parseNumber(b);
-    const aNum = Number.isFinite(na);
-    const bNum = Number.isFinite(nb);
+    // Numeric comparison if possible
+    const parsedA = parseNumber(a);
+    const parsedB = parseNumber(b);
+    const isANumber = Number.isFinite(parsedA);
+    const isBNumber = Number.isFinite(parsedB);
 
-    if (aNum && bNum) {
-      if (na < nb) return -1;
-      if (na > nb) return 1;
+    if (isANumber && isBNumber) {
+      if (parsedA < parsedB) return -1;
+      if (parsedA > parsedB) return 1;
       return 0;
     }
 
-    // Fallback: case-insensitive string compare
-    const sa = (parseString(a) ?? "").toString().toLowerCase();
-    const sb = (parseString(b) ?? "").toString().toLowerCase();
-    if (sa < sb) return -1;
-    if (sa > sb) return 1;
+    // Fallback: case-insensitive string comparison
+    const stringA = (parseString(a) ?? "").toString().toLowerCase();
+    const stringB = (parseString(b) ?? "").toString().toLowerCase();
+    if (stringA < stringB) return -1;
+    if (stringA > stringB) return 1;
     return 0;
   };
 
-  // Stable sort: decorate with original index
-  const decorated = working.map((row, i) => ({ row, i }));
+  const rowsWithOriginalIndex = orientedMatrix.map((row, rowIndex) => ({ row, rowIndex }));
 
-  decorated.sort((A, B) => {
-    const base = cmp(A.row[idx], B.row[idx]);
-    if (base !== 0) return base * order;
-    // stable tiebreaker: original order
-    return A.i - B.i;
+  rowsWithOriginalIndex.sort((rowA, rowB) => {
+    const baseComparison = compareValues(rowA.row[sortColumnIndex], rowB.row[sortColumnIndex]);
+    if (baseComparison !== 0) return baseComparison * parsedSortDirection;
+    return rowA.rowIndex - rowB.rowIndex;
   });
 
-  const sorted = decorated.map((d) => d.row);
-  return byCol ? transpose(sorted) : sorted;
+  // Extract sorted rows
+  const sortedMatrix = rowsWithOriginalIndex.map((item) => item.row);
+
+  // Return rows or columns depending on orientation
+  return isSortByColumn ? transpose(sortedMatrix) : sortedMatrix;
 }
 
 
+
 /**
  * Returns the transpose of an array.
  *

package/package.json

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

package/types/cjs/index.d.cts

@@ -3806,7 +3806,7 @@ export function SMARTCONTRACT(...args: any[]): Promise<any>;
  * @param {*} by_col Optional. A logical value indicating the desired sort direction; FALSE to sort by row (default), TRUE to sort by column
  * @returns
  */
-export function SORT(array: any, sort_index: any, is_ascending: any, by_col?: any): any;
+export function SORT(inputArray: any, sortIndex: number, isAscending: any, sortByColumn?: boolean): any;
 /**
  * Returns a positive square root.
  *

package/types/esm/index.d.mts

@@ -3806,7 +3806,7 @@ export function SMARTCONTRACT(...args: any[]): Promise<any>;
  * @param {*} by_col Optional. A logical value indicating the desired sort direction; FALSE to sort by row (default), TRUE to sort by column
  * @returns
  */
-export function SORT(array: any, sort_index: any, is_ascending: any, by_col?: any): any;
+export function SORT(inputArray: any, sortIndex: number, isAscending: any, sortByColumn?: boolean): any;
 /**
  * Returns a positive square root.
  *