@oscarpalmer/atoms 0.192.0 → 0.193.1

package/src/color/space/rgb.ts

@@ -1,240 +0,0 @@
-import {join} from '../../internal/string';
-import {COLOR_DEFAULTS, COLOR_MAX, COLOR_TYPE} from '../constants';
-import {getAlpha, getAlphaValue} from '../misc/alpha';
-import {getHexValue} from '../misc/get';
-import {isRgbLike} from '../misc/is';
-import type {
-	ColorState,
-	ColorType,
-	HSLAColor,
-	HSLColor,
-	HWBAColor,
-	HWBColor,
-	RGBAColor,
-	RGBColor,
-} from '../models';
-
-// #region Types
-
-type RgbValues = {
-	blue: number;
-	delta: number;
-	green: number;
-	max: number;
-	min: number;
-	red: number;
-};
-
-// #endregion
-
-// #region Functions
-
-export function convertRgbToHex(rgb: RGBAColor | RGBColor, alpha: boolean): string {
-	const hex = `${join(
-		[rgb.red, rgb.green, rgb.blue].map(color => {
-			const hexString = color.toString(16);
-
-			return hexString.length === 1 ? `0${hexString}` : hexString;
-		}),
-	)}`;
-
-	let a = '';
-
-	if (typeof alpha === 'boolean' && alpha) {
-		a = getAlpha((rgb as RGBAColor).alpha, false).hex;
-	}
-
-	return `${hex}${a}`;
-}
-
-export function convertRgbToHsla(value: unknown): HSLAColor {
-	const rgb = isRgbLike(value) ? getRgbValue(value) : {...COLOR_DEFAULTS.rgb};
-	const values = getRgbValues(rgb);
-
-	const {delta, max, min} = values;
-
-	const lightness = (min + max) / 2;
-
-	let hue = 0;
-	let saturation = 0;
-
-	if (delta !== 0) {
-		saturation = (max - lightness) / Math.min(lightness, 1 - lightness);
-
-		hue = getRgbHue(values);
-
-		hue *= 60;
-	}
-
-	return {
-		hue,
-		saturation: saturation * COLOR_MAX.percent,
-		lightness: lightness * COLOR_MAX.percent,
-		alpha: getAlphaValue((value as RGBAColor)?.alpha ?? COLOR_MAX.percent),
-	};
-}
-
-export function convertRgbToHwba(value: unknown): HWBAColor {
-	const rgb = isRgbLike(value) ? getRgbValue(value) : {...COLOR_DEFAULTS.rgb};
-	const values = getRgbValues(rgb);
-
-	const {delta, max, min} = values;
-
-	let hue = 0;
-
-	if (delta !== 0) {
-		hue = getRgbHue(values);
-
-		hue *= 60;
-	}
-
-	return {
-		hue,
-		whiteness: min * COLOR_MAX.percent,
-		blackness: (1 - max) * COLOR_MAX.percent,
-		alpha: getAlphaValue((value as RGBAColor)?.alpha ?? COLOR_MAX.percent),
-	};
-}
-
-export function getColorFromRgb<Type extends ColorType>(
-	state: ColorState,
-	type: Type,
-): NonNullable<ColorState[Type]> {
-	switch (type) {
-		case COLOR_TYPE.hex:
-			state.hex = rgbToHex(state.rgb!);
-			break;
-
-		case COLOR_TYPE.hsl:
-			state.hsl = rgbToHsl(state.rgb!);
-			break;
-
-		case COLOR_TYPE.hwb:
-			state.hwb = rgbToHwb(state.rgb!);
-			break;
-	}
-
-	return state[type]!;
-}
-
-function getRgbHue(values: RgbValues): number {
-	const {blue, delta, green, max, red} = values;
-
-	switch (max) {
-		case blue:
-			return (red - green) / delta + 4;
-
-		case green:
-			return (blue - red) / delta + 2;
-
-		default:
-			return (green - blue) / delta + (green < blue ? 6 : 0);
-	}
-}
-
-export function getRgbValue(value: Record<keyof RGBColor, unknown>): RGBColor {
-	return {
-		blue: getHexValue((value as RGBColor).blue),
-		green: getHexValue((value as RGBColor).green),
-		red: getHexValue((value as RGBColor).red),
-	};
-}
-
-function getRgbValues(rgb: RGBColor): RgbValues {
-	const blue = rgb.blue / COLOR_MAX.hex;
-	const green = rgb.green / COLOR_MAX.hex;
-	const red = rgb.red / COLOR_MAX.hex;
-
-	const max = Math.max(blue, green, red);
-	const min = Math.min(blue, green, red);
-
-	const delta = max - min;
-
-	return {blue, delta, green, max, min, red};
-}
-
-/**
- * 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) : {...COLOR_DEFAULTS.rgb},
-		alpha ?? false,
-	);
-}
-
-/**
- * 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
- */
-export function rgbToHsl(rgb: RGBAColor | RGBColor): HSLColor {
-	const {hue, lightness, saturation} = convertRgbToHsla(rgb);
-
-	return {
-		hue,
-		lightness,
-		saturation,
-	};
-}
-
-/**
- * Convert an _RGB(A)_ color to an _HSLA_ color
- *
- * _If the value is unable to be converted, a black _HSLA_ 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 _HSLA_ color
- */
-export function rgbToHsla(rgb: RGBAColor | RGBColor): HSLAColor {
-	return convertRgbToHsla(rgb);
-}
-
-/**
- * Convert an _RGB(A)_ color to an _HWB_ color
- *
- * _If the value is unable to be converted, a black _HWB_ 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 _HWB_ color
- */
-export function rgbToHwb(rgb: RGBAColor | RGBColor): HWBColor {
-	const {blackness, hue, whiteness} = convertRgbToHwba(rgb);
-
-	return {
-		hue,
-		whiteness,
-		blackness,
-	};
-}
-
-/**
- * Convert an _RGB(A)_ color to an _HWBA_ color
-
- * _If the value is unable to be converted, a black _HWBA_ 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 _HWBA_ color
- */
-export function rgbToHwba(rgb: RGBAColor | RGBColor): HWBAColor {
-	return convertRgbToHwba(rgb);
-}
-
-// #endregion

