@sapphire/iterator-utilities 1.0.3-next.fc35dd86 → 2.0.0-next.09afdaab

package/dist/esm/lib/isSorted.d.mts

@@ -0,0 +1,35 @@
+import { IterableResolvable } from './from.mjs';
+
+/**
+ * Checks if the elements of this iterator are sorted in ascending order.
+ *
+ * That is, for each element `a` and its following element `b`, `a <= b` must hold. If the iterator yields exactly zero
+ * or one element, `true` is returned.
+ *
+ * This function uses the default comparator (lexicographically), which means it will compare the elements as strings.
+ * If this is undesirable, use {@link isSortedBy} instead.
+ *
+ * @seealso {@link isSortedBy} for a version that allows custom comparators.
+ * @seealso {@link isSortedByKey} for a version that allows custom key extractors.
+ *
+ * @param iterable The iterator to compare.
+ *
+ * @example
+ * ```typescript
+ * import { isSorted } from '@sapphire/iterator-utilities';
+ *
+ * assert(isSorted([1, 2, 2, 9]);
+ * assert(!isSorted([1, 3, 2, 4]);
+ *
+ * assert(isSorted([0]);
+ * assert(isSorted([]);
+ * assert(isSorted([0, 1, NaN]);
+ * ```
+ *
+ * @remarks
+ *
+ * This function consumes the entire iterator.
+ */
+declare function isSorted<const ElementType>(iterable: IterableResolvable<ElementType>): boolean;
+
+export { isSorted };

package/dist/esm/lib/isSorted.mjs

@@ -0,0 +1,12 @@
+import { __name } from '../chunk-PAWJFY3S.mjs';
+import { isSortedBy } from './isSortedBy.mjs';
+import { defaultCompare } from './shared/comparators.mjs';
+
+function isSorted(iterable) {
+  return isSortedBy(iterable, defaultCompare);
+}
+__name(isSorted, "isSorted");
+
+export { isSorted };
+//# sourceMappingURL=isSorted.mjs.map
+//# sourceMappingURL=isSorted.mjs.map

package/dist/esm/lib/isSorted.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/lib/isSorted.ts"],"names":[],"mappings":";;;;AAmCO,SAAS,SAA4B,QAAoD,EAAA;AAC/F,EAAO,OAAA,UAAA,CAAW,UAAU,cAAc,CAAA;AAC3C;AAFgB,MAAA,CAAA,QAAA,EAAA,UAAA,CAAA","file":"isSorted.mjs","sourcesContent":["import type { IterableResolvable } from './from';\nimport { isSortedBy } from './isSortedBy';\nimport type { isSortedByKey } from './isSortedByKey';\nimport { defaultCompare } from './shared/comparators';\n\n/**\n * Checks if the elements of this iterator are sorted in ascending order.\n *\n * That is, for each element `a` and its following element `b`, `a <= b` must hold. If the iterator yields exactly zero\n * or one element, `true` is returned.\n *\n * This function uses the default comparator (lexicographically), which means it will compare the elements as strings.\n * If this is undesirable, use {@link isSortedBy} instead.\n *\n * @seealso {@link isSortedBy} for a version that allows custom comparators.\n * @seealso {@link isSortedByKey} for a version that allows custom key extractors.\n *\n * @param iterable The iterator to compare.\n *\n * @example\n * ```typescript\n * import { isSorted } from '@sapphire/iterator-utilities';\n *\n * assert(isSorted([1, 2, 2, 9]);\n * assert(!isSorted([1, 3, 2, 4]);\n *\n * assert(isSorted([0]);\n * assert(isSorted([]);\n * assert(isSorted([0, 1, NaN]);\n * ```\n *\n * @remarks\n *\n * This function consumes the entire iterator.\n */\nexport function isSorted<const ElementType>(iterable: IterableResolvable<ElementType>): boolean {\n\treturn isSortedBy(iterable, defaultCompare);\n}\n"]}

package/dist/esm/lib/isSortedBy.d.mts

@@ -0,0 +1,32 @@
+import { IterableResolvable } from './from.mjs';
+import { CompareByComparator } from './shared/_compare.mjs';
+
+/**
+ * Checks if the elements of this iterator are sorted using the given comparator function.
+ *
+ * @seealso {@link isSorted} for a version that uses the default comparator.
+ * @seealso {@link isSortedByKey} for a version that allows custom key extractors.
+ *
+ * @param iterable The iterator to compare.
+ *
+ * @example
+ * ```typescript
+ * import { ascNumber, isSortedBy } from '@sapphire/iterator-utilities';
+ *
+ * assert(isSortedBy([1, 2, 2, 9], ascNumber));
+ * assert(!isSortedBy([1, 2, 2, 9], ascNumber));
+ *
+ * assert(isSortedBy([0], () => true));
+ * assert(isSortedBy([0], () => false));
+ *
+ * assert(isSortedBy([], () => true));
+ * assert(isSortedBy([], () => false));
+ * ```
+ *
+ * @remarks
+ *
+ * This function consumes the entire iterator.
+ */
+declare function isSortedBy<const ElementType>(iterable: IterableResolvable<ElementType>, comparator: CompareByComparator<ElementType>): boolean;
+
+export { isSortedBy };

package/dist/esm/lib/isSortedBy.mjs

@@ -0,0 +1,23 @@
+import { __name } from '../chunk-PAWJFY3S.mjs';
+import { assertFunction } from './shared/_assertFunction.mjs';
+import { compareIteratorElements, orderingIsGreater } from './shared/_compare.mjs';
+import { toIterableIterator } from './toIterableIterator.mjs';
+
+function isSortedBy(iterable, comparator) {
+  comparator = assertFunction(comparator);
+  const iterator = toIterableIterator(iterable);
+  const result = iterator.next();
+  if (result.done) return true;
+  let previous = result.value;
+  for (const current of iterator) {
+    const comparison = compareIteratorElements(previous, current, comparator);
+    if (orderingIsGreater(comparison)) return false;
+    previous = current;
+  }
+  return true;
+}
+__name(isSortedBy, "isSortedBy");
+
+export { isSortedBy };
+//# sourceMappingURL=isSortedBy.mjs.map
+//# sourceMappingURL=isSortedBy.mjs.map

