@oscarpalmer/atoms 0.190.0 → 0.192.0

package/dist/internal/subscription.d.mts

@@ -0,0 +1,52 @@
+import { Key } from "../models.mjs";
+//#region src/internal/subscription.d.ts
+type Subscription = {
+  /**
+   * Is the subscription active?
+   */
+  get active(): boolean;
+  /**
+   * Unsubscribe from changes
+   */
+  unsubscribe(): void;
+};
+type SubscriptionParameters = {
+  isActive?: () => boolean;
+  key?: Key;
+  property: SubscriptionProperty;
+  subscriptions: Subscriptions;
+  value: unknown;
+};
+type SubscriptionProperty = {
+  key: string;
+  value: unknown;
+};
+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>>;
+};
+declare function clearSubscriptions(store: Subscriptions): void;
+declare function getSubscription(parameters: SubscriptionParameters): Subscription;
+declare function getSubscriptions<Value = unknown>(keys?: Set<Key>): Subscriptions<Value>;
+/**
+ * Is the value a subscription?
+ *
+ * @param value Value to check
+ * @returns `true` if the value is a subscription, otherwise `false`
+ */
+declare function isSubscription(value: unknown): value is Subscription;
+//#endregion
+export { Subscription, SubscriptionParameters, SubscriptionProperty, Subscriptions, clearSubscriptions, getSubscription, getSubscriptions, isSubscription };

package/dist/internal/subscription.mjs

@@ -0,0 +1,127 @@
+import { isPlainObject } from "./is.mjs";
+//#region src/internal/subscription.ts
+function addSubscription(subscription, state) {
+	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)
+ // istanbul ignore next
+	return;
+	let keyedItems = items.keyed.get(key);
+	if (keyedItems == null) {
+		keyedItems = /* @__PURE__ */ new Set();
+		items.keyed.set(key, keyedItems);
+	}
+	keyedItems.add(subscription);
+	let keyedFrom = values.from.keyed.get(key);
+	if (keyedFrom == null) {
+		keyedFrom = /* @__PURE__ */ new Map();
+		values.from.keyed.set(key, keyedFrom);
+	}
+	keyedFrom.set(value, subscription);
+	let keyedTo = values.to.keyed.get(key);
+	if (keyedTo == null) {
+		keyedTo = /* @__PURE__ */ new Map();
+		values.to.keyed.set(key, keyedTo);
+	}
+	keyedTo.set(subscription, value);
+}
+function clearSubscriptions(store) {
+	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) {
+	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);
+}
+function getSubscription(parameters) {
+	const state = {
+		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, 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, state);
+	return Object.freeze(instance);
+}
+function getSubscriptions(keys) {
+	return {
+		keys,
+		items: {
+			any: /* @__PURE__ */ new Set(),
+			keyed: keys == null ? void 0 : /* @__PURE__ */ new Map()
+		},
+		values: {
+			from: {
+				any: /* @__PURE__ */ new Map(),
+				keyed: keys == null ? void 0 : /* @__PURE__ */ new Map()
+			},
+			to: {
+				any: /* @__PURE__ */ new Map(),
+				keyed: keys == null ? void 0 : /* @__PURE__ */ new Map()
+			}
+		}
+	};
+}
+/**
+* Is the value a subscription?
+*
+* @param value Value to check
+* @returns `true` if the value is a subscription, otherwise `false`
+*/
+function isSubscription(value) {
+	return isPlainObject(value) && PROPERTY in value && value[PROPERTY] === true;
+}
+function removeFromStore(items, values, subscription, value, key) {
+	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, state) {
+	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)
+ // istanbul ignore next
+	return;
+	removeFromStore(keyed, values, subscription, value, key);
+	if (keyed.size === 0) items.keyed.delete(key);
+}
+const PROPERTY = "$subscription";
+//#endregion
+export { clearSubscriptions, getSubscription, getSubscriptions, isSubscription };

package/dist/models.d.mts

@@ -156,5 +156,9 @@ type TypedArray = Int8Array | Uint8Array | Uint8ClampedArray | Int16Array | Uint
  * Thanks, type-fest!
  */
 type UnionToIntersection<Union> = (Union extends unknown ? (distributedUnion: Union) => void : never) extends ((mergedIntersection: infer Intersection) => void) ? Intersection & Union : never;
