@oscarpalmer/atoms 0.76.0 → 0.77.1

package/src/js/array/group-by.ts

@@ -1,140 +1,150 @@
-import type {KeyCallback, ValueCallback} from '~/array/models';
 import {getCallbacks} from '~/internal/array/callbacks';
 import type {Key, KeyedValue, PlainObject} from '~/models';
 
 /**
  * Create a record from an array of items using a specific key
  */
-export function groupBy<Item, Key extends keyof Item>(
+export function groupBy<Item extends PlainObject, ItemKey extends keyof Item>(
 	array: Item[],
-	key: Key,
-): Record<KeyedValue<Item, Key>, Item>;
+	key: ItemKey,
+): Record<KeyedValue<Item, ItemKey>, Item>;
 
 /**
  * Create a record from an array of items using a specific key, and grouping them into arrays
  */
-export function groupBy<Item, Key extends keyof Item>(
+export function groupBy<Item extends PlainObject, ItemKey extends keyof Item>(
 	array: Item[],
-	key: Key,
+	key: ItemKey,
 	arrays: true,
-): Record<KeyedValue<Item, Key>, Item[]>;
+): Record<KeyedValue<Item, ItemKey>, Item[]>;
 
 /**
  * Create a record from an array of items using a specific key
  */
-export function groupBy<Item, Key extends KeyCallback<Item>>(
-	array: Item[],
-	key: Key,
-): Record<ReturnType<Key>, Item>;
+export function groupBy<
+	Item,
+	ItemKey extends (item: Item, index: number, array: Item[]) => Key,
+>(array: Item[], key: ItemKey): Record<ReturnType<ItemKey>, Item>;
 
 /**
  * Create a record from an array of items using a specific key, and grouping them into arrays
  */
-export function groupBy<Item, Key extends KeyCallback<Item>>(
+export function groupBy<
+	Item,
+	ItemKey extends (item: Item, index: number, array: Item[]) => Key,
+>(
 	array: Item[],
-	key: Key,
+	key: ItemKey,
 	arrays: true,
-): Record<ReturnType<Key>, Item[]>;
+): Record<ReturnType<ItemKey>, Item[]>;
 
 /**
  * Create a record from an array of items using a specific key and value
  */
-export function groupBy<Item, Key extends keyof Item, Value extends keyof Item>(
+export function groupBy<
+	Item extends PlainObject,
+	ItemKey extends keyof Item,
+	ItemValue extends keyof Item,
+>(
 	array: Item[],
-	key: Key,
-	value: Value,
-): Record<KeyedValue<Item, Key>, KeyedValue<Item, Value>>;
+	key: ItemKey,
+	value: ItemValue,
+): Record<KeyedValue<Item, ItemKey>, KeyedValue<Item, ItemValue>>;
 
 /**
  * Create a record from an array of items using a specific key and value, and grouping them into arrays
  */
-export function groupBy<Item, Key extends keyof Item, Value extends keyof Item>(
+export function groupBy<
+	Item extends PlainObject,
+	ItemKey extends keyof Item,
+	ItemValue extends keyof Item,
+>(
 	array: Item[],
-	key: Key,
-	value: Value,
+	key: ItemKey,
+	value: ItemValue,
 	arrays: true,
-): Record<KeyedValue<Item, Key>, Array<KeyedValue<Item, Value>>>;
+): Record<KeyedValue<Item, ItemKey>, Array<KeyedValue<Item, ItemValue>>>;
 
 /**
  * Create a record from an array of items using a specific key and value
  */
 export function groupBy<
-	Item,
-	Key extends keyof Item,
-	Value extends ValueCallback<Item>,
+	Item extends PlainObject,
+	ItemKey extends keyof Item,
+	ItemValue extends (item: Item, index: number, array: Item[]) => unknown,
 >(
 	array: Item[],
-	key: Key,
-	value: Value,
-): Record<KeyedValue<Item, Key>, ReturnType<Value>>;
+	key: ItemKey,
+	value: ItemValue,
+): Record<KeyedValue<Item, ItemKey>, ReturnType<ItemValue>>;
 
 /**
  * Create a record from an array of items using a specific key and value, and grouping them into arrays
  */
 export function groupBy<
-	Item,
-	Key extends keyof Item,
-	Value extends ValueCallback<Item>,
+	Item extends PlainObject,
+	ItemKey extends keyof Item,
+	ItemValue extends (item: Item, index: number, array: Item[]) => unknown,
 >(
 	array: Item[],
-	key: Key,
-	value: Value,
+	key: ItemKey,
+	value: ItemValue,
 	arrays: true,
-): Record<KeyedValue<Item, Key>, Array<ReturnType<Value>>>;
+): Record<KeyedValue<Item, ItemKey>, Array<ReturnType<ItemValue>>>;
 
 /**
  * Create a record from an array of items using a specific key and value
  */
 export function groupBy<
