@oscarpalmer/atoms 0.185.0 → 0.186.0

package/src/array/first.ts

@@ -5,10 +5,20 @@ import type {PlainObject} from '../models';
 
 /**
  * Get the first item 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 First item that matches the value, or `undefined` if no match is found
+ *
+ * @example
+ * ```typescript
+ * first(
+ *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
+ *   item => item.value,
+ *   10,
+ * ); // => {id: 1, value: 10}
+ * ```
  */
 export function first<Item, Callback extends (item: Item, index: number, array: Item[]) => unknown>(
 	array: Item[],
@@ -18,10 +28,20 @@ export function first<Item, Callback extends (item: Item, index: number, array:
 
 /**
  * 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 First item that matches the value, or `undefined` if no match is found
+ *
+ * @example
+ * ```typescript
+ * first(
+ *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
+ *   'value',
+ *   10,
+ * ); // => {id: 1, value: 10}
+ * ```
  */
 export function first<Item extends PlainObject, ItemKey extends keyof Item>(
 	array: Item[],
@@ -31,9 +51,18 @@ export function first<Item extends PlainObject, ItemKey extends keyof Item>(
 
 /**
  * Get the first item matching the filter
+ *
  * @param array Array to search in
  * @param filter Filter callback to match items
  * @returns First item that matches the filter, or `undefined` if no match is found
+ *
+ * @example
+ * ```typescript
+ * first(
+ *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
+ *   item => item.value === 10,
+ * ); // => {id: 1, value: 10}
+ * ```
  */
 export function first<Item>(
 	array: Item[],
@@ -42,8 +71,16 @@ export function first<Item>(
 
 /**
  * Get the first item from an array
+ *
  * @param array Array to get from
- * @return First item from the array, or `undefined` if the array is empty
+ * @returns First item from the array, or `undefined` if the array is empty
+ *
+ * @example
+ * ```typescript
+ * first(
+ *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
+ * ); // => {id: 1, value: 10}
+ * ```
  */
 export function first<Item>(array: Item[]): Item | undefined;
 
@@ -57,11 +94,22 @@ first.default = firstOrDefault;
  * Get the first item matching the given value, or a default value if no match is found
  *
  * Available as `firstOrDefault` and `first.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 First item that matches the value, or the default value if no match is found
+ *
+ * @example
+ * ```typescript
+ * firstOrDefault(
+ *   [{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 firstOrDefault<
 	Item,
@@ -72,13 +120,23 @@ export function firstOrDefault<
  * Get the first item matching the given value by key, or a default value if no match is found
  *
  * Available as `firstOrDefault` and `first.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 First item that matches the value, or the default value if no match is found
+ *
+ * @example
+ * ```typescript
+ * firstOrDefault(
+ *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
+ *   {id: -1, value: 30},
+ *   'value',
+ *   30,
+ * ); // => {id: -1, value: 30}
+ * ```
  */
-
 export function firstOrDefault<Item extends PlainObject, ItemKey extends keyof Item>(
 	array: Item[],
 	defaultValue: Item,
@@ -90,10 +148,20 @@ export function firstOrDefault<Item extends PlainObject, ItemKey extends keyof I
  * Get the first item matching the filter, or a default value if no match is found
  *
  * Available as `firstOrDefault` and `first.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 First item that matches the filter, or the default value if no match is found
+ *
+ * @example
+ * ```typescript
+ * firstOrDefault(
+ *   [{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 firstOrDefault<Item>(
 	array: Item[],
@@ -105,9 +173,15 @@ export function firstOrDefault<Item>(
  * Get the first item from an array, or a default value if the array is empty
  *
  * Available as `firstOrDefault` and `first.default`
+ *
  * @param array Array to get from
  * @param defaultValue Default value to return if the array is empty
- * @return First item from the array, or the default value if the array is empty
+ * @returns First item from the array, or the default value if the array is empty
+ *
+ * @example
+ * ```typescript
+ * firstOrDefault([], {id: -1, value: 30}); // => {id: -1, value: 30}
+ * ```
  */
 export function firstOrDefault<Item>(array: Item[], defaultValue: Item): Item;
 

package/src/array/flatten.ts

@@ -4,8 +4,14 @@ import type {NestedArray} from '../models';
 
 /**
  * Flatten an array _(using native `flat` and maximum depth)_
+ *
  * @param array Array to flatten
  * @returns Flattened array
+ *
+ * @example
+ * ```typescript
+ * flatten([1, [2, [3, 4], 5], 6]); // => [1, 2, 3, 4, 5, 6]
+ * ```
  */
 export function flatten<Item>(array: Item[]): NestedArray<Item>[] {
 	return (Array.isArray(array) ? array.flat(Number.POSITIVE_INFINITY) : []) as NestedArray<Item>[];

package/src/array/from.ts

@@ -2,25 +2,43 @@
 
 /**
  * Get an array with a specified length, filled with indices
+ *
  * @param length Length of the array
  * @returns Array of indices
+ *
+ * @example
+ * ```typescript
+ * range(5); // => [0, 1, 2, 3, 4]
+ * ```
  */
 export function range(length: number): number[];
 
 /**
  * Get an array of numbers in a specified range
+ *
  * @param start Starting number _(inclusive)_
  * @param end Ending number _(exclusive)_
  * @returns Array of numbers in range
+ *
+ * @example
+ * ```typescript
+ * range(2, 5); // => [2, 3, 4]
+ * ```
  */
 export function range(start: number, end: number): number[];
 
 /**
  * Get an array of numbers in a specified range with a specified step
+ *
  * @param start Starting number _(inclusive)_
  * @param end Ending number _(exclusive)_
  * @param step Step between numbers
  * @returns Array of numbers in range
+ *
+ * @example
+ * ```typescript
+ * range(0, 10, 2); // => [0, 2, 4, 6, 8]
+ * ```
  */
 export function range(start: number, end: number, step: number): number[];
 
@@ -50,16 +68,28 @@ export function range(first: number, second?: number, third?: number): number[]
 
 /**
  * Get an array with a specified length, filled with indices
+ *
  * @param length Length of the array
  * @returns Array of indices
+ *
+ * @example
+ * ```typescript
+ * times(5); // => [0, 1, 2, 3, 4]
+ * ```
  */
 export function times(length: number): number[];
 
 /**
  * Get an array with a specified length, filled by values from a callback
+ *
  * @param length Length of the array
  * @param callback Callback function to generate values
  * @returns Array of values generated by the callback
+ *
+ * @example
+ * ```typescript
+ * times(5, index => index * 2); // => [0, 2, 4, 6, 8]
+ * ```
  */
 export function times<Callback extends (index: number) => unknown>(
 	length: number,
@@ -68,9 +98,15 @@ export function times<Callback extends (index: number) => unknown>(
 
 /**
  * Get an array with a specified length, filled with a specified value
+ *
  * @param length Length of the array
  * @param value Value to fill the array with
  * @returns Array filled with the specified value
+ *
+ * @example
+ * ```typescript
+ * times(5, 'a'); // => ['a', 'a', 'a', 'a', 'a']
+ * ```
  */
 export function times<Value>(length: number, value: Value): Value[];
 

package/src/array/get.ts

@@ -5,8 +5,15 @@ import type {NumericalKeys, PlainObject} from '../models';
 
 /**
  * Get an array from an object, where only values with numerical keys will be included
+ *
  * @param value Object to convert to an array
  * @returns Array holding the values of the object's numerical keys
+ *
+ * @example
+ * ```typescript
+ * getArray({0: 'a', 1: 'b', 2: 'c', d: 'd'}, true); // => ['a', 'b', 'c']
+ * getArray({a: 'a', b: 'b', c: 'c', d: 'd'}, true); // => []
+ * ```
  */
 export function getArray<Value extends PlainObject>(
 	value: Value,
@@ -15,32 +22,31 @@ export function getArray<Value extends PlainObject>(
 
 /**
  * Get an array from an object
+ *
  * @param value Object to convert to an array
  * @returns Array holding the values of the object
+ *
+ * @example
+ * ```typescript
+ * getArray({0: 'a', 1: 'b', 2: 'c', d: 'd'}); // => ['a', 'b', 'c', 'd']
+ * getArray({a: 'a', b: 'b', c: 'c', d: 'd'}); // => ['a', 'b', 'c', 'd']
+ * ```
  */
 export function getArray<Value extends PlainObject>(value: Value): Value[keyof Value][];
 
 /**
- * Get an array
+ * Get an array from a value
+ *
  * @param value Original array
  * @returns Original array
+ *
+ * @example
+ * ```typescript
+ * getArray(123); // => [123]
+ * ```
  */
 export function getArray<Item>(value: Item[]): Item[];
 
-/**
- * Get an array from a value
- * @param value Value to convert to an array
- * @returns Array holding the value
- */
-export function getArray<Item>(value: Item): Item[];
-
-/**
- * Get an array from an unknown value
- * @param value Value to convert to an array
- * @returns Array of value
- */
-export function getArray(value: unknown): unknown[];
-
 export function getArray(value: unknown, indiced?: unknown): unknown[] {
 	if (Array.isArray(value)) {
 		return value;

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/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

@@ -4,10 +4,20 @@ import {COMPARE_SETS_INTERSECTION, compareSets} from '../internal/array/sets';
 
 /**
  * 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[],
@@ -17,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>,
@@ -30,9 +50,18 @@ 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[];