@guillaume-docquier/tools-ts 8.6.0 → 9.0.0

package/README.md

@@ -49,9 +49,10 @@ intervals.
 
 Use this tool when code needs shared ordering helpers.
 
-| Export | What it is                                     | Use it when                                                                             |
-| ------ | ---------------------------------------------- | --------------------------------------------------------------------------------------- |
-| `Sort` | Comparator helpers for common sort operations. | You want a shared sorting utility instead of rewriting compare callbacks at call sites. |
+| Export       | What it is                                                                     | Use it when                                                                             |
+| ------------ | ------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------- |
+| `Sort`       | Direction-aware numeric and property comparators, plus comparator composition. | You want a shared sorting utility instead of rewriting compare callbacks at call sites. |
+| `Comparator` | Helper type to define comparators compatible with the Sort utilities.          | You define sorting comparators.                                                         |
 
 ### Randomness
 
@@ -106,14 +107,14 @@ consistent context, scopes, formatting, and redaction.
 Use these small utilities to keep common asynchronous and callback patterns
 consistent.
 
-| Export            | What it is                                            | Use it when                                                                     |
-| ----------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------- |
-| `setTimeoutAsync` | Promise-based timeout helper.                         | You want `await`-friendly delays that work in browser and Node environments.    |
-| `debounce`        | Creates a debounced callback.                         | A repeated event should trigger work only after calls have settled for a delay. |
-| `noop`            | Synchronous no-op function.                           | You need a safe default callback that intentionally does nothing.               |
-| `asyncNoop`       | Asynchronous no-op function.                          | You need a safe default async callback or hook that resolves immediately.       |
-| `omit`            | Runtime equivalent of `Omit<TType, TKey>`.            | You need to remove keys from an object.                                         |
-| `indexBy`         | Indexes objects by a selected string-valued property. | You need to look up objects by a string key.                                    |
+| Export            | What it is                                                      | Use it when                                                                     |
+| ----------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------- |
+| `setTimeoutAsync` | Promise-based timeout helper.                                   | You want `await`-friendly delays that work in browser and Node environments.    |
+| `debounce`        | Creates a debounced callback.                                   | A repeated event should trigger work only after calls have settled for a delay. |
+| `noop`            | Synchronous no-op function.                                     | You need a safe default callback that intentionally does nothing.               |
+| `asyncNoop`       | Asynchronous no-op function.                                    | You need a safe default async callback or hook that resolves immediately.       |
+| `omit`            | Runtime equivalent of `Omit<TType, TKey>`.                      | You need to remove keys from an object.                                         |
+| `indexBy`         | Indexes objects by a selected string or number valued property. | You need to look up objects by a key.                                           |
 
 ### Profiling
 

package/dist/Sort.d.ts

