@oscarpalmer/atoms 0.184.2 → 0.186.0

package/dist/array/{position.d.mts → match.d.mts}

@@ -1,121 +1,253 @@
 import { PlainObject } from "../models.mjs";
 
-//#region src/array/position.d.ts
-type ArrayPosition = 'end' | 'inside' | 'invalid' | 'outside' | 'same' | 'start';
+//#region src/array/match.d.ts
+/**
+ * Comparison of an array within another array
+ */
+type ArrayComparison = 'end' | 'inside' | 'invalid' | 'outside' | 'same' | 'start';
 /**
  * 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
+ * ```
  */
-declare function endsWithArray<Item extends PlainObject>(haystack: Item[], needle: Item[], key: keyof Item): boolean;
+declare function endsWithArray<Item>(haystack: Item[], needle: 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
+ * ```
  */
-declare function endsWithArray<Item>(haystack: Item[], needle: Item[], callback: (item: Item, index: number, array: Item[]) => unknown): boolean;
+declare function endsWithArray<Item extends PlainObject>(haystack: Item[], needle: Item[], 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
+ * ```
  */
 declare function endsWithArray<Item>(haystack: Item[], needle: Item[]): boolean;
 /**
  * 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'
+ * ```
  */
-declare function getArrayPosition<Item extends PlainObject>(haystack: Item[], needle: Item[], key: keyof Item): ArrayPosition;
+declare function getArrayComparison<Item>(haystack: Item[], needle: 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'
+ * ```
  */
-declare function getArrayPosition<Item>(haystack: Item[], needle: Item[], callback: (item: Item, index: number, array: Item[]) => unknown): ArrayPosition;
+declare function getArrayComparison<Item extends PlainObject>(haystack: Item[], needle: Item[], 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'
+ * ```
  */
-declare function getArrayPosition<Item>(haystack: Item[], needle: Item[]): ArrayPosition;
+declare function getArrayComparison<Item>(haystack: Item[], needle: Item[]): ArrayComparison;
 /**
  * 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
+ * ```
  */
-declare function includesArray<Item extends PlainObject>(haystack: Item[], needle: Item[], key: keyof Item): boolean;
+declare function includesArray<Item>(haystack: Item[], needle: 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
+ * ```
  */
-declare function includesArray<Item>(haystack: Item[], needle: Item[], callback: (item: Item, index: number, array: Item[]) => unknown): boolean;
+declare function includesArray<Item extends PlainObject>(haystack: Item[], needle: Item[], 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
+ * ```
  */
 declare function includesArray<Item>(haystack: Item[], needle: Item[]): boolean;
 /**
  * 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
+ * ```
  */
-declare function indexOfArray<Item extends PlainObject>(haystack: Item[], needle: Item[], key: keyof Item): number;
+declare function indexOfArray<Item>(haystack: Item[], needle: 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
+ * ```
  */
-declare function indexOfArray<Item>(haystack: Item[], needle: Item[], callback: (item: Item, index: number, array: Item[]) => unknown): number;
+declare function indexOfArray<Item extends PlainObject>(haystack: Item[], needle: Item[], 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
+ * ```
  */
 declare function indexOfArray<Item>(haystack: Item[], needle: Item[]): number;
 /**
  * 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
+ * ```
  */
-declare function startsWithArray<Item extends PlainObject>(haystack: Item[], needle: Item[], key: keyof Item): boolean;
+declare function startsWithArray<Item>(haystack: Item[], needle: 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
+ * ```
  */
-declare function startsWithArray<Item>(haystack: Item[], needle: Item[], callback: (item: Item, index: number, array: Item[]) => unknown): boolean;
+declare function startsWithArray<Item extends PlainObject>(haystack: Item[], needle: Item[], 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
+ * ```
  */
 declare function startsWithArray<Item>(haystack: Item[], needle: Item[]): boolean;
 //#endregion
-export { ArrayPosition, endsWithArray, getArrayPosition, includesArray, indexOfArray, startsWithArray };
+export { ArrayComparison, endsWithArray, getArrayComparison, includesArray, indexOfArray, startsWithArray };

package/dist/array/{position.mjs → match.mjs}

@@ -1,14 +1,14 @@
 import { getArrayCallback } from "../internal/array/callbacks.mjs";
-//#region src/array/position.ts
+//#region src/array/match.ts
 function endsWithArray(haystack, needle, key) {
 	return endings.has(getPosition(haystack, needle, key)[1]);
 }
-function getArrayPosition(haystack, needle, key) {
+function getArrayComparison(haystack, needle, key) {
 	return getPosition(haystack, needle, key)[1];
 }
 function getName(start, haystack, needle) {
-	if (start === 0) return haystack === needle ? POSITION_SAME : POSITION_START;
-	return start + needle === haystack ? POSITION_END : POSITION_INSIDE;
+	if (start === 0) return haystack === needle ? COMPARISON_SAME : COMPARISON_START;
+	return start + needle === haystack ? COMPARISON_END : COMPARISON_INSIDE;
 }
 function getPosition(haystack, needle, key) {
 	if (!Array.isArray(haystack) || !Array.isArray(needle)) return invalid;
@@ -43,16 +43,16 @@ function indexOfArray(haystack, needle, key) {
 function startsWithArray(haystack, needle, key) {
 	return starts.has(getPosition(haystack, needle, key)[1]);
 }
-const POSITION_END = "end";
-const POSITION_INSIDE = "inside";
-const POSITION_INVALID = "invalid";
-const POSITION_OUTSIDE = "outside";
-const POSITION_SAME = "same";
-const POSITION_START = "start";
-const endings = new Set([POSITION_END, POSITION_SAME]);
-const invalid = [-1, POSITION_INVALID];
-const outside = [-1, POSITION_OUTSIDE];
-const outsides = new Set([POSITION_INVALID, POSITION_OUTSIDE]);
-const starts = new Set([POSITION_START, POSITION_SAME]);
+const COMPARISON_END = "end";
+const COMPARISON_INSIDE = "inside";
+const COMPARISON_INVALID = "invalid";
+const COMPARISON_OUTSIDE = "outside";
+const COMPARISON_SAME = "same";
+const COMPARISON_START = "start";
+const endings = new Set([COMPARISON_END, COMPARISON_SAME]);
+const invalid = [-1, COMPARISON_INVALID];
+const outside = [-1, COMPARISON_OUTSIDE];
+const outsides = new Set([COMPARISON_INVALID, COMPARISON_OUTSIDE]);
+const starts = new Set([COMPARISON_START, COMPARISON_SAME]);
 //#endregion
-export { endsWithArray, getArrayPosition, includesArray, indexOfArray, startsWithArray };
+export { endsWithArray, getArrayComparison, includesArray, indexOfArray, startsWithArray };

package/dist/array/move.d.mts

@@ -7,36 +7,66 @@ import { PlainObject } from "../models.mjs";
  * 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)
+ * ```
  */
-declare function move<Item extends PlainObject, ItemKey extends keyof Item>(array: Item[], from: Item | Item[], to: Item | Item[], key: ItemKey): Item[];
+declare function move<Item>(array: Item[], from: Item | Item[], to: Item | Item[], callback: (item: Item, index: number, array: Item[]) => unknown): Item[];
 /**
  * Move an item _(or array of items)_ to the position of another item _(or array of items)_ within an array
  *
  * 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)
+ * ```
  */
-declare function move<Item>(array: Item[], from: Item | Item[], to: Item | Item[], callback: (item: Item, index: number, array: Item[]) => unknown): Item[];
+declare function move<Item extends PlainObject, ItemKey extends keyof Item>(array: Item[], from: Item | Item[], to: Item | Item[], key: ItemKey): Item[];
 /**
  * Move an item _(or array of items)_ to the position of another item _(or array of items)_ within an array
  *
  * 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)
+ * ```
  */
 declare function move<Item>(array: Item[], from: Item | Item[], to: Item | Item[]): Item[];
 declare namespace move {
@@ -49,10 +79,20 @@ declare namespace move {
  * 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)
+ * ```
  */
 declare function moveIndices<Item>(array: Item[], from: number, to: number): Item[];
 /**
@@ -61,36 +101,66 @@ declare function moveIndices<Item>(array: Item[], from: number, to: number): Ite
  * 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)_
  */
-declare function moveToIndex<Item extends PlainObject, ItemKey extends keyof Item>(array: Item[], value: Item | Item[], index: number, key: ItemKey): Item[];
+declare function moveToIndex<Item>(array: Item[], value: Item | Item[], index: number, callback: (item: Item, index: number, array: Item[]) => unknown): Item[];
 /**
  * Move an item _(or array of items)_ to an index within an array
  *
  * 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)
+ * ```
  */
-declare function moveToIndex<Item>(array: Item[], value: Item | Item[], index: number, callback: (item: Item, index: number, array: Item[]) => unknown): Item[];
+declare function moveToIndex<Item extends PlainObject, ItemKey extends keyof Item>(array: Item[], value: Item | Item[], index: number, key: ItemKey): Item[];
 /**
  * Move an item _(or array of items)_ to an index within an array
  *
  * 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)
+ * ```
  */
 declare function moveToIndex<Item>(array: Item[], value: Item | Item[], index: number): Item[];
 //#endregion

package/dist/array/move.mjs

@@ -1,4 +1,4 @@
-import { indexOfArray } from "./position.mjs";
+import { indexOfArray } from "./match.mjs";
 import { arraysOverlap } from "../internal/array/overlap.mjs";
 //#region src/array/move.ts
 function move(array, from, to, key) {
@@ -31,10 +31,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)
+* ```
 */
 function moveIndices(array, from, to) {
 	if (!Array.isArray(array)) return [];

package/dist/array/partition.d.mts

@@ -3,32 +3,67 @@ import { PlainObject } from "../models.mjs";
 //#region src/array/partition.d.ts
 /**
  * Get a partitioned array of items
+ *
  * @param array Array to search in
  * @param callback Callback to get an item's value for matching
  * @param value Value to match against
  * @returns Partitioned array of items
+ *
+ * @example
+ * ```typescript
+ * partition(
+ *   [{id: 1}, {id: 2}, {id: 3}],
+ *   item => item.id,
+ *   2,
+ * ); // => [[{id: 2}], [{id: 1}, {id: 3}]]
+ * ```
  */
 declare function partition<Item, Callback extends (item: Item, index: number, array: Item[]) => unknown>(array: Item[], callback: Callback, value: ReturnType<Callback>): Item[][];
 /**
  * Get a partitioned array of items
+ *
  * @param array Array to search in
  * @param key Key to get an item's value for matching
  * @param value Value to match against
  * @returns Partitioned array of items
+ *
+ * @example
+ * ```typescript
+ * partition(
+ *   [{id: 1}, {id: 2}, {id: 3}],
+ *   'id',
+ *   2,
+ * ); // => [[{id: 2}], [{id: 1}, {id: 3}]]
+ * ```
  */
 declare function partition<Item extends PlainObject, ItemKey extends keyof Item>(array: Item[], key: ItemKey, value: Item[ItemKey]): Item[][];
 /**
  * Get a partitioned array of items
+ *
  * @param array Array to search in
  * @param filter Filter callback to match items
  * @returns Partitioned array of items
+ *
+ * @example
+ * ```typescript
+ * partition(
+ *   [{id: 1}, {id: 2}, {id: 3}],
+ *   item => item.id === 2,
+ * ); // => [[{id: 2}], [{id: 1}, {id: 3}]]
+ * ```
  */
 declare function partition<Item>(array: Item[], filter: (item: Item, index: number, array: Item[]) => boolean): Item[][];
 /**
  * Get a partitioned array of items matching the given item
+ *
  * @param array Array to search in
  * @param item Item to match against
  * @returns Partitioned array of items
+ *
+ * @example
+ * ```typescript
+ * partition([1, 2, 3, 4, 5], 3); // => [[3], [1, 2, 4, 5]]
+ * ```
  */
 declare function partition<Item>(array: Item[], item: Item): Item[][];
 //#endregion

package/dist/array/push.d.mts

@@ -1,9 +1,17 @@
 //#region src/array/push.d.ts
 /**
  * Push items into an array _(at the end)_
+ *
+ * _(Uses chunking to avoid call stack size being exceeded)_
+ *
  * @param array Original array
  * @param pushed Pushed items
  * @returns New length of the array
+ *
+ * @example
+ * ```typescript
+ * push([1, 2, 3], [4, 5]); // => 5 (new length); array becomes [1, 2, 3, 4, 5]
+ * ```
  */
 declare function push<Item>(array: Item[], pushed: Item[]): number;
 //#endregion

package/dist/array/push.mjs

@@ -2,9 +2,17 @@ import { INSERT_TYPE_PUSH, insertValues } from "../internal/array/insert.mjs";
 //#region src/array/push.ts
 /**
 * Push items into an array _(at the end)_
+*
+* _(Uses chunking to avoid call stack size being exceeded)_
+*
 * @param array Original array
 * @param pushed Pushed items
 * @returns New length of the array
+*
+* @example
+* ```typescript
+* push([1, 2, 3], [4, 5]); // => 5 (new length); array becomes [1, 2, 3, 4, 5]
+* ```
 */
 function push(array, pushed) {
 	return insertValues(INSERT_TYPE_PUSH, array, pushed, array.length, 0);

package/dist/array/reverse.d.mts

@@ -1,6 +1,7 @@
 //#region src/array/reverse.d.ts
 /**
  * Reverse the order of items in an array
+ *
  * @param array Array to reverse
  * @returns Reversed array
  */

package/dist/array/reverse.mjs

@@ -1,6 +1,7 @@
 //#region src/array/reverse.ts
 /**
 * Reverse the order of items in an array
+*
 * @param array Array to reverse
 * @returns Reversed array
 */