@oscarpalmer/atoms 0.185.0 → 0.186.1

package/dist/array/swap.d.mts

@@ -5,62 +5,166 @@ import { PlainObject } from "../models.mjs";
  * Swap two smaller arrays within a larger array
  *
  * If either of the smaller arrays are not present in the larger array, or if they overlap, the larger array will be returned unchanged
+ *
  * @param array Array of items to swap
  * @param first First array
  * @param second Second array
- * @param key Key to get an item's value for matching
+ * @param callback Callback to get an item's value for matching
  * @returns Original array with items swapped _(or unchanged if unable to swap)_
+ *
+ * @example
+ * ```typescript
+ * swap(
+ *   [
+ *     {id: 1, name: 'Alice'},
+ *     {id: 2, name: 'Bob'},
+ *     {id: 3, name: 'Charlie'},
+ *   ],
+ *   [
+ *     {id: 2, name: 'Bob'},
+ *   ],
+ *   [
+ *     {id: 3, name: 'Charlie'},
+ *   ],
+ *   item => item.id,
+ * ); // => [
+ *    //   {id: 1, name: 'Alice'},
+ *    //   {id: 3, name: 'Charlie'},
+ *    //   {id: 2, name: 'Bob'},
+ *    // ]
+ * ```
  */
-declare function swap<Item extends PlainObject, ItemKey extends keyof Item>(array: Item[], first: Item[], second: Item[], key: ItemKey): Item[];
+declare function swap<Item>(array: Item[], first: Item[], second: Item[], callback: (item: Item, index: number, array: Item[]) => unknown): Item[];
 /**
  * Swap two smaller arrays within a larger array
  *
  * If either of the smaller arrays are not present in the larger array, or if they overlap, the larger array will be returned unchanged
+ *
  * @param array Array of items to swap
  * @param first First array
  * @param second Second array
- * @param callback Callback to get an item's value for matching
+ * @param key Key to get an item's value for matching
  * @returns Original array with items swapped _(or unchanged if unable to swap)_
+ *
+ * @example
+ * ```typescript
+ * swap(
+ *   [
+ *     {id: 1, name: 'Alice'},
+ *     {id: 2, name: 'Bob'},
+ *     {id: 3, name: 'Charlie'},
+ *   ],
+ *   [
+ *     {id: 2, name: 'Bob'},
+ *   ],
+ *   [
+ *     {id: 3, name: 'Charlie'},
+ *   ],
+ *   'id',
+ * ); // => [
+ *    //   {id: 1, name: 'Alice'},
+ *    //   {id: 3, name: 'Charlie'},
+ *    //   {id: 2, name: 'Bob'},
+ *    // ]
+ * ```
  */
-declare function swap<Item>(array: Item[], first: Item[], second: Item[], callback: (item: Item, index: number, array: Item[]) => unknown): Item[];
+declare function swap<Item extends PlainObject, ItemKey extends keyof Item>(array: Item[], first: Item[], second: Item[], key: ItemKey): Item[];
 /**
  * Swap two smaller arrays within a larger array
  *
  * If either of the smaller arrays are not present in the larger array, or if they overlap, the larger array will be returned unchanged
+ *
  * @param array Array of items to swap
  * @param first First array
  * @param second Second array
  * @returns Original array with items swapped _(or unchanged if unable to swap)_
+ *
+ * @example
+ * ```typescript
+ * swap(
+ *   [1, 2, 3, 4, 5, 6],
+ *   [1, 2],
+ *   [5, 6],
+ * ); // => [5, 6, 3, 4, 1, 2]
+ * ```
  */
 declare function swap<Item>(array: Item[], first: Item[], second: Item[]): Item[];
 /**
  * Swap two indiced items in an array
  *
  * If either of the items are not present in the array, the array will be returned unchanged
+ *
  * @param array Array of items to swap
  * @param first First item
  * @param second Second item
- * @param key Key to get an item's value for matching
+ * @param callback Callback to get an item's value for matching
  * @returns Original array with items swapped _(or unchanged if unable to swap)_
+ *
+ * @example
+ * ```typescript
+ * swap(
+ *   [
+ *     {id: 1, name: 'Alice'},
+ *     {id: 2, name: 'Bob'},
+ *     {id: 3, name: 'Charlie'},
+ *   ],
+ *   {id: 2, name: 'Bob'},
+ *   {id: 3, name: 'Charlie'},
+ *   item => item.id,
+ * ); // => [
+ *    //   {id: 1, name: 'Alice'},
+ *    //   {id: 3, name: 'Charlie'},
+ *    //   {id: 2, name: 'Bob'},
+ *    // ]
+ * ```
  */
