@oscarpalmer/atoms 0.186.2 → 0.187.0

package/src/color/misc/is.ts

@@ -33,9 +33,10 @@ function isBytey(value: unknown): value is number {
 }
 
 /**
- * Is the value a Color?
+ * Is the value a _Color_?
+ *
  * @param value Value to check
- * @returns `true` if the value is a Color, otherwise `false`
+ * @returns `true` if the value is a _Color_, otherwise `false`
  */
 export function isColor(value: unknown): value is Color {
 	return typeof value === 'object' && value !== null && '$color' in value && value.$color === true;
@@ -75,9 +76,19 @@ function isDegree(value: unknown): value is number {
 
 /**
  * Is the value a hex color?
+ *
  * @param value Value to check
- * @param alpha Allow alpha channel? _(defaults to `true`)_
+ * @param alpha Allow alpha channel _(opacity)_? _(defaults to `true`)_
  * @returns `true` if the value is a hex color, otherwise `false`
+ *
+ * @example
+ * ```typescript
+ * isHexColor('ff0000');  // => true
+ * isHexColor('#ff0000'); // => true
+ *
+ * isHexColor('#ff000050');        // => true
+ * isHexColor('#ff000050', false); // => false
+ * ```
  */
 export function isHexColor(value: unknown, alpha?: boolean): value is string {
 	if (typeof value !== 'string') {
@@ -96,18 +107,20 @@ export function isHexColor(value: unknown, alpha?: boolean): value is string {
 }
 
 /**
- * Is the value an HSLA color?
+ * Is the value an _HSLA_ color?
+ *
  * @param value Value to check
- * @returns `true` if the value is an HSLA color, otherwise `false`
+ * @returns `true` if the value is an _HSLA_ color, otherwise `false`
  */
 export function isHslaColor(value: unknown): value is HSLAColor {
 	return isColorValue(value, KEYS_HSLA);
 }
 
 /**
- * Is the value an HSL color?
+ * Is the value an _HSL_ color?
+ *
  * @param value Value to check
- * @returns `true` if the value is an HSL color, otherwise `false`
+ * @returns `true` if the value is an _HSL_ color, otherwise `false`
  */
 export function isHslColor(value: unknown): value is HSLColor {
 	return isColorValue(value, KEYS_HSLA) || isColorValue(value, KEYS_HSL);
@@ -118,18 +131,20 @@ export function isHslLike(value: unknown): value is Record<keyof HSLColor, unkno
 }
 
 /**
- * Is the value an RGBA color?
+ * Is the value an _RGBA_ color?
+ *
  * @param value Value to check
- * @returns `true` if the value is an RGBA color, otherwise `false`
+ * @returns `true` if the value is an _RGBA_ color, otherwise `false`
  */
 export function isRgbaColor(value: unknown): value is RGBAColor {
 	return isColorValue(value, KEYS_RGBA);
 }
 
 /**
- * Is the value an RGB color?
+ * Is the value an _RGB_ color?
+ *
  * @param value Value to check
- * @returns `true` if the value is an RGB color, otherwise `false`
+ * @returns `true` if the value is an _RGB_ color, otherwise `false`
  */
 export function isRgbColor(value: unknown): value is RGBColor {
 	return isColorValue(value, KEYS_RGBA) || isColorValue(value, KEYS_RGB);

package/src/color/misc/state.ts

@@ -63,7 +63,7 @@ export function getColorState(value: unknown): ColorState {
 	}
 
 	state.alpha ??= getAlpha(ALPHA_FULL_VALUE);
-	state.hex ??= String(HEX_BLACK);
+	state.hex ??= HEX_BLACK;
 	state.hsl ??= {...DEFAULT_HSL};
 	state.rgb ??= {...DEFAULT_RGB};
 

package/src/color/models.ts

@@ -6,16 +6,19 @@ export type Alpha = {
 };
 
 type ColorWithAlpha = {
+	/**
+	 * Alpha channel _(opacity)_ of the color _(in percentage; 0-100)_
+	 */
 	alpha: number;
 };
 
 /**
- * An _HSL_-color with an alpha channel
+ * An _HSL_ color with an alpha channel _(opacity)_
  */
 export type HSLAColor = HSLColor & ColorWithAlpha;
 
 /**
- * An _HSL_-color
+ * An _HSL_ color
  */
 export type HSLColor = {
 	/**
@@ -33,12 +36,12 @@ export type HSLColor = {
 };
 
 /**
- * An _RGB_-color with an alpha channel
+ * An _RGB_ color with an alpha channel _(opacity)_
  */
 export type RGBAColor = RGBColor & ColorWithAlpha;
 
 /**
- * An _RGB_-color
+ * An _RGB_ color
  */
 export type RGBColor = {
 	/**

package/src/color/space/hex.ts

@@ -36,9 +36,12 @@ function convertHexToRgba(value: string): RGBAColor {
 
 /**
  * Get the normalized hex color from a value
+ *
+ * _If the value is unable to be parsed or normalized, a hex color of `000000` will be returned, with the alpha channel _(opacity)_ value `0` included, if specified_
+ *
  * @param value Value to normalize
- * @param alpha Include alpha channel? _(defaults to `false`)_
- * @returns Normalized hex color, or `000000` if the value is unable to be normalized
+ * @param alpha Include alpha channel _(opacity)_? _(defaults to `false`)_
+ * @returns Normalized hex color
  */
 export function getNormalizedHex(value: unknown, alpha?: boolean): string {
 	const includeAlpha = alpha ?? false;
@@ -78,9 +81,12 @@ export function hexToHsla(value: string): HSLAColor {
 }
 
 /**
- * Convert a hex color to an RGB color
+ * Convert a hex color to an _RGB_ color
+ *
+ * _If the value is unable to be converted, a black RGB color will be returned_
+ *
  * @param value Original value
- * @returns RGB color
+ * @returns _RGB_ color
  */
 export function hexToRgb(value: string): RGBColor {
 	const {blue, green, red} = convertHexToRgba(value);
@@ -89,9 +95,12 @@ export function hexToRgb(value: string): RGBColor {
 }
 
 /**
- * Convert a hex color to an RGBA color
+ * Convert a hex color to an _RGBA_ color
+ *
+ * _If the value is unable to be converted, a black RGBA color with an alpha channel (opacity) of `0` will be returned_
+ *
  * @param value Original value
- * @returns RGBA color
+ * @returns _RGBA_ color
  */
 export function hexToRgba(value: string): RGBAColor {
 	return convertHexToRgba(value);

package/src/color/space/hsl.ts

@@ -42,9 +42,12 @@ export function hslToHex(hsl: HSLAColor | HSLColor, alpha?: boolean): string {
 }
 
 /**
- * Convert an HSL(A) color to an RGB color
+ * Convert an _HSL(A)_ color to an _RGB_ color
+ *
+ * _If the value is unable to be converted, a black RGB color will be returned_
+ *
+ * _Thanks, https://github.com/color-js/color.js/blob/main/src/spaces/hsl.js#L61_
  *
- * Thanks, https://github.com/color-js/color.js/blob/main/src/spaces/hsl.js#L61
  * @param hsl HSL(A) color
  * @returns RGB color
  */
@@ -59,9 +62,12 @@ export function hslToRgb(hsl: HSLAColor | HSLColor): RGBColor {
 }
 
 /**
- * Convert an HSL(A) color to an RGBA color
+ * Convert an _HSL(A)_ color to an _RGBA_ color
+ *
+ * _If the value is unable to be converted, a black RGBA color with an alpha channel (opactiy) of `0` will be returned_
+ *
+ * _Thanks, https://github.com/color-js/color.js/blob/main/src/spaces/hsl.js#L61_
  *
- * Thanks, https://github.com/color-js/color.js/blob/main/src/spaces/hsl.js#L61
  * @param hsl HSL(A) color
  * @returns RGBA color
  */

package/src/color/space/rgb.ts

@@ -77,21 +77,27 @@ export function getRgbValue(value: Record<keyof RGBColor, unknown>): RGBColor {
 }
 
 /**
- * Convert an RGB(A) color to a hex color _(with optional alpha channel)_
- * @param rgb RGB(A) color
- * @param alpha Include alpha channel? _(defaults to `false`)_
- * @returns Hex color
+ * Convert an _RGB(A)_ color to a hex color _(with optional alpha channel, i.e., opacity)_
+ *
+ * _If the value is unable to be converted, a black hex color will be returned_
+ *
+ * @param rgb _RGB(A)_ color
+ * @param alpha Include alpha channel _(opacity)_? _(defaults to `false`)_
+ * @returns Hex color string
  */
 export function rgbToHex(rgb: RGBAColor | RGBColor, alpha?: boolean): string {
 	return convertRgbToHex(isRgbLike(rgb) ? getRgbValue(rgb) : {...DEFAULT_RGB}, alpha ?? false);
 }
 
 /**
- * Convert an RGB(A) color to an HSL color
+ * Convert an _RGB(A)_ color to an _HSL_ color
+ *
+ * _If the value is unable to be converted, a black HSL color will be returned_
  *
- * Thanks, https://github.com/color-js/color.js/blob/main/src/spaces/hsl.js#L26
- * @param rgb RGB(A) color
- * @returns HSL color
+ * _Thanks, https://github.com/color-js/color.js/blob/main/src/spaces/hsl.js#L26_
+ *
+ * @param rgb _RGB(A)_ color
+ * @returns _HSL_ color
  */
 export function rgbToHsl(rgb: RGBAColor | RGBColor): HSLColor {
 	const {hue, lightness, saturation} = convertRgbToHsla(rgb);
@@ -104,11 +110,14 @@ export function rgbToHsl(rgb: RGBAColor | RGBColor): HSLColor {
 }
 
 /**
- * Convert an RGB(A) color to an HSLA color
+ * Convert an _RGB(A)_ color to an _HSLA_ color
+ *
+ * _If the value is unable to be converted, a black _HSLA_ color with an alpha channel (opacity) of `0` will be returned_
+ *
+ * _Thanks, https://github.com/color-js/color.js/blob/main/src/spaces/hsl.js#L26_
  *
- * Thanks, https://github.com/color-js/color.js/blob/main/src/spaces/hsl.js#L26
- * @param rgb RGB(A) color
- * @returns HSLA color
+ * @param rgb _RGB(A)_ color
+ * @returns _HSLA_ color
  */
 export function rgbToHsla(rgb: RGBAColor | RGBColor): HSLAColor {
 	return convertRgbToHsla(rgb);

package/src/function/assert.ts

@@ -4,7 +4,7 @@ import type {Constructor, NestedKeys, NestedValue, PlainObject} from '../models'
 // #region Types
 
 /**
- * Asserter for a nested property of a value
+ * Asserter for a property of a value
  */
 export type AssertProperty<
 	Value extends PlainObject,
@@ -33,6 +33,7 @@ type NestedPick<Value, Path extends string> = Value extends PlainObject
 
 /**
  * Asserts that a condition is true, throwing an error if it is not
+ *
  * @param condition Condition to assert
  * @param message Error message
  * @param error Error constructor _(defaults to `Error`)_
@@ -54,13 +55,14 @@ assert.is = assertIs;
 assert.property = assertProperty;
 
 /**
- * Creates an asserter that asserts a condition is true, throwing an error if it is not
+ * Creates an _Asserter_ that asserts a condition is true, throwing an error if it is not
+ *
+ * _Available as `assertCondition` and `assert.condition`_
  *
- * Available as `assertCondition` and `assert.condition`
  * @param condition Condition to assert
  * @param message Error message
  * @param error Error constructor _(defaults to `Error`)_
- * @returns Asserter
+ * @returns _Asserter_
  */
 export function assertCondition<Value>(
 	condition: (value: unknown) => boolean,
@@ -75,7 +77,8 @@ export function assertCondition<Value>(
 /**
  * Asserts that a value is defined, throwing an error if it is not
  *
- * Available as `assertDefined` and `assert.defined`
+ * _Available as `assertDefined` and `assert.defined`_
+ *
  * @param value Value to assert
  * @param message Error message
  * @param error Error constructor _(defaults to `Error`)_
@@ -89,13 +92,14 @@ export function assertDefined<Value>(
 }
 
 /**
- * Creates an asserter that asserts a value is an instance of a constructor, throwing an error if it is not
+ * Creates an _Asserter_ that asserts a value is an instance of a constructor, throwing an error if it is not
+ *
+ * _Available as `assertInstanceOf` and `assert.instanceOf`_
  *
- * Available as `assertInstanceOf` and `assert.instanceOf`
  * @param constructor Constructor to check against
  * @param message Error message
  * @param error Error constructor _(defaults to `Error`)_
- * @returns Asserter
+ * @returns _Asserter_
  */
 export function assertInstanceOf<Value>(
 	constructor: Constructor<Value>,
@@ -108,13 +112,14 @@ export function assertInstanceOf<Value>(
 }
 
 /**
- * Creates an asserter that asserts a value is of a specific type, throwing an error if it is not
+ * Creates an _Asserter_ that asserts a value is of a specific type, throwing an error if it is not
+ *
+ * _Available as `assertIs` and `assert.is`_
  *
- * Available as `assertIs` and `assert.is`
  * @param condition Type guard function to check the value
  * @param message Error message
  * @param error Error constructor _(defaults to `Error`)_
- * @returns Asserter
+ * @returns _Asserter_
  */
 export function assertIs<Value>(
 	condition: (value: unknown) => value is Value,
@@ -127,14 +132,15 @@ export function assertIs<Value>(
 }
 
 /**
- * Creates an asserter that asserts a property of a value exists and satisfies a condition, throwing an error if it does not
+ * Creates an _Asserter_ that asserts a property of a value exists and satisfies a condition, throwing an error if it does not
+ *
+ * _Available as `assertProperty` and `assert.property`_
  *
- * Available as `assertProperty` and `assert.property`
  * @param path Path to the property to check, e.g., `foo.bar.baz` for a nested property
  * @param condition Condition to assert for the property
  * @param message Error message
  * @param error Error constructor _(defaults to `Error`)_
- * @returns Asserter
+ * @returns _Asserter_
  */
 export function assertProperty<
 	Value extends PlainObject,

package/src/function/limit.ts

@@ -11,11 +11,11 @@ import type {
 /**
  * Debounce a function, ensuring it is only called after `time` milliseconds have passed
  *
- * When called, successful _(finished)_ results will resolve and errors will reject.
+ * - When called, successful _(finished)_ results will resolve and errors will reject
+ * - On subsequent calls, existing calls will be canceled _(rejected)_, the timer reset, and will wait another `time` milliseconds before the new call is made _(and so on...)_
  *
- * On subsequent calls, existing calls will be canceled _(rejected)_, the timer reset, and will wait another `time` milliseconds before the new call is made _(and so on...)_
+ * _Available as `asyncDebounce` and `debounce.async`_
  *
- * Available as `asyncDebounce` and `debounce.async`
  * @param callback Callback to debounce
  * @param time Time in milliseconds to wait before calling the callback _(defaults to `0`; e.g., as soon as possible)_
  * @returns Debounced callback handler with a `cancel` method
@@ -30,11 +30,11 @@ export function asyncDebounce<Callback extends GenericAsyncCallback | GenericCal
 /**
  * Throttle a function, ensuring it is only called once every `time` milliseconds
  *
- * When called, successful _(finished)_ results will resolve and errors will reject.
+ * - When called, successful _(finished)_ results will resolve and errors will reject
+ * - On subsequent calls, existing calls will be canceled _(rejected)_ and will wait until the next valid time to call the callback again _(and so on...)_
  *
- * On subsequent calls, existing calls will be canceled _(rejected)_ and will wait until the next valid time to call the callback again _(and so on...)_
+ * _Available as `asyncThrottle` and `throttle.async`_
  *
- * Available as `asyncThrottle` and `throttle.async`
  * @param callback Callback to throttle
  * @param time Time in milliseconds to wait before calling the callback again _(defaults to `0`; e.g., as soon as possible)_
  * @returns Throttled callback handler with a `cancel` method
@@ -50,6 +50,7 @@ export function asyncThrottle<Callback extends GenericAsyncCallback | GenericCal
  * Debounce a function, ensuring it is only called after `time` milliseconds have passed
  *
  * On subsequent calls, the timer is reset and will wait another `time` milliseconds _(and so on...)_
+ *
  * @param callback Callback to debounce
  * @param time Time in milliseconds to wait before calling the callback _(defaults to `0`; e.g., as soon as possible)_
  * @returns Debounced callback handler with a `cancel` method
@@ -65,6 +66,7 @@ debounce.async = asyncDebounce;
 
 /**
  * Throttle a function, ensuring it is only called once every `time` milliseconds
+ *
  * @param callback Callback to throttle
  * @param time Time in milliseconds to wait before calling the callback again _(defaults to `0`; e.g., as soon as possible)_
  * @returns Throttled callback handler with a `cancel` method

package/src/function/memoize.ts

@@ -6,13 +6,15 @@ import {SizedMap} from '../sized/map';
 // #region Types
 
 /**
- * A memoized function, caching and retrieving results based on the its parameters _(or a custom cache key)_
+ * A _Memoized_ function instance, caching and retrieving results based on the its parameters _(or a custom cache key)_
  */
 class Memoized<Callback extends GenericCallback> {
 	readonly #state: MemoizedState<Callback>;
 
 	/**
 	 * Maximum cache size
+	 *
+	 * @returns Maximum cache size _(or `Number.NaN` if the instance has been destroyed)_
 	 */
 	get maximum(): number {
 		return this.#state.cache?.maximum ?? Number.NaN;
@@ -20,6 +22,8 @@ class Memoized<Callback extends GenericCallback> {
 
 	/**
 	 * Current cache size
+	 *
+	 * @returns Current cache size _(or `Number.NaN` if the instance has been destroyed)_
 	 */
 	get size(): number {
 		return this.#state.cache?.size ?? Number.NaN;
@@ -56,6 +60,7 @@ class Memoized<Callback extends GenericCallback> {
 
 	/**
 	 * Delete a result from the cache
+	 *
 	 * @param key Key to delete
 	 * @returns `true` if the key existed and was removed, otherwise `false`
 	 */
@@ -64,7 +69,9 @@ class Memoized<Callback extends GenericCallback> {
 	}
 
 	/**
-	 * Destroy the instance _(clearing its cache and removing its callback)_
+	 * Destroy the instance
+	 *
+	 * _(When a Memoized instance is destroyed, its cache and callback are removed, and calls to `run` will throw an error)_
 	 */
 	destroy(): void {
 		this.#state.cache?.clear();
@@ -75,6 +82,7 @@ class Memoized<Callback extends GenericCallback> {
 
 	/**
 	 * Get a result from the cache
+	 *
 	 * @param key Key to get
 	 * @returns Cached result or `undefined` if it does not exist
 	 */
@@ -84,6 +92,7 @@ class Memoized<Callback extends GenericCallback> {
 
 	/**
 	 * Does the result exist?
+	 *
 	 * @param key Key to check
 	 * @returns `true` if the result exists, otherwise `false`
 	 */
@@ -93,12 +102,13 @@ class Memoized<Callback extends GenericCallback> {
 
 	/**
 	 * Run the callback with the provided parameters
+	 *
 	 * @param parameters Parameters to pass to the callback
 	 * @returns Cached or computed _(then cached)_ result
 	 */
 	run(...parameters: Parameters<Callback>): ReturnType<Callback> {
 		if (this.#state.cache == null || this.#state.getter == null) {
-			throw new Error('The Memoized instance has been destroyed');
+			throw new Error(MEMOIZED_ERROR_DESTROYED);
 		}
 
 		return this.#state.getter(...parameters);
@@ -106,7 +116,7 @@ class Memoized<Callback extends GenericCallback> {
 }
 
 /**
- * Options for memoized functions
+ * Options for a _Memoized_ function
  */
 type MemoizedOptions<Callback extends GenericCallback> = {
 	/**
@@ -146,14 +156,19 @@ function getMemoizationOptions<Callback extends GenericCallback>(
 
 /**
  * Memoize a function, caching and retrieving results based on the first parameter
+ *
  * @param callback Callback to memoize
  * @param options Memoization options
- * @returns Memoized instance
+ * @returns _Memoized_ instance
  */
 export function memoize<Callback extends GenericCallback>(
 	callback: Callback,
 	options?: MemoizedOptions<Callback>,
 ): Memoized<Callback> {
+	if (typeof callback !== 'function') {
+		throw new TypeError(MEMOIZED_ERROR_CALLBACK);
+	}
+
 	return new Memoized(callback, getMemoizationOptions(options));
 }
 
@@ -163,6 +178,10 @@ export function memoize<Callback extends GenericCallback>(
 
 const DEFAULT_CACHE_SIZE = 1024;
 
+const MEMOIZED_ERROR_CALLBACK = 'Memoized requires a callback function';
+
+const MEMOIZED_ERROR_DESTROYED = 'The Memoized instance has been destroyed';
+
 const SEPARATOR = '_';
 
 // #endregion

package/src/function/once.ts

@@ -32,9 +32,10 @@ type OnceState<Value> = {
 /**
  * Create an asynchronous function that can only be called once, rejecting or resolving the same result on subsequent calls
  *
- * Available as `asyncOnce` and `once.async`
+ * _Available as `asyncOnce` and `once.async`_
+ *
  * @param callback Callback to use once
- * @returns Once callback
+ * @returns _Once_ callback
  */
 export function asyncOnce<Callback extends GenericAsyncCallback>(
 	callback: Callback,
@@ -132,8 +133,9 @@ function handleOnceResult<Value>(
 
 /**
  * Create a function that can only be called once, returning the same value on subsequent calls
+ *
  * @param callback Callback to use once
- * @returns Once callback
+ * @returns _Once_ callback
  */
 export function once<Callback extends GenericCallback>(callback: Callback): OnceCallback<Callback> {
 	assert(() => typeof callback === 'function', ONCE_MESSAGE_EXPECTATION);

package/src/function/retry.ts

@@ -31,7 +31,8 @@ export type RetryOptions = {
 /**
  * Retry a callback a specified number of times, with a delay between attempts
  *
- * Available as `asyncRetry` and `retry.async`
+ * _Available as `asyncRetry` and `retry.async`_
+ *
  * @param callback Callback to retry
  * @param options Retry options
  * @returns Callback result
@@ -44,7 +45,8 @@ async function asyncRetry<Callback extends GenericAsyncCallback>(
 /**
  * Retry a callback a specified number of times, with a delay between attempts
  *
- * Available as `asyncRetry` and `retry.async`
+ * _Available as `asyncRetry` and `retry.async`_
+ *
  * @param callback Callback to retry
  * @param options Retry options
  * @returns Callback result
@@ -57,7 +59,8 @@ async function asyncRetry<Callback extends GenericCallback>(
 /**
  * Retry a callback a specified number of times, with a delay between attempts
  *
- * Available as `asyncRetry` and `retry.async`
+ * _Available as `asyncRetry` and `retry.async`_
+ *
  * @param callback Callback to retry
  * @param options Retry options
  * @returns Callback result
@@ -119,6 +122,7 @@ function getRetryOptions(input?: RetryOptions): Required<RetryOptions> {
 
 /**
  * Retry a callback a specified number of times
+ *
  * @param callback Callback to retry
  * @param options Retry options
  * @returns Callback result