@oscarpalmer/atoms 0.184.2 → 0.186.0

package/src/array/group-by.ts

@@ -7,10 +7,20 @@ import type {Key, KeyedValue, PlainObject, Simplify} from '../models';
  * Create a record from an array of items using a specific key and value
  *
  * If multiple items have the same key, the latest item's value will be used
+ *
  * @param array Array to group
  * @param key Callback to get an item's grouping key
  * @param value Callback to get an item's value
  * @returns Record of keyed values
+ *
+ * @example
+ * ```typescript
+ * groupBy(
+ *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
+ *   item => item.value,
+ *   item => item,
+ * ); // => {10: {id: 3, value: 10}, 20: {id: 2, value: 20}}
+ * ```
  */
 export function groupBy<
 	Item,
@@ -26,10 +36,20 @@ export function groupBy<
  * Create a record from an array of items using a specific key and value
  *
  * If multiple items have the same key, the latest item's value will be used
+ *
  * @param array Array to group
  * @param key Callback to get an item's grouping key
  * @param value Key to use for value
  * @returns Record of keyed values
+ *
+ * @example
+ * ```typescript
+ * groupBy(
+ *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
+ *   item => item.value,
+ *   'id'
+ * ); // => {10: 3, 20: 2}
+ * ```
  */
 export function groupBy<
 	Item extends PlainObject,
@@ -45,10 +65,20 @@ export function groupBy<
  * Create a record from an array of items using a specific key and value
  *
  * If multiple items have the same key, the latest item's value will be used
+ *
  * @param array Array to group
  * @param key Key to use for grouping
  * @param value Callback to get an item's value
  * @returns Record of keyed values
+ *
+ * @example
+ * ```typescript
+ * groupBy(
+ *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
+ *   'value',
+ *   item => item,
+ * ); // => {10: {id: 3, value: 10}, 20: {id: 2, value: 20}}
+ * ```
  */
 export function groupBy<
 	Item extends PlainObject,
@@ -64,10 +94,20 @@ export function groupBy<
  * Create a record from an array of items using a specific key and value
  *
  * If multiple items have the same key, the latest item's value will be used
+ *
  * @param array Array to group
  * @param key Key to use for grouping
  * @param value Key to use for value
  * @returns Record of keyed values
+ *
+ * @example
+ * ```typescript
+ * groupBy(
+ *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
+ *   'value',
+ *   'id'
+ * ); // => {10: 3, 20: 2}
+ * ```
  */
 export function groupBy<
 	Item extends PlainObject,
@@ -83,9 +123,18 @@ export function groupBy<
  * Create a record from an array of items using a specific key
  *
  * If multiple items have the same key, the latest item will be used
+ *
  * @param array Array to group
  * @param callback Callback to get an item's grouping key
  * @returns Record of keyed items