-declare function swap<Item extends PlainObject, ItemKey extends keyof Item>(array: Item[], first: Item, second: Item, key: ItemKey): Item[];
+declare function swap<Item>(array: Item[], first: Item, second: Item, callback: (item: Item, index: number, array: Item[]) => unknown): Item[];
 /**
  * Swap two indiced items in an array
  *
  * If either of the items are not present in the array, the array will be returned unchanged
+ *
  * @param array Array of items to swap
  * @param first First item
  * @param second Second item
- * @param callback Callback to get an item's value for matching
+ * @param key Key to get an item's value for matching
  * @returns Original array with items swapped _(or unchanged if unable to swap)_
+ *
+ * @example
+ * ```typescript
+ * swap(
+ *   [
+ *     {id: 1, name: 'Alice'},
+ *     {id: 2, name: 'Bob'},
+ *     {id: 3, name: 'Charlie'},
+ *   ],
+ *   {id: 2, name: 'Bob'},
+ *   {id: 3, name: 'Charlie'},
+ *   'id',
+ * ); // => [
+ *    //   {id: 1, name: 'Alice'},
+ *    //   {id: 3, name: 'Charlie'},
+ *    //   {id: 2, name: 'Bob'},
+ *    // ]
+ * ```
  */
-declare function swap<Item>(array: Item[], first: Item, second: Item, callback: (item: Item, index: number, array: Item[]) => unknown): Item[];
+declare function swap<Item extends PlainObject, ItemKey extends keyof Item>(array: Item[], first: Item, second: Item, key: ItemKey): Item[];
 /**
  * Swap two indiced items in an array
+ *
  * @param array Array of items to swap
  * @param first First item
  * @param second Second item
  * @returns Original array with items swapped _(or unchanged if unable to swap)_
+ *
+ * @example
+ * ```typescript
+ * swap(
+ *   [1, 2, 3, 4, 5, 6],
+ *   2,
+ *   5,
+ * ); // => [1, 5, 3, 4, 2, 6]
+ * ```
  */
 declare function swap<Item>(array: Item[], first: Item, second: Item): Item[];
 declare namespace swap {
@@ -72,6 +176,7 @@ declare namespace swap {
  * If either index is out of bounds, the array will be returned unchanged
  *
  * Available as `swapIndices` and `swap.indices`
+ *
  * @param array Array of items to swap
  * @param first First index _(can be negative to count from the end)_
  * @param second Second index _(can be negative to count from the end)_

package/dist/array/swap.mjs

@@ -34,6 +34,7 @@ function swapArrays(array, from, to, key) {
 * If either index is out of bounds, the array will be returned unchanged
 *
 * Available as `swapIndices` and `swap.indices`
+*
 * @param array Array of items to swap
 * @param first First index _(can be negative to count from the end)_
 * @param second Second index _(can be negative to count from the end)_

package/dist/array/to-map.d.mts

@@ -5,64 +5,130 @@ import { Key, PlainObject } from "../models.mjs";
  * 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 }
+ * ```
  */
 declare function toMap<Item, KeyCallback extends (item: Item, index: number, array: Item[]) => Key, ValueCallback extends (item: Item, index: number, array: Item[]) => unknown>(array: Item[], key: KeyCallback, value: ValueCallback): Map<ReturnType<KeyCallback>, ReturnType<ValueCallback>>;
 /**
  * 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 }
+ * ```
  */
 declare function toMap<Item extends PlainObject, KeyCallback extends (item: Item, index: number, array: Item[]) => Key, ItemValue extends keyof Item>(array: Item[], key: KeyCallback, value: ItemValue): Map<ReturnType<KeyCallback>, Item[ItemValue]>;
 /**
  * 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 }
+ * ```
  */
 declare function toMap<Item extends PlainObject, ItemKey extends keyof Item, ValueCallback extends (item: Item, index: number, array: Item[]) => unknown>(array: Item[], key: ItemKey, value: ValueCallback): Map<Item[ItemKey], ReturnType<ValueCallback>>;
 /**
  * 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 }
+ * ```
  */
 declare function toMap<Item extends PlainObject, ItemKey extends keyof Item, ItemValue extends keyof Item>(array: Item[], key: ItemKey, value: ItemValue): Map<Item[ItemKey], Item[ItemValue]>;
 /**
  * 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} }
+ * ```
  */
 declare function toMap<Item, Callback extends (item: Item, index: number, array: Item[]) => Key>(array: Item[], callback: Callback): Map<ReturnType<Callback>, Item>;
 /**
  * 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} }
+ * ```
  */
 declare function toMap<Item extends PlainObject, ItemKey extends keyof Item>(array: Item[], key: ItemKey): Map<Item[ItemKey], 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} }
