lightness/type-comparator

Useful comparator functions written on Typescript

Type Comparator

Useful comparator functions written on Typescript (But you can use it on your JS project)

Table of Contents

• Type Comparator
  • Table of Contents
  • Installation
  • Usage
    • Base comparators: asc and desc
    • Functional way
      • Function reverse(comparator)
      • Function map(mapper, comparator)
      • Function condition(conditionFn, comparatorA, comparatorB)
      • Function queue(comparators)
    • Chaining way
      • Basic usage
      • Chain .reverse()
      • Chain .map(mapper)
      • Chain .if(conditionFn)
      • Chain .then(comparator)
      • Chain .elif(conditionFn)
      • Chain .else(comparator)
      • Chain .use(comparators)
    • Something more complex?... Ok!
    • Q&A
  • Support
  • Contributing

Installation

npm i type-comparator

Usage

Base comparators: asc and desc

asc is simple comparator contains just base comparison logic.

It works well with numbers...

const array = [17, 4, -17, 42, -3, 0];

// [-17, -3, 0, 4, 17, 42]
array.slice().sort(asc); 
// [42, 17, 4, 0, -3, -17]
array.slice().sort(desc); 

And with strings...

const array = ['aaa', 'bax', 'a', 'x', 'ax', 'ab', 'ba', 'bx'];

// ["a", "aaa", "ab", "ax", "ba", "bax", "bx", "x"]
array.slice().sort(asc); 
// ["x", "bx", "bax", "ba", "ax", "ab", "aaa", "a"]
array.slice().sort(desc);

Even with dates...

const array = [new Date(2018, 0, 1), new Date(2017, 0, 1), new Date(2019, 0, 1)];

// [Date(2017, 0, 1), Date(2018, 0, 1), Date(2019, 0, 1)]
array.slice().sort(asc); 
// [Date(2019, 0, 1), Date(2018, 0, 1), Date(2017, 0, 1)]
array.slice().sort(desc);

Actually it works well with everything comparable by > and <.

NOTE Every values which are neither > nor < are equal.

As you can see below, the initial order remains. If you want to sort by value of some item property, take a look on map function.

var array1 = [{a: 1}, {a: 5}];
var array2 = [{a: 5}, {a: 1}];

array1.slice().sort(asc);  // [{a: 1}, {a: 5}]
array2.slice().sort(asc);  // [{a: 5}, {a: 1}]
array1.slice().sort(desc); // [{a: 1}, {a: 5}]
array2.slice().sort(desc); // [{a: 5}, {a: 1}]

---

Functional way

Function reverse(comparator)

Just swap comparator args.

import { asc, cmp, reverse } from 'type-comparator';

const functionalCmp = reverse(asc);
const array = [17, 4, -17, 42, -3, 0];

// [ 42, 17, 4, 0, -3, -17 ]
array.slice().sort(functionalCmp);  

Function map(mapper, comparator)

Maps each args with mapper and apply comparator.

import { asc, cmp, map } from 'type-comparator';

const mapper = x => x.a;
const comparator = map(mapper, asc);
const array = [{ a: 15 }, { a: 5 }];

// [ { a: 5 }, { a: 15 } ]
array.slice().sort(comparator);

Function condition(conditionFn, comparatorA, comparatorB)

Has following logic:

• Applies comparatorA, if both args satisfy conditionFn.
• Applies comparatorB, if both args do not satisfy conditionFn.
• Returns positive value, if only first arg satisfies conditionFn.
• Returns negative value, if only second arg satisfies conditionFn.

import { asc, cmp, condition } from 'type-comparator';

const conditionFn = x => x % 2 === 0;
const comparator = condition(conditionFn, asc, desc);
const array = [17, 4, -17, 42, -3, 0];

// [ 17, -3, -17, 0, 4, 42 ]
array.slice().sort(comparator);

Function queue(comparators)

Applies first comparator from comparators.

