@oscarpalmer/atoms 0.75.0 → 0.76.0

package/src/js/array/splice.ts

@@ -1,57 +1,53 @@
-import {insertValues} from '@/array/insert';
+import {insertValues} from '~/array/insert';
 
 /**
  * Removes and returns all items from an array starting from a specific index
  */
-export function splice<Value>(array: Value[], start: number): Value[];
+export function splice<Item>(array: Item[], start: number): Item[];
 
 /**
  * Removes and returns _(up to)_ a specific amount of items from an array, starting from a specific index
  */
-export function splice<Value>(
-	array: Value[],
+export function splice<Item>(
+	array: Item[],
 	start: number,
 	amount: number,
-): Value[];
+): Item[];
 
 /**
  * - Splices values into an array and returns any removed values
  * - Uses chunking to avoid stack overflow
  */
-export function splice<Value>(
-	array: Value[],
+export function splice<Item>(
+	array: Item[],
 	start: number,
-	values: Value[],
-): Value[];
+	added: Item[],
+): Item[];
 
 /**
  * - Splices values into an array and returns any removed values
  * - Uses chunking to avoid stack overflow
  */
-export function splice<Value>(
-	array: Value[],
+export function splice<Item>(
+	array: Item[],
 	start: number,
 	amount: number,
-	values: Value[],
-): Value[];
+	added: Item[],
+): Item[];
 
-export function splice<Value>(
-	array: Value[],
+export function splice(
+	array: unknown[],
 	start: number,
-	amountOrValues?: number | Value[],
-	values?: Value[],
-): Value[] {
-	const amoutOrValuesIsArray = Array.isArray(amountOrValues);
+	first?: number | unknown[],
+	second?: unknown[],
+): unknown[] {
+	const isArray = Array.isArray(first);
 
 	return insertValues(
 		'splice',
 		array,
-		amoutOrValuesIsArray ? amountOrValues : values ?? [],
+		isArray ? first : (second ?? []),
 		start,
-		amoutOrValuesIsArray
-			? array.length
-			: typeof amountOrValues === 'number' && amountOrValues > 0
-				? amountOrValues
-				: 0,
-	) as Value[];
+		isArray ? array.length : typeof first === 'number' && first > 0 ? first : 0,
+	) as unknown[];
 }

package/src/js/array/to-map.ts

@@ -1,82 +1,170 @@
-import type {KeyCallback} from '@/array/models';
-import {getCallbacks} from '@/internal/array-callbacks';
-import type {Key} from '@/models';
+import type {KeyCallback, ValueCallback} from '~/array/models';
+import {getCallbacks} from '~/internal/array/callbacks';
+import type {Key, KeyedValue} from '~/models';
 
 /**
- * Converts an array into a map, using indices as keys
+ * Create a map from an array of items _(using their indices as keys)_
  */
-export function toMap<Value>(array: Value[]): Map<number, Value>;
+export function toMap<Item>(array: Item[]): Map<number, Item>;
 
 /**
- * Converts an array into a map, using indices as keys and grouping values into arrays
+ * Create a map from an array of items using a specific key
  */
-export function toMap<Value>(
-	array: Value[],
+export function toMap<Item, Key extends keyof Item>(
+	array: Item[],
+	key: Key,
+): Map<KeyedValue<Item, Key>, Item>;
+
+/**
+ * Create a map from an array of items using a specific key, and grouping them into arrays
+ */
+export function toMap<Item, Key extends keyof Item>(
+	array: Item[],
+	key: Key,
 	arrays: true,
-): Map<number, Value[]>;
+): Map<KeyedValue<Item, Key>, Item[]>;
 
 /**
- * - Converts an array into a map
- * - Uses `key` to find an identifcation value to use as keys
+ * Create a map from an array of items using a specific key
  */
