@oscarpalmer/atoms 0.199.0 → 0.201.0

package/dist/array/flatten.d.mts

@@ -11,6 +11,6 @@ import { NestedArray } from "../models.mjs";
  * flatten([1, [2, [3, 4], 5], 6]); // => [1, 2, 3, 4, 5, 6]
  * ```
  */
-declare function flatten<Item>(array: Item[]): NestedArray<Item>[];
+declare function flatten<Item>(array: Item[]): Array<NestedArray<Item>>;
 //#endregion
 export { flatten };

package/dist/array/from.d.mts

@@ -62,7 +62,7 @@ declare function times(length: number): number[];
  * times(5, index => index * 2); // => [0, 2, 4, 6, 8]
  * ```
  */
-declare function times<Callback extends (index: number) => unknown>(length: number, callback: Callback): ReturnType<Callback>[];
+declare function times<Callback extends (index: number) => unknown>(length: number, callback: Callback): Array<ReturnType<Callback>>;
 /**
  * Get an array with a specified length, filled with a specified value
  *

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

@@ -155,7 +155,7 @@ 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>, ReturnType<ValueCallback>[]>;
+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
  *
@@ -201,7 +201,7 @@ declare function groupArraysBy<Item extends PlainObject, KeyCallback extends (it
  *    // }
  * ```
  */
-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>, ReturnType<ValueCallback>[]>>;
+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
  *

package/dist/array/index.d.mts

@@ -14,7 +14,7 @@ import { intersection } from "./intersection.mjs";
 import { partition } from "./partition.mjs";
 import { push } from "./push.mjs";
 import { reverse } from "./reverse.mjs";
-import { select } from "./select.mjs";
+import { reverseSelect, select } from "./select.mjs";
 import { single } from "./single.mjs";
 import { drop, slice, take } from "./slice.mjs";
 import { splice } from "./splice.mjs";
@@ -23,4 +23,4 @@ import { toggle } from "./toggle.mjs";
 import { union } from "./union.mjs";
 import { unique } from "./unique.mjs";
 import { update } from "./update.mjs";
-export { ArrayComparison, chunk, compact, difference, drop, endsWithArray, exists, find, findLast, flatten, getArray, getArrayComparison, includesArray, indexOf, indexOfArray, insert, intersection, lastIndexOf, partition, push, range, reverse, select, shuffle, single, slice, splice, startsWithArray, take, times, toSet, toggle, union, unique, update };
+export { ArrayComparison, chunk, compact, difference, drop, endsWithArray, exists, find, findLast, flatten, getArray, getArrayComparison, includesArray, indexOf, indexOfArray, insert, intersection, lastIndexOf, partition, push, range, reverse, reverseSelect, select, shuffle, single, slice, splice, startsWithArray, take, times, toSet, toggle, union, unique, update };

package/dist/array/index.mjs

@@ -14,7 +14,7 @@ import { intersection } from "./intersection.mjs";
 import { partition } from "./partition.mjs";
 import { push } from "./push.mjs";
 import { reverse } from "./reverse.mjs";
-import { select } from "./select.mjs";
+import { reverseSelect, select } from "./select.mjs";
 import { single } from "./single.mjs";
 import { drop, slice, take } from "./slice.mjs";
 import { splice } from "./splice.mjs";
@@ -23,4 +23,4 @@ import { toggle } from "./toggle.mjs";
 import { union } from "./union.mjs";
 import { unique } from "./unique.mjs";
 import { update } from "./update.mjs";
-export { chunk, compact, difference, drop, endsWithArray, exists, find, findLast, flatten, getArray, getArrayComparison, includesArray, indexOf, indexOfArray, insert, intersection, lastIndexOf, partition, push, range, reverse, select, shuffle, single, slice, splice, startsWithArray, take, times, toSet, toggle, union, unique, update };
+export { chunk, compact, difference, drop, endsWithArray, exists, find, findLast, flatten, getArray, getArrayComparison, includesArray, indexOf, indexOfArray, insert, intersection, lastIndexOf, partition, push, range, reverse, reverseSelect, select, shuffle, single, slice, splice, startsWithArray, take, times, toSet, toggle, union, unique, update };