package/dist/esm/lib/isSortedBy.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/lib/isSortedBy.ts"],"names":[],"mappings":";;;;;AAiCO,SAAS,UAAA,CAA8B,UAA2C,UAAuD,EAAA;AAC/I,EAAA,UAAA,GAAa,eAAe,UAAU,CAAA;AAEtC,EAAM,MAAA,QAAA,GAAW,mBAAmB,QAAQ,CAAA;AAC5C,EAAM,MAAA,MAAA,GAAS,SAAS,IAAK,EAAA;AAC7B,EAAI,IAAA,MAAA,CAAO,MAAa,OAAA,IAAA;AAExB,EAAA,IAAI,WAAW,MAAO,CAAA,KAAA;AACtB,EAAA,KAAA,MAAW,WAAW,QAAU,EAAA;AAC/B,IAAA,MAAM,UAAa,GAAA,uBAAA,CAAqC,QAAU,EAAA,OAAA,EAAS,UAAU,CAAA;AACrF,IAAI,IAAA,iBAAA,CAAkB,UAAU,CAAA,EAAU,OAAA,KAAA;AAE1C,IAAW,QAAA,GAAA,OAAA;AAAA;AAGZ,EAAO,OAAA,IAAA;AACR;AAhBgB,MAAA,CAAA,UAAA,EAAA,YAAA,CAAA","file":"isSortedBy.mjs","sourcesContent":["import type { IterableResolvable } from './from';\nimport type { isSorted } from './isSorted';\nimport type { isSortedByKey } from './isSortedByKey';\nimport { assertFunction } from './shared/_assertFunction';\nimport { compareIteratorElements, orderingIsGreater, type CompareByComparator } from './shared/_compare';\nimport { toIterableIterator } from './toIterableIterator';\n\n/**\n * Checks if the elements of this iterator are sorted using the given comparator function.\n *\n * @seealso {@link isSorted} for a version that uses the default comparator.\n * @seealso {@link isSortedByKey} for a version that allows custom key extractors.\n *\n * @param iterable The iterator to compare.\n *\n * @example\n * ```typescript\n * import { ascNumber, isSortedBy } from '@sapphire/iterator-utilities';\n *\n * assert(isSortedBy([1, 2, 2, 9], ascNumber));\n * assert(!isSortedBy([1, 2, 2, 9], ascNumber));\n *\n * assert(isSortedBy([0], () => true));\n * assert(isSortedBy([0], () => false));\n *\n * assert(isSortedBy([], () => true));\n * assert(isSortedBy([], () => false));\n * ```\n *\n * @remarks\n *\n * This function consumes the entire iterator.\n */\nexport function isSortedBy<const ElementType>(iterable: IterableResolvable<ElementType>, comparator: CompareByComparator<ElementType>): boolean {\n\tcomparator = assertFunction(comparator);\n\n\tconst iterator = toIterableIterator(iterable);\n\tconst result = iterator.next();\n\tif (result.done) return true;\n\n\tlet previous = result.value;\n\tfor (const current of iterator) {\n\t\tconst comparison = compareIteratorElements<ElementType>(previous, current, comparator);\n\t\tif (orderingIsGreater(comparison)) return false;\n\n\t\tprevious = current;\n\t}\n\n\treturn true;\n}\n"]}

package/dist/esm/lib/isSortedByKey.d.mts

@@ -0,0 +1,30 @@
+import { IterableResolvable } from './from.mjs';
+import { CompareByComparator } from './shared/_compare.mjs';
+
+/**
+ * Checks if the elements of this iterator are sorted using the given key extraction function.
+ *
+ * Instead of comparing the iterator's elements directly, this function compares the keys of the elements, as determined
+ * by `callbackFn`. Apart from that, it's equivalent to {@link isSorted}; see its documentation for more information.
+ *
+ * @seealso {@link isSorted} for a version that uses the default comparator.
+ * @seealso {@link isSortedBy} for a version that allows custom comparators.
+ *
+ * @param iterable The iterator to compare.
+ * @param callbackFn The function to extract the key from an element.
+ *
+ * @example
+ * ```typescript
+ * import { isSortedByKey } from '@sapphire/iterator-utilities';
+ *
+ * assert(isSortedByKey(['c', 'bb', 'aaa'], (s) => s.length));
+ * assert(!isSortedBy([-2, -1, 0, 3], (n) => Math.abs(n)));
+ * ```
+ *
+ * @remarks
+ *
+ * This function consumes the entire iterator.
+ */
+declare function isSortedByKey<const ElementType, const MappedType>(iterable: IterableResolvable<ElementType>, callbackFn: (a: ElementType, index: number) => MappedType, comparator?: CompareByComparator<MappedType>): boolean;
+
+export { isSortedByKey };

package/dist/esm/lib/isSortedByKey.mjs

@@ -0,0 +1,26 @@
+import { __name } from '../chunk-PAWJFY3S.mjs';
+import { assertFunction } from './shared/_assertFunction.mjs';
+import { compareIteratorElements, orderingIsGreater } from './shared/_compare.mjs';
+import { defaultCompare } from './shared/comparators.mjs';
+import { toIterableIterator } from './toIterableIterator.mjs';
+
+function isSortedByKey(iterable, callbackFn, comparator = defaultCompare) {
+  callbackFn = assertFunction(callbackFn);
+  const iterator = toIterableIterator(iterable);
+  const result = iterator.next();
+  if (result.done) return true;
+  let previousKey = callbackFn(result.value, 0);
+  let index = 1;
+  for (const current of iterator) {
+    const currentKey = callbackFn(current, index++);
+    const comparison = compareIteratorElements(previousKey, currentKey, comparator);
+    if (orderingIsGreater(comparison)) return false;
+    previousKey = currentKey;
+  }
+  return true;
+}
+__name(isSortedByKey, "isSortedByKey");
+
+export { isSortedByKey };
+//# sourceMappingURL=isSortedByKey.mjs.map
+//# sourceMappingURL=isSortedByKey.mjs.map

package/dist/esm/lib/isSortedByKey.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/lib/isSortedByKey.ts"],"names":[],"mappings":";;;;;;AAgCO,SAAS,aACf,CAAA,QAAA,EACA,UACA,EAAA,UAAA,GAA8C,cACpC,EAAA;AACV,EAAA,UAAA,GAAa,eAAe,UAAU,CAAA;AAEtC,EAAM,MAAA,QAAA,GAAW,mBAAmB,QAAQ,CAAA;AAC5C,EAAM,MAAA,MAAA,GAAS,SAAS,IAAK,EAAA;AAC7B,EAAI,IAAA,MAAA,CAAO,MAAa,OAAA,IAAA;AAExB,EAAA,IAAI,WAAc,GAAA,UAAA,CAAW,MAAO,CAAA,KAAA,EAAO,CAAC,CAAA;AAC5C,EAAA,IAAI,KAAQ,GAAA,CAAA;AACZ,EAAA,KAAA,MAAW,WAAW,QAAU,EAAA;AAC/B,IAAM,MAAA,UAAA,GAAa,UAAW,CAAA,OAAA,EAAS,KAAO,EAAA,CAAA;AAC9C,IAAA,MAAM,UAAa,GAAA,uBAAA,CAAoC,WAAa,EAAA,UAAA,EAAY,UAAU,CAAA;AAC1F,IAAI,IAAA,iBAAA,CAAkB,UAAU,CAAA,EAAU,OAAA,KAAA;AAE1C,IAAc,WAAA,GAAA,UAAA;AAAA;AAGf,EAAO,OAAA,IAAA;AACR;AAtBgB,MAAA,CAAA,aAAA,EAAA,eAAA,CAAA","file":"isSortedByKey.mjs","sourcesContent":["import type { IterableResolvable } from './from';\nimport type { isSorted } from './isSorted';\nimport type { isSortedBy } from './isSortedBy';\nimport { assertFunction } from './shared/_assertFunction';\nimport { compareIteratorElements, orderingIsGreater, type CompareByComparator } from './shared/_compare';\nimport { defaultCompare } from './shared/comparators';\nimport { toIterableIterator } from './toIterableIterator';\n\n/**\n * Checks if the elements of this iterator are sorted using the given key extraction function.\n *\n * Instead of comparing the iterator's elements directly, this function compares the keys of the elements, as determined\n * by `callbackFn`. Apart from that, it's equivalent to {@link isSorted}; see its documentation for more information.\n *\n * @seealso {@link isSorted} for a version that uses the default comparator.\n * @seealso {@link isSortedBy} for a version that allows custom comparators.\n *\n * @param iterable The iterator to compare.\n * @param callbackFn The function to extract the key from an element.\n *\n * @example\n * ```typescript\n * import { isSortedByKey } from '@sapphire/iterator-utilities';\n *\n * assert(isSortedByKey(['c', 'bb', 'aaa'], (s) => s.length));\n * assert(!isSortedBy([-2, -1, 0, 3], (n) => Math.abs(n)));\n * ```\n *\n * @remarks\n *\n * This function consumes the entire iterator.\n */\nexport function isSortedByKey<const ElementType, const MappedType>(\n\titerable: IterableResolvable<ElementType>,\n\tcallbackFn: (a: ElementType, index: number) => MappedType,\n\tcomparator: CompareByComparator<MappedType> = defaultCompare\n): boolean {\n\tcallbackFn = assertFunction(callbackFn);\n\n\tconst iterator = toIterableIterator(iterable);\n\tconst result = iterator.next();\n\tif (result.done) return true;\n\n\tlet previousKey = callbackFn(result.value, 0);\n\tlet index = 1;\n\tfor (const current of iterator) {\n\t\tconst currentKey = callbackFn(current, index++);\n\t\tconst comparison = compareIteratorElements<MappedType>(previousKey, currentKey, comparator);\n\t\tif (orderingIsGreater(comparison)) return false;\n\n\t\tpreviousKey = currentKey;\n\t}\n\n\treturn true;\n}\n"]}