-export function toMap<Value>(array: Value[], key: Key): Map<Key, Value>;
+export function toMap<Item, Key extends KeyCallback<Item>>(
+	array: Item[],
+	key: Key,
+): Map<ReturnType<Key>, Item>;
 
 /**
- * - Converts an array into a map
- * - Uses `key` to find an identifcation value to use as keys
- * - Groups values into arrays
+ * Create a map from an array of items using a specific key, and grouping them into arrays
  */
-export function toMap<Value>(
-	array: Value[],
+export function toMap<Item, Key extends KeyCallback<Item>>(
+	array: Item[],
 	key: Key,
 	arrays: true,
-): Map<Key, Value[]>;
+): Map<ReturnType<Key>, Item[]>;
 
 /**
- * - Converts an array into a map
- * - Uses `key` to find an identifcation value to use as keys
+ * Create a map from an array of items using a specific key and value
  */
-export function toMap<Value>(
-	array: Value[],
-	key: KeyCallback<Value>,
-): Map<Key, Value>;
+export function toMap<Item, Key extends keyof Item, Value extends keyof Item>(
+	array: Item[],
+	key: Key,
+	value: Value,
+): Map<KeyedValue<Item, Key>, KeyedValue<Item, Value>>;
 
 /**
- * - Converts an array into a map
- * - Uses `key` to find an identifcation value to use as keys
- * - Groups values into arrays
+ * Create a map from an array of items using a specific key and value, and grouping them into arrays
  */
-export function toMap<Value>(
-	array: Value[],
-	key: KeyCallback<Value>,
+export function toMap<Item, Key extends keyof Item, Value extends keyof Item>(
+	array: Item[],
+	key: Key,
+	value: Value,
 	arrays: true,
-): Map<Key, Value[]>;
+): Map<KeyedValue<Item, Key>, Array<KeyedValue<Item, Value>>>;
 
