@oscarpalmer/atoms 0.184.2 → 0.186.0

package/src/array/find.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
+ * find(
+ *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
+ *   item => item.value,
+ *   10,
+ * ); // => {id: 1, value: 10}
+ * ```
  */
 export function find<Item, Callback extends (item: Item, index: number, array: Item[]) => unknown>(
 	array: Item[],
@@ -18,10 +28,20 @@ export function find<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 First item that matches the value, or `undefined` if no match is found
+ *
+ * @example
+ * ```typescript
+ * find(
+ *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
+ *   'value',
+ *   10,
+ * ); // => {id: 1, value: 10}
+ * ```
  */
 export function find<Item extends PlainObject, ItemKey extends keyof Item>(
 	array: Item[],
@@ -31,9 +51,18 @@ export function find<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
+ * find(
+ *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
+ *   item => item.value === 10,
+ * ); // => {id: 1, value: 10}
+ * ```
  */
 export function find<Item>(
 	array: Item[],
@@ -42,9 +71,15 @@ export function find<Item>(
 
 /**
  * Get the first item matching the given value
+ *
  * @param array Array to search in
  * @param value Value to match against
  * @returns First item that matches the value, or `undefined` if no match is found
+ *
+ * @example
+ * ```typescript
+ * find([1, 2, 3, 2, 1], 1); // => 1
+ * ```
  */
 export function find<Item>(array: Item[], value: Item): Item | undefined;
 
@@ -58,10 +93,20 @@ find.last = findLast;
  * Get the last item matching the given value
  *
  * Available as `findLast` and `find.last`
+ *
  * @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
+ * findLast(
+ *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
+ *   item => item.value,
+ *   10,
+ * ); // => {id: 3, value: 10}
+ * ```
  */
 export function findLast<
 	Item,
@@ -72,10 +117,20 @@ export function findLast<
  * Get the last item matching the given value by key
  *
  * Available as `findLast` and `find.last`
+ *
  * @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
+ * findLast(
+ *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
+ *   'value',
+ *   10,
+ * ); // => {id: 3, value: 10}
+ * ```
  */
 export function findLast<Item extends PlainObject, ItemKey extends keyof Item>(
 	array: Item[],
@@ -87,9 +142,18 @@ export function findLast<Item extends PlainObject, ItemKey extends keyof Item>(
  * Get the last item matching the filter
  *
  * Available as `findLast` and `find.last`
+ *
  * @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
+ * findLast(
+ *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
+ *   item => item.value === 10,
+ * ); // => {id: 3, value: 10}
+ * ```
  */
 export function findLast<Item>(
 	array: Item[],
@@ -100,9 +164,15 @@ export function findLast<Item>(
  * Get the last item matching the given value
  *
  * Available as `findLast` and `find.last`
+ *
  * @param array Array to search in
  * @param value Value to match against
  * @returns Last item that matches the value, or `undefined` if no match is found
+ *
+ * @example
+ * ```typescript
+ * findLast([1, 2, 3, 2, 1], 1); // => 1
+ * ```
  */
 export function findLast<Item>(array: Item[], value: Item): Item | undefined;
 

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

@@ -1,24 +1,44 @@
+// #region Functions
+
 /**
  * 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[];
 
@@ -48,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,
@@ -66,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[];
 
@@ -87,3 +125,5 @@ export function times(length: number, value?: unknown): unknown[] {
 
 	return values;
 }
+
+// #endregion

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;