@oscarpalmer/atoms 0.192.0 → 0.193.1

package/src/array/swap.ts

@@ -1,322 +0,0 @@
-import {getArrayCallback} from '../internal/array/callbacks';
-import {indexOf} from '../internal/array/index-of';
-import {arraysOverlap} from '../internal/array/overlap';
-import type {PlainObject} from '../models';
-import {indexOfArray} from './match';
-
-// #region Functions
-
-/**
- * Swap two smaller arrays within a larger array
- *
- * If either of the smaller arrays are not present in the larger array, or if they overlap, the larger array will be returned unchanged
- *
- * @param array Array of items to swap
- * @param first First array
- * @param second Second array
- * @param callback Callback to get an item's value for matching
- * @returns Original array with items swapped _(or unchanged if unable to swap)_
- *
- * @example
- * ```typescript
- * swap(
- *   [
- *     {id: 1, name: 'Alice'},
- *     {id: 2, name: 'Bob'},
- *     {id: 3, name: 'Charlie'},
- *   ],
- *   [
- *     {id: 2, name: 'Bob'},
- *   ],
- *   [
- *     {id: 3, name: 'Charlie'},
- *   ],
- *   item => item.id,
- * ); // => [
- *    //   {id: 1, name: 'Alice'},
- *    //   {id: 3, name: 'Charlie'},
- *    //   {id: 2, name: 'Bob'},
- *    // ]
- * ```
- */
-export function swap<Item>(
-	array: Item[],
-	first: Item[],
-	second: Item[],
-	callback: (item: Item, index: number, array: Item[]) => unknown,
-): Item[];
-
-/**
- * Swap two smaller arrays within a larger array
- *
- * If either of the smaller arrays are not present in the larger array, or if they overlap, the larger array will be returned unchanged
- *
- * @param array Array of items to swap
- * @param first First array
- * @param second Second array
- * @param key Key to get an item's value for matching
- * @returns Original array with items swapped _(or unchanged if unable to swap)_
- *
- * @example
- * ```typescript
- * swap(
- *   [
- *     {id: 1, name: 'Alice'},
- *     {id: 2, name: 'Bob'},
- *     {id: 3, name: 'Charlie'},
- *   ],
- *   [
- *     {id: 2, name: 'Bob'},
- *   ],
- *   [
- *     {id: 3, name: 'Charlie'},
- *   ],
- *   'id',
- * ); // => [
- *    //   {id: 1, name: 'Alice'},
- *    //   {id: 3, name: 'Charlie'},
- *    //   {id: 2, name: 'Bob'},
- *    // ]
- * ```
- */
-export function swap<Item extends PlainObject, ItemKey extends keyof Item>(
-	array: Item[],
-	first: Item[],
-	second: Item[],
-	key: ItemKey,
-): Item[];
-
-/**
- * Swap two smaller arrays within a larger array
- *
- * If either of the smaller arrays are not present in the larger array, or if they overlap, the larger array will be returned unchanged
- *
- * @param array Array of items to swap
- * @param first First array
- * @param second Second array
- * @returns Original array with items swapped _(or unchanged if unable to swap)_
- *
- * @example
- * ```typescript
- * swap(
- *   [1, 2, 3, 4, 5, 6],
- *   [1, 2],
- *   [5, 6],
- * ); // => [5, 6, 3, 4, 1, 2]
- * ```
- */
-export function swap<Item>(array: Item[], first: Item[], second: Item[]): Item[];
-
-/**
- * Swap two indiced items in an array
- *
- * If either of the items are not present in the array, the array will be returned unchanged
- *
- * @param array Array of items to swap
- * @param first First item
- * @param second Second item
- * @param callback Callback to get an item's value for matching
- * @returns Original array with items swapped _(or unchanged if unable to swap)_
- *
- * @example
- * ```typescript
- * swap(
- *   [
- *     {id: 1, name: 'Alice'},
- *     {id: 2, name: 'Bob'},
- *     {id: 3, name: 'Charlie'},
- *   ],
- *   {id: 2, name: 'Bob'},
- *   {id: 3, name: 'Charlie'},
- *   item => item.id,
- * ); // => [
- *    //   {id: 1, name: 'Alice'},
- *    //   {id: 3, name: 'Charlie'},
- *    //   {id: 2, name: 'Bob'},
- *    // ]
- * ```
- */
-export function swap<Item>(
-	array: Item[],
-	first: Item,
-	second: Item,
-	callback: (item: Item, index: number, array: Item[]) => unknown,
-): Item[];
-
-/**
- * Swap two indiced items in an array
- *
- * If either of the items are not present in the array, the array will be returned unchanged
- *
- * @param array Array of items to swap
- * @param first First item
- * @param second Second item
- * @param key Key to get an item's value for matching
- * @returns Original array with items swapped _(or unchanged if unable to swap)_
- *
- * @example
- * ```typescript
- * swap(
- *   [
- *     {id: 1, name: 'Alice'},
- *     {id: 2, name: 'Bob'},
- *     {id: 3, name: 'Charlie'},
- *   ],
- *   {id: 2, name: 'Bob'},
- *   {id: 3, name: 'Charlie'},
- *   'id',
- * ); // => [
- *    //   {id: 1, name: 'Alice'},
- *    //   {id: 3, name: 'Charlie'},
- *    //   {id: 2, name: 'Bob'},
- *    // ]
- * ```
- */
-export function swap<Item extends PlainObject, ItemKey extends keyof Item>(
-	array: Item[],
-	first: Item,
-	second: Item,
-	key: ItemKey,
-): Item[];
-
-/**
- * Swap two indiced items in an array
- *
- * @param array Array of items to swap
- * @param first First item
- * @param second Second item
- * @returns Original array with items swapped _(or unchanged if unable to swap)_
- *
- * @example
- * ```typescript
- * swap(
- *   [1, 2, 3, 4, 5, 6],
- *   2,
- *   5,
- * ); // => [1, 5, 3, 4, 2, 6]
- * ```
- */
-export function swap<Item>(array: Item[], first: Item, second: Item): Item[];
-
-export function swap(
-	array: unknown[],
-	first: unknown,
-	second: unknown,
-	third?: unknown,
-): unknown[] {
-	if (!Array.isArray(array)) {
-		return [];
-	}
-
-	if (array.length === 0) {
-		return array;
-	}
-
-	if (Array.isArray(first) && Array.isArray(second)) {
-		return swapArrays(array, first, second, third);
-	}
-
-	return swapValues(array, first, second, third);
-}
-
-swap.indices = swapIndices;
-
-function swapArrays(array: unknown[], from: unknown[], to: unknown[], key: unknown): unknown[] {
-	if (from.length === 0 || to.length === 0) {
-		return array;
-	}
-
-	if (from.length === 1 && to.length === 1) {
-		return swapValues(array, from[0], to[0], key);
-	}
-
-	const fromIndex = indexOfArray(array, from, key as never);
-	const toIndex = indexOfArray(array, to, key as never);
-
-	if (fromIndex === -1 || toIndex === -1) {
-		return array;
-	}
-
-	const {first, second, overlap} = arraysOverlap(
-		{
-			array: from,
-			index: fromIndex,
-		},
-		{
-			array: to,
-			index: toIndex,
-		},
-	);
-
-	if (overlap) {
-		// The arrays overlap, so we can't swap them without losing data
-
-		return array;
-	}
-
-	array.splice(first.index, first.array.length, ...second.array);
-
-	array.splice(
-		second.index + (second.array.length - first.array.length),
-		second.array.length,
-		...first.array,
-	);
-
-	return array;
-}
-
-/**
- * Swap two indiced items in an array
- *
- * If either index is out of bounds, the array will be returned unchanged
- *
- * _Available as `swapIndices` and `swap.indices`_
- *
- * @param array Array of items to swap
- * @param first First index _(can be negative to count from the end)_
- * @param second Second index _(can be negative to count from the end)_
- * @returns Original array with items swapped _(or unchanged if unable to swap)_
- */
-function swapIndices<Item>(array: Item[], first: number, second: number): Item[] {
-	if (!Array.isArray(array) || array.length === 0) {
-		return [];
-	}
-
-	if (typeof first !== 'number' || typeof second !== 'number') {
-		return array;
-	}
-
-	const firstIndex = first < 0 ? array.length + first : first;
-	const secondIndex = second < 0 ? array.length + second : second;
-
-	if (firstIndex === secondIndex || firstIndex >= array.length || secondIndex >= array.length) {
-		return array;
-	}
-
-	const temp = array[firstIndex];
-
-	array[firstIndex] = array[secondIndex];
-	array[secondIndex] = temp;
-
-	return array;
-}
-
-function swapValues(array: unknown[], from: unknown, to: unknown, key?: unknown): unknown[] {
-	const callback = getArrayCallback(key);
-
-	const first =
-		callback == null
-			? array.indexOf(from)
-			: indexOf(array, callback, callback(from, undefined, []));
-
-	const second =
-		callback == null ? array.indexOf(to) : indexOf(array, callback, callback(to, undefined, []));
-
-	if (first === second || first === -1 || second === -1) {
-		return array;
-	}
-
-	return swapIndices(array, first, second);
-}
-
-// #endregion

