@oscarpalmer/atoms 0.201.0 → 0.203.0

package/dist/array/sort.mjs

@@ -1,10 +1,20 @@
 import { isPlainObject } from "../internal/is.mjs";
 import { compare } from "../internal/value/compare.mjs";
 //#region src/array/sort.ts
+const SORTER_PROPERTY = "$sorter";
+function Sorter(sorters) {
+	Object.defineProperty(this, SORTER_SYMBOL, { value: sorters });
+}
+Object.defineProperties(Sorter.prototype, {
+	[SORTER_PROPERTY]: { value: true },
+	index: { value: getSortedArrayIndex },
+	is: { value: isSortedArray },
+	sort: { value: sortArray }
+});
 function getComparisonSorter(callback, modifier) {
 	return {
 		modifier,
-		compare: { simple: callback },
+		comparison: { simple: callback },
 		get: false,
 		identifier: callback.toString()
 	};
@@ -13,15 +23,29 @@ function getComparisonValue(first, second, sorters, length) {
 	for (let index = 0; index < length; index += 1) {
 		const sorter = sorters[index];
 		const values = [sorter.get ? sorter.value(first) : first, sorter.get ? sorter.value(second) : second];
-		const comparison = (sorter.compare?.complex?.(first, values[0], second, values[1]) ?? sorter.compare?.simple?.(values[0], values[1]) ?? compare(values[0], values[1])) * sorter.modifier;
+		const comparison = (sorter.comparison?.complex?.(first, values[0], second, values[1]) ?? sorter.comparison?.simple?.(values[0], values[1]) ?? compare(values[0], values[1])) * sorter.modifier;
 		if (comparison !== 0) return comparison;
 	}
 	return 0;
 }
-function getIndex(array, item, sorters) {
+function getModifier(first, second) {
+	return modifiers[first === true || second === true ? SORT_DIRECTION_DESCENDING : SORT_DIRECTION_ASCENDING];
+}
+function getObjectSorter(obj, modifier) {
+	let sorter;
+	if (typeof obj.comparison === "function") sorter = getComparisonSorter(obj.comparison, modifier);
+	else if (typeof obj.key === "string") {
+		sorter = getValueSortHandlers(obj.key, modifier);
+		if (typeof obj.compare === "function") sorter.comparison = { complex: obj.compare };
+	} else if (typeof obj.value === "function") sorter = getValueSortHandlers(obj.value, modifier);
+	if (sorter != null && typeof obj.direction === "string") sorter.modifier = modifiers[obj.direction] ?? modifier;
+	return sorter;
+}
+function getSortedArrayIndex(array, item) {
 	if (!Array.isArray(array)) return -1;
 	const { length } = array;
 	if (length === 0) return 0;
+	const sorters = Array.isArray(this) ? this : this[SORTER_SYMBOL];
 	const sortersLength = sorters.length;
 	if (getComparisonValue(item, array[0], sorters, sortersLength) < 0) return 0;
 	if (getComparisonValue(item, array[length - 1], sorters, sortersLength) >= 0) return length;
@@ -34,36 +58,23 @@ function getIndex(array, item, sorters) {
 	}
 	return low;
 }
-function getModifier(first, second) {
-	return modifiers[first === true || second === true ? SORT_DIRECTION_DESCENDING : SORT_DIRECTION_ASCENDING];
-}
-function getObjectSorter(obj, modifier) {
-	let sorter;
-	if (typeof obj.comparison === "function") sorter = getComparisonSorter(obj.comparison, modifier);
-	else if (typeof obj.key === "string") {
-		sorter = getValueSorter(obj.key, modifier);
-		if (typeof obj.compare === "function") sorter.compare = { complex: obj.compare };
-	} else if (typeof obj.value === "function") sorter = getValueSorter(obj.value, modifier);
-	if (sorter != null && typeof obj.direction === "string") sorter.modifier = modifiers[obj.direction] ?? modifier;
-	return sorter;
-}
 function getSortedIndex(array, item, first, second) {
-	return getIndex(array, item, getSorters(first, getModifier(first, second)));
+	return getSortedArrayIndex.call(getSortHandlers(first, getModifier(first, second)), array, item);
 }
-function getSorter(value, modifier) {
+function getSortHandler(value, modifier) {
 	switch (true) {
 		case typeof value === "function": return getComparisonSorter(value, modifier);
-		case typeof value === "string": return getValueSorter(value, modifier);
+		case typeof value === "string": return getValueSortHandlers(value, modifier);
 		case isPlainObject(value): return getObjectSorter(value, modifier);
 	}
 }
-function getSorters(value, modifier) {
+function getSortHandlers(value, modifier) {
 	const array = Array.isArray(value) ? value : [value];
 	const { length } = array;
 	const sorters = [];
 	for (let index = 0; index < length; index += 1) {
 		const item = array[index];
-		const sorter = getSorter(item, modifier);
+		const sorter = getSortHandler(item, modifier);
 		if (sorter != null) sorters.push(sorter);
 	}
 	if (sorters.length === 0) return [{
@@ -73,7 +84,7 @@ function getSorters(value, modifier) {
 	}];
 	return sorters.filter((value, index, array) => array.findIndex((next) => next.identifier === value.identifier) === index);
 }
-function getValueSorter(value, modifier) {
+function getValueSortHandlers(value, modifier) {
 	const isFunction = typeof value === "function";
 	return {
 		modifier,
@@ -83,21 +94,16 @@ function getValueSorter(value, modifier) {
 	};
 }
 function initializeSorter(first, second) {
-	const sorters = getSorters(first, getModifier(first, second));
-	const sorter = (array) => sortArray(array, sorters);
-	Object.defineProperties(sorter, {
-		index: { value: (array, item) => getIndex(array, item, sorters) },
-		is: { value: (array) => isSortedArray(array, sorters) }
-	});
-	return sorter;
+	return new Sorter(getSortHandlers(first, getModifier(first, second)));
 }
 function isSorted(array, first, second) {
-	return isSortedArray(array, getSorters(first, getModifier(first, second)));
+	return isSortedArray.call(getSortHandlers(first, getModifier(first, second)), array);
 }
-function isSortedArray(array, sorters) {
+function isSortedArray(array) {
 	if (!Array.isArray(array)) return false;
 	const { length } = array;
 	if (length < 2) return true;
+	const sorters = Array.isArray(this) ? this : this[SORTER_SYMBOL];
 	const sortersLength = sorters.length;
 	let offset = 0;
 	if (length >= SORT_THRESHOLD) {
@@ -119,10 +125,11 @@ function isSortedArray(array, sorters) {
 	return true;
 }
 function sort(array, first, second) {
-	return sortArray(array, getSorters(first, getModifier(first, second)));
+	return sortArray.call(getSortHandlers(first, getModifier(first, second)), array);
 }
-function sortArray(array, sorters) {
+function sortArray(array) {
 	if (!Array.isArray(array)) return [];
+	const sorters = Array.isArray(this) ? this : this[SORTER_SYMBOL];
 	const { length } = sorters;
 	return array.length > 1 ? array.sort((first, second) => getComparisonValue(first, second, sorters, length)) : array;
 }
@@ -130,6 +137,7 @@ const SORT_PEEK_PERCENTAGE = 10;
 const SORT_THRESHOLD = 100;
 const SORT_DIRECTION_ASCENDING = "ascending";
 const SORT_DIRECTION_DESCENDING = "descending";
+const SORTER_SYMBOL = Symbol(SORTER_PROPERTY);
 const modifiers = {
 	[SORT_DIRECTION_ASCENDING]: 1,
 	[SORT_DIRECTION_DESCENDING]: -1

package/dist/array/splice.d.mts

@@ -20,7 +20,7 @@
  * ); // => [3, 4], array becomes [1, 2, 6, 7, 5]
  * ```
  */
-declare function splice<Item>(array: Item[], start: number, amount: number, added: Item[]): Item[];
+export declare function splice<Item>(array: Item[], start: number, amount: number, added: Item[]): Item[];
 /**
  * Adds items into an array at a specific index
  *
@@ -40,7 +40,7 @@ declare function splice<Item>(array: Item[], start: number, amount: number, adde
  * ); // => [], array becomes [1, 2, 6, 7, 3, 4, 5]
  * ```
  */
-declare function splice<Item>(array: Item[], start: number, added: Item[]): Item[];
+export declare function splice<Item>(array: Item[], start: number, added: Item[]): Item[];
 /**
  * Removes and returns _(up to)_ a specific amount of items from an array, starting from a specific index
  *
@@ -60,7 +60,7 @@ declare function splice<Item>(array: Item[], start: number, added: Item[]): Item
  * ); // => [3, 4], array becomes [1, 2, 5]
  * ```
  */
-declare function splice<Item>(array: Item[], start: number, amount: number): Item[];
+export declare function splice<Item>(array: Item[], start: number, amount: number): Item[];
 /**
  * Removes and returns all items from an array starting from a specific index
  *
@@ -78,6 +78,5 @@ declare function splice<Item>(array: Item[], start: number, amount: number): Ite
  * ); // => [3, 4, 5], array becomes [1, 2]
  * ```
  */
-declare function splice<Item>(array: Item[], start: number): Item[];
-//#endregion
-export { splice };
+export declare function splice<Item>(array: Item[], start: number): Item[];
+//#endregion

package/dist/array/swap.d.mts

@@ -33,7 +33,7 @@ import { PlainObject } from "../models.mjs";
  *    // ]
  * ```
  */
-declare function swap<Item>(array: Item[], first: Item[], second: Item[], callback: (item: Item, index: number, array: Item[]) => unknown): Item[];
+export 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
  *
@@ -67,7 +67,7 @@ declare function swap<Item>(array: Item[], first: Item[], second: Item[], callba
  *    // ]
  * ```
  */
-declare function swap<Item extends PlainObject, ItemKey extends keyof Item>(array: Item[], first: Item[], second: Item[], key: ItemKey): Item[];
+export 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
  *
@@ -87,7 +87,7 @@ declare function swap<Item extends PlainObject, ItemKey extends keyof Item>(arra
  * ); // => [5, 6, 3, 4, 1, 2]
  * ```
  */
-declare function swap<Item>(array: Item[], first: Item[], second: Item[]): Item[];
+export declare function swap<Item>(array: Item[], first: Item[], second: Item[]): Item[];
 /**
  * Swap two indiced items in an array
  *
@@ -117,7 +117,7 @@ declare function swap<Item>(array: Item[], first: Item[], second: Item[]): Item[
  *    // ]
  * ```
  */
-declare function swap<Item>(array: Item[], first: Item, second: Item, callback: (item: Item, index: number, array: Item[]) => unknown): Item[];
+export 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
  *
@@ -147,7 +147,7 @@ declare function swap<Item>(array: Item[], first: Item, second: Item, callback:
  *    // ]
  * ```
  */
-declare function swap<Item extends PlainObject, ItemKey extends keyof Item>(array: Item[], first: Item, second: Item, key: ItemKey): Item[];
+export 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
  *
@@ -165,8 +165,8 @@ declare function swap<Item extends PlainObject, ItemKey extends keyof Item>(arra
  * ); // => [1, 5, 3, 4, 2, 6]
  * ```
  */
-declare function swap<Item>(array: Item[], first: Item, second: Item): Item[];
-declare namespace swap {
+export declare function swap<Item>(array: Item[], first: Item, second: Item): Item[];
+export declare namespace swap {
   var indices: typeof swapIndices;
 }
 /**
@@ -182,5 +182,4 @@ declare namespace swap {
  * @returns Original array with items swapped _(or unchanged if unable to swap)_
  */
 declare function swapIndices<Item>(array: Item[], first: number, second: number): Item[];
-//#endregion
-export { swap };
+//#endregion

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>>;
+export 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>;
+export 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)_
  *
@@ -129,18 +51,18 @@ declare function toMap<Item extends PlainObject, ItemKey extends keyof Item>(arr
  * ); // => 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 {
+export declare function toMap<Item>(array: Item[]): Map<number, Item>;
+export 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>>>;
+export 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,5 @@ 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[]>;
-//#endregion
-export { toMap, toMapArrays };
+export declare function toMapArrays<Item, KeyArg extends KeyOrCallback<Item, Key>>(array: Item[], key: KeyArg): Map<KeyOrCallbackKey<Item, KeyArg>, Item[]>;
+//#endregion