@oscarpalmer/atoms 0.74.1 → 0.76.0

package/src/js/array/find.ts

@@ -1,29 +1,54 @@
-import {findValue} from '../internal/array-find';
-import type {Key} from '../models';
-import type {BooleanCallback, KeyCallback} from './models';
+import type {BooleanCallback, KeyCallback} from '~/array/models';
+import {findValue} from '~/internal/array/find';
 
 /**
- * Returns the first item matching `value`, or `undefined` if no match is found
+ * Get the first item matching `value` _(or `undefined` if no match is found)_
  */
-export function find<Model, Value>(
-	array: Model[],
-	value: Value | BooleanCallback<Model>,
-): Model | undefined;
+export function find<Item>(array: Item[], value: Item): Item | undefined;
 
 /**
- * - Returns the first matching item, or `undefined` if no match is found
+ * Get the first item matching `value` _(or `undefined` if no match is found)_
+ */
+export function find<Item>(
+	array: Item[],
+	matches: BooleanCallback<Item>,
+): Item | undefined;
+
+/**
+ * - Get the first matching item _(or `undefined` if no match is found)_
+ * - Use `key` to find a comparison value to match with `value`
+ */
+export function find<Item, Key extends keyof Item>(
+	array: Item[],
+	key: Key,
+	value: Item[Key],
+): Item | undefined;
+
+/**
+ * - Get the first matching item _(or `undefined` if no match is found)_
  * - Use `key` to find a comparison value to match with `value`
  */
