@oscarpalmer/atoms 0.193.0 → 0.194.0

package/dist/color/models.d.mts

@@ -1,5 +1,6 @@
 import { Subscription } from "../internal/subscription.mjs";
-import { COLOR_ALPHA, COLOR_TYPE } from "./constants.mjs";
+import { HeraldEvents } from "../herald.mjs";
+import { COLOR_ALPHA } from "./constants.mjs";
 //#region src/color/models.d.ts
 type Alpha = {
   hex: string;
@@ -9,6 +10,10 @@ type Alpha = {
  * A color that is represented in multiple color formats
  */
 type Color = {
+  /**
+   *
+   */
+  readonly changes: HeraldEvents<ColorChanges>;
   /**
    * Get the alpha channel _(opacity)_ of the color as a percentage between `0` and `100`
    *
@@ -134,74 +139,12 @@ type Color = {
    */
   set rgba(value: RGBAColor);
   /**
-   * Subscribe to alpha channel _(opacity)_ changes of the color
-   *
-   * @param key Color property to subscribe to
-   * @param callback Callback function for changes
-   */
-  subscribe(key: 'alpha', callback: (value: number) => void): Subscription;
-  /**
-   * Subscribe to hex color changes of the color
-   *
-   * @param key Color type to subscribe to
-   * @param callback Callback function for changes
-   */
-  subscribe(key: typeof COLOR_TYPE.hex, callback: (value: string) => void): Subscription;
-  /**
-   * Subscribe to hex color changes of the color with alpha channel _(opacity)_
-   *
-   * @param key Color type to subscribe to
-   * @param callback Callback function for changes
-   */
-  subscribe(key: typeof COLOR_TYPE.hexa, callback: (value: string) => void): Subscription;
-  /**
-   * Subscribe to _HSL_ color changes of the color
+   * Subscribe to value changes for the color
    *
-   * @param key Color type to subscribe to
-   * @param callback Callback function for changes
+   * @param callback Callback function
+   * @param signal Optional abort signal to cancel the subscription
    */
-  subscribe(key: typeof COLOR_TYPE.hsl, callback: (value: HSLColor) => void): Subscription;
-  /**
-   * Subscribe to _HSL(A)_ color changes of the color
-   *
-   * @param key Color type to subscribe to
-   * @param callback Callback function for changes
-   */
-  subscribe(key: typeof COLOR_TYPE.hsla, callback: (value: HSLAColor) => void): Subscription;
-  /**
-   * Subscribe to _HWB_ color changes of the color
-   *
-   * @param key Color type to subscribe to
-   * @param callback Callback function for changes
-   */
-  subscribe(key: typeof COLOR_TYPE.hwb, callback: (value: HWBColor) => void): Subscription;
-  /**
-   * Subscribe to _HWB(A)_ color changes of the color
-   *
-   * @param key Color type to subscribe to
-   * @param callback Callback function for changes
-   */
-  subscribe(key: typeof COLOR_TYPE.hwba, callback: (value: HWBAColor) => void): Subscription;
-  /**
-   * Subscribe to _RGB_ color changes of the color
-   *
-   * @param key Color type to subscribe to
-   * @param callback Callback function for changes
-   */
-  subscribe(key: typeof COLOR_TYPE.rgb, callback: (value: RGBColor) => void): Subscription;
-  /**
-   * Subscribe to _RGBA_ color changes of the color
-   *
-   * @param key Color type to subscribe to
-   * @param callback Callback function for changes
-   */
-  subscribe(key: typeof COLOR_TYPE.rgba, callback: (value: RGBAColor) => void): Subscription;
-  /**
-   * Subscribe to any color changes of the color
-   *
-   * @param callback Callback function for changes
-   */
-  subscribe(callback: (value: Color) => void): Subscription;
+  subscribe(callback: (value: Color) => void, signal?: AbortSignal): Subscription;
   /**
    * Get the color as a hex string
    *
@@ -243,6 +186,18 @@ type Color = {
    */
   unsubscribe(): void;
 };
+type ColorChanges = {
+  '*': (value: Color) => void;
+  alpha: (value: number) => void;
+  hex: (value: string) => void;
+  hexa: (value: string) => void;
+  hsl: (value: HSLColor) => void;
+  hsla: (value: HSLAColor) => void;
+  hwb: (value: HWBColor) => void;
+  hwba: (value: HWBAColor) => void;
+  rgb: (value: RGBColor) => void;
+  rgba: (value: RGBAColor) => void;
+};
 type ColorWithAlpha = {
   /**
    * Alpha channel _(opacity)_ of the color _(in percentage; 0-100)_
@@ -332,4 +287,4 @@ type ColorValue = string | HSLColor | HWBColor | RGBColor;
  */
 type ColorValueExtended = ColorValue | HSLAColor | HWBAColor | RGBAColor;
 //#endregion
-export { Alpha, Color, ColorProperty, ColorState, ColorType, ColorTypeExtended, ColorValue, ColorValueExtended, HSLAColor, HSLColor, HWBAColor, HWBColor, RGBAColor, RGBColor };
+export { Alpha, Color, ColorChanges, ColorProperty, ColorState, ColorType, ColorTypeExtended, ColorValue, ColorValueExtended, HSLAColor, HSLColor, HWBAColor, HWBColor, RGBAColor, RGBColor };

package/dist/function/assert.mjs

@@ -40,7 +40,7 @@ function assertCondition(condition, message, error) {
 * @param error Error constructor _(defaults to `Error`)_
 */
 function assertDefined(value, message, error) {
-	assert(() => value != null, message ?? MESSAGE_VALUE_DEFINED, error);
+	assert(() => value != null, message ?? ASSERT_MESSAGE_VALUE_DEFINED, error);
 }
 /**
 * Creates an _Asserter_ that asserts a value is an instance of a constructor, throwing an error if it is not
@@ -91,6 +91,6 @@ function assertProperty(path, condition, message, error) {
 		}, message, error);
 	};
 }
-const MESSAGE_VALUE_DEFINED = "Expected value to be defined";
+const ASSERT_MESSAGE_VALUE_DEFINED = "Expected value to be defined";
 //#endregion
 export { assert, assertCondition, assertDefined, assertInstanceOf, assertIs, assertProperty };

package/dist/function/limit.d.mts

@@ -36,9 +36,6 @@ declare function asyncThrottle<Callback extends GenericAsyncCallback | GenericCa
  * @returns Debounced callback handler with a `cancel` method
  */
 declare function debounce<Callback extends GenericCallback>(callback: Callback, time?: number): CancelableCallback<Callback>;
-declare namespace debounce {
-  var async: typeof asyncDebounce;
-}
 /**
  * Throttle a function, ensuring it is only called once every `time` milliseconds
  *
@@ -47,8 +44,5 @@ declare namespace debounce {
  * @returns Throttled callback handler with a `cancel` method
  */
 declare function throttle<Callback extends GenericCallback>(callback: Callback, time?: number): CancelableCallback<Callback>;
-declare namespace throttle {
-  var async: typeof asyncThrottle;
-}
 //#endregion
 export { asyncDebounce, asyncThrottle, debounce, throttle };

package/dist/function/limit.mjs

@@ -42,7 +42,6 @@ function asyncThrottle(callback, time) {
 function debounce(callback, time) {
 	return getTimer(TIMER_DEBOUNCE, callback, time);
 }
-debounce.async = asyncDebounce;
 /**
 * Throttle a function, ensuring it is only called once every `time` milliseconds
 *
@@ -53,6 +52,7 @@ debounce.async = asyncDebounce;
 function throttle(callback, time) {
 	return getTimer(TIMER_THROTTLE, callback, time);
 }
-throttle.async = asyncThrottle;
+Object.defineProperty(debounce, "async", { value: asyncDebounce });
+Object.defineProperty(throttle, "async", { value: asyncThrottle });
 //#endregion
 export { asyncDebounce, asyncThrottle, debounce, throttle };

package/dist/function/memoize.mjs

@@ -6,7 +6,7 @@ function getMemoizationOptions(input) {
 	const { cacheKey, cacheSize } = isPlainObject(input) ? input : {};
 	return {
 		cacheKey: typeof cacheKey === "function" ? cacheKey : void 0,
-		cacheSize: typeof cacheSize === "number" && cacheSize > 0 ? cacheSize : DEFAULT_CACHE_SIZE
+		cacheSize: typeof cacheSize === "number" && cacheSize > 0 ? cacheSize : MEMOIZED_CACHE_SIZE_DEFAULT
 	};
 }
 /**
@@ -17,54 +17,41 @@ function getMemoizationOptions(input) {
 * @returns _Memoized_ instance
 */
 function memoize(callback, options) {
-	if (typeof callback !== "function") throw new TypeError(MEMOIZED_ERROR_CALLBACK);
-	const state = { options: getMemoizationOptions(options) };
+	if (typeof callback !== "function") throw new TypeError(MEMOIZED_CALLBACK);
+	const state = {
+		cache: void 0,
+		getter: void 0,
+		options: getMemoizationOptions(options)
+	};
 	state.cache = new SizedMap(state.options.cacheSize);
 	state.getter = (...parameters) => {
-		const key = state.options.cacheKey?.(...parameters) ?? (parameters.length === 1 ? parameters[0] : join(parameters.map(getString), SEPARATOR));
+		const key = state.options.cacheKey?.(...parameters) ?? (parameters.length === 1 ? parameters[0] : join(parameters.map(getString), MEMOIZED_KEY_SEPARATOR));
 		if (state.cache.has(key)) return state.cache.get(key);
 		const value = callback(...parameters);
-		state.cache?.set(key, value);
+		state.cache.set(key, value);
 		return value;
 	};
 	const instance = {
-		clear: () => {
-			state.cache?.clear();
-		},
-		delete: (key) => {
-			return state.cache?.delete(key) ?? false;
-		},
-		destroy: () => {
-			state.cache?.clear();
-			state.cache = void 0;
-			state.getter = void 0;
-		},
-		get: (key) => {
-			return state.cache?.get(key);
-		},
-		has: (key) => {
-			return state.cache?.has(key) ?? false;
-		},
-		run: (...parameters) => {
-			if (state.cache == null || state.getter == null) throw new Error(MEMOIZED_ERROR_DESTROYED);
-			return state.getter(...parameters);
-		}
+		clear: () => state.cache.clear(),
+		delete: (key) => state.cache.delete(key),
+		get: (key) => state.cache.get(key),
+		has: (key) => state.cache.has(key),
+		run: (...parameters) => state.getter(...parameters)
 	};
 	Object.defineProperties(instance, {
 		maximum: {
 			enumerable: true,
-			get: () => state.cache?.maximum ?? NaN
+			get: () => state.cache.maximum
 		},
 		size: {
 			enumerable: true,
-			get: () => state.cache?.size ?? NaN
+			get: () => state.cache.size
 		}
 	});
 	return Object.freeze(instance);
 }
-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 = "_";
+const MEMOIZED_CACHE_SIZE_DEFAULT = 1024;
+const MEMOIZED_CALLBACK = "Memoized requires a callback function";
+const MEMOIZED_KEY_SEPARATOR = "_";
 //#endregion
 export { memoize };

package/dist/function/once.d.mts

@@ -16,8 +16,5 @@ declare function asyncOnce<Callback extends GenericAsyncCallback>(callback: Call
  * @returns _Once_ callback
  */
 declare function once<Callback extends GenericCallback>(callback: Callback): OnceCallback<Callback>;
-declare namespace once {
-  var async: typeof asyncOnce;
-}
 //#endregion
 export { asyncOnce, once };

package/dist/function/once.mjs

@@ -45,6 +45,7 @@ function asyncOnce(callback) {
 			enumerable: true,
 			get: () => state.called
 		},
+		clear: { value: () => clearState(state) },
 		cleared: {
 			enumerable: true,
 			get: () => state.cleared
@@ -58,13 +59,13 @@ function asyncOnce(callback) {
 			get: () => state.finished
 		}
 	});
-	fn.clear = () => {
-		if (!state.called || !state.finished || state.cleared) return;
-		state.cleared = true;
-		state.value = void 0;
-	};
 	return fn;
 }
+function clearState(state) {
+	if (!state.called || state.cleared) return;
+	state.cleared = true;
+	state.value = void 0;
+}
 function handleOnceResult(state, value, error) {
 	state.error = error;
 	state.finished = true;
@@ -98,18 +99,20 @@ function once(callback) {
 		return state.value;
 	};
 	Object.defineProperties(fn, {
-		called: { get: () => state.called },
-		cleared: { get: () => state.cleared }
+		called: {
+			enumerable: true,
+			get: () => state.called
+		},
+		clear: { value: () => clearState(state) },
+		cleared: {
+			enumerable: true,
+			get: () => state.cleared
+		}
 	});
-	fn.clear = () => {
-		if (!state.called || state.cleared) return;
-		state.cleared = true;
-		state.value = void 0;
-	};
 	return fn;
 }
-once.async = asyncOnce;
 const ONCE_MESSAGE_CLEARED = "Once has been cleared";
 const ONCE_MESSAGE_EXPECTATION = "Once expected a function";
+Object.defineProperty(once, "async", { value: asyncOnce });
 //#endregion
 export { asyncOnce, once };

package/dist/function/retry.d.mts

@@ -1,4 +1,4 @@
-import { GenericAsyncCallback, GenericCallback } from "../models.mjs";
+import { GenericCallback } from "../models.mjs";
 //#region src/function/retry.d.ts
 /**
  * An error thrown when a retry fails
@@ -12,26 +12,6 @@ type RetryOptions = {
   times?: number;
   when?: (error: unknown) => boolean;
 };
-/**
- * Retry a callback a specified number of times, with a delay between attempts
- *
- * _Available as `asyncRetry` and `retry.async`_
- *
- * @param callback Callback to retry
- * @param options Retry options
- * @returns Callback result
- */
-declare function asyncRetry<Callback extends GenericAsyncCallback>(callback: Callback, options?: RetryOptions): Promise<Awaited<ReturnType<Callback>>>;
-/**
- * Retry a callback a specified number of times, with a delay between attempts
- *
- * _Available as `asyncRetry` and `retry.async`_
- *
- * @param callback Callback to retry
- * @param options Retry options
- * @returns Callback result
- */
-declare function asyncRetry<Callback extends GenericCallback>(callback: Callback, options?: RetryOptions): Promise<ReturnType<Callback>>;
 /**
  * Retry a callback a specified number of times
  *
@@ -40,8 +20,5 @@ declare function asyncRetry<Callback extends GenericCallback>(callback: Callback
  * @returns Callback result
  */
 declare function retry<Callback extends GenericCallback>(callback: Callback, options?: Omit<RetryOptions, 'delay'>): ReturnType<Callback>;
-declare namespace retry {
-  var async: typeof asyncRetry;
-}
 //#endregion
 export { RetryError, RetryOptions, retry };

package/dist/function/retry.mjs

@@ -78,12 +78,12 @@ function retry(callback, options) {
 	}
 	throw new RetryError(RETRY_MESSAGE_FAILED, last);
 }
-retry.async = asyncRetry;
 function shouldRetry() {
 	return true;
 }
 const RETRY_ERROR_NAME = "RetryError";
 const RETRY_MESSAGE_EXPECTATION = "Retry expected a function";
 const RETRY_MESSAGE_FAILED = "Retry failed";
+Object.defineProperty(retry, "async", { value: asyncRetry });
 //#endregion
 export { RetryError, retry };

package/dist/function/work.mjs

@@ -15,7 +15,6 @@ function flow(...fns) {
 		return isOk(value) ? value.value : value;
 	}), fns, true);
 }
