@oscarpalmer/atoms 0.217.0 → 0.219.0

package/dist/internal/random.d.mts

@@ -1,4 +1,10 @@
 //#region src/internal/random.d.ts
+/**
+ * Get a random number between 0 _(inclusive)_ and 1 _(exclusive)_
+ *
+ * @returns Random number
+ */
+export declare function getRandom(): number;
 /**
  * Get a random floating-point number
  *

package/dist/internal/random.mjs

@@ -1,12 +1,22 @@
 import { isNumber } from "./is.mjs";
 import { floor } from "./math/misc.mjs";
 //#region src/internal/random.ts
+/**
+* Get a random number between 0 _(inclusive)_ and 1 _(exclusive)_
+*
+* @returns Random number
+*/
+function getRandom() {
+	/* istanbul ignore if */
+	if (globalThis.crypto == null) return Math.random();
+	return globalThis.crypto.getRandomValues(/* @__PURE__ */ new Uint32Array(1))[0] / RANDOM_DIVISOR;
+}
 function getRandomFloatingNumberValue(inclusive, minimum, maximum) {
 	let maxFloat = isNumber(maximum) && maximum <= Number.MAX_SAFE_INTEGER ? maximum : Number.MAX_SAFE_INTEGER;
 	let minFloat = isNumber(minimum) && minimum >= Number.MIN_SAFE_INTEGER ? minimum : Number.MIN_SAFE_INTEGER;
 	if (minFloat === maxFloat) return minFloat;
 	if (minFloat > maxFloat) [minFloat, maxFloat] = [maxFloat, minFloat];
-	return Math.random() * (maxFloat + (inclusive ? 1 : 0) - minFloat) + minFloat;
+	return getRandom() * (maxFloat + (inclusive ? 1 : 0) - minFloat) + minFloat;
 }
 /**
 * Get a random floating-point number
@@ -28,5 +38,6 @@ function getRandomFloatingNumber(minimum, maximum) {
 function getRandomInteger(minimum, maximum) {
 	return floor(getRandomFloatingNumberValue(true, minimum, maximum));
 }
+const RANDOM_DIVISOR = 2 ** 32;
 //#endregion
-export { getRandomFloatingNumber, getRandomInteger };
+export { getRandom, getRandomFloatingNumber, getRandomInteger };

package/dist/internal/result/attempt.mjs

@@ -7,16 +7,16 @@ async function asyncAttempt(value, err) {
 		else result = value;
 		if (result instanceof Promise) result = await result;
 		return ok(result);
-	} catch (thrown) {
-		return getError(err ?? thrown, err == null ? void 0 : thrown);
+	} catch (error) {
+		return getError(err ?? error, err == null ? void 0 : error);
 	}
 }
 function attempt(callback, err) {
 	try {
 		const value = callback();
 		return ok(value);
-	} catch (thrown) {
-		return getError(err ?? thrown, err == null ? void 0 : thrown);
+	} catch (error) {
+		return getError(err ?? error, err == null ? void 0 : error);
 	}
 }
 attempt.async = asyncAttempt;

package/dist/internal/string/case.d.mts

@@ -4,6 +4,14 @@
  *
  * @param value String to convert
  * @returns Camel-cased string
+ *
+ * @example
+ * ```typescript
+ * camelCase('this is camel case'); // => 'thisIsCamelCase'
+ * camelCase('ThisIsCamelCase');    // => 'thisIsCamelCase'
+ * camelCase('this-is-camel-case'); // => 'thisIsCamelCase'
+ * camelCase('this_is_camel_case'); // => 'thisIsCamelCase'
+ * ```
  */
 export declare function camelCase(value: string): string;
 /**
@@ -11,6 +19,14 @@ export declare function camelCase(value: string): string;
  *
  * @param value String to capitalize
  * @returns Capitalized string
+ *
+ * @example
+ * ```typescript
+ * capitalize('this is a test'); // => 'This is a test'
+ * capitalize('This Is A Test'); // => 'This is a test'
+ * capitalize('t');              // => 'T'
+ * capitalize('');               // => ''
+ * ```
  */
 export declare function capitalize(value: string): string;
 /**
@@ -18,6 +34,14 @@ export declare function capitalize(value: string): string;
  *
  * @param value String to convert
  * @returns Kebab-cased string
+ *
+ * @example
+ * ```typescript
+ * kebabCase('this is kebab case'); // => 'this-is-kebab-case'
+ * kebabCase('ThisIsKebabCase');    // => 'this-is-kebab-case'
+ * kebabCase('this-is-kebab-case'); // => 'this-is-kebab-case'
+ * kebabCase('this_is_kebab_case'); // => 'this-is-kebab-case'
+ * ```
  */
 export declare function kebabCase(value: string): string;
 /**
@@ -25,6 +49,13 @@ export declare function kebabCase(value: string): string;
  *
  * @param value String to convert
  * @returns Lower-cased string
+ *
+ * @example
+ * ```typescript
+ * lowerCase('THIS IS A TEST'); // => 'this is a test'
+ * lowerCase('this is a test'); // => 'this is a test'
+ * lowerCase('t');              // => 't'
+ * ```
  */
 export declare function lowerCase(value: string): string;
 /**
@@ -32,6 +63,14 @@ export declare function lowerCase(value: string): string;
  *
  * @param value String to convert
  * @returns Pascal-cased string
+ *
+ * @example
+ * ```typescript
+ * pascalCase('this is pascal case'); // => 'ThisIsPascalCase'
+ * pascalCase('ThisIsPascalCase');    // => 'ThisIsPascalCase'
+ * pascalCase('this-is-pascal-case'); // => 'ThisIsPascalCase'
+ * pascalCase('this_is_pascal_case'); // => 'ThisIsPascalCase'
+ * ```
  */
 export declare function pascalCase(value: string): string;
 /**
@@ -39,6 +78,14 @@ export declare function pascalCase(value: string): string;
  *
  * @param value String to convert
  * @returns Snake-cased string
+ *
+ * @example
+ * ```typescript
+ * snakeCase('this is snake case'); // => 'this_is_snake_case'
+ * snakeCase('ThisIsSnakeCase');    // => 'this_is_snake_case'
+ * snakeCase('this-is-snake-case'); // => 'this_is_snake_case'
+ * snakeCase('this_is_snake_case'); // => 'this_is_snake_case'
+ * ```
  */
 export declare function snakeCase(value: string): string;
 /**
@@ -46,6 +93,14 @@ export declare function snakeCase(value: string): string;
  *
  * @param value String to convert
  * @returns Title-cased string
+ *
+ * @example
+ * ```typescript
+ * titleCase('this is a test'); // => 'This Is A Test'
+ * titleCase('This Is A Test'); // => 'This Is A Test'
+ * titleCase('t');              // => 'T'
+ * titleCase('');               // => ''
+ * ```
  */
 export declare function titleCase(value: string): string;
 /**
@@ -53,6 +108,14 @@ export declare function titleCase(value: string): string;
  *
  * @param value String to convert
  * @returns Upper-cased string
+ *
+ * @example
+ * ```typescript
+ * upperCase('this is a test'); // => 'THIS IS A TEST'
+ * upperCase('This Is A Test'); // => 'THIS IS A TEST'
+ * upperCase('t');              // => 'T'
+ * upperCase('');               // => ''
+ * ```
  */
 export declare function upperCase(value: string): string;
 //#endregion