@@ -1,18 +1,29 @@
-export declare const Sort: {
+declare enum SortDirection {
+    /**
+     * From smallest to biggest.
+     */
+    Ascending = "Ascending",
     /**
-     * Sorts numbers by ascending values
+     * From biggest to smallest.
      */
-    byAscending: (a: number, b: number) => number;
+    Descending = "Descending"
+}
+export type Comparator<T> = (first: T, second: T) => number;
+export declare const Sort: {
+    Direction: typeof SortDirection;
     /**
-     * Sorts records by a numeric property in ascending order
+     * Composes comparators.
      */
-    byAscendingProperty: <TProperty extends PropertyKey>(property: TProperty) => <TRecord extends Record<TProperty, number>>(a: TRecord, b: TRecord) => number;
+    compose: <T>(...comparators: ReadonlyArray<Comparator<T>>) => Comparator<T>;
     /**
-     * Sorts numbers by ascending values
+     * Compares numbers in the selected direction.
+     * Defaults to Ascending.
      */
-    byDescending: (a: number, b: number) => number;
+    numeric: (direction?: SortDirection) => Comparator<number>;
     /**
-     * Sorts records by a numeric property in descending order
+     * Compares records by a numeric property in the selected direction.
+     * Defaults to Ascending.
      */
-    byDescendingProperty: <TProperty extends PropertyKey>(property: TProperty) => <TRecord extends Record<TProperty, number>>(a: TRecord, b: TRecord) => number;
+    byNumericProperty: <TProperty extends PropertyKey>(property: TProperty, direction?: SortDirection) => <TRecord extends Record<TProperty, number>>(first: TRecord, second: TRecord) => number;
 };
+export {};

package/dist/Sort.js

@@ -1,27 +1,49 @@
-export const Sort = {
+var SortDirection;
+(function (SortDirection) {
     /**
-     * Sorts numbers by ascending values
+     * From smallest to biggest.
      */
-    byAscending: (a, b) => {
-        return a - b;
-    },
+    SortDirection["Ascending"] = "Ascending";
+    /**
+     * From biggest to smallest.
+     */
+    SortDirection["Descending"] = "Descending";
+})(SortDirection || (SortDirection = {}));
+export const Sort = {
+    Direction: SortDirection,
     /**
-     * Sorts records by a numeric property in ascending order
+     * Composes comparators.
      */
-    byAscendingProperty: (property) => (a, b) => {
-        return Sort.byAscending(a[property], b[property]);
+    compose: (...comparators) => {
+        return (first, second) => {
+            for (const comparator of comparators) {
+                const comparison = comparator(first, second);
+                if (comparison !== 0) {
+                    return comparison;
+                }
+            }
+            return 0;
+        };
     },
     /**
-     * Sorts numbers by ascending values
+     * Compares numbers in the selected direction.
+     * Defaults to Ascending.
      */
-    byDescending: (a, b) => {
-        return b - a;
+    numeric: (direction = SortDirection.Ascending) => {
+        switch (direction) {
+            case SortDirection.Ascending:
+                return (first, second) => first - second;
+            case SortDirection.Descending:
+                return (first, second) => second - first;
+        }
     },
     /**
-     * Sorts records by a numeric property in descending order
+     * Compares records by a numeric property in the selected direction.
+     * Defaults to Ascending.
      */
-    byDescendingProperty: (property) => (a, b) => {
-        return Sort.byDescending(a[property], b[property]);
+    byNumericProperty: (property, direction = SortDirection.Ascending) => {
+        const compare = Sort.numeric(direction);
+        return (first, second) => compare(first[property], second[property]);
     },
 };
 //# sourceMappingURL=Sort.js.map

package/dist/Sort.js.map

@@ -1 +1 @@
-{"version":3,"file":"Sort.js","sourceRoot":"","sources":["../src/Sort.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,IAAI,GAAG;IAClB;;OAEG;IACH,WAAW,EAAE,CAAC,CAAS,EAAE,CAAS,EAAU,EAAE;QAC5C,OAAO,CAAC,GAAG,CAAC,CAAA;IACd,CAAC;IAED;;OAEG;IACH,mBAAmB,EACjB,CAAgC,QAAmB,EAAE,EAAE,CACvD,CAA4C,CAAU,EAAE,CAAU,EAAU,EAAE;QAC5E,OAAO,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAA;IACnD,CAAC;IAEH;;OAEG;IACH,YAAY,EAAE,CAAC,CAAS,EAAE,CAAS,EAAU,EAAE;QAC7C,OAAO,CAAC,GAAG,CAAC,CAAA;IACd,CAAC;IAED;;OAEG;IACH,oBAAoB,EAClB,CAAgC,QAAmB,EAAE,EAAE,CACvD,CAA4C,CAAU,EAAE,CAAU,EAAU,EAAE;QAC5E,OAAO,IAAI,CAAC,YAAY,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAA;IACpD,CAAC;CACJ,CAAA"}
+{"version":3,"file":"Sort.js","sourceRoot":"","sources":["../src/Sort.ts"],"names":[],"mappings":"AAAA,IAAK,aAUJ;AAVD,WAAK,aAAa;IAChB;;OAEG;IACH,wCAAuB,CAAA;IAEvB;;OAEG;IACH,0CAAyB,CAAA;AAC3B,CAAC,EAVI,aAAa,KAAb,aAAa,QAUjB;AAID,MAAM,CAAC,MAAM,IAAI,GAAG;IAClB,SAAS,EAAE,aAAa;IAExB;;OAEG;IACH,OAAO,EAAE,CAAI,GAAG,WAAyC,EAAiB,EAAE;QAC1E,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE;YACvB,KAAK,MAAM,UAAU,IAAI,WAAW,EAAE,CAAC;gBACrC,MAAM,UAAU,GAAG,UAAU,CAAC,KAAK,EAAE,MAAM,CAAC,CAAA;gBAC5C,IAAI,UAAU,KAAK,CAAC,EAAE,CAAC;oBACrB,OAAO,UAAU,CAAA;gBACnB,CAAC;YACH,CAAC;YAED,OAAO,CAAC,CAAA;QACV,CAAC,CAAA;IACH,CAAC;IAED;;;OAGG;IACH,OAAO,EAAE,CAAC,SAAS,GAAkB,aAAa,CAAC,SAAS,EAAsB,EAAE;QAClF,QAAQ,SAAS,EAAE,CAAC;YAClB,KAAK,aAAa,CAAC,SAAS;gBAC1B,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,CAAC,KAAK,GAAG,MAAM,CAAA;YAC1C,KAAK,aAAa,CAAC,UAAU;gBAC3B,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,CAAC,MAAM,GAAG,KAAK,CAAA;QAC5C,CAAC;IACH,CAAC;IAED;;;OAGG;IACH,iBAAiB,EAAE,CAAgC,QAAmB,EAAE,SAAS,GAAkB,aAAa,CAAC,SAAS,EAAE,EAAE;QAC5H,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,CAAA;QACvC,OAAO,CAA4C,KAAc,EAAE,MAAe,EAAU,EAAE,CAC5F,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAA;IAC9C,CAAC;CACF,CAAA"}

package/dist/entry.tools-ts.d.ts

@@ -25,7 +25,7 @@ export type { LogContext } from "./logging/log-context/LogContext.js";
 export type { LoggerContext } from "./logging/log-context/LoggerContext.js";
 export type { LogContextProvider } from "./logging/log-context/LogContextProvider.js";
 export { debounce } from "./debounce.js";
-export { Sort } from "./Sort.js";
+export { Sort, type Comparator } from "./Sort.js";
 export { Rng, type RngState } from "./rng/Rng.js";
 export type { Generator } from "./rng/Generator.js";
 export { createGeneratorStub } from "./rng/Generator.stub.js";

package/dist/entry.tools-ts.js.map

@@ -1 +1 @@
-{"version":3,"file":"entry.tools-ts.js","sourceRoot":"","sources":["../src/entry.tools-ts.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAC7C,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAA;AAC3D,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAA;AACnD,OAAO,EAAE,mBAAmB,EAAE,MAAM,iCAAiC,CAAA;AACrE,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAA;AACzD,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAI5C,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AACtC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAChC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACpC,OAAO,EAAE,MAAM,EAA8B,MAAM,aAAa,CAAA;AAChE,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AACtC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAClC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACpC,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAC1C,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AACtD,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,WAAW,CAAA;AAE3C,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAA;AAC5C,OAAO,EAAE,yBAAyB,EAAE,MAAM,wBAAwB,CAAA;AAClE,OAAO,EAAE,iBAAiB,EAAE,MAAM,0CAA0C,CAAA;AAC5E,OAAO,EAAE,sBAAsB,EAAE,MAAM,+CAA+C,CAAA;AAEtF,OAAO,EAAE,oBAAoB,EAAE,MAAM,kCAAkC,CAAA;AAKvE,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AACxC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAChC,OAAO,EAAE,GAAG,EAAiB,MAAM,cAAc,CAAA;AAEjD,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAA;AAC7D,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAA;AACxD,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AACxC,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAA;AAC5D,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAA;AACzD,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAA;AACrE,OAAO,EAAE,OAAO,EAAW,MAAM,2BAA2B,CAAA;AAC5D,OAAO,EAAE,OAAO,EAAY,MAAM,2BAA2B,CAAA;AAC7D,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAClC,OAAO,EAAgB,OAAO,EAAgE,MAAM,YAAY,CAAA;AAChH,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA"}
+{"version":3,"file":"entry.tools-ts.js","sourceRoot":"","sources":["../src/entry.tools-ts.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAC7C,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAA;AAC3D,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAA;AACnD,OAAO,EAAE,mBAAmB,EAAE,MAAM,iCAAiC,CAAA;AACrE,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAA;AACzD,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAI5C,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AACtC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAChC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACpC,OAAO,EAAE,MAAM,EAA8B,MAAM,aAAa,CAAA;AAChE,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AACtC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAClC,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACpC,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAA;AAC1C,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AACtD,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,WAAW,CAAA;AAE3C,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAA;AAC5C,OAAO,EAAE,yBAAyB,EAAE,MAAM,wBAAwB,CAAA;AAClE,OAAO,EAAE,iBAAiB,EAAE,MAAM,0CAA0C,CAAA;AAC5E,OAAO,EAAE,sBAAsB,EAAE,MAAM,+CAA+C,CAAA;AAEtF,OAAO,EAAE,oBAAoB,EAAE,MAAM,kCAAkC,CAAA;AAKvE,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AACxC,OAAO,EAAE,IAAI,EAAmB,MAAM,WAAW,CAAA;AACjD,OAAO,EAAE,GAAG,EAAiB,MAAM,cAAc,CAAA;AAEjD,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAA;AAC7D,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAA;AACxD,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AACxC,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAA;AAC5D,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAA;AACzD,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAA;AACrE,OAAO,EAAE,OAAO,EAAW,MAAM,2BAA2B,CAAA;AAC5D,OAAO,EAAE,OAAO,EAAY,MAAM,2BAA2B,CAAA;AAC7D,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAClC,OAAO,EAAgB,OAAO,EAAgE,MAAM,YAAY,CAAA;AAChH,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guillaume-docquier/tools-ts",
-  "version": "8.6.0",
+  "version": "9.0.0",
   "description": "My personal collection of typescript tools",
   "homepage": "https://github.com/Guillaume-Docquier/tools-ts",
   "license": "MIT",