+ * ```
  */
 declare function toMap<Item>(array: Item[]): Map<number, Item>;
 declare namespace toMap {
@@ -72,58 +138,116 @@ declare namespace toMap {
  * 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] }
+ * ```
  */
 declare function toMapArrays<Item, KeyCallback extends (item: Item, index: number, array: Item[]) => Key, ValueCallback extends (item: Item, index: number, array: Item[]) => unknown>(array: Item[], key: KeyCallback, value: ValueCallback): Map<ReturnType<KeyCallback>, ReturnType<ValueCallback>[]>;
 /**
  * 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] }
+ * ```
  */
 declare function toMapArrays<Item extends PlainObject, KeyCallback extends (item: Item, index: number, array: Item[]) => Key, ItemValue extends keyof Item>(array: Item[], key: KeyCallback, value: ItemValue): Map<ReturnType<KeyCallback>, Item[ItemValue][]>;
 /**
  * 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] }
+ * ```
  */
 declare function toMapArrays<Item extends PlainObject, ItemKey extends keyof Item, ValueCallback extends (item: Item, index: number, array: Item[]) => unknown>(array: Item[], key: ItemKey, value: ValueCallback): Map<Item[ItemKey], ReturnType<ValueCallback>[]>;
 /**
  * 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] }
+ * ```
  */
 declare function toMapArrays<Item extends PlainObject, ItemKey extends keyof Item, ItemValue extends keyof Item>(array: Item[], key: ItemKey, value: ItemValue): Map<Item[ItemKey], Item[ItemValue][]>;
 /**
  * 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}] }
+ * ```
  */
 declare function toMapArrays<Item, Callback extends (item: Item, index: number, array: Item[]) => Key>(array: Item[], callback: Callback): Map<ReturnType<Callback>, Item[]>;
 /**
  * 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}] }
+ * ```
  */
 declare function toMapArrays<Item extends PlainObject, ItemKey extends keyof Item>(array: Item[], key: ItemKey): Map<Item[ItemKey], Item[]>;
 //#endregion

package/dist/array/to-record.d.mts

@@ -5,64 +5,130 @@ import { Key, KeyedValue, PlainObject, Simplify } from "../models.mjs";
  * 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 }
