@catstral/levy-utils 1.0.0 → 2.0.0

package/README.md

@@ -1,56 +1,131 @@
-# levy-utils
-levy-utils is a lightweight, dependency-light library of common JS/TS utility functions covering everyday needs: array/object manipulation, type checks, async helpers, and value conversion.
+# @catstral/levy-utils
+@catstral/levy-utils is a lightweight, dependency-light library of common JS/TS utility functions covering everyday needs: array/object manipulation, type checks, async helpers, and value conversion.
 
 ## How to install
 Install with a package manager
 ```bash
 # using npm
-npm install levy-utils
+npm install @catstral/levy-utils
 
 # using yarn
-yarn add levy-utils
+yarn add @catstral/levy-utils
 
 # using pnpm
-pnpm add levy-utils
+pnpm add @catstral/levy-utils
 
 # using bun
-bun add levy-utils
+bun add @catstral/levy-utils
 ```
 
 ## Usage
 ```ts
-import { range, sift, toggle } from "levy-utils";
+import { range, sift, toggle } from "@catstral/levy-utils";
 ```
 
 ## Utils
 A list of all the utilities supported:
 - [Array utilities](#array-utilities)
   - [cluster](#clusteritems-size)
+  - [concat](#concatvalues)
   - [counting](#countinglist-identity)
+  - [filter](#filterlist-predicate)
+  - [filterMap](#filtermaplist-filter-mapper)
+  - [first](#firstlist-fallback)
   - [fork](#forklist-condition)
+  - [group](#grouplist-identity)
+  - [hasItems](#hasitemslist)
+  - [last](#lastlist-fallback)
   - [list](#liststartorlength-end-options)
-  - [select](#selectlist-filter-mapper)
+  - [map](#maplist-callback)
+  - [max](#maxlist-mapper-options)
+  - [min](#minlist-mapper-options)
+  - [overflow](#overflowlist-clamplength)
+  - [reduce](#reducelist-initial-callback-options)
+  - [select](#selectlist-callback)
   - [sift](#siftlist)
+  - [sum](#sumlist-mapper)
   - [toggle](#togglelist-itemtotoggle-options)
 - [Callback utilities](#callback-utilities)
   - [chain](#chaincallbacks)
+  - [compose](#composecallbacks)
   - [defer](#defercallback)
+  - [noop](#noop)
+  - [pipe](#pipevalue-callback)
+  - [preset](#presetcallback-parameters)
   - [retry](#retrycallback-options)
+  - [task](#taskcallback)
 - [Miscellaneous utilities](#miscellaneous-utilities)
   - [compute / isComputation](#computevalue-args--iscomputationvalue)
+  - [identity](#identityvalue)
   - [isEmpty](#isemptyvalue)
+  - [isNull](#isnullvalue)
+  - [isNullish](#isnullishvalue)
   - [isPrimitive](#isprimitivevalue)
+  - [isPromise](#ispromisevalue)
+  - [isPromiseLike](#ispromiselikevalue)
+  - [isUndefined](#isundefinedvalue)
+  - [match](#matchvalue-clause-fallback)
+  - [Range (class)](#rangerangestring)
+    - [static from](#static-fromrange)
+    - [details (getter)](#details-getter)
+      - [start (getter)](#start-getter)
+      - [end (getter)](#end-getter)
+      - [step (getter)](#step-getter)
+      - [mapper (getter)](#mapper-getter)
+    - [start](#startstart)
+    - [end](#endend)
+    - [step](#stepstep)
+    - [map](#mapmapper)
+    - [includes](#includesvalue)
+    - [excludes](#excludesvalue)
+    - [toArray](#toarray)
+    - [clone](#clone)
   - [range](#rangestartorlength-end-options)
+  - [raise](#raisevalue)
+  - [readOnly / isReadOnly](#readonlyvalue-deepfreeze--isreadonlyvalue)
+  - [safe](#safecallback)
   - [sleep](#sleepdelay)
+  - [timeout / isTimeoutError](#timeoutvalue-delayms-options--istimeouterrorvalue)
+  - [unwrap](#unwrapoption-fallback)
+  - [values](#valuestarget)
 - [Number utilities](#number-utilities)
+  - [Math utilities](#math-utilities)
+    - [isPrime](#isPrimevalue)
+    - [mod](#moddividend-divisor)
+  - [clamp](#clampmin-value-max)
+  - [isDecimal](#isdecimalvalue)
+  - [isEven](#isevenvalue)
+  - [isInteger](#isintegervalue)
+  - [isNegative](#isnegativevalue)
+  - [isOdd](#isoddvalue)
+  - [isPositive](#ispositivevalue)
+  - [negative](#negativevalue)
+  - [positive](#positivevalue)
+  - [sign](#signvalue)
   - [toFloat](#tofloatvalue-fallback)
   - [toInt](#tointvalue-fallback)
+  - [trunc](#truncvalue-fractiondigits)
 - [Object utilities](#object-utilities)
   - [entries](#entriesvalue)
+  - [extend](#extendvalue-other)
   - [isObject](#isobjectitem)
   - [keys](#keysvalue)
   - [omit](#omitobject-keys)
   - [pick](#pickobject-keys)
+- [Randomization utilities](#randomization-utilities)
+  - [UUID utilities](#uuid-utilities)
+    - [uuidMax](#uuidmax)
+    - [uuidNil](#uuidnil)
+    - [uuidV1 / v1](#uuidv1options)
+    - [uuidV4 / v4 / uuid](#uuidv4options)
+    - [uuidV7 / v7](#uuidv7options)
+  - [chance](#chancepercentage)
+  - [draw](#drawlist)
+  - [maybe](#maybe)
+  - [random](#randommin-max)
+  - [scatter](#scatterlist-split-options)
+  - [shuffle](#shufflelist)
+  - [uid](#uidlength-charset)
 - [String utilities](#string-utilities)
   - [Casing utilities](#casing-utilities)
     - [camelCase](#camelcasestr-options)
@@ -80,6 +155,15 @@ cluster([1, 2, 3, 4, 5], 2);
 // [[1, 2], [3, 4], [5]]
 ```
 
+#### `concat(...values)`
+Concatenates values and arrays into a new array.
+
+```ts
+concat(1, [2, 3], 4);
+// Expected output:
+// [1, 2, 3, 4]
+```
+
 #### `counting(list, identity)`
 Reduces a list down to an object of keys (as determined by the `identity` callback) mapped to how many times that key occurred.
 
@@ -93,6 +177,49 @@ counting(["a", "b", "a", "c", "a"], (item) => item);
 // }
 ```
 
+#### `filter(list, predicate)`
+Returns a new list containing the items of a given list that pass a predicate.
+
+If the predicate returns a promise for any item, a promise is returned that resolves once all of them have.
+
+```ts
+filter([1, 2, 3, 4], (n) => n % 2 === 0);
+// Expected output:
+// [2, 4]
+
+await filter([1, 2, 3], async (n) => n > 1);
+// Expected output:
+// [2, 3]
+```
+
+#### `filterMap(list, filter, mapper)`
+Returns a new list of items based on filtered and mapped values of a given list.
+
+```ts
+filterMap(
+    [1, 2, 3, 4],
+    (n) => n % 2 === 0,
+    (n) => n * 10,
+);
+// Expected output:
+// [20, 40]
+```
+
+This utility was formerly called `select`.
+
+#### `first(list, fallback?)`
+Returns the first item of a list, or a fallback if the list is empty.
+
+```ts
+first([1, 2, 3]);
+// Expected output:
+// 1
+
+first([], "none");
+// Expected output:
+// "none"
+```
+
 #### `fork(list, condition)`
 Splits a list into a tuple of two arrays based on a condition: items that pass, and items that don't.
 
@@ -102,6 +229,44 @@ fork([1, 2, 3, 4], (n) => n % 2 === 0);
 // [[2, 4], [1, 3]]
 ```
 
+#### `group(list, identity)`
+Groups the items of a list into an object of keys (as determined by the `identity` callback) mapped to the items with that key.
+
+```ts
+group(["apple", "avocado", "banana"], (item) => item[0]);
+// Expected output:
+// {
+//     a: ["apple", "avocado"],
+//     b: ["banana"],
+// }
+```
+
+#### `hasItems(list)`
+Checks if a list has at least one item, narrowing its type to a non-empty tuple.
+
+```ts
+hasItems([1, 2, 3]);
+// Expected output:
+// true
+
+hasItems([]);
+// Expected output:
+// false
+```
+
+#### `last(list, fallback?)`
+Returns the last item of a list, or a fallback if the list is empty.
+
+```ts
+last([1, 2, 3]);
+// Expected output:
+// 3
+
+last([], "none");
+// Expected output:
+// "none"
+```
+
 ### `list(startOrLength, end?, options?)`
 Returns an array with values to a specified size (inclusive), optionally stepped and/or mapped to another value.
 
@@ -127,9 +292,175 @@ list(0, 3, {
 // ["foo-0", "foo-1", "foo-2", "foo-3"]
 ```
 
-<!-- TODO -->
-#### `select(list, filter, mapper)`
-Returns a new list of items based on filtered and mapped values of a given list.
+options:
+- `step` - The steps used to generate the array.
+- `valueMapper` - A mapper function to map a step to a value.
+
+#### `map(list, callback)`
+Returns a new list of items based on mapped values of a given list.
+
+If the callback returns a promise for any item, a promise is returned that resolves once all of them have.
+
+```ts
+map([1, 2, 3], (n) => n * 2);
+// Expected output:
+// [2, 4, 6]
+
+await map([1, 2, 3], async (n) => n + 1);
+// Expected output:
+// [2, 3, 4]
+```
+
+#### `max(list, mapper?, options?)`
+Returns the largest item from a list.
+
+```ts
+max([1, 2, 3]);
+// Expected output:
+// 3
+
+max(
+    [
+        {
+            name: "Bob"
+            weight: 54
+        },
+        {
+            name: "Paul"
+            weight: 87
+        },
+        {
+            name: "Jane"
+            weight: 63
+        },
+    ],
+    (item) => item.weight,
+);
+// Expected output:
+// {
+//     name: "Paul",
+//     weight: 87,
+// }
+```
+
+#### `min(list, mapper?, options?)`
+Returns the smallest item from a list.
+
+```ts
+min([1, 2, 3]);
+// Expected output:
+// 1
+
+min(
+    [
+        {
+            name: "Bob"
+            weight: 54
+        },
+        {
+            name: "Paul"
+            weight: 87
+        },
+        {
+            name: "Jane"
+            weight: 63
+        },
+    ],
+    (item) => item.weight,
+);
+// Expected output:
+// {
+//     name: "Bob",
+//     weight: 54,
+// }
+```
+
+#### `overflow(list, clampLength)`
+Splits a list into a tuple of two arrays: the first `clampLength` items, and the rest of the items.
+
+Throws an `OverflowUtilError` if the clamp length is negative or the given list is not an array.
+
+```ts
+overflow([1, 2, 3, 4, 5], 3);
+// Expected output:
+// [[1, 2, 3], [4, 5]]
+```
+
+#### `reduce(list, initial, callback, options?)`
+Reduces all items of a list down to an accumulated result.
+
+```ts
+reduce([1, 2, 3], 0, (acc, n) => acc + n);
+// Expected output:
+// 6
+
+reduce(["a", "b", "c"], "", (acc, letter) => acc + letter, {
+    direction: "DESCENDING",
+});
+// Expected output:
+// "cba"
+
+reduce([1, 2, 3], 0, (acc, n) => acc + n, {
+    result: (total) => `Total: ${total}`,
+});
+// Expected output:
+// "Total: 6"
+```
+
+Options:
+- `direction` - `"ASCENDING"` or `"DESCENDING"`, determines the order the list is reduced in (default `"ASCENDING"`)
+- `result` - transforms the final accumulator into the returned result
+
+#### `select(list, callback)`
+Returns a new list built by deciding, per item, what should end up in the result. The callback receives a context object and must return one of its actions.
+
+```ts
+select(
+    [1, 2, 3, 4, 5, 6, 7, 8, 9, 10],
+    ({ item, keep, discard, filter }) => {
+        if (item < 3) {
+            return keep();
+        }
+    
+        if (item > 8) {
+            return discard();
+        }
+    
+        return filter(item % 2 === 0);
+    },
+);
+// Expected output:
+// [1, 2, 4, 6, 8]
+
+select<number | string[] | null, string>(
+    [1, ["2", "3", "4"], null, ["7", "8", "9"], 10],
+    ({ item, map, flat, spread }) => {
+        if (typeof item === "number") {
+            return map(item.toString());
+        }
+
+        if (Array.isArray(item)) {
+            return flat(item);
+        }
+
+        return spread("5", "6");
+    },
+);
+// Expected output:
+// ["1", "2", "3", "4", "5", "6", "7", "8", "9", "10"]
+```
+
+Available actions:
+- `keep()` - keeps the current item
+- `discard()` - removes the current item
+- `filter(keep)` - keeps or removes the current item based on a boolean
+- `map(value)` - replaces the current item with a value
+- `flat(values)` - replaces the current item with every value of a list
+- `spread(...values)` - replaces the current item with every given value
+
+Throws a `SelectUtilError` if the callback returns an invalid action.
+
+This utility was reworked, it's old behaviour has moved to the `filterMap` utility.
 
 #### `sift(list)`
 Filters all falsy values out of a list.
@@ -148,6 +479,27 @@ sift([1, 0, 2, null, 3, undefined, false]);
 // [1, 2, 3]
 ```
 
+#### `sum(list, mapper?)`
+Sums a list of items into a total number.
+
+```ts
+sum([1, 2, 3]);
+// Expected output:
+// 6
+
+sum([1, 2, 3], (n) => n * 2);
+// Expected output:
+// 12
+
+sum([false, true, "", "Hello", null, {}, undefined, []]);
+// Expected output:
+// 4
+
+sum(["3", "4", "5"], (item) => Number.parseInt(item, 10));
+// Expected output:
+// 12
+```
+
 #### `toggle(list, itemToToggle, options?)`
 Toggles a value in an array: removes it if present, adds it if not.
 
@@ -200,6 +552,24 @@ chain(() => true, (value: boolean) => value ? "true" : "false");
 // "true"
 ```
 
+#### `compose(...callbacks)`
+Turns many callbacks into a single re-usable callback.
+
+```ts
+const fn = compose(
+    (n: number) => n + 1,
+    (n: number) => n * 2,
+);
+
+fn(2);
+// Expected output:
+// 6
+
+fn(5);
+// Expected output:
+// 12
+```
+
 #### `defer(callback)`
 Defers a callback to the next execution cycle.
 
@@ -207,6 +577,50 @@ Defers a callback to the next execution cycle.
 defer(() => console.log("runs after the current call stack clears"));
 ```
 
+#### `noop()`
+No operation, this function does nothing. Useful for placeholder code.
+
+```ts
+noop();
+// Expected output:
+// undefined
+```
+
+#### `pipe(value, callback)`
+Pipes a value into a callback and returns its result.
+
+```ts
+pipe(5, (n) => n * 2);
+// Expected output:
+// 10
+
+pipe("Foo", (value) => `${value} Bar`);
+// Expected output:
+// "Foo Bar"
+```
+
+#### `preset(callback, parameters)`
+Presets the parameters of a callback with a callback that computes its arguments.
+
+```ts
+const fn = preset(
+    Number.parseInt,
+    (value: string): [string, number] => [value, 10],
+);
+
+fn("10");
+// Expected output:
+// 10
+
+fn("3.2");
+// Expected output:
+// 3
+
+preset(Number.parseInt, ["0", 10])();
+// Expected output:
+// 0
+```
+
 #### `retry(callback, options?)`
 Retries an async (or sync) callback until it succeeds or the maximum number of attempts is reached.
 
@@ -225,6 +639,19 @@ Options:
 - `backoff` - whether to double the delay after each retry (default `false`)
 - `onRetry` - callback invoked with the error and attempt number on each failed attempt
 
+#### `task(callback?)`
+Executes the given callback in asynchronous context.
+
+```ts
+// This yields execution to the microtask queue.
+await task();
+
+// A task that has a seperate asynchronous flow 
+task(async () => {
+    await doSomething();
+});
+```
+
 <!-- !SECTION -->
 <!-- SECTION: Misc utils -->
 
@@ -242,6 +669,23 @@ compute((a: number, b: number) => a + b, 2, 3);
 // 5
 ```
 
+#### `identity(value)`
+Returns the given value as is, with its type inferred as narrowly as possible (as a `const` generic).
+
+```ts
+identity(5);
+// Expected output:
+// 5
+
+identity({
+    a: 1,
+});
+// Expected output:
+// {
+//     a: 1,
+// }
+```
+
 #### `isEmpty(value)`
 Checks if a value is considered empty.
 
@@ -276,91 +720,693 @@ isEmpty({
 // false (the key exists)
 ```
 
-#### `isPrimitive(value)`
-Checks if a value is a primitive: `string`, `number`, `boolean`, `symbol`, `null`, or `undefined`.
+#### `isNull(value)`
+Checks if a value is `null`.
 
 ```ts
-isPrimitive("foo");
+isNull(null);
 // Expected output:
 // true
 
-isPrimitive({});
+isNull(undefined);
 // Expected output:
 // false
 ```
 
-#### `range(startOrLength, end?, options?)`
-Returns a generator that yields values over a specified range (inclusive), optionally stepped and/or mapped to another value.
+#### `isNullish(value)`
+Checks if a value is nullish: `null` or `undefined`.
 
 ```ts
-for (const value of range(3)) {
-    console.log(value);
-}
+isNullish(null);
 // Expected output:
-// logs 0, 1, 2, 3
+// true
 
-for (const value of range(0, 3)) {
-    console.log(value);
-}
+isNullish(undefined);
 // Expected output:
-// logs 0, 1, 2, 3
+// true
 
-for (const value of range(0, 6, {
-    step: 2,
-})) {
-    console.log(value);
-}
+isNullish(0);
 // Expected output:
-// logs 0, 2, 4, 6
+// false
+```
 
-for (const value of range(0, 3, {
-    valueMapper: (step) => `foo-${step}`,
-})) {
-    console.log(value);
-}
+#### `isPrimitive(value)`
+Checks if a value is a primitive: `string`, `number`, `boolean`, `symbol`, `null`, or `undefined`.
+
+```ts
+isPrimitive("foo");
 // Expected output:
-// logs "foo-0", "foo-1", "foo-2", "foo-3"
+// true
+
+isPrimitive({});
+// Expected output:
+// false
 ```
 
-#### `sleep(delay)`
-Returns a promise that resolves after the specified delay (in milliseconds).
+#### `isPromise(value)`
+Checks if a value is a `Promise` (an instance of `Promise`).
 
 ```ts
-await sleep(1000);
+isPromise(Promise.resolve(1));
 // Expected output:
-// waits 1 second
-```
+// true
 
-<!-- !SECTION -->
-<!-- SECTION: Number utils -->
+isPromise({ 
+    then: () => {},
+});
+// Expected output:
+// false
+```
 
-### Number utilities
-#### `toFloat(value, fallback?)`
-Converts a value to a float, falling back to a default (`0` by default) if the conversion fails or the value isn't a supported type.
+#### `isPromiseLike(value)`
+Checks if a value is promise-like: an object with a `then` function.
 
 ```ts
-toFloat("3.14");
+isPromiseLike(Promise.resolve(1));
 // Expected output:
-// 3.14
+// true
 
-toFloat(true);
+isPromiseLike({
+    then: () => {},
+});
 // Expected output:
-// 1
+// true
 
-toFloat("not a number", -1);
+isPromiseLike({});
 // Expected output:
-// -1
+// false
 ```
 
-#### `toInt(value, fallback?)`
-Converts a value to an integer, falling back to a default (`0` by default) if the conversion fails or the value isn't a supported type.
+#### `isUndefined(value)`
+Checks if a value is `undefined`.
 
 ```ts
-toInt("42");
+isUndefined(undefined);
 // Expected output:
-// 42
+// true
 
-toInt(true);
+isUndefined(null);
+// Expected output:
+// false
+```
+
+#### `match(value, clause, fallback?)`
+Matches a value to a clause that return a value
+and returns a fallback if none of the cases match.
+
+```ts
+const fn = (value: string) => {
+    return match(
+        value,
+        {
+            A: 1,
+            B: 2,
+        },
+        -1,
+    );
+};
+
+fn("A");
+// Expected output:
+// 1
+
+fn("B");
+// Expected output:
+// 2
+
+fn("C");
+// Expected output:
+// -1
+```
+
+#### `Range(rangeString?)`
+> The constructor of this has an overload:  
+> `Range(details?)`
+> 
+> Details:
+> - `start` - The start value of the range (optional).
+> - `inclusiveStart` - If the range should consider the `start` to be inclusive (optional).
+> - `end` - The end value of the range (optional)
+> - `inclusiveEnd` - If the range should consider the `end` to be inclusive (optional).
+> - `step` - The step value of the range (optional).
+> - `mapper` - The mapper of the range, this maps a step to a value (optional).
+
+This is a class representing a range value, it is an iterable and generates values based on a start and end value (if specified).
+
+If no start of end value is specified the range will work as expected with methods, but trying to iterate over it will throw an error.
+
+It can also be given a `step` and a `mapper` to define how it should be generating a value.
+
+If the argument given is a string, then it is expected to have that string match the following definition:
+`S?>?..=?E?` where:
+* `S` - The start of the range (optional)
+* `E` - The end of the range (optional)
+* `>` - If the start value is exclusive of this range (optional)
+* `=` - If the end value is inclusive of this range (optional)
+
+Here is a simple table explaining the different types of range strings:
+| Syntax             | Range           | Is iterable |
+| -------------------| --------------- | ----------- |
+| `[start]..[end]`   | start ≤ x < end | Yes         |
+| `[start]>..[end]`  | start < x < end | Yes         |
+| `[start]..=[end]`  | start ≤ x ≤ end | Yes         |
+| `[start]>..=[end]` | start < x ≤ end | Yes         |
+| `..`               | -               | No          |
+| `[start]..`        | start ≤ x       | No          |
+| `[start]>..`       | start < x       | No          |
+| `..[end]`          | x < end         | No          |
+| `..=[end]`         | x ≤ end         | No          |
+
+If a value is not iterable, that means it will throw an error on attempting to iterate the range.  
+A full range is a range without bounds, this mostly exists for completeness and would effect how certain methods of the range work, see the methods for more details on how they are effected.
+
+> This class can also be gotten from the [range](#rangestartorlength-end-options) utility function.
+
+##### `static from(range)`
+Creates a new range with the details from the specified range.
+
+> This does the same as [Range.clone](#clone)
+
+##### `details (getter)`
+Gets the internal details of the Range.
+
+> This is a getter, no value can be set here.
+
+###### `start (getter)`
+Gets the start value of range.
+
+> This is a getter, no value can be set here.
+
+###### `end (getter)`
+Gets the end value of range.
+
+> This is a getter, no value can be set here.
+
+###### `step (getter)`
+Gets the step value of range.
+
+> This is a getter, no value can be set here.
+
+###### `mapper (getter)`
+Gets the mapper value of range.
+
+> This is a getter, no value can be set here.
+
+##### `start(start?)`
+Creates a new Range with a given start value set.
+
+##### `inclusiveStart(inclusiveStart)`
+Creates a new Range with a given inclusive start value set.
+
+##### `end(end?)`
+Creates a new Range with a given end value set.
+
+##### `inclusiveEnd(inclusiveEnd)`
+Creates a new Range with a given inclusive  end value set.
+
+##### `step(step?)`
+Creates a new Range with a given step value set.
+
+##### `map(mapper)`
+Creates a new Range with a given mapper set.
+
+##### `includes(value)`
+Returns a boolean to signal if the given value is included in the range.
+
+> Notes:
+> - If the range is a full range, then this will **always** return true.
+> - `NaN` will **always** return false (unless the range is a full range).
+
+##### `excludes(value)`
+Returns a boolean to signal if the given value is excluded from the range.
+
+> Notes:
+> - If the range is a full range, then this will **always** return false.
+> - `NaN` will **always** return false.
+
+##### `toArray()`
+Returns an array based on the values of the range.
+
+##### `clone()`
+Returns a new Range with same details.
+
+> This does the same as [static Range.from](#static-fromrange)
+
+#### `range(startOrLength, end?, options?)`
+Returns a [Range](#rangerangestring) that yields values over a specified range (inclusive), optionally stepped and/or mapped to another value.
+
+```ts
+for (const value of range(3)) {
+    console.log(value);
+}
+// Expected output:
+// logs 0, 1, 2, 3
+
+for (const value of range(0, 3)) {
+    console.log(value);
+}
+// Expected output:
+// logs 0, 1, 2, 3
+
+for (const value of range(0, 6, {
+    step: 2,
+})) {
+    console.log(value);
+}
+// Expected output:
+// logs 0, 2, 4, 6
+
+for (const value of range(0, 3, {
+    valueMapper: (step) => `foo-${step}`,
+})) {
+    console.log(value);
+}
+// Expected output:
+// logs "foo-0", "foo-1", "foo-2", "foo-3"
+
+for (const value of range(0, 3, {
+    inclusiveStart: false,
+})) {
+    console.log(value);
+}
+// Expected output:
+// logs 1, 2, 3
+
+for (const value of range(0, 3, {
+    inclusiveEnd: false,
+})) {
+    console.log(value);
+}
+// Expected output:
+// logs 0, 1, 2
+```
+
+options:
+- `step` - The steps used to generate the array.
+- `valueMapper` - A mapper function to map a step to a value.
+- `inclusiveStart` - Wether the start value is considered inclusive.
+- `inclusiveEnd` - Wether the end value is considered inclusive.
+
+> NOTE: `inclusiveEnd` default value here differs from the `inclusiveEnd` value set by [`Range`](#rangerangestring), this is for backwards compatibility.
+
+#### `raise(value)`
+Throws the given value, never returns.
+
+- A string is wrapped in an `Error`.
+- A function is called without arguments and its result is thrown.
+- Any other value is thrown as is.
+
+This is useful for throwing in expression positions, such as a fallback.
+
+```ts
+raise("Something went wrong");
+// Expected to throw:
+// Error("Something went wrong")
+
+raise(() => new RangeError("Out of range"));
+// Expected to throw:
+// RangeError("Out of range")
+```
+
+#### `readOnly(value, deepFreeze?)` / `isReadOnly(value)`
+`readOnly` returns a read-only copy of an object, array, map, or set.
+
+`isReadOnly` checks if a value is frozen.
+
+```ts
+const original = {
+    a: 1,
+    nested: {
+        b: 2
+    }
+};
+const shallow = readOnly(original);
+const deep = readOnly(original, true);
+
+isReadOnly(shallow);
+// Expected output:
+// true
+
+shallow.nested === original.nested;
+// Expected output:
+// true (nested values are shared and still mutable)
+
+deep.nested === original.nested;
+// Expected output:
+// false (nested values are cloned and frozen)
+
+isReadOnly(original);
+// Expected output:
+// false
+```
+
+#### `safe(callback)`
+Executes the given callback and returns an option of the result.
+
+```ts
+safe(() => {
+    return "Hello world";
+});
+// Expected output:
+// {
+//     success: true,
+//     value: "Hello world",
+// }
+
+safe(() => {  
+    throw new Error("Goodbye world");
+});
+// Expected output:
+// {
+//     success: false,
+//     error: Error("Goodbye world"),
+// }
+```
+
+#### `sleep(delay)`
+Returns a promise that resolves after the specified delay (in milliseconds).
+
+```ts
+await sleep(1000);
+// Expected output:
+// waits 1 second
+```
+
+#### `timeout(value, delayMs, options?)` / `isTimeoutError(value)`
+Wraps a promise (or a callback that returns one) into a promise that rejects with a `TimeoutError` if it hasn't settled after the given delay (in milliseconds). If the promise settles first, its result (or error) is passed through.
+
+When given a callback, it receives an `AbortSignal` which is aborted when the delay elapses, so the underlying operation can be cancelled.
+
+`isTimeoutError` checks if a value is a `TimeoutError`.
+
+```ts
+await timeout(sleep(100), 1000);
+// Expected output:
+// resolves after 100ms
+
+await timeout(sleep(2000), 1000);
+// Expected to throw:
+// TimeoutError("The operation was timed out after 1000ms")
+
+await timeout(
+    (signal) => fetch("https://example.com", { 
+        signal,
+    }),
+    1000,
+);
+// Expected output:
+// the response, or a rejection (and an aborted request) if it takes longer than 1 second
+
+try {
+    await timeout(sleep(2000), 1000);
+} catch (error) {
+    isTimeoutError(error);
+    // Expected output:
+    // true
+}
+```
+
+Options:
+- `onTimeout` - a callback invoked with the delay when it elapses. Throwing inside it rejects the promise with the thrown value instead of a `TimeoutError`.
+
+#### `unwrap(option, fallback?)`
+Directly returns the option's value, or throws the option's error.
+An option's error won't be thrown when a fallback is provided.
+
+```ts
+const option = safe(() => {
+    throw new Error("Goodbye world");
+});
+
+unwrap(option);
+// Expected to throw:
+// Error("Goodbye world")
+
+unwrap(option, null);
+// Expected output:
+// null
+```
+
+#### `values(target)`
+Returns an array of values based on the given target.
+
+```ts
+values([1, 2, 3]);
+// Expected output:
+// [1, 2, 3]
+
+values(new Set([4, 5, 6]));
+// Expected output:
+// [4, 5, 6]
+
+values({
+  A: "a",
+  B: "b",
+  C: "c",
+});
+// Expected output:
+// ["a", "b", "c"]
+
+values(new Map([
+  ["D", "d"],
+  ["E", "e"],
+  ["F", "f"],
+]));
+// Expected output:
+// ["d", "e", "f"]
+```
+
+<!-- !SECTION -->
+<!-- SECTION: Number utils -->
+
+### Number utilities
+#### Math utilities
+##### `isPrime(value)`
+Checks if the given value is a prime number.
+
+```ts
+isPrime(11);
+// Expected output:
+// true
+
+isPrime(4);
+// Expected output:
+// false
+
+isPrime(103);
+// Expected output:
+// true
+
+isPrime(-9.2);
+// Expected output:
+// false
+```
+
+##### `mod(dividend, divisor)`
+Returns the modulo of a dividend and a divisor.
+
+```ts
+mod(10, 5);
+// Expected output:
+// 0
+
+mod(-2, 4);
+// Expected output:
+// 2
+
+mod(6, 10);
+// Expected output:
+// 6
+```
+
+#### `clamp(min, value, max)`
+Clamps a number between a minimum and maximum value.
+
+```ts
+clamp(-5, 0, 5);
+// Expected output:
+// 0
+
+clamp(-5, 20, 5);
+// Expected output:
+// 5
+
+clamp(-5, -20, 5);
+// Expected output:
+// -5
+```
+
+#### `isDecimal(value)`
+Checks if the given value is a number with decimals.
+
+```ts
+isDecimal(1.1);
+// Expected output:
+// true
+
+isDecimal(1);
+// Expected output:
+// false
+
+isDecimal(NaN);
+// Expected output:
+// false
+```
+
+#### `isEven(value)`
+Checks if the given value is an even number.
+
+```ts
+isEven(4);
+// Expected output:
+// true
+
+isEven(3);
+// Expected output:
+// false
+
+isEven(0.5);
+// Expected output:
+// false
+```
+
+#### `isInteger(value)`
+Checks if the given value is an integer.
+
+```ts
+isInteger(4);
+// Expected output:
+// true
+
+isInteger(4.5);
+// Expected output:
+// false
+```
+
+#### `isNegative(value)`
+Checks if the given value is a negative number.
+
+```ts
+isNegative(-5);
+// Expected output:
+// true
+
+isNegative(5);
+// Expected output:
+// false
+
+isNegative(-0);
+// Expected output:
+// true
+```
+
+#### `isOdd(value)`
+Checks if the given value is an odd number.
+
+```ts
+isOdd(3);
+// Expected output:
+// true
+
+isOdd(4);
+// Expected output:
+// false
+
+isOdd(0.5);
+// Expected output:
+// false
+```
+
+#### `isPositive(value)`
+Checks if the given value is a positive number.
+
+```ts
+isPositive(5);
+// Expected output:
+// true
+
+isPositive(-5);
+// Expected output:
+// false
+
+isPositive(0);
+// Expected output:
+// true
+```
+
+#### `negative(value)`
+Converts a number into a negative number.
+
+```ts
+negative(5);
+// Expected output:
+// -5
+
+negative(-5);
+// Expected output:
+// -5
+```
+
+#### `positive(value)`
+Converts a number into a positive number.
+
+```ts
+positive(-5);
+// Expected output:
+// 5
+
+positive(5);
+// Expected output:
+// 5
+```
+
+#### `sign(value)`
+Returns the sign of the given number: `1` if positive, `-1` if negative, `0` if zero (`NaN` is converted into zero).
+
+```ts
+sign(5);
+// Expected output:
+// 1
+
+sign(-5);
+// Expected output:
+// -1
+
+sign(0);
+// Expected output:
+// 0
+
+sign(NaN);
+// Expected output:
+// 0
+```
+
+#### `toFloat(value, fallback?)`
+Converts a value to a float, falling back to a default (`0` by default) if the conversion fails or the value isn't a supported type.
+
+```ts
+toFloat("3.14");
+// Expected output:
+// 3.14
+
+toFloat(true);
+// Expected output:
+// 1
+
+toFloat("not a number", -1);
+// Expected output:
+// -1
+```
+
+#### `toInt(value, fallback?)`
+Converts a value to an integer, falling back to a default (`0` by default) if the conversion fails or the value isn't a supported type.
+
+```ts
+toInt("42");
+// Expected output:
+// 42
+
+toInt(true);
 // Expected output:
 // 1
 
@@ -369,6 +1415,23 @@ toInt("not a number", -1);
 // -1
 ```
 
+#### `trunc(value, fractionDigits?)`
+Truncates a number to the specified number of fraction digits.
+
+```ts
+trunc(1.58);
+// Expected output:
+// 1
+
+trunc(1.456, 2);
+// Expected output:
+// 1.45
+
+trunc(1.789, 10)
+// Expected output:
+// 1.789
+```
+
 <!-- !SECTION -->
 <!-- SECTION: object -->
 
@@ -385,6 +1448,25 @@ entries({
 // [["a", 1], ["b", "two"]] (typed as [K, T[K]][])
 ```
 
+#### `extend(value, other)`
+Extends an object with another object.
+
+```ts
+extend(
+    {
+        key: "value",
+    },
+    {
+        foo: "bar",
+    },
+);
+// Expected output:
+// {
+//     key: "value",
+//     foo: "bar",
+// }
+```
+
 #### `isObject(item)`
 Checks if a value is an object, excluding arrays.
 
@@ -474,6 +1556,235 @@ pick(
 // }
 ```
 
+<!-- !SECTION -->
+<!-- SECTION: Random utils -->
+### Randomization utilities
+Almost all utilites that generate someting at random are done with a cryptographically secure pseudorandom number generator (called from now own **CSPRNG**) and utilizes the [`crypto.getRandomValues`](https://developer.mozilla.org/en-US/docs/Web/API/Crypto/getRandomValues) method. If a utility does not use this, it will be mentioned in the description of that utility.
+
+#### UUID utilities
+##### `uuidMax()`
+Returns the max UUID string possible.
+
+```ts
+uuidMax();
+// Expected output:
+// "ffffffff-ffff-ffff-ffff-ffffffffffff"
+```
+
+##### `uuidNil()`
+Returns the nil UUID string.
+
+```ts
+uuidNil();
+// Expected output:
+// "00000000-0000-0000-0000-000000000000"
+```
+
+#### `uuidV1(options?)`
+> This is also aliased to `v1`
+
+Returns a randomly generated UUID V1 string.
+
+```ts
+uuidV1();
+// Possible output:
+// c232ab00-9414-11ec-b3c8-9f68deced846
+
+uuidV1({
+    random: Uint8Array.of(0, 0, 0, 0, 0, 0, 0, 0, 0x33c8 >> 8, 0x33c8 & 0xff, 0x9f, 0x68, 0xde, 0xce, 0xd8, 0x46),
+    milliseconds: 0x17f22e279b0,
+    nanoseconds: 0,
+    clockSequence: 0x33c8,
+    node: Uint8Array.of(0x9f, 0x68, 0xde, 0xce, 0xd8, 0x46),
+})
+// Expected output:
+// c232ab00-9414-11ec-b3c8-9f68deced846
+```
+
+options:
+- `random` - The random bytes used to generate the UUID.
+- `rng` - A function to generate a list of random bytes for UUID generation.
+- `milliseconds` - A number that represents the amount of milliseconds from the EPOCH (number of milliseconds since 01-01-1970).
+- `nanoseconds` - A number that represents tha amount of nanoseconds have elapsed in the specified millisecond (This will always be 0 if not defined, javascript does not measure beyond the millisecond range).
+- `clockSequence` - The current clock sequence used for generation.
+- `node` - A list of random bytes used to complete the UUID V1.
+
+#### `uuidV4(options?)`
+> This is also aliased to `v4` or `uuid`
+
+Returns a randomly generated UUID V4 string.
+
+```ts
+uuidV4();
+// Possible output:
+// 919108f7-52d1-4320-9bac-f847db4148a8
+
+uuidV4({
+    random: Uint8Array.of(0x91, 0x91, 0x08, 0xf7, 0x52, 0xd1, 0x43, 0x20, 0x9b, 0xac, 0xf8, 0x47, 0xdb, 0x41, 0x48, 0xa8),
+})
+// Expected output:
+// 919108f7-52d1-4320-9bac-f847db4148a8
+```
+
+options:
+- `random` - The random bytes used to generate the UUID.
+- `rng` - A function to generate a list of random bytes for UUID generation.
+
+#### `uuidV7(options?)`
+> This is also aliased to `v7`
+
+Returns a randomly generated UUID V7 string.
+
+```ts
+uuidV7();
+// Possible output:
+// 017f22e2-79b0-7cc3-98c4-dc0c0c07398f
+
+uuidV7({
+    random: Uint8Array.of(0x10, 0x7f, 0x22, 0xe2, 0x79, 0xb0, 0x7c, 0xc3, 0x98, 0xc4, 0xdc, 0x0c, 0x0c, 0x07, 0x39, 0x8f),
+    milliseconds: 0x017f22e279b0,
+    sequence: 0xcc363137,
+})
+// Expected output:
+// 017f22e2-79b0-7cc3-98c4-dc0c0c07398f
+```
+
+options:
+- `random` - The random bytes used to generate the UUID.
+- `rng` - A function to generate a list of random bytes for UUID generation.
+- `milliseconds` - A number that represents the amount of milliseconds from the EPOCH (number of milliseconds since 01-01-1970).
+- `sequence` - The current clock sequence used for generation.
+
+#### `chance(percentage)`
+Returns a random boolean based on the specified percentage.  
+The percentage must be a number between 0 and 1. If it is not inside that range it will return a fixed value according to that percentage, so if percentage is more than or equal to 1 it will always return true and if percentage is less than or equal to 0 it will always return false.
+
+```ts
+chance(0.5);
+// Expected output:
+// true | false
+
+chance(1);
+// Expected output:
+// true
+
+chance(0);
+// Expected output:
+// false
+```
+
+#### `draw(list)`
+Returns a random item from a specified list (or `undefined` if the list is empty).
+
+```ts
+draw([0, 1, 2, 3]);
+// Expected output:
+// 0 | 1 | 2 | 3
+
+draw([]);
+// Expected output:
+// undefined
+```
+
+#### `maybe()`
+Returns a random boolean.
+
+```ts
+maybe();
+// Expected output:
+// true | false
+```
+
+#### `random(min?, max?)`
+Returns a random value between a specified minimum and maximum value.
+
+If the minimum and maximum values contradict each other, then this function will return `NaN`.
+
+> NOTE: this utility does **NOT** use [CSPRNG](#randomization-utilities).
+
+```ts
+random();
+// Expected output:
+// n where n > 0 and n < 1
+
+random(10, 20);
+// Expected output:
+// n where n > 10 and n < 20
+
+random(1, 0);
+// Expected output:
+// NaN
+```
+
+#### `scatter(list, split?, options?)`
+Given an array, splits that array into 2 given a hard split and devides the items at random into the 2 given lists.  
+The split must be a number between 0 and 1. If it is not inside that range it will return a fixed sized array according to that split, so if percentage is more than or equal to 1 it will always return `[list, []]` and if percentage is less than or equal to 0 it will always return `[[], list]` (Do note that these are handled as exception cases, meaning if this is the case then the first list will not be in a random order, but preserved order instead).
+
+> NOTE: the first array will be in a random order, while the second array will have the order preserved.
+
+```ts
+scatter([0, 1, 2, 3, 4]);
+// Possible output:
+// [[3, 2, 4], [0, 1]]
+
+scatter([0, 1, 2, 3, 4], 0.6);
+// Possible output:
+// [[3, 2, 4], [0, 1]]
+
+scatter([0, 1, 2, 3, 4], 0.4);
+// Possible output:
+// [[2, 4], [0, 1, 3]]
+
+
+scatter([0, 1, 2, 3, 4], 0.5, {
+    bias: "FLOOR",
+});
+// Possible output:
+// [[2, 4], [0, 1, 3]]
+
+scatter([0, 1, 2, 3, 4], 0.5, {
+    bias: "ROUND",
+});
+// Possible output:
+// [[3, 2, 4], [0, 1]]
+
+scatter([0, 1, 2, 3, 4], 0.5, {
+    bias: "CEILING",
+});
+// Possible output:
+// [[3, 2, 4], [0, 1]]
+```
+
+options:
+- `bias` - When the split does not work exactly for the given array length, this will decide how to split the final item (e.g. given an array of 5 items and a split of `0.5` (50%), the bias will decide if the split will be `3 - 2` or `2 - 3`) (default = `"ROUND"`)
+
+#### `shuffle(list)`
+Shuffles the array into a new array will all the items in a random order.
+
+```ts
+shuffle([0, 1, 2, 3, 4]);
+// Possible output:
+// [2, 4, 0, 1, 3]
+```
+
+#### `uid(length?, charset?)`
+Returns a random string of characters gotten from a specified charset that can be used for ids.  
+The default length is `8` and the default charset is `ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789`.
+
+```ts
+uid();
+// Possible output:
+// "Dae3pmZH"
+
+uid(12);
+// Possible output:
+// "9lqD8Mp3CUrK"
+
+uid(8, "Aa");
+// Possible output:
+// "AaAAAaAA"
+```
+
 <!-- !SECTION -->
 <!-- SECTION: String utils -->
 
@@ -527,7 +1838,7 @@ capitalize("some value");
 Converts a string into a custom cased version of the string, required a seperator and word transformer to work.
 
 > NOTE:  
-  This library also exports other casing utils that use this function under the hood and can (and most likely should) be used in most cases.
+> This library also exports other casing utils that use this function under the hood and can (and most likely should) be used in most cases.
 
 ```ts
 customCase("someValue", {