@oscarpalmer/atoms 0.185.0 → 0.186.0

package/src/array/partition.ts

@@ -5,10 +5,20 @@ import type {PlainObject} from '../models';
 
 /**
  * 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}]]
+ * ```
  */
 export function partition<
 	Item,
@@ -17,10 +27,20 @@ export function partition<
 
 /**
  * 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}]]
+ * ```
  */
 export function partition<Item extends PlainObject, ItemKey extends keyof Item>(
 	array: Item[],
@@ -30,9 +50,18 @@ export function partition<Item extends PlainObject, ItemKey extends keyof 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}]]
+ * ```
  */
 export function partition<Item>(
 	array: Item[],
@@ -41,9 +70,15 @@ export function partition<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]]
+ * ```
  */
 export function partition<Item>(array: Item[], item: Item): Item[][];
 

package/src/array/push.ts

@@ -2,13 +2,19 @@ import {INSERT_TYPE_PUSH, insertValues} from '../internal/array/insert';
 
 // #region Functions
 
-// Uses chunking to avoid call stack size being exceeded
-
 /**
  * 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]
+ * ```
  */
 export function push<Item>(array: Item[], pushed: Item[]): number {
 	return insertValues(INSERT_TYPE_PUSH, array, pushed, array.length, 0) as number;

package/src/array/reverse.ts

@@ -2,6 +2,7 @@
 
 /**
  * Reverse the order of items in an array
+ *
  * @param array Array to reverse
  * @returns Reversed array
  */

package/src/array/select.ts

@@ -5,11 +5,22 @@ import type {PlainObject} from '../models';
 
 /**
  * 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']
+ * ```
  */
 export function select<
 	Item,
@@ -24,11 +35,22 @@ export function select<
 
 /**
  * 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']
+ * ```
  */
 export function select<
 	Item extends PlainObject,
@@ -43,11 +65,22 @@ export function select<
 
 /**
  * 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']
+ * ```
  */
 export function select<
 	Item extends PlainObject,
@@ -62,11 +95,22 @@ export function select<
 
 /**
  * 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']
+ * ```
  */
 export function select<
 	Item extends PlainObject,
@@ -81,10 +125,20 @@ export function select<
 
 /**
  * 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']
+ * ```
  */
 export function select<
 	Item,
@@ -103,6 +157,16 @@ export function select<
  * @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']
+ * ```
  */
 export function select<
 	Item extends PlainObject,
@@ -117,10 +181,20 @@ export function select<
 
 /**
  * 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']
+ * ```
  */
 export function select<
 	Item,
@@ -133,10 +207,20 @@ export function select<
 
 /**
  * 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']
+ * ```
  */
 export function select<Item extends PlainObject, MapKey extends keyof Item>(
 	array: Item[],
@@ -146,29 +230,26 @@ export function select<Item extends PlainObject, MapKey extends keyof Item>(
 
 /**
  * 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]
+ * ```
  */
 export 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
- */
-export function select<Item extends PlainObject, MapKey extends keyof Item>(
-	array: Item[],
-	item: Item,
-	map: MapKey,
-): Array<Item[MapKey]>;
-
 export function select(array: unknown[], ...parameters: unknown[]): unknown[] {
 	const mapper = parameters.pop();
 

package/src/array/single.ts

@@ -7,10 +7,20 @@ import type {PlainObject} from '../models';
  * 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}
+ * ```
  */
 export function single<
 	Item,
@@ -21,10 +31,20 @@ export function single<
  * 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}
+ * ```
  */
 export function single<Item extends PlainObject, ItemKey extends keyof Item>(
 	array: Item[],
@@ -36,9 +56,18 @@ export function single<Item extends PlainObject, ItemKey extends keyof Item>(
  * 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}
+ * ```
  */
 export function single<Item>(
 	array: Item[],

package/src/array/slice.ts

@@ -11,35 +11,64 @@ type ExtractType = 'drop' | 'take';
 
 /**
  * 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}]
+ * ```
  */
-export function drop<Item extends PlainObject, ItemKey extends keyof Item>(
+export function drop<Item, Callback extends (item: Item, index: number, array: Item[]) => unknown>(
 	array: Item[],
-	key: ItemKey,
-	value: Item[ItemKey],
+	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}]
+ * ```
  */
-export function drop<Item, Callback extends (item: Item, index: number, array: Item[]) => unknown>(
+export function drop<Item extends PlainObject, ItemKey extends keyof Item>(
 	array: Item[],
-	callback: Callback,
-	value: ReturnType<Callback>,
+	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}]
+ * ```
  */
 export function drop<Item extends PlainObject>(
 	array: Item[],
@@ -48,9 +77,16 @@ export function drop<Item extends PlainObject>(
 
 /**
  * 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]
+ * ```
  */
 export function drop(array: unknown[], count: number): unknown[];
 
@@ -138,25 +174,43 @@ function extract(
 
 /**
  * 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]
+ * ```
  */
 export 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]
+ * ```
  */
 export 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]
+ * ```
  */
 export function slice<Item>(array: Item[]): Item[];
 
@@ -187,35 +241,64 @@ export function slice(array: unknown[], first?: number, second?: number): unknow
 
 /**
  * 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}]
+ * ```
  */
-export function take<Item extends PlainObject, ItemKey extends keyof Item>(
+export function take<Item, Callback extends (item: Item, index: number, array: Item[]) => unknown>(
 	array: Item[],
-	key: ItemKey,
-	value: Item[ItemKey],
+	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}]
+ * ```
  */
-export function take<Item, Callback extends (item: Item, index: number, array: Item[]) => unknown>(
+export function take<Item extends PlainObject, ItemKey extends keyof Item>(
 	array: Item[],
-	callback: Callback,
-	value: ReturnType<Callback>,
+	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}]
+ * ```
  */
 export function take<Item extends PlainObject>(
 	array: Item[],
@@ -224,9 +307,16 @@ export function take<Item extends PlainObject>(
 
 /**
  * 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]
+ * ```
  */
 export function take(array: unknown[], count: number): unknown[];