@oscarpalmer/atoms 0.201.0 → 0.202.0

package/dist/array/group-by.d.mts

@@ -1,33 +1,13 @@
-import { Key, KeyedValue, PlainObject, Simplify } from "../models.mjs";
+import { Key, KeyOrCallback, KeyOrCallbackKey, KeyOrCallbackValue, Simplify } from "../models.mjs";
 //#region src/array/group-by.d.ts
 /**
- * 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}}
- * ```
- */
-declare function groupBy<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): Simplify<Record<ReturnType<KeyCallback>, ReturnType<ValueCallback>>>;
-/**
- * Create a record from an array of items using a specific key and value
+ * Create a record from an array of items using a specific key
  *
  * 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
+ * @param key Callback or key to use for grouping
+ * @param value Callback or key to use for value, defaulting to the item itself
  * @returns Record of keyed values
  *
  * @example
@@ -35,58 +15,18 @@ declare function groupBy<Item, KeyCallback extends (item: Item, index: number, a
  * groupBy(
  *   [{id: 1, value: 10}, {id: 2, value: 20}, {id: 3, value: 10}],
  *   item => item.value,
- *   'id'
- * ); // => {10: 3, 20: 2}
- * ```
- */
-declare function groupBy<Item extends PlainObject, KeyCallback extends (item: Item, index: number, array: Item[]) => Key, ItemValue extends keyof Item>(array: Item[], key: KeyCallback, value: ItemValue): Record<ReturnType<KeyCallback>, Item[ItemValue]>;
-/**
- * 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}}
  * ```
  */
-declare function groupBy<Item extends PlainObject, ItemKey extends keyof Item, ValueCallback extends (item: Item, index: number, array: Item[]) => unknown>(array: Item[], key: ItemKey, value: ValueCallback): Simplify<Record<KeyedValue<Item, ItemKey>, ReturnType<ValueCallback>>>;
-/**
- * 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}
- * ```
- */
-declare function groupBy<Item extends PlainObject, ItemKey extends keyof Item, ItemValue extends keyof Item>(array: Item[], key: ItemKey, value: ItemValue): Simplify<Record<KeyedValue<Item, ItemKey>, Item[ItemValue]>>;
+declare function groupBy<Item, KeyArg extends KeyOrCallback<Item, Key>, ValueArg extends KeyOrCallback<Item>>(array: Item[], key: KeyArg, value: ValueArg): Simplify<Record<KeyOrCallbackKey<Item, KeyArg>, KeyOrCallbackValue<Item, ValueArg>>>;
 /**
  * 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
+ * @param key Callback or key to use for grouping
  * @returns Record of keyed items
  *
  * @example
@@ -97,25 +37,7 @@ declare function groupBy<Item extends PlainObject, ItemKey extends keyof Item, I
  * ); // => {10: {id: 3, value: 10}, 20: {id: 2, value: 20}}
  * ```
  */
-declare function groupBy<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 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}}
- * ```
- */
-declare function groupBy<Item extends PlainObject, ItemKey extends keyof Item>(array: Item[], key: ItemKey): Simplify<Record<KeyedValue<Item, ItemKey>, Item>>;
+declare function groupBy<Item, KeyArg extends KeyOrCallback<Item, Key>>(array: Item[], key: KeyArg): Simplify<Record<KeyOrCallbackKey<Item, KeyArg>, Item>>;
 /**
  * Create a record from an array of items _(using indices as keys)_
  *
@@ -134,13 +56,13 @@ declare namespace groupBy {
   var arrays: typeof groupArraysBy;
 }
 /**
- * Create a record from an array of items using a specific key and value, grouping values into arrays
+ * Create a record from an array of items using a specific key, 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
+ * @param key Callback or key to use for grouping
+ * @param value Callback or key to use for value, defaulting to the item itself
  * @returns Record of keyed values
  *
  * @example
@@ -155,83 +77,14 @@ declare namespace groupBy {
  *    // }
  * ```
  */