package/dist/esm/lib/last.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../src/lib/last.ts"],"names":["last"],"mappings":";;;AAsBO,SAAS,KAAwB,QAAoE,EAAA;AAC3G,EAAIA,IAAAA,KAAAA,CAAAA;AACJ,EAAW,KAAA,MAAA,KAAA,IAAS,kBAAmB,CAAA,QAAQ,CAAG,EAAA;AACjD,IAAAA,KAAO,GAAA,KAAA,CAAA;AAAA,GACR;AAEA,EAAOA,OAAAA,KAAAA,CAAAA;AACR,CAAA;AAPgB,MAAA,CAAA,IAAA,EAAA,MAAA,CAAA","file":"last.mjs","sourcesContent":["import type { IterableResolvable } from './from';\nimport { toIterableIterator } from './toIterableIterator';\n\n/**\n * Consumes the iterable until it's exhausted, returning the last element.\n *\n * @param iterable An iterator to return the last value of.\n * @returns The value at the last position in the source iterator, or `undefined` if the iterator is empty.\n *\n * @example\n * ```typescript\n * import { last } from '@sapphire/iterator-utilities';\n *\n * const iterable = [1, 2, 3, 4, 5];\n * console.log(last(iterable));\n * // Output: 5\n * ```\n *\n * @remarks\n *\n * This function consumes the entire iterator to find the last value.\n */\nexport function last<const ElementType>(iterable: IterableResolvable<ElementType>): ElementType | undefined {\n\tlet last: ElementType | undefined;\n\tfor (const value of toIterableIterator(iterable)) {\n\t\tlast = value;\n\t}\n\n\treturn last;\n}\n"]}
+{"version":3,"sources":["../../../src/lib/last.ts"],"names":["last"],"mappings":";;;AAsBO,SAAS,KAAwB,QAAoE,EAAA;AAC3G,EAAIA,IAAAA,KAAAA;AACJ,EAAW,KAAA,MAAA,KAAA,IAAS,kBAAmB,CAAA,QAAQ,CAAG,EAAA;AACjD,IAAAA,KAAO,GAAA,KAAA;AAAA;AAGR,EAAOA,OAAAA,KAAAA;AACR;AAPgB,MAAA,CAAA,IAAA,EAAA,MAAA,CAAA","file":"last.mjs","sourcesContent":["import type { IterableResolvable } from './from';\nimport { toIterableIterator } from './toIterableIterator';\n\n/**\n * Consumes the iterable until it's exhausted, returning the last element.\n *\n * @param iterable An iterator to return the last value of.\n * @returns The value at the last position in the source iterator, or `undefined` if the iterator is empty.\n *\n * @example\n * ```typescript\n * import { last } from '@sapphire/iterator-utilities';\n *\n * const iterable = [1, 2, 3, 4, 5];\n * console.log(last(iterable));\n * // Output: 5\n * ```\n *\n * @remarks\n *\n * This function consumes the entire iterator to find the last value.\n */\nexport function last<const ElementType>(iterable: IterableResolvable<ElementType>): ElementType | undefined {\n\tlet last: ElementType | undefined;\n\tfor (const value of toIterableIterator(iterable)) {\n\t\tlast = value;\n\t}\n\n\treturn last;\n}\n"]}

package/dist/esm/lib/lessOrEqualThan.d.mts

@@ -0,0 +1,32 @@
+import { IterableResolvable } from './from.mjs';
+
+/**
+ * Determines if the elements of `iterable` are {@link LexicographicComparison lexicographically} less or equal than
+ * those of another.
+ *
+ * @param iterable The iterator to compare.
+ * @param other The iterator to compare against.
+ *
+ * @example
+ * ```typescript
+ * import { lessOrEqualThan } from '@sapphire/iterator-utilities';
+ *
+ * const x = [1, 2, 3, 4];
+ * const y = [1, 4, 9, 16];
+ * console.log(lessOrEqualThan([1], [1]));
+ * // Output: false
+ * console.log(lessOrEqualThan([1], [1, 2]));
+ * // Output: true
+ * console.log(lessOrEqualThan([1, 2], [1]));
+ * // Output: false
+ * console.log(lessOrEqualThan([1, 2], [1, 2]));
+ * // Output: true
+ * ```
+ *
+ * @remarks
+ *
+ * This function consumes the entire iterator.
+ */
+declare function lessOrEqualThan<const ElementType>(iterable: IterableResolvable<ElementType>, other: IterableResolvable<ElementType>): boolean;
+
+export { lessOrEqualThan as le, lessOrEqualThan };

package/dist/esm/lib/lessOrEqualThan.mjs

@@ -0,0 +1,13 @@
+import { __name } from '../chunk-PAWJFY3S.mjs';
+import { compare } from './compare.mjs';
+import { orderingIsGreater } from './shared/_compare.mjs';
+
+function lessOrEqualThan(iterable, other) {
+  const result = compare(iterable, other);
+  return !orderingIsGreater(result);
+}
+__name(lessOrEqualThan, "lessOrEqualThan");
+
+export { lessOrEqualThan as le, lessOrEqualThan };
+//# sourceMappingURL=lessOrEqualThan.mjs.map
+//# sourceMappingURL=lessOrEqualThan.mjs.map

package/dist/esm/lib/lessOrEqualThan.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/lib/lessOrEqualThan.ts"],"names":[],"mappings":";;;;AA+BO,SAAS,eAAA,CAAmC,UAA2C,KAAiD,EAAA;AAC9I,EAAM,MAAA,MAAA,GAAS,OAAQ,CAAA,QAAA,EAAU,KAAK,CAAA;AACtC,EAAO,OAAA,CAAC,kBAAkB,MAAM,CAAA;AACjC;AAHgB,MAAA,CAAA,eAAA,EAAA,iBAAA,CAAA","file":"lessOrEqualThan.mjs","sourcesContent":["import { compare } from './compare';\nimport type { IterableResolvable } from './from';\nimport { orderingIsGreater, type LexicographicComparison } from './shared/_compare';\n\n/**\n * Determines if the elements of `iterable` are {@link LexicographicComparison lexicographically} less or equal than\n * those of another.\n *\n * @param iterable The iterator to compare.\n * @param other The iterator to compare against.\n *\n * @example\n * ```typescript\n * import { lessOrEqualThan } from '@sapphire/iterator-utilities';\n *\n * const x = [1, 2, 3, 4];\n * const y = [1, 4, 9, 16];\n * console.log(lessOrEqualThan([1], [1]));\n * // Output: false\n * console.log(lessOrEqualThan([1], [1, 2]));\n * // Output: true\n * console.log(lessOrEqualThan([1, 2], [1]));\n * // Output: false\n * console.log(lessOrEqualThan([1, 2], [1, 2]));\n * // Output: true\n * ```\n *\n * @remarks\n *\n * This function consumes the entire iterator.\n */\nexport function lessOrEqualThan<const ElementType>(iterable: IterableResolvable<ElementType>, other: IterableResolvable<ElementType>): boolean {\n\tconst result = compare(iterable, other);\n\treturn !orderingIsGreater(result);\n}\n\nexport { lessOrEqualThan as le };\n"]}