-export function find<Model, Value = Model>(
-	array: Model[],
-	value: Value,
-	key: Key | KeyCallback<Model>,
-): Model | undefined;
+export function find<Item, Key extends KeyCallback<Item>>(
+	array: Item[],
+	key: Key,
+	value: ReturnType<Key>,
+): Item | undefined;
+
+export function find<Item>(
+	array: unknown[],
+	...parameters: unknown[]
+): Item | undefined {
+	const {length} = parameters;
 
-export function find<Model, Value = Model>(
-	array: Model[],
-	value: Value | BooleanCallback<Model>,
-	key?: Key | KeyCallback<Model>,
-): Model | undefined {
-	return findValue('value', array, value, key) as Model | undefined;
+	return findValue(
+		'value',
+		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 Item | undefined;
 }

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

@@ -1,47 +1,178 @@
-import {getCallbacks} from '../internal/array-callbacks';
-import type {Key} from '../models';
-import type {KeyCallback} from './models';
+import type {KeyCallback, ValueCallback} from '~/array/models';
+import {getCallbacks} from '~/internal/array/callbacks';
+import type {Key, KeyedValue, PlainObject} from '~/models';
 
 /**
- * Groups an array of items using a key or callback
+ * Create a record from an array of items using a specific key
  */
-export function groupBy<Value>(
-	array: Value[],
-	key: Key | KeyCallback<Value>,
-): Record<Key, Value[]> {
-	return groupValues(array, key, true, false) as never;
+export function groupBy<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 groupBy<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 groupBy<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 groupBy<Item, Key extends KeyCallback<Item>>(
+	array: Item[],
+	key: Key,
+	arrays: true,
+): Record<ReturnType<Key>, 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>(
+	array: Item[],
+	key: Key,
+	value: Value,
+): Record<KeyedValue<Item, 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 groupBy<Item, Key extends keyof Item, Value extends keyof Item>(
+	array: Item[],
+	key: Key,
+	value: Value,
+	arrays: true,
+): Record<KeyedValue<Item, Key>, Array<KeyedValue<Item, Value>>>;
+
+/**
+ * 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>,
+>(
+	array: Item[],
+	key: Key,
+	value: Value,
+): Record<KeyedValue<Item, Key>, ReturnType<Value>>;
+
+/**
+ * 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>,
+>(
+	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 groupBy<
+	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 groupBy<
+	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 groupBy<
+	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 groupBy<
+	Item,
+	Key extends KeyCallback<Item>,
+	Value extends ValueCallback<Item>,
+>(
+	array: Item[],
+	key: Key,
+	value: Value,
+	arrays: true,
+): Record<ReturnType<Key>, Array<ReturnType<Value>>>;
+
+export function groupBy(
+	array: unknown[],
+	first?: boolean,
+	second?: unknown,
+	third?: boolean,
+): PlainObject {
+	return groupValues(
+		array,
+		first,
+		second,
+		first === true || second === true || third === true,
+	) as never;
 }
 
-export function groupValues<Value>(
-	array: Value[],
-	key: Key | KeyCallback<Value>,
+export function groupValues(
+	array: unknown[],
+	key: unknown,
+	value: unknown,
 	arrays: boolean,
-	indicable: boolean,
 ): Record<Key, unknown> {
-	const callbacks = getCallbacks(undefined, key);
-	const hasCallback = typeof callbacks?.key === 'function';
-
-	if (!hasCallback && !indicable) {
-		return {};
-	}
-
+	const callbacks = getCallbacks(undefined, key, value);
 	const record: Record<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 (arrays) {
 			const existing = record[key];
 
-			if (Array.isArray(existing)) {
-				existing.push(value);
-			} else {
+			if (existing == null) {
 				record[key] = [value];
+			} else {
+				(existing as unknown[]).push(value);
 			}
 		} else {
 			record[key] = value;

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

@@ -1,29 +1,51 @@
-import {findValue} from '../internal/array-find';
-import type {Key} from '../models';
-import type {BooleanCallback, KeyCallback} from './models';
+import type {BooleanCallback, KeyCallback} from '~/array/models';
+import {findValue} from '~/internal/array/find';
 
 /**
- * Returns the index for the first item matching `value`, or `-1` if no match is found
+ * Get the index for the first item matching `value` _(or `-1` if no match is found)_
  */
-export function indexOf<Model, Value>(
-	array: Model[],
-	value: Value | BooleanCallback<Model>,
+export function indexOf<Item>(array: Item[], value: Item): number;
+
+/**
+ * Get the index for the first item matching `value` _(or `-1` if no match is found)_
+ */
+export function indexOf<Item>(
+	array: Item[],
+	matches: BooleanCallback<Item>,
 ): number;
 
 /**
- * - Returns the index for the first matching item, or `-1` if no match is found
+ * - 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<Model, Value = Model>(
-	array: Model[],
-	value: Value,
-	key: Key | KeyCallback<Model>,
+export function indexOf<Item, Key extends keyof Item>(
+	array: Item[],
+	key: Key,
+	value: Item[Key],
 ): number;
 
-export function indexOf<Model, Value = Model>(
-	array: Model[],
-	value: Value | BooleanCallback<Model>,
-	key?: Key | KeyCallback<Model>,
-): number {
-	return findValue('index', array, value, key) as 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(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;
 }

package/src/js/array/index.ts

@@ -1,19 +1,20 @@
-import type {NestedArrayType} from '../models';
-import {insertValues} from './insert';
+import {insertValues} from '~/array/insert';
+import type {NestedArrayType} from '~/models';
 
 /**
- * Flattens an array _(using native `flat` and maximum depth)_
+ * Flatten an array _(using native `flat` and maximum depth)_
  */
-export function flatten<Value>(array: Value[]): NestedArrayType<Value>[] {
-	return array.flat(Number.POSITIVE_INFINITY) as NestedArrayType<Value>[];
+export function flatten<Item>(array: Item[]): NestedArrayType<Item>[] {
+	return array.flat(Number.POSITIVE_INFINITY) as NestedArrayType<Item>[];
 }
 
 /**
- * - Pushes values to the end of an array, returning the new length
- * - Uses chunking to avoid stack overflow
+ * - Push values to the end of an array
+ * - Returns the new length
+ * - _(Uses chunking to avoid stack overflow)_
  */
-export function push<Value>(array: Value[], values: Value[]): number {
-	return insertValues('push', array, values, array.length, 0) as number;
+export function push<Item>(array: Item[], pushed: Item[]): number {
+	return insertValues('push', array, pushed, array.length, 0) as number;
 }
 
 export * from './chunk';

package/src/js/array/insert.ts

@@ -1,30 +1,44 @@
-import {chunk} from './chunk';
-import type {InsertType} from './models';
+import {chunk} from '~/array/chunk';
+import type {InsertType} from '~/array/models';
 
 /**
- * - Inserts values into an array at a specified index
- * - Uses chunking to avoid stack overflow
+ * - Insert values into an array _(at the end)_
+ * - _(Uses chunking to avoid stack overflow_)
  */
-export function insert<Value>(
-	array: Value[],
-	index: number,
-	values: Value[],
+export function insert<Item>(array: Item[], items: Item[]): void;
+
+/**
+ * - Insert values into an array at a specified index
+ * - _(Uses chunking to avoid stack overflow_)
+ */
+export function insert<Item>(array: Item[], index: number, items: Item[]): void;
+
+export function insert(
+	array: unknown[],
+	first: unknown,
+	second?: unknown[],
 ): void {
-	insertValues('splice', array, values, index, 0);
+	insertValues(
+		'splice',
+		array,
+		Array.isArray(first) ? first : (second ?? []),
+		typeof first === 'number' ? first : array.length,
+		0,
+	);
 }
 
-export function insertValues<Value>(
+export function insertValues<Item>(
 	type: InsertType,
-	array: Value[],
-	values: Value[],
+	array: Item[],
+	items: Item[],
 	start: number,
 	deleteCount: number,
 ): unknown {
-	const chunked = chunk(values);
+	const chunked = chunk(items);
 	const lastIndex = chunked.length - 1;
 
 	let index = Number(chunked.length);
-	let returned: Value[] | undefined;
+	let returned: Item[] | undefined;
 
 	while (--index >= 0) {
 		const result = array.splice(

package/src/js/array/models.ts

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

package/src/js/array/shuffle.ts

@@ -1,9 +1,9 @@
-import {getRandomInteger} from '../random';
+import {getRandomInteger} from '~/random';
 
 /**
- * Shuffles an array
+ * Shuffle an array
  */
-export function shuffle<Value>(array: Value[]): Value[] {
+export function shuffle<Item>(array: Item[]): Item[] {
 	const shuffled = array.slice();
 	const {length} = shuffled;
 

package/src/js/array/sort.ts

@@ -1,43 +1,42 @@
-import {isKey} from '../is';
-import type {Key, PlainObject} from '../models';
-import {compare} from '../value/compare';
-import type {SortKey, SortKeyCallback, SortKeyWithCallback} from './models';
+import type {
+	SortKey,
+	SortKeyCallback,
+	SortKeyWithCallback,
+} from '~/array/models';
+import {isKey} from '~/is';
+import type {Key, PlainObject} from '~/models';
+import {compare} from '~/value/compare';
 
 /**
- * Sorts an array of items _(ascending by default)_
+ * Sort an array of items _(defaults to ascending)_
  */
-export function sort<Value>(array: Value[], descending?: boolean): Value[];
+export function sort<Item>(array: Item[], descending?: boolean): Item[];
 
 /**
- * - Sorts an array of items, using a `key` to sort by a specific value
- * - Ascending by default, but can be changed by setting `descending` to `true`, or using a `SortKey`
+ * - 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<Value>(
-	array: Value[],
-	key: Key | SortKey<Value> | SortKeyCallback<Value>,
+export function sort<Item>(
+	array: Item[],
+	key: Key | SortKey<Item> | SortKeyCallback<Item>,
 	descending?: boolean,
-): Value[];
+): Item[];
 
 /**
- * - Sorts an array of items, using multiple `keys` to sort by specific values
- * - Ascending by default, but can be changed by setting `descending` to `true`, or using `SortKey`
+ * - 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<Value>(
-	array: Value[],
-	keys: Array<Key | SortKey<Value> | SortKeyCallback<Value>>,
+export function sort<Item>(
+	array: Item[],
+	keys: Array<Key | SortKey<Item> | SortKeyCallback<Item>>,
 	descending?: boolean,
-): Value[];
-
-export function sort<Value>(
-	array: Value[],
-	first?:
-		| boolean
-		| Key
-		| SortKey<Value>
-		| SortKeyCallback<Value>
-		| Array<Key | SortKey<Value> | SortKeyCallback<Value>>,
-	second?: boolean,
-): Value[] {
+): Item[];
+
+export function sort(
+	array: unknown[],
+	first?: unknown,
+	second?: unknown,
+): unknown[] {
 	if (array.length < 2) {
 		return array;
 	}
@@ -52,23 +51,22 @@ export function sort<Value>(
 
 	const keys = (Array.isArray(first) ? first : [first])
 		.map(key => {
-			const returned: SortKeyWithCallback<Value> = {
+			const returned: SortKeyWithCallback<unknown> = {
 				direction,
 				callback: undefined as never,
 			};
 
 			if (isKey(key)) {
-				returned.callback = (value: Value) =>
-					(value as PlainObject)[key] as never;
+				returned.callback = value => (value as PlainObject)[key] as never;
 			} else if (typeof key === 'function') {
 				returned.callback = key;
 			} else if (typeof key?.value === 'function' || isKey(key?.value)) {
 				returned.direction = key?.direction ?? direction;
+
 				returned.callback =
 					typeof key.value === 'function'
 						? key.value
-						: (value: Value) =>
-								(value as PlainObject)[key.value as Key] as never;
+						: value => (value as PlainObject)[key.value as Key] as never;
 			}
 
 			return returned;