-	Item,
-	Key extends KeyCallback<Item>,
-	Value extends keyof Item,
+	Item extends PlainObject,
+	ItemKey extends (item: Item, index: number, array: Item[]) => Key,
+	ItemValue extends keyof Item,
 >(
 	array: Item[],
-	key: Key,
-	value: Value,
-): Record<ReturnType<Key>, KeyedValue<Item, Value>>;
+	key: ItemKey,
+	value: ItemValue,
+): Record<ReturnType<ItemKey>, KeyedValue<Item, ItemValue>>;
 
 /**
  * Create a record from an array of items using a specific key and value, and grouping them into arrays
  */
 export function groupBy<
-	Item,
-	Key extends KeyCallback<Item>,
-	Value extends keyof Item,
+	Item extends PlainObject,
+	ItemKey extends (item: Item, index: number, array: Item[]) => Key,
+	ItemValue extends keyof Item,
 >(
 	array: Item[],
-	key: Key,
-	value: Value,
+	key: ItemKey,
+	value: ItemValue,
 	arrays: true,
-): Record<ReturnType<Key>, Array<KeyedValue<Item, Value>>>;
+): Record<ReturnType<ItemKey>, Array<KeyedValue<Item, ItemValue>>>;
 
 /**
  * Create a record from an array of items using a specific key and value
  */
 export function groupBy<
 	Item,
-	Key extends KeyCallback<Item>,
-	Value extends ValueCallback<Item>,
+	ItemKey extends (item: Item, index: number, array: Item[]) => Key,
+	ItemValue extends (item: Item, index: number, array: Item[]) => unknown,
 >(
 	array: Item[],
-	key: Key,
-	value: Value,
-): Record<ReturnType<Key>, ReturnType<Value>>;
+	key: ItemKey,
+	value: ItemValue,
+): Record<ReturnType<ItemKey>, ReturnType<ItemValue>>;
 
 /**
  * Create a record from an array of items using a specific key and value, and grouping them into arrays
  */
 export function groupBy<
 	Item,
