fix(_internal/compareValues): place null and undefined values last when sorting

src/_internal/compareValues.ts

@@ -1,9 +1,31 @@
+function getNullishPriority(value: any): number {
+  if (value === null) {
+    return 1;
+  }
+  if (value === undefined) {
+    return 2;
+  }
+  return 0;
+}
+
 export function compareValues(a: any, b: any, order: 'asc' | 'desc'): 0 | -1 | 1 {
+  const isAsc = order === 'asc';
+  const aPriority = getNullishPriority(a);
+  const bPriority = getNullishPriority(b);
+
+  if (aPriority !== bPriority) {
+    return isAsc ? (aPriority > bPriority ? 1 : -1) : aPriority > bPriority ? -1 : 1;
+  }
+
+  if (aPriority !== 0) {
+    return 0;
+  }
+
   if (a < b) {
-    return order === 'asc' ? -1 : 1;
+    return isAsc ? -1 : 1;
   }
   if (a > b) {
-    return order === 'asc' ? 1 : -1;
+    return isAsc ? 1 : -1;
   }
   return 0;
 }

src/array/orderBy.spec.ts

@@ -60,4 +60,40 @@ describe('orderBy', () => {
       { user: 'fred', age: 48 },
     ]);
   });
+
+  it('should place null and undefined values at the end when ascending', () => {
+    const items = [
+      { name: 'a', value: 3 },
+      { name: 'b', value: null },
+      { name: 'c', value: 1 },
+      { name: 'd', value: undefined },
+      { name: 'e', value: 2 },
+    ];
+
+    expect(orderBy(items, ['value'], ['asc'])).toEqual([
+      { name: 'c', value: 1 },
+      { name: 'e', value: 2 },
+      { name: 'a', value: 3 },
+      { name: 'b', value: null },
+      { name: 'd', value: undefined },
+    ]);
+  });
+
+  it('should place null and undefined values at the beginning when descending', () => {
+    const items = [
+      { name: 'a', value: 3 },
+      { name: 'b', value: null },
+      { name: 'c', value: 1 },
+      { name: 'd', value: undefined },
+      { name: 'e', value: 2 },
+    ];
+
+    expect(orderBy(items, ['value'], ['desc'])).toEqual([
+      { name: 'd', value: undefined },
+      { name: 'b', value: null },
+      { name: 'a', value: 3 },
+      { name: 'e', value: 2 },
+      { name: 'c', value: 1 },
+    ]);
+  });
 });

src/array/sortBy.spec.ts

@@ -53,4 +53,40 @@ describe('sortBy', () => {
       { user: 'foo', age: 24 },
     ]);
   });
+
+  it('should place null and undefined values at the end', () => {
+    const items = [
+      { user: 'foo', age: 3 },
+      { user: 'bar', age: null },
+      { user: 'baz', age: 1 },
+      { user: 'qux', age: undefined },
+      { user: 'quux', age: 2 },
+    ];
+
+    expect(sortBy(items, ['age'])).toEqual([
+      { user: 'baz', age: 1 },
+      { user: 'quux', age: 2 },
+      { user: 'foo', age: 3 },
+      { user: 'bar', age: null },
+      { user: 'qux', age: undefined },
+    ]);
+  });
+
+  it('should maintain stable order among multiple null and undefined values', () => {
+    const items = [
+      { user: 'a', age: null },
+      { user: 'b', age: 1 },
+      { user: 'c', age: undefined },
+      { user: 'd', age: null },
+      { user: 'e', age: undefined },
+    ];
+
+    expect(sortBy(items, ['age'])).toEqual([
+      { user: 'b', age: 1 },
+      { user: 'a', age: null },
+      { user: 'd', age: null },
+      { user: 'c', age: undefined },
+      { user: 'e', age: undefined },
+    ]);
+  });
 });