package/dist/internal/string/case.mjs

@@ -7,6 +7,14 @@ import { STRING_CASE_CAMEL, STRING_CASE_KEBAB, STRING_CASE_PASCAL, STRING_CASE_S
 *
 * @param value String to convert
 * @returns Camel-cased string
+*
+* @example
+* ```typescript
+* camelCase('this is camel case'); // => 'thisIsCamelCase'
+* camelCase('ThisIsCamelCase');    // => 'thisIsCamelCase'
+* camelCase('this-is-camel-case'); // => 'thisIsCamelCase'
+* camelCase('this_is_camel_case'); // => 'thisIsCamelCase'
+* ```
 */
 function camelCase(value) {
 	return toCase(STRING_CASE_CAMEL, value, true, false);
@@ -16,6 +24,14 @@ function camelCase(value) {
 *
 * @param value String to capitalize
 * @returns Capitalized string
+*
+* @example
+* ```typescript
+* capitalize('this is a test'); // => 'This is a test'
+* capitalize('This Is A Test'); // => 'This is a test'
+* capitalize('t');              // => 'T'
+* capitalize('');               // => ''
+* ```
 */
 function capitalize(value) {
 	if (typeof value !== "string" || value.length === 0) return "";
@@ -27,6 +43,14 @@ function capitalize(value) {
 *
 * @param value String to convert
 * @returns Kebab-cased string
+*
+* @example
+* ```typescript
+* kebabCase('this is kebab case'); // => 'this-is-kebab-case'
+* kebabCase('ThisIsKebabCase');    // => 'this-is-kebab-case'
+* kebabCase('this-is-kebab-case'); // => 'this-is-kebab-case'
+* kebabCase('this_is_kebab_case'); // => 'this-is-kebab-case'
+* ```
 */
 function kebabCase(value) {
 	return toCase(STRING_CASE_KEBAB, value, false, false);
@@ -36,6 +60,13 @@ function kebabCase(value) {
 *
 * @param value String to convert
 * @returns Lower-cased string
+*
+* @example
+* ```typescript
+* lowerCase('THIS IS A TEST'); // => 'this is a test'
+* lowerCase('this is a test'); // => 'this is a test'
+* lowerCase('t');              // => 't'
+* ```
 */
 function lowerCase(value) {
 	if (typeof value !== "string") return "";
@@ -47,6 +78,14 @@ function lowerCase(value) {
 *
 * @param value String to convert
 * @returns Pascal-cased string
+*
+* @example
+* ```typescript
+* pascalCase('this is pascal case'); // => 'ThisIsPascalCase'
+* pascalCase('ThisIsPascalCase');    // => 'ThisIsPascalCase'
+* pascalCase('this-is-pascal-case'); // => 'ThisIsPascalCase'
+* pascalCase('this_is_pascal_case'); // => 'ThisIsPascalCase'
+* ```
 */
 function pascalCase(value) {
 	return toCase(STRING_CASE_PASCAL, value, true, true);
@@ -56,6 +95,14 @@ function pascalCase(value) {
 *
 * @param value String to convert
 * @returns Snake-cased string
+*
+* @example
+* ```typescript
+* snakeCase('this is snake case'); // => 'this_is_snake_case'
+* snakeCase('ThisIsSnakeCase');    // => 'this_is_snake_case'
+* snakeCase('this-is-snake-case'); // => 'this_is_snake_case'
+* snakeCase('this_is_snake_case'); // => 'this_is_snake_case'
+* ```
 */
 function snakeCase(value) {
 	return toCase(STRING_CASE_SNAKE, value, false, false);
@@ -65,6 +112,14 @@ function snakeCase(value) {
 *
 * @param value String to convert
 * @returns Title-cased string
+*
+* @example
+* ```typescript
+* titleCase('this is a test'); // => 'This Is A Test'
+* titleCase('This Is A Test'); // => 'This Is A Test'
+* titleCase('t');              // => 'T'
+* titleCase('');               // => ''
+* ```
 */
 function titleCase(value) {
 	if (typeof value !== "string" || value.length === 0) return "";
@@ -107,6 +162,14 @@ function toCaseCallback(value) {
 *
 * @param value String to convert
 * @returns Upper-cased string
+*
+* @example
+* ```typescript
+* upperCase('this is a test'); // => 'THIS IS A TEST'
+* upperCase('This Is A Test'); // => 'THIS IS A TEST'
+* upperCase('t');              // => 'T'
+* upperCase('');               // => ''
+* ```
 */
 function upperCase(value) {
 	if (typeof value !== "string" || value.length === 0) return "";

package/dist/internal/string/misc.d.mts

@@ -17,7 +17,13 @@
  * ```
  */
 export declare function getString(value: unknown): string;
+/**
+ * @internal
+ */
 export declare function ignoreKey(key: string): boolean;
+/**
+ * @internal
+ */
 export declare function interpolate(strings: TemplateStringsArray, values: unknown[]): string;
 /**
  * Join an array of values into a string _(while ignoring empty values)_
@@ -27,9 +33,23 @@ export declare function interpolate(strings: TemplateStringsArray, values: unkno
  * @param array Array of values
  * @param delimiter Delimiter to use between values
  * @returns Joined string
+ * @example
+ * ```typescript
+ * join(['a', 'b', 'c']);          // => 'abc'
+ * join(['a', 'b', 'c'], ', ');   // => 'a, b, c'
+ * join(['a', '', 'c']);           // => 'ac'
+ * join([null, 'b', undefined]);   // => 'b'
+ * join([]);                       // => ''
+ * ```
  */
 export declare function join(array: unknown[], delimiter?: string): string;
+/**
+ * @internal
+ */
 export declare function tryDecode(value: string): string;
+/**
+ * @internal
+ */
 export declare function tryEncode(value: boolean | number | string): unknown;
 /**
  * Split a string into words _(and other readable parts)_

package/dist/internal/string/misc.mjs

@@ -27,9 +27,15 @@ function getString(value) {
 	const asString = String(value.valueOf?.() ?? value);
 	return asString.startsWith("[object ") ? JSON.stringify(value) : asString;
 }
+/**
+* @internal
+*/
 function ignoreKey(key) {
 	return STRING_EXPRESSION_IGNORED.test(key);
 }
+/**
+* @internal
+*/
 function interpolate(strings, values) {
 	const { length } = strings;
 	let interpolated = "";
@@ -47,6 +53,14 @@ function interpolate(strings, values) {
 * @param array Array of values
 * @param delimiter Delimiter to use between values
 * @returns Joined string
+* @example
+* ```typescript
+* join(['a', 'b', 'c']);          // => 'abc'
+* join(['a', 'b', 'c'], ', ');   // => 'a, b, c'
+* join(['a', '', 'c']);           // => 'ac'
+* join([null, 'b', undefined]);   // => 'b'
+* join([]);                       // => ''
+* ```
 */
 function join(array, delimiter) {
 	if (!Array.isArray(array)) return "";
@@ -62,9 +76,15 @@ function join(array, delimiter) {
 function tryCallback(value, callback) {
 	return unwrap(attempt(() => callback(value)), value);
 }
+/**
+* @internal
+*/
 function tryDecode(value) {
 	return tryCallback(value, decodeURIComponent);
 }
+/**
+* @internal
+*/
 function tryEncode(value) {
 	return tryCallback(value, encodeURIComponent);
 }
@@ -75,7 +95,8 @@ function tryEncode(value) {
 * @returns Array of words found in the string
 */
 function words(value) {
-	return typeof value === "string" ? value.match(STRING_EXPRESSION_WORDS) ?? [] : [];
+	if (typeof value === "string") return value.match(STRING_EXPRESSION_WORDS) ?? [];
+	return [];
 }
 //#endregion
 export { getString, ignoreKey, interpolate, join, tryDecode, tryEncode, words };

package/dist/internal/subscription.mjs

@@ -125,7 +125,7 @@ function createSubscriptionsProperty(input) {
 	const values = isPlainObject(input) ? input : {};
 	return {
 		key: typeof values.key === "string" ? values.key : SUBSCRIPTION_PROPERTY,
-		value: values.value == null ? SUBSCRIPTION_NAME : values.value
+		value: values.value ?? "subscription"
 	};
 }
 function createSubscriptionsState(property, keys) {

package/dist/internal/value/equal.mjs

@@ -1,5 +1,6 @@
 import { isNonPlainObject, isPlainObject, isPrimitive, isTypedArray } from "../is.mjs";
 import { round } from "../math/misc.mjs";
+import { min } from "../math/aggregate.mjs";
 import { createCompareHandler } from "./handlers.mjs";
 import { EQUAL_ERROR_PROPERTIES, EQUAL_EXPRESSION_PROPERTIES, EQUAL_SYMBOL } from "../../models/value/value.equal.model.mjs";
 //#region src/internal/value/equal.ts
@@ -63,7 +64,7 @@ function equalArray(first, second, options) {
 	let offset = 0;
 	if (length >= 100) {
 		offset = round(length / 10);
-		offset = offset > 100 ? 100 : offset;
+		offset = min([offset, 100]);
 		for (let index = 0; index < offset; index += 1) if (!(equalValue(first[index], second[index], options) && equalValue(first[length - index - 1], second[length - index - 1], options))) return false;
 	}
 	const end = length - offset;

package/dist/internal/value/partial.mjs

@@ -2,7 +2,9 @@ import { isPlainObject } from "../is.mjs";
 //#region src/internal/value/partial.ts
 function partial(value, providedKeys, omit) {
 	if (!isPlainObject(value)) return {};
-	const keys = omit ? Object.keys(value) : Array.isArray(providedKeys) ? providedKeys : [];
+	let keys;
+	if (omit) keys = Object.keys(value);
+	else keys = Array.isArray(providedKeys) ? providedKeys : [];
 	const { length } = keys;
 	if (length === 0) return omit ? value : {};
 	const partials = {};

package/dist/logger.d.mts

@@ -1,7 +1,19 @@
 import { Lumberjack, TimeLogger } from "./models/logger.model.mjs";
 //#region src/logger.d.ts
 declare function TimeLogger(this: any, label: string): void;
+/**
+ * Is the value a _Logger_?
+ *
+ * @param value Value to check
+ * @returns `true` if the value is a _Logger_, otherwise `false`
+ */
 declare function isLogger(value: unknown): value is Lumberjack;
+/**
+ * Is the value a _TimeLogger_?
+ *
+ * @param value Value to check
+ * @returns `true` if the value is a _TimeLogger_, otherwise `false`
+ */
 declare function isTimeLogger(value: unknown): value is TimeLogger;
 /**
  * A logger that can be used to log messages to the console

package/dist/logger.mjs

@@ -64,12 +64,24 @@ function getTimeLoggerStop() {
 	}
 	return noop;
 }
+/**
+* Is the value a _Logger_?
+*
+* @param value Value to check
+* @returns `true` if the value is a _Logger_, otherwise `false`
+*/
 function isLogger(value) {
 	return isLoggerInstance(LOGGER_NAME, value);
 }
 function isLoggerInstance(name, value) {
 	return typeof value === "object" && value !== null && "$logger" in value && value["$logger"] === name;
 }
+/**
+* Is the value a _TimeLogger_?
+*
+* @param value Value to check
+* @returns `true` if the value is a _TimeLogger_, otherwise `false`
+*/
 function isTimeLogger(value) {
 	return isLoggerInstance(LOGGER_NAME_TIMED, value);
 }

package/dist/math.d.mts

@@ -8,6 +8,16 @@ import { floor, round } from "./internal/math/misc.mjs";
  * @param items List of items
  * @param callback Callback to get an item's value
  * @returns Average value, or `Number.NaN` if no average can be calculated
+ *
+ * @example
+ * ```typescript
+ * average([
+ *   {value: 1},
+ *   {value: 2},
+ *   {value: 3},
+ * ], item => item.value); // => 2
+ * average([{value: 1}], item => item.nope); // => Number.NaN
+ * ```
  */
 export declare function average<Item>(items: Item[], callback: (item: Item, index: number, array: Item[]) => number): number;
 /**
@@ -16,6 +26,12 @@ export declare function average<Item>(items: Item[], callback: (item: Item, inde
  * @param items List of items
  * @param key Key to use for value
  * @returns Average value, or `Number.NaN` if no average can be calculated
+ *
+ * @example
+ * ```typescript
+ * average([{value: 1}, {value: 2}, {value: 3}], 'value'); // => 2
+ * average([{value: 1}], 'nope'); // => Number.NaN
+ * ```
  */
 export declare function average<Item extends PlainObject>(items: Item[], key: keyof NumericalValues<Item>): number;
 /**
@@ -23,6 +39,12 @@ export declare function average<Item extends PlainObject>(items: Item[], key: ke
  *
  * @param numbers List of numbers
  * @returns Average value, or `Number.NaN` if no average can be calculated
+ *
+ * @example
+ * ```typescript
+ * average([1, 2, 3, 4, 5]); // => 3
+ * average([]); // => Number.NaN
+ * ```
  */
 export declare function average(numbers: number[]): number;
 /**
@@ -31,6 +53,13 @@ export declare function average(numbers: number[]): number;
  * @param value Number to round up
  * @param decimals Number of decimal places to round to _(defaults to `0`)_
  * @returns Rounded number, or `Number.NaN` if the value if unable to be rounded
+ *
+ * @example
+ * ```typescript
+ * ceil(1.234, 2); // => 1.24
+ * ceil(1.234);    // => 2
+ * ceil('abc');    // => Number.NaN
+ * ```
  */
 export declare function ceil(value: number, decimals?: number): number;
 /**
@@ -40,6 +69,14 @@ export declare function ceil(value: number, decimals?: number): number;
  * @param callback Callback to get an item's value
  * @param value Value to match and count
  * @returns Number of items that match the condition, or `Number.NaN` if no count can be calculated
+ *
+ * @example
+ * ```typescript
+ * count([1, 2, 3, 2], (item) => item, 2); // => 2
+ * count([{value: 1}, {value: 2}, {value: 3}], 'value', 2); // => 1
+ * count([1, 2, 3], (item) => item, 4); // => 0
+ * count([], (item) => item, 1); // => Number.NaN
+ * ```
  */
 export declare function count<Item>(array: Item[], callback: (item: Item, index: number, array: Item[]) => unknown, value: unknown): number;
 /**
@@ -49,6 +86,12 @@ export declare function count<Item>(array: Item[], callback: (item: Item, index:
  * @param key Key to use for value
  * @param value Value to match and count
  * @returns Number of items with the specified key value, or `Number.NaN` if no count can be calculated
+ *
+ * @example
+ * ```typescript
+ * count([{value: 1}, {value: 2}, {value: 3}], 'value', 2); // => 1
+ * count([{value: 1}], 'nope', 1); // => Number.NaN
+ * ```
  */
 export declare function count<Item extends PlainObject, ItemKey extends keyof Item>(array: Item[], key: ItemKey, value: Item[ItemKey]): number;
 /**
@@ -56,6 +99,12 @@ export declare function count<Item extends PlainObject, ItemKey extends keyof It
  *
  * @param values Array to count for
  * @returns Number of items, or `Number.NaN` if no count can be calculated
+ *
+ * @example
+ * ```typescript
+ * count([1, 2, 3]); // => 3
+ * count([]);        // => Number.NaN
+ * ```
  */
 export declare function count(values: unknown[]): number;
 /**
@@ -64,6 +113,13 @@ export declare function count(values: unknown[]): number;
  * @param array List of items
  * @param callback Callback to get an item's value
  * @returns Median value, or `Number.NaN` if no median can be calculated
+ *
+ * @example
+ * ```typescript
+ * median([1, 2, 3, 4, 5]); // => 3
+ * median([1, 2, 3, 4]);    // => 2.5
+ * median([]);              // => Number.NaN
+ * ```
  */
 export declare function median<Item>(array: Item[], callback: (item: Item, index: number, array: Item[]) => number): number;
 /**
@@ -72,6 +128,13 @@ export declare function median<Item>(array: Item[], callback: (item: Item, index
  * @param array List of items
  * @param key Key to use for value
  * @returns Median value, or `Number.NaN` if no median can be calculated
+ *
+ * @example
+ * ```typescript
+ * median([{value: 1}, {value: 2}, {value: 3}], 'value'); // => 2
+ * median([{value: 1}, {value: 2}, {value: 3}, {value: 4}], 'value'); // => 2.5
+ * median([], 'value'); // => Number.NaN
+ * ```
  */
 export declare function median<Item extends PlainObject>(array: Item[], key: keyof NumericalValues<Item>): number;
 /**
@@ -79,6 +142,13 @@ export declare function median<Item extends PlainObject>(array: Item[], key: key
  *
  * @param array List of numbers
  * @returns Median value, or `Number.NaN` if no median can be calculated
+ *
+ * @example
+ * ```typescript
+ * median([1, 2, 3, 4, 5]); // => 3
+ * median([1, 2, 3, 4]);    // => 2.5
+ * median([]);              // => Number.NaN
+ * ```
  */
 export declare function median(array: number[]): number;
 /**
@@ -87,6 +157,13 @@ export declare function median(array: number[]): number;
  * @param items List of items
  * @param callback Callback to get an item's value
  * @returns Sum of the values, or `Number.NaN` if no sum can be calculated
+ *
+ * @example
+ * ```typescript
+ * sum([{value: 1}, {value: 2}, {value: 3}], 'value'); // => 6
+ * sum([{value: 1}, {value: 2}, {value: 3}], item => item.value); // => 6
+ * sum([]); // => Number.NaN
+ * ```
  */
 export declare function sum<Item>(items: Item[], callback: (item: Item, index: number, array: Item[]) => number): number;
 /**
@@ -95,6 +172,13 @@ export declare function sum<Item>(items: Item[], callback: (item: Item, index: n
  * @param items List of items
  * @param key Key to use for value
  * @returns Sum of the values, or `Number.NaN` if no sum can be calculated
+ *
+ * @example
+ * ```typescript
+ * sum([{value: 1}, {value: 2}, {value: 3}], 'value'); // => 6
+ * sum([{value: 1}, {value: 2}, {value: 3}], item => item.value); // => 6
+ * sum([]); // => Number.NaN
+ * ```
  */
 export declare function sum<Item extends PlainObject>(items: Item[], key: keyof NumericalValues<Item>): number;
 /**
@@ -102,6 +186,12 @@ export declare function sum<Item extends PlainObject>(items: Item[], key: keyof
  *
  * @param values List of numbers
  * @returns Sum of the numbers, or `Number.NaN` if no sum can be calculated
+ *
+ * @example
+ * ```typescript
+ * sum([1, 2, 3]); // => 6
+ * sum([]);        // => Number.NaN
+ * ```
  */
 export declare function sum(values: number[]): number;
 //#endregion

package/dist/math.mjs

@@ -13,6 +13,13 @@ function average(array, key) {
 * @param value Number to round up
 * @param decimals Number of decimal places to round to _(defaults to `0`)_
 * @returns Rounded number, or `Number.NaN` if the value if unable to be rounded
+*
+* @example
+* ```typescript
+* ceil(1.234, 2); // => 1.24
+* ceil(1.234);    // => 2
+* ceil('abc');    // => Number.NaN
+* ```
 */
 function ceil(value, decimals) {
 	return roundNumber(Math.ceil, value, decimals);