Skip to content

Commit

Permalink
Introduce Comparator and PairSorting (#1937)
Browse files Browse the repository at this point in the history
Co-authored-by: Julien Deniau <julien@deniau.me>
  • Loading branch information
giancosta86 and jdeniau authored Mar 10, 2023
1 parent 376944d commit f0f3932
Show file tree
Hide file tree
Showing 5 changed files with 117 additions and 12 deletions.
66 changes: 66 additions & 0 deletions __tests__/Comparator.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,66 @@
import { List, OrderedSet, Seq, Comparator, PairSorting } from 'immutable';

const sourceNumbers: readonly number[] = [3, 4, 5, 6, 7, 9, 10, 12, 90, 92, 95];

const expectedSortedNumbers: readonly number[] = [
7, 95, 90, 92, 3, 5, 9, 4, 6, 10, 12,
];

const testComparator: Comparator<number> = (left, right) => {
//The number 7 always goes first...
if (left == 7) {
return PairSorting.LeftThenRight;
} else if (right == 7) {
return PairSorting.RightThenLeft;
}

//...followed by numbers >= 90, then by all the others.
if (left >= 90 && right < 90) {
return PairSorting.LeftThenRight;
} else if (left < 90 && right >= 90) {
return PairSorting.RightThenLeft;
}

//Within each group, even numbers go first...
if (left % 2 && !(right % 2)) {
return PairSorting.LeftThenRight;
} else if (!(left % 2) && right % 2) {
return PairSorting.RightThenLeft;
}

//...and, finally, sort the numbers of each subgroup in ascending order.
return left - right;
};

describe.each([
['List', List],
['OrderedSet', OrderedSet],
['Seq.Indexed', Seq.Indexed],
])('Comparator applied to %s', (_collectionName, testCollectionConstructor) => {
const sourceCollection = testCollectionConstructor(sourceNumbers);

const expectedSortedCollection = testCollectionConstructor(
expectedSortedNumbers
);

describe('when sorting', () => {
it('should support the enum as well as numeric return values', () => {
const actualCollection = sourceCollection.sort(testComparator);
expect(actualCollection).toEqual(expectedSortedCollection);
});
});

describe('when retrieving the max value', () => {
it('should support the enum as well as numeric return values', () => {
const actualMax = sourceCollection.max(testComparator);
expect(actualMax).toBe(12);
});
});

describe('when retrieving the min value', () => {
it('should support the enum as well as numeric return values', () => {
const actualMin = sourceCollection.min(testComparator);
expect(actualMin).toBe(7);
});
});
});
3 changes: 3 additions & 0 deletions src/Immutable.js
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ import { List } from './List';
import { Map } from './Map';
import { Stack } from './Stack';
import { OrderedSet } from './OrderedSet';
import { PairSorting } from './PairSorting';
import { Set } from './Set';
import { Record } from './Record';
import { Range } from './Range';
Expand Down Expand Up @@ -62,6 +63,7 @@ export default {
Stack: Stack,
Set: Set,
OrderedSet: OrderedSet,
PairSorting: PairSorting,

Record: Record,
Range: Range,
Expand Down Expand Up @@ -118,6 +120,7 @@ export {
Stack,
Set,
OrderedSet,
PairSorting,
Record,
Range,
Repeat,
Expand Down
4 changes: 4 additions & 0 deletions src/PairSorting.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
export const PairSorting = {
LeftThenRight: -1,
RightThenLeft: +1,
};
34 changes: 28 additions & 6 deletions type-definitions/immutable.d.ts
Original file line number Diff line number Diff line change
Expand Up @@ -125,6 +125,27 @@ declare namespace Immutable {
: // other case : should be kept as is
T;

/**
* Describes which item in a pair should be placed first when sorting
*
* @ignore
*/
export enum PairSorting {
LeftThenRight = -1,
RightThenLeft = +1,
}

/**
* Function comparing two items of the same type. It can return:
*
* * a PairSorting value, to indicate whether the left-hand item or the right-hand item should be placed before the other
*
* * the traditional numeric return value - especially -1, 0, or 1
*
* @ignore
*/
export type Comparator<T> = (left: T, right: T) => PairSorting | number;

/**
* Lists are ordered indexed dense collections, much like a JavaScript
* Array.
Expand Down Expand Up @@ -4526,6 +4547,7 @@ declare namespace Immutable {
* * Returns `0` if the elements should not be swapped.
* * Returns `-1` (or any negative number) if `valueA` comes before `valueB`
* * Returns `1` (or any positive number) if `valueA` comes after `valueB`
* * Alternatively, can return a value of the `PairSorting` enum type
* * Is pure, i.e. it must always return the same value for the same pair
* of values.
*
Expand All @@ -4548,7 +4570,7 @@ declare namespace Immutable {
*
* Note: This is always an eager operation.
*/
sort(comparator?: (valueA: V, valueB: V) => number): this;
sort(comparator?: Comparator<V>): this;

/**
* Like `sort`, but also accepts a `comparatorValueMapper` which allows for
Expand All @@ -4573,7 +4595,7 @@ declare namespace Immutable {
*/
sortBy<C>(
comparatorValueMapper: (value: V, key: K, iter: this) => C,
comparator?: (valueA: C, valueB: C) => number
comparator?: Comparator<C>
): this;

/**
Expand Down Expand Up @@ -4972,7 +4994,7 @@ declare namespace Immutable {
* If `comparator` returns 0 and either value is NaN, undefined, or null,
* that value will be returned.
*/
max(comparator?: (valueA: V, valueB: V) => number): V | undefined;
max(comparator?: Comparator<V>): V | undefined;

/**
* Like `max`, but also accepts a `comparatorValueMapper` which allows for
Expand All @@ -4991,7 +5013,7 @@ declare namespace Immutable {
*/
maxBy<C>(
comparatorValueMapper: (value: V, key: K, iter: this) => C,
comparator?: (valueA: C, valueB: C) => number
comparator?: Comparator<C>
): V | undefined;

/**
Expand All @@ -5009,7 +5031,7 @@ declare namespace Immutable {
* If `comparator` returns 0 and either value is NaN, undefined, or null,
* that value will be returned.
*/
min(comparator?: (valueA: V, valueB: V) => number): V | undefined;
min(comparator?: Comparator<V>): V | undefined;

/**
* Like `min`, but also accepts a `comparatorValueMapper` which allows for
Expand All @@ -5028,7 +5050,7 @@ declare namespace Immutable {
*/
minBy<C>(
comparatorValueMapper: (value: V, key: K, iter: this) => C,
comparator?: (valueA: C, valueB: C) => number
comparator?: Comparator<C>
): V | undefined;

// Comparison
Expand Down
22 changes: 16 additions & 6 deletions type-definitions/immutable.js.flow
Original file line number Diff line number Diff line change
Expand Up @@ -60,6 +60,14 @@ type $IterableOf<C> = $Call<
C
>;

const PairSorting: $ReadOnly<{ LeftThenRight: number, RightThenLeft: number }> =
{
LeftThenRight: -1,
RightThenLeft: +1,
};

type Comparator<T> = (left: T, right: T) => number;

declare class _Collection<K, +V> implements ValueObject {
equals(other: mixed): boolean;
hashCode(): number;
Expand Down Expand Up @@ -129,11 +137,11 @@ declare class _Collection<K, +V> implements ValueObject {
entrySeq(): IndexedSeq<[K, V]>;

reverse(): this;
sort(comparator?: (valueA: V, valueB: V) => number): this;
sort(comparator?: Comparator<V>): this;

sortBy<C>(
comparatorValueMapper: (value: V, key: K, iter: this) => C,
comparator?: (valueA: C, valueB: C) => number
comparator?: Comparator<C>
): this;

groupBy<G>(
Expand Down Expand Up @@ -238,15 +246,15 @@ declare class _Collection<K, +V> implements ValueObject {
keyOf(searchValue: V): K | void;
lastKeyOf(searchValue: V): K | void;

max(comparator?: (valueA: V, valueB: V) => number): V;
max(comparator?: Comparator<V>): V;
maxBy<C>(
comparatorValueMapper: (value: V, key: K, iter: this) => C,
comparator?: (valueA: C, valueB: C) => number
comparator?: Comparator<C>
): V;
min(comparator?: (valueA: V, valueB: V) => number): V;
min(comparator?: Comparator<V>): V;
minBy<C>(
comparatorValueMapper: (value: V, key: K, iter: this) => C,
comparator?: (valueA: C, valueB: C) => number
comparator?: Comparator<C>
): V;

isSubset(iter: Iterable<V>): boolean;
Expand Down Expand Up @@ -2351,6 +2359,7 @@ export default {
Map,
OrderedMap,
OrderedSet,
PairSorting,
Range,
Repeat,
Record,
Expand Down Expand Up @@ -2387,6 +2396,7 @@ export default {
};

export type {
Comparator,
KeyedCollection,
IndexedCollection,
SetCollection,
Expand Down

0 comments on commit f0f3932

Please sign in to comment.