+/**
+ * A function that unsubscribes from a subscription
+ */
+type Unsubscriber = () => void;
 //#endregion
-export { ArrayOrPlainObject, AsyncCancelableCallback, BuiltIns, CancelableCallback, Constructor, EventPosition, GenericAsyncCallback, GenericCallback, Key, KeyedValue, NestedArray, NestedKeys, NestedPartial, NestedValue, NestedValues, NumericalKeys, NumericalValues, OnceAsyncCallback, OnceCallback, PlainObject, Primitive, RequiredKeys, Simplify, ToString, TypedArray, UnionToIntersection };
+export { ArrayOrPlainObject, AsyncCancelableCallback, BuiltIns, CancelableCallback, Constructor, EventPosition, GenericAsyncCallback, GenericCallback, Key, KeyedValue, NestedArray, NestedKeys, NestedPartial, NestedValue, NestedValues, NumericalKeys, NumericalValues, OnceAsyncCallback, OnceCallback, PlainObject, Primitive, RequiredKeys, Simplify, ToString, TypedArray, UnionToIntersection, Unsubscriber };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@oscarpalmer/atoms",
-	"version": "0.190.0",
+	"version": "0.192.0",
 	"description": "Atomic utilities for making your JavaScript better.",
 	"keywords": [
 		"helper",
@@ -257,10 +257,10 @@
 		"watch": "npx vite build --watch"
 	},
 	"devDependencies": {
-		"@oxlint/plugins": "^1.78",
+		"@oxlint/plugins": "^1.79",
 		"@types/node": "^26.2",
-		"@vitest/coverage-istanbul": "4.1.10",
-		"eslint": "^10.8",
+		"@vitest/coverage-istanbul": "^4.1",
+		"eslint": "^10.9",
 		"jsdom": "^30",
 		"tsdown": "^0.22",
 		"typescript": "^6",

package/src/beacon.ts

@@ -1,5 +1,13 @@
 import {noop} from './internal/function/misc';
 import {isPlainObject} from './internal/is';
+import {
+	clearSubscriptions,
+	getSubscription,
+	getSubscriptions,
+	type Subscription,
+	type SubscriptionProperty,
+	type Subscriptions,
+} from './internal/subscription';
 import type {PlainObject} from './models';
 
 // #region Types
@@ -13,11 +21,6 @@ export type Beacon<Value> = {
 	 */
 	get active(): boolean;
 
-	/**
-	 * Is the beacon closed?
-	 */
-	get closed(): boolean;
-
 	/**
 	 * The observable that can be subscribed to
 	 */
@@ -29,9 +32,9 @@ export type Beacon<Value> = {
 	get value(): Value;
 
 	/**
-	 * Close the beacon
+	 * Deactivate the beacon
 	 */
-	close(): void;
+	deactivate(): void;
 
 	/**
 	 * Emit a new value
@@ -55,9 +58,6 @@ export type Beacon<Value> = {
 	finish(): void;
 };
 
-/**
- * Options for Beacon
- */
 export type BeaconOptions<Value> = {
 	/**
 	 * Method for comparing values for equality
@@ -73,8 +73,8 @@ export type BeaconOptions<Value> = {
 type BeaconState<Value> = {
 	active: boolean;
 	observable: Observable<Value>;
-	observers: Map<Subscription, Observer<Value>>;
 	options: Required<BeaconOptions<Value>>;
+	subscriptions: Subscriptions<Observer<unknown>>;
 	value: Value;
 };
 
@@ -85,14 +85,9 @@ export type Observable<Value> = {
 	get active(): boolean;
 
 	/**
-	 * Is the observable closed?
-	 */
-	get closed(): boolean;
-
-	/**
-	 * Close the observable
+	 * Deactivate the observable
 	 */
-	close(): void;
+	deactivate(): void;
 
 	/**
 	 * Subscribe to value changes
@@ -122,9 +117,6 @@ type ObservableState<Value> = {
 	beacon: BeaconState<Value>;
 };
 
-/**
- * An observer receives notifications from an observable
- */
 type Observer<Value> = {
 	/**
 	 * Callback for when the observable is completed
@@ -140,28 +132,6 @@ type Observer<Value> = {
 	next?: (value: Value) => void;
 };
 
-export type Subscription = {
-	/**
-	 * Is the subscription active?
-	 */
-	get active(): boolean;
-
-	/**
-	 * Is the subscription closed?
-	 */
-	get closed(): boolean;
-
-	/**
-	 * Close the subscription
-	 */
-	close(): void;
-
-	/**
-	 * Unsubscribe from its observable
-	 */
-	unsubscribe(): void;
-};
-
 // #endregion
 
 // #region Functions
@@ -178,12 +148,12 @@ export function beacon<Value>(value: Value, options?: BeaconOptions<Value>): Bea
 		value,
 		active: true,
 		observable: undefined as never,
-		observers: new Map(),
 		options: getBeaconOptions(options),
+		subscriptions: getSubscriptions(),
 	};
 
 	const instance = {
-		close: (): void => {
+		deactivate: (): void => {
 			finishBeacon(state, false);
 		},
 		emit: (value: Value, finish?: boolean): void => {
@@ -206,10 +176,6 @@ export function beacon<Value>(value: Value, options?: BeaconOptions<Value>): Bea
 			enumerable: true,
 			get: () => state.active,
 		},
-		closed: {
-			enumerable: true,
-			get: () => !state.active,
-		},
 		observable: {
 			enumerable: true,
 			get: () => {
@@ -238,21 +204,15 @@ function finishBeacon<Value>(state: BeaconState<Value>, emit: boolean): void {
 
 	state.active = false;
 
-	const entries = [...state.observers.entries()];
-	const {length} = entries;
-
-	for (let index = 0; index < length; index += 1) {
-		const [subscription, observer] = entries[index];
-
+	for (const [, observer] of state.subscriptions.values.to.any) {
 		if (emit) {
 			observer.complete?.();
 		}
-
-		subscription.close();
 	}
 
-	state.observable?.close();
-	state.observers.clear();
+	clearSubscriptions(state.subscriptions);
+
+	state.observable?.deactivate();
 
 	state.observable = undefined as never;
 }
@@ -317,16 +277,6 @@ export function isObservable<Value = unknown>(value: unknown): value is Observab
 	return isBeaconInstance<Observable<Value>>(NAME_OBSERVABLE, value);
 }
 
-/**
- * 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 isBeaconInstance<Subscription>(NAME_SUBSCRIPTION, value);
-}
-
 function observe<Value>(beacon: BeaconState<Value>): Observable<Value> {
 	const state: ObservableState<Value> = {
 		beacon,
@@ -334,7 +284,7 @@ function observe<Value>(beacon: BeaconState<Value>): Observable<Value> {
 	};
 
 	const instance = {
-		close: (): void => {
+		deactivate: (): void => {
 			state.active = false;
 		},
 		subscribe(
@@ -347,9 +297,13 @@ function observe<Value>(beacon: BeaconState<Value>): Observable<Value> {
 			}
 
 			const observer = getObserver(first, second, third);
-			const subscription = subscribe(state);
 
-			beacon.observers.set(subscription, observer);
+			const subscription = getSubscription({
+				isActive: () => beacon.active && state.active,
+				property: beaconSubscription,
+				subscriptions: beacon.subscriptions,
+				value: observer,
+			});
 
 			observer.next?.(beacon.value);
 
@@ -366,53 +320,11 @@ function observe<Value>(beacon: BeaconState<Value>): Observable<Value> {
 			enumerable: true,
 			get: () => beacon.active && state.active,
 		},
-		closed: {
-			enumerable: true,
-			get: () => !beacon.active || !state.active,
-		},
 	});
 
 	return Object.freeze(instance) as Observable<Value>;
 }
 
-function subscribe<Value>(observable: ObservableState<Value>): Subscription {
-	function unsubscribe(): void {
-		if (active) {
-			active = false;
-
-			observable.beacon.observers.delete(instance as Subscription);
-		}
-	}
-
-	let active = true;
-
-	const instance = {
-		close: (): void => {
-			unsubscribe();
-		},
-		unsubscribe: (): void => {
-			unsubscribe();
-		},
-	};
-
-	Object.defineProperties(instance, {
-		[KEY_BEACON]: {
-			enumerable: false,
-			value: NAME_SUBSCRIPTION,
-		},
-		active: {
-			enumerable: true,
-			get: () => observable.beacon.active && observable.active && active,
-		},
-		closed: {
-			enumerable: true,
-			get: () => !observable.beacon.active || !observable.active || !active,
-		},
-	});
-
-	return Object.freeze(instance) as Subscription;
-}
-
 function update<Value>(
 	type: keyof Observer<never>,
 	state: BeaconState<Value>,
@@ -431,7 +343,7 @@ function update<Value>(
 		state.value = value as Value;
 	}
 
-	for (const [, observer] of state.observers) {
+	for (const [, observer] of state.subscriptions.values.to.any) {
 		observer[type]?.(value as never);
 	}
 
@@ -454,10 +366,13 @@ const NAME_BEACON = 'beacon';
 
 const NAME_OBSERVABLE = 'observable';
 
-const NAME_SUBSCRIPTION = 'subscription';
-
 const TYPE_ERROR = 'error';
 
 const TYPE_NEXT = 'next';
 
+const beaconSubscription: SubscriptionProperty = {
+	key: KEY_BEACON,
+	value: 'subscription',
+};
+
 // #endregion

package/src/color/constants.ts

@@ -1,88 +1,137 @@
-import type {Alpha, HSLAColor, HSLColor, HWBAColor, HWBColor, RGBAColor, RGBColor} from './models';
-
-// #region Variables
-
-export const ALPHA_FULL_HEX_SHORT = 'f';
-
-export const ALPHA_FULL_HEX_LONG = `${ALPHA_FULL_HEX_SHORT}${ALPHA_FULL_HEX_SHORT}`;
+import type {
+	Alpha,
+	ColorTypeExtended,
+	HSLAColor,
+	HSLColor,
+	HWBAColor,
+	HWBColor,
+	RGBAColor,
+	RGBColor,
+} from './models';
+
+// #region Types
+
+type ColorTypes = {
+	all: Set<'alpha' | ColorTypeExtended>;
+	hex: 'hex';
+	hexa: 'hexa';
+	hsl: 'hsl';
+	hsla: 'hsla';
+	hwb: 'hwb';
+	hwba: 'hwba';
+	rgb: 'rgb';
+	rgba: 'rgba';
+};
 
-export const ALPHA_NONE_HEX = '00';
+// #endregion
 
-export const ALPHA_NONE_VALUE = 0;
+// #region Variables
 
-export const DEFAULT_ALPHA: Alpha = {
-	hex: ALPHA_FULL_HEX_LONG,
-	value: 100,
+export const COLOR_ALPHA = {
+	fullHexShort: 'f',
+	fullHexLong: 'ff',
+	name: 'alpha',
+	noneHex: '00',
+	noneValue: 0,
 };
 
-export const DEFAULT_HSL: HSLColor = {
-	hue: 0,
-	saturation: 0,
-	lightness: 0,
+export const COLOR_DEFAULTS = {
+	alpha: {
+		hex: COLOR_ALPHA.fullHexLong,
+		value: 100,
+	},
+	hexBlack: '000000',
+	hexWhite: 'ffffff',
+	hsl: {
+		hue: 0,
+		saturation: 0,
+		lightness: 0,
+	},
+	hwb: {
+		hue: 0,
+		whiteness: 0,
+		blackness: 100,
+	},
+	rgb: {
+		blue: 0,
+		green: 0,
+		red: 0,
+	},
 };
 
-export const DEFAULT_HWB: HWBColor = {
-	hue: 0,
-	whiteness: 0,
-	blackness: 100,
+export const COLOR_EXPRESSION = {
+	alphaHex: /^([a-f0-9]{1,2})$/i,
+	hexLong: /^#?([a-f0-9]{2})([a-f0-9]{2})([a-f0-9]{2})([a-f0-9]{2})?$/i,
+	hexShort: /^#?([a-f0-9]{3,4})$/i,
+	prefix: /^#/,
 };
 
-export const DEFAULT_RGB: RGBColor = {
-	blue: 0,
-	green: 0,
-	red: 0,
+export const COLOR_LENGTHS = {
+	hexLong: 6,
+	hexShort: 3,
 };
 
-export const EXPRESSION_HEX_LONG = /^#?([a-f0-9]{2})([a-f0-9]{2})([a-f0-9]{2})([a-f0-9]{2})?$/i;
-
-export const EXPRESSION_HEX_SHORT = /^#?([a-f0-9]{3,4})$/i;
-
-export const EXPRESSION_PREFIX = /^#/;
-
-export const HEX_BLACK = '000000';
-
-export const HEX_WHITE = 'ffffff';
-
-export const LENGTH_LONG = 6;
-
-export const LENGTH_SHORT = 3;
-
-export const KEYS_HSL: Array<keyof HSLColor> = ['hue', 'saturation', 'lightness'];
-
-export const KEYS_HSLA: Array<keyof HSLAColor> = [...KEYS_HSL, 'alpha'];
+export const COLOR_KEYS = {
+	hsl: ['hue', 'saturation', 'lightness'] as Array<keyof HSLColor>,
+	hsla: [] as Array<keyof HSLAColor>,
+	hwb: ['hue', 'whiteness', 'blackness'] as Array<keyof HWBColor>,
+	hwba: [] as Array<keyof HWBAColor>,
+	rgb: ['red', 'green', 'blue'] as Array<keyof RGBColor>,
+	rgba: [] as Array<keyof RGBAColor>,
+};
 
-export const KEYS_HWB: Array<keyof HWBColor> = ['hue', 'whiteness', 'blackness'];
+COLOR_KEYS.hsla = [...COLOR_KEYS.hsl, COLOR_ALPHA.name as keyof Alpha] as Array<keyof HSLAColor>;
 
-export const KEYS_HWBA: Array<keyof HWBAColor> = [...KEYS_HWB, 'alpha'];
+COLOR_KEYS.hwba = [...COLOR_KEYS.hwb, COLOR_ALPHA.name as keyof Alpha] as Array<keyof HWBAColor>;
 
-export const KEYS_RGB: Array<keyof RGBColor> = ['red', 'green', 'blue'];
+COLOR_KEYS.rgba = [...COLOR_KEYS.rgb, COLOR_ALPHA.name as keyof Alpha] as Array<keyof RGBAColor>;
 
-export const KEYS_RGBA: Array<keyof RGBAColor> = [...KEYS_RGB, 'alpha'];
+export const COLOR_MAX = {
+	degree: 360,
+	hex: 255,
+	percent: 100,
+};
 
-export const MAX_DEGREE = 360;
+export const COLOR_PROPERTY = {
+	name: '$color',
+	subscription: 'subscription',
+};
 
-export const MAX_HEX = 255;
+export const COLOR_TYPE: ColorTypes = {
+	all: undefined as unknown as Set<'alpha' | ColorTypeExtended>,
+	hex: 'hex',
+	hexa: 'hexa',
+	hsl: 'hsl',
+	hsla: 'hsla',
+	hwb: 'hwb',
+	hwba: 'hwba',
+	rgb: 'rgb',
+	rgba: 'rgba',
+};
 
-export const MAX_PERCENT = 100;
+COLOR_TYPE.all = new Set([
+	COLOR_ALPHA.name as 'alpha',
+	COLOR_TYPE.hex,
+	COLOR_TYPE.hexa,
+	COLOR_TYPE.hsl,
+	COLOR_TYPE.hsla,
+	COLOR_TYPE.hwb,
+	COLOR_TYPE.hwba,
+	COLOR_TYPE.rgb,
+	COLOR_TYPE.rgba,
+] as Array<'alpha' | ColorTypeExtended>);
 
 // https://www.w3.org/TR/WCAG20/#relativeluminancedef
-
-export const SRGB_LUMINANCE_BLUE = 0.0722;
-
-export const SRGB_LUMINANCE_EXPONENT = 2.4;
-
-export const SRGB_LUMINANCE_GREEN = 0.7152;
-
-export const SRGB_LUMINANCE_MINIMUM = 0.03928;
-
-export const SRGB_LUMINANCE_MODIFIER = 1.055;
-
-export const SRGB_LUMINANCE_MULTIPLIER = 12.92;
-
-export const SRGB_LUMINANCE_OFFSET = 0.055;
-
-export const SRGB_LUMINANCE_RED = 0.2126;
-
-export const SRGB_LUMINANCE_THRESHOLD = 0.625;
+export const COLOR_SRGB = {
+	luminanceBlue: 0.0722,
+	luminanceExponent: 2.4,
+	luminanceGreen: 0.7152,
+	luminanceMinimum: 0.03928,
+	luminanceModifier: 1.055,
+	luminanceMultiplier: 12.92,
+	luminanceOffset: 0.055,
+	luminanceRed: 0.2126,
+	luminanceThreshold: 0.625,
+};
 
 // #endregion