package/dist/array/select.d.mts

@@ -1,109 +1,111 @@
 import { PlainObject } from "../models.mjs";
 //#region src/array/select.d.ts
+type MapKeyOrCallback<Item> = ((item: Item, index: number, array: Item[]) => unknown) | (Item extends PlainObject ? keyof Item : never);
+type Mapped<Item, Map extends MapKeyOrCallback<Item>> = Map extends ((item: Item, index: number, array: Item[]) => unknown) ? ReturnType<Map> : Map extends keyof Item ? Item[Map] : never;
+type ObjectKeysOf<Item> = { [Key in keyof Item]: Item[Key] extends PlainObject ? Key : never; }[keyof Item];
 /**
- * Get a filtered and mapped array of items
+ * Get a mapped and filtered array of items
  *
  * @param array Array to search in
- * @param filterCallback Callback to get an item's value for matching
+ * @param map Callback or key to map the items
+ * @param filterCallback Callback to get a mapped value's value for matching
  * @param filterValue Value to match against
- * @param mapCallback Callback to map the matched items
- * @returns Filtered and mapped array of items
+ * @returns Mapped and filtered array of items
  *
  * @example
  * ```typescript
- * select(
+ * reverseSelect(
  *   [{id: 1, name: 'Alice'}, {id: 2, name: 'Bob'}, {id: 3, name: 'Charlie'}],
- *   item => item.id,
- *   2,
  *   item => item.name,
+ *   value => value.length,
+ *   3,
  * ); // => ['Bob']
  * ```
  */
-declare function select<Item, FilterCallback extends (item: Item, index: number, array: Item[]) => unknown, MapCallback extends (item: Item, index: number, array: Item[]) => unknown>(array: Item[], filterCallback: FilterCallback, filterValue: ReturnType<FilterCallback>, mapCallback: MapCallback): Array<ReturnType<MapCallback>>;
+declare function reverseSelect<Item, Map extends MapKeyOrCallback<Item>, FilterCallback extends (item: Mapped<Item, Map>, index: number, array: Item[]) => unknown>(array: Item[], map: Map, filterCallback: FilterCallback, filterValue: ReturnType<FilterCallback>): Array<Mapped<Item, Map>>;
 /**
- * Get a filtered and mapped array of items
+ * Get a mapped and filtered array of items
  *
  * @param array Array to search in
- * @param filterCallback Callback to get an item's value for matching
+ * @param map Callback to map the items
+ * @param filterKey Key to get a mapped value's value for matching
  * @param filterValue Value to match against
- * @param mapKey Key to get an item's value for mapping
- * @returns Filtered and mapped array of items
+ * @returns Mapped and filtered array of items
  *
  * @example
  * ```typescript
- * select(
+ * reverseSelect(
  *   [{id: 1, name: 'Alice'}, {id: 2, name: 'Bob'}, {id: 3, name: 'Charlie'}],
- *   item => item.id,
- *   2,
- *   'name',
- * ); // => ['Bob']
+ *   item => ({label: item.name}),
+ *   'label',
+ *   'Bob',
+ * ); // => [{label: 'Bob'}]
  * ```
  */
