@oscarpalmer/atoms 0.185.0 → 0.186.0

package/src/array/last.ts

@@ -5,10 +5,20 @@ import type {PlainObject} from '../models';
 
 /**
  * Get the last items matching the given value
+ *
  * @param array Array to search in
  * @param callback Callback to get an item's value for matching
  * @param value Value to match against
  * @returns Last item that matches the value, or `undefined` if no match is found
+ *
+ * @example
+ * ```typescript
+ * last(
+ *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
+ *   item => item.value,
+ *   10,
+ * ); // => {id: 3, value: 10}
+ * ```
  */
 export function last<Item, Callback extends (item: Item, index: number, array: Item[]) => unknown>(
 	array: Item[],
@@ -18,10 +28,20 @@ export function last<Item, Callback extends (item: Item, index: number, array: I
 
 /**
  * Get the first item matching the given value by key
+ *
  * @param array Array to search in
  * @param key Key to get an item's value for matching
  * @param value Value to match against
  * @returns Last item that matches the value, or `undefined` if no match is found
+ *
+ * @example
+ * ```typescript
+ * last(
+ *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
+ *   'value',
+ *   10,
+ * ); // => {id: 3, value: 10}
+ * ```
  */
 export function last<Item extends PlainObject, ItemKey extends keyof Item>(
 	array: Item[],
@@ -31,9 +51,18 @@ export function last<Item extends PlainObject, ItemKey extends keyof Item>(
 
 /**
  * Get the last item matching the filter
+ *
  * @param array Array to search in
  * @param filter Filter callback to match items
  * @returns Last item that matches the filter, or `undefined` if no match is found
+ *
+ * @example
+ * ```typescript
+ * last(
+ *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
+ *   item => item.value === 10,
+ * ); // => {id: 3, value: 10}
+ * ```
  */
 export function last<Item>(
 	array: Item[],
@@ -42,8 +71,14 @@ export function last<Item>(
 
 /**
  * Get the last item from an array
+ *
  * @param array Array to get from
- * @return Last item from the array, or `undefined` if the array is empty
+ * @returns Last item from the array, or `undefined` if the array is empty
+ *
+ * @example
+ * ```typescript
+ * last([1, 2, 3]); // => 3
+ * ```
  */
 export function last<Item>(array: Item[]): Item | undefined;
 
@@ -57,11 +92,22 @@ last.default = lastOrDefault;
  * Get the last item matching the given value
  *
  * Available as `lastOrDefault` and `last.default`
+ *
  * @param array Array to search in
  * @param defaultValue Default value to return if no match is found
  * @param callback Callback to get an item's value for matching
  * @param value Value to match against
  * @returns Last item that matches the value, or the default value if no match is found
+ *
+ * @example
+ * ```typescript
+ * lastOrDefault(
+ *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
+ *   {id: -1, value: 30},
+ *   item => item.value,
+ *   30,
+ * ); // => {id: -1, value: 30}
+ * ```
  */
 export function lastOrDefault<
 	Item,
@@ -72,11 +118,22 @@ export function lastOrDefault<
  * Get the last item matching the given value by key
  *
  * Available as `lastOrDefault` and `last.default`
+ *
  * @param array Array to search in
  * @param defaultValue Default value to return if no match is found
  * @param key Key to get an item's value for matching
  * @param value Value to match against
  * @returns Last item that matches the value, or the default value if no match is found
+ *
+ * @example
+ * ```typescript
+ * lastOrDefault(
+ *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
+ *   {id: -1, value: 30},
+ *   'value',
+ *   30,
+ * ); // => {id: -1, value: 30}
+ * ```
  */
 export function lastOrDefault<Item extends PlainObject, ItemKey extends keyof Item>(
 	array: Item[],
@@ -89,10 +146,20 @@ export function lastOrDefault<Item extends PlainObject, ItemKey extends keyof It
  * Get the last item matching the filter
  *
  * Available as `lastOrDefault` and `last.default`
+ *
  * @param array Array to search in
  * @param defaultValue Default value to return if no match is found
  * @param filter Filter callback to match items
  * @returns Last item that matches the filter, or the default value if no match is found
+ *
+ * @example
+ * ```typescript
+ * lastOrDefault(
+ *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
+ *   {id: -1, value: 30},
+ *   item => item.value === 30,
+ * ); // => {id: -1, value: 30}
+ * ```
  */
 export function lastOrDefault<Item>(
 	array: Item[],
@@ -104,9 +171,15 @@ export function lastOrDefault<Item>(
  * Get the last item from an array
  *
  * Available as `lastOrDefault` and `last.default`
+ *
  * @param array Array to get from
  * @param defaultValue Default value to return if the array is empty
- * @return Last item from the array, or the default value if the array is empty
+ * @returns Last item from the array, or the default value if the array is empty
+ *
+ * @example
+ * ```typescript
+ * lastOrDefault([], {id: -1, value: 30}); // => {id: -1, value: 30}
+ * ```
  */
 export function lastOrDefault<Item>(array: Item[], defaultValue: Item): Item;
 

package/src/array/match.ts

@@ -16,33 +16,58 @@ export type ArrayComparison = 'end' | 'inside' | 'invalid' | 'outside' | 'same'
  * Does the needle array end the haystack array?
  * @param haystack Haystack array
  * @param needle Needle array
- * @param key Key to get an item's value for matching
- * @return `true` if the haystack ends with the needle, otherwise `false`
+ * @param callback Callback to get an item's value for matching
+ * @returns `true` if the haystack ends with the needle, otherwise `false`
+ *
+ * @example
+ * ```typescript
+ * endsWithArray(
+ *   [{id: 1}, {id: 2}, {id: 3}],
+ *   [{id: 2}, {id: 3}],
+ *   item => item.id,
+ * ); // => true
+ * ```
  */
-export function endsWithArray<Item extends PlainObject>(
+export function endsWithArray<Item>(
 	haystack: Item[],
 	needle: Item[],
-	key: keyof Item,
+	callback: (item: Item, index: number, array: Item[]) => unknown,
 ): boolean;
 
 /**
  * Does the needle array end the haystack array?
+ *
  * @param haystack Haystack array
  * @param needle Needle array
- * @param callback Callback to get an item's value for matching
- * @return `true` if the haystack ends with the needle, otherwise `false`
+ * @param key Key to get an item's value for matching
+ * @returns `true` if the haystack ends with the needle, otherwise `false`
+ *
+ * @example
+ * ```typescript
+ * endsWithArray(
+ *   [{id: 1}, {id: 2}, {id: 3}],
+ *   [{id: 2}, {id: 3}],
+ *   'id',
+ * ); // => true
+ * ```
  */
-export function endsWithArray<Item>(
+export function endsWithArray<Item extends PlainObject>(
 	haystack: Item[],
 	needle: Item[],
-	callback: (item: Item, index: number, array: Item[]) => unknown,
+	key: keyof Item,
 ): boolean;
 
 /**
  * Does the needle array end the haystack array?
+ *
  * @param haystack Haystack array
  * @param needle Needle array
- * @return `true` if the haystack ends with the needle, otherwise `false`
+ * @returns `true` if the haystack ends with the needle, otherwise `false`
+ *
+ * @example
+ * ```typescript
+ * endsWithArray([1, 2, 3], [2, 3]); // => true
+ * ```
  */
 export function endsWithArray<Item>(haystack: Item[], needle: Item[]): boolean;
 
@@ -52,35 +77,61 @@ export function endsWithArray(haystack: unknown[], needle: unknown[], key?: unkn
 
 /**
  * Get the position of an array within another array
+ *
  * @param haystack Haystack array
  * @param needle Needle array
- * @param key Key to get an item's value for matching
+ * @param callback Callback to get an item's value for matching
  * @returns Position of the needle within the haystack
+ *
+ * @example
+ * ```typescript
+ * getArrayComparison(
+ *   [{id: 1}, {id: 2}, {id: 3}],
+ *   [{id: 2}, {id: 3}],
+ *   item => item.id,
+ * ); // => 'end'
+ * ```
  */
-export function getArrayComparison<Item extends PlainObject>(
+export function getArrayComparison<Item>(
 	haystack: Item[],
 	needle: Item[],
-	key: keyof Item,
+	callback: (item: Item, index: number, array: Item[]) => unknown,
 ): ArrayComparison;
 
 /**
  * Get the position of an array within another array
+ *
  * @param haystack Haystack array
  * @param needle Needle array
- * @param callback Callback to get an item's value for matching
+ * @param key Key to get an item's value for matching
  * @returns Position of the needle within the haystack
+ *
+ * @example
+ * ```typescript
+ * getArrayComparison(
+ *   [{id: 1}, {id: 2}, {id: 3}],
+ *   [{id: 2}, {id: 3}],
+ *   'id',
+ * ); // => 'end'
+ * ```
  */
-export function getArrayComparison<Item>(
+export function getArrayComparison<Item extends PlainObject>(
 	haystack: Item[],
 	needle: Item[],
-	callback: (item: Item, index: number, array: Item[]) => unknown,
+	key: keyof Item,
 ): ArrayComparison;
 
 /**
  * Get the position of an array within another array
+ *
  * @param haystack Haystack array
  * @param needle Needle array
  * @returns Position of the needle within the haystack
+ *
+ * @example
+ * ```typescript
+ * getArrayComparison([1, 2, 3], [2, 3]); // => 'end'
+ * ```
  */
 export function getArrayComparison<Item>(haystack: Item[], needle: Item[]): ArrayComparison;
 
@@ -165,35 +216,61 @@ function getPosition(
 
 /**
  * Does the needle array exist within the haystack array?
+ *
  * @param haystack Haystack array
  * @param needle Needle array
- * @param key Key to get an item's value for matching
- * @return `true` if the haystack includes the needle, otherwise `false`
+ * @param callback Callback to get an item's value for matching
+ * @returns `true` if the haystack includes the needle, otherwise `false`
+ *
+ * @example
+ * ```typescript
+ * includesArray(
+ *   [{id: 1}, {id: 2}, {id: 3}],
+ *   [{id: 2}, {id: 3}],
+ *   item => item.id,
+ * ); // => true
+ * ```
  */
-export function includesArray<Item extends PlainObject>(
+export function includesArray<Item>(
 	haystack: Item[],
 	needle: Item[],
-	key: keyof Item,
+	callback: (item: Item, index: number, array: Item[]) => unknown,
 ): boolean;
 
 /**
  * Does the needle array exist within the haystack array?
+ *
  * @param haystack Haystack array
  * @param needle Needle array
- * @param callback Callback to get an item's value for matching
- * @return `true` if the haystack includes the needle, otherwise `false`
+ * @param key Key to get an item's value for matching
+ * @returns `true` if the haystack includes the needle, otherwise `false`
+ *
+ * @example
+ * ```typescript
+ * includesArray(
+ *   [{id: 1}, {id: 2}, {id: 3}],
+ *   [{id: 2}, {id: 3}],
+ *   'id',
+ * ); // => true
+ * ```
  */
-export function includesArray<Item>(
+export function includesArray<Item extends PlainObject>(
 	haystack: Item[],
 	needle: Item[],
-	callback: (item: Item, index: number, array: Item[]) => unknown,
+	key: keyof Item,
 ): boolean;
 
 /**
  * Does the needle array exist within the haystack array?
+ *
  * @param haystack Haystack array
  * @param needle Needle array
- * @return `true` if the haystack includes the needle, otherwise `false`
+ * @returns `true` if the haystack includes the needle, otherwise `false`
+ *
+ * @example
+ * ```typescript
+ * includesArray([1, 2, 3], [2, 3]); // => true
+ * ```
  */
 export function includesArray<Item>(haystack: Item[], needle: Item[]): boolean;
 
@@ -203,35 +280,61 @@ export function includesArray(haystack: unknown[], needle: unknown[], key?: unkn
 
 /**
  * Get the index of an array within another array
+ *
  * @param haystack Haystack array
  * @param needle Needle array
- * @param key Key to get an item's value for matching
- * @return Index of the needle's start within the haystack, or `-1` if it is not found
+ * @param callback Callback to get an item's value for matching
+ * @returns Index of the needle's start within the haystack, or `-1` if it is not found
+ *
+ * @example
+ * ```typescript
+ * indexOfArray(
+ *   [{id: 1}, {id: 2}, {id: 3}],
+ *   [{id: 2}, {id: 3}],
+ *   item => item.id,
+ * ); // => 1
+ * ```
  */
-export function indexOfArray<Item extends PlainObject>(
+export function indexOfArray<Item>(
 	haystack: Item[],
 	needle: Item[],
-	key: keyof Item,
+	callback: (item: Item, index: number, array: Item[]) => unknown,
 ): number;
 
 /**
  * Get the index of an array within another array
+ *
  * @param haystack Haystack array
  * @param needle Needle array
- * @param callback Callback to get an item's value for matching
- * @return Index of the needle's start within the haystack, or `-1` if it is not found
+ * @param key Key to get an item's value for matching
+ * @returns Index of the needle's start within the haystack, or `-1` if it is not found
+ *
+ * @example
+ * ```typescript
+ * indexOfArray(
+ *   [{id: 1}, {id: 2}, {id: 3}],
+ *   [{id: 2}, {id: 3}],
+ *   'id',
+ * ); // => 1
+ * ```
  */
-export function indexOfArray<Item>(
+export function indexOfArray<Item extends PlainObject>(
 	haystack: Item[],
 	needle: Item[],
-	callback: (item: Item, index: number, array: Item[]) => unknown,
+	key: keyof Item,
 ): number;
 
 /**
  * Get the index of an array within another array
+ *
  * @param haystack Haystack array
  * @param needle Needle array
- * @return Index of the needle's start within the haystack, or `-1` if it is not found
+ * @returns Index of the needle's start within the haystack, or `-1` if it is not found
+ *
+ * @example
+ * ```typescript
+ * indexOfArray([1, 2, 3], [2, 3]); // => 1
+ * ```
  */
 export function indexOfArray<Item>(haystack: Item[], needle: Item[]): number;
 
@@ -241,35 +344,61 @@ export function indexOfArray(haystack: unknown[], needle: unknown[], key?: unkno
 
 /**
  * Does the needle array start the haystack array?
+ *
  * @param haystack Haystack array
  * @param needle Needle array
- * @param key Key to get an item's value for matching
- * @return `true` if the haystack starts with the needle, otherwise `false`
+ * @param callback Callback to get an item's value for matching
+ * @returns `true` if the haystack starts with the needle, otherwise `false`
+ *
+ * @example
+ * ```typescript
+ * startsWithArray(
+ *   [{id: 1}, {id: 2}, {id: 3}],
+ *   [{id: 1}, {id: 2}],
+ *   item => item.id,
+ * ); // => true
+ * ```
  */
-export function startsWithArray<Item extends PlainObject>(
+export function startsWithArray<Item>(
 	haystack: Item[],
 	needle: Item[],
-	key: keyof Item,
+	callback: (item: Item, index: number, array: Item[]) => unknown,
 ): boolean;
 
 /**
  * Does the needle array start the haystack array?
+ *
  * @param haystack Haystack array
  * @param needle Needle array
- * @param callback Callback to get an item's value for matching
- * @return `true` if the haystack starts with the needle, otherwise `false`
+ * @param key Key to get an item's value for matching
+ * @returns `true` if the haystack starts with the needle, otherwise `false`
+ *
+ * @example
+ * ```typescript
+ * startsWithArray(
+ *   [{id: 1}, {id: 2}, {id: 3}],
+ *   [{id: 1}, {id: 2}],
+ *   'id',
+ * ); // => true
+ * ```
  */
-export function startsWithArray<Item>(
+export function startsWithArray<Item extends PlainObject>(
 	haystack: Item[],
 	needle: Item[],
-	callback: (item: Item, index: number, array: Item[]) => unknown,
+	key: keyof Item,
 ): boolean;
 
 /**
  * Does the needle array start the haystack array?
+ *
  * @param haystack Haystack array
  * @param needle Needle array
- * @return `true` if the haystack starts with the needle, otherwise `false`
+ * @returns `true` if the haystack starts with the needle, otherwise `false`
+ *
+ * @example
+ * ```typescript
+ * startsWithArray([1, 2, 3], [1, 2]); // => true
+ * ```
  */
 export function startsWithArray<Item>(haystack: Item[], needle: Item[]): boolean;
 

package/src/array/move.ts

@@ -10,17 +10,27 @@ import {indexOfArray} from './match';
  * When moving to the front of the array, the moved items will be placed __before__ the target item. When moving to the back of the array, the moved items will be placed __after__ the target item.
  *
  * If either of values are not present in the array, or if they overlap, the array will be returned unchanged
+ *
  * @param array Array to move within
  * @param from Item or items to move
  * @param to Item or items to move to
- * @param key Key to get an item's value for matching
+ * @param callback Callback to get an item's value for matching
  * @returns Original array with items moved _(or unchanged if unable to move)_
+ *
+ * @example
+ * ```typescript
+ * const array = [{id: 1}, {id: 2}, {id: 3}, {id: 4}];
+ *
+ * move(array, {id: 1}, {id: 3}, item => item.id);            // => [{id: 2}, {id: 3}, {id: 1}, {id: 4}]
+ * move(array, [{id: 2}, {id: 3}], {id: 4}, item => item.id); // => [{id: 1}, {id: 4}, {id: 2}, {id: 3}]
+ * move(array, {id: 5}, {id: 1}, item => item.id);            // => [{id: 1}, {id: 2}, {id: 3}, {id: 4}] (unchanged)
+ * ```
  */
-export function move<Item extends PlainObject, ItemKey extends keyof Item>(
+export function move<Item>(
 	array: Item[],
 	from: Item | Item[],
 	to: Item | Item[],
-	key: ItemKey,
+	callback: (item: Item, index: number, array: Item[]) => unknown,
 ): Item[];
 
 /**
@@ -29,17 +39,27 @@ export function move<Item extends PlainObject, ItemKey extends keyof Item>(
  * When moving to the front of the array, the moved items will be placed __before__ the target item. When moving to the back of the array, the moved items will be placed __after__ the target item.
  *
  * If either of values are not present in the array, or if they overlap, the array will be returned unchanged
+ *
  * @param array Array to move within
  * @param from Item or items to move
  * @param to Item or items to move to
- * @param callback Callback to get an item's value for matching
+ * @param key Key to get an item's value for matching
  * @returns Original array with items moved _(or unchanged if unable to move)_
+ *
+ * @example
+ * ```typescript
+ * const array = [{id: 1}, {id: 2}, {id: 3}, {id: 4}];
+ *
+ * move(array, {id: 1}, {id: 3}, 'id');            // => [{id: 2}, {id: 3}, {id: 1}, {id: 4}]
+ * move(array, [{id: 2}, {id: 3}], {id: 4}, 'id'); // => [{id: 1}, {id: 4}, {id: 2}, {id: 3}]
+ * move(array, {id: 5}, {id: 1}, 'id');            // => [{id: 1}, {id: 2}, {id: 3}, {id: 4}] (unchanged)
+ * ```
  */
-export function move<Item>(
+export function move<Item extends PlainObject, ItemKey extends keyof Item>(
 	array: Item[],
 	from: Item | Item[],
 	to: Item | Item[],
-	callback: (item: Item, index: number, array: Item[]) => unknown,
+	key: ItemKey,
 ): Item[];
 
 /**
@@ -48,10 +68,20 @@ export function move<Item>(
  * When moving to the front of the array, the moved items will be placed __before__ the target item. When moving to the back of the array, the moved items will be placed __after__ the target item.
  *
  * If either of values are not present in the array, or if they overlap, the array will be returned unchanged
+ *
  * @param array Array to move within
  * @param from Item or items to move
  * @param to Item or items to move to
  * @returns Original array with items moved _(or unchanged if unable to move)_
+ *
+ * @example
+ * ```typescript
+ * const array = [1, 2, 3, 4];
+ *
+ * move(array, 1, 3);      // => [2, 3, 1, 4]
+ * move(array, [2, 3], 4); // => [1, 4, 2, 3]
+ * move(array, 5, 1);      // => [1, 2, 3, 4] (unchanged)
+ * ```
  */
 export function move<Item>(array: Item[], from: Item | Item[], to: Item | Item[]): Item[];
 
@@ -116,10 +146,20 @@ move.toIndex = moveToIndex;
  * If the from index is out of bounds, the array will be returned unchanged
  *
  * Available as `moveIndices` and `move.indices`
+ *
  * @param array Array to move within
  * @param from Index to move from
  * @param to Index to move to
  * @returns Original array with item moved _(or unchanged if unable to move)_
+ *
+ * @example
+ * ```typescript
+ * const array = [1, 2, 3, 4];
+ *
+ * moveIndices(array, 0, 2);  // => [2, 3, 1, 4]
+ * moveIndices(array, -1, 0); // => [4, 2, 3, 1]
+ * moveIndices(array, 5, 1);  // => [4, 2, 3, 1] (unchanged)
+ * ```
  */
 export function moveIndices<Item>(array: Item[], from: number, to: number): Item[] {
 	if (!Array.isArray(array)) {
@@ -156,17 +196,27 @@ export function moveIndices<Item>(array: Item[], from: number, to: number): Item
  * If the value is not present in the array, or if the index is out of bounds, the array will be returned unchanged
  *
  * Available as `moveToIndex` and `move.toIndex`
+ *
+ * @example
+ * ```typescript
+ * const array = [{id: 1}, {id: 2}, {id: 3}, {id: 4}];
+ *
+ * moveToIndex(array, {id: 1}, 2, item => item.id);            // => [{id: 2}, {id: 3}, {id: 1}, {id: 4}]
+ * moveToIndex(array, [{id: 2}, {id: 3}], 3, item => item.id); // => [{id: 1}, {id: 4}, {id: 2}, {id: 3}]
+ * moveToIndex(array, {id: 5}, 1, item => item.id);            // => [{id: 1}, {id: 2}, {id: 3}, {id: 4}] (unchanged)
+ * ```
+ *
  * @param array Array to move within
  * @param value Item or items to move
  * @param index Index to move to
- * @param key Key to get an item's value for matching
+ * @param callback Callback to get an item's value for matching
  * @returns Original array with items moved _(or unchanged if unable to move)_
  */
-export function moveToIndex<Item extends PlainObject, ItemKey extends keyof Item>(
+export function moveToIndex<Item>(
 	array: Item[],
 	value: Item | Item[],
 	index: number,
-	key: ItemKey,
+	callback: (item: Item, index: number, array: Item[]) => unknown,
 ): Item[];
 
 /**
@@ -175,17 +225,27 @@ export function moveToIndex<Item extends PlainObject, ItemKey extends keyof Item
  * If the value is not present in the array, or if the index is out of bounds, the array will be returned unchanged
  *
  * Available as `moveToIndex` and `move.toIndex`
+ *
  * @param array Array to move within
  * @param value Item or items to move
  * @param index Index to move to
- * @param callback Callback to get an item's value for matching
+ * @param key Key to get an item's value for matching
  * @returns Original array with items moved _(or unchanged if unable to move)_
+ *
+ * @example
+ * ```typescript
+ * const array = [{id: 1}, {id: 2}, {id: 3}, {id: 4}];
+ *
+ * moveToIndex(array, {id: 1}, 2, 'id');            // => [{id: 2}, {id: 3}, {id: 1}, {id: 4}]
+ * moveToIndex(array, [{id: 2}, {id: 3}], 3, 'id'); // => [{id: 1}, {id: 4}, {id: 2}, {id: 3}]
+ * moveToIndex(array, {id: 5}, 1, 'id');            // => [{id: 1}, {id: 2}, {id: 3}, {id: 4}] (unchanged)
+ * ```
  */
-export function moveToIndex<Item>(
+export function moveToIndex<Item extends PlainObject, ItemKey extends keyof Item>(
 	array: Item[],
 	value: Item | Item[],
 	index: number,
-	callback: (item: Item, index: number, array: Item[]) => unknown,
+	key: ItemKey,
 ): Item[];
 
 /**
@@ -194,10 +254,20 @@ export function moveToIndex<Item>(
  * If the value is not present in the array, or if the index is out of bounds, the array will be returned unchanged
  *
  * Available as `moveToIndex` and `move.toIndex`
+ *
  * @param array Array to move within
  * @param value Item or items to move
  * @param index Index to move to
  * @returns Original array with items moved _(or unchanged if unable to move)_
+ *
+ * @example
+ * ```typescript
+ * const array = [1, 2, 3, 4];
+ *
+ * moveToIndex(array, 1, 2);      // => [2, 3, 1, 4]
+ * moveToIndex(array, [2, 3], 3); // => [1, 4, 2, 3]
+ * moveToIndex(array, 5, 1);      // => [1, 2, 3, 4] (unchanged)
+ * ```
  */
 export function moveToIndex<Item>(array: Item[], value: Item | Item[], index: number): Item[];