+ * ```
  */
 declare function toRecord<Item, KeyCallback extends (item: Item, index: number, array: Item[]) => Key, ValueCallback extends (item: Item, index: number, array: Item[]) => unknown>(array: Item[], key: KeyCallback, value: ValueCallback): Record<ReturnType<KeyCallback>, ReturnType<ValueCallback>>;
 /**
  * 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 }
+ * ```
  */
 declare function toRecord<Item extends PlainObject, Callback extends (item: Item, index: number, array: Item[]) => Key, ItemValue extends keyof Item>(array: Item[], callback: Callback, value: ItemValue): Record<ReturnType<Callback>, Item[ItemValue]>;
 /**
  * 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 }
+ * ```
  */
 declare function toRecord<Item extends PlainObject, ItemKey extends keyof Item, Callback extends (item: Item, index: number, array: Item[]) => unknown>(array: Item[], key: ItemKey, callback: Callback): Simplify<Record<KeyedValue<Item, ItemKey>, ReturnType<Callback>>>;
 /**
  * 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 }
+ * ```
  */
 declare function toRecord<Item extends PlainObject, ItemKey extends keyof Item, ItemValue extends keyof Item>(array: Item[], key: ItemKey, value: ItemValue): Simplify<Record<KeyedValue<Item, ItemKey>, Item[ItemValue]>>;
 /**
  * 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} }
+ * ```
  */
 declare function toRecord<Item, Callback extends (item: Item, index: number, array: Item[]) => Key>(array: Item[], callback: Callback): Record<ReturnType<Callback>, Item>;
 /**
  * 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} }
+ * ```
  */
 declare function toRecord<Item extends PlainObject, ItemKey extends keyof Item>(array: Item[], key: ItemKey): Simplify<Record<KeyedValue<Item, ItemKey>, 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} }
+ * ```
  */
 declare function toRecord<Item>(array: Item[]): Record<number, Item>;
 declare namespace toRecord {
@@ -72,58 +138,116 @@ declare namespace toRecord {
  * 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] }
+ * ```
  */
 declare function toRecordArrays<Item, KeyCallback extends (item: Item, index: number, array: Item[]) => Key, ValueCallback extends (item: Item, index: number, array: Item[]) => unknown>(array: Item[], key: KeyCallback, value: ValueCallback): Record<ReturnType<KeyCallback>, ReturnType<ValueCallback>[]>;
 /**
  * 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] }
+ * ```
  */
 declare function toRecordArrays<Item extends PlainObject, Callback extends (item: Item, index: number, array: Item[]) => Key, ItemValue extends keyof Item>(array: Item[], callback: Callback, value: ItemValue): Record<ReturnType<Callback>, Item[ItemValue][]>;
 /**
  * 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] }
+ * ```
  */
 declare function toRecordArrays<Item extends PlainObject, ItemKey extends keyof Item, Callback extends (item: Item, index: number, array: Item[]) => unknown>(array: Item[], key: ItemKey, callback: Callback): Simplify<Record<KeyedValue<Item, ItemKey>, ReturnType<Callback>[]>>;
 /**
  * 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] }
+ * ```
  */
 declare function toRecordArrays<Item extends PlainObject, ItemKey extends keyof Item, ItemValue extends keyof Item>(array: Item[], key: ItemKey, value: ItemValue): Simplify<Record<KeyedValue<Item, ItemKey>, Item[ItemValue][]>>;
 /**
  * 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}] }
+ * ```
  */
 declare function toRecordArrays<Item, Callback extends (item: Item, index: number, array: Item[]) => Key>(array: Item[], callback: Callback): Record<ReturnType<Callback>, Item[]>;
 /**
  * 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}] }
+ * ```
  */
 declare function toRecordArrays<Item extends PlainObject, ItemKey extends keyof Item>(array: Item[], key: ItemKey): Simplify<Record<KeyedValue<Item, ItemKey>, Item[]>>;
 //#endregion