@oscarpalmer/atoms 0.191.0 → 0.193.0

package/src/color/space/hex.ts

@@ -1,16 +1,11 @@
 import {join} from '../../internal/string';
 import {
-	ALPHA_FULL_HEX_LONG,
-	ALPHA_FULL_HEX_SHORT,
-	EXPRESSION_HEX_LONG,
-	EXPRESSION_PREFIX,
-	HEX_BLACK,
-	LENGTH_LONG,
-	LENGTH_SHORT,
-	MAX_HEX,
-	TYPE_HSL,
-	TYPE_HWB,
-	TYPE_RGB,
+	COLOR_ALPHA,
+	COLOR_DEFAULTS,
+	COLOR_EXPRESSION,
+	COLOR_LENGTHS,
+	COLOR_MAX,
+	COLOR_TYPE,
 } from '../constants';
 import {getHexValue, getPercentage} from '../misc/get';
 import {isHexColor} from '../misc/is';
@@ -30,7 +25,7 @@ import {convertRgbToHsla, convertRgbToHwba} from './rgb';
 
 function convertHexToRgba(value: string): RGBAColor {
 	const normalized = getNormalizedHex(value, true);
-	const pairs = EXPRESSION_HEX_LONG.exec(normalized) as RegExpExecArray;
+	const pairs = COLOR_EXPRESSION.hexLong.exec(normalized) as RegExpExecArray;
 	const values: number[] = [];
 
 	const {length} = pairs;
@@ -40,7 +35,7 @@ function convertHexToRgba(value: string): RGBAColor {
 	}
 
 	return {
-		alpha: getPercentage((values[3] / MAX_HEX) * 100),
+		alpha: getPercentage((values[3] / COLOR_MAX.hex) * 100),
 		blue: getHexValue(values[2]),
 		green: getHexValue(values[1]),
 		red: getHexValue(values[0]),
@@ -52,15 +47,15 @@ export function getColorFromHex<Type extends ColorType>(
 	type: Type,
 ): NonNullable<ColorState[Type]> {
 	switch (type) {
-		case TYPE_HSL:
+		case COLOR_TYPE.hsl:
 			state.hsl ??= hexToHsl(state.hex!);
 			break;
 
-		case TYPE_HWB:
+		case COLOR_TYPE.hwb:
 			state.hwb ??= hexToHwb(state.hex!);
 			break;
 
-		case TYPE_RGB:
+		case COLOR_TYPE.rgb:
 			state.rgb ??= hexToRgb(state.hex!);
 			break;
 	}
@@ -81,21 +76,21 @@ export function getNormalizedHex(value: unknown, alpha?: boolean): string {
 	const includeAlpha = alpha ?? false;
 
 	if (!isHexColor(value)) {
-		return `${HEX_BLACK}${includeAlpha ? ALPHA_FULL_HEX_LONG : ''}`;
+		return `${COLOR_DEFAULTS.hexBlack}${includeAlpha ? COLOR_ALPHA.fullHexLong : ''}`;
 	}
 
-	const normalized = value.replace(EXPRESSION_PREFIX, '');
+	const normalized = value.replace(COLOR_EXPRESSION.prefix, '');
 
-	if (normalized.length < LENGTH_LONG) {
-		const hex = normalized.slice(0, LENGTH_SHORT);
-		const a = includeAlpha ? (normalized[LENGTH_SHORT] ?? ALPHA_FULL_HEX_SHORT) : '';
+	if (normalized.length < COLOR_LENGTHS.hexLong) {
+		const hex = normalized.slice(0, COLOR_LENGTHS.hexShort);
+		const a = includeAlpha ? (normalized[COLOR_LENGTHS.hexShort] ?? COLOR_ALPHA.fullHexShort) : '';
 
 		return join(`${hex}${a}`.split('').map(character => character.repeat(2)));
 	}
 
-	const hex = normalized.slice(0, LENGTH_LONG);
+	const hex = normalized.slice(0, COLOR_LENGTHS.hexLong);
 
-	const a = includeAlpha ? normalized.slice(LENGTH_LONG) || ALPHA_FULL_HEX_LONG : '';
+	const a = includeAlpha ? normalized.slice(COLOR_LENGTHS.hexLong) || COLOR_ALPHA.fullHexLong : '';
 
 	return `${hex}${a}`;
 }

package/src/color/space/hsl.ts

@@ -1,12 +1,4 @@
-import {
-	DEFAULT_HSL,
-	MAX_DEGREE,
-	MAX_HEX,
-	MAX_PERCENT,
-	TYPE_HEX,
-	TYPE_HWB,
-	TYPE_RGB,
-} from '../constants';
+import {COLOR_DEFAULTS, COLOR_MAX, COLOR_TYPE} from '../constants';
 import {getAlphaValue} from '../misc/alpha';
 import {getDegrees, getHexValue, getPercentage} from '../misc/get';
 import {isHslLike} from '../misc/is';
@@ -25,12 +17,12 @@ import {convertRgbToHex} from './rgb';
 // #region Functions
 
 function convertHslToHwba(input: unknown): HWBAColor {
-	const hsl = isHslLike(input) ? getHslValue(input) : {...DEFAULT_HSL};
+	const hsl = isHslLike(input) ? getHslValue(input) : {...COLOR_DEFAULTS.hsl};
 
 	let {hue, lightness, saturation} = hsl;
 
-	lightness /= MAX_PERCENT;
-	saturation /= MAX_PERCENT;
+	lightness /= COLOR_MAX.percent;
+	saturation /= COLOR_MAX.percent;
 
 	const value = lightness + saturation * Math.min(lightness, 1 - lightness);
 
@@ -45,21 +37,21 @@ function convertHslToHwba(input: unknown): HWBAColor {
 
 	return {
 		hue,
-		whiteness: whiteness * MAX_PERCENT,
-		blackness: blackness * MAX_PERCENT,
-		alpha: getAlphaValue((input as HSLAColor)?.alpha ?? MAX_PERCENT),
+		whiteness: whiteness * COLOR_MAX.percent,
+		blackness: blackness * COLOR_MAX.percent,
+		alpha: getAlphaValue((input as HSLAColor)?.alpha ?? COLOR_MAX.percent),
 	};
 }
 
 function convertHslToRgba(input: unknown): RGBAColor {
-	const hsl = isHslLike(input) ? getHslValue(input) : {...DEFAULT_HSL};
+	const hsl = isHslLike(input) ? getHslValue(input) : {...COLOR_DEFAULTS.hsl};
 
-	const hue = hsl.hue % MAX_DEGREE;
-	const saturation = hsl.saturation / MAX_PERCENT;
-	const lightness = hsl.lightness / MAX_PERCENT;
+	const hue = hsl.hue % COLOR_MAX.degree;
+	const saturation = hsl.saturation / COLOR_MAX.percent;
+	const lightness = hsl.lightness / COLOR_MAX.percent;
 
 	return {
-		alpha: getAlphaValue((input as HSLAColor)?.alpha ?? MAX_PERCENT),
+		alpha: getAlphaValue((input as HSLAColor)?.alpha ?? COLOR_MAX.percent),
 		blue: getHexValue(getHexyValue(hue, lightness, saturation, 4)),
 		green: getHexValue(getHexyValue(hue, lightness, saturation, 8)),
 		red: getHexValue(getHexyValue(hue, lightness, saturation, 0)),
@@ -71,15 +63,15 @@ export function getColorFromHsl<Type extends ColorType>(
 	type: Type,
 ): NonNullable<ColorState[Type]> {
 	switch (type) {
-		case TYPE_HEX:
+		case COLOR_TYPE.hex:
 			state.hex = hslToHex(state.hsl!);
 			break;
 
-		case TYPE_HWB:
+		case COLOR_TYPE.hwb:
 			state.hwb = hslToHwb(state.hsl!);
 			break;
 
-		case TYPE_RGB:
+		case COLOR_TYPE.rgb:
 			state.rgb = hslToRgb(state.hsl!);
 			break;
 	}
@@ -91,7 +83,7 @@ function getHexyValue(hue: number, lightness: number, saturation: number, value:
 	const part = (value + hue / 30) % 12;
 	const mod = saturation * Math.min(lightness, 1 - lightness);
 
-	return (lightness - mod * Math.max(-1, Math.min(part - 3, 9 - part, 1))) * MAX_HEX;
+	return (lightness - mod * Math.max(-1, Math.min(part - 3, 9 - part, 1))) * COLOR_MAX.hex;
 }
 
 export function getHslValue(value: Record<keyof HSLColor, unknown>): HSLColor {

package/src/color/space/hwb.ts

@@ -1,4 +1,4 @@
-import {DEFAULT_HWB, MAX_PERCENT, TYPE_HEX, TYPE_HSL, TYPE_RGB} from '../constants';
+import {COLOR_DEFAULTS, COLOR_MAX, COLOR_TYPE} from '../constants';
 import {getAlphaValue} from '../misc/alpha';
 import {getDegrees, getPercentage} from '../misc/get';
 import {isHwbLike} from '../misc/is';
@@ -18,10 +18,10 @@ import {rgbToHex} from './rgb';
 // #region Functions
 
 export function convertHwbToHsl(input: HWBAColor | HWBColor): HSLAColor {
-	let {blackness, hue, whiteness} = isHwbLike(input) ? getHwbValue(input) : DEFAULT_HWB;
+	let {blackness, hue, whiteness} = isHwbLike(input) ? getHwbValue(input) : COLOR_DEFAULTS.hwb;
 
-	blackness /= MAX_PERCENT;
-	whiteness /= MAX_PERCENT;
+	blackness /= COLOR_MAX.percent;
+	whiteness /= COLOR_MAX.percent;
 
 	if (blackness + whiteness > 1) {
 		const total = blackness + whiteness;
@@ -36,9 +36,9 @@ export function convertHwbToHsl(input: HWBAColor | HWBColor): HSLAColor {
 
 	return {
 		hue,
-		saturation: saturation * MAX_PERCENT,
-		lightness: lightness * MAX_PERCENT,
-		alpha: getAlphaValue((input as HWBAColor)?.alpha ?? MAX_PERCENT),
+		saturation: saturation * COLOR_MAX.percent,
+		lightness: lightness * COLOR_MAX.percent,
+		alpha: getAlphaValue((input as HWBAColor)?.alpha ?? COLOR_MAX.percent),
 	};
 }
 
@@ -47,15 +47,15 @@ export function getColorFromHwb<Type extends ColorType>(
 	type: Type,
 ): NonNullable<ColorState[Type]> {
 	switch (type) {
-		case TYPE_HEX:
+		case COLOR_TYPE.hex:
 			state.hex = hwbToHex(state.hwb!);
 			break;
 
-		case TYPE_HSL:
+		case COLOR_TYPE.hsl:
 			state.hsl = hwbToHsl(state.hwb!);
 			break;
 
-		case TYPE_RGB:
+		case COLOR_TYPE.rgb:
 			state.rgb = hwbToRgb(state.hwb!);
 			break;
 	}

package/src/color/space/rgb.ts

@@ -1,5 +1,5 @@
 import {join} from '../../internal/string';
-import {DEFAULT_RGB, MAX_HEX, MAX_PERCENT, TYPE_HEX, TYPE_HSL, TYPE_HWB} from '../constants';
+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';
@@ -48,7 +48,7 @@ export function convertRgbToHex(rgb: RGBAColor | RGBColor, alpha: boolean): stri
 }
 
 export function convertRgbToHsla(value: unknown): HSLAColor {
-	const rgb = isRgbLike(value) ? getRgbValue(value) : {...DEFAULT_RGB};
+	const rgb = isRgbLike(value) ? getRgbValue(value) : {...COLOR_DEFAULTS.rgb};
 	const values = getRgbValues(rgb);
 
 	const {delta, max, min} = values;
@@ -68,14 +68,14 @@ export function convertRgbToHsla(value: unknown): HSLAColor {
 
 	return {
 		hue,
-		saturation: saturation * MAX_PERCENT,
-		lightness: lightness * MAX_PERCENT,
-		alpha: getAlphaValue((value as RGBAColor)?.alpha ?? MAX_PERCENT),
+		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) : {...DEFAULT_RGB};
+	const rgb = isRgbLike(value) ? getRgbValue(value) : {...COLOR_DEFAULTS.rgb};
 	const values = getRgbValues(rgb);
 
 	const {delta, max, min} = values;
@@ -90,9 +90,9 @@ export function convertRgbToHwba(value: unknown): HWBAColor {
 
 	return {
 		hue,
-		whiteness: min * MAX_PERCENT,
-		blackness: (1 - max) * MAX_PERCENT,
-		alpha: getAlphaValue((value as RGBAColor)?.alpha ?? MAX_PERCENT),
+		whiteness: min * COLOR_MAX.percent,
+		blackness: (1 - max) * COLOR_MAX.percent,
+		alpha: getAlphaValue((value as RGBAColor)?.alpha ?? COLOR_MAX.percent),
 	};
 }
 
@@ -101,15 +101,15 @@ export function getColorFromRgb<Type extends ColorType>(
 	type: Type,
 ): NonNullable<ColorState[Type]> {
 	switch (type) {
-		case TYPE_HEX:
+		case COLOR_TYPE.hex:
 			state.hex = rgbToHex(state.rgb!);
 			break;
 
-		case TYPE_HSL:
+		case COLOR_TYPE.hsl:
 			state.hsl = rgbToHsl(state.rgb!);
 			break;
 
-		case TYPE_HWB:
+		case COLOR_TYPE.hwb:
 			state.hwb = rgbToHwb(state.rgb!);
 			break;
 	}
@@ -141,9 +141,9 @@ export function getRgbValue(value: Record<keyof RGBColor, unknown>): RGBColor {
 }
 
 function getRgbValues(rgb: RGBColor): RgbValues {
-	const blue = rgb.blue / MAX_HEX;
-	const green = rgb.green / MAX_HEX;
-	const red = rgb.red / MAX_HEX;
+	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);
@@ -163,7 +163,10 @@ function getRgbValues(rgb: RGBColor): RgbValues {
  * @returns Hex color string
  */
 export function rgbToHex(rgb: RGBAColor | RGBColor, alpha?: boolean): string {
-	return convertRgbToHex(isRgbLike(rgb) ? getRgbValue(rgb) : {...DEFAULT_RGB}, alpha ?? false);
+	return convertRgbToHex(
+		isRgbLike(rgb) ? getRgbValue(rgb) : {...COLOR_DEFAULTS.rgb},
+		alpha ?? false,
+	);
 }
 
 /**

package/src/herald.ts

@@ -1,5 +1,5 @@
 import {noop} from './internal/function/misc';
-import type {GenericCallback} from './models';
+import type {GenericCallback, Unsubscriber} from './models';
 
 // #region Types
 
@@ -57,8 +57,6 @@ export type Herald<Map extends Record<string, GenericCallback>> = {
 	unsubscribe<Event extends keyof Map>(event: Event, callback?: Map[Event]): void;
 };
 
-export type Unsubscriber = () => void;
-
 // #endregion
 
 // #region Functions

package/src/index.ts

@@ -21,6 +21,7 @@ export * from './herald';
 
 export * from './internal/function/misc';
 export * from './internal/string';
+export {isSubscription, type Subscription} from './internal/subscription';
 export * from './internal/value/compare';
 export * from './internal/value/equal';
 export * from './internal/value/get';

package/src/internal/subscription.ts

@@ -0,0 +1,264 @@
+import type {Key} from '../models';
+import {isPlainObject} from './is';
+
+// #region Types
+
+export type Subscription = {
+	/**
+	 * Is the subscription active?
+	 */
+	get active(): boolean;
+
+	/**
+	 * Unsubscribe from changes
+	 */
+	unsubscribe(): void;
+};
+
+export type SubscriptionParameters = {
+	isActive?: () => boolean;
+	key?: Key;
+	property: SubscriptionProperty;
+	subscriptions: Subscriptions;
+	value: unknown;
+};
+
+export type SubscriptionProperty = {
+	key: string;
+	value: unknown;
+};
+
+type SubscriptionState = {
+	active: boolean;
+	parameters: SubscriptionParameters;
+};
+
+export type Subscriptions<Value = unknown> = {
+	items: SubscriptionsItems;
+	keys?: Set<Key>;
+	values: SubscriptionsValues<Value>;
+};
+
+type SubscriptionsItems = {
+	any: Set<Subscription>;
+	keyed?: Map<Key, Set<Subscription>>;
+};
+
+type SubscriptionsValues<Value = unknown> = {
+	from: SubscriptionsValuesItem<Value, Subscription>;
+	to: SubscriptionsValuesItem<Subscription, Value>;
+};
+
+type SubscriptionsValuesItem<MapKey, MapValue> = {
+	any: Map<MapKey, MapValue>;
+	keyed?: Map<Key, Map<MapKey, MapValue>>;
+};
+
+// #endregion
+
+// #region Functions
+
+function addSubscription(subscription: Subscription, state: SubscriptionState): void {
+	const {key, subscriptions, value} = state.parameters;
+	const {items, values} = subscriptions;
+
+	if (key == null) {
+		items.any.add(subscription);
+		values.from.any.set(value, subscription);
+		values.to.any.set(subscription, value);
+
+		return;
+	}
+
+	if (items.keyed == null || values.from.keyed == null || values.to.keyed == null) {
+		// TODO: fix tests or document
+		// istanbul ignore next
+		return;
+	}
+
+	let keyedItems = items.keyed.get(key);
+
+	if (keyedItems == null) {
+		keyedItems = new Set();
+
+		items.keyed.set(key, keyedItems);
+	}
+
+	keyedItems.add(subscription);
+
+	let keyedFrom = values.from.keyed.get(key);
+
+	if (keyedFrom == null) {
+		keyedFrom = new Map();
+
+		values.from.keyed.set(key, keyedFrom);
+	}
+
+	keyedFrom.set(value, subscription);
+
+	let keyedTo = values.to.keyed.get(key);
+
+	if (keyedTo == null) {
+		keyedTo = new Map();
+
+		values.to.keyed.set(key, keyedTo);
+	}
+
+	keyedTo.set(subscription, value);
+}
+
+export function clearSubscriptions(store: Subscriptions): void {
+	for (const susbcription of store.values.to.any.keys()) {
+		susbcription.unsubscribe();
+	}
+
+	if (store.values.to.keyed != null) {
+		for (const values of store.values.to.keyed.values()) {
+			for (const susbcription of values.keys()) {
+				susbcription.unsubscribe();
+			}
+		}
+	}
+}
+
+function getExistingSubscription(state: SubscriptionState): Subscription | undefined {
+	const {parameters} = state;
+	const {values} = parameters.subscriptions;
+
+	return parameters.key == null
+		? values.from.any.get(parameters.value)
+		: values.from.keyed?.get(parameters.key)?.get(parameters.value);
+}
+
+export function getSubscription(parameters: SubscriptionParameters): Subscription {
+	const state: SubscriptionState = {
+		parameters,
+		active: true,
+	};
+
+	const existing = getExistingSubscription(state);
+
+	if (existing != null) {
+		return existing;
+	}
+
+	if (
+		parameters.subscriptions.keys != null &&
+		parameters.key != null &&
+		!parameters.subscriptions.keys.has(parameters.key)
+	) {
+		throw new Error();
+	}
+
+	const instance = {
+		unsubscribe: () => {
+			removeSubscription(instance as Subscription, state);
+		},
+	};
+
+	Object.defineProperties(instance, {
+		[PROPERTY]: {
+			enumerable: false,
+			value: true,
+		},
+		[parameters.property.key]: {
+			enumerable: false,
+			value: parameters.property.value,
+		},
+		active: {
+			enumerable: true,
+			get: () => (parameters.isActive?.() ?? true) && state.active,
+		},
+	});
+
+	addSubscription(instance as Subscription, state);
+
+	return Object.freeze(instance) as Subscription;
+}
+
+export function getSubscriptions<Value = unknown>(keys?: Set<Key>): Subscriptions<Value> {
+	return {
+		keys,
+		items: {
+			any: new Set(),
+			keyed: keys == null ? undefined : new Map(),
+		},
+		values: {
+			from: {
+				any: new Map(),
+				keyed: keys == null ? undefined : new Map(),
+			},
+			to: {
+				any: new Map(),
+				keyed: keys == null ? undefined : new Map(),
+			},
+		},
+	};
+}
+
+/**
+ * Is the value a subscription?
+ *
+ * @param value Value to check
+ * @returns `true` if the value is a subscription, otherwise `false`
+ */
+export function isSubscription(value: unknown): value is Subscription {
+	return isPlainObject(value) && PROPERTY in value && value[PROPERTY] === true;
+}
+
+function removeFromStore(
+	items: Set<Subscription>,
+	values: SubscriptionsValues,
+	subscription: Subscription,
+	value: unknown,
+	key?: Key,
+): void {
+	items.delete(subscription);
+
+	if (key == null) {
+		values.from.any.delete(value);
+		values.to.any.delete(subscription);
+	} else {
+		values.from.keyed?.get(key)?.delete(value);
+		values.to.keyed?.get(key)?.delete(subscription);
+	}
+}
+
+function removeSubscription(subscription: Subscription, state: SubscriptionState): void {
+	if (!state.active) {
+		return;
+	}
+
+	state.active = false;
+
+	const {key, subscriptions, value} = state.parameters;
+	const {items, values} = subscriptions;
+
+	if (key == null) {
+		removeFromStore(items.any, values, subscription, value);
+
+		return;
+	}
+
+	const keyed = items.keyed?.get(key);
+
+	if (items.keyed == null || keyed == null) {
+		// TODO, fix tests or document
+		// istanbul ignore next
+		return;
+	}
+
+	removeFromStore(keyed, values, subscription, value, key);
+
+	if (keyed.size === 0) {
+		items.keyed.delete(key);
+	}
+}
+
+// #endregion
+
+// #region Variables
+
+const PROPERTY = '$subscription';
+
+// #endregion

package/src/models.ts

@@ -278,4 +278,9 @@ export type UnionToIntersection<Union> = (
 	? Intersection & Union
 	: never;
 
+/**
+ * A function that unsubscribes from a subscription
+ */
+export type Unsubscriber = () => void;
+
 // #endregion