@oscarpalmer/atoms 0.185.0 → 0.186.0

package/src/array/sort.ts

@@ -112,6 +112,7 @@ export type SortDirection = 'ascending' | 'descending';
 export type Sorter<Item> = {
 	/**
 	 * Sort an array of items
+	 *
 	 * @param array Array to sort
 	 * @returns Sorted array
 	 */
@@ -121,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
@@ -129,6 +131,7 @@ export type Sorter<Item> = {
 
 	/**
 	 * Is the array sorted?
+	 *
 	 * @param array Array to check
 	 * @returns `true` if sorted, otherwise `false`
 	 */
@@ -251,6 +254,7 @@ 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.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
@@ -270,6 +274,7 @@ 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.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
@@ -289,6 +294,7 @@ 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.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`)_
@@ -366,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
@@ -379,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
@@ -392,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
  */
@@ -410,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)_
@@ -423,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)_
@@ -438,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`
@@ -500,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[],

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

@@ -10,44 +10,100 @@ import {indexOfArray} from './match';
  * 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[];
 
@@ -55,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[];
 
@@ -167,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)_

package/src/array/to-map.ts

@@ -43,10 +43,20 @@ function getMapValues(
  * 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,
@@ -62,10 +72,20 @@ export function toMap<
  * 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,
@@ -77,10 +97,20 @@ export function toMap<
  * 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,
@@ -92,10 +122,20 @@ export function toMap<
  * 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,
@@ -107,9 +147,18 @@ export function toMap<
  * 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[],
@@ -120,9 +169,18 @@ export function toMap<Item, Callback extends (item: Item, index: number, array:
  * 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[],
@@ -131,8 +189,16 @@ export function toMap<Item extends PlainObject, ItemKey extends keyof 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>;
 
@@ -146,10 +212,20 @@ 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,
@@ -165,10 +241,20 @@ export function toMapArrays<
  * 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,
@@ -184,10 +270,20 @@ export function toMapArrays<
  * 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,
@@ -203,10 +299,20 @@ export function toMapArrays<
  * 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,
@@ -218,9 +324,18 @@ export function toMapArrays<
  * 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,
@@ -231,9 +346,18 @@ export function toMapArrays<
  * 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[],