• If comparator returns non-zero value, returns it as result.
• If comparator returns 0, apply next comparator from comparators.
• If there is no more comparator in comparators list, returns 0.

import { asc, cmp, desc, map, queue } from 'type-comparator';

const comparator = queue([
    map(x => x.name, asc),
    map(x => x.age, desc),
]);
const array = [
    { name: 'Alex', age: 21 },
    { name: 'Jane', age: 19 },
    { name: 'Alex', age: 26 },
];

// [ 
//    { name: 'Alex', age: 26 },
//    { name: 'Alex', age: 21 },
//    { name: 'Jane', age: 19 } 
// ]
array.slice().sort(comparator);

---

Chaining way

Basic usage

cmp() - just starts chaining. .use(comparator) - applies comparator and terminates chaining.

Note: use() chain can work with any comparator function (not only produced by type-comparator)

import { asc, cmp } from 'type-comparator';

// same as just `asc` function
const comparator1 = cmp().use(asc);

// works like `asc` but just for numbers
const comparator2 = cmp().use((a, b) => a - b); 

// not a lot of sense, but it's possible
const comparator3 = cmp().use(comparator1); 

Chain .reverse()

import { asc, cmp, reverse } from 'type-comparator';

const comparator = cmp().reverse().use(asc);
const array = [17, 4, -17, 42, -3, 0];

// [ 42, 17, 4, 0, -3, -17 ]
array.slice().sort(comparator);

Chain .map(mapper)

import { asc, cmp, map } from 'type-comparator';

const mapper = x => x.a;
const comparator = cmp().map(mapper).use(asc);
const array = [{ a: 15 }, { a: 5 }];

// [ { a: 5 }, { a: 15 } ]
array.slice().sort(comparator);

Chain .if(conditionFn)

Checks conditionFn for each arg.

• Applies next .then chain, if both args satisfy conditionFn.
• Applies next .else/.elif chain, if both args do not satisfy conditionFn.
• Returns positive value, if only first arg satisfies conditionFn.
• Returns negative value, if only second arg satisfies conditionFn.

Note: After .if() chain, only .then chain is available.

import { asc, cmp } from 'type-comparator';

const conditionFn = x => x % 4 === 0;
const conditionFn2 = x => x % 2 === 0;
const chainingCmp = cmp()
    .if(conditionFn).then(asc)
    .elif(conditionFn2).then(asc)
    .else(asc);
const array = [17, 4, -17, 42, -3, 0];

// [ -17, -3, 17, 42, 0, 4 ]
array.slice().sort(chainingCmp);

Chain .then(comparator)

Applies comparator, if condition from previous .if()chain satisfies for both args.

Note: After .then() chain, only .elif() or .else() chains are available. Note: .then() chain is available only after .if() or .elif() chains.

Chain .elif(conditionFn)

Works same .if() chain.

Note: After .elif() chain, only .then() chain is available. Note: .elif() chain is available only after .then() chain.

Chain .else(comparator)

Applies comparator, if both args do not satisfy comparators from previous .if()/.elif chains.

Note: .else() chain is available only after .then() chain. Note: .else() chain finishes chaining and returns result comparator function.

Chain .use(comparators)

Works same as queue(comparators) and terminates chaining.

import { asc, cmp, desc } from 'type-comparator';

const comparator = cmp().use([
    cmp().map(x => x.name).use(asc),
    cmp().map(x => x.age).use(desc),
]);
const array = [
    { name: 'Alex', age: 21 },
    { name: 'Jane', age: 19 },
    { name: 'Alex', age: 26 },
];

// [ 
//    { name: 'Alex', age: 26 },
//    { name: 'Alex', age: 21 },
//    { name: 'Jane', age: 19 } 
// ]
array.slice().sort(comparator);    

---

Something more complex?... Ok!

import { asc, cmp, desc } from 'type-comparator';