-declare function groupArraysBy<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>, Array<ReturnType<ValueCallback>>>;
-/**
- * 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],
- *    // }
- * ```
- */
-declare function groupArraysBy<Item extends PlainObject, KeyCallback extends (item: Item, index: number, array: Item[]) => Key, ItemValue extends keyof Item>(array: Item[], key: KeyCallback, value: ItemValue): Record<ReturnType<KeyCallback>, Item[ItemValue][]>;
-/**
- * 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}],
- *    // }
- * ```
- */
-declare function groupArraysBy<Item extends PlainObject, ItemKey extends keyof Item, ValueCallback extends (item: Item, index: number, array: Item[]) => unknown>(array: Item[], key: ItemKey, value: ValueCallback): Simplify<Record<KeyedValue<Item, ItemKey>, Array<ReturnType<ValueCallback>>>>;
-/**
- * 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],
- *    // }
- * ```
- */
-declare function groupArraysBy<Item extends PlainObject, ItemKey extends keyof Item, ItemValue extends keyof Item>(array: Item[], key: ItemKey, value: ItemValue): Simplify<Record<KeyedValue<Item, ItemKey>, Item[ItemValue][]>>;
+declare function groupArraysBy<Item, KeyArg extends KeyOrCallback<Item, Key>, ValueArg extends KeyOrCallback<Item>>(array: Item[], key: KeyArg, value: ValueArg): Simplify<Record<KeyOrCallbackKey<Item, KeyArg>, Array<KeyOrCallbackValue<Item, ValueArg>>>>;
 /**
  * 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
+ * @param key Callback or key to use for grouping
  * @returns Record of keyed items
  *
  * @example
@@ -245,27 +98,6 @@ declare function groupArraysBy<Item extends PlainObject, ItemKey extends keyof I
  *    // }
  * ```
  */
-declare function groupArraysBy<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 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}],
- *    // }
- * ```
- */
-declare function groupArraysBy<Item extends PlainObject, ItemKey extends keyof Item>(array: Item[], key: ItemKey): Simplify<Record<KeyedValue<Item, ItemKey>, Item[]>>;
+declare function groupArraysBy<Item, KeyArg extends KeyOrCallback<Item, Key>>(array: Item[], key: KeyArg): Simplify<Record<KeyOrCallbackKey<Item, KeyArg>, Item[]>>;
 //#endregion
 export { groupArraysBy, groupBy };

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

@@ -1,13 +1,13 @@
-import { Key, PlainObject } from "../models.mjs";
+import { Key, KeyOrCallback, KeyOrCallbackKey, KeyOrCallbackValue } from "../models.mjs";
 //#region src/array/to-map.d.ts
 /**
- * Create a _Map_ from an array of items using callbacks
+ * Create a _Map_ from an array of items using a specific key
  *
  * 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
+ * @param key Callback or key to use for grouping
+ * @param value Callback or key to use for value, defaulting to the item itself
  * @returns _Map_ of keyed values
  *
  * @example
@@ -19,74 +19,14 @@ import { Key, PlainObject } from "../models.mjs";
  * ); // => 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>>;
+declare function toMap<Item, KeyArg extends KeyOrCallback<Item, Key>, ValueArg extends KeyOrCallback<Item>>(array: Item[], key: KeyArg, value: ValueArg): Map<KeyOrCallbackKey<Item, KeyArg>, KeyOrCallbackValue<Item, ValueArg>>;
 /**
- * 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
+ * Create a _Map_ 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 convert
- * @param callback Callback to get an item's grouping key
+ * @param key Callback or key to use for grouping
  * @returns _Map_ of keyed items
  *
  * @example
@@ -97,25 +37,7 @@ declare function toMap<Item extends PlainObject, ItemKey extends keyof Item, Ite
  * ); // => 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>;
+declare function toMap<Item, KeyArg extends KeyOrCallback<Item, Key>>(array: Item[], key: KeyArg): Map<KeyOrCallbackKey<Item, KeyArg>, Item>;
 /**
  * Create a _Map_ from an array of items _(using indices as keys)_
  *
@@ -134,13 +56,13 @@ declare namespace toMap {
   var arrays: typeof toMapArrays;
 }
 /**
- * Create a _Map_ from an array of items using callbacks, grouping values into arrays
+ * Create a _Map_ from an array of items using a specific key, 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
+ * @param key Callback or key to use for grouping
+ * @param value Callback or key to use for value, defaulting to the item itself
  * @returns _Map_ of keyed arrays of values
  *
  * @example
@@ -152,74 +74,14 @@ declare namespace toMap {
  * ); // => 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>, Array<ReturnType<ValueCallback>>>;
+declare function toMapArrays<Item, KeyArg extends KeyOrCallback<Item, Key>, ValueArg extends KeyOrCallback<Item>>(array: Item[], key: KeyArg, value: ValueArg): Map<KeyOrCallbackKey<Item, KeyArg>, Array<KeyOrCallbackValue<Item, ValueArg>>>;
 /**
- * Create a _Map_ from an array of items using a callback and value, grouping values into arrays
+ * Create a _Map_ from an array of items using a specific key, grouping items 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], Array<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
+ * @param key Callback or key to use for grouping
  * @returns _Map_ of keyed arrays of items
  *
  * @example
@@ -230,24 +92,6 @@ declare function toMapArrays<Item extends PlainObject, ItemKey extends keyof Ite
  * ); // => 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[]>;
+declare function toMapArrays<Item, KeyArg extends KeyOrCallback<Item, Key>>(array: Item[], key: KeyArg): Map<KeyOrCallbackKey<Item, KeyArg>, Item[]>;
 //#endregion
 export { toMap, toMapArrays };