@esmalley/ts-utils 6.4.5 → 7.0.0

package/README.md

@@ -20,15 +20,19 @@ A modular collection of TypeScript utilities for modern web development.
 * [CSV](#csv)
 * [Dates](#dates)
 * [Kontororu (Events)](#kontororu-events)
+* [Numbers](#numbers)
 * [Objector](#objector)
 * [Sorter](#sorter)
 * [Style](#style)
+* [Tasker](#tasker)
 * [Textor](#textor)
 * [Theme](#theme)
 * [Toaster](#toaster)
+* [UuidService](#uuidservice)
 
 
 * [Testing](#testing)
+  * [Benchmarks](#benchmarks)
 * [License](#license)
 
 ---
@@ -76,6 +80,48 @@ console.log(actualHealth); // Output: 100
 ```
 
 
+### `lerp(a, b, amount)`
+
+Linearly interpolates between two numbers. `amount` is clamped to 0–1, so the result never overshoots.
+
+```ts
+Arithmetic.lerp(0, 100, 0.25); // 25
+```
+
+### `round(value, precision?)`
+
+Rounds to a fixed number of decimal places, handling the half-way cases that naive scaling gets wrong. A negative precision rounds to tens, hundreds, and so on.
+
+```ts
+Arithmetic.round(1.005, 2); // 1.01  (not 1 as with Math.round(v * 100) / 100)
+Arithmetic.round(1234, -2); // 1200
+```
+
+### `mapRange(value, inMin, inMax, outMin, outMax)` / `normalize(value, min, max)`
+
+Re-maps a number from one range onto another. `normalize` is the special case that maps onto 0–1, and is the inverse of `lerp`.
+
+```ts
+// A 1000-2000 rating expressed as a 0-100 score
+Arithmetic.mapRange(1500, 1000, 2000, 0, 100); // 50
+Arithmetic.normalize(1500, 1000, 2000);        // 0.5
+```
+
+### Descriptive statistics
+
+`sum`, `mean`, `median`, `mode`, `variance`, `stdDev`, and `percentile`.
+
+Aggregates over an empty list return `NaN` rather than `0`, so an empty data set is visibly empty instead of silently reading as a real zero. `variance` and `stdDev` are sample statistics (dividing by `n - 1`); pass `true` as the second argument for the population form.
+
+```ts
+const scores = [88, 72, 95, 64, 79];
+
+Arithmetic.mean(scores);            // 79.6
+Arithmetic.median(scores);          // 79
+Arithmetic.stdDev(scores);          // 11.97...
+Arithmetic.percentile(scores, 90);  // 92.2
+Arithmetic.mode([1, 2, 2, 3]);      // [2]   (every tied value, in first-seen order)
+```
 
 ---
 
@@ -112,7 +158,62 @@ const matchups = Arrayifier.getCombinations(players, 2);
 
 ```
 
+A three-argument form, `getCombinations(arr, n, r)`, draws from only the first `n` elements.
+
+### `groupBy(arr, keyFn)` / `countBy(arr, keyFn)`
+
+Buckets or counts items by a derived key.
+
+```ts
+Arrayifier.groupBy(games, (g) => g.season);
+// { 2025: [...], 2026: [...] }
+
+Arrayifier.countBy(games, (g) => g.status);
+// { final: 12, live: 3 }
+```
+
+### `chunk(arr, size)`
+
+Splits an array into consecutive chunks of at most `size`.
+
+```ts
+Arrayifier.chunk([1, 2, 3, 4, 5], 2); // [[1, 2], [3, 4], [5]]
+```
+
+### `unique(arr)` / `uniqueBy(arr, keyFn)`
+
+Removes duplicates, keeping the first occurrence. `unique` compares by identity; `uniqueBy` compares a derived key, which is what you want for objects.
+
+```ts
+Arrayifier.unique([1, 2, 2, 3]);              // [1, 2, 3]
+Arrayifier.uniqueBy(players, (p) => p.team_id);
+```
 
+### `sortBy(arr, keyFn, direction?)`
+
+Sorts by a derived value without mutating the input. Numbers compare numerically, everything else as strings, and null/undefined keys sort last in both directions.
+
+```ts
+Arrayifier.sortBy(teams, (t) => t.rating, 'desc');
+```
+
+### `partition(arr, predicate)`
+
+Splits into the items that satisfy the predicate and those that do not.
+
+```ts
+const [wins, losses] = Arrayifier.partition(games, (g) => g.won);
+```
+
+### `range(start, end?, step?)`
+
+A sequence of numbers, excluding the end. With one argument, counts from 0.
+
+```ts
+Arrayifier.range(4);        // [0, 1, 2, 3]
+Arrayifier.range(1, 4);     // [1, 2, 3]
+Arrayifier.range(3, 0, -1); // [3, 2, 1]
+```
 
 ---
 
@@ -173,7 +274,20 @@ console.log(overlay); // Output: rgba(0, 0, 0, 0.5)
 
 ```
 
+### Conversions: `hexToRgb`, `rgbToHex`, `rgbToHsl`, `hslToRgb`
 
+The full set of conversions is public, so you can move between representations in either direction. `hexToRgb` accepts shorthand (`#fff`) and throws on malformed input rather than silently reporting black. `rgbToHex` rounds and clamps its channels, so an out-of-range value cannot produce a malformed string.
+
+```ts
+Color.hexToRgb('#ff8000');     // [255, 128, 0]
+Color.rgbToHex(255, 128, 0);   // '#FF8000'
+Color.rgbToHsl(255, 0, 0);     // [0, 100, 50]   (hue 0-360, sat/lightness 0-100)
+Color.hslToRgb(0, 100, 50);    // [255, 0, 0]
+
+// Rotate a hue without leaving hex
+const [h, s, l] = Color.rgbToHsl(...Color.hexToRgb('#3498db'));
+const shifted = Color.rgbToHex(...Color.hslToRgb((h + 180) % 360, s, l));
+```
 
 ---
 
@@ -181,6 +295,27 @@ console.log(overlay); // Output: rgba(0, 0, 0, 0.5)
 
 Utilities for data exportation.
 
+### `stringify(data)`
+
+Converts a nested object into an RFC 4180 CSV string. Headers are the union of every row's keys, so a row carrying extra columns is not truncated to the shape of the first one. Values containing a comma, quote or newline are quoted, and embedded quotes are doubled. `null` and `undefined` become empty cells, while `0`, `false` and `''` survive as written.
+
+* **Example 1: Building a CSV in Memory**
+```ts
+import { CSV } from '@esmalley/ts-utils';
+
+const csv = CSV.stringify({
+  1: { team: 'Tigers', wins: 0, note: 'Rebuilding, "again"' },
+  2: { team: 'Bears', wins: 12, streak: 3 },
+});
+
+// team,wins,note,streak
+// Tigers,0,"Rebuilding, ""again""",
+// Bears,12,,3
+
+```
+
+
+
 ### `download(data)`
 
 Takes a nested object and triggers a browser download of a generated `.csv` file.
@@ -257,6 +392,154 @@ console.log(Dates.isSameDay(d1, d2)); // true
 
 ```
 
+### Period boundaries
+
+`getStartOfDay` / `getEndOfDay`, `getStartOfMonth` / `getEndOfMonth`, and `getDaysInMonth`.
+
+```ts
+Dates.getEndOfDay('2026-03-15');    // 2026-03-15 23:59:59.999 local
+Dates.getEndOfMonth('2026-02-10');  // 2026-02-28 23:59:59.999
+Dates.getDaysInMonth('2024-02-01'); // 29
+```
+
+### `eachDayOfInterval(start, end)`
+
+Every day from `start` to `end` inclusive, as local midnights. Steps by calendar day, so it stays correct across DST boundaries.
+
+* **Example: Building a month grid**
+Pair with `getStartOfGrid` / `getEndOfGrid` to get whole Sunday-to-Saturday weeks covering the month.
+```ts
+const cells = Dates.eachDayOfInterval(
+  Dates.getStartOfGrid('2026-03-01'),
+  Dates.getEndOfGrid('2026-03-01'),
+);
+// cells.length is always a multiple of 7
+```
+
+### `isBetween(date, start, end, inclusive?)`
+
+Whether a date falls between two others. The bounds may be given in either order, and comparison is by exact instant — pair with `getStartOfDay` / `getEndOfDay` for a whole-day range.
+
+```ts
+Dates.isBetween('2026-03-05', '2026-03-01', '2026-03-10'); // true
+```
+
+---
+
+## Tasker
+
+Wrappers for controlling how and when other functions run.
+
+### `debounce(fn, wait, leading?)`
+
+Delays a function until it has stopped being called for `wait` ms. The returned function carries `cancel()`, `flush()`, and `pending()`.
+
+* **Example: Search-as-you-type**
+```ts
+import { Tasker } from '@esmalley/ts-utils';
+
+const search = Tasker.debounce((term: string) => runQuery(term), 300);
+
+search('gon');
+search('gonz');   // only this one runs, 300ms after the last keystroke
+```
+
+### `throttle(fn, wait)`
+
+Allows a function to run at most once per `wait` ms. The first call runs immediately; a call made during the cooling-off period runs when it ends, carrying the most recent arguments.
+
+```ts
+window.addEventListener('scroll', Tasker.throttle(() => measure(), 100));
+```
+
+### `retry(fn, options?)`
+
+Calls an async function until it succeeds, backing off between attempts. Rethrows the final error once attempts are exhausted.
+
+```ts
+const data = await Tasker.retry(() => fetchRatings(), {
+  attempts: 5,
+  delay: 500,
+  onRetry: (error, attempt) => console.warn(`retry ${attempt}`, error),
+});
+```
+
+### `backoff(attempt, options?)`
+
+The delay before a given retry attempt, growing exponentially and capped at `maxDelay`. Pass `jitter` to randomize across `0..computed` and avoid a thundering herd.
+
+```ts
+Tasker.backoff(0); // 1000
+Tasker.backoff(3); // 8000
+```
+
+### `memoize(fn, keyFn?)` / `once(fn)`
+
+Caches results by arguments, or restricts a function to a single call. The memoized function carries `clear()` and `size()`.
+
+```ts
+const ratingFor = Tasker.memoize((teamId: number) => compute(teamId));
+const init = Tasker.once(() => connect());
+```
+
+### `sleep(ms)`
+
+Resolves after a delay.
+
+```ts
+await Tasker.sleep(250);
+```
+
+---
+
+## Numbers
+
+Human-readable number formatting.
+
+### `formatOrdinal(n)` / `ordinalSuffix(n)`
+
+A number with its English ordinal suffix, or just the suffix.
+
+```ts
+Numbers.formatOrdinal(1);  // '1st'
+Numbers.formatOrdinal(23); // '23rd'
+Numbers.ordinalSuffix(11); // 'th'
+```
+
+### `format(value, decimals?, locale?)` / `formatSigned(value, decimals?)`
+
+Locale grouping separators, optionally with an explicit sign for deltas such as a change in rank.
+
+```ts
+Numbers.format(1234567);      // '1,234,567'
+Numbers.format(1234.5, 2);    // '1,234.50'
+Numbers.formatSigned(3);      // '+3'
+```
+
+### `formatCompact(value, decimals?)`
+
+A large number shortened with a magnitude suffix. Implemented directly rather than through Intl's compact notation, whose exact output varies with the runtime's ICU data.
+
+```ts
+Numbers.formatCompact(1234);      // '1.2K'
+Numbers.formatCompact(2_000_000); // '2M'
+```
+
+### `formatPercent(value, decimals?, fromRatio?)`
+
+A ratio as a percentage. Pass `false` for `fromRatio` if the input is already scaled.
+
+```ts
+Numbers.formatPercent(0.1234); // '12.3%'
+```
+
+### `formatDuration(ms, parts?)` / `formatBytes(bytes, decimals?)`
+
+```ts
+Numbers.formatDuration(3_725_000);    // '1h 2m'
+Numbers.formatDuration(3_725_000, 3); // '1h 2m 5s'
+Numbers.formatBytes(1536);            // '1.5 KB'
+```
 
 ---
 
@@ -293,6 +576,29 @@ Objector.extender(defaults, userConfig);
 
 ```
 
+### `deepEqual(a, b)`
+
+Structurally compares two values — the counterpart to `deepClone`. Handles the same shapes (Date, RegExp, Map, Set, arrays, plain objects, symbol keys) and tolerates circular references.
+
+`NaN` equals `NaN` and `+0` does not equal `-0`, matching `Object.is` rather than `===`. Objects must share a prototype to be considered equal.
+
+* **Example 1: Change detection**
+```ts
+if (!Objector.deepEqual(previousFilters, nextFilters)) {
+  refetch();
+}
+
+```
+
+* **Example 2: Verifying a clone**
+```ts
+const copy = Objector.deepClone(state);
+Objector.deepEqual(state, copy); // true
+copy.user.id = 2;
+Objector.deepEqual(state, copy); // false
+
+```
+
 
 
 ---
@@ -362,6 +668,14 @@ const shadow = Style.getShadow(4);
 
 String manipulation and linguistic utility functions.
 
+### `toKebabCase(str)`
+
+Converts camelCase or PascalCase to kebab-case. Used internally to turn CSS-in-JS property names into real CSS properties, but general purpose.
+
+```ts
+Textor.toKebabCase('backgroundColor'); // 'background-color'
+```
+
 ### `levenshtein(a, b)`
 
 Calculates the Levenshtein distance between two strings. This is a string metric for measuring the difference between two sequences (the minimum number of single-character edits required to change one word into the other).
@@ -479,27 +793,6 @@ console.log(light.background.main); // #ffffff
 
 
 
-### Palette Accessors (e.g., `getGrey()`, `getAmber()`, etc.)
-
-The class provides access to the standard Material Design color ramps.
-
-* **Example 1: Using Specific Color Weights**
-```ts
-const theme = new Theme('light');
-const greys = theme.getGrey();
-
-const dividerStyle = {
-  backgroundColor: greys[300] // Light grey for dividers
-};
-
-const secondaryText = {
-  color: greys[600] // Medium grey for subtext
-};
-
-```
-
-
-
 ---
 
 ## Toaster
@@ -528,7 +821,7 @@ const unsubscribe = toaster.subscribe((newList) => {
 
 ### `add(message, type)`
 
-Adds a new notification to the stack. Defaults to `'info'` type. Automatically triggers a close request after 4 seconds.
+Adds a new notification to the stack and returns its id, which `requestClose(id)` and `remove(id)` take. Defaults to `'info'` type. Automatically triggers a close request after `Toaster.AUTO_DISMISS_MS` (4 seconds); the exit phase then lasts `Toaster.EXIT_ANIMATION_MS` (500ms). Both are public constants, so a UI can drive its animation from the same numbers.
 
 * **Example 1: Error Handling**
 ```ts
@@ -546,13 +839,20 @@ try {
 ```ts
 toaster.add("You have a new message."); // Defaults to 'info'
 
+// Hold on to the id to dismiss a toast before it auto-dismisses.
+const id = toaster.add("Uploading...");
+await upload();
+toaster.remove(id);
+
 ```
 
 
 
 ### `requestClose(id)`
 
-Starts the "exit" phase for a toast. It marks the toast as `exiting: true`, allowing the UI to play a fade-out animation before the toast is fully removed 500ms later.
+Starts the "exit" phase for a toast. It marks the toast as `exiting: true` so the UI can play a fade-out animation.
+
+Your UI is expected to call `remove(id)` once that animation ends — that is the normal path, and it is what gets the toast off the list. As a safety net, the toast is also dropped 500ms later in case the animation callback never arrives (a backgrounded tab, an unmount mid-animation, reduced-motion settings). That late removal is silent when the UI already handled it, so it costs no extra render.
 
 * **Example 1: Manual Dismiss Button**
 ```ts
@@ -563,11 +863,24 @@ const handleClose = (toastId) => {
 
 ```
 
+* **Example 2: Removing when the animation ends**
+```tsx
+<div
+  className={isExiting ? 'toast-fade-out' : 'toast-slide-up'}
+  onAnimationEnd={() => {
+    if (isExiting) {
+      toaster.remove(toast.id);
+    }
+  }}
+>
+
+```
+
 
 
 ### `remove(id)`
 
-Immediately removes a toast from the list without waiting for an animation or timeout.
+Immediately removes a toast from the list without waiting for an animation or timeout. Removing an id that is not present is a no-op and notifies nobody.
 
 * **Example 1: Force Clearing a specific alert**
 ```ts
@@ -610,6 +923,104 @@ bus.addEventListener('data', (payload) => console.log(payload));
 
 ```
 
+---
+
+## UuidService
+
+A singleton that generates UUIDv7 identifiers — time-ordered, so they sort chronologically and index well as a primary key.
+
+### `generateUUIDv7Bytes()`
+
+Returns the raw 16 bytes. Monotonic within a millisecond via a 12-bit counter, and holds steady if the wall clock jumps backwards.
+
+```ts
+import { uuidService } from '@esmalley/ts-utils';
+
+const bytes = uuidService.generateUUIDv7Bytes();
+const id = uuidService.binToUuid(bytes);
+// '01997e4c-1f3a-7b21-9c04-5e6f70818293'
+```
+
+### `binToUuid(buffer)` / `uuidToBin(uuid)`
+
+Converts between the 16-byte form and the canonical dashed string. Storing the binary form in a `BINARY(16)` column costs 16 bytes instead of 36.
+
+```ts
+const bin = uuidService.uuidToBin(id);
+uuidService.binToUuid(bin) === id; // true
+```
+
+### `isValid(uuid)`
+
+Whether a string is a well-formed UUID, dashed or bare.
+
+```ts
+uuidService.isValid(id);          // true
+uuidService.isValid('not-a-id');  // false
+```
+
+---
+
+# Testing
+
+Unit tests run on Jest in ESM mode:
+
+```bash
+npm test                      # type-checks, then runs every suite
+npm test -- Arithmetic        # one file
+npm run typecheck             # tsc --noEmit on its own
+```
+
+`npm test` runs `typecheck` first via `pretest`. That matters because ts-jest is configured with `isolatedModules: true`, which makes it transpile tests without type-checking them — so Jest alone will happily run a test file full of type errors. `tsc --noEmit` covers `src`, `tests` and everything else the root `tsconfig.json` includes, while `npm run build` stays scoped to `src`.
+
+## Benchmarks
+
+Correctness is covered by Jest; execution time is covered by a separate benchmark suite built on [tinybench](https://github.com/tinylibs/tinybench). Benchmarks live in `bench/*.bench.js` and read like tests:
+
+```js
+import { Arithmetic } from '../dist/esm/index.js';
+import { suite, bench } from './harness.js';
+
+const ratings = Array.from({ length: 10_000 }, () => Math.random() * 2000);
+
+suite('Arithmetic (10k values)', () => {
+  bench('mean()', () => Arithmetic.mean(ratings));
+  bench('median()', () => Arithmetic.median(ratings));
+});
+```
+
+They import from `dist/esm`, not `src`, so they measure what consumers actually install. Build first:
+
+```bash
+npm run build
+npm run bench                 # run everything
+npm run bench -- Arithmetic   # filter by suite or bench name
+npm run bench -- --time=1000  # sample each bench for 1000ms (default 500)
+```
+
+### Catching regressions
+
+Record the current numbers, make a change, then re-run to see the difference:
+
+```bash
+npm run bench:save            # writes bench/baseline.json
+# ...optimize something...
+npm run bench                 # each row gains a delta column
+```
+
+```
+Arithmetic (10k values)
+  mean()         12,001 ops/s    +-0.9%    84.59 us    1,419 runs      same
+  median()          471 ops/s    +-4.1%     2.17 ms       64 runs    +18.2%
+```
+
+Deltas are throughput, so a positive number is faster. Anything under 5% reports as `same`, because run-to-run noise on a working machine swamps it. The baseline is machine-specific and git-ignored — compare against your own hardware, never someone else's.
+
+Two annotations flag numbers you should not trust:
+
+* **`unstable`** — the margin of error exceeded 5%. Re-run with a longer `--time`, or close whatever else is busy.
+* **`faster than the clock` / `at timer resolution`** — the work finished faster than the platform timer can resolve, so the figure is approximate. Benchmark a realistic batch instead of a single call.
+