package/dist/esm/lib/lessThan.d.mts

@@ -0,0 +1,32 @@
+import { IterableResolvable } from './from.mjs';
+
+/**
+ * Determines if the elements of `iterable` are {@link LexicographicComparison lexicographically} less than those of
+ * another.
+ *
+ * @param iterable The iterator to compare.
+ * @param other The iterator to compare against.
+ *
+ * @example
+ * ```typescript
+ * import { lessThan } from '@sapphire/iterator-utilities';
+ *
+ * const x = [1, 2, 3, 4];
+ * const y = [1, 4, 9, 16];
+ * console.log(lessThan([1], [1]));
+ * // Output: false
+ * console.log(lessThan([1], [1, 2]));
+ * // Output: true
+ * console.log(lessThan([1, 2], [1]));
+ * // Output: false
+ * console.log(lessThan([1, 2], [1, 2]));
+ * // Output: false
+ * ```
+ *
+ * @remarks
+ *
+ * This function consumes the entire iterator.
+ */
+declare function lessThan<const ElementType>(iterable: IterableResolvable<ElementType>, other: IterableResolvable<ElementType>): boolean;
+
+export { lessThan, lessThan as lt };

package/dist/esm/lib/lessThan.mjs

@@ -0,0 +1,13 @@
+import { __name } from '../chunk-PAWJFY3S.mjs';
+import { compare } from './compare.mjs';
+import { orderingIsLess } from './shared/_compare.mjs';
+
+function lessThan(iterable, other) {
+  const result = compare(iterable, other);
+  return orderingIsLess(result);
+}
+__name(lessThan, "lessThan");
+
+export { lessThan, lessThan as lt };
+//# sourceMappingURL=lessThan.mjs.map
+//# sourceMappingURL=lessThan.mjs.map

package/dist/esm/lib/lessThan.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/lib/lessThan.ts"],"names":[],"mappings":";;;;AA+BO,SAAS,QAAA,CAA4B,UAA2C,KAAiD,EAAA;AACvI,EAAM,MAAA,MAAA,GAAS,OAAQ,CAAA,QAAA,EAAU,KAAK,CAAA;AACtC,EAAA,OAAO,eAAe,MAAM,CAAA;AAC7B;AAHgB,MAAA,CAAA,QAAA,EAAA,UAAA,CAAA","file":"lessThan.mjs","sourcesContent":["import { compare } from './compare';\nimport type { IterableResolvable } from './from';\nimport { orderingIsLess, type LexicographicComparison } from './shared/_compare';\n\n/**\n * Determines if the elements of `iterable` are {@link LexicographicComparison lexicographically} less than those of\n * another.\n *\n * @param iterable The iterator to compare.\n * @param other The iterator to compare against.\n *\n * @example\n * ```typescript\n * import { lessThan } from '@sapphire/iterator-utilities';\n *\n * const x = [1, 2, 3, 4];\n * const y = [1, 4, 9, 16];\n * console.log(lessThan([1], [1]));\n * // Output: false\n * console.log(lessThan([1], [1, 2]));\n * // Output: true\n * console.log(lessThan([1, 2], [1]));\n * // Output: false\n * console.log(lessThan([1, 2], [1, 2]));\n * // Output: false\n * ```\n *\n * @remarks\n *\n * This function consumes the entire iterator.\n */\nexport function lessThan<const ElementType>(iterable: IterableResolvable<ElementType>, other: IterableResolvable<ElementType>): boolean {\n\tconst result = compare(iterable, other);\n\treturn orderingIsLess(result);\n}\n\nexport { lessThan as lt };\n"]}

package/dist/esm/lib/map.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../src/lib/map.ts"],"names":[],"mappings":";;;;AAmBO,UAAU,GAAA,CAChB,UACA,UAC+B,EAAA;AAC/B,EAAA,UAAA,GAAa,eAAe,UAAU,CAAA,CAAA;AAEtC,EAAA,IAAI,KAAQ,GAAA,CAAA,CAAA;AACZ,EAAW,KAAA,MAAA,OAAA,IAAW,kBAAmB,CAAA,QAAQ,CAAG,EAAA;AACnD,IAAM,MAAA,UAAA,CAAW,SAAS,KAAO,EAAA,CAAA,CAAA;AAAA,GAClC;AACD,CAAA;AAViB,MAAA,CAAA,GAAA,EAAA,KAAA,CAAA","file":"map.mjs","sourcesContent":["import type { IterableResolvable } from './from';\nimport { assertFunction } from './shared/_assertFunction';\nimport { toIterableIterator } from './toIterableIterator';\n\n/**\n * Creates an iterable with the results of calling a provided function on each element.\n *\n * @param iterable An iterator to map over.\n * @param callbackFn A function to execute for each element produced by the iterator. Its return value is yielded by the iterator helper.\n *\n * @example\n * ```typescript\n * import { map } from '@sapphire/iterator-utilities';\n *\n * const iterable = [1, 2, 3, 4, 5];\n * console.log([...map(iterable, (value) => value * 2)]);\n * // Output: [2, 4, 6, 8, 10]\n * ```\n */\nexport function* map<const ElementType, const MappedType>(\n\titerable: IterableResolvable<ElementType>,\n\tcallbackFn: (element: ElementType, index: number) => MappedType\n): IterableIterator<MappedType> {\n\tcallbackFn = assertFunction(callbackFn);\n\n\tlet index = 0;\n\tfor (const element of toIterableIterator(iterable)) {\n\t\tyield callbackFn(element, index++);\n\t}\n}\n"]}
+{"version":3,"sources":["../../../src/lib/map.ts"],"names":[],"mappings":";;;;AAmBO,UAAU,GAAA,CAChB,UACA,UAC+B,EAAA;AAC/B,EAAA,UAAA,GAAa,eAAe,UAAU,CAAA;AAEtC,EAAA,IAAI,KAAQ,GAAA,CAAA;AACZ,EAAW,KAAA,MAAA,OAAA,IAAW,kBAAmB,CAAA,QAAQ,CAAG,EAAA;AACnD,IAAM,MAAA,UAAA,CAAW,SAAS,KAAO,EAAA,CAAA;AAAA;AAEnC;AAViB,MAAA,CAAA,GAAA,EAAA,KAAA,CAAA","file":"map.mjs","sourcesContent":["import type { IterableResolvable } from './from';\nimport { assertFunction } from './shared/_assertFunction';\nimport { toIterableIterator } from './toIterableIterator';\n\n/**\n * Creates an iterable with the results of calling a provided function on each element.\n *\n * @param iterable An iterator to map over.\n * @param callbackFn A function to execute for each element produced by the iterator. Its return value is yielded by the iterator helper.\n *\n * @example\n * ```typescript\n * import { map } from '@sapphire/iterator-utilities';\n *\n * const iterable = [1, 2, 3, 4, 5];\n * console.log([...map(iterable, (value) => value * 2)]);\n * // Output: [2, 4, 6, 8, 10]\n * ```\n */\nexport function* map<const ElementType, const MappedType>(\n\titerable: IterableResolvable<ElementType>,\n\tcallbackFn: (element: ElementType, index: number) => MappedType\n): IterableIterator<MappedType> {\n\tcallbackFn = assertFunction(callbackFn);\n\n\tlet index = 0;\n\tfor (const element of toIterableIterator(iterable)) {\n\t\tyield callbackFn(element, index++);\n\t}\n}\n"]}

