@guillaume-docquier/tools-ts 4.0.1 → 4.1.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.

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

@@ -23,3 +23,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

@@ -18,4 +18,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,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/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.1.0",
   "description": "My personal collection of typescript tools",
   "homepage": "https://github.com/Guillaume-Docquier/tools-ts",
   "repository": {