@guillaume-docquier/tools-ts 4.0.1 → 4.2.0

package/README.md

@@ -44,6 +44,26 @@ duplicating min/max checks across call sites.
 | ------- | ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
 | `Range` | Helpers for creating, validating, comparing, and testing ranges. | You need finite integer or float intervals with inclusive minimums and configurable maximums. |
 
+### Sorting
+
+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. |
+
+### Randomness
+
+Use these tools when code needs injectable randomness or deterministic
+pseudo-random sequences.
+
+| Export           | What it is                                                           | Use it when                                                                               |
+| ---------------- | -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| `Rng`            | Type for the RNG facade returned by `createRng`.                     | A function accepts or stores the package RNG abstraction.                                 |
+| `createRng`      | Builds an RNG facade from a generator that returns values in [0, 1). | You need range-aware random numbers, shuffling, or draws backed by injectable randomness. |
+| `Generator`      | Type for raw generators that return values in [0, 1).                | You accept or provide the primitive random source used to construct an `Rng`.             |
+| `mulberry32Prng` | Deterministic seeded pseudo-random generator factory.                | Tests, simulations, or generation code need repeatable pseudo-random sequences.           |
+
 ### Utility Types
 
 These exports are type-only helpers for common TypeScript modeling problems.
@@ -81,12 +101,13 @@ 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.       |
+| 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.                                         |
 
 ### Measurement
 

package/dist/Sort.d.ts

@@ -0,0 +1,6 @@
+export declare const Sort: {
+    /**
+     * Sorts numbers by ascending values
+     */
+    byAscending: (a: number, b: number) => number;
+};

package/dist/Sort.js

@@ -0,0 +1,9 @@
+export const Sort = {
+    /**
+     * Sorts numbers by ascending values
+     */
+    byAscending: (a, b) => {
+        return a - b;
+    },
+};
+//# sourceMappingURL=Sort.js.map

package/dist/Sort.js.map

@@ -0,0 +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;CACF,CAAA"}

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

@@ -6,6 +6,7 @@ export { isNodeJSError } from "./errors/isNodeJSError.js";
 export { getEnumKey } from "./getEnumKey.js";
 export type * from "./utility-types.js";
 export { asArray } from "./asArray.js";
+export { omit } from "./omit.js";
 export { Assert } from "./Assert.js";
 export { Result, type Success, type Failure } from "./Result.js";
 export { Measure } from "./Measure.js";
@@ -23,3 +24,6 @@ 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 { createRng, type Rng, type Generator } from "./rng/rng.js";
+export { mulberry32Prng } from "./rng/mulberry32prng.js";

package/dist/entry.tools-ts.js

@@ -5,6 +5,7 @@ export { NotImplementedError } from "./errors/NotImplementedError.js";
 export { isNodeJSError } from "./errors/isNodeJSError.js";
 export { getEnumKey } from "./getEnumKey.js";
 export { asArray } from "./asArray.js";
+export { omit } from "./omit.js";
 export { Assert } from "./Assert.js";
 export { Result } from "./Result.js";
 export { Measure } from "./Measure.js";
@@ -18,4 +19,7 @@ export { jsonLineFormatter } from "./logging/formatter/jsonLineFormatter.js";
 export { prettyConsoleFormatter } from "./logging/formatter/prettyConsoleFormatter.js";
 export { createConsoleLogSink } from "./logging/sink/ConsoleLogSink.js";
 export { debounce } from "./debounce.js";
+export { Sort } from "./Sort.js";
+export { createRng } from "./rng/rng.js";
+export { mulberry32Prng } from "./rng/mulberry32prng.js";
 //# sourceMappingURL=entry.tools-ts.js.map

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,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,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"}
+{"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,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,SAAS,EAA4B,MAAM,cAAc,CAAA;AAClE,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAA"}

package/dist/noop.d.ts

@@ -1,10 +1,10 @@
 /**
  * Does nothing.
- * Usually used a default parameter for optional callbacks.
+ * Usually used as a default parameter for optional callbacks.
  */
 export declare function noop(): void;
 /**
  * Asynchronously does nothing.
- * Usually used a default parameter for async optional callbacks.
+ * Usually used as a default parameter for async optional callbacks.
  */
 export declare function asyncNoop(): Promise<void>;

package/dist/noop.js

@@ -1,11 +1,11 @@
 /**
  * Does nothing.
- * Usually used a default parameter for optional callbacks.
+ * Usually used as a default parameter for optional callbacks.
  */
 export function noop() { }
 /**
  * Asynchronously does nothing.
- * Usually used a default parameter for async optional callbacks.
+ * Usually used as a default parameter for async optional callbacks.
  */
 export async function asyncNoop() { }
 //# sourceMappingURL=noop.js.map