package/src/array/to-map.ts

@@ -1,371 +0,0 @@
-import {getArrayCallbacks} from '../internal/array/callbacks';
-import type {Key, PlainObject} from '../models';
-
-// #region Functions
-
-function getMapValues(
-	array: unknown[],
-	first: unknown,
-	second: unknown,
-	arrays: boolean,
-): Map<unknown, unknown> {
-	if (!Array.isArray(array)) {
-		return new Map();
-	}
-
-	const {length} = array;
-	const callbacks = getArrayCallbacks(undefined, first, second);
-	const map = new Map<Key, unknown>();
-
-	for (let index = 0; index < length; index += 1) {
-		const item = array[index];
-
-		const key = callbacks?.keyed?.(item, index, array) ?? index;
-		const value = callbacks?.value?.(item, index, array) ?? item;
-
-		if (arrays) {
-			const existing = map.get(key);
-
-			if (existing == null) {
-				map.set(key, [value]);
-			} else {
-				(existing as unknown[]).push(value);
-			}
-		} else {
-			map.set(key, value);
-		}
-	}
-
-	return map;
-}
-
-/**
- * Create a _Map_ from an array of items using callbacks
- *
- * If multiple items have the same key, the latest item's value will be used
- *
- * @param array Array to convert
- * @param key Callback to get an item's grouping key
- * @param value Callback to get an item's value
- * @returns _Map_ of keyed values
- *
- * @example
- * ```typescript
- * toMap(
- *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
- *   item => item.value,
- *   item => item.id,
- * ); // => Map { 10 => 3, 20 => 2 }
- * ```
- */
-export function toMap<
-	Item,
-	KeyCallback extends (item: Item, index: number, array: Item[]) => Key,
-	ValueCallback extends (item: Item, index: number, array: Item[]) => unknown,
->(
-	array: Item[],
-	key: KeyCallback,
-	value: ValueCallback,
-): Map<ReturnType<KeyCallback>, ReturnType<ValueCallback>>;
-
-/**
- * Create a _Map_ from an array of items using a callback and value
- *
- * If multiple items have the same key, the latest item's value will be used
- *
- * @param array Array to convert
- * @param key Callback to get an item's grouping key
- * @param value Key to use for value
- * @returns _Map_ of keyed values
- *
- * @example
- * ```typescript
- * toMap(
- *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
- *   item => item.value,
- *   'id',
- * ); // => Map { 10 => 3, 20 => 2 }
- * ```
- */
-export function toMap<
-	Item extends PlainObject,
-	KeyCallback extends (item: Item, index: number, array: Item[]) => Key,
-	ItemValue extends keyof Item,
->(array: Item[], key: KeyCallback, value: ItemValue): Map<ReturnType<KeyCallback>, Item[ItemValue]>;
-
-/**
- * Create a _Map_ from an array of items using a key and callback
- *
- * If multiple items have the same key, the latest item's value will be used
- *
- * @param array Array to convert
- * @param key Key to use for grouping
- * @param value Callback to get an item's value
- * @returns _Map_ of keyed values
- *
- * @example
- * ```typescript
- * toMap(
- *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
- *   'value',
- *   item => item.id,
- * ); // => Map { 10 => 3, 20 => 2 }
- * ```
- */
-export function toMap<
-	Item extends PlainObject,
-	ItemKey extends keyof Item,
-	ValueCallback extends (item: Item, index: number, array: Item[]) => unknown,
->(array: Item[], key: ItemKey, value: ValueCallback): Map<Item[ItemKey], ReturnType<ValueCallback>>;
-
-/**
- * Create a _Map_ from an array of items using a key and value
- *
- * If multiple items have the same key, the latest item's value will be used
- *
- * @param array Array to convert
- * @param key Key to use for grouping
- * @param value Key to use for value
- * @returns _Map_ of keyed values
- *
- * @example
- * ```typescript
- * toMap(
- *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
- *   'value',
- *   'id',
- * ); // => Map { 10 => 3, 20 => 2 }
- * ```
- */
-export function toMap<
-	Item extends PlainObject,
-	ItemKey extends keyof Item,
-	ItemValue extends keyof Item,
->(array: Item[], key: ItemKey, value: ItemValue): Map<Item[ItemKey], Item[ItemValue]>;
-
-/**
- * Create a _Map_ from an array of items using a callback
- *
- * If multiple items have the same key, the latest item will be used
- *
- * @param array Array to convert
- * @param callback Callback to get an item's grouping key
- * @returns _Map_ of keyed items
- *
- * @example
- * ```typescript
- * toMap(
- *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
- *   item => item.value,
- * ); // => Map { 10 => {id: 3, value: 10}, 20 => {id: 2, value: 20} }
- * ```
- */
-export function toMap<Item, Callback extends (item: Item, index: number, array: Item[]) => Key>(
-	array: Item[],
-	callback: Callback,
-): Map<ReturnType<Callback>, Item>;
-
-/**
- * Create a _Map_ from an array of items using a key
- *
- * If multiple items have the same key, the latest item will be used
- *
- * @param array Array to convert
- * @param key Key to use for grouping
- * @returns _Map_ of keyed items
- *
- * @example
- * ```typescript
- * toMap(
- *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
- *   'value',
- * ); // => Map { 10 => {id: 3, value: 10}, 20 => {id: 2, value: 20} }
- * ```
- */
-export function toMap<Item extends PlainObject, ItemKey extends keyof Item>(
-	array: Item[],
-	key: ItemKey,
-): Map<Item[ItemKey], Item>;
-
-/**
- * Create a _Map_ from an array of items _(using indices as keys)_
- *
- * @param array Array to convert
- * @returns _Map_ of indiced items
- *
- * @example
- * ```typescript
- * toMap(
- *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
- * ); // => Map { 0 => {id: 1, value: 10}, 1 => {id: 2, value: 20}, 2 => {id: 3, value: 10} }
- * ```
- */
-export function toMap<Item>(array: Item[]): Map<number, Item>;
-
-export function toMap(array: unknown[], first?: unknown, second?: unknown): unknown {
-	return getMapValues(array, first, second, false);
-}
-
-toMap.arrays = toMapArrays;
-
-/**
- * Create a _Map_ from an array of items using callbacks, grouping values into arrays
- *
- * _Available as `toMapArrays` and `toMap.arrays`_
- *
- * @param array Array to convert
- * @param key Callback to get an item's grouping key
- * @param value Callback to get an item's value
- * @returns _Map_ of keyed arrays of values
- *
- * @example
- * ```typescript
- * toMapArrays(
- *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
- *   item => item.value,
- *   item => item.id,
- * ); // => Map { 10 => [1, 3], 20 => [2] }
- * ```
- */
-export function toMapArrays<
-	Item,
-	KeyCallback extends (item: Item, index: number, array: Item[]) => Key,
-	ValueCallback extends (item: Item, index: number, array: Item[]) => unknown,
->(
-	array: Item[],
-	key: KeyCallback,
-	value: ValueCallback,
-): Map<ReturnType<KeyCallback>, ReturnType<ValueCallback>[]>;
-
-/**
- * Create a _Map_ from an array of items using a callback and value, grouping values into arrays
- *
- * _Available as `toMapArrays` and `toMap.arrays`_
- *
- * @param array Array to convert
- * @param key Callback to get an item's grouping key
- * @param value Key to use for value
- * @returns _Map_ of keyed arrays of values
- *
- * @example
- * ```typescript
- * toMapArrays(
- *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
- *   item => item.value,
- *   'id',
- * ); // => Map { 10 => [1, 3], 20 => [2] }
- * ```
- */
-export function toMapArrays<
-	Item extends PlainObject,
-	KeyCallback extends (item: Item, index: number, array: Item[]) => Key,
-	ItemValue extends keyof Item,
->(
-	array: Item[],
-	key: KeyCallback,
-	value: ItemValue,
-): Map<ReturnType<KeyCallback>, Item[ItemValue][]>;
-
-/**
- * Create a _Map_ from an array of items using a key and callback, grouping values into arrays
- *
- * _Available as `toMapArrays` and `toMap.arrays`_
- *
- * @param array Array to convert
- * @param key Key to use for grouping
- * @param value Callback to get an item's value
- * @returns _Map_ of keyed arrays of values
- *
- * @example
- * ```typescript
- * toMapArrays(
- *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
- *   'value',
- *   item => item.id,
- * ); // => Map { 10 => [1, 3], 20 => [2] }
- * ```
- */
-export function toMapArrays<
-	Item extends PlainObject,
-	ItemKey extends keyof Item,
-	ValueCallback extends (item: Item, index: number, array: Item[]) => unknown,
->(
-	array: Item[],
-	key: ItemKey,
-	value: ValueCallback,
-): Map<Item[ItemKey], ReturnType<ValueCallback>[]>;
-
-/**
- * Create a _Map_ from an array of items using a key and value, grouping values into arrays
- *
- * _Available as `toMapArrays` and `toMap.arrays`_
- *
- * @param array Array to convert
- * @param key Key to use for grouping
- * @param value Key to use for value
- * @returns _Map_ of keyed arrays of values
- *
- * @example
- * ```typescript
- * toMapArrays(
- *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
- *   'value',
- *   'id',
- * ); // => Map { 10 => [1, 3], 20 => [2] }
- * ```
- */
-export function toMapArrays<
-	Item extends PlainObject,
-	ItemKey extends keyof Item,
-	ItemValue extends keyof Item,
->(array: Item[], key: ItemKey, value: ItemValue): Map<Item[ItemKey], Item[ItemValue][]>;
-
-/**
- * Create a _Map_ from an array of items using a callback, grouping items into arrays
- *
- * _Available as `toMapArrays` and `toMap.arrays`_
- *
- * @param array Array to convert
- * @param callback Callback to get an item's grouping key
- * @returns _Map_ of keyed arrays of items
- *
- * @example
- * ```typescript
- * toMapArrays(
- *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
- *   item => item.value,
- * ); // => Map { 10 => [{id: 1, value: 10}, {id: 3, value: 10}], 20 => [{id: 2, value: 20}] }
- * ```
- */
-export function toMapArrays<
-	Item,
-	Callback extends (item: Item, index: number, array: Item[]) => Key,
->(array: Item[], callback: Callback): Map<ReturnType<Callback>, Item[]>;
-
-/**
- * Create a _Map_ from an array of items using a key, grouping items into arrays
- *
- * _Available as `toMapArrays` and `toMap.arrays`_
- *
- * @param array Array to convert
- * @param key Key to use for grouping
- * @returns _Map_ of keyed arrays of items
- *
- * @example
- * ```typescript
- * toMapArrays(
- *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
- *   'value',
- * ); // => Map { 10 => [{id: 1, value: 10}, {id: 3, value: 10}], 20 => [{id: 2, value: 20}] }
- * ```
- */
-export function toMapArrays<Item extends PlainObject, ItemKey extends keyof Item>(
-	array: Item[],
-	key: ItemKey,
-): Map<Item[ItemKey], Item[]>;
-
-export function toMapArrays(array: unknown[], first?: unknown, second?: unknown): unknown {
-	return getMapValues(array, first, second, true);
-}
-
-// #endregion