@oscarpalmer/atoms 0.184.2 → 0.186.0

package/dist/array/select.d.mts

@@ -3,46 +3,100 @@ import { PlainObject } from "../models.mjs";
 //#region src/array/select.d.ts
 /**
  * Get a filtered and mapped array of items
+ *
  * @param array Array to search in
  * @param filterCallback Callback to get an item's value for matching
  * @param filterValue Value to match against
  * @param mapCallback Callback to map the matched items
  * @returns Filtered and mapped array of items
+ *
+ * @example
+ * ```typescript
+ * select(
+ *   [{id: 1, name: 'Alice'}, {id: 2, name: 'Bob'}, {id: 3, name: 'Charlie'}],
+ *   item => item.id,
+ *   2,
+ *   item => item.name,
+ * ); // => ['Bob']
+ * ```
  */
 declare function select<Item, FilterCallback extends (item: Item, index: number, array: Item[]) => unknown, MapCallback extends (item: Item, index: number, array: Item[]) => unknown>(array: Item[], filterCallback: FilterCallback, filterValue: ReturnType<FilterCallback>, mapCallback: MapCallback): Array<ReturnType<MapCallback>>;
 /**
  * Get a filtered and mapped array of items
+ *
  * @param array Array to search in
  * @param filterCallback Callback to get an item's value for matching
  * @param filterValue Value to match against
  * @param mapKey Key to get an item's value for mapping
  * @returns Filtered and mapped array of items
+ *
+ * @example
+ * ```typescript
+ * select(
+ *   [{id: 1, name: 'Alice'}, {id: 2, name: 'Bob'}, {id: 3, name: 'Charlie'}],
+ *   item => item.id,
+ *   2,
+ *   'name',
+ * ); // => ['Bob']
+ * ```
  */
 declare function select<Item extends PlainObject, FilterCallback extends (item: Item, index: number, array: Item[]) => unknown, MapKey extends keyof Item>(array: Item[], filterCallback: FilterCallback, filterValue: ReturnType<FilterCallback>, mapKey: MapKey): Array<Item[MapKey]>;
 /**
  * Get a filtered and mapped array of items
+ *
  * @param array Array to search in
  * @param filterKey Key to get an item's value for matching
  * @param filterValue Value to match against
  * @param mapCallback Callback to map the matched items
  * @returns Filtered and mapped array of items
+ *
+ * @example
+ * ```typescript
+ * select(
+ *   [{id: 1, name: 'Alice'}, {id: 2, name: 'Bob'}, {id: 3, name: 'Charlie'}],
+ *   'id',
+ *   2,
+ *   item => item.name,
+ * ); // => ['Bob']
+ * ```
  */
 declare function select<Item extends PlainObject, ItemKey extends keyof Item, MapCallback extends (item: Item, index: number, array: Item[]) => unknown>(array: Item[], filterKey: ItemKey, filterValue: Item[ItemKey], mapCallback: MapCallback): Array<ReturnType<MapCallback>>;
 /**
  * Get a filtered and mapped array of items
+ *
  * @param array Array to search in
  * @param filterKey Key to get an item's value for matching
  * @param filterValue Value to match against
  * @param mapKey Key to get an item's value for mapping
  * @returns Filtered and mapped array of items
+ *
+ * @example
+ * ```typescript
+ * select(
+ *   [{id: 1, name: 'Alice'}, {id: 2, name: 'Bob'}, {id: 3, name: 'Charlie'}],
+ *   'id',
+ *   2,
+ *   'name',
+ * ); // => ['Bob']
+ * ```
  */
 declare function select<Item extends PlainObject, ItemKey extends keyof Item, MapKey extends keyof Item>(array: Item[], filterKey: ItemKey, filterValue: Item[ItemKey], mapKey: MapKey): Array<Item[MapKey]>;
 /**
  * Get a filtered and mapped array of items
+ *
  * @param array Array to search in
  * @param filterCallback Filter callback to match items
  * @param mapCallback Callback to map the matched items
  * @returns Filtered and mapped array of items
+ *
+ * @example
+ * ```typescript
+ * select(
+ *   [{id: 1, name: 'Alice'}, {id: 2, name: 'Bob'}, {id: 3, name: 'Charlie'}],
+ *   item => item.id === 2,
+ *   item => item.name,
+ * ); // => ['Bob']
+ * ```
  */
 declare function select<Item, FilterCallback extends (item: Item, index: number, array: Item[]) => unknown, MapCallback extends (item: Item, index: number, array: Item[]) => unknown>(array: Item[], filterCallback: FilterCallback, filterValue: ReturnType<FilterCallback>, mapCallback: MapCallback): Array<ReturnType<MapCallback>>;
 /**
@@ -51,39 +105,71 @@ declare function select<Item, FilterCallback extends (item: Item, index: number,
  * @param filterCallback Filter callback to match items
  * @param mapKey Key to get an item's value for mapping
  * @returns Filtered and mapped array of items
+ *
+ * @example
+ * ```typescript
+ * select(
+ *   [{id: 1, name: 'Alice'}, {id: 2, name: 'Bob'}, {id: 3, name: 'Charlie'}],
+ *   item => item.id,
+ *   2,
+ *   'name'
+ * ); // => ['Bob']
+ * ```
  */
 declare function select<Item extends PlainObject, FilterCallback extends (item: Item, index: number, array: Item[]) => unknown, MapKey extends keyof Item>(array: Item[], filterCallback: FilterCallback, filterValue: ReturnType<FilterCallback>, mapKey: MapKey): Array<Item[MapKey]>;
 /**
  * Get a filtered and mapped array of items
+ *
  * @param array Array to search in
  * @param filter Filter callback to match items
  * @param map Callback to map the matched items
  * @returns Filtered and mapped array of items
+ *
+ * @example
+ * ```typescript
+ * select(
+ *   [{id: 1, name: 'Alice'}, {id: 2, name: 'Bob'}, {id: 3, name: 'Charlie'}],
+ *   item => item.id === 2,
+ *   item => item.name,
+ * ); // => ['Bob']
+ * ```
  */
 declare function select<Item, MapCallback extends (item: Item, index: number, array: Item[]) => unknown>(array: Item[], filter: (item: Item, index: number, array: Item[]) => boolean, map: MapCallback): Array<ReturnType<MapCallback>>;
 /**
  * Get a filtered and mapped array of items
+ *
  * @param array Array to search in
  * @param filter Filter callback to match items
  * @param map Key to get an item's value for mapping
  * @returns Filtered and mapped array of items
+ *
+ * @example
+ * ```typescript
+ * select(
+ *   [{id: 1, name: 'Alice'}, {id: 2, name: 'Bob'}, {id: 3, name: 'Charlie'}],
+ *   item => item.id === 2,
+ *   'name'
+ * ); // => ['Bob']
+ * ```
  */
 declare function select<Item extends PlainObject, MapKey extends keyof Item>(array: Item[], filter: (item: Item, index: number, array: Item[]) => boolean, map: MapKey): Array<Item[MapKey]>;
 /**
  * Get a filtered and mapped array of items
+ *
  * @param array Array to search in
  * @param item Item to match against
  * @param map Callback to map the matched items
  * @returns Filtered and mapped array of items
+ *
+ * @example
+ * ```typescript
+ * select(
+ *   [1, 2, 3, 2, 1],
+ *   3,
+ *   value => value ** 2,
+ * ); // => [9]
+ * ```
  */
 declare function select<Item, MapCallback extends (item: Item, index: number, array: Item[]) => unknown>(array: Item[], item: Item, map: MapCallback): Array<ReturnType<MapCallback>>;