-	Key extends KeyCallback<Item>,
-	Value extends ValueCallback<Item>,
+	ItemKey extends (item: Item, index: number, array: Item[]) => Key,
+	ItemValue extends (item: Item, index: number, array: Item[]) => unknown,
 >(
 	array: Item[],
-	key: Key,
-	value: Value,
+	key: ItemKey,
+	value: ItemValue,
 	arrays: true,
-): Record<ReturnType<Key>, Array<ReturnType<Value>>>;
+): Record<ReturnType<ItemKey>, Array<ReturnType<ItemValue>>>;
 
 export function groupBy(
 	array: unknown[],

package/src/js/array/index-of.ts

@@ -1,5 +1,5 @@
-import type {BooleanCallback, KeyCallback} from '~/array/models';
 import {findValue} from '~/internal/array/find';
+import type {Key, PlainObject} from '~/models';
 
 /**
  * Get the index for the first item matching `value` _(or `-1` if no match is found)_
@@ -11,41 +11,28 @@ export function indexOf<Item>(array: Item[], value: Item): number;
  */
 export function indexOf<Item>(
 	array: Item[],
-	matches: BooleanCallback<Item>,
+	matches: (item: Item, index: number, array: Item[]) => boolean,
 ): number;
 
 /**
  * - Get the index for the first matching item _(or `-1` if no match is found)_
  * - Use `key` to find a comparison value to match with `value`
  */
-export function indexOf<Item, Key extends keyof Item>(
+export function indexOf<Item extends PlainObject, ItemKey extends keyof Item>(
 	array: Item[],
-	key: Key,
-	value: Item[Key],
+	key: ItemKey,
+	value: Item[ItemKey],
 ): number;
 
 /**
  * - Get the index for the first matching item _(or `-1` if no match is found)_
  * - Use `key` to find a comparison value to match with `value`
  */
-export function indexOf<Item, Key extends KeyCallback<Item>>(
-	array: Item[],
-	key: Key,
-	value: ReturnType<Key>,
-): number;
+export function indexOf<
+	Item,
+	ItemKey extends (item: Item, index: number, array: Item[]) => Key,
+>(array: Item[], key: ItemKey, value: ReturnType<ItemKey>): number;
 
 export function indexOf(array: unknown[], ...parameters: unknown[]): number {
-	const {length} = parameters;
-
-	return findValue(
-		'index',
-		array,
-		length === 1 && typeof parameters[0] === 'function'
-			? parameters[0]
-			: undefined,
-		length === 2 ? parameters[0] : undefined,
-		length === 1 && typeof parameters[0] !== 'function'
-			? parameters[0]
-			: parameters[1],
-	) as number;
+	return findValue('index', array, parameters) as number;
 }

package/src/js/array/models.ts

@@ -1,13 +1,5 @@
 import type {GenericCallback, Key} from '~/models';
 
-export type ArrayCallback<Item, Value> = (
-	item: Item,
-	index: number,
-	array: Item[],
-) => Value;
-
-export type BooleanCallback<Item> = ArrayCallback<Item, boolean>;
-
 export type Callbacks = {
 	bool?: GenericCallback;
 	key?: GenericCallback;
@@ -18,18 +10,12 @@ export type FindType = 'index' | 'value';
 
 export type InsertType = 'push' | 'splice';
 
-export type KeyCallback<Item> = ArrayCallback<Item, Key>;
-
 export type SortKey<Item> = {
 	direction: 'asc' | 'desc';
-	value: Key | SortKeyCallback<Item>;
+	value: Key | ((item: Item) => Key);
 };
 
-export type SortKeyCallback<Item> = (item: Item) => unknown;
-
 export type SortKeyWithCallback<Item> = {
-	callback: SortKeyCallback<Item>;
+	callback: (item: Item) => Key;
 	direction: 'asc' | 'desc';
 };
-
-export type ValueCallback<Item> = ArrayCallback<Item, unknown>;

package/src/js/array/sort.ts

@@ -1,8 +1,4 @@
-import type {
-	SortKey,
-	SortKeyCallback,
-	SortKeyWithCallback,
-} from '~/array/models';
+import type {SortKey, SortKeyWithCallback} from '~/array/models';
 import {isKey} from '~/is';
 import type {Key, PlainObject} from '~/models';
 import {compare} from '~/value/compare';
@@ -18,7 +14,17 @@ export function sort<Item>(array: Item[], descending?: boolean): Item[];
  */
 export function sort<Item>(
 	array: Item[],
-	key: Key | SortKey<Item> | SortKeyCallback<Item>,
+	key: Key | SortKey<Item> | ((item: Item) => Key),
+	descending?: boolean,
+): Item[];
+
+/**
+ * - Sort an array of items, using a `key` to sort by a specific value
+ * - Defaults to ascending, but can be changed by setting `descending` to `true`, or using a `SortKey`
+ */
+export function sort<Item extends PlainObject, ItemKey extends keyof Item>(
+	array: Item[],
+	key: ItemKey | Key | SortKey<Item> | ((item: Item) => Key),
 	descending?: boolean,
 ): Item[];
 
@@ -28,7 +34,17 @@ export function sort<Item>(
  */
 export function sort<Item>(
 	array: Item[],
-	keys: Array<Key | SortKey<Item> | SortKeyCallback<Item>>,
+	keys: Array<Key | SortKey<Item> | ((item: Item) => Key)>,
+	descending?: boolean,
+): Item[];
+
+/**
+ * - Sort an array of items, using multiple `keys` to sort by specific values
+ * - Defaults to ascending, but can be changed by setting `descending` to `true`, or using `SortKey`
+ */
+export function sort<Item extends PlainObject, ItemKey extends keyof Item>(
+	array: Item[],
+	keys: Array<ItemKey | Key | SortKey<Item> | ((item: Item) => Key)>,
 	descending?: boolean,
 ): Item[];
 

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

@@ -1,6 +1,5 @@
-import type {KeyCallback, ValueCallback} from '~/array/models';
 import {getCallbacks} from '~/internal/array/callbacks';
-import type {Key, KeyedValue} from '~/models';
+import type {Key, KeyedValue, PlainObject} from '~/models';
 
 /**
  * Create a map from an array of items _(using their indices as keys)_
@@ -10,117 +9,124 @@ export function toMap<Item>(array: Item[]): Map<number, Item>;
 /**
  * Create a map from an array of items using a specific key
  */
-export function toMap<Item, Key extends keyof Item>(
+export function toMap<Item extends PlainObject, ItemKey extends keyof Item>(
 	array: Item[],
-	key: Key,
-): Map<KeyedValue<Item, Key>, Item>;
+	key: ItemKey,
+): Map<KeyedValue<Item, ItemKey>, 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>(
+export function toMap<Item extends PlainObject, ItemKey extends keyof Item>(
 	array: Item[],
-	key: Key,
+	key: ItemKey,
 	arrays: true,
-): Map<KeyedValue<Item, Key>, Item[]>;
+): Map<KeyedValue<Item, ItemKey>, Item[]>;
 
 /**
  * Create a map from an array of items using a specific key
  */
-export function toMap<Item, Key extends KeyCallback<Item>>(
-	array: Item[],
-	key: Key,
-): Map<ReturnType<Key>, Item>;
+export function toMap<
+	Item,
+	ItemKey extends (item: Item, index: number, array: Item[]) => Key,
+>(array: Item[], key: ItemKey): Map<ReturnType<ItemKey>, Item>;
 
 /**
  * Create a map from an array of items using a specific key, and grouping them into arrays
  */
-export function toMap<Item, Key extends KeyCallback<Item>>(
-	array: Item[],
-	key: Key,
-	arrays: true,
-): Map<ReturnType<Key>, Item[]>;
+export function toMap<
+	Item,
+	ItemKey extends (item: Item, index: number, array: Item[]) => Key,
+>(array: Item[], key: ItemKey, arrays: true): Map<ReturnType<ItemKey>, Item[]>;
 
 /**
  * Create a map from an array of items using a specific key and value
  */
-export function toMap<Item, Key extends keyof Item, Value extends keyof Item>(
+export function toMap<
+	Item extends PlainObject,
+	ItemKey extends keyof Item,
+	ItemValue extends keyof Item,
+>(
 	array: Item[],
-	key: Key,
-	value: Value,
-): Map<KeyedValue<Item, Key>, KeyedValue<Item, Value>>;
+	key: ItemKey,
+	value: ItemValue,
+): Map<KeyedValue<Item, ItemKey>, KeyedValue<Item, ItemValue>>;
 
 /**
  * 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 keyof Item>(
+export function toMap<
+	Item extends PlainObject,
+	ItemKey extends keyof Item,
+	ItemValue extends keyof Item,
+>(
 	array: Item[],
-	key: Key,
-	value: Value,
+	key: ItemKey,
+	value: ItemValue,
 	arrays: true,
-): Map<KeyedValue<Item, Key>, Array<KeyedValue<Item, Value>>>;
+): Map<KeyedValue<Item, ItemKey>, Array<KeyedValue<Item, ItemValue>>>;
 
 /**
  * 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>,
+	Item extends PlainObject,
+	ItemKey extends keyof Item,
+	ItemValue extends (item: Item, index: number, array: Item[]) => unknown,
 >(
 	array: Item[],
-	key: Key,
-	value: Value,
-): Map<KeyedValue<Item, Key>, ReturnType<Value>>;
+	key: ItemKey,
+	value: ItemValue,
+): Map<KeyedValue<Item, ItemKey>, ReturnType<ItemValue>>;
 
 /**
  * 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>,
+	Item extends PlainObject,
+	ItemKey extends keyof Item,
+	ItemValue extends (item: Item, index: number, array: Item[]) => unknown,
 >(
 	array: Item[],
-	key: Key,
-	value: Value,
+	key: ItemKey,
+	value: ItemValue,
 	arrays: true,
-): Map<KeyedValue<Item, Key>, Array<ReturnType<Value>>>;
+): Map<KeyedValue<Item, ItemKey>, Array<ReturnType<ItemValue>>>;
 
 /**
  * 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,
+	Item extends PlainObject,
+	ItemKey extends (item: Item, index: number, array: Item[]) => Key,
+	ItemValue extends keyof Item,
 >(
 	array: Item[],
-	key: Key,
-	value: Value,
-): Map<ReturnType<Key>, KeyedValue<Item, Value>>;
+	key: ItemKey,
+	value: ItemValue,
+): Map<ReturnType<ItemKey>, KeyedValue<Item, ItemValue>>;
 
 /**
  * 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,
+	Item extends PlainObject,
+	ItemKey extends (item: Item, index: number, array: Item[]) => Key,
+	ItemValue extends keyof Item,
 >(
 	array: Item[],
-	key: Key,
-	value: Value,
+	key: ItemKey,
+	value: ItemValue,
 	arrays: true,
-): Map<ReturnType<Key>, Array<KeyedValue<Item, Value>>>;
+): Map<ReturnType<ItemKey>, Array<KeyedValue<Item, ItemValue>>>;
 
 /**
  * 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>,
+	Key extends (item: Item, index: number, array: Item[]) => Key,
+	Value extends (item: Item, index: number, array: Item[]) => unknown,
 >(
 	array: Item[],
 	key: Key,
@@ -132,8 +138,8 @@ export function toMap<
  */
 export function toMap<
 	Item,
-	Key extends KeyCallback<Item>,
-	Value extends ValueCallback<Item>,
+	Key extends (item: Item, index: number, array: Item[]) => Key,
+	Value extends (item: Item, index: number, array: Item[]) => unknown,
 >(
 	array: Item[],
 	key: Key,