-flow.async = asyncFlow;
 async function asyncPipe(value, ...pipes) {
 	assertPipeFunctions(pipes);
 	return asyncWork(value, pipes, false);
@@ -24,7 +23,6 @@ function pipe(value, ...pipes) {
 	assertPipeFunctions(pipes);
 	return work(value, pipes, false);
 }
-pipe.async = asyncPipe;
 async function asyncWork(initial, functions, flow) {
 	const { length } = functions;
 	let transformed = unwrapValue(initial);
@@ -36,10 +34,10 @@ async function asyncWork(initial, functions, flow) {
 }
 function unwrapValue(value, flow, nested) {
 	if (typeof value === "function") {
-		if (nested != null) throw new TypeError(MESSAGE_NESTING);
+		if (nested != null) throw new TypeError(WORK_MESSAGE_NESTING);
 		return unwrapValue(value(), flow, true);
 	}
-	if (flow != null && value instanceof Promise) throw new TypeError(flow ? MESSAGE_FLOW_PROMISE : MESSAGE_PIPE_PROMISE);
+	if (flow != null && value instanceof Promise) throw new TypeError(flow ? WORK_MESSAGE_FLOW_PROMISE : WORK_MESSAGE_PIPE_PROMISE);
 	if (isError(value)) throw value.error;
 	return isOk(value) ? value.value : value;
 }
@@ -52,12 +50,16 @@ function work(initial, functions, flow) {
 	}
 	return transformed;
 }
-const MESSAGE_FLOW_ARRAY = "Flow expected to receive an array of functions";
-const MESSAGE_FLOW_PROMISE = "Synchronous Flow received a promise. Use `flow.async` instead.";
-const MESSAGE_NESTING = "Return values are too deeply nested.";
-const MESSAGE_PIPE_ARRAY = "Pipe expected to receive an array of functions";
-const MESSAGE_PIPE_PROMISE = "Synchronous Pipe received a promise. Use `pipe.async` instead.";
-const assertFlowFunctions = assert.condition((value) => Array.isArray(value) && value.every((item) => typeof item === "function"), MESSAGE_FLOW_ARRAY, TypeError);
-const assertPipeFunctions = assert.condition((value) => Array.isArray(value) && value.every((item) => typeof item === "function"), MESSAGE_PIPE_ARRAY, TypeError);
+const WORK_MESSAGE_FLOW_ARRAY = "Flow expected to receive an array of functions";
+const WORK_MESSAGE_FLOW_PROMISE = "Synchronous Flow received a promise. Use `flow.async` instead.";
+const WORK_MESSAGE_NESTING = "Return values are too deeply nested.";
+const WORK_MESSAGE_PIPE_ARRAY = "Pipe expected to receive an array of functions";
+const WORK_MESSAGE_PIPE_PROMISE = "Synchronous Pipe received a promise. Use `pipe.async` instead.";
+const assertFlowFunctions = assert.condition((value) => Array.isArray(value) && value.every((item) => typeof item === "function"), WORK_MESSAGE_FLOW_ARRAY, TypeError);
+const assertPipeFunctions = assert.condition((value) => Array.isArray(value) && value.every((item) => typeof item === "function"), WORK_MESSAGE_PIPE_ARRAY, TypeError);
+flow.async = asyncFlow;
+pipe.async = asyncPipe;
+Object.defineProperty(flow, "async", { value: asyncFlow });
+Object.defineProperty(pipe, "async", { value: asyncPipe });
 //#endregion
 export { asyncFlow, asyncPipe, flow, pipe };

package/dist/herald.d.mts

@@ -1,25 +1,8 @@
-import { GenericCallback, Unsubscriber } from "./models.mjs";
+import { GenericCallback } from "./models.mjs";
+import { Subscription, SubscriptionProperty } from "./internal/subscription.mjs";
 //#region src/herald.d.ts
-type Events<Map extends Record<string, GenericCallback>> = {
-  /**
-   * 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;
-  /**
-   * 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;
-};
-type Herald<Map extends Record<string, GenericCallback>> = {
-  readonly events: Events<Map>;
+type Herald<Events extends Record<string, GenericCallback>> = {
+  readonly events: HeraldEvents<Events>;
   /**
    * Remove all event subscribers
    */
@@ -30,37 +13,46 @@ type Herald<Map extends Record<string, GenericCallback>> = {
    * @param event Event name
    * @param parameters Event parameters
    */
-  emit<Event extends keyof Map>(event: Event, ...parameters: Parameters<Map[Event]>): void;
+  emit<Event extends keyof Events>(event: Event, ...parameters: Parameters<Events[Event]>): void;
   /**
-   * Subscribe to an event with a callback
+   * Is the event observed by any subscribers?
    *
    * @param event Event name
-   * @param callback Callback function
-   * @returns Unsubscriber function
+   * @returns `true` if the event is observed, otherwise `false`
    */
-  subscribe<Event extends keyof Map>(event: Event, callback: Map[Event]): Unsubscriber;
+  observed<Event extends keyof Events>(event: Event): boolean;
   /**
-   * Unsubscribe from an event with a callback _(or all callbacks, if no callback is provided)_
+   * Subscribe to an event with a callback
    *
    * @param event Event name
    * @param callback Callback function
+   * @param signal Optional abort signal to cancel the subscription
+   * @returns Subscription instance
    */
-  unsubscribe<Event extends keyof Map>(event: Event, callback?: Map[Event]): void;
+  subscribe<Event extends keyof Events>(event: Event, callback: Events[Event], signal?: AbortSignal): Subscription;
+};
+type HeraldEvents<Events extends Record<string, GenericCallback>> = { [Key in keyof Events]: Key extends '*' ? never : (callback: Events[Key], signal?: AbortSignal) => void; };
+type HeraldOnCreate<Events extends Record<string, GenericCallback>> = <Event extends keyof Events>(event: Event, callback: Events[Event], subscription: Subscription) => void;
+type HeraldOptions<Events extends Record<string, GenericCallback>> = {
+  names: Array<keyof Events>;
+  property?: SubscriptionProperty;
+  onCreate?: HeraldOnCreate<Events>;
 };
 /**
  * Create a _Herald_ for announcing named events
  *
  * @param names Event names
+ * @param property Optional property for subscription identification _(defaults to `$herald`)_
  * @returns _Herald_ instance
  */
-declare function herald<Events extends Record<string, GenericCallback>>(names: (keyof Events)[]): Herald<Events>;
+declare function herald<Events extends Record<string, GenericCallback>>(options: HeraldOptions<Events>): Herald<Events>;
 /**
  * Is the value events for a herald?
  *
  * @param value Value to check
  * @returns `true` if the value is events for a herald, otherwise `false`
  */
-declare function isEvents<Map extends Record<string, GenericCallback> = Record<string, GenericCallback>>(value: unknown): value is Events<Map>;
+declare function isHeraldEvents<Events extends Record<string, GenericCallback> = Record<string, GenericCallback>>(value: unknown): value is HeraldEvents<Events>;
 /**
  * Is the value a herald?
  *
@@ -68,5 +60,12 @@ declare function isEvents<Map extends Record<string, GenericCallback> = Record<s
  * @returns `true` if the value is a herald, otherwise `false`
  */
 declare function isHerald<Events extends Record<string, GenericCallback> = Record<string, GenericCallback>>(value: unknown): value is Herald<Events>;
+/**
+ * Is the value a herald subscription?
+ *
+ * @param value Value to check
+ * @returns `true` if the value is a herald subscription, otherwise `false`
+ */
+declare function isHeraldSubscription(value: unknown): value is Subscription;
 //#endregion
-export { Events, Herald, herald, isEvents, isHerald };
+export { Herald, HeraldEvents, HeraldOptions, herald, isHerald, isHeraldEvents, isHeraldSubscription };