package/dist/omit.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Returns the given record with omitted keys.
+ *
+ * @example
+ * ```ts
+ * const record = { a: 1, b: 2, c: 3 }
+ * const omitted = omit(record, "b", "c")
+ *
+ * console.log(record) // { a: 1, b: 2, c: 3 }
+ * console.log(omitted) // { a: 1 }
+ * ```
+ */
+export declare function omit<TRecord extends Record<string, unknown>, TKey extends keyof TRecord>(record: Readonly<TRecord>, ...keys: TKey[]): Omit<TRecord, TKey>;

package/dist/omit.js

@@ -0,0 +1,20 @@
+/**
+ * Returns the given record with omitted keys.
+ *
+ * @example
+ * ```ts
+ * const record = { a: 1, b: 2, c: 3 }
+ * const omitted = omit(record, "b", "c")
+ *
+ * console.log(record) // { a: 1, b: 2, c: 3 }
+ * console.log(omitted) // { a: 1 }
+ * ```
+ */
+export function omit(record, ...keys) {
+    const result = { ...record };
+    for (const key of keys) {
+        delete result[key];
+    }
+    return result;
+}
+//# sourceMappingURL=omit.js.map

package/dist/omit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"omit.js","sourceRoot":"","sources":["../src/omit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,IAAI,CAClB,MAAyB,EACzB,GAAG,IAAY;IAEf,MAAM,MAAM,GAAG,EAAE,GAAG,MAAM,EAAE,CAAA;IAE5B,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,OAAO,MAAM,CAAC,GAAG,CAAC,CAAA;IACpB,CAAC;IAED,OAAO,MAAM,CAAA;AACf,CAAC"}

package/dist/rng/mulberry32prng.d.ts

@@ -0,0 +1,7 @@
+import type { Generator } from "./rng.js";
+/**
+ * Creates a deterministic pseudo-random number generator based on a 32-bit integer seed using the mulberry32 algorithm.
+ *
+ * It generates floats in the range [0, 1)
+ */
+export declare function mulberry32Prng(seed: number): Generator;

package/dist/rng/mulberry32prng.js

@@ -0,0 +1,16 @@
+/**
+ * Creates a deterministic pseudo-random number generator based on a 32-bit integer seed using the mulberry32 algorithm.
+ *
+ * It generates floats in the range [0, 1)
+ */
+export function mulberry32Prng(seed) {
+    let state = seed >>> 0;
+    return () => {
+        state += 0x6d2b79f5;
+        let next = state;
+        next = Math.imul(next ^ (next >>> 15), next | 1);
+        next ^= next + Math.imul(next ^ (next >>> 7), next | 61);
+        return ((next ^ (next >>> 14)) >>> 0) / 4_294_967_296;
+    };
+}
+//# sourceMappingURL=mulberry32prng.js.map

package/dist/rng/mulberry32prng.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mulberry32prng.js","sourceRoot":"","sources":["../../src/rng/mulberry32prng.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,IAAI,KAAK,GAAG,IAAI,KAAK,CAAC,CAAA;IAEtB,OAAO,GAAG,EAAE;QACV,KAAK,IAAI,UAAU,CAAA;QAEnB,IAAI,IAAI,GAAG,KAAK,CAAA;QAChB,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,IAAI,KAAK,EAAE,CAAC,EAAE,IAAI,GAAG,CAAC,CAAC,CAAA;QAChD,IAAI,IAAI,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,IAAI,KAAK,CAAC,CAAC,EAAE,IAAI,GAAG,EAAE,CAAC,CAAA;QAExD,OAAO,CAAC,CAAC,IAAI,GAAG,CAAC,IAAI,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,aAAa,CAAA;IACvD,CAAC,CAAA;AACH,CAAC"}

package/dist/rng/rng.d.ts

@@ -0,0 +1,37 @@
+import type { Range } from "../Range.js";
+/**
+ * A generator that returns numbers in the range [0, 1)
+ */
+export type Generator = () => number;
+export type Rng = {
+    /**
+     * Generates a random number based on the given Range.
+     * It will output an int given an int Range, or a float given a float Range.
+     */
+    random: (range: Range) => number;
+    /**
+     * Generates a float in the float Range.
+     * When no range is provided, returns a float in the range [0, 1).
+     */
+    float: (range?: Range<"float">) => number;
+    /**
+     * Generates an int in the int Range.
+     */
+    int: (range: Range<"integer">) => number;
+    /**
+     * Shuffles an array in place.
+     */
+    shuffle: <T>(values: T[]) => T[];
+    /**
+     * Draws a number of elements without modifying the original array.
+     */
+    draw: <T>(values: T[], count: number) => {
+        drawn: T[];
+        remaining: T[];
+    };
+};
+/**
+ * Creates a random number generator based on your generator of choice.
+ * @param generator The generator that returns numbers in the range [0, 1)
+ */
+export declare function createRng(generator: Generator): Rng;

