array: defaultComparator, noFail option for sort

src/array.ts

@@ -1,8 +1,9 @@
-import { type AnyCell, type MapCell, ValueCell } from "./cell";
+import type { AnyCell, MapCell, ValueCell } from "./cell";
 import { collector, reuseOrCreate } from "./gc";
 import type { SheetProxy } from "./proxy";
 
 export type CellArray<T> = AnyCell<AnyCell<T>[]>;
+export type ValueCellArray<T> = ValueCell<ValueCell<T>[]>;
 
 /**
  * mapArray implements .map() for a cellified array.
@@ -53,20 +54,45 @@ export const mapArray = <T, U>(
     name
   );
 
+/**
+ * Compares two values and returns a number indicating their order.
+ *
+ * This function is designed to be used as a comparator in sorting functions.
+ * It returns:
+ * - `1` if `a` is greater than `b`
+ * - `-1` if `a` is less than `b`
+ * - `0` if `a` is equal to `b`
+ *
+ * @param {*} a - The first value to compare.
+ * @param {*} b - The second value to compare.
+ * @returns {number} - Order.
+ *
+ * @example
+ * const array = [3, 1, 4, 1, 5, 9, 2, 6, 5, 3, 5];
+ * array.sort(defaultComparator);
+ */
+export const defaultComparator = <T>(a: T, b: T): number =>
+  a > b ? 1 : a < b ? -1 : 0;
+
 /**
  * implementation of sort for a cellified array.
  * @description this implementation relies on pointers but reuses the original cells.
  * @param proxy
  * @param arr
  * @param compare comparison function
+ * @param noFail should be true when the following conditions are met:
+ * 1. compare must be defined
+ * 2. cells must be an array (possibly empty)
+ * 3. compare should never fail
  */
 export const sort = <T>(
   proxy: SheetProxy,
   arr: CellArray<T>,
-  compare: (a: T, b: T) => number = (a, b) => (a > b ? 1 : a < b ? -1 : 0)
+  compare: (a: T, b: T) => number = defaultComparator,
+  noFail = false
 ): CellArray<T> => {
   const coll = collector<CellArray<T>>(proxy);
-  return proxy.map(
+  return proxy.mapNoPrevious(
     [arr],
     (cells) =>
       coll(
@@ -77,10 +103,12 @@ export const sort = <T>(
               .map((_, index) => index)
               .sort((indexA, indexB) => compare(_cells[indexA], _cells[indexB]))
               .map((index) => cells[index]),
-          "_sort"
+          "_sort",
+          noFail
         )
       ),
-    "sort"
+    "sort",
+    noFail
   );
 };
 

src/index.ts

@@ -28,6 +28,7 @@ export type { ComputeFn, Unsubscriber } from "./types";
 // Utilities
 
 export {
+  defaultComparator,
   filter,
   filterPredicateCell,
   find,
@@ -38,7 +39,8 @@ export {
   mapArrayCell,
   reduce,
   sort,
-  type CellArray
+  type CellArray,
+  type ValueCellArray
 } from "./array";
 export {
   cellify,