@thi.ng/compare 2.2.26 → 2.3.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2024-03-13T14:04:31Z
+- **Last updated**: 2024-03-29T12:16:20Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,12 @@ See [Conventional Commits](https://conventionalcommits.org/) for commit guidelin
 **Note:** Unlisted _patch_ versions only involve non-code or otherwise excluded changes
 and/or version bumps of transitive dependencies.
 
+## [2.3.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/compare@2.3.0) (2024-03-29)
+
+#### 🚀 Features
+
+- add compareLengthAsc/Desc(), refactor, add docs ([49dab9e](https://github.com/thi-ng/umbrella/commit/49dab9e))
+
 ## [2.2.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/compare@2.2.0) (2023-09-15)
 
 #### 🚀 Features

package/README.md

@@ -15,6 +15,9 @@
 > GitHub](https://github.com/sponsors/postspectacular). Thank you! ❤️
 
 - [About](#about)
+  - [Generic comparison](#generic-comparison)
+  - [Additional comparators](#additional-comparators)
+  - [Operators](#operators)
 - [Status](#status)
 - [Installation](#installation)
 - [Dependencies](#dependencies)
@@ -31,10 +34,32 @@ Comparators with optional support for types implementing the [@thi.ng/api
 `ICompare`](https://github.com/thi-ng/umbrella/tree/develop/packages/api/src/compare.ts)
 interface.
 
-Since v1.2.0 additional higher-order comparators are included, e.g. to
-reverse the ordering of an existing comparator and allow hierarchical
-sorting by multiple keys/dimensions, each with their own optional
-comparator. See examples below.
+### Generic comparison
+
+- [`compare()`](https://docs.thi.ng/umbrella/compare/functions/compare.html)
+
+### Additional comparators
+
+- [`compareByKey()`](https://docs.thi.ng/umbrella/compare/functions/compareByKey.html)
+- [`compareByKeys2()`](https://docs.thi.ng/umbrella/compare/functions/compareByKeys2.html)
+- [`compareByKeys3()`](https://docs.thi.ng/umbrella/compare/functions/compareByKeys3.html)
+- [`compareByKeys4()`](https://docs.thi.ng/umbrella/compare/functions/compareByKeys4.html)
+- [`compareLengthAsc()`](https://docs.thi.ng/umbrella/compare/functions/compareLengthAsc.html)
+- [`compareLengthDesc()`](https://docs.thi.ng/umbrella/compare/functions/compareLengthDesc.html)
+- [`compareNumAsc()`](https://docs.thi.ng/umbrella/compare/functions/compareNumAsc.html)
+- [`compareNumDesc()`](https://docs.thi.ng/umbrella/compare/functions/compareNumDesc.html)
+- [`reverse()`](https://docs.thi.ng/umbrella/compare/functions/reverse.html)
+
+### Operators
+
+- [`numericOp()`](https://docs.thi.ng/umbrella/compare/functions/numericOp.html)
+- [`stringOp()`](https://docs.thi.ng/umbrella/compare/functions/stringOp.html)
+- [`eq()`](https://docs.thi.ng/umbrella/compare/functions/eq.html)
+- [`gt()`](https://docs.thi.ng/umbrella/compare/functions/gt.html)
+- [`gte()`](https://docs.thi.ng/umbrella/compare/functions/gte.html)
+- [`lt()`](https://docs.thi.ng/umbrella/compare/functions/lt.html)
+- [`lte()`](https://docs.thi.ng/umbrella/compare/functions/lte.html)
+- [`neq()`](https://docs.thi.ng/umbrella/compare/functions/neq.html)
 
 ## Status
 
@@ -62,7 +87,7 @@ For Node.js REPL:
 const compare = await import("@thi.ng/compare");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 601 bytes
+Package sizes (brotli'd, pre-treeshake): ESM: 629 bytes
 
 ## Dependencies
 
@@ -111,7 +136,7 @@ compare(new Foo(1), new Foo(2));
 
 Key-based object comparison is supported for 1 - 4 keys / dimensions.
 
-```ts
+```ts tangle:export/readme1.ts
 import * as cmp from "@thi.ng/compare";
 
 const src = [
@@ -122,7 +147,9 @@ const src = [
 ];
 
 // cluster sort by id -> age (default comparators)
-[...src].sort(cmp.compareByKeys2("id", "age"));
+console.log(
+    [...src].sort(cmp.compareByKeys2("id", "age"))
+);
 // [
 //   { id: 'alice', age: 23 },
 //   { id: 'bart', age: 42 },
@@ -131,7 +158,9 @@ const src = [
 // ]
 
 // cluster sort by age -> id (default comparators)
-[...src].sort(cmp.compareByKeys2("age", "id"));
+console.log(
+    [...src].sort(cmp.compareByKeys2("age", "id"))
+);
 // [
 //   { id: 'dora', age: 11 },
 //   { id: 'alice', age: 23 },
@@ -141,7 +170,9 @@ const src = [
 
 // cluster sort by age -> id
 // (custom comparator for `age` key)
-[...src].sort(cmp.compareByKeys2("age", "id", cmp.compareNumDesc));
+console.log(
+    [...src].sort(cmp.compareByKeys2("age", "id", cmp.compareNumDesc))
+);
 // [
 //   { id: 'charlie', age: 66 },
 //   { id: 'bart', age: 42 },
@@ -150,7 +181,9 @@ const src = [
 // ]
 
 // using `reverse()` comparator for `id`
-[...src].sort(cmp.compareByKeys2("age", "id", cmp.compare, cmp.reverse(cmp.compare)));
+console.log(
+    [...src].sort(cmp.compareByKeys2("age", "id", cmp.compare, cmp.reverse(cmp.compare)))
+);
 // [
 //   { id: 'dora', age: 11 },
 //   { id: 'alice', age: 23 },

package/compare.d.ts

@@ -1,2 +1,28 @@
+/**
+ * Generic comparator (for arbitrary types) with support for
+ * [ICompare](https://docs.thi.ng/umbrella/api/interfaces/ICompare.html)
+ * implementations and using the rules described below. Returns standard
+ * comparator result, i.e. a negative value if `a < b`, a positive value if `a >
+ * b` and zero otherwise.
+ *
+ * @remarks
+ * Special handling for the following case, in the given order:
+ *
+ * `a === b` => 0
+ *
+ * | a        | b        | result        |
+ * |----------|----------|--------------:|
+ * | null     | null     | 0             |
+ * | null     | non-null | -1            |
+ * | non-null | null     | 1             |
+ * | ICompare | any      | a.compare(b)  |
+ * | any      | ICompare | -b.compare(a) |
+ *
+ * Note: `null` here also includes `undefined`
+ *
+ * @param a
+ * @param b
+ * @returns
+ */
 export declare const compare: (a: any, b: any) => number;
 //# sourceMappingURL=compare.d.ts.map

package/index.d.ts

@@ -1,5 +1,6 @@
 export * from "./compare.js";
 export * from "./keys.js";
+export * from "./length.js";
 export * from "./numeric.js";
 export * from "./ops.js";
 export * from "./reverse.js";

package/index.js

@@ -1,5 +1,6 @@
 export * from "./compare.js";
 export * from "./keys.js";
+export * from "./length.js";
 export * from "./numeric.js";
 export * from "./ops.js";
 export * from "./reverse.js";

package/keys.js

@@ -1,31 +1,31 @@
 import { compare } from "./compare.js";
-const getKey = (k) => typeof k === "function" ? k : (x) => x[k];
+const __key = (k) => typeof k === "function" ? k : (x) => x[k];
 function compareByKey(key, cmp = compare) {
-  const kfn = getKey(key);
+  const kfn = __key(key);
   return (x, y) => cmp(kfn(x), kfn(y));
 }
 function compareByKeys2(a, b, cmpA = compare, cmpB = compare) {
-  const ka = getKey(a);
-  const kb = getKey(b);
+  const ka = __key(a);
+  const kb = __key(b);
   return (x, y) => {
     let res = cmpA(ka(x), ka(y));
     return res === 0 ? cmpB(kb(x), kb(y)) : res;
   };
 }
 function compareByKeys3(a, b, c, cmpA = compare, cmpB = compare, cmpC = compare) {
-  const ka = getKey(a);
-  const kb = getKey(b);
-  const kc = getKey(c);
+  const ka = __key(a);
+  const kb = __key(b);
+  const kc = __key(c);
   return (x, y) => {
     let res = cmpA(ka(x), ka(y));
     return res === 0 ? (res = cmpB(kb(x), kb(y))) === 0 ? cmpC(kc(x), kc(y)) : res : res;
   };
 }
 function compareByKeys4(a, b, c, d, cmpA = compare, cmpB = compare, cmpC = compare, cmpD = compare) {
-  const ka = getKey(a);
-  const kb = getKey(b);
-  const kc = getKey(c);
-  const kd = getKey(d);
+  const ka = __key(a);
+  const kb = __key(b);
+  const kc = __key(c);
+  const kd = __key(d);
   return (x, y) => {
     let res = cmpA(ka(x), ka(y));
     return res === 0 ? (res = cmpB(kb(x), kb(y))) === 0 ? (res = cmpC(kc(x), kc(y))) === 0 ? cmpD(kd(x), kd(y)) : res : res : res;

package/length.d.ts

@@ -0,0 +1,16 @@
+import type { Comparator, ILength } from "@thi.ng/api";
+/**
+ * Length comparator (ascending order)
+ *
+ * @param a -
+ * @param b -
+ */
+export declare const compareLengthAsc: Comparator<ILength>;
+/**
+ * Length comparator (descending order)
+ *
+ * @param a -
+ * @param b -
+ */
+export declare const compareLengthDesc: Comparator<ILength>;
+//# sourceMappingURL=length.d.ts.map

package/length.js

@@ -0,0 +1,6 @@
+const compareLengthAsc = (a, b) => a.length - b.length;
+const compareLengthDesc = (a, b) => b.length - a.length;
+export {
+  compareLengthAsc,
+  compareLengthDesc
+};

package/numeric.d.ts

@@ -1,16 +1,16 @@
-import type { FnN2 } from "@thi.ng/api";
+import type { Comparator } from "@thi.ng/api";
 /**
  * Numeric comparator (ascending order)
  *
  * @param a -
  * @param b -
  */
-export declare const compareNumAsc: FnN2;
+export declare const compareNumAsc: Comparator<number>;
 /**
  * Numeric comparator (descending order)
  *
  * @param a -
  * @param b -
  */
-export declare const compareNumDesc: FnN2;
+export declare const compareNumDesc: Comparator<number>;
 //# sourceMappingURL=numeric.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/compare",
-  "version": "2.2.26",
+  "version": "2.3.0",
   "description": "Comparators with support for types implementing the @thi.ng/api/ICompare interface",
   "type": "module",
   "module": "./index.js",
@@ -36,14 +36,14 @@
     "tool:tangle": "../../node_modules/.bin/tangle src/**/*.ts"
   },
   "dependencies": {
-    "@thi.ng/api": "^8.9.30"
+    "@thi.ng/api": "^8.9.31"
   },
   "devDependencies": {
-    "@microsoft/api-extractor": "^7.42.3",
-    "esbuild": "^0.20.1",
+    "@microsoft/api-extractor": "^7.43.0",
+    "esbuild": "^0.20.2",
     "rimraf": "^5.0.5",
     "typedoc": "^0.25.12",
-    "typescript": "^5.4.2"
+    "typescript": "^5.4.3"
   },
   "keywords": [
     "comparator",
@@ -70,6 +70,9 @@
     "./keys": {
       "default": "./keys.js"
     },
+    "./length": {
+      "default": "./length.js"
+    },
     "./numeric": {
       "default": "./numeric.js"
     },
@@ -80,5 +83,5 @@
       "default": "./reverse.js"
     }
   },
-  "gitHead": "7f3fcbd6c0462b0ce45afa141fe163d1f297fd51\n"
+  "gitHead": "ce5ae2a322d50a7ce8ecccbd94fa55c496ba04fd\n"
 }