@oscarpalmer/atoms 0.185.0 → 0.186.0

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

@@ -4,11 +4,23 @@ 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[],
@@ -17,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[],
@@ -30,10 +54,21 @@ 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[];
 

package/src/array/union.ts

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

package/src/array/unique.ts

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

package/src/array/update.ts

@@ -2,11 +2,23 @@ import {updateInArray} from '../internal/array/update';
 import type {PlainObject} from '../models';
 
 /**
- * Update an item in an array: if the item exists, it will be updated; if it doesn't, it will be added
+ * Update an item in an array
+ *
+ * If the item exists, it will be updated; if it doesn't, it will be added
+ *
  * @param destination Array to update within
  * @param updated Updated items
  * @param callback Callback to find existing item
  * @returns Original array
+ *
+ * @example
+ * ```typescript
+ * update(
+ *   [{id: 1}, {id: 2}, {id: 3}],
+ *   [{id: 2, name: 'Updated'}, {id: 4, name: 'New'}],
+ *   item => item.id,
+ * ); // => [{id: 1}, {id: 2, name: 'Updated'}, {id: 3}, {id: 4, name: 'New'}]
+ * ```
  */
 export function update<Item>(
 	destination: Item[],
@@ -15,11 +27,23 @@ export function update<Item>(
 ): Item[];
 
 /**
- * Update an item in an array: if the item exists, it will be updated; if it doesn't, it will be added
+ * Update an item in an array
+ *
+ * If the item exists, it will be updated; if it doesn't, it will be added
+ *
  * @param destination Array to update within
  * @param updated Updated items
  * @param key Key to find existing item
  * @returns Original array
+ *
+ * @example
+ * ```typescript
+ * update(
+ *   [{id: 1}, {id: 2}, {id: 3}],
+ *   [{id: 2, name: 'Updated'}, {id: 4, name: 'New'}],
+ *   'id',
+ * ); // => [{id: 1}, {id: 2, name: 'Updated'}, {id: 3}, {id: 4, name: 'New'}]
+ * ```
  */
 export function update<Item extends PlainObject, ItemKey extends keyof Item>(
 	destination: Item[],
@@ -28,10 +52,21 @@ export function update<Item extends PlainObject, ItemKey extends keyof Item>(
 ): Item[];
 
 /**
- * Update an item in an array: if the item exists, it will be updated; if it doesn't, it will be added
+ * Update an item in an array
+ *
+ * If the item exists, it will be updated; if it doesn't, it will be added
+ *
  * @param destination Array to update within
  * @param updated Updated items
  * @returns Original array
+ *
+ * @example
+ * ```typescript
+ * update(
+ *   [1, 2, 3],
+ *   [2, 4],
+ * ); // => [1, 2, 3, 4]
+ * ```
  */
 export function update<Item>(destination: Item[], updated: Item[]): Item[];
 

package/src/internal/array/chunk.ts

@@ -2,9 +2,15 @@
 
 /**
  * Chunk an array into smaller arrays
+ *
  * @param array Array to chunk
  * @param size Size of each chunk _(minimum is `1`, maximum is `5000`; defaults to `5000`)_
  * @returns Array of arrays
+ *
+ * @example
+ * ```typescript
+ * chunk([1, 2, 3, 4, 5], 2); // => [[1, 2], [3, 4], [5]]
+ * ```
  */
 export function chunk<Item>(array: Item[], size?: number): Item[][] {
 	if (!Array.isArray(array)) {

package/src/internal/array/compact.ts

@@ -2,9 +2,15 @@
 
 /**
  * Compact an array _(removing all false-y values)_
+ *
  * @param array Array to compact
  * @param strict True to remove all false-y values
  * @returns Compacted array
+ *
+ * @example
+ * ```typescript
+ * compact([0, 1, '', 'hello', false, true, null, undefined]); // => [1, 'hello', true]
+ * ```
  */
 export function compact<Item>(
 	array: Item[],
@@ -13,8 +19,14 @@ export function compact<Item>(
 
 /**
  * Compact an array _(removing all `null` and `undefined` values)_
+ *
  * @param array Array to compact
  * @returns Compacted array
+ *
+ * @example
+ * ```typescript
+ * compact([0, 1, '', 'hello', false, true, null, undefined]); // => [0, 1, '', 'hello', false, true]
+ * ```
  */
 export function compact<Item>(array: Item[]): Exclude<Item, null | undefined>[];