@oscarpalmer/atoms 0.184.2 → 0.186.0

package/src/array/to-map.ts

@@ -43,10 +43,20 @@ function getMapValues(
  * Create a Map from an array of items using callbacks
  *
  * If multiple items have the same key, the latest item's value will be used
+ *
  * @param array Array to convert
  * @param key Callback to get an item's grouping key
  * @param value Callback to get an item's value
  * @returns Map of keyed values
+ *
+ * @example
+ * ```typescript
+ * toMap(
+ *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
+ *   item => item.value,
+ *   item => item.id,
+ * ); // => Map { 10 => 3, 20 => 2 }
+ * ```
  */
 export function toMap<
 	Item,
@@ -62,10 +72,20 @@ export function toMap<
  * Create a Map from an array of items using a callback and value
  *
  * If multiple items have the same key, the latest item's value will be used
+ *
  * @param array Array to convert
  * @param key Callback to get an item's grouping key
  * @param value Key to use for value
  * @returns Map of keyed values
+ *
+ * @example
+ * ```typescript
+ * toMap(
+ *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
+ *   item => item.value,
+ *   'id',
+ * ); // => Map { 10 => 3, 20 => 2 }
+ * ```
  */
 export function toMap<
 	Item extends PlainObject,
@@ -77,10 +97,20 @@ export function toMap<
  * Create a Map from an array of items using a key and callback
  *
  * If multiple items have the same key, the latest item's value will be used
+ *
  * @param array Array to convert
  * @param key Key to use for grouping
  * @param value Callback to get an item's value
  * @returns Map of keyed values
+ *
+ * @example
+ * ```typescript
+ * toMap(
+ *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
+ *   'value',
+ *   item => item.id,
+ * ); // => Map { 10 => 3, 20 => 2 }
+ * ```
  */
 export function toMap<
 	Item extends PlainObject,
@@ -92,10 +122,20 @@ export function toMap<
  * Create a Map from an array of items using a key and value
  *
  * If multiple items have the same key, the latest item's value will be used
+ *
  * @param array Array to convert
  * @param key Key to use for grouping
  * @param value Key to use for value
  * @returns Map of keyed values
+ *
+ * @example
+ * ```typescript
+ * toMap(
+ *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
+ *   'value',
+ *   'id',
+ * ); // => Map { 10 => 3, 20 => 2 }
+ * ```
  */
 export function toMap<
 	Item extends PlainObject,
@@ -107,9 +147,18 @@ export function toMap<
  * Create a Map from an array of items using a callback
  *
  * If multiple items have the same key, the latest item will be used
+ *
  * @param array Array to convert
  * @param callback Callback to get an item's grouping key
  * @returns Map of keyed items
+ *
+ * @example
+ * ```typescript
+ * toMap(
+ *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
+ *   item => item.value,
+ * ); // => Map { 10 => {id: 3, value: 10}, 20 => {id: 2, value: 20} }
+ * ```
  */
 export function toMap<Item, Callback extends (item: Item, index: number, array: Item[]) => Key>(
 	array: Item[],
@@ -120,9 +169,18 @@ export function toMap<Item, Callback extends (item: Item, index: number, array:
  * Create a Map from an array of items using a key
  *
  * If multiple items have the same key, the latest item will be used
+ *
  * @param array Array to convert
  * @param key Key to use for grouping
  * @returns Map of keyed items
+ *
+ * @example
+ * ```typescript
+ * toMap(
+ *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
+ *   'value',
+ * ); // => Map { 10 => {id: 3, value: 10}, 20 => {id: 2, value: 20} }
+ * ```
  */
 export function toMap<Item extends PlainObject, ItemKey extends keyof Item>(
 	array: Item[],
@@ -131,8 +189,16 @@ export function toMap<Item extends PlainObject, ItemKey extends keyof Item>(
 
 /**
  * Create a Map from an array of items _(using indices as keys)_
+ *
  * @param array Array to convert
  * @returns Map of indiced items
+ *
+ * @example
+ * ```typescript
+ * toMap(
+ *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
+ * ); // => Map { 0 => {id: 1, value: 10}, 1 => {id: 2, value: 20}, 2 => {id: 3, value: 10} }
+ * ```
  */
 export function toMap<Item>(array: Item[]): Map<number, Item>;
 
@@ -146,10 +212,20 @@ toMap.arrays = toMapArrays;
  * Create a Map from an array of items using callbacks, grouping values into arrays
  *
  * Available as `toMapArrays` and `toMap.arrays`
+ *
  * @param array Array to convert
  * @param key Callback to get an item's grouping key
  * @param value Callback to get an item's value
  * @returns Map of keyed arrays of values
+ *
+ * @example
+ * ```typescript
+ * toMapArrays(
+ *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
+ *   item => item.value,
+ *   item => item.id,
+ * ); // => Map { 10 => [1, 3], 20 => [2] }
+ * ```
  */
 export function toMapArrays<
 	Item,
@@ -165,10 +241,20 @@ export function toMapArrays<
  * Create a Map from an array of items using a callback and value, grouping values into arrays
  *
  * Available as `toMapArrays` and `toMap.arrays`
+ *
  * @param array Array to convert
  * @param key Callback to get an item's grouping key
  * @param value Key to use for value
  * @returns Map of keyed arrays of values
+ *
+ * @example
+ * ```typescript
+ * toMapArrays(
+ *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
+ *   item => item.value,
+ *   'id',
+ * ); // => Map { 10 => [1, 3], 20 => [2] }
+ * ```
  */
 export function toMapArrays<
 	Item extends PlainObject,
@@ -184,10 +270,20 @@ export function toMapArrays<
  * Create a Map from an array of items using a key and callback, grouping values into arrays
  *
  * Available as `toMapArrays` and `toMap.arrays`
+ *
  * @param array Array to convert
  * @param key Key to use for grouping
  * @param value Callback to get an item's value
  * @returns Map of keyed arrays of values
+ *
+ * @example
+ * ```typescript
+ * toMapArrays(
+ *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
+ *   'value',
+ *   item => item.id,
+ * ); // => Map { 10 => [1, 3], 20 => [2] }
+ * ```
  */
 export function toMapArrays<
 	Item extends PlainObject,
@@ -203,10 +299,20 @@ export function toMapArrays<
  * Create a Map from an array of items using a key and value, grouping values into arrays
  *
  * Available as `toMapArrays` and `toMap.arrays`
+ *
  * @param array Array to convert
  * @param key Key to use for grouping
  * @param value Key to use for value
  * @returns Map of keyed arrays of values
+ *
+ * @example
+ * ```typescript
+ * toMapArrays(
+ *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
+ *   'value',
+ *   'id',
+ * ); // => Map { 10 => [1, 3], 20 => [2] }
+ * ```
  */
 export function toMapArrays<
 	Item extends PlainObject,
@@ -218,9 +324,18 @@ export function toMapArrays<
  * Create a Map from an array of items using a callback, grouping items into arrays
  *
  * Available as `toMapArrays` and `toMap.arrays`
+ *
  * @param array Array to convert
  * @param callback Callback to get an item's grouping key
  * @returns Map of keyed arrays of items
+ *
+ * @example
+ * ```typescript
+ * toMapArrays(
+ *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
+ *   item => item.value,
+ * ); // => Map { 10 => [{id: 1, value: 10}, {id: 3, value: 10}], 20 => [{id: 2, value: 20}] }
+ * ```
  */
 export function toMapArrays<
 	Item,
@@ -231,9 +346,18 @@ export function toMapArrays<
  * Create a Map from an array of items using a key, grouping items into arrays
  *
  * Available as `toMapArrays` and `toMap.arrays`
+ *
  * @param array Array to convert
  * @param key Key to use for grouping
  * @returns Map of keyed arrays of items
+ *
+ * @example
+ * ```typescript
+ * toMapArrays(
+ *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
+ *   'value',
+ * ); // => Map { 10 => [{id: 1, value: 10}, {id: 3, value: 10}], 20 => [{id: 2, value: 20}] }
+ * ```
  */
 export function toMapArrays<Item extends PlainObject, ItemKey extends keyof Item>(
 	array: Item[],

package/src/array/to-record.ts

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

package/src/array/to-set.ts

@@ -5,9 +5,18 @@ import type {PlainObject} from '../models';
 
 /**
  * Create a Set from an array of items using a callback
+ *
  * @param array Array to convert
  * @param callback Callback to get an item's value
  * @returns Set of values
+ *
+ * @example
+ * ```typescript
+ * toSet(
+ *   [{id: 1}, {id: 2}, {id: 3}],
+ *   item => item.id,
+ * ); // => Set { 1, 2, 3 }
+ * ```
  */
 export function toSet<Item, Callback extends (item: Item, index: number, array: Item[]) => unknown>(
 	array: Item[],
@@ -16,9 +25,18 @@ export function toSet<Item, Callback extends (item: Item, index: number, array:
 
 /**
  * Create a Set from an array of items using a key
+ *
  * @param array Array to convert
  * @param key Key to use for value
  * @returns Set of values
+ *
+ * @example
+ * ```typescript
+ * toSet(
+ *   [{id: 1}, {id: 2}, {id: 3}],
+ *   'id',
+ * ); // => Set { 1, 2, 3 }
+ * ```
  */
 export function toSet<Item extends PlainObject, ItemKey extends keyof Item>(
 	array: Item[],
@@ -27,8 +45,14 @@ export function toSet<Item extends PlainObject, ItemKey extends keyof Item>(
 
 /**
  * Create a Set from an array of items
+ *
  * @param array Array to convert
  * @returns Set of items
+ *
+ * @example
+ * ```typescript
+ * toSet([1, 2, 3]); // => Set { 1, 2, 3 }
+ * ```
  */
 export function toSet<Item>(array: Item[]): Set<Item>;
 

package/src/array/toggle.ts

@@ -1,12 +1,26 @@
 import {updateInArray} from '../internal/array/update';
 import type {PlainObject} from '../models';
 
+// #region Functions
+
 /**
- * Toggle an item in an array: if the item exists, it will be removed; if it doesn't, it will be added
+ * Toggle an item in an array
+ *
+ * If the item exists, it will be removed; if it doesn't, it will be added
+ *
  * @param destination Array to toggle within
  * @param toggled Toggled items
  * @param callback Callback to find existing item
  * @returns Original array
+ *
+ * @example
+ * ```typescript
+ * toggle(
+ *   [{id: 1}, {id: 2}, {id: 3}],
+ *   [{id: 2}, {id: 4}],
+ *   item => item.id,
+ * ); // => [{id: 1}, {id: 3}, {id: 4}]
+ * ```
  */
 export function toggle<Item>(
 	destination: Item[],
@@ -15,11 +29,23 @@ export function toggle<Item>(
 ): Item[];
 
 /**
- * Toggle an item in an array: if the item exists, it will be removed; if it doesn't, it will be added
+ * Toggle an item in an array
+ *
+ * If the item exists, it will be removed; if it doesn't, it will be added
+ *
  * @param destination Array to toggle within
  * @param toggled Toggled items
  * @param key Key to find existing item
  * @returns Original array
+ *
+ * @example
+ * ```typescript
+ * toggle(
+ *   [{id: 1}, {id: 2}, {id: 3}],
+ *   [{id: 2}, {id: 4}],
+ *   'id',
+ * ); // => [{id: 1}, {id: 3}, {id: 4}]
+ * ```
  */
 export function toggle<Item extends PlainObject, ItemKey extends keyof Item>(
 	destination: Item[],
@@ -28,13 +54,26 @@ export function toggle<Item extends PlainObject, ItemKey extends keyof Item>(
 ): Item[];
 
 /**
- * Toggle an item in an array: if the item exists, it will be removed; if it doesn't, it will be added
+ * Toggle an item in an array
+ *
+ * If the item exists, it will be removed; if it doesn't, it will be added
+ *
  * @param destination Array to toggle within
  * @param toggled Toggled items
  * @returns Original array
+ *
+ * @example
+ * ```typescript
+ * toggle(
+ *   [1, 2, 3],
+ *   [2, 4],
+ * ); // => [1, 3, 4]
+ * ```
  */
 export function toggle<Item>(destination: Item[], toggled: Item[]): Item[];
 
 export function toggle(array: unknown[], values: unknown[], key?: unknown): unknown[] {
 	return updateInArray(array, values, key, false);
 }
+
+// #endregion

package/src/array/union.ts

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