-/**
- * Get a filtered and mapped array of items
- * @param array Array to search in
- * @param item Item to match against
- * @param map Key to get an item's value for mapping
- * @returns Filtered and mapped array of items
- */
-declare function select<Item extends PlainObject, MapKey extends keyof Item>(array: Item[], item: Item, map: MapKey): Array<Item[MapKey]>;
 //#endregion
 export { select };

package/dist/array/single.d.mts

@@ -5,29 +5,58 @@ import { PlainObject } from "../models.mjs";
  * Get the _only_ item matching the given value
  *
  * Throws an error if multiple items match the 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 Only item that matches the value, or `undefined` if no match is found
+ *
+ * @example
+ * ```typescript
+ * single(
+ *   [{id: 1}, {id: 2}, {id: 3}],
+ *   item => item.id,
+ *   2
+ * ); // => {id: 2}
+ * ```
  */
 declare function single<Item, Callback extends (item: Item, index: number, array: Item[]) => unknown>(array: Item[], callback: Callback, value: ReturnType<Callback>): Item | undefined;
 /**
  * Get the _only_ item matching the given value by key
  *
  * Throws an error if multiple items match the value
+ *
  * @param array Array to search in
  * @param key Key to get an item's value for matching
  * @param value Value to match against
  * @returns Only item that matches the value, or `undefined` if no match is found
+ *
+ * @example
+ * ```typescript
+ * single(
+ *   [{id: 1}, {id: 2}, {id: 3}],
+ *   'id',
+ *   2
+ * ); // => {id: 2}
+ * ```
  */
 declare function single<Item extends PlainObject, ItemKey extends keyof Item>(array: Item[], key: ItemKey, value: Item[ItemKey]): Item | undefined;
 /**
  * Get the _only_ item matching the filter
  *
  * Throws an error if multiple items match the filter
+ *
  * @param array Array to search in
  * @param filter Filter callback to match items
  * @returns Only item that matches the filter, or `undefined` if no match is found
+ *
+ * @example
+ * ```typescript
+ * single(
+ *   [{id: 1}, {id: 2}, {id: 3}],
+ *   item => item.id === 2
+ * ); // => {id: 2}
+ * ```
  */
 declare function single<Item>(array: Item[], filter: (item: Item, index: number, array: Item[]) => boolean): Item | undefined;
 //#endregion

