@oscarpalmer/atoms 0.75.0 → 0.76.0

package/src/js/colour/hsl.ts

@@ -1,8 +1,8 @@
-import {Colour} from '@/colour/base';
-import {hslToRgb} from '@/colour/functions';
-import type {HexColour} from '@/colour/hex';
-import type {RGBColour} from '@/colour/rgb';
-import {clamp} from '@/number';
+import {Colour} from '~/colour/base';
+import {hslToRgb} from '~/colour/functions';
+import type {HexColour} from '~/colour/hex';
+import type {RGBColour} from '~/colour/rgb';
+import {clamp} from '~/number';
 
 export type HSLColourValue = {
 	hue: number;
@@ -12,42 +12,42 @@ export type HSLColourValue = {
 
 export class HSLColour extends Colour<HSLColourValue> {
 	/**
-	 * Gets the current hue
+	 * Get the current hue
 	 */
 	get hue(): number {
 		return +this.state.value.hue;
 	}
 
 	/**
-	 * Sets the current hue
+	 * Set the current hue
 	 */
 	set hue(value: number) {
 		this.state.value.hue = clamp(value, 0, 360);
 	}
 
 	/**
-	 * Gets the current lightness
+	 * Get the current lightness
 	 */
 	get lightness(): number {
 		return +this.state.value.lightness;
 	}
 
 	/**
-	 * Sets the current lightness
+	 * Set the current lightness
 	 */
 	set lightness(value: number) {
 		this.state.value.lightness = clamp(value, 0, 100);
 	}
 
 	/**
-	 * Gets the current saturation
+	 * Get the current saturation
 	 */
 	get saturation(): number {
 		return +this.state.value.saturation;
 	}
 
 	/**
-	 * Sets the current saturation
+	 * Set the current saturation
 	 */
 	set saturation(value: number) {
 		this.state.value.saturation = clamp(value, 0, 100);
@@ -57,17 +57,23 @@ export class HSLColour extends Colour<HSLColourValue> {
 		super('hsl', value, defaults, properties);
 	}
 
+	/**
+	 * @inheritdoc
+	 */
 	toHex(): HexColour {
 		return HSLColour.toRgb(this.state.value).toHex();
 	}
 
 	/**
-	 * Converts the colour to an RGB-colour
+	 * Convert the colour to an RGB-colour
 	 */
 	toRgb(): RGBColour {
 		return HSLColour.toRgb(this.state.value);
 	}
 
+	/**
+	 * @inheritdoc
+	 */
 	toString(): string {
 		return `hsl(${this.state.value.hue}, ${this.state.value.saturation}%, ${this.state.value.lightness}%)`;
 	}

package/src/js/colour/index.ts

@@ -1,4 +1,4 @@
-import type {RGBColourValue} from '@/colour/rgb';
+import type {RGBColourValue} from '~/colour/rgb';
 
 /**
  * Get a foreground colour _(usually text)_ based on a background colour's luminance

package/src/js/colour/is.ts

@@ -1,6 +1,6 @@
-import type {HexColour} from '@/colour/hex';
-import type {HSLColour} from '@/colour/hsl';
-import type {RGBColour} from '@/colour/rgb';
+import type {HexColour} from '~/colour/hex';
+import type {HSLColour} from '~/colour/hsl';
+import type {RGBColour} from '~/colour/rgb';
 
 /**
  * Is the value a colour?

package/src/js/colour/rgb.ts

@@ -1,8 +1,8 @@
-import {Colour} from '@/colour/base';
-import {rgbToHex, rgbToHsl} from '@/colour/functions';
-import type {HexColour} from '@/colour/hex';
-import type {HSLColour} from '@/colour/hsl';
-import {clamp} from '@/number';
+import {Colour} from '~/colour/base';
+import {rgbToHex, rgbToHsl} from '~/colour/functions';
+import type {HexColour} from '~/colour/hex';
+import type {HSLColour} from '~/colour/hsl';
+import {clamp} from '~/number';
 
 export type RGBColourValue = {
 	blue: number;
@@ -12,42 +12,42 @@ export type RGBColourValue = {
 
 export class RGBColour extends Colour<RGBColourValue> {
 	/**
-	 * Gets the current blue value
+	 * Get the current blue value
 	 */
 	get blue(): number {
 		return +this.state.value.blue;
 	}
 
 	/**
-	 * Sets the current blue value
+	 * Set the current blue value
 	 */
 	set blue(value: number) {
 		this.state.value.blue = clamp(value, 0, 255);
 	}
 
 	/**
-	 * Gets the current green value
+	 * Get the current green value
 	 */
 	get green(): number {
 		return +this.state.value.green;
 	}
 
 	/**
-	 * Sets the current green value
+	 * Set the current green value
 	 */
 	set green(value: number) {
 		this.state.value.green = clamp(value, 0, 255);
 	}
 
 	/**
-	 * Gets the current red value
+	 * Get the current red value
 	 */
 	get red(): number {
 		return +this.state.value.red;
 	}
 
 	/**
-	 * Sets the current red value
+	 * Set the current red value
 	 */
 	set red(value: number) {
 		this.state.value.red = clamp(value, 0, 255);
@@ -57,6 +57,9 @@ export class RGBColour extends Colour<RGBColourValue> {
 		super('rgb', value, defaults, properties);
 	}
 
+	/**
+	 * @inheritdoc
+	 */
 	toHex(): HexColour {
 		return RGBColour.toHex(this.value);
 	}
@@ -68,6 +71,9 @@ export class RGBColour extends Colour<RGBColourValue> {
 		return RGBColour.toHsl(this.value);
 	}
 
+	/**
+	 * @inheritdoc
+	 */
 	toString(): string {
 		return `rgb(${this.value.red}, ${this.value.green}, ${this.value.blue})`;
 	}

package/src/js/emitter.ts

@@ -1,4 +1,4 @@
-import {noop} from '@/function';
+import {noop} from '~/function';
 
 class Emitter<Value> {
 	private declare readonly state: EmitterState<Value>;
@@ -36,14 +36,14 @@ class Emitter<Value> {
 	}
 
 	/**
-	 * Destroys the emitter
+	 * Destroy the emitter
 	 */
 	destroy(): void {
 		finishEmitter(this.state, false);
 	}
 
 	/**
-	 * Emits a new value _(and optionally finishes the emitter)_
+	 * Emit a new value _(and optionally finishes the emitter)_
 	 */
 	emit(value: Value, finish?: boolean): void {
 		if (this.state.active) {
@@ -60,7 +60,7 @@ class Emitter<Value> {
 	}
 
 	/**
-	 * Emits an error _(and optionally finishes the emitter)_
+	 * Emit an error _(and optionally finishes the emitter)_
 	 */
 	error(error: Error, finish?: boolean): void {
 		if (this.state.active) {
@@ -75,7 +75,7 @@ class Emitter<Value> {
 	}
 
 	/**
-	 * Finishes the emitter
+	 * Finish the emitter
 	 */
 	finish(): void {
 		finishEmitter(this.state, true);
@@ -103,12 +103,12 @@ class Observable<Value> {
 	}
 
 	/**
-	 * Subscribes to value changes
+	 * Subscribe to value changes
 	 */
 	subscribe(observer: Observer<Value>): Subscription<Value>;
 
 	/**
-	 * Subscribes to value changes
+	 * Subscribe to value changes
 	 */
 	subscribe(
 		onNext: (value: Value) => void,
@@ -169,6 +169,9 @@ class Subscription<Value> {
 		return this.state.closed || !(this.state.emitter?.active ?? false);
 	}
 
+	/**
+	 * Destroy the subscription
+	 */
 	destroy(): void {
 		this.unsubscribe();
 
@@ -177,7 +180,7 @@ class Subscription<Value> {
 	}
 
 	/**
-	 * Unsubscribes from the observable
+	 * Unsubscribe from its observable
 	 */
 	unsubscribe(): void {
 		if (!this.state.closed) {
@@ -197,7 +200,7 @@ type SubscriptionState<Value> = {
 const properties: Array<keyof Observer<never>> = ['complete', 'error', 'next'];
 
 /**
- * Creates a new emitter
+ * Create a new emitter
  */
 export function emitter<Value>(value: Value): Emitter<Value> {
 	return new Emitter(value);

package/src/js/function.ts

@@ -1,9 +1,9 @@
-import type {GenericCallback} from '@/models';
-import {clamp} from '@/number';
+import type {GenericCallback} from '~/models';
+import {clamp} from '~/number';
 
 type Debounced<Callback extends GenericCallback> = Callback & {
 	/**
-	 * Cancels the debounce
+	 * Cancel the debounce
 	 */
 	cancel: () => void;
 };
@@ -34,21 +34,21 @@ class Memoised<Callback extends GenericCallback> {
 	}
 
 	/**
-	 * Clears the cache
+	 * Clear the cache
 	 */
 	clear(): void {
 		this.state.cache?.clear();
 	}
 
 	/**
-	 * Deletes a result from the cache
+	 * Delete a result from the cache
 	 */
 	delete(key: Parameters<Callback>[0]): boolean {
 		return this.state.cache?.delete(key);
 	}
 
 	/**
-	 * Destroys the instance, clearing its cache and removing its callback
+	 * Destroy the instance, clearing its cache and removing its callback
 	 */
 	destroy(): void {
 		this.state.cache.clear();
@@ -58,21 +58,21 @@ class Memoised<Callback extends GenericCallback> {
 	}
 
 	/**
-	 * Retrieves the result from the cache if it exists, or `undefined` otherwise
+	 * Get a result from the cache if it exists _(or `undefined` otherwise)_
 	 */
 	get(key: Parameters<Callback>[0]): ReturnType<Callback> | undefined {
 		return this.state.cache?.get(key);
 	}
 
 	/**
-	 * Checks if the cache has a result for a given key
+	 * Does the result exist?
 	 */
 	has(key: Parameters<Callback>[0]): boolean {
 		return this.state.cache?.has(key) ?? false;
 	}
 
 	/**
-	 * Retrieves the result from the cache if it exists, otherwise runs the callback, caches the result, and returns it
+	 * Get the result from the cache if it exists; otherwise runs the callback, caches the result, and returns it
 	 */
 	run(...parameters: Parameters<Callback>): ReturnType<Callback> {
 		return this.state.getter(...parameters);
@@ -85,7 +85,7 @@ type MemoisedState<Callback extends GenericCallback> = {
 };
 
 /**
- * - Debounces a function, ensuring it is only called after `time` milliseconds have passed
+ * - 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...)_
  * - Time is clamped between _0_ and _1000_ milliseconds
  * - Returns the callback with an added `cancel`-method for manually cancelling the debounce
@@ -114,7 +114,7 @@ export function debounce<Callback extends GenericCallback>(
 }
 
 /**
- * Memoises a function, caching and retrieving results based on the first parameter
+ * Memoise a function, caching and retrieving results based on the first parameter
  */
 export function memoise<Callback extends GenericCallback>(
 	callback: Callback,
@@ -128,7 +128,7 @@ export function memoise<Callback extends GenericCallback>(
 export function noop(): void {}
 
 /**
- * - Throttles a function, ensuring it is only called once every `time` milliseconds
+ * - Throttle a function, ensuring it is only called once every `time` milliseconds
  * - Time is clamped between _0_ and _1000_ milliseconds
  */
 export function throttle<Callback extends GenericCallback>(

package/src/js/index.ts

@@ -1,16 +1,16 @@
-export * from '@/array/index';
-export * from '@/colour/index';
-export * from '@/emitter';
-export * from '@/function';
-export * from '@/is';
-export * from '@/logger';
-export * from '@/math';
-export * from '@/models';
-export * from '@/number';
-export * from '@/query';
-export * from '@/queue';
-export * from '@/random';
-export * from '@/sized';
-export * from '@/string/index';
-export * from '@/touch';
-export * from '@/value/index';
+export * from '~/array/index';
+export * from '~/colour/index';
+export * from '~/emitter';
+export * from '~/function';
+export * from '~/is';
+export * from '~/logger';
+export * from '~/math';
+export * from '~/models';
+export * from '~/number';
+export * from '~/query';
+export * from '~/queue';
+export * from '~/random';
+export * from '~/sized';
+export * from '~/string/index';
+export * from '~/touch';
+export * from '~/value/index';

package/src/js/internal/array/callbacks.ts

@@ -0,0 +1,33 @@
+import type {BooleanCallback, Callbacks, KeyCallback} from '~/array/models';
+import type {GenericCallback, PlainObject} from '~/models';
+
+function getCallback(value: unknown): GenericCallback | undefined {
+	switch (typeof value) {
+		case 'function':
+			return value as GenericCallback;
+
+		case 'number':
+		case 'string':
+			return typeof value === 'string' && value.includes('.')
+				? undefined
+				: (obj: PlainObject) => obj[value];
+
+		default:
+			return;
+	}
+}
+
+export function getCallbacks(
+	bool?: unknown,
+	key?: unknown,
+	value?: unknown,
+): Callbacks | undefined {
+	if (typeof bool === 'function') {
+		return {bool: bool as BooleanCallback<unknown>};
+	}
+
+	return {
+		key: getCallback(key) as KeyCallback<unknown>,
+		value: getCallback(value) as GenericCallback,
+	};
+}

package/src/js/internal/{array-find.ts → array/find.ts}

@@ -1,18 +1,18 @@
-import type {BooleanCallback, FindType, KeyCallback} from '@/array/models';
-import {getCallbacks} from '@/internal/array-callbacks';
-import type {Key} from '@/models';
+import type {FindType} from '~/array/models';
+import {getCallbacks} from '~/internal/array/callbacks';
 
-export function findValue<Model, Value = Model>(
+export function findValue(
 	type: FindType,
-	array: Model[],
-	value: Value | BooleanCallback<Model>,
-	key?: Key | KeyCallback<Model>,
+	array: unknown[],
+	bool: unknown,
+	key: unknown,
+	value: unknown,
 ): unknown {
-	const callbacks = getCallbacks(value, key);
+	const callbacks = getCallbacks(bool, key);
 
 	if (callbacks?.bool == null && callbacks?.key == null) {
 		return type === 'index'
-			? array.indexOf(value as Model)
+			? array.findIndex(item => item === value)
 			: array.find(item => item === value);
 	}
 
@@ -35,21 +35,21 @@ export function findValue<Model, Value = Model>(
 	return type === 'index' ? -1 : undefined;
 }
 
-export function findValues<Model, Value = Model>(
+export function findValues(
 	type: 'all' | 'unique',
-	array: Model[],
-	value: Value | BooleanCallback<Model>,
-	key?: Key | KeyCallback<Model>,
-): Model[] {
-	const callbacks = getCallbacks(value, key);
-
+	array: unknown[],
+	bool: unknown,
+	key: unknown,
+	value: unknown,
+): unknown[] {
+	const callbacks = getCallbacks(bool, key);
 	const {length} = array;
 
 	if (type === 'unique' && callbacks?.key == null && length >= 100) {
 		return Array.from(new Set(array));
 	}
 
-	if (typeof callbacks?.bool === 'function') {
+	if (callbacks?.bool != null) {
 		return array.filter(callbacks.bool);
 	}
 
@@ -57,20 +57,19 @@ export function findValues<Model, Value = Model>(
 		return array.filter(item => item === value);
 	}
 
-	const hasCallback = typeof callbacks?.key === 'function';
-	const result: Model[] = [];
-	const values: unknown[] = hasCallback ? [] : result;
+	const result: unknown[] = [];
+	const values: unknown[] = callbacks?.key != null ? [] : result;
 
 	for (let index = 0; index < length; index += 1) {
 		const item = array[index];
-		const itemKey = hasCallback ? callbacks.key?.(item, index, array) : item;
+		const keyed = callbacks?.key?.(item, index, array) ?? item;
 
 		if (
-			(type === 'all' && itemKey === value) ||
-			(type === 'unique' && values.indexOf(itemKey) === -1)
+			(type === 'all' && keyed === value) ||
+			(type === 'unique' && values.indexOf(keyed) === -1)
 		) {
 			if (values !== result) {
-				values.push(itemKey);
+				values.push(keyed);
 			}
 
 			result.push(item);

package/src/js/internal/{value-handle.ts → value/handle.ts}

@@ -1,4 +1,4 @@
-import type {PlainObject} from '@/models';
+import type {PlainObject} from '~/models';
 
 function findKey(
 	needle: string,

package/src/js/is.ts

@@ -1,5 +1,5 @@
-import type {ArrayOrPlainObject, Key, PlainObject, Primitive} from '@/models';
-import {getString} from '@/string';
+import type {ArrayOrPlainObject, Key, PlainObject, Primitive} from '~/models';
+import {getString} from '~/string';
 
 /**
  * Is the value an array or a record?

package/src/js/logger.ts

@@ -1,4 +1,4 @@
-import {noop} from '@/function';
+import {noop} from '~/function';
 
 declare global {
 	var _atomic_logging: boolean;
@@ -10,14 +10,14 @@ if (globalThis._atomic_logging == null) {
 
 class Logger {
 	/**
-	 * Logs any number of values at the "debug" log level
+	 * Log any number of values at the "debug" log level
 	 */
 	get debug() {
 		return this.enabled ? console.debug : noop;
 	}
 
 	/**
-	 * Logs the value and shows all its properties
+	 * Log the value and shows all its properties
 	 */
 	get dir() {
 		return this.enabled ? console.dir : noop;
@@ -38,49 +38,49 @@ class Logger {
 	}
 
 	/**
-	 * Logs any number of values at the "error" log level
+	 * Log any number of values at the "error" log level
 	 */
 	get error() {
 		return this.enabled ? console.error : noop;
 	}
 
 	/**
-	 * Logs any number of values at the "info" log level
+	 * Log any number of values at the "info" log level
 	 */
 	get info() {
 		return this.enabled ? console.info : noop;
 	}
 
 	/**
-	 * Logs any number of values at the "log" log level
+	 * Log any number of values at the "log" log level
 	 */
 	get log() {
 		return this.enabled ? console.log : noop;
 	}
 
 	/**
-	 * Logs data as a table, with optional properties to use as columns
+	 * Log data as a table, with optional properties to use as columns
 	 */
 	get table() {
 		return this.enabled ? console.table : noop;
 	}
 
 	/**
-	 * Logs any number of values together with a trace from where it was called
+	 * Log any number of values together with a trace from where it was called
 	 */
 	get trace() {
 		return this.enabled ? console.trace : noop;
 	}
 
 	/**
-	 * Logs any number of values at the "warn" log level
+	 * Log any number of values at the "warn" log level
 	 */
 	get warn() {
 		return this.enabled ? console.warn : noop;
 	}
 
 	/**
-	 * - Starts a logged timer with a label
+	 * - Start a logged timer with a label
 	 * - Returns a `Time`-object for logging the current duration of the timer and stopping the timer _(and logging the total duration)_
 	 */
 	time(label: string): Time {
@@ -104,8 +104,8 @@ class Time {
 	}
 
 	/**
-	 * - Logs the current duration of the timer
-	 * - Ignored if logging is disabled
+	 * - Log the current duration of the timer
+	 * - _(Ignored if logging is disabled)_
 	 */
 	log(): void {
 		if (this.state.started && !this.state.stopped && logger.enabled) {
@@ -114,8 +114,8 @@ class Time {
 	}
 
 	/**
-	 * - Stops the timer and logs the total duration
-	 * - Will always log the total duration, even if logging is disabled
+	 * - Stop the timer and logs the total duration
+	 * - _(Will always log the total duration, even if logging is disabled)_
 	 */
 	stop(): void {
 		if (this.state.started && !this.state.stopped) {

package/src/js/math.ts

@@ -20,7 +20,7 @@ export function min(values: number[]): number {
 }
 
 /**
- * Rounds a number to a specific number of decimal places _(defaults to 0)_
+ * Round a number to a specific number of decimal places _(defaults to 0)_
  */
 export function round(value: number, decimals?: number): number {
 	if (typeof decimals !== 'number' || decimals < 1) {

package/src/js/models.ts

@@ -13,6 +13,11 @@ export type EventPosition = {
 	y: number;
 };
 
+export type KeyedValue<
+	Item,
+	Key extends keyof Item,
+> = Item[Key] extends PropertyKey ? Item[Key] : never;
+
 export type NestedArrayType<Value> = Value extends Array<infer NestedValue>
 	? NestedArrayType<NestedValue>
 	: Value;
@@ -20,11 +25,6 @@ export type NestedArrayType<Value> = Value extends Array<infer NestedValue>
 // biome-ignore lint/suspicious/noExplicitAny: <explanation>
 export type GenericCallback = (...args: any[]) => any;
 
-export type GetterSetter<Value> = {
-	get(): Value;
-	set(value: Value): void;
-};
-
 export type Key = number | string;
 
 export type PlainObject = UnknownRecord;

package/src/js/number.ts

@@ -6,7 +6,7 @@ export function between(value: number, min: number, max: number): boolean {
 }
 
 /**
- * - Clamps a number between a minimum and maximum value
+ * - Clamp a number between a minimum and maximum value
  * - If `loop` is `true`, when the value is less than the minimum, it will be clamped as the maximum, and vice versa
  */
 export function clamp(
@@ -23,7 +23,7 @@ export function clamp(
 }
 
 /**
- * - Gets the number value from an unknown value
+ * - Get the number value from an unknown value
  * - Returns `NaN` if the value is `undefined`, `null`, or cannot be parsed
  * - Based on Lodash :-)
  */