const comparator = cmp()
    .map(x => x.a)
    .use([
        cmp()
            .map(x => x.b)
            .use(desc),
        cmp()
            .if(x => (x.b + x.c) % 2 === 0)
            .map(x => x.c)
            .use(asc),
    ]);

const array = [
    { a: { b: 1, c: 7 } },
    { a: { b: 1, c: 6 } },
    { a: { b: 1, c: 5 } },
    { a: { b: 1, c: 4 } },
    { a: { b: 1, c: 3 } },
    { a: { b: 3, c: 2 } },
];

// [
//     { a: { b: 3, c: 2 } },
//     { a: { b: 1, c: 4 } },
//     { a: { b: 1, c: 6 } },
//     { a: { b: 1, c: 3 } },
//     { a: { b: 1, c: 5 } },
//     { a: { b: 1, c: 7 } },
// ]
array.slice().sort(comparator);

---

Q&A

Q: Should reverse(cmp) be equals to reversed array with cmp ?

A: In general, it should not. Array.prototype.reverse just reverse all elements order, regardless its values. When comparator suppose both values are equal, it returns 0. And these elements save original order.

const array = [1, 2, 4];
const comparator = cmp().map(x => x % 2 === 0).use(asc);

// [2, 4, 1]
array.slice().sort(reverse(comparator));

// [4, 2, 1]
array.slice().sort(comparator).reverse();

Support

Please open an issue for support.

Contributing

Please contribute using Github Flow. Create a branch, add commits, and open a pull request.

type-comparator's Issues

Rename `transform` to `map`

It's really more obvious :)

Change `if` behavior

Seems like if isn't good naming. Any ideas? :)

Here is example how it works: Link

Here is source code: Link

❓

Latest release (0.2.9-rc.2) is missing the build directory

I think the latest release is missing its build directory, which causes TS to fail to import anything.

The error message I get is Cannot find module 'type-comparator' or its corresponding type declarations.ts(2307)

Skimming the Github workflows file, it looks like there's no npm build step being called anywhere, just install and publish

How should I write to get the results I want?

const array = [
{ name: 'Mission1', value: 1, isGeted:true, isFinish:true },
{ name: 'Mission2', value: 2, isGeted:false, isFinish:true },
{ name: 'Mission3', value: 3, isGeted:false, isFinish:false },
{ name: 'Mission4', value: 4, isGeted:false, isFinish:false},
];

I want get the result like this:

const array = [
{ name: 'Mission2', value: 2, isGeted:false, isFinish:true },
{ name: 'Mission4', value: 4, isGeted:false, isFinish:false},
{ name: 'Mission3', value: 3, isGeted:false, isFinish:false },
{ name: 'Mission1', value: 1, isGeted:true, isFinish:true },
];

Means the finish mission is in the top. But when "isGeted" is true, it will move to the bottom.
At last, other missions will sort by value desc.

I write this:
comparator = queue([
map(m => m.isGeted, asc),
map(m => m.isFinish, desc),
map(m => m.value, desc)
]);
but the result is:
[
{ name: 'Mission2', value: 2, isGeted:false, isFinish:true },
{ name: 'Mission1', value: 1, isGeted:true, isFinish:true },
{ name: 'Mission4', value: 4, isGeted:false, isFinish:false},
{ name: 'Mission3', value: 3, isGeted:false, isFinish:false },
];
How should I write to get the results I want?

Angular warns on CommonJS or AMD dependencies

When a class in Angular app uses types from the library, Angular prints the following warning while executing ng build.

Versions
Angular: v14+ (I've not checked on earlier ones).
type-comparator: 0.2.9

Add functionality of 'exclude' chain and functional comparator

IMHO it's really useful to have operator .exclude(values: string | string[]), which will sort values with maximum priority

For example:

const a = [
  "--",
  "a",
  "b"
]

// a = ['a', 'b', '--']
a.sort(cmp().exclude('--').use(asc));