@oscarpalmer/atoms 0.184.2 → 0.186.0

package/src/array/sort.ts

@@ -104,9 +104,15 @@ type InternalSorterCompare = {
  */
 export type SortDirection = 'ascending' | 'descending';
 
+/**
+ * Sorter for an array with predefined sorters
+ *
+ * Can be used to sort an array, get the predicted index for an item, and check if an array is sorted
+ */
 export type Sorter<Item> = {
 	/**
 	 * Sort an array of items
+	 *
 	 * @param array Array to sort
 	 * @returns Sorted array
 	 */
@@ -116,6 +122,7 @@ export type Sorter<Item> = {
 	 * Get the index for an item _(to be inserted into an array of items)_
 	 *
 	 * _(If the array is not sorted, it will be treated as sorted, and the result may be inaccurate)_
+	 *
 	 * @param array Array to get the index from
 	 * @param item Item to get the index for
 	 * @returns Index for item
@@ -124,6 +131,7 @@ export type Sorter<Item> = {
 
 	/**
 	 * Is the array sorted?
+	 *
 	 * @param array Array to check
 	 * @returns `true` if sorted, otherwise `false`
 	 */
@@ -245,7 +253,8 @@ function getObjectSorter(obj: PlainObject, modifier: number): InternalSorter | u
  *
  * _(If the array is not sorted, it will be treated as sorted, and the result may be inaccurate)_
  *
- * Available as `getSortedIndex` and `sort.index`
+ * Available as `getSortedIndex` and `sort.getIndex`
+ *
  * @param array Array to get the index from
  * @param item Item to get the index for
  * @param sorters Sorters to use to determine sorting
@@ -264,7 +273,8 @@ export function getSortedIndex<Item>(
  *
  * _(If the array is not sorted, it will be treated as sorted, and the result may be inaccurate)_
  *
- * Available as `getSortedIndex` and `sort.index`
+ * Available as `getSortedIndex` and `sort.getIndex`
+ *
  * @param array Array to get the index from
  * @param item Item to get the index for
  * @param sorter Sorter to use to determine sorting
@@ -283,7 +293,8 @@ export function getSortedIndex<Item>(
  *
  * _(If the array is not sorted, it will be treated as sorted, and the result may be inaccurate)_
  *
- * Available as `getSortedIndex` and `sort.index`
+ * Available as `getSortedIndex` and `sort.getIndex`
+ *
  * @param array Array to get the index from
  * @param item Item to get the index for
  * @param descending Sorted in descending order? _(defaults to `false`)_
@@ -361,6 +372,7 @@ function getValueSorter(value: string | Function, modifier: number): InternalSor
  * Initialize a sort handler with sorters _(and an optional default direction)_
  *
  * Available as `initializeSorter` and `sort.initialize`
+ *
  * @param sorters Sorters to use for sorting
  * @param descending Sort in descending order? _(defaults to `false`; overridden by individual sorters)_
  * @returns Sort handler
@@ -374,6 +386,7 @@ export function initializeSorter<Item>(
  * Initialize a sort handler with a sorter _(and an optional default direction)_
  *
  * Available as `initializeSorter` and `sort.initialize`
+ *
  * @param sorter Sorter to use for sorting
  * @param descending Sort in descending order? _(defaults to `false`; overridden by individual sorters)_
  * @returns Sort handler
@@ -387,6 +400,7 @@ export function initializeSorter<Item>(
  * Initialize a sort handler _(with an optional default direction)_
  *
  * Available as `initializeSorter` and `sort.initialize`
+ *
  * @param descending Sort in descending order? _(defaults to `false`)_
  * @returns Sort handler
  */
@@ -405,6 +419,7 @@ export function initializeSorter(first?: unknown, second?: unknown): Sorter<unkn
 
 /**
  * Is the array sorted according to the sorters _(and the optional default direction)_?
+ *
  * @param array Array to check
  * @param sorters Sorters to determine sorting
  * @param descending Sorted in descending order? _(defaults to `false`; overridden by individual sorters)_
@@ -418,6 +433,7 @@ export function isSorted<Item>(
 
 /**
  * Is the array sorted according to the sorter _(and the optional default direction)_?
+ *
  * @param array Array to check
  * @param sorter Sorter to determine sorting
  * @param descending Sorted in descending order? _(defaults to `false`; overridden by individual sorters)_
@@ -433,6 +449,7 @@ export function isSorted<Item>(
  * Is the array sorted?
  *
  * Available as `isSorted` and `sort.is`
+ *
  * @param array Array to check
  * @param descending Sorted in descending order? _(defaults to `false`)_
  * @returns `true` if sorted, otherwise `false`
@@ -495,10 +512,19 @@ function isSortedArray(array: unknown[], sorters: InternalSorter[]): boolean {
 
 /**
  * Sort an array of items using a comparison callback
+ *
  * @param array Array to sort
  * @param comparator Comparator to use for sorting
  * @param descending Sort in descending order? _(defaults to `false`; overridden by individual sorters)_
  * @returns Sorted array
+ *
+ * @example
+ * ```typescript
+ * sort(
+ *   [{id: 3}, {id: 1}, {id: 2}],
+ *   (first, second) => first.id - second.id,
+ * ); // => [{id: 1}, {id: 2}, {id: 3}]
+ * ```
  */
 export function sort<Item>(
 	array: Item[],
@@ -552,7 +578,7 @@ function sortArray(array: unknown[], sorters: InternalSorter[]): unknown[] {
 		: array;
 }
 
-sort.index = getSortedIndex;
+sort.getIndex = getSortedIndex;
 sort.initialize = initializeSorter;
 sort.is = isSorted;
 

package/src/array/splice.ts

@@ -2,41 +2,87 @@ import {INSERT_TYPE_SPLICE, insertValues} from '../internal/array/insert';
 
 // #region Functions
 
-// Uses chunking to avoid call stack size being exceeded
-
 /**
  * Adds items into an array at a specific index and removes a specific amount of items
+ *
+ * _(Uses chunking to avoid call stack size being exceeded)_
+ *
  * @param array Original array
  * @param start Index to start splicing from
  * @param amount Number of items to remove
  * @param added Added items
  * @returns Removed items
+ *
+ * @example
+ * ```typescript
+ * splice(
+ *   [1, 2, 3, 4, 5],
+ *   2,
+ *   2,
+ *   [6, 7]
+ * ); // => [3, 4], array becomes [1, 2, 6, 7, 5]
+ * ```
  */
 export function splice<Item>(array: Item[], start: number, amount: number, added: Item[]): Item[];
 
 /**
  * Adds items into an array at a specific index
+ *
+ * _(Uses chunking to avoid call stack size being exceeded)_
+ *
  * @param array Original array
  * @param start Index to start splicing from
  * @param added Added items
  * @returns Removed items
+ *
+ * @example
+ * ```typescript
+ * splice(
+ *   [1, 2, 3, 4, 5],
+ *   2,
+ *   [6, 7]
+ * ); // => [], array becomes [1, 2, 6, 7, 3, 4, 5]
+ * ```
  */
 export function splice<Item>(array: Item[], start: number, added: Item[]): Item[];
 
 /**
  * Removes and returns _(up to)_ a specific amount of items from an array, starting from a specific index
+ *
+ * _(Uses chunking to avoid call stack size being exceeded)_
+ *
  * @param array Original array
  * @param start Index to start splicing from
  * @param amount Number of items to remove
  * @returns Removed items
+ *
+ * @example
+ * ```typescript
+ * splice(
+ *   [1, 2, 3, 4, 5],
+ *   2,
+ *   2,
+ * ); // => [3, 4], array becomes [1, 2, 5]
+ * ```
  */
 export function splice<Item>(array: Item[], start: number, amount: number): Item[];
 
 /**
  * Removes and returns all items from an array starting from a specific index
+ *
+ * _(Uses chunking to avoid call stack size being exceeded)_
+ *
  * @param array Original array
  * @param start Index to start splicing from
  * @returns Removed items
+ *
+ * @example
+ * ```typescript
+ * splice(
+ *   [1, 2, 3, 4, 5],
+ *   2,
+ * ); // => [3, 4, 5], array becomes [1, 2]
+ * ```
  */
 export function splice<Item>(array: Item[], start: number): Item[];
 
@@ -46,12 +92,14 @@ export function splice(
 	deleteCountOrItems?: unknown,
 	items?: unknown,
 ): unknown[] {
+	const deleteCountIsNumber = typeof deleteCountOrItems === 'number';
+
 	return insertValues(
 		INSERT_TYPE_SPLICE,
 		array,
-		typeof deleteCountOrItems === 'number' ? items : deleteCountOrItems,
+		deleteCountIsNumber ? items : deleteCountOrItems,
 		start,
-		typeof deleteCountOrItems === 'number' ? deleteCountOrItems : 0,
+		deleteCountIsNumber ? deleteCountOrItems : 0,
 	) as unknown[];
 }
 

package/src/array/swap.ts

@@ -2,50 +2,108 @@ 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 './position';
+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 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 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 extends PlainObject, ItemKey extends keyof Item>(
+export function swap<Item>(
 	array: Item[],
 	first: Item[],
 	second: Item[],
-	key: ItemKey,
+	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 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 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>(
+export function swap<Item extends PlainObject, ItemKey extends keyof Item>(
 	array: Item[],
 	first: Item[],
 	second: Item[],
-	callback: (item: Item, index: number, array: Item[]) => unknown,
+	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[];
 
@@ -53,42 +111,90 @@ 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 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 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 extends PlainObject, ItemKey extends keyof Item>(
+export function swap<Item>(
 	array: Item[],
 	first: Item,
 	second: Item,
-	key: ItemKey,
+	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 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 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>(
+export function swap<Item extends PlainObject, ItemKey extends keyof Item>(
 	array: Item[],
 	first: Item,
 	second: Item,
-	callback: (item: Item, index: number, array: Item[]) => unknown,
+	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[];
 
@@ -165,6 +271,7 @@ function swapArrays(array: unknown[], from: unknown[], to: unknown[], key: unkno
  * 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)_
@@ -211,3 +318,5 @@ function swapValues(array: unknown[], from: unknown, to: unknown, key?: unknown)
 
 	return swapIndices(array, first, second);
 }
+
+// #endregion