package/dist/rng/rng.js

@@ -0,0 +1,58 @@
+const intBoundsOffset = {
+    inclusive: 1,
+    exclusive: 0,
+};
+/**
+ * Creates a random number generator based on your generator of choice.
+ * @param generator The generator that returns numbers in the range [0, 1)
+ */
+export function createRng(generator) {
+    function random(range) {
+        switch (range.numericType) {
+            case "float":
+                // The fact we have to cast like this sucks a little bit, we'll see if we have to do this often or not.
+                return float(range);
+            case "integer":
+                // The fact we have to cast like this sucks a little bit, we'll see if we have to do this often or not.
+                return int(range);
+        }
+    }
+    function float(range) {
+        if (range === undefined) {
+            return generator();
+        }
+        // Because of floating point errors, this is inclusive when min > 1, but that's statistically insignificant.
+        return range.min + generator() * (range.max - range.min);
+    }
+    function int(range) {
+        // We +1 the max because float is exclusive of the max, but for int we want the range to be inclusive.
+        // We floor before the addition, because the addition can lose precision and generate numbers that are out of bounds when float ~= 1.
+        // We don't use Math.floor(float(rangeWithMaxPlus1)) for the same reason
+        return range.min + Math.floor(float() * (range.max + intBoundsOffset[range.maxBoundType] - range.min));
+    }
+    /**
+     * Fisher-Yates shuffle in place.
+     */
+    function shuffle(values) {
+        for (let i = values.length - 1; i > 0; i--) {
+            const j = Math.floor(generator() * (i + 1));
+            [values[i], values[j]] = [values[j], values[i]];
+        }
+        return values;
+    }
+    function draw(values, count) {
+        const shuffled = shuffle(values.slice());
+        return {
+            drawn: shuffled,
+            remaining: shuffled.splice(count),
+        };
+    }
+    return {
+        random,
+        float,
+        int,
+        shuffle,
+        draw,
+    };
+}
+//# sourceMappingURL=rng.js.map

package/dist/rng/rng.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rng.js","sourceRoot":"","sources":["../../src/rng/rng.ts"],"names":[],"mappings":"AAoCA,MAAM,eAAe,GAAG;IACtB,SAAS,EAAE,CAAC;IACZ,SAAS,EAAE,CAAC;CAC4C,CAAA;AAE1D;;;GAGG;AACH,MAAM,UAAU,SAAS,CAAC,SAAoB;IAC5C,SAAS,MAAM,CAAC,KAAY;QAC1B,QAAQ,KAAK,CAAC,WAAW,EAAE,CAAC;YAC1B,KAAK,OAAO;gBACV,uGAAuG;gBACvG,OAAO,KAAK,CAAC,KAAwC,CAAC,CAAA;YACxD,KAAK,SAAS;gBACZ,uGAAuG;gBACvG,OAAO,GAAG,CAAC,KAAwC,CAAC,CAAA;QACxD,CAAC;IACH,CAAC;IAED,SAAS,KAAK,CAAC,KAAsB;QACnC,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,OAAO,SAAS,EAAE,CAAA;QACpB,CAAC;QAED,4GAA4G;QAC5G,OAAO,KAAK,CAAC,GAAG,GAAG,SAAS,EAAE,GAAG,CAAC,KAAK,CAAC,GAAG,GAAG,KAAK,CAAC,GAAG,CAAC,CAAA;IAC1D,CAAC;IAED,SAAS,GAAG,CAAC,KAAuB;QAClC,sGAAsG;QACtG,qIAAqI;QACrI,wEAAwE;QACxE,OAAO,KAAK,CAAC,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,GAAG,CAAC,KAAK,CAAC,GAAG,GAAG,eAAe,CAAC,KAAK,CAAC,YAAY,CAAC,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAA;IACxG,CAAC;IAED;;OAEG;IACH,SAAS,OAAO,CAAI,MAA0B;QAC5C,KAAK,IAAI,CAAC,GAAG,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;YAC3C,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAC1C;YAAA,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAM,EAAE,MAAM,CAAC,CAAC,CAAM,CAAC,CAAA;QAC5D,CAAC;QAED,OAAO,MAAM,CAAA;IACf,CAAC;IAED,SAAS,IAAI,CAAI,MAAkC,EAAE,KAAa;QAChE,MAAM,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAA;QAExC,OAAO;YACL,KAAK,EAAE,QAAQ;YACf,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC;SAClC,CAAA;IACH,CAAC;IAED,OAAO;QACL,MAAM;QACN,KAAK;QACL,GAAG;QACH,OAAO;QACP,IAAI;KACL,CAAA;AACH,CAAC"}

package/package.json

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