package/dist/esm/lib/max.d.mts

@@ -1,8 +1,13 @@
 import { IterableResolvable } from './from.mjs';
-import { NumberResolvable } from './shared/_toNumberOrThrow.mjs';
 
 /**
- * Consumes the iterable and returns the highest number element. If the iterable is empty, or contains only non-number values, it returns `null`.
+ * Consumes the iterable and returns the highest number element. If the iterable is empty, it returns `null`.
+ *
+ * This function uses the default comparator (lexicographically), which means it will compare the elements as strings.
+ * If this is undesirable, use {@link maxBy} instead.
+ *
+ * @seealso {@link maxBy} for a version that allows custom comparators.
+ * @seealso {@link maxByKey} for a version that allows custom key extractors.
  *
  * @param iterable An iterator of number values to determine the maximum value of.
  * @returns The maximum value in the input iterator, or `null` if the iterator is empty or contains only non-number values.
@@ -20,6 +25,6 @@ import { NumberResolvable } from './shared/_toNumberOrThrow.mjs';
  *
  * This function consumes the entire iterator.
  */
-declare function max(iterable: IterableResolvable<NumberResolvable>): number | null;
+declare function max<const ElementType>(iterable: IterableResolvable<ElementType>): ElementType | null;
 
 export { max };

package/dist/esm/lib/max.mjs

@@ -1,13 +1,9 @@
 import { __name } from '../chunk-PAWJFY3S.mjs';
-import { map } from './map.mjs';
-import { toNumberOrThrow } from './shared/_toNumberOrThrow.mjs';
+import { maxBy } from './maxBy.mjs';
+import { defaultCompare } from './shared/comparators.mjs';
 
 function max(iterable) {
-  let max2 = null;
-  for (const value of map(iterable, toNumberOrThrow)) {
-    if (max2 === null || value > max2) max2 = value;
-  }
-  return max2;
+  return maxBy(iterable, defaultCompare);
 }
 __name(max, "max");
 

package/dist/esm/lib/max.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../src/lib/max.ts"],"names":["max"],"mappings":";;;;AAuBO,SAAS,IAAI,QAA+D,EAAA;AAClF,EAAA,IAAIA,IAAqB,GAAA,IAAA,CAAA;AACzB,EAAA,KAAA,MAAW,KAAS,IAAA,GAAA,CAAI,QAAU,EAAA,eAAe,CAAG,EAAA;AACnD,IAAA,IAAIA,IAAQ,KAAA,IAAA,IAAQ,KAAQA,GAAAA,IAAAA,EAAKA,IAAM,GAAA,KAAA,CAAA;AAAA,GACxC;AAEA,EAAOA,OAAAA,IAAAA,CAAAA;AACR,CAAA;AAPgB,MAAA,CAAA,GAAA,EAAA,KAAA,CAAA","file":"max.mjs","sourcesContent":["import type { IterableResolvable } from './from';\nimport { map } from './map';\nimport { toNumberOrThrow, type NumberResolvable } from './shared/_toNumberOrThrow';\n\n/**\n * Consumes the iterable and returns the highest number element. If the iterable is empty, or contains only non-number values, it returns `null`.\n *\n * @param iterable An iterator of number values to determine the maximum value of.\n * @returns The maximum value in the input iterator, or `null` if the iterator is empty or contains only non-number values.\n *\n * @example\n * ```typescript\n * import { max } from '@sapphire/iterator-utilities';\n *\n * const iterable = [1, 2, 3, 4, 5];\n * console.log(max(iterable));\n * // Output: 5\n * ```\n *\n * @remarks\n *\n * This function consumes the entire iterator.\n */\nexport function max(iterable: IterableResolvable<NumberResolvable>): number | null {\n\tlet max: number | null = null;\n\tfor (const value of map(iterable, toNumberOrThrow)) {\n\t\tif (max === null || value > max) max = value;\n\t}\n\n\treturn max;\n}\n"]}
+{"version":3,"sources":["../../../src/lib/max.ts"],"names":[],"mappings":";;;;AA8BO,SAAS,IAAuB,QAA+D,EAAA;AACrG,EAAO,OAAA,KAAA,CAAM,UAAU,cAAc,CAAA;AACtC;AAFgB,MAAA,CAAA,GAAA,EAAA,KAAA,CAAA","file":"max.mjs","sourcesContent":["import type { IterableResolvable } from './from';\nimport { maxBy } from './maxBy';\nimport type { maxByKey } from './maxByKey';\nimport { defaultCompare } from './shared/comparators';\n\n/**\n * Consumes the iterable and returns the highest number element. If the iterable is empty, it returns `null`.\n *\n * This function uses the default comparator (lexicographically), which means it will compare the elements as strings.\n * If this is undesirable, use {@link maxBy} instead.\n *\n * @seealso {@link maxBy} for a version that allows custom comparators.\n * @seealso {@link maxByKey} for a version that allows custom key extractors.\n *\n * @param iterable An iterator of number values to determine the maximum value of.\n * @returns The maximum value in the input iterator, or `null` if the iterator is empty or contains only non-number values.\n *\n * @example\n * ```typescript\n * import { max } from '@sapphire/iterator-utilities';\n *\n * const iterable = [1, 2, 3, 4, 5];\n * console.log(max(iterable));\n * // Output: 5\n * ```\n *\n * @remarks\n *\n * This function consumes the entire iterator.\n */\nexport function max<const ElementType>(iterable: IterableResolvable<ElementType>): ElementType | null {\n\treturn maxBy(iterable, defaultCompare);\n}\n"]}

package/dist/esm/lib/maxBy.d.mts

@@ -0,0 +1,31 @@
+import { IterableResolvable } from './from.mjs';
+import { CompareByComparator } from './shared/_compare.mjs';
+
+/**
+ * Returns the element that gives the maximum value with respect to the specified comparison function.
+ *
+ * If several elements are equally maximum, the last element is returned. If the iterator is empty, `null` is returned.
+ *
+ * @seealso {@link max} for a version that uses the default comparator.
+ * @seealso {@link maxByKey} for a version that allows custom key extractors.
+ *
+ * @param iterable An iterator of number values to determine the maximum value of.
+ * @param comparator A function to execute for each element produced by the iterator. It should return a number value.
+ * @returns The element that gives the maximum value from the specified function, or `null` if the iterator is empty.
+ *
+ * @example
+ * ```typescript
+ * import { ascNumber, maxBy } from '@sapphire/iterator-utilities';
+ *
+ * const iterable = [-3, 0, 1, 5, -10];
+ * console.log(maxBy(iterable, ascNumber));
+ * // Output: 5
+ * ```
+ *
+ * @remarks
+ *
+ * This function consumes the entire iterator.
+ */
+declare function maxBy<const ElementType>(iterable: IterableResolvable<ElementType>, comparator: CompareByComparator<ElementType>): ElementType | null;
+
+export { maxBy };