-declare function select<Item extends PlainObject, FilterCallback extends (item: Item, index: number, array: Item[]) => unknown, MapKey extends keyof Item>(array: Item[], filterCallback: FilterCallback, filterValue: ReturnType<FilterCallback>, mapKey: MapKey): Array<Item[MapKey]>;
+declare function reverseSelect<Item, MapCallback extends (item: Item, index: number, array: Item[]) => PlainObject, ItemKey extends keyof ReturnType<MapCallback>>(array: Item[], map: MapCallback, filterKey: ItemKey, filterValue: ReturnType<MapCallback>[ItemKey]): Array<ReturnType<MapCallback>>;
 /**
- * Get a filtered and mapped array of items
+ * Get a mapped and filtered array of items
  *
  * @param array Array to search in
- * @param filterKey Key to get an item's value for matching
+ * @param map Key to map the items
+ * @param filterKey Key to get a mapped value's value for matching
  * @param filterValue Value to match against
- * @param mapCallback Callback to map the matched items
- * @returns Filtered and mapped array of items
+ * @returns Mapped and filtered array of items
  *
  * @example
  * ```typescript
- * select(
- *   [{id: 1, name: 'Alice'}, {id: 2, name: 'Bob'}, {id: 3, name: 'Charlie'}],
- *   'id',
- *   2,
- *   item => item.name,
- * ); // => ['Bob']
+ * reverseSelect(
+ *   [{meta: {tag: 'a'}}, {meta: {tag: 'b'}}],
+ *   'meta',
+ *   'tag',
+ *   'b',
+ * ); // => [{tag: 'b'}]
  * ```
  */
-declare function select<Item extends PlainObject, ItemKey extends keyof Item, MapCallback extends (item: Item, index: number, array: Item[]) => unknown>(array: Item[], filterKey: ItemKey, filterValue: Item[ItemKey], mapCallback: MapCallback): Array<ReturnType<MapCallback>>;
+declare function reverseSelect<Item, MapKey extends ObjectKeysOf<Item>, ItemKey extends keyof Item[MapKey]>(array: Item[], map: MapKey, filterKey: ItemKey, filterValue: Item[MapKey][ItemKey]): Array<Item[MapKey]>;
 /**
- * Get a filtered and mapped array of items
+ * Get a mapped and filtered array of items
  *
  * @param array Array to search in
- * @param filterKey Key to get an item's value for matching
- * @param filterValue Value to match against
- * @param mapKey Key to get an item's value for mapping
- * @returns Filtered and mapped array of items
+ * @param map Callback or key to map the items
+ * @param filter Filter callback to match mapped values
+ * @returns Mapped and filtered array of items
  *
  * @example
  * ```typescript
- * select(
+ * reverseSelect(
  *   [{id: 1, name: 'Alice'}, {id: 2, name: 'Bob'}, {id: 3, name: 'Charlie'}],
- *   'id',
- *   2,
- *   'name',
+ *   item => item.name,
+ *   value => value.startsWith('B'),
  * ); // => ['Bob']
  * ```
  */
-declare function select<Item extends PlainObject, ItemKey extends keyof Item, MapKey extends keyof Item>(array: Item[], filterKey: ItemKey, filterValue: Item[ItemKey], mapKey: MapKey): Array<Item[MapKey]>;
+declare function reverseSelect<Item, Map extends MapKeyOrCallback<Item>>(array: Item[], map: Map, filter: (item: Mapped<Item, Map>, index: number, array: Item[]) => boolean): Array<Mapped<Item, Map>>;
 /**
- * Get a filtered and mapped array of items
+ * Get a mapped and filtered array of items
  *
  * @param array Array to search in
- * @param filterCallback Filter callback to match items
- * @param mapCallback Callback to map the matched items
- * @returns Filtered and mapped array of items
+ * @param map Callback or key to map the items
+ * @param value Mapped value to match against
+ * @returns Mapped and filtered array of items
  *
  * @example
  * ```typescript
- * select(
- *   [{id: 1, name: 'Alice'}, {id: 2, name: 'Bob'}, {id: 3, name: 'Charlie'}],
- *   item => item.id === 2,
- *   item => item.name,
- * ); // => ['Bob']
+ * reverseSelect(
+ *   [1, 2, 3, 2, 1],
+ *   value => value ** 2,
+ *   4,
+ * ); // => [4, 4]
  * ```
  */
