@oscarpalmer/atoms 0.184.2 → 0.186.0

package/src/array/{position.ts → match.ts}

@@ -1,9 +1,12 @@
-// #region Types
-
 import {getArrayCallback} from '../internal/array/callbacks';
 import type {PlainObject} from '../models';
 
-export type ArrayPosition = 'end' | 'inside' | 'invalid' | 'outside' | 'same' | 'start';
+// #region Types
+
+/**
+ * Comparison of an array within another array
+ */
+export type ArrayComparison = 'end' | 'inside' | 'invalid' | 'outside' | 'same' | 'start';
 
 // #endregion
 
@@ -13,33 +16,58 @@ export type ArrayPosition = '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;
 
@@ -49,59 +77,85 @@ 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 getArrayPosition<Item extends PlainObject>(
+export function getArrayComparison<Item>(
 	haystack: Item[],
 	needle: Item[],
-	key: keyof Item,
-): ArrayPosition;
+	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 getArrayPosition<Item>(
+export function getArrayComparison<Item extends PlainObject>(
 	haystack: Item[],
 	needle: Item[],
-	callback: (item: Item, index: number, array: Item[]) => unknown,
-): ArrayPosition;
+	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 getArrayPosition<Item>(haystack: Item[], needle: Item[]): ArrayPosition;
+export function getArrayComparison<Item>(haystack: Item[], needle: Item[]): ArrayComparison;
 
-export function getArrayPosition(
+export function getArrayComparison(
 	haystack: unknown[],
 	needle: unknown[],
 	key?: unknown,
-): ArrayPosition {
+): ArrayComparison {
 	return getPosition(haystack, needle, key)[1];
 }
 
-function getName(start: number, haystack: number, needle: number): ArrayPosition {
+function getName(start: number, haystack: number, needle: number): ArrayComparison {
 	if (start === 0) {
-		return haystack === needle ? POSITION_SAME : POSITION_START;
+		return haystack === needle ? COMPARISON_SAME : COMPARISON_START;
 	}
 
-	return start + needle === haystack ? POSITION_END : POSITION_INSIDE;
+	return start + needle === haystack ? COMPARISON_END : COMPARISON_INSIDE;
 }
 
 function getPosition(
 	haystack: unknown[],
 	needle: unknown[],
 	key?: unknown,
-): readonly [number, ArrayPosition] {
+): readonly [number, ArrayComparison] {
 	if (!Array.isArray(haystack) || !Array.isArray(needle)) {
 		return invalid;
 	}
@@ -162,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;
 
@@ -200,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;
 
@@ -238,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;
 
@@ -278,26 +410,26 @@ export function startsWithArray(haystack: unknown[], needle: unknown[], key?: un
 
 // #region Variables
 
-const POSITION_END: ArrayPosition = 'end';
+const COMPARISON_END: ArrayComparison = 'end';
 
-const POSITION_INSIDE: ArrayPosition = 'inside';
+const COMPARISON_INSIDE: ArrayComparison = 'inside';
 
-const POSITION_INVALID: ArrayPosition = 'invalid';
+const COMPARISON_INVALID: ArrayComparison = 'invalid';
 
-const POSITION_OUTSIDE: ArrayPosition = 'outside';
+const COMPARISON_OUTSIDE: ArrayComparison = 'outside';
 
-const POSITION_SAME: ArrayPosition = 'same';
+const COMPARISON_SAME: ArrayComparison = 'same';
 
-const POSITION_START: ArrayPosition = 'start';
+const COMPARISON_START: ArrayComparison = 'start';
 
-const endings = new Set<ArrayPosition>([POSITION_END, POSITION_SAME]);
+const endings = new Set<ArrayComparison>([COMPARISON_END, COMPARISON_SAME]);
 
-const invalid = [-1, POSITION_INVALID] as const;
+const invalid = [-1, COMPARISON_INVALID] as const;
 
-const outside = [-1, POSITION_OUTSIDE] as const;
+const outside = [-1, COMPARISON_OUTSIDE] as const;
 
-const outsides = new Set<ArrayPosition>([POSITION_INVALID, POSITION_OUTSIDE]);
+const outsides = new Set<ArrayComparison>([COMPARISON_INVALID, COMPARISON_OUTSIDE]);
 
-const starts = new Set<ArrayPosition>([POSITION_START, POSITION_SAME]);
+const starts = new Set<ArrayComparison>([COMPARISON_START, COMPARISON_SAME]);
 
 // #endregion

package/src/array/move.ts

@@ -1,6 +1,8 @@
 import {arraysOverlap} from '../internal/array/overlap';
 import type {PlainObject} from '../models';
-import {indexOfArray} from './position';
+import {indexOfArray} from './match';
+
+// #region Functions
 
 /**
  * Move an item _(or array of items)_ to the position of another item _(or array of items)_ within an array
@@ -8,17 +10,27 @@ import {indexOfArray} from './position';
  * 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[];
 
 /**
@@ -27,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[];
 
 /**
@@ -46,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[];
 
@@ -114,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)) {
@@ -154,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[];
 
 /**
@@ -173,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[];
 
 /**
@@ -192,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[];
 
@@ -239,3 +311,5 @@ export function moveToIndex(
 
 	return array;
 }
+
+// #endregion