package/dist/esm/lib/maxBy.mjs

@@ -0,0 +1,24 @@
+import { __name } from '../chunk-PAWJFY3S.mjs';
+import { assertFunction } from './shared/_assertFunction.mjs';
+import { compareIteratorElements, orderingIsLess } from './shared/_compare.mjs';
+import { toIterableIterator } from './toIterableIterator.mjs';
+
+function maxBy(iterable, comparator) {
+  comparator = assertFunction(comparator);
+  const iterator = toIterableIterator(iterable);
+  const first = iterator.next();
+  if (first.done) return null;
+  let maximum = first.value;
+  for (const value of iterator) {
+    const comparison = compareIteratorElements(value, maximum, comparator);
+    if (!orderingIsLess(comparison)) {
+      maximum = value;
+    }
+  }
+  return maximum;
+}
+__name(maxBy, "maxBy");
+
+export { maxBy };
+//# sourceMappingURL=maxBy.mjs.map
+//# sourceMappingURL=maxBy.mjs.map

package/dist/esm/lib/maxBy.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/lib/maxBy.ts"],"names":[],"mappings":";;;;;AAgCO,SAAS,KAAA,CACf,UACA,UACqB,EAAA;AACrB,EAAA,UAAA,GAAa,eAAe,UAAU,CAAA;AAEtC,EAAM,MAAA,QAAA,GAAW,mBAAmB,QAAQ,CAAA;AAC5C,EAAM,MAAA,KAAA,GAAQ,SAAS,IAAK,EAAA;AAC5B,EAAI,IAAA,KAAA,CAAM,MAAa,OAAA,IAAA;AAEvB,EAAA,IAAI,UAAU,KAAM,CAAA,KAAA;AACpB,EAAA,KAAA,MAAW,SAAS,QAAU,EAAA;AAC7B,IAAA,MAAM,UAAa,GAAA,uBAAA,CAAqC,KAAO,EAAA,OAAA,EAAS,UAAU,CAAA;AAClF,IAAI,IAAA,CAAC,cAAe,CAAA,UAAU,CAAG,EAAA;AAChC,MAAU,OAAA,GAAA,KAAA;AAAA;AACX;AAGD,EAAO,OAAA,OAAA;AACR;AAnBgB,MAAA,CAAA,KAAA,EAAA,OAAA,CAAA","file":"maxBy.mjs","sourcesContent":["import type { IterableResolvable } from './from';\nimport type { max } from './max';\nimport type { maxByKey } from './maxByKey';\nimport { assertFunction } from './shared/_assertFunction';\nimport { compareIteratorElements, orderingIsLess, type CompareByComparator } from './shared/_compare';\nimport { toIterableIterator } from './toIterableIterator';\n\n/**\n * Returns the element that gives the maximum value with respect to the specified comparison function.\n *\n * If several elements are equally maximum, the last element is returned. If the iterator is empty, `null` is returned.\n *\n * @seealso {@link max} for a version that uses the default comparator.\n * @seealso {@link maxByKey} for a version that allows custom key extractors.\n *\n * @param iterable An iterator of number values to determine the maximum value of.\n * @param comparator A function to execute for each element produced by the iterator. It should return a number value.\n * @returns The element that gives the maximum value from the specified function, or `null` if the iterator is empty.\n *\n * @example\n * ```typescript\n * import { ascNumber, maxBy } from '@sapphire/iterator-utilities';\n *\n * const iterable = [-3, 0, 1, 5, -10];\n * console.log(maxBy(iterable, ascNumber));\n * // Output: 5\n * ```\n *\n * @remarks\n *\n * This function consumes the entire iterator.\n */\nexport function maxBy<const ElementType>(\n\titerable: IterableResolvable<ElementType>,\n\tcomparator: CompareByComparator<ElementType>\n): ElementType | null {\n\tcomparator = assertFunction(comparator);\n\n\tconst iterator = toIterableIterator(iterable);\n\tconst first = iterator.next();\n\tif (first.done) return null;\n\n\tlet maximum = first.value;\n\tfor (const value of iterator) {\n\t\tconst comparison = compareIteratorElements<ElementType>(value, maximum, comparator);\n\t\tif (!orderingIsLess(comparison)) {\n\t\t\tmaximum = value;\n\t\t}\n\t}\n\n\treturn maximum;\n}\n"]}

package/dist/esm/lib/maxByKey.d.mts

@@ -0,0 +1,32 @@
+import { IterableResolvable } from './from.mjs';
+import { CompareByComparator } from './shared/_compare.mjs';
+
+/**
+ * Returns the element that gives the maximum value from the specified function.
+ *
+ * If several elements are equally maximum, the last element is returned. If the iterator is empty, `null` is returned.
+ *
+ * @seealso {@link max} for a version that uses the default comparator.
+ * @seealso {@link maxBy} for a version that allows custom comparators.
+ *
+ * @param iterable An iterator of number values to determine the maximum value of.
+ * @param callbackFn A function to execute for each element produced by the iterator, producing a key to compare with.
+ * @param comparator A function to execute for each element produced by the iterator. It should return a number value.
+ * @returns The element that gives the maximum value from the specified function, or `null` if the iterator is empty.
+ *
+ * @example
+ * ```typescript
+ * import { maxByKey } from '@sapphire/iterator-utilities';
+ *
+ * const iterable = [-3, 0, 1, 5, -10];
+ * console.log(maxByKey(iterable, (value) => Math.abs(value)));
+ * // Output: -10
+ * ```
+ *
+ * @remarks
+ *
+ * This function consumes the entire iterator.
+ */
+declare function maxByKey<const ElementType, const MappedType>(iterable: IterableResolvable<ElementType>, callbackFn: (element: ElementType, index: number) => MappedType, comparator?: CompareByComparator<MappedType>): ElementType | null;
+
+export { maxByKey };

package/dist/esm/lib/maxByKey.mjs

@@ -0,0 +1,29 @@
+import { __name } from '../chunk-PAWJFY3S.mjs';
+import { assertFunction } from './shared/_assertFunction.mjs';
+import { compareIteratorElements, orderingIsGreater } from './shared/_compare.mjs';
+import { defaultCompare } from './shared/comparators.mjs';
+import { toIterableIterator } from './toIterableIterator.mjs';
+
+function maxByKey(iterable, callbackFn, comparator = defaultCompare) {
+  callbackFn = assertFunction(callbackFn);
+  const iterator = toIterableIterator(iterable);
+  const first = iterator.next();
+  if (first.done) return null;
+  let maximum = first.value;
+  let maximumKey = callbackFn(maximum, 0);
+  let index = 1;
+  for (const value of iterator) {
+    const key = callbackFn(value, index++);
+    const comparison = compareIteratorElements(maximumKey, key, comparator);
+    if (!orderingIsGreater(comparison)) {
+      maximum = value;
+      maximumKey = key;
+    }
+  }
+  return maximum;
+}
+__name(maxByKey, "maxByKey");
+
+export { maxByKey };
+//# sourceMappingURL=maxByKey.mjs.map
+//# sourceMappingURL=maxByKey.mjs.map