-declare function select<Item, FilterCallback extends (item: Item, index: number, array: Item[]) => unknown, MapCallback extends (item: Item, index: number, array: Item[]) => unknown>(array: Item[], filterCallback: FilterCallback, filterValue: ReturnType<FilterCallback>, mapCallback: MapCallback): Array<ReturnType<MapCallback>>;
+declare function reverseSelect<Item, Map extends MapKeyOrCallback<Item>>(array: Item[], map: Map, value: Mapped<Item, Map>): Array<Mapped<Item, Map>>;
 /**
  * Get a filtered and mapped array of items
  *
  * @param array Array to search in
- * @param filterCallback Filter callback to match items
- * @param mapKey Key to get an item's value for mapping
+ * @param filterCallback Callback to get an item's value for matching
+ * @param filterValue Value to match against
+ * @param map Callback or key to map the matched items
  * @returns Filtered and mapped array of items
  *
  * @example
@@ -112,35 +114,37 @@ declare function select<Item, FilterCallback extends (item: Item, index: number,
  *   [{id: 1, name: 'Alice'}, {id: 2, name: 'Bob'}, {id: 3, name: 'Charlie'}],
  *   item => item.id,
  *   2,
- *   'name'
+ *   item => item.name,
  * ); // => ['Bob']
  * ```
  */
-declare function select<Item extends PlainObject, FilterCallback extends (item: Item, index: number, array: Item[]) => unknown, MapKey extends keyof Item>(array: Item[], filterCallback: FilterCallback, filterValue: ReturnType<FilterCallback>, mapKey: MapKey): Array<Item[MapKey]>;
+declare function select<Item, FilterCallback extends (item: Item, index: number, array: Item[]) => unknown, Map extends MapKeyOrCallback<Item>>(array: Item[], filterCallback: FilterCallback, filterValue: ReturnType<FilterCallback>, map: Map): Array<Mapped<Item, Map>>;
 /**
  * Get a filtered and mapped array of items
  *
  * @param array Array to search in
- * @param filter Filter callback to match items
- * @param map Callback to map the matched items
+ * @param filterKey Key to get an item's value for matching
+ * @param filterValue Value to match against
+ * @param map Callback or key to map the matched items
  * @returns Filtered and mapped array of items
  *
  * @example
  * ```typescript
  * select(
  *   [{id: 1, name: 'Alice'}, {id: 2, name: 'Bob'}, {id: 3, name: 'Charlie'}],
- *   item => item.id === 2,
- *   item => item.name,
+ *   'id',
+ *   2,
+ *   'name',
  * ); // => ['Bob']
  * ```
  */
-declare function select<Item, MapCallback extends (item: Item, index: number, array: Item[]) => unknown>(array: Item[], filter: (item: Item, index: number, array: Item[]) => boolean, map: MapCallback): Array<ReturnType<MapCallback>>;
+declare function select<Item extends PlainObject, ItemKey extends keyof Item, Map extends MapKeyOrCallback<Item>>(array: Item[], filterKey: ItemKey, filterValue: Item[ItemKey], map: Map): Array<Mapped<Item, Map>>;
 /**
  * Get a filtered and mapped array of items
  *
  * @param array Array to search in
  * @param filter Filter callback to match items
- * @param map Key to get an item's value for mapping
+ * @param map Callback or key to map the matched items
  * @returns Filtered and mapped array of items
  *
  * @example
@@ -148,17 +152,17 @@ declare function select<Item, MapCallback extends (item: Item, index: number, ar
  * select(
  *   [{id: 1, name: 'Alice'}, {id: 2, name: 'Bob'}, {id: 3, name: 'Charlie'}],
  *   item => item.id === 2,
- *   'name'
+ *   item => item.name,
  * ); // => ['Bob']
  * ```
  */