package/src/function/assert.ts

@@ -1,174 +0,0 @@
-import {hasValueResult} from '../internal/value/has';
-import type {Constructor, NestedKeys, NestedValue, PlainObject} from '../models';
-
-// #region Types
-
-/**
- * Asserter for a property of a value
- */
-export type AssertProperty<
-	Value extends PlainObject,
-	Path extends NestedKeys<Value>,
-	Asserted extends NestedPick<Value, Path> = NestedPick<Value, Path>,
-> = Asserter<Asserted>;
-
-/**
- * A function that asserts a value is of a specific type, throwing an error if it is not
- */
-export type Asserter<Value> = (value: unknown) => asserts value is Value;
-
-type NestedPick<Value, Path extends string> = Value extends PlainObject
-	? Path extends `${infer Head}.${infer Rest}`
-		? Head extends keyof Value
-			? {[Key in Head]: NestedPick<Value[Key], Rest>}
-			: never
-		: Path extends keyof Value
-			? {[Key in Path]: Value[Key]}
-			: never
-	: never;
-
-// #endregion
-
-// #region Functions
-
-/**
- * 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`)_
- */
-export function assert<Condition extends () => boolean>(
-	condition: Condition,
-	message: string,
-	error?: ErrorConstructor,
-): asserts condition {
-	if (!condition()) {
-		throw new (error ?? Error)(message);
-	}
-}
-
-assert.condition = assertCondition;
-assert.defined = assertDefined;
-assert.instanceOf = assertInstanceOf;
-assert.is = assertIs;
-assert.property = assertProperty;
-
-/**
- * Creates an _Asserter_ that asserts a condition is true, throwing an error if it is not
- *
- * _Available as `assertCondition` and `assert.condition`_
- *
- * @param condition Condition to assert
- * @param message Error message
- * @param error Error constructor _(defaults to `Error`)_
- * @returns _Asserter_
- */
-export function assertCondition<Value>(
-	condition: (value: unknown) => boolean,
-	message: string,
-	error?: ErrorConstructor,
-): Asserter<Value> {
-	return value => {
-		assert(() => condition(value), message, error);
-	};
-}
-
-/**
- * Asserts that a value is defined, throwing an error if it is not
- *
- * _Available as `assertDefined` and `assert.defined`_
- *
- * @param value Value to assert
- * @param message Error message
- * @param error Error constructor _(defaults to `Error`)_
- */
-export function assertDefined<Value>(
-	value: unknown,
-	message?: string,
-	error?: ErrorConstructor,
-): asserts value is Exclude<Value, null | undefined> {
-	assert(() => value != null, message ?? MESSAGE_VALUE_DEFINED, error);
-}
-
-/**
- * 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`_
- *
- * @param constructor Constructor to check against
- * @param message Error message
- * @param error Error constructor _(defaults to `Error`)_
- * @returns _Asserter_
- */
-export function assertInstanceOf<Value>(
-	constructor: Constructor<Value>,
-	message: string,
-	error?: ErrorConstructor,
-): Asserter<Value> {
-	return value => {
-		assert(() => value instanceof constructor, message, error);
-	};
-}
-
-/**
- * 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`_
- *
- * @param condition Type guard function to check the value
- * @param message Error message
- * @param error Error constructor _(defaults to `Error`)_
- * @returns _Asserter_
- */
-export function assertIs<Value>(
-	condition: (value: unknown) => value is Value,
-	message: string,
-	error?: ErrorConstructor,
-): Asserter<Value> {
-	return value => {
-		assert(() => condition(value), message, error);
-	};
-}
-
-/**
- * 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`_
- *
- * @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_
- */
-export function assertProperty<
-	Value extends PlainObject,
-	Path extends NestedKeys<Value>,
-	Asserted = NestedPick<Value, Path>,
->(
-	path: Path,
-	condition: (value: NestedValue<Value, Path>) => boolean,
-	message: string,
-	error?: ErrorConstructor,
-): Asserter<Asserted> {
-	return (value: unknown): asserts value is Asserted => {
-		assert(
-			() => {
-				const result = hasValueResult(value as never, path, false);
-
-				return result.ok && condition(result.value as never);
-			},
-			message,
-			error,
-		);
-	};
-}
-
-// #endregion
-
-// #region Variables
-
-const MESSAGE_VALUE_DEFINED = 'Expected value to be defined';
-
-// #endregion