package/dist/esm/lib/maxByKey.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/lib/maxByKey.ts"],"names":[],"mappings":";;;;;;AAkCO,SAAS,QACf,CAAA,QAAA,EACA,UACA,EAAA,UAAA,GAA8C,cACzB,EAAA;AACrB,EAAA,UAAA,GAAa,eAAe,UAAU,CAAA;AAEtC,EAAM,MAAA,QAAA,GAAW,mBAAmB,QAAQ,CAAA;AAC5C,EAAM,MAAA,KAAA,GAAQ,SAAS,IAAK,EAAA;AAC5B,EAAI,IAAA,KAAA,CAAM,MAAa,OAAA,IAAA;AAEvB,EAAA,IAAI,UAAU,KAAM,CAAA,KAAA;AACpB,EAAI,IAAA,UAAA,GAAa,UAAW,CAAA,OAAA,EAAS,CAAC,CAAA;AACtC,EAAA,IAAI,KAAQ,GAAA,CAAA;AACZ,EAAA,KAAA,MAAW,SAAS,QAAU,EAAA;AAC7B,IAAM,MAAA,GAAA,GAAM,UAAW,CAAA,KAAA,EAAO,KAAO,EAAA,CAAA;AACrC,IAAA,MAAM,UAAa,GAAA,uBAAA,CAAoC,UAAY,EAAA,GAAA,EAAK,UAAU,CAAA;AAElF,IAAI,IAAA,CAAC,iBAAkB,CAAA,UAAU,CAAG,EAAA;AACnC,MAAU,OAAA,GAAA,KAAA;AACV,MAAa,UAAA,GAAA,GAAA;AAAA;AACd;AAGD,EAAO,OAAA,OAAA;AACR;AAzBgB,MAAA,CAAA,QAAA,EAAA,UAAA,CAAA","file":"maxByKey.mjs","sourcesContent":["import type { IterableResolvable } from './from';\nimport type { max } from './max';\nimport type { maxBy } from './maxBy';\nimport { assertFunction } from './shared/_assertFunction';\nimport { compareIteratorElements, orderingIsGreater, type CompareByComparator } from './shared/_compare';\nimport { defaultCompare } from './shared/comparators';\nimport { toIterableIterator } from './toIterableIterator';\n\n/**\n * Returns the element that gives the maximum value from the specified function.\n *\n * If several elements are equally maximum, the last element is returned. If the iterator is empty, `null` is returned.\n *\n * @seealso {@link max} for a version that uses the default comparator.\n * @seealso {@link maxBy} for a version that allows custom comparators.\n *\n * @param iterable An iterator of number values to determine the maximum value of.\n * @param callbackFn A function to execute for each element produced by the iterator, producing a key to compare with.\n * @param comparator A function to execute for each element produced by the iterator. It should return a number value.\n * @returns The element that gives the maximum value from the specified function, or `null` if the iterator is empty.\n *\n * @example\n * ```typescript\n * import { maxByKey } from '@sapphire/iterator-utilities';\n *\n * const iterable = [-3, 0, 1, 5, -10];\n * console.log(maxByKey(iterable, (value) => Math.abs(value)));\n * // Output: -10\n * ```\n *\n * @remarks\n *\n * This function consumes the entire iterator.\n */\nexport function maxByKey<const ElementType, const MappedType>(\n\titerable: IterableResolvable<ElementType>,\n\tcallbackFn: (element: ElementType, index: number) => MappedType,\n\tcomparator: CompareByComparator<MappedType> = defaultCompare\n): ElementType | null {\n\tcallbackFn = assertFunction(callbackFn);\n\n\tconst iterator = toIterableIterator(iterable);\n\tconst first = iterator.next();\n\tif (first.done) return null;\n\n\tlet maximum = first.value;\n\tlet maximumKey = callbackFn(maximum, 0);\n\tlet index = 1;\n\tfor (const value of iterator) {\n\t\tconst key = callbackFn(value, index++);\n\t\tconst comparison = compareIteratorElements<MappedType>(maximumKey, key, comparator);\n\n\t\tif (!orderingIsGreater(comparison)) {\n\t\t\tmaximum = value;\n\t\t\tmaximumKey = key;\n\t\t}\n\t}\n\n\treturn maximum;\n}\n"]}

package/dist/esm/lib/min.d.mts

@@ -1,8 +1,13 @@
 import { IterableResolvable } from './from.mjs';
-import { NumberResolvable } from './shared/_toNumberOrThrow.mjs';
 
 /**
- * Consumes the iterable and returns the lowest number element. If the iterable is empty, or contains only non-number values, it returns `null`.
+ * Consumes the iterable and returns the lowest number element. If the iterable is empty, it returns `null`.
+ *
+ * This function uses the default comparator (lexicographically), which means it will compare the elements as strings.
+ * If this is undesirable, use {@link minBy} instead.
+ *
+ * @seealso {@link minBy} for a version that allows custom comparators.
+ * @seealso {@link minByKey} for a version that allows custom key extractors.
  *
  * @param iterable An iterator of number values to determine the minimum value of.
  * @returns The minimum value in the input iterator, or `null` if the iterator is empty or contains only non-number values.
@@ -20,6 +25,6 @@ import { NumberResolvable } from './shared/_toNumberOrThrow.mjs';
  *
  * This function consumes the entire iterator.
  */
-declare function min(iterable: IterableResolvable<NumberResolvable>): number | null;
+declare function min<const ElementType>(iterable: IterableResolvable<ElementType>): ElementType | null;
 
 export { min };

package/dist/esm/lib/min.mjs

@@ -1,13 +1,9 @@
 import { __name } from '../chunk-PAWJFY3S.mjs';
-import { map } from './map.mjs';
-import { toNumberOrThrow } from './shared/_toNumberOrThrow.mjs';
+import { minBy } from './minBy.mjs';
+import { defaultCompare } from './shared/comparators.mjs';
 
 function min(iterable) {
-  let min2 = null;
-  for (const value of map(iterable, toNumberOrThrow)) {
-    if (min2 === null || value < min2) min2 = value;
-  }
-  return min2;
+  return minBy(iterable, defaultCompare);
 }
 __name(min, "min");
 