-declare function select<Item extends PlainObject, MapKey extends keyof Item>(array: Item[], filter: (item: Item, index: number, array: Item[]) => boolean, map: MapKey): Array<Item[MapKey]>;
+declare function select<Item, Map extends MapKeyOrCallback<Item>>(array: Item[], filter: (item: Item, index: number, array: Item[]) => boolean, map: Map): Array<Mapped<Item, Map>>;
 /**
  * Get a filtered and mapped array of items
  *
  * @param array Array to search in
  * @param item Item to match against
- * @param map Callback to map the matched items
+ * @param map Callback or key to map the matched items
  * @returns Filtered and mapped array of items
  *
  * @example
@@ -170,6 +174,9 @@ declare function select<Item extends PlainObject, MapKey extends keyof Item>(arr
  * ); // => [9]
  * ```
  */
-declare function select<Item, MapCallback extends (item: Item, index: number, array: Item[]) => unknown>(array: Item[], item: Item, map: MapCallback): Array<ReturnType<MapCallback>>;
+declare function select<Item, Map extends MapKeyOrCallback<Item>>(array: Item[], item: Item, map: Map): Array<Mapped<Item, Map>>;
+declare namespace select {
+  var reverse: typeof reverseSelect;
+}
 //#endregion
-export { select };
+export { reverseSelect, select };

package/dist/array/select.mjs

@@ -1,8 +1,23 @@
 import { findValues } from "../internal/array/find.mjs";
 //#region src/array/select.ts
+function reverseSelect(array, ...parameters) {
+	const mapper = parameters.shift();
+	return findValues("all", array, parameters, {
+		callback: mapper,
+		reverse: true
+	}).matched;
+}
 function select(array, ...parameters) {
+	return selectValues(array, parameters);
+}
+function selectValues(array, parameters) {
 	const mapper = parameters.pop();
-	return findValues("all", array, parameters, mapper).matched;
+	return findValues("all", array, parameters, {
+		callback: mapper,
+		reverse: false
+	}).matched;
 }
+select.reverse = reverseSelect;
+Object.defineProperty(select, "reverse", { value: reverseSelect });
 //#endregion
-export { select };
+export { reverseSelect, select };

package/dist/array/sort.d.mts

@@ -172,6 +172,8 @@ declare function initializeSorter<Item>(descending?: boolean): Sorter<Item>;
 /**
  * Is the array sorted according to the sorters _(and the optional default direction)_?
  *
+ * _Available as `isSorted` and `sort.is`_
+ *
  * @param array Array to check
  * @param sorters Sorters to determine sorting
  * @param descending Sorted in descending order? _(defaults to `false`; overridden by individual sorters)_
@@ -181,6 +183,8 @@ declare function isSorted<Item>(array: Item[], sorters: Array<ArraySorter<Item>>
 /**
  * Is the array sorted according to the sorter _(and the optional default direction)_?
  *
+ * _Available as `isSorted` and `sort.is`_
+ *
  * @param array Array to check
  * @param sorter Sorter to determine sorting
  * @param descending Sorted in descending order? _(defaults to `false`; overridden by individual sorters)_

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

@@ -152,7 +152,7 @@ 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>, ReturnType<ValueCallback>[]>;
+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>>>;
 /**
  * Create a _Map_ from an array of items using a callback and value, grouping values into arrays
  *
@@ -192,7 +192,7 @@ declare function toMapArrays<Item extends PlainObject, KeyCallback extends (item
  * ); // => 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>[]>;
+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
  *

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

@@ -152,7 +152,7 @@ declare namespace toRecord {
  * ); // => { 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>[]>;
+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>, Array<ReturnType<ValueCallback>>>;
 /**
  * Create a record from an array of items using a callback and value, grouping values into arrays
  *
@@ -192,7 +192,7 @@ declare function toRecordArrays<Item extends PlainObject, Callback extends (item
  * ); // => { 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>[]>>;
+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>, Array<ReturnType<Callback>>>>;
 /**
  * Create a record from an array of items using a key and value, grouping values into arrays
  *