+ *
+ * @example
+ * ```typescript
+ * groupBy(
+ *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
+ *   item => item.value,
+ * ); // => {10: {id: 3, value: 10}, 20: {id: 2, value: 20}}
+ * ```
  */
 export function groupBy<Item, Callback extends (item: Item, index: number, array: Item[]) => Key>(
 	array: Item[],
@@ -96,9 +145,18 @@ export function groupBy<Item, Callback extends (item: Item, index: number, array
  * Create a record from an array of items using a specific key
  *
  * If multiple items have the same key, the latest item will be used
+ *
  * @param array Array to group
  * @param key Key to use for grouping
  * @returns Record of keyed items
+ *
+ * @example
+ * ```typescript
+ * groupBy(
+ *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
+ *   'value',
+ * ); // => {10: {id: 3, value: 10}, 20: {id: 2, value: 20}}
+ * ```
  */
 export function groupBy<Item extends PlainObject, ItemKey extends keyof Item>(
 	array: Item[],
@@ -107,8 +165,16 @@ export function groupBy<Item extends PlainObject, ItemKey extends keyof Item>(
 
 /**
  * Create a record from an array of items _(using indices as keys)_
+ *
  * @param array Array to group
  * @returns Record of indiced items
+ *
+ * @example
+ * ```typescript
+ * groupBy(
+ *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
+ * ); // => {0: {id: 1, value: 10}, 1: {id: 2, value: 20}, 2: {id: 3, value: 10}}
+ * ```
  */
 export function groupBy<Item>(array: Item[]): Record<number, Item>;
 
@@ -122,10 +188,23 @@ groupBy.arrays = groupArraysBy;
  * Create a record from an array of items using a specific key and value, grouping values into arrays
  *
  * Available as `groupArraysBy` and `groupBy.arrays`
+ *
  * @param array Array to group
  * @param key Callback to get an item's grouping key
  * @param value Callback to get an item's value
  * @returns Record of keyed values
+ *
+ * @example
+ * ```typescript
+ * groupArraysBy(
+ *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
+ *   item => item.value,
+ *   item => item,
+ * ); // => {
+ *    //   10: [{id: 1, value: 10}, {id: 3, value: 10}],
+ *    //   20: [{id: 2, value: 20}],
+ *    // }
+ * ```
  */
 export function groupArraysBy<
 	Item,
@@ -141,10 +220,23 @@ export function groupArraysBy<
  * Create a record from an array of items using a specific key and value, grouping values into arrays
  *
  * Available as `groupArraysBy` and `groupBy.arrays`
+ *
  * @param array Array to group
  * @param key Callback to get an item's grouping key
  * @param value Key to use for value
  * @returns Record of keyed values
+ *
+ * @example
+ * ```typescript
+ * groupArraysBy(
+ *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
+ *   item => item.value,
+ *   'id',
+ * ); // => {
+ *    //   10: [1, 3],
+ *    //   20: [2],
+ *    // }
+ * ```
  */
 export function groupArraysBy<
 	Item extends PlainObject,
@@ -160,10 +252,23 @@ export function groupArraysBy<
  * Create a record from an array of items using a specific key and value, grouping values into arrays
  *
  * Available as `groupArraysBy` and `groupBy.arrays`
+ *
  * @param array Array to group
  * @param key Key to use for grouping
  * @param value Callback to get an item's value
  * @returns Record of keyed values
+ *
+ * @example
+ * ```typescript
+ * groupArraysBy(
+ *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
+ *   'value',
+ *   item => item,
+ * ); // => {
+ *    //   10: [{id: 1, value: 10}, {id: 3, value: 10}],
+ *    //   20: [{id: 2, value: 20}],
+ *    // }
+ * ```
  */
 export function groupArraysBy<
 	Item extends PlainObject,
@@ -179,10 +284,23 @@ export function groupArraysBy<
  * Create a record from an array of items using a specific key and value, grouping values into arrays
  *
  * Available as `groupArraysBy` and `groupBy.arrays`
+ *
  * @param array Array to group
  * @param key Key to use for grouping
  * @param value Key to use for value
  * @returns Record of keyed values
+ *
+ * @example
+ * ```typescript
+ * groupArraysBy(
+ *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
+ *   'value',
+ *   'id',
+ * ); // => {
+ *    //   10: [1, 3],
+ *    //   20: [2],
+ *    // }
+ * ```
  */
 export function groupArraysBy<
 	Item extends PlainObject,
@@ -198,9 +316,21 @@ export function groupArraysBy<
  * Create a record from an array of items using a specific key, grouping items into arrays
  *
  * Available as `groupArraysBy` and `groupBy.arrays`
+ *
  * @param array Array to group
  * @param callback Callback to get an item's grouping key
  * @returns Record of keyed items
+ *
+ * @example
+ * ```typescript
+ * groupArraysBy(
+ *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
+ *   item => item.value,
+ * ); // => {
+ *    //   10: [{id: 1, value: 10}, {id: 3, value: 10}],
+ *    //   20: [{id: 2, value: 20}],
+ *    // }
+ * ```
  */
 export function groupArraysBy<
 	Item,
@@ -211,9 +341,21 @@ export function groupArraysBy<
  * Create a record from an array of items using a specific key, grouping items into arrays
  *
  * Available as `groupArraysBy` and `groupBy.arrays`
+ *
  * @param array Array to group
  * @param key Key to use for grouping
  * @returns Record of keyed items
+ *
+ * @example
+ * ```typescript
+ * groupArraysBy(
+ *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
+ *   'value',
+ * ); // => {
+ *    //   10: [{id: 1, value: 10}, {id: 3, value: 10}],
+ *    //   20: [{id: 2, value: 20}],
+ *    // }
+ * ```
  */
 export function groupArraysBy<Item extends PlainObject, ItemKey extends keyof Item>(
 	array: Item[],

package/src/array/index.ts

@@ -12,7 +12,7 @@ export * from './get';
 export * from './insert';
 export * from './intersection';
 export * from './partition';
-export * from './position';
+export * from './match';
 export * from './push';
 export * from './reverse';
 export * from './select';

package/src/array/insert.ts

@@ -2,22 +2,36 @@ import {INSERT_TYPE_INSERT, insertValues} from '../internal/array/insert';
 
 // #region Functions
 
-// Uses chunking to avoid call stack size being exceeded
-
 /**
  * Insert items into an array at a specified index
+ *
+ * _(Uses chunking to avoid call stack size being exceeded)_
+ *
  * @param array Original array
  * @param index Index to insert at
  * @param items Inserted items
  * @returns Updated array
+ *
+ * @example
+ * ```typescript
+ * insert([1, 2, 3], 1, [4, 5]); // => [1, 4, 5, 2, 3]
+ * ```
  */
 export function insert<Item>(array: Item[], index: number, items: Item[]): Item[];
 
 /**
  * Insert items into an array _(at the end)_
+ *
+ * _(Uses chunking to avoid call stack size being exceeded)_
+ *
  * @param array Original array
  * @param items Inserted items
  * @returns Updated array
+ *
+ * @example
+ * ```typescript
+ * insert([1, 2, 3], [4, 5]); // => [1, 2, 3, 4, 5]
+ * ```
  */
 export function insert<Item>(array: Item[], items: Item[]): Item[];
 

package/src/array/intersection.ts

@@ -1,11 +1,23 @@
 import {COMPARE_SETS_INTERSECTION, compareSets} from '../internal/array/sets';
 
+// #region Functions
+
 /**
  * Get the common values between two arrays
+ *
  * @param first First array
  * @param second Second array
  * @param callback Callback to get an item's value for comparison
  * @returns Common values from both arrays
+ *
+ * @example
+ * ```typescript
+ * intersection(
+ *   [{id: 1}, {id: 2}, {id: 3}],
+ *   [{id: 2}, {id: 3}, {id: 4}],
+ *   item => item.id,
+ * ); // => [{id: 2}, {id: 3}]
+ * ```
  */
 export function intersection<First, Second>(
 	first: First[],
@@ -15,10 +27,20 @@ export function intersection<First, Second>(
 
 /**
  * Get the common values between two arrays
+ *
  * @param first First array
  * @param second Second array
  * @param key Key to get an item's value for comparison
  * @returns Common values from both arrays
+ *
+ * @example
+ * ```typescript
+ * intersection(
+ *   [{id: 1}, {id: 2}, {id: 3}],
+ *   [{id: 2}, {id: 3}, {id: 4}],
+ *   'id',
+ * ); // => [{id: 2}, {id: 3}]
+ * ```
  */
 export function intersection<
 	First extends Record<string, unknown>,
@@ -28,12 +50,23 @@ export function intersection<
 
 /**
  * Get the common values between two arrays
+ *
  * @param first First array
  * @param second Second array
  * @returns Common values from both arrays
+ *
+ * @example
+ * ```typescript
+ * intersection(
+ *   [1, 2, 3],
+ *   [2, 3, 4],
+ * ); // => [2, 3]
+ * ```
  */
 export function intersection<First, Second>(first: First[], second: Second[]): First[];
 
 export function intersection(first: unknown[], second: unknown[], key?: unknown): unknown[] {
 	return compareSets(COMPARE_SETS_INTERSECTION, first, second, key);
 }
+
+// #endregion

package/src/array/last.ts

@@ -5,10 +5,20 @@ import type {PlainObject} from '../models';
 
 /**
  * Get the last items matching the given 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 Last item that matches the value, or `undefined` if no match is found
+ *
+ * @example
+ * ```typescript
+ * last(
+ *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
+ *   item => item.value,
+ *   10,
+ * ); // => {id: 3, value: 10}
+ * ```
  */
 export function last<Item, Callback extends (item: Item, index: number, array: Item[]) => unknown>(
 	array: Item[],
@@ -18,10 +28,20 @@ export function last<Item, Callback extends (item: Item, index: number, array: I
 
 /**
  * Get the first item matching the given value by key
+ *
  * @param array Array to search in
  * @param key Key to get an item's value for matching
  * @param value Value to match against
  * @returns Last item that matches the value, or `undefined` if no match is found
+ *
+ * @example
+ * ```typescript
+ * last(
+ *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
+ *   'value',
+ *   10,
+ * ); // => {id: 3, value: 10}
+ * ```
  */
 export function last<Item extends PlainObject, ItemKey extends keyof Item>(
 	array: Item[],
@@ -31,9 +51,18 @@ export function last<Item extends PlainObject, ItemKey extends keyof Item>(
 
 /**
  * Get the last item matching the filter
+ *
  * @param array Array to search in
  * @param filter Filter callback to match items
  * @returns Last item that matches the filter, or `undefined` if no match is found
+ *
+ * @example
+ * ```typescript
+ * last(
+ *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
+ *   item => item.value === 10,
+ * ); // => {id: 3, value: 10}
+ * ```
  */
 export function last<Item>(
 	array: Item[],
@@ -42,8 +71,14 @@ export function last<Item>(
 
 /**
  * Get the last item from an array
+ *
  * @param array Array to get from
- * @return Last item from the array, or `undefined` if the array is empty
+ * @returns Last item from the array, or `undefined` if the array is empty
+ *
+ * @example
+ * ```typescript
+ * last([1, 2, 3]); // => 3
+ * ```
  */
 export function last<Item>(array: Item[]): Item | undefined;
 
@@ -57,11 +92,22 @@ last.default = lastOrDefault;
  * Get the last item matching the given value
  *
  * Available as `lastOrDefault` and `last.default`
+ *
  * @param array Array to search in
  * @param defaultValue Default value to return if no match is found
  * @param callback Callback to get an item's value for matching
  * @param value Value to match against
  * @returns Last item that matches the value, or the default value if no match is found
+ *
+ * @example
+ * ```typescript
+ * lastOrDefault(
+ *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
+ *   {id: -1, value: 30},
+ *   item => item.value,
+ *   30,
+ * ); // => {id: -1, value: 30}
+ * ```
  */
 export function lastOrDefault<
 	Item,
@@ -72,11 +118,22 @@ export function lastOrDefault<
  * Get the last item matching the given value by key
  *
  * Available as `lastOrDefault` and `last.default`
+ *
  * @param array Array to search in
  * @param defaultValue Default value to return if no match is found
  * @param key Key to get an item's value for matching
  * @param value Value to match against
  * @returns Last item that matches the value, or the default value if no match is found
+ *
+ * @example
+ * ```typescript
+ * lastOrDefault(
+ *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
+ *   {id: -1, value: 30},
+ *   'value',
+ *   30,
+ * ); // => {id: -1, value: 30}
+ * ```
  */
 export function lastOrDefault<Item extends PlainObject, ItemKey extends keyof Item>(
 	array: Item[],
@@ -89,10 +146,20 @@ export function lastOrDefault<Item extends PlainObject, ItemKey extends keyof It
  * Get the last item matching the filter
  *
  * Available as `lastOrDefault` and `last.default`
+ *
  * @param array Array to search in
  * @param defaultValue Default value to return if no match is found
  * @param filter Filter callback to match items
  * @returns Last item that matches the filter, or the default value if no match is found
+ *
+ * @example
+ * ```typescript
+ * lastOrDefault(
+ *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
+ *   {id: -1, value: 30},
+ *   item => item.value === 30,
+ * ); // => {id: -1, value: 30}
+ * ```
  */
 export function lastOrDefault<Item>(
 	array: Item[],
@@ -104,9 +171,15 @@ export function lastOrDefault<Item>(
  * Get the last item from an array
  *
  * Available as `lastOrDefault` and `last.default`
+ *
  * @param array Array to get from
  * @param defaultValue Default value to return if the array is empty
- * @return Last item from the array, or the default value if the array is empty
+ * @returns Last item from the array, or the default value if the array is empty
+ *
+ * @example
+ * ```typescript
+ * lastOrDefault([], {id: -1, value: 30}); // => {id: -1, value: 30}
+ * ```
  */
 export function lastOrDefault<Item>(array: Item[], defaultValue: Item): Item;