package/dist/esm/lib/min.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../src/lib/min.ts"],"names":["min"],"mappings":";;;;AAuBO,SAAS,IAAI,QAA+D,EAAA;AAClF,EAAA,IAAIA,IAAqB,GAAA,IAAA,CAAA;AACzB,EAAA,KAAA,MAAW,KAAS,IAAA,GAAA,CAAI,QAAU,EAAA,eAAe,CAAG,EAAA;AACnD,IAAA,IAAIA,IAAQ,KAAA,IAAA,IAAQ,KAAQA,GAAAA,IAAAA,EAAKA,IAAM,GAAA,KAAA,CAAA;AAAA,GACxC;AAEA,EAAOA,OAAAA,IAAAA,CAAAA;AACR,CAAA;AAPgB,MAAA,CAAA,GAAA,EAAA,KAAA,CAAA","file":"min.mjs","sourcesContent":["import type { IterableResolvable } from './from';\nimport { map } from './map';\nimport { toNumberOrThrow, type NumberResolvable } from './shared/_toNumberOrThrow';\n\n/**\n * Consumes the iterable and returns the lowest number element. If the iterable is empty, or contains only non-number values, it returns `null`.\n *\n * @param iterable An iterator of number values to determine the minimum value of.\n * @returns The minimum value in the input iterator, or `null` if the iterator is empty or contains only non-number values.\n *\n * @example\n * ```typescript\n * import { min } from '@sapphire/iterator-utilities';\n *\n * const iterable = [1, 2, 3, 4, 5];\n * console.log(min(iterable));\n * // Output: 1\n * ```\n *\n * @remarks\n *\n * This function consumes the entire iterator.\n */\nexport function min(iterable: IterableResolvable<NumberResolvable>): number | null {\n\tlet min: number | null = null;\n\tfor (const value of map(iterable, toNumberOrThrow)) {\n\t\tif (min === null || value < min) min = value;\n\t}\n\n\treturn min;\n}\n"]}
+{"version":3,"sources":["../../../src/lib/min.ts"],"names":[],"mappings":";;;;AA8BO,SAAS,IAAuB,QAA+D,EAAA;AACrG,EAAO,OAAA,KAAA,CAAM,UAAU,cAAc,CAAA;AACtC;AAFgB,MAAA,CAAA,GAAA,EAAA,KAAA,CAAA","file":"min.mjs","sourcesContent":["import type { IterableResolvable } from './from';\nimport { minBy } from './minBy';\nimport type { minByKey } from './minByKey';\nimport { defaultCompare } from './shared/comparators';\n\n/**\n * Consumes the iterable and returns the lowest number element. If the iterable is empty, it returns `null`.\n *\n * This function uses the default comparator (lexicographically), which means it will compare the elements as strings.\n * If this is undesirable, use {@link minBy} instead.\n *\n * @seealso {@link minBy} for a version that allows custom comparators.\n * @seealso {@link minByKey} for a version that allows custom key extractors.\n *\n * @param iterable An iterator of number values to determine the minimum value of.\n * @returns The minimum value in the input iterator, or `null` if the iterator is empty or contains only non-number values.\n *\n * @example\n * ```typescript\n * import { min } from '@sapphire/iterator-utilities';\n *\n * const iterable = [1, 2, 3, 4, 5];\n * console.log(min(iterable));\n * // Output: 1\n * ```\n *\n * @remarks\n *\n * This function consumes the entire iterator.\n */\nexport function min<const ElementType>(iterable: IterableResolvable<ElementType>): ElementType | null {\n\treturn minBy(iterable, defaultCompare);\n}\n"]}

package/dist/esm/lib/minBy.d.mts

@@ -0,0 +1,31 @@
+import { IterableResolvable } from './from.mjs';
+import { CompareByComparator } from './shared/_compare.mjs';
+
+/**
+ * Returns the element that gives the minimum value with respect to the specified comparison function.
+ *
+ * If several elements are equally minimum, the last element is returned. If the iterator is empty, `null` is returned.
+ *
+ * @seealso {@link min} for a version that uses the default comparator.
+ * @seealso {@link minByKey} for a version that allows custom key extractors.
+ *
+ * @param iterable An iterator of number values to determine the minimum value of.
+ * @param callbackFn A function to execute for each element produced by the iterator. It should return a number value.
+ * @returns The element that gives the minimum value from the specified function, or `null` if the iterator is empty.
+ *
+ * @example
+ * ```typescript
+ * import { ascNumber, minBy } from '@sapphire/iterator-utilities';
+ *
+ * const iterable = [-3, 0, 1, 5, -10];
+ * console.log(minBy(iterable, ascNumber));
+ * // Output: -10
+ * ```
+ *
+ * @remarks
+ *
+ * This function consumes the entire iterator.
+ */
+declare function minBy<const ElementType>(iterable: IterableResolvable<ElementType>, comparator: CompareByComparator<ElementType>): ElementType | null;
+
+export { minBy };

package/dist/esm/lib/minBy.mjs

@@ -0,0 +1,24 @@
+import { __name } from '../chunk-PAWJFY3S.mjs';
+import { assertFunction } from './shared/_assertFunction.mjs';
+import { compareIteratorElements, orderingIsGreater } from './shared/_compare.mjs';
+import { toIterableIterator } from './toIterableIterator.mjs';
+
+function minBy(iterable, comparator) {
+  comparator = assertFunction(comparator);
+  const iterator = toIterableIterator(iterable);
+  const first = iterator.next();
+  if (first.done) return null;
+  let minimum = first.value;
+  for (const value of iterator) {
+    const comparison = compareIteratorElements(value, minimum, comparator);
+    if (!orderingIsGreater(comparison)) {
+      minimum = value;
+    }
+  }
+  return minimum;
+}
+__name(minBy, "minBy");
+
+export { minBy };
+//# sourceMappingURL=minBy.mjs.map
+//# sourceMappingURL=minBy.mjs.map

package/dist/esm/lib/minBy.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/lib/minBy.ts"],"names":[],"mappings":";;;;;AAgCO,SAAS,KAAA,CACf,UACA,UACqB,EAAA;AACrB,EAAA,UAAA,GAAa,eAAe,UAAU,CAAA;AAEtC,EAAM,MAAA,QAAA,GAAW,mBAAmB,QAAQ,CAAA;AAC5C,EAAM,MAAA,KAAA,GAAQ,SAAS,IAAK,EAAA;AAC5B,EAAI,IAAA,KAAA,CAAM,MAAa,OAAA,IAAA;AAEvB,EAAA,IAAI,UAAU,KAAM,CAAA,KAAA;AACpB,EAAA,KAAA,MAAW,SAAS,QAAU,EAAA;AAC7B,IAAA,MAAM,UAAa,GAAA,uBAAA,CAAqC,KAAO,EAAA,OAAA,EAAS,UAAU,CAAA;AAElF,IAAI,IAAA,CAAC,iBAAkB,CAAA,UAAU,CAAG,EAAA;AACnC,MAAU,OAAA,GAAA,KAAA;AAAA;AACX;AAGD,EAAO,OAAA,OAAA;AACR;AApBgB,MAAA,CAAA,KAAA,EAAA,OAAA,CAAA","file":"minBy.mjs","sourcesContent":["import type { IterableResolvable } from './from';\nimport type { min } from './min';\nimport type { minByKey } from './minByKey';\nimport { assertFunction } from './shared/_assertFunction';\nimport { compareIteratorElements, orderingIsGreater, type CompareByComparator } from './shared/_compare';\nimport { toIterableIterator } from './toIterableIterator';\n\n/**\n * Returns the element that gives the minimum value with respect to the specified comparison function.\n *\n * If several elements are equally minimum, the last element is returned. If the iterator is empty, `null` is returned.\n *\n * @seealso {@link min} for a version that uses the default comparator.\n * @seealso {@link minByKey} for a version that allows custom key extractors.\n *\n * @param iterable An iterator of number values to determine the minimum value of.\n * @param callbackFn A function to execute for each element produced by the iterator. It should return a number value.\n * @returns The element that gives the minimum value from the specified function, or `null` if the iterator is empty.\n *\n * @example\n * ```typescript\n * import { ascNumber, minBy } from '@sapphire/iterator-utilities';\n *\n * const iterable = [-3, 0, 1, 5, -10];\n * console.log(minBy(iterable, ascNumber));\n * // Output: -10\n * ```\n *\n * @remarks\n *\n * This function consumes the entire iterator.\n */\nexport function minBy<const ElementType>(\n\titerable: IterableResolvable<ElementType>,\n\tcomparator: CompareByComparator<ElementType>\n): ElementType | null {\n\tcomparator = assertFunction(comparator);\n\n\tconst iterator = toIterableIterator(iterable);\n\tconst first = iterator.next();\n\tif (first.done) return null;\n\n\tlet minimum = first.value;\n\tfor (const value of iterator) {\n\t\tconst comparison = compareIteratorElements<ElementType>(value, minimum, comparator);\n\n\t\tif (!orderingIsGreater(comparison)) {\n\t\t\tminimum = value;\n\t\t}\n\t}\n\n\treturn minimum;\n}\n"]}