package/src/function/index.ts

@@ -1,2 +0,0 @@
-export {noop} from '../internal/function/misc';
-export {memoize, type Memoized, type MemoizedOptions} from './memoize';

package/src/function/limit.ts

@@ -1,83 +0,0 @@
-import {getAsyncTimer, getTimer, TIMER_DEBOUNCE, TIMER_THROTTLE} from '../internal/function/timer';
-import type {
-	AsyncCancelableCallback,
-	CancelableCallback,
-	GenericAsyncCallback,
-	GenericCallback,
-} from '../models';
-
-// #region Functions
-
-/**
- * Debounce a function, ensuring it is only called after `time` milliseconds have passed
- *
- * - 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...)_
- *
- * _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
- */
-export function asyncDebounce<Callback extends GenericAsyncCallback | GenericCallback>(
-	callback: Callback,
-	time?: number,
-): AsyncCancelableCallback<Callback> {
-	return getAsyncTimer(TIMER_DEBOUNCE, callback, time);
-}
-
-/**
- * Throttle a function, ensuring it is only called once every `time` milliseconds
- *
- * - 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...)_
- *
- * _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
- */
-export function asyncThrottle<Callback extends GenericAsyncCallback | GenericCallback>(
-	callback: Callback,
-	time?: number,
-): AsyncCancelableCallback<Callback> {
-	return getAsyncTimer(TIMER_THROTTLE, callback, time);
-}
-
-/**
- * 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
- */
-export function debounce<Callback extends GenericCallback>(
-	callback: Callback,
-	time?: number,
-): CancelableCallback<Callback> {
-	return getTimer(TIMER_DEBOUNCE, callback, time);
-}
-
-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
- */
-export function throttle<Callback extends GenericCallback>(
-	callback: Callback,
-	time?: number,
-): CancelableCallback<Callback> {
-	return getTimer(TIMER_THROTTLE, callback, time);
-}
-
-throttle.async = asyncThrottle;
-
-// #endregion

package/src/function/memoize.ts