-export function toMap<Value>(
-	array: Value[],
-	first?: boolean | Key | KeyCallback<Value>,
-	second?: boolean,
+/**
+ * Create a map from an array of items using a specific key and value
+ */
+export function toMap<
+	Item,
+	Key extends keyof Item,
+	Value extends ValueCallback<Item>,
+>(
+	array: Item[],
+	key: Key,
+	value: Value,
+): Map<KeyedValue<Item, Key>, ReturnType<Value>>;
+
+/**
+ * Create a map from an array of items using a specific key and value, and grouping them into arrays
+ */
+export function toMap<
+	Item,
+	Key extends keyof Item,
+	Value extends ValueCallback<Item>,
+>(
+	array: Item[],
+	key: Key,
+	value: Value,
+	arrays: true,
+): Map<KeyedValue<Item, Key>, Array<ReturnType<Value>>>;
+
+/**
+ * Create a map from an array of items using a specific key and value
+ */
+export function toMap<
+	Item,
+	Key extends KeyCallback<Item>,
+	Value extends keyof Item,
+>(
+	array: Item[],
+	key: Key,
+	value: Value,
+): Map<ReturnType<Key>, KeyedValue<Item, Value>>;
+
+/**
+ * Create a map from an array of items using a specific key and value, and grouping them into arrays
+ */
+export function toMap<
+	Item,
+	Key extends KeyCallback<Item>,
+	Value extends keyof Item,
+>(
+	array: Item[],
+	key: Key,
+	value: Value,
+	arrays: true,
+): Map<ReturnType<Key>, Array<KeyedValue<Item, Value>>>;
+
+/**
+ * Create a map from an array of items using a specific key and value
+ */
+export function toMap<
+	Item,
+	Key extends KeyCallback<Item>,
+	Value extends ValueCallback<Item>,
+>(
+	array: Item[],
+	key: Key,
+	value: Value,
+): Map<ReturnType<Key>, ReturnType<Value>>;
+
+/**
+ * Create a map from an array of items using a specific key and value, and grouping them into arrays
+ */
+export function toMap<
+	Item,
+	Key extends KeyCallback<Item>,
+	Value extends ValueCallback<Item>,
+>(
+	array: Item[],
+	key: Key,
+	value: Value,
+	arrays: true,
+): Map<ReturnType<Key>, Array<ReturnType<Value>>>;
+
+export function toMap(
+	array: unknown[],
+	first?: unknown,
+	second?: unknown,
+	third?: unknown,
 ): Map<Key, unknown> {
-	const asArrays = first === true || second === true;
-	const callbacks = getCallbacks(undefined, first);
-	const hasCallback = typeof callbacks?.key === 'function';
+	const asArrays = first === true || second === true || third === true;
+	const callbacks = getCallbacks(undefined, first, second);
 	const map = new Map<Key, unknown>();
 	const {length} = array;
 
 	for (let index = 0; index < length; index += 1) {
-		const value = array[index];
+		const item = array[index];
 
-		const key = hasCallback
-			? (callbacks?.key?.(value, index, array) ?? index)
-			: index;
+		const key = callbacks?.key?.(item, index, array) ?? index;
+		const value = callbacks?.value?.(item, index, array) ?? item;
 
 		if (asArrays) {
 			const existing = map.get(key);
 
-			if (Array.isArray(existing)) {
-				existing.push(value);
-			} else {
+			if (existing == null) {
 				map.set(key, [value]);
+			} else {
+				(existing as unknown[]).push(value);
 			}
 		} else {
 			map.set(key, value);

package/src/js/array/to-record.ts

@@ -1,66 +1,164 @@
-import {groupValues} from '@/array/group-by';
-import type {KeyCallback} from '@/array/models';
-import type {Key} from '@/models';
+import {groupValues} from '~/array/group-by';
+import type {KeyCallback, ValueCallback} from '~/array/models';
+import type {KeyedValue, PlainObject} from '~/models';
 
 /**
- * Converts an array into a record, using indices as keys
+ * Create a record from an array of items _(using their indices as keys)_
  */
-export function toRecord<Value>(array: Value[]): Record<number, Value>;
+export function toRecord<Item>(array: Item[]): Record<number, Item>;
 
 /**
- * Converts an array into a record, using indices as keys and grouping values into arrays
+ * Create a record from an array of items using a specific key
  */
-export function toRecord<Value>(
-	array: Value[],
+export function toRecord<Item, Key extends keyof Item>(
+	array: Item[],
+	key: Key,
+): Record<KeyedValue<Item, Key>, Item>;
+
+/**
+ * Create a record from an array of items using a specific key, and grouping them into arrays
+ */
+export function toRecord<Item, Key extends keyof Item>(
+	array: Item[],
+	key: Key,
+	arrays: true,
+): Record<KeyedValue<Item, Key>, Item[]>;
+
+/**
+ * Create a record from an array of items using a specific key
+ */
+export function toRecord<Item, Key extends KeyCallback<Item>>(
+	array: Item[],
+	key: Key,
+): Record<ReturnType<Key>, Item>;
+
+/**
+ * Create a record from an array of items using a specific key, and grouping them into arrays
+ */
+export function toRecord<Item, Key extends KeyCallback<Item>>(
+	array: Item[],
+	key: Key,
 	arrays: true,
-): Record<number, Value[]>;
+): Record<ReturnType<Key>, Item[]>;
 
 /**
- * - Converts an array into a record
- * - Uses `key` to find an identifcation value to use as keys
+ * Create a record from an array of items using a specific key and value
  */
-export function toRecord<Value>(array: Value[], key: Key): Record<Key, Value>;
+export function toRecord<
+	Item,
+	Key extends keyof Item,
+	Value extends keyof Item,
+>(
+	array: Item[],
+	key: Key,
+	value: Value,
+): Record<KeyedValue<Item, Key>, KeyedValue<Item, Value>>;
 
 /**
- * - Converts an array into a record
- * - Uses `key` to find an identifcation value to use as keys
- * - Groups values into arrays
+ * Create a record from an array of items using a specific key and value, and grouping them into arrays
  */
-export function toRecord<Value>(
-	array: Value[],
+export function toRecord<
+	Item,
+	Key extends keyof Item,
+	Value extends keyof Item,
+>(
+	array: Item[],
 	key: Key,
+	value: Value,
 	arrays: true,
-): Record<Key, Value[]>;
+): Record<KeyedValue<Item, Key>, Array<KeyedValue<Item, Value>>>;
 
 /**
- * - Converts an array into a record
- * - Uses `key` to find an identifcation value to use as keys
+ * Create a record from an array of items using a specific key and value
  */
-export function toRecord<Value>(
-	array: Value[],
-	key: KeyCallback<Value>,
-): Record<Key, Value>;
+export function toRecord<
+	Item,
+	Key extends keyof Item,
+	Value extends ValueCallback<Item>,
+>(
+	array: Item[],
+	key: Key,
+	value: Value,
+): Record<KeyedValue<Item, Key>, ReturnType<Value>>;
 
 /**
- * - Converts an array into a record
- * - Uses `key` to find an identifcation value to use as keys
- * - Groups values into arrays
+ * Create a record from an array of items using a specific key and value, and grouping them into arrays
  */
-export function toRecord<Value>(
-	array: Value[],
-	key: KeyCallback<Value>,
+export function toRecord<
+	Item,
+	Key extends keyof Item,
+	Value extends ValueCallback<Item>,
+>(
+	array: Item[],
+	key: Key,
+	value: Value,
+	arrays: true,
+): Record<KeyedValue<Item, Key>, Array<ReturnType<Value>>>;
+
+/**
+ * Create a record from an array of items using a specific key and value
+ */
+export function toRecord<
+	Item,
+	Key extends KeyCallback<Item>,
+	Value extends keyof Item,
+>(
+	array: Item[],
+	key: Key,
+	value: Value,
+): Record<ReturnType<Key>, KeyedValue<Item, Value>>;
+
+/**
+ * Create a record from an array of items using a specific key and value, and grouping them into arrays
+ */
+export function toRecord<
+	Item,
+	Key extends KeyCallback<Item>,
+	Value extends keyof Item,
+>(
+	array: Item[],
+	key: Key,
+	value: Value,
+	arrays: true,
+): Record<ReturnType<Key>, Array<KeyedValue<Item, Value>>>;
+
+/**
+ * Create a record from an array of items using a specific key and value
+ */
+export function toRecord<
+	Item,
+	Key extends KeyCallback<Item>,
+	Value extends ValueCallback<Item>,
+>(
+	array: Item[],
+	key: Key,
+	value: Value,
+): Record<ReturnType<Key>, ReturnType<Value>>;
+
+/**
+ * Create a record from an array of items using a specific key and value, and grouping them into arrays
+ */
+export function toRecord<
+	Item,
+	Key extends KeyCallback<Item>,
+	Value extends ValueCallback<Item>,
+>(
+	array: Item[],
+	key: Key,
+	value: Value,
 	arrays: true,
-): Record<Key, Value[]>;
+): Record<ReturnType<Key>, Array<ReturnType<Value>>>;
 
-export function toRecord<Value>(
-	array: Value[],
-	first?: boolean | Key | KeyCallback<Value>,
-	second?: boolean,
-): Record<Key, unknown> {
+export function toRecord(
+	array: unknown[],
+	first?: unknown,
+	second?: unknown,
+	third?: unknown,
+): PlainObject {
 	return groupValues(
 		array,
-		first as Key | KeyCallback<Value>,
-		first === true || second === true,
-		true,
+		first as never,
+		second,
+		first === true || second === true || third === true,
 	);
 }

package/src/js/array/unique.ts

@@ -1,24 +1,29 @@
-import type {KeyCallback} from '@/array/models';
-import {findValues} from '@/internal/array-find';
-import type {Key} from '@/models';
+import type {KeyCallback} from '~/array/models';
+import {findValues} from '~/internal/array/find';
 
 /**
- * Returns an array of unique items
+ * Get an array of unique items
  */
-export function unique<Value>(array: Value[]): Value[];
+export function unique<Item>(array: Item[]): Item[];
 
 /**
- * - Returns an array of unique items
+ * - Get an array of unique items
  * - Use `key` to find a comparison value to match with `value`
  */
-export function unique<Value>(
-	array: Value[],
-	key: Key | KeyCallback<Value>,
-): Value[];
+export function unique<Item, Key extends keyof Item>(
+	array: Item[],
+	key: Key,
+): Item[];
 
-export function unique<Value>(
-	array: Value[],
-	key?: Key | KeyCallback<Value>,
-): Value[] {
-	return findValues('unique', array, undefined, key);
+/**
+ * - Get an array of unique items
+ * - Use `key` to find a comparison value to match with `value`
+ */
+export function unique<Item, Key extends KeyCallback<Item>>(
+	array: Item[],
+	key: Key,
+): Item[];
+
+export function unique(array: unknown[], key?: unknown): unknown[] {
+	return findValues('unique', array, undefined, key, undefined);
 }

package/src/js/colour/base.ts

@@ -1,12 +1,12 @@
-import type {HexColour} from '@/colour/hex';
-import {isColourValue} from '@/colour/is';
+import type {HexColour} from '~/colour/hex';
+import {isColourValue} from '~/colour/is';
 
 export abstract class Colour<Model> {
 	private declare readonly $colour: string;
 	protected declare readonly state: ColourState<Model>;
 
 	/**
-	 * Gets the current value of the colour
+	 * Get the current value of the colour
 	 */
 	get value(): Model {
 		return {...this.state.value};

package/src/js/colour/functions.ts

@@ -1,7 +1,7 @@
-import {HexColour} from '@/colour/hex';
-import {HSLColour, type HSLColourValue} from '@/colour/hsl';
-import {RGBColour, type RGBColourValue} from '@/colour/rgb';
-import {clamp} from '@/number';
+import {HexColour} from '~/colour/hex';
+import {HSLColour, type HSLColourValue} from '~/colour/hsl';
+import {RGBColour, type RGBColourValue} from '~/colour/rgb';
+import {clamp} from '~/number';
 
 export const anyPattern = /^#*([a-f0-9]{3}){1,2}$/i;
 const groupedPattern = /^#*([a-f0-9]{2})([a-f0-9]{2})([a-f0-9]{2})$/i;
@@ -115,8 +115,6 @@ export function rgbToHsl(rgb: RGBColourValue): HSLColour {
 			case red:
 				hue = (green - blue) / delta + (green < blue ? 6 : 0);
 				break;
-			default:
-				break;
 		}
 
 		hue *= 60;

package/src/js/colour/hex.ts

@@ -1,6 +1,6 @@
-import {anyPattern, getNormalisedHex, hexToRgb} from '@/colour/functions';
-import type {HSLColour} from '@/colour/hsl';
-import type {RGBColour} from '@/colour/rgb';
+import {anyPattern, getNormalisedHex, hexToRgb} from '~/colour/functions';
+import type {HSLColour} from '~/colour/hsl';
+import type {RGBColour} from '~/colour/rgb';
 
 type State = {
 	value: string;
@@ -11,14 +11,14 @@ export class HexColour {
 	private readonly state: State;
 
 	/**
-	 * Gets the value of the colour
+	 * Get the value of the colour
 	 */
 	get value(): string {
 		return `#${this.state.value}`;
 	}
 
 	/**
-	 * Sets the value of the colour
+	 * Set the value of the colour
 	 */
 	set value(value: string) {
 		this.state.value = anyPattern.test(value)