package/dist/array/slice.d.mts

@@ -3,83 +3,173 @@ import { PlainObject } from "../models.mjs";
 //#region src/array/slice.d.ts
 /**
  * Drop items from the start of an array until they match a value
+ *
  * @param array Original array
- * @param key Key to get an item's value for matching
+ * @param callback Callback to get an item's value for matching
  * @param value Value to match against
  * @returns New array with items dropped
+ *
+ * @example
+ * ```typescript
+ * drop(
+ *   [{id: 1}, {id: 2}, {id: 3}],
+ *   item => item.id,
+ *   2,
+ * ); // => [{id: 2}, {id: 3}]
+ * ```
  */
-declare function drop<Item extends PlainObject, ItemKey extends keyof Item>(array: Item[], key: ItemKey, value: Item[ItemKey]): Item[];
+declare function drop<Item, Callback extends (item: Item, index: number, array: Item[]) => unknown>(array: Item[], callback: Callback, value: ReturnType<Callback>): Item[];
 /**
  * Drop items from the start of an array until they match a value
+ *
  * @param array Original array
- * @param callback Callback to get an item's value for matching
+ * @param key Key to get an item's value for matching
  * @param value Value to match against
- * @return New array with items dropped
+ * @returns New array with items dropped
+ *
+ * @example
+ * ```typescript
+ * drop(
+ *   [{id: 1}, {id: 2}, {id: 3}],
+ *   'id',
+ *   2,
+ * ); // => [{id: 2}, {id: 3}]
+ * ```
  */
-declare function drop<Item, Callback extends (item: Item, index: number, array: Item[]) => unknown>(array: Item[], callback: Callback, value: ReturnType<Callback>): Item[];
+declare function drop<Item extends PlainObject, ItemKey extends keyof Item>(array: Item[], key: ItemKey, value: Item[ItemKey]): Item[];
 /**
  * Drop items from the start of an array while they match a filter
+ *
  * @param array Original array
  * @param callback Filter callback to match items
- * @return New array with items dropped
+ * @returns New array with items dropped
+ *
+ * @example
+ * ```typescript
+ * drop(
+ *   [{id: 1}, {id: 2}, {id: 3}],
+ *   item => item.id === 2,
+ * ); // => [{id: 2}, {id: 3}]
+ * ```
  */
 declare function drop<Item extends PlainObject>(array: Item[], callback: (item: Item, index: number, array: Item[]) => boolean): Item[];
 /**
  * Drop a specified number of items, from the start if `>= 0`, or from the end if `< 0`
+ *
  * @param array Original array
  * @param count Number of items to drop
  * @returns New array with items dropped
+ *
+ * @example
+ * ```typescript
+ * drop([1, 2, 3, 4, 5], 2);  // => [3, 4, 5]
+ * drop([1, 2, 3, 4, 5], -2); // => [1, 2, 3]
+ * ```
  */
 declare function drop(array: unknown[], count: number): unknown[];
 /**
  * Slice an array, returning a new array with a specified range of items
+ *
  * @param array Original array
  * @param start Start index _(inclusive)_
  * @param end End index _(exclusive)_
- * @return New array with sliced items
+ * @returns New array with sliced items
+ *
+ * @example
+ * ```typescript
+ * slice([1, 2, 3, 4, 5], 1, 4); // => [2, 3, 4]
+ * ```
  */
 declare function slice<Item>(array: Item[], start: number, end: number): Item[];
 /**
- * Slice an array, returning a new array with a specified number of items
+ * Slice an array, returning a new array with a specified number of items _(from the start)_
+ *
  * @param array Original array
- * @param count Maximum sixe of the new array
- * @return New array with sliced items
+ * @param count Maximum size of the new array
+ * @returns New array with sliced items
+ *
+ * @example
+ * ```typescript
+ * slice([1, 2, 3, 4, 5], 3); // => [1, 2, 3]
+ * ```
  */
 declare function slice<Item>(array: Item[], count: number): Item[];
 /**
  * Slice an array
+ *
  * @param array Array to slice
  * @returns Sliced array
+ *
+ * @example
+ * ```typescript
+ * slice([1, 2, 3]); // => [1, 2, 3]
+ * ```
  */
 declare function slice<Item>(array: Item[]): Item[];
 /**
  * Take items from the start of an array until they match a value
+ *
  * @param array Original array
- * @param key Key to get an item's value for matching
+ * @param callback Callback to get an item's value for matching
  * @param value Value to match against
  * @returns New array with taken items
+ *
+ * @example
+ * ```typescript
+ * take(
+ *   [{id: 1}, {id: 2}, {id: 3}],
+ *   item => item.id,
+ *   2,
+ * ); // => [{id: 1}]
+ * ```
  */
-declare function take<Item extends PlainObject, ItemKey extends keyof Item>(array: Item[], key: ItemKey, value: Item[ItemKey]): Item[];
+declare function take<Item, Callback extends (item: Item, index: number, array: Item[]) => unknown>(array: Item[], callback: Callback, value: ReturnType<Callback>): Item[];
 /**
  * Take items from the start of an array until they match a value
+ *
  * @param array Original array
- * @param callback Callback to get an item's value for matching
+ * @param key Key to get an item's value for matching
  * @param value Value to match against
- * @return New array with taken items
+ * @returns New array with taken items
+ *
+ * @example
+ * ```typescript
+ * take(
+ *   [{id: 1}, {id: 2}, {id: 3}],
+ *   'id',
+ *   2,
+ * ); // => [{id: 1}]
+ * ```
  */
-declare function take<Item, Callback extends (item: Item, index: number, array: Item[]) => unknown>(array: Item[], callback: Callback, value: ReturnType<Callback>): Item[];
+declare function take<Item extends PlainObject, ItemKey extends keyof Item>(array: Item[], key: ItemKey, value: Item[ItemKey]): Item[];
 /**
  * Take items from the start of an array while they match a filter
+ *
  * @param array Original array
  * @param callback Filter callback to match items
- * @return New array with taken items
+ * @returns New array with taken items
+ *
+ * @example
+ * ```typescript
+ * take(
+ *   [{id: 1}, {id: 2}, {id: 3}],
+ *   item => item.id === 2,
+ * ); // => [{id: 1}]
+ * ```
  */
 declare function take<Item extends PlainObject>(array: Item[], callback: (item: Item, index: number, array: Item[]) => boolean): Item[];
 /**
  * Take a specified number of items, from the start if `>= 0`, or from the end if `< 0`
+ *
  * @param array Original array
  * @param count Number of items to take
  * @returns New array with taken items
+ *
+ * @example
+ * ```typescript
+ * take([1, 2, 3, 4, 5], 2);  // => [1, 2]
+ * take([1, 2, 3, 4, 5], -2); // => [4, 5]
+ * ```
  */
 declare function take(array: unknown[], count: number): unknown[];
 //#endregion

package/dist/array/sort.d.mts

@@ -65,9 +65,15 @@ type ComparisonSorter<Item> = (first: Item, second: Item) => number;
  * Direction to sort by
  */
 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
+ */
 type Sorter<Item> = {
   /**
    * Sort an array of items
+   *
    * @param array Array to sort
    * @returns Sorted array
    */
@@ -76,6 +82,7 @@ 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
@@ -83,6 +90,7 @@ type Sorter<Item> = {
   index(array: Item[], item: Item): number;
   /**
    * Is the array sorted?
+   *
    * @param array Array to check
    * @returns `true` if sorted, otherwise `false`
    */
@@ -93,7 +101,8 @@ type Sorter<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 sorters Sorters to use to determine sorting
@@ -106,7 +115,8 @@ declare function getSortedIndex<Item>(array: Item[], item: Item, sorters: Array<
  *
  * _(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
@@ -119,7 +129,8 @@ declare function getSortedIndex<Item>(array: Item[], item: Item, sorter: ArraySo
  *
  * _(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`)_
@@ -130,6 +141,7 @@ declare function getSortedIndex<Item>(array: Item[], item: Item, descending?: bo
  * 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
@@ -139,6 +151,7 @@ declare function initializeSorter<Item>(sorters: Array<ArraySorter<Item>>, desce
  * 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
@@ -148,12 +161,14 @@ declare function initializeSorter<Item>(sorter: ArraySorter<Item>, descending?:
  * 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
  */
 declare function initializeSorter<Item>(descending?: boolean): Sorter<Item>;
 /**
  * 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)_
@@ -162,6 +177,7 @@ declare function initializeSorter<Item>(descending?: boolean): Sorter<Item>;
 declare function isSorted<Item>(array: Item[], sorters: Array<ArraySorter<Item>>, descending?: boolean): boolean;
 /**
  * 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)_
@@ -172,6 +188,7 @@ declare function isSorted<Item>(array: Item[], sorter: ArraySorter<Item>, descen
  * 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`
@@ -179,10 +196,19 @@ declare function isSorted<Item>(array: Item[], sorter: ArraySorter<Item>, descen
 declare function isSorted<Item>(array: Item[], descending?: boolean): 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}]
+ * ```
  */
 declare function sort<Item>(array: Item[], comparator: (first: Item, second: Item) => number, descending?: boolean): Item[];
 /**
@@ -209,7 +235,7 @@ declare function sort<Item>(array: Item[], sorter: ArraySorter<Item>, descending
  */
 declare function sort<Item>(array: Item[], descending?: boolean): Item[];
 declare namespace sort {
-  var index: typeof getSortedIndex;
+  var getIndex: typeof getSortedIndex;
   var initialize: typeof initializeSorter;
   var is: typeof isSorted;
 }

package/dist/array/sort.mjs

@@ -124,7 +124,7 @@ function sortArray(array, sorters) {
 	const { length } = sorters;
 	return array.length > 1 ? array.sort((first, second) => getComparisonValue(first, second, sorters, length)) : array;
 }
-sort.index = getSortedIndex;
+sort.getIndex = getSortedIndex;
 sort.initialize = initializeSorter;
 sort.is = isSorted;
 const SORT_PEEK_PERCENTAGE = 10;

package/dist/array/splice.d.mts

@@ -1,34 +1,82 @@
 //#region src/array/splice.d.ts
 /**
  * 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]
+ * ```
  */
 declare 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]
+ * ```
  */
 declare 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]
+ * ```
  */
 declare 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]
+ * ```
  */
 declare function splice<Item>(array: Item[], start: number): Item[];
 //#endregion

package/dist/array/splice.mjs

@@ -1,7 +1,8 @@
 import { INSERT_TYPE_SPLICE, insertValues } from "../internal/array/insert.mjs";
 //#region src/array/splice.ts
 function splice(array, start, deleteCountOrItems, items) {
-	return insertValues(INSERT_TYPE_SPLICE, array, typeof deleteCountOrItems === "number" ? items : deleteCountOrItems, start, typeof deleteCountOrItems === "number" ? deleteCountOrItems : 0);
+	const deleteCountIsNumber = typeof deleteCountOrItems === "number";
+	return insertValues(INSERT_TYPE_SPLICE, array, deleteCountIsNumber ? items : deleteCountOrItems, start, deleteCountIsNumber ? deleteCountOrItems : 0);
 }
 //#endregion
 export { splice };