@@ -1,202 +0,0 @@
-import {isPlainObject} from '../internal/is';
-import {getString, join} from '../internal/string';
-import type {GenericCallback} from '../models';
-import {SizedMap} from '../sized/map';
-
-// #region Types
-
-/**
- * A _Memoized_ function instance, caching and retrieving results based on the its parameters _(or a custom cache key)_
- */
-export type Memoized<Callback extends GenericCallback> = {
-	/**
-	 * Maximum cache size
-	 *
-	 * @returns Maximum cache size _(or `Number.NaN` if the instance has been destroyed)_
-	 */
-	get maximum(): number;
-
-	/**
-	 * Current cache size
-	 *
-	 * @returns Current cache size _(or `Number.NaN` if the instance has been destroyed)_
-	 */
-	get size(): number;
-
-	/**
-	 * Clear the cache
-	 */
-	clear(): void;
-
-	/**
-	 * Delete a result from the cache
-	 *
-	 * @param key Key to delete
-	 * @returns `true` if the key existed and was removed, otherwise `false`
-	 */
-	delete(key: unknown): boolean;
-
-	/**
-	 * 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;
-
-	/**
-	 * Get a result from the cache
-	 *
-	 * @param key Key to get
-	 * @returns Cached result or `undefined` if it does not exist
-	 */
-	get(key: unknown): ReturnType<Callback> | undefined;
-
-	/**
-	 * Does the result exist?
-	 *
-	 * @param key Key to check
-	 * @returns `true` if the result exists, otherwise `false`
-	 */
-	has(key: unknown): boolean;
-
-	/**
-	 * 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>;
-};
-
-/**
- * Options for a _Memoized_ function
- */
-export type MemoizedOptions<Callback extends GenericCallback> = {
-	/**
-	 * Callback for getting a cache key for the provided parameters
-	 */
-	cacheKey?: (...parameters: Parameters<Callback>) => unknown;
-	/**
-	 * Size of the cache
-	 */
-	cacheSize?: number;
-};
-
-type MemoizedState<Callback extends GenericCallback> = {
-	cache?: SizedMap<unknown, ReturnType<Callback>>;
-	getter?: (...parameters: Parameters<Callback>) => ReturnType<Callback>;
-	options: Options;
-};
-
-type Options = {
-	cacheKey?: GenericCallback;
-	cacheSize: number;
-};
-
-// #endregion
-
-// #region Functions
-
-function getMemoizationOptions<Callback extends GenericCallback>(
-	input?: MemoizedOptions<Callback>,
-): Options {
-	const {cacheKey, cacheSize} = isPlainObject(input) ? (input as MemoizedOptions<Callback>) : {};
-
-	return {
-		cacheKey: typeof cacheKey === 'function' ? cacheKey : undefined,
-		cacheSize: typeof cacheSize === 'number' && cacheSize > 0 ? cacheSize : DEFAULT_CACHE_SIZE,
-	};
-}
-
-/**
- * Memoize a function, caching and retrieving results based on the first parameter
- *
- * @param callback Callback to memoize
- * @param options Memoization options
- * @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);
-	}
-
-	const state: MemoizedState<Callback> = {
-		options: getMemoizationOptions(options),
-	};
-
-	state.cache = new SizedMap<unknown, ReturnType<Callback>>(state.options.cacheSize);
-
-	state.getter = (...parameters: Parameters<Callback>): ReturnType<Callback> => {
-		const key =
-			state.options.cacheKey?.(...parameters) ??
-			(parameters.length === 1 ? parameters[0] : join(parameters.map(getString), SEPARATOR));
-
-		if (state.cache!.has(key)) {
-			return state.cache!.get(key) as ReturnType<Callback>;
-		}
-
-		const value = callback(...parameters);
-
-		state.cache?.set(key, value);
-
-		return value;
-	};
-
-	const instance = {
-		clear: () => {
-			state.cache?.clear();
-		},
-		delete: (key: unknown) => {
-			return state.cache?.delete(key) ?? false;
-		},
-		destroy: () => {
-			state.cache?.clear();
-
-			state.cache = undefined;
-			state.getter = undefined;
-		},
-		get: (key: unknown) => {
-			return state.cache?.get(key);
-		},
-		has: (key: unknown) => {
-			return state.cache?.has(key) ?? false;
-		},
-		run: (...parameters: Parameters<Callback>) => {
-			if (state.cache == null || state.getter == null) {
-				throw new Error(MEMOIZED_ERROR_DESTROYED);
-			}
-
-			return state.getter(...parameters);
-		},
-	};
-
-	Object.defineProperties(instance, {
-		maximum: {
-			enumerable: true,
-			get: () => state.cache?.maximum ?? Number.NaN,
-		},
-		size: {
-			enumerable: true,
-			get: () => state.cache?.size ?? Number.NaN,
-		},
-	});
-
-	return Object.freeze(instance) as Memoized<Callback>;
-}
-
-// #endregion
-
-// #region Variables
-
-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