@oscarpalmer/atoms 0.186.2 → 0.187.0

package/src/{kalas.ts → herald.ts}

@@ -4,40 +4,45 @@ import type {GenericCallback} from './models';
 // #region Types
 
 class Events<Map extends Record<string, GenericCallback>> {
-	readonly #kalas: Kalas<Map>;
+	readonly #herald: Herald<Map>;
 
-	constructor(kalas: Kalas<Map>) {
-		this.#kalas = kalas;
+	constructor(herald: Herald<Map>) {
+		this.#herald = herald;
 	}
 
 	/**
 	 * Subscribe to an event with a callback
+	 *
 	 * @param event Event name
 	 * @param callback Callback function
 	 * @returns Unsubscriber function
 	 */
 	subscribe<Event extends keyof Map>(event: Event, callback: Map[Event]): Unsubscriber {
-		return this.#kalas.subscribe(event, callback);
+		return this.#herald.subscribe(event, callback);
 	}
 
 	/**
 	 * Unsubscribe from an event with a callback _(or all callbacks, if no callback is provided)_
+	 *
 	 * @param event Event name
 	 * @param callback Callback function
 	 * @returns Unsubscriber function
 	 */
 	unsubscribe<Event extends keyof Map>(event: Event, callback?: Map[Event]): void {
-		return this.#kalas.unsubscribe(event, callback);
+		return this.#herald.unsubscribe(event, callback);
 	}
 }
 
-class Kalas<Map extends Record<string, GenericCallback>> {
+/**
+ * A _Herald_ is an announcer for named events, allowing emission, subscription, and unsubscription of events
+ */
+class Herald<Map extends Record<string, GenericCallback>> {
 	readonly #names: Set<keyof Map>;
 
 	readonly #subscribers = new Map<keyof Map, Set<Map[keyof Map]>>();
 
 	/**
-	 * Events interface for subscribing and unsubscribing to events
+	 * Events interface for subscribing to and unsubscribing from events
 	 */
 	declare readonly events: Events<Map>;
 
@@ -58,6 +63,7 @@ class Kalas<Map extends Record<string, GenericCallback>> {
 
 	/**
 	 * Emit an event with parameters
+	 *
 	 * @param event Event name
 	 * @param parameters Event parameters
 	 */
@@ -75,6 +81,7 @@ class Kalas<Map extends Record<string, GenericCallback>> {
 
 	/**
 	 * Subscribe to an event with a callback
+	 *
 	 * @param event Event name
 	 * @param callback Callback function
 	 * @returns Unsubscriber function
@@ -101,6 +108,7 @@ class Kalas<Map extends Record<string, GenericCallback>> {
 
 	/**
 	 * Unsubscribe from an event with a callback _(or all callbacks, if no callback is provided)_
+	 *
 	 * @param event Event name
 	 * @param callback Callback function
 	 */
@@ -134,13 +142,14 @@ export type Unsubscriber = () => void;
 // #region Functions
 
 /**
- * Create a Kalas _(party)_ for named events
+ * Create a _Herald_ for announcing named events
+ *
  * @param names Event names
- * @returns Kalas instance
+ * @returns _Herald_ instance
  */
-export function kalas<Events extends Record<string, GenericCallback>>(
+export function herald<Events extends Record<string, GenericCallback>>(
 	names: (keyof Events)[],
-): Kalas<Events> {
+): Herald<Events> {
 	if (
 		!Array.isArray(names) ||
 		names.length === 0 ||
@@ -149,19 +158,19 @@ export function kalas<Events extends Record<string, GenericCallback>>(
 		throw new Error(MESSAGE);
 	}
 
-	return new Kalas<Events>(names);
+	return new Herald<Events>(names);
 }
 
 // #endregion
 
 // #region Variables
 
-const MESSAGE = 'Kalas requires an array of event names.';
+const MESSAGE = 'Herald requires an array of event names.';
 
 // #endregion
 
 // #region Exports
 
-export {type Events, type Kalas};
+export {type Events, type Herald};
 
 // #endregion

package/src/index.ts

@@ -17,6 +17,8 @@ export * from './function/once';
 export * from './function/retry';
 export * from './function/work';
 
+export * from './herald';
+
 export * from './internal/function/misc';
 export * from './internal/string';
 export * from './internal/value/compare';
@@ -25,8 +27,6 @@ export * from './internal/value/get';
 export * from './internal/value/has';
 export * from './internal/value/set';
 
-export * from './kalas';
-
 export * from './string/case';
 export * from './string/fuzzy';
 export * from './string/index';
@@ -37,6 +37,7 @@ export * from './string/template';
 export * from './value/clone';
 export * from './value/collection';
 export * from './value/diff';
+export * from './value/freeze';
 export * from './value/index';
 export * from './value/merge';
 export * from './value/transform';

package/src/internal/array/index-of.ts

@@ -91,7 +91,7 @@ indexOf.last = lastIndexOf;
 /**
  * Get the index of the last matching item by callback
  *
- * Available as `lastIndexOf` and `indexOf.last`
+ * _Available as `lastIndexOf` and `indexOf.last`_
  *
  * @param array Array to search in
  * @param callback Callback to get an item's value
@@ -115,7 +115,7 @@ export function lastIndexOf<
 /**
  * Get the index of the last matching item by key
  *
- * Available as `lastIndexOf` and `indexOf.last`
+ * _Available as `lastIndexOf` and `indexOf.last`_
  *
  * @param array Array to search in
  * @param key Key to match items by
@@ -140,7 +140,7 @@ export function lastIndexOf<Item extends PlainObject, ItemKey extends keyof Item
 /**
  * Get the index of the last item matching the filter
  *
- * Available as `lastIndexOf` and `indexOf.last`
+ * _Available as `lastIndexOf` and `indexOf.last`_
  *
  * @param array Array to search in
  * @param filter Filter callback to match items
@@ -162,7 +162,7 @@ export function lastIndexOf<Item>(
 /**
  * Get the index of the last item matching the given item
  *
- * Available as `lastIndexOf` and `indexOf.last`
+ * _Available as `lastIndexOf` and `indexOf.last`_
  *
  * @param array Array to search in
  * @param item Item to match against

package/src/internal/array/insert.ts

@@ -20,7 +20,7 @@ function insertChunkedValues(
 	const chunked = chunk(items);
 	const lastIndex = chunked.length - 1;
 
-	let index = Number(chunked.length);
+	let index = chunked.length;
 	let returned: unknown[] | undefined;
 
 	while (index > 0) {

package/src/internal/array/shuffle.ts

@@ -4,6 +4,7 @@ import {getRandomInteger} from '../random';
 
 /**
  * Shuffle items in array
+ *
  * @param array Original array
  * @returns Shuffled array
  */
@@ -18,7 +19,7 @@ export function shuffle<Item>(array: Item[]): Item[] {
 		return shuffled;
 	}
 
-	let index = Number(shuffled.length);
+	let index = shuffled.length;
 
 	while (--index >= 0) {
 		const random = getRandomInteger(0, index);

package/src/internal/is.ts

@@ -10,9 +10,10 @@ import type {
 // #region Functions
 
 /**
- * Is the value an array or a record?
+ * Is the value an array or a plain object?
+ *
  * @param value Value to check
- * @returns `true` if the value is an array or a record, otherwise `false`
+ * @returns `true` if the value is an array or a plain object, otherwise `false`
  */
 export function isArrayOrPlainObject(value: unknown): value is ArrayOrPlainObject {
 	return Array.isArray(value) || isPlainObject(value);
@@ -20,6 +21,7 @@ export function isArrayOrPlainObject(value: unknown): value is ArrayOrPlainObjec
 
 /**
  * Is the value a constructor function?
+ *
  * @param value Value to check
  * @returns `true` if the value is a constructor function, otherwise `false`
  */
@@ -29,6 +31,7 @@ export function isConstructor(value: unknown): value is Constructor {
 
 /**
  * Is the value an instance of the constructor?
+ *
  * @param constructor Class constructor
  * @param value Value to check
  * @returns `true` if the value is an instance of the constructor, otherwise `false`
@@ -41,9 +44,10 @@ export function isInstanceOf<Instance>(
 }
 
 /**
- * Is the value a key?
+ * Is the value a _Key_?
+ *
  * @param value Value to check
- * @returns `true` if the value is a `Key` _(`number` or `string`)_, otherwise `false`
+ * @returns `true` if the value is a _Key_ _(`number` or `string`)_, otherwise `false`
  */
 export function isKey(value: unknown): value is Key {
 	return typeof value === 'number' || typeof value === 'string';
@@ -51,6 +55,7 @@ export function isKey(value: unknown): value is Key {
 
 /**
  * Is the value not an array or a plain object?
+ *
  * @param value Value to check
  * @returns `true` if the value is not an array or a plain object, otherwise `false`
  */
@@ -62,6 +67,7 @@ export function isNonArrayOrPlainObject<Value>(
 
 /**
  * Is the value not a constructor function?
+ *
  * @param value Value to check
  * @returns `true` if the value is not a constructor function, otherwise `false`
  */
@@ -71,6 +77,7 @@ export function isNonConstructor<Value>(value: Value): value is Exclude<Value, C
 
 /**
  * Is the value not an instance of the constructor?
+ *
  * @param constructor Class constructor
  * @param value Value to check
  * @returns `true` if the value is not an instance of the constructor, otherwise `false`
@@ -83,9 +90,10 @@ export function isNonInstanceOf<Instance, Value>(
 }
 
 /**
- * Is the value not a key?
+ * Is the value not a _Key_?
+ *
  * @param value Value to check
- * @returns `true` if the value is not a `Key` _(`number` or `string`)_, otherwise `false`
+ * @returns `true` if the value is not a _Key_ _(`number` or `string`)_, otherwise `false`
  */
 export function isNonKey<Value>(value: Value): value is Exclude<Value, Key> {
 	return !isKey(value);
@@ -93,6 +101,7 @@ export function isNonKey<Value>(value: Value): value is Exclude<Value, Key> {
 
 /**
  * Is the value not a number?
+ *
  * @param value Value to check
  * @returns `true` if the value is not a `number`, otherwise `false`
  */
@@ -102,6 +111,7 @@ export function isNonNumber<Value>(value: Value): value is Exclude<Value, number
 
 /**
  * Is the value not a plain object?
+ *
  * @param value Value to check
  * @returns `true` if the value is not a plain object, otherwise `false`
  */
@@ -111,6 +121,7 @@ export function isNonPlainObject<Value>(value: Value): value is Exclude<Value, P
 
 /**
  * Is the value not a primitive value?
+ *
  * @param value Value to check
  * @returns `true` if the value is not a primitive value, otherwise `false`
  */
@@ -120,6 +131,7 @@ export function isNonPrimitive<Value>(value: Value): value is Exclude<Value, Pri
 
 /**
  * Is the value not a template strings array?
+ *
  * @param value Value to check
  * @returns `true` if the value is not a `TemplateStringsArray`, otherwise `false`
  */
@@ -131,6 +143,7 @@ export function isNonTemplateStringsArray<Value>(
 
 /**
  * Is the value not a typed array?
+ *
  * @param value Value to check
  * @returns `true` if the value is not a typed array, otherwise `false`
  */
@@ -140,6 +153,7 @@ export function isNonTypedArray<Value>(value: Value): value is Exclude<Value, Ty
 
 /**
  * Is the value a number?
+ *
  * @param value Value to check
  * @returns `true` if the value is a `number`, otherwise `false`
  */
@@ -149,6 +163,7 @@ export function isNumber(value: unknown): value is number {
 
 /**
  * Is the value a plain object?
+ *
  * @param value Value to check
  * @returns `true` if the value is a plain object, otherwise `false`
  */
@@ -171,9 +186,10 @@ export function isPlainObject(value: unknown): value is PlainObject {
 }
 
 /**
- * - Is the value a primitive value?
+ * Is the value a primitive value?
+ *
  * @param value Value to check
- * @returns `true` if the value matches, otherwise `false`
+ * @returns `true` if the value is a primitive value, otherwise `false`
  */
 export function isPrimitive(value: unknown): value is Primitive {
 	if (value == null) {
@@ -193,6 +209,7 @@ export function isPrimitive(value: unknown): value is Primitive {
 
 /**
  * Is the value a template strings array?
+ *
  * @param value Value to check
  * @returns `true` if the value is a `TemplateStringsArray`, otherwise `false`
  */
@@ -202,6 +219,7 @@ export function isTemplateStringsArray(value: unknown): value is TemplateStrings
 
 /**
  * Is the value a typed array?
+ *
  * @param value Value to check
  * @returns `true` if the value is a typed array, otherwise `false`
  */

package/src/internal/math/aggregate.ts

@@ -72,14 +72,14 @@ export function getAggregateCallback(key: unknown): Function | undefined {
  * max(
  *   [{id: 1, value: 10}, {id: 2, value: 20}],
  *   item => item.value,
- * ); // 20
+ * ); // => 20
  *
- * max([], item => item.value); // Number.NaN
+ * max([], item => item.value); // => Number.NaN
  * ```
  *
  * @param items List of items
  * @param callback Callback to get an item's value
- * @returns Maximum value, or `NaN` if no maximum can be found
+ * @returns Maximum value, or `Number.NaN` if no maximum can be found
  */
 export function max<Item>(
 	items: Item[],
@@ -94,14 +94,14 @@ export function max<Item>(
  * max(
  *   [{id: 1, value: 10}, {id: 2, value: 20}],
  *   'value',
- * ); // 20
+ * ); // => 20
  *
- * max([], 'value'); // Number.NaN
+ * max([], 'value'); // => Number.NaN
  * ```
  *
  * @param items List of items
  * @param key Key to use for value
- * @returns Maximum value, or `NaN` if no maximum can be found
+ * @returns Maximum value, or `Number.NaN` if no maximum can be found
  */
 export function max<Item extends PlainObject, ItemKey extends keyof NumericalValues<Item>>(
 	items: Item[],
@@ -113,12 +113,12 @@ export function max<Item extends PlainObject, ItemKey extends keyof NumericalVal
  *
  * @example
  * ```typescript
- * max([10, 20]); // 20
- * max([]);       // Number.NaN
+ * max([10, 20]); // => 20
+ * max([]);       // => Number.NaN
  * ```
  *
  * @param values List of numbers
- * @returns Maximum value, or `NaN` if no maximum can be found
+ * @returns Maximum value, or `Number.NaN` if no maximum can be found
  */
 export function max(values: number[]): number;
 

package/src/internal/number.ts

@@ -4,6 +4,7 @@ import {isNumber} from './is';
 
 /**
  * Is the number between a minimum and maximum value?
+ *
  * @param value Value to check
  * @param minimum Minimum value
  * @param maximum Maximum value
@@ -26,11 +27,18 @@ export function between(value: number, minimum: number, maximum: number): boolea
 
 /**
  * Clamp a number between a minimum and maximum value
+ *
  * @param value Value to clamp
  * @param minimum Minimum value
  * @param maximum Maximum value
  * @param loop If `true`, the value will loop around when smaller than the minimum or larger than the maximum _(defaults to `false`)_
  * @returns Clamped value
+ *
+ * @example
+ * ```typescript
+ * clamp(10, 0, 5);       // => 5
+ * clamp(10, 0, 5, true); // => 0
+ * ```
  */
 export function clamp(value: number, minimum: number, maximum: number, loop?: boolean): number {
 	if (![value, minimum, maximum].every(isNumber)) {
@@ -47,9 +55,12 @@ export function clamp(value: number, minimum: number, maximum: number, loop?: bo
 }
 
 /**
- * Get the number value from an unknown value _(based on Lodash)_
+ * Get the number value from an unknown value
+ *
+ * _(Based on Lodash)_
+ *
  * @param value Original value
- * @returns Original value as a number, or `NaN` if the value is unable to be parsed
+ * @returns Original value as a number, or `Number.NaN` if the value is unable to be parsed
  */
 export function getNumber(value: unknown): number {
 	if (typeof value === 'number') {

package/src/internal/random.ts

@@ -2,7 +2,11 @@ import {isNumber} from './is';
 
 // #region Functions
 
-function _getRandomFloat(inclusive: boolean, minimum?: number, maximum?: number): number {
+function getRandomFloatingNumberValue(
+	inclusive: boolean,
+	minimum?: number,
+	maximum?: number,
+): number {
 	let maxFloat =
 		isNumber(maximum) && maximum <= Number.MAX_SAFE_INTEGER ? maximum : Number.MAX_SAFE_INTEGER;
 
@@ -22,22 +26,24 @@ function _getRandomFloat(inclusive: boolean, minimum?: number, maximum?: number)
 
 /**
  * Get a random floating-point number
+ *
  * @param minimum Minimum value
  * @param maximum Maximum value
  * @returns Random floating-point number
  */
-export function getRandomFloat(minimum?: number, maximum?: number): number {
-	return _getRandomFloat(false, minimum, maximum);
+export function getRandomFloatingNumber(minimum?: number, maximum?: number): number {
+	return getRandomFloatingNumberValue(false, minimum, maximum);
 }
 
 /**
  * Get a random integer
+ *
  * @param minimum Minimum value
  * @param maximum Maximum value
  * @returns Random integer
  */
 export function getRandomInteger(minimum?: number, maximum?: number): number {
-	return Math.floor(_getRandomFloat(true, minimum, maximum));
+	return Math.floor(getRandomFloatingNumberValue(true, minimum, maximum));
 }
 
 // #endregion

package/src/internal/result.ts

@@ -4,20 +4,11 @@ import {isNonPlainObject} from './is';
 
 // #region Functions
 
-function _isResult(value: unknown, okValue: boolean): value is Result<unknown, unknown> {
-	if (isNonPlainObject(value)) {
-		return false;
-	}
-
-	return (
-		(value as PlainObject).ok === okValue && (okValue ? PROPERTY_VALUE : PROPERTY_ERROR) in value
-	);
-}
-
 /**
- * Is the result an extended error?
- * @param result Result to check
- * @returns `true` if the result is an extended error, `false` otherwise
+ * Is the _Result_ an extended error?
+ *
+ * @param result _Result_ to check
+ * @returns `true` if the _Result_ is an extended error, `false` otherwise
  */
 export function isError<Value, E = Error>(
 	result: ExtendedErr<E> | Result<Value, E>,
@@ -25,14 +16,16 @@ export function isError<Value, E = Error>(
 ): result is ExtendedErr<E>;
 
 /**
- * Is the result an error?
- * @param result Result to check
- * @returns `true` if the result is an error, `false` otherwise
+ * Is the _Result_ an error?
+ *
+ * @param result _Result_ to check
+ * @returns `true` if the _Result_ is an error, `false` otherwise
  */
 export function isError<Value, E = Error>(result: Result<Value, E>): result is Err<E>;
 
 /**
  * Is the value an error?
+ *
  * @param value Value to check
  * @returns `true` if the value is an error, `false` otherwise
  */
@@ -43,41 +36,49 @@ export function isError(
 	extended?: boolean,
 ): value is Err<unknown> | ExtendedErr<unknown> {
 	return (
-		_isResult(value, false) &&
+		isResultValue(value, false) &&
 		(extended === true ? (value as ExtendedErr<unknown>).original instanceof Error : true)
 	);
 }
 
 /**
- * Is the result ok?
- * @param value Result to check
- * @returns `true` if the result is ok, `false` otherwise
+ * Is the _Result_ ok?
+ *
+ * @param value _Result_ to check
+ * @returns `true` if the _Result_ is ok, `false` otherwise
  */
 export function isOk<Value, E = Error>(value: Result<Value, E>): value is Ok<Value>;
 
 /**
  * Is the value ok?
+ *
  * @param value Value to check
  * @returns `true` if the value is ok, `false` otherwise
  */
 export function isOk(value: unknown): value is Ok<unknown>;
 
-/**
- * Is the result ok?
- * @param result Result to check
- * @returns `true` if the result is ok, `false` otherwise
- */
 export function isOk(value: unknown): value is Ok<unknown> {
-	return _isResult(value, true);
+	return isResultValue(value, true);
 }
 
 /**
- * Is the value a result?
+ * Is the value a _Result_?
+ *
  * @param value Value to check
- * @returns `true` if the value is a result, `false` otherwise
+ * @returns `true` if the value is a _Result_, `false` otherwise
  */
 export function isResult(value: unknown): value is ExtendedErr<unknown> | Result<unknown, unknown> {
-	return _isResult(value, true) || _isResult(value, false);
+	return isResultValue(value, true) || isResultValue(value, false);
+}
+
+function isResultValue(value: unknown, okValue: boolean): value is Result<unknown, unknown> {
+	if (isNonPlainObject(value)) {
+		return false;
+	}
+
+	return (
+		(value as PlainObject).ok === okValue && (okValue ? PROPERTY_VALUE : PROPERTY_ERROR) in value
+	);
 }
 
 // #endregion

package/src/internal/string.ts

@@ -2,8 +2,20 @@
 
 /**
  * Get the string value from any value
+ *
  * @param value Original value
  * @returns String representation of the value
+ *
+ * @example
+ * ```typescript
+ * getString(null)       // => ''
+ * getString('foo')      // => 'foo'
+ * getString(123)        // => '123'
+ * getString(true)       // => 'true'
+ * getString([1, 2, 3])  // => '1,2,3'
+ * getString({a: 1})     // => '{"a":1}'
+ * getString(() => 123)  // => '123'
+ * ```
  */
 export function getString(value: unknown): string {
 	if (typeof value === 'string') {
@@ -31,10 +43,25 @@ export function ignoreKey(key: string): boolean {
 	return EXPRESSION_IGNORED.test(key);
 }
 
+export function interpolate(strings: TemplateStringsArray, values: unknown[]): string {
+	const {length} = strings;
+
+	let interpolated = '';
+
+	for (let index = 0; index < length; index += 1) {
+		const value = values[index];
+
+		interpolated += `${strings[index]}${Array.isArray(value) ? join(value.map(getString)) : getString(value)}`;
+	}
+
+	return interpolated;
+}
+
 /**
  * Join an array of values into a string _(while ignoring empty values)_
  *
  * _(`null`, `undefined`, and any values that become whitespace-only strings are considered empty)_
+ *
  * @param array Array of values
  * @param delimiter Delimiter to use between values
  * @returns Joined string
@@ -81,6 +108,7 @@ export function tryEncode(value: boolean | number | string): unknown {
 
 /**
  * Split a string into words _(and other readable parts)_
+ *
  * @param value Original string
  * @returns Array of words found in the string
  */

package/src/internal/value/compare.ts

@@ -19,6 +19,7 @@ const COMPARE_NAME: string = 'compare';
 
 /**
  * Compare two values _(for sorting purposes)_
+ *
  * @param first First value
  * @param second Second value
  * @returns `0` if equal; `-1` first comes before second; `1` first comes after second
@@ -124,7 +125,8 @@ function compareValue(
 /**
  * Deregister a custom comparison handler for a class
  *
- * Available as `deregisterComparator` and `compare.deregister`
+ * _Available as `deregisterComparator` and `compare.deregister`_
+ *
  * @param constructor Class constructor
  */
 export function deregisterComparator<Instance>(constructor: Constructor<Instance>): void {
@@ -142,7 +144,8 @@ function getComparisonParts(value: unknown): unknown[] {
 /**
  * Register a custom comparison handler for a class
  *
- * Available as `registerComparator` and `compare.register`
+ * _Available as `registerComparator` and `compare.register`_
+ *
  * @param constructor Class constructor
  * @param handler Method name or comparison function _(defaults to `compare`)_
  */