atomic-fns 1.2.0 → 2.0.0

package/dist/collections/entries.js

@@ -0,0 +1,131 @@
+/**
+ * What a collection holds: `keys`, `values`, `entries`, `size`, `isEmpty`, `includes`.
+ */
+import { isMap, isSet, mapSize, setSize, typedArrayLength } from '../internal/kind.js';
+import { eachEntry } from './shape.js';
+/**
+ * The keys of `collection`: indices of an array (holes skipped), typed array, string (one per code
+ * point) or other iterable, the keys of a `Map`, the members of a `Set`, and the own enumerable
+ * string keys of any other object. `null`, `undefined`, numbers, booleans, bigints and symbols
+ * have none. Other iterables are consumed to obtain positions.
+ * @param collection The collection to read.
+ * @returns A new array of keys, in iteration order.
+ * @example
+ * ```ts
+ * keys({ a: 1, b: 2 }) // ['a', 'b']
+ * keys(new Map([['x', 1]])) // ['x']
+ * keys('héllo') // [0, 1, 2, 3, 4]
+ * ```
+ */
+export function keys(collection) {
+    const out = [];
+    eachEntry(collection, (_value, key) => {
+        out.push(key);
+    });
+    return out;
+}
+/**
+ * The values of `collection`, in the order {@link keys} gives their keys.
+ * @param collection The collection to read.
+ * @returns A new array of values.
+ * @example
+ * ```ts
+ * values({ a: 1, b: 2 }) // [1, 2]
+ * values(new Map([['x', 1]])) // [1]
+ * values('👍🏽!') // ['👍', '🏽', '!']
+ * ```
+ */
+export function values(collection) {
+    const out = [];
+    eachEntry(collection, (value) => {
+        out.push(value);
+    });
+    return out;
+}
+/**
+ * The `[key, value]` pairs of `collection`, as `Map.prototype.entries` gives them.
+ * @param collection The collection to read.
+ * @returns A new array of pairs.
+ * @example
+ * ```ts
+ * entries({ a: 1 }) // [['a', 1]]
+ * entries(['x', 'y']) // [[0, 'x'], [1, 'y']]
+ * entries(new Set(['s'])) // [['s', 's']]
+ * ```
+ */
+export function entries(collection) {
+    const out = [];
+    eachEntry(collection, (value, key) => {
+        out.push([key, value]);
+    });
+    return out;
+}
+/**
+ * How many entries `collection` has: the `size` of a `Map` or `Set`, the present elements of an
+ * array (holes do not count), the length of a typed array, the code points of a string, the own
+ * enumerable string keys of an object. An iterable that is none of these is read to its end to
+ * count it, so a one-shot iterator such as a generator is exhausted.
+ * @param collection The collection to measure.
+ * @returns The number of entries.
+ * @example
+ * ```ts
+ * size({ a: 1, b: 2 }) // 2
+ * size([1, , 3]) // 2
+ * size('👍🏽') // 2
+ * ```
+ */
+export function size(collection) {
+    if (isMap(collection))
+        return mapSize(collection);
+    if (isSet(collection))
+        return setSize(collection);
+    if (typeof collection === 'object' && collection !== null) {
+        const length = typedArrayLength(collection);
+        if (length !== undefined)
+            return length;
+    }
+    let n = 0;
+    eachEntry(collection, () => {
+        n++;
+    });
+    return n;
+}
+/**
+ * True when `collection` has no entries, by the rules of {@link size}. An iterable is read only
+ * until its first element, and is then closed, so a one-shot iterator such as a generator has
+ * nothing left to give.
+ * @param collection The collection to test.
+ * @returns Whether it has no entries.
+ * @example
+ * ```ts
+ * isEmpty({}) // true
+ * isEmpty([, ,]) // true
+ * isEmpty(new Map([[1, 2]])) // false
+ * isEmpty(null) // true
+ * ```
+ */
+export function isEmpty(collection) {
+    return !eachEntry(collection, () => true);
+}
+/**
+ * True when `collection` holds `value`, compared with SameValueZero against its values (`NaN`
+ * finds `NaN`, `0` finds `-0`). For a string, `value` is a substring, as
+ * `String.prototype.includes` reads it. An iterable is read until the first match, where it is
+ * closed, or to its end, so a one-shot iterator such as a generator is used up either way.
+ * @param collection The collection to search.
+ * @param value The value to look for.
+ * @returns Whether it is there.
+ * @example
+ * ```ts
+ * includes({ a: 1 }, 1) // true
+ * includes(new Map([['k', NaN]]), NaN) // true
+ * includes('hello', 'ell') // true
+ * ```
+ */
+export function includes(collection, value) {
+    if (typeof collection === 'string')
+        return collection.includes(value);
+    if (isSet(collection))
+        return Set.prototype.has.call(collection, value);
+    return eachEntry(collection, (v) => v === value || (v !== v && value !== value));
+}

package/dist/collections/frozen-set.d.ts

@@ -0,0 +1,42 @@
+/**
+ * A `Set` whose contents cannot change after construction: `add`, `delete` and `clear` throw
+ * `TypeError`. Membership is SameValueZero, as for any `Set`, and every read method and the ES2025
+ * set algebra (`union`, `intersection`, ...) are inherited; those return a plain, mutable `Set`.
+ * `Set.prototype.add.call(frozen, x)`, `Set.prototype.delete.call(frozen, x)` and
+ * `Set.prototype.clear.call(frozen)` still mutate, as with any `Set` subclass. Because it is a
+ * `Set`, a FrozenSet type-checks wherever a `Set` is expected, and code there that mutates it
+ * throws.
+ *
+ * @example
+ * ```ts
+ * const primaries = new FrozenSet(['red', 'green', 'blue'])
+ * primaries.has('red') // true
+ * primaries.add('pink') // throws TypeError
+ * ```
+ */
+export declare class FrozenSet<T> extends Set<T> {
+    /**
+     * Create a frozen set holding `iterable`'s values. A plain array is walked in own-element time,
+     * so a huge sparse array costs its elements, not its length.
+     * @param iterable Initial values. `null` means none.
+     * @throws {TypeError} when `iterable` is not iterable.
+     */
+    constructor(iterable?: Iterable<T> | null);
+    /**
+     * Rejected: a FrozenSet cannot change.
+     * @throws {TypeError}
+     */
+    add(_value: T): this;
+    /**
+     * Rejected: a FrozenSet cannot change.
+     * @throws {TypeError}
+     */
+    delete(_value: T): boolean;
+    /**
+     * Rejected: a FrozenSet cannot change.
+     * @throws {TypeError}
+     */
+    clear(): void;
+    /** `'FrozenSet'`, for `Object.prototype.toString`. */
+    get [Symbol.toStringTag](): string;
+}

package/dist/collections/frozen-set.js

@@ -0,0 +1,64 @@
+import { forEachArrayElement, iteratesAsArray } from './internal/iterable.js';
+/**
+ * A `Set` whose contents cannot change after construction: `add`, `delete` and `clear` throw
+ * `TypeError`. Membership is SameValueZero, as for any `Set`, and every read method and the ES2025
+ * set algebra (`union`, `intersection`, ...) are inherited; those return a plain, mutable `Set`.
+ * `Set.prototype.add.call(frozen, x)`, `Set.prototype.delete.call(frozen, x)` and
+ * `Set.prototype.clear.call(frozen)` still mutate, as with any `Set` subclass. Because it is a
+ * `Set`, a FrozenSet type-checks wherever a `Set` is expected, and code there that mutates it
+ * throws.
+ *
+ * @example
+ * ```ts
+ * const primaries = new FrozenSet(['red', 'green', 'blue'])
+ * primaries.has('red') // true
+ * primaries.add('pink') // throws TypeError
+ * ```
+ */
+export class FrozenSet extends Set {
+    /**
+     * Create a frozen set holding `iterable`'s values. A plain array is walked in own-element time,
+     * so a huge sparse array costs its elements, not its length.
+     * @param iterable Initial values. `null` means none.
+     * @throws {TypeError} when `iterable` is not iterable.
+     */
+    constructor(iterable) {
+        super();
+        if (iterable == null)
+            return;
+        if (iteratesAsArray(iterable)) {
+            forEachArrayElement(iterable, (x) => {
+                super.add(x);
+            });
+            return;
+        }
+        for (const x of iterable) {
+            super.add(x);
+        }
+    }
+    /**
+     * Rejected: a FrozenSet cannot change.
+     * @throws {TypeError}
+     */
+    add(_value) {
+        throw new TypeError('FrozenSet is immutable');
+    }
+    /**
+     * Rejected: a FrozenSet cannot change.
+     * @throws {TypeError}
+     */
+    delete(_value) {
+        throw new TypeError('FrozenSet is immutable');
+    }
+    /**
+     * Rejected: a FrozenSet cannot change.
+     * @throws {TypeError}
+     */
+    clear() {
+        throw new TypeError('FrozenSet is immutable');
+    }
+    /** `'FrozenSet'`, for `Object.prototype.toString`. */
+    get [Symbol.toStringTag]() {
+        return 'FrozenSet';
+    }
+}

package/dist/collections/group.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Grouping and ordering by key: `groupBy`, `countBy`, `keyBy`, `partition`, `sortBy`, `orderBy`,
+ * `minBy`, `maxBy`, `sumBy`, `meanBy`.
+ */
+import { type Collection, type CollectionCallback, type CollectionKey, type CollectionValue } from './shape.js';
+/** A key a key helper can order: a number, a bigint, a string, or `null` / `undefined` (last). */
+export type SortKey = number | bigint | string | null | undefined;
+/**
+ * The values of `collection` grouped under the key `keyOf` returns for each, in a
+ * `null`-prototype object, as `Object.groupBy` builds it.
+ * @param collection The collection to group.
+ * @param keyOf Returns the group key of one entry.
+ * @returns An object from each key to its values, in order of first appearance.
+ * @example
+ * ```ts
+ * groupBy([6.1, 4.2, 6.3], (n) => Math.floor(n)) // { 4: [4.2], 6: [6.1, 6.3] }
+ * ```
+ */
+export declare function groupBy<C extends Collection, K extends PropertyKey>(collection: C, keyOf: CollectionCallback<C, K>): Partial<Record<K, CollectionValue<C>[]>>;
+/**
+ * How many values of `collection` fall under each key `keyOf` returns, in a `null`-prototype
+ * object.
+ * @param collection The collection to count.
+ * @param keyOf Returns the key of one entry.
+ * @returns An object from each key to its count.
+ * @example
+ * ```ts
+ * countBy(['one', 'two', 'three'], (s) => s.length) // { 3: 2, 5: 1 }
+ * ```
+ */
+export declare function countBy<C extends Collection, K extends PropertyKey>(collection: C, keyOf: CollectionCallback<C, K>): Partial<Record<K, number>>;
+/**
+ * The values of `collection` under the key `keyOf` returns for each, in a `null`-prototype
+ * object; a later value replaces an earlier one with the same key.
+ * @param collection The collection to index.
+ * @param keyOf Returns the key of one entry.
+ * @returns An object from each key to the last value with it.
+ * @example
+ * ```ts
+ * keyBy([{ id: 'a', n: 1 }], (row) => row.id) // { a: { id: 'a', n: 1 } }
+ * ```
+ */
+export declare function keyBy<C extends Collection, K extends PropertyKey>(collection: C, keyOf: CollectionCallback<C, K>): Partial<Record<K, CollectionValue<C>>>;
+/**
+ * The values of `collection` split into those `predicate` passes and those it fails.
+ * @param collection The collection to split.
+ * @param predicate Tests one entry.
+ * @returns `[pass, fail]`, each in order.
+ * @example
+ * ```ts
+ * partition([1, 2, 3, 4], (n) => n % 2 === 0) // [[2, 4], [1, 3]]
+ * ```
+ */
+export declare function partition<C extends Collection, S extends CollectionValue<C>>(collection: C, predicate: (value: CollectionValue<C>, key: CollectionKey<C>, collection: C) => value is S): [pass: S[], fail: Exclude<CollectionValue<C>, S>[]];
+/** {@link partition} with a predicate that is not a type guard. */
+export declare function partition<C extends Collection>(collection: C, predicate: CollectionCallback<C, unknown>): [pass: CollectionValue<C>[], fail: CollectionValue<C>[]];
+/** `'asc'` or `'desc'`: the direction {@link orderBy} sorts one key in. */
+export type SortOrder = 'asc' | 'desc';
+/**
+ * The values of `collection` in ascending order of the keys `keyOf` returns, compared with the
+ * default key order: numbers and bigints by value, strings by UTF-16 code units, `null` and
+ * `undefined` last. The sort is stable, and several key functions break ties in turn.
+ * @param collection The collection to sort.
+ * @param keyOf One key function, or a list of them.
+ * @returns A new sorted array.
+ * @throws {RangeError} when a key is `NaN`.
+ * @throws {TypeError} when a key is a string against a number, or of any other type.
+ * @example
+ * ```ts
+ * sortBy([{ n: 2 }, { n: 1 }], (row) => row.n) // [{ n: 1 }, { n: 2 }]
+ * ```
+ */
+export declare function sortBy<C extends Collection>(collection: C, keyOf: CollectionCallback<C, SortKey> | readonly CollectionCallback<C, SortKey>[]): CollectionValue<C>[];
+/**
+ * {@link sortBy} with a direction per key: `orders[i]` is `'asc'` (the default) or `'desc'` for
+ * `keyOf[i]`. `null` and `undefined` keys stay last in either direction.
+ * @param collection The collection to sort.
+ * @param keyOf The key functions, in priority order.
+ * @param orders The direction of each key.
+ * @returns A new sorted array.
+ * @throws {TypeError} when `keyOf` or `orders` is not an array, for an unknown order or more
+ *   orders than key functions, or for a key {@link sortBy} cannot order.
+ * @throws {RangeError} when a key is `NaN`.
+ * @example
+ * ```ts
+ * const users = [{ name: 'b', age: 1 }, { name: 'a', age: 2 }, { name: 'b', age: 3 }]
+ * orderBy(users, [(u) => u.name, (u) => u.age], ['asc', 'desc'])
+ * // [{ name: 'a', age: 2 }, { name: 'b', age: 3 }, { name: 'b', age: 1 }]
+ * ```
+ */
+export declare function orderBy<C extends Collection>(collection: C, keyOf: readonly CollectionCallback<C, SortKey>[], orders?: readonly SortOrder[]): CollectionValue<C>[];
+/**
+ * The value of `collection` with the smallest key, by the default key order; the first one on a
+ * tie. Entries whose key is `null` or `undefined` are skipped.
+ * @param collection The collection to search.
+ * @param keyOf Returns the key of one entry.
+ * @returns The value found, or `undefined` when no entry has a key.
+ * @throws {RangeError} for a `NaN` key; {@link sortBy} lists the `TypeError` cases.
+ * @example
+ * ```ts
+ * minBy([{ n: 2 }, { n: 1 }], (row) => row.n) // { n: 1 }
+ * ```
+ */
+export declare function minBy<C extends Collection>(collection: C, keyOf: CollectionCallback<C, SortKey>): CollectionValue<C> | undefined;
+/**
+ * The value of `collection` with the largest key, by the default key order; the first one on a
+ * tie. Entries whose key is `null` or `undefined` are skipped.
+ * @param collection The collection to search.
+ * @param keyOf Returns the key of one entry.
+ * @returns The value found, or `undefined` when no entry has a key.
+ * @throws {RangeError} for a `NaN` key; {@link sortBy} lists the `TypeError` cases.
+ * @example
+ * ```ts
+ * maxBy({ a: 3, b: 7 }, (n) => n) // 7
+ * ```
+ */
+export declare function maxBy<C extends Collection>(collection: C, keyOf: CollectionCallback<C, SortKey>): CollectionValue<C> | undefined;
+/**
+ * The sum of the numbers `valueOf` returns for the entries of `collection`; `0` when empty.
+ * @param collection The collection to add up.
+ * @param valueOf Returns the number of one entry.
+ * @returns The sum.
+ * @throws {TypeError} when `valueOf` returns anything but a number.
+ * @example
+ * ```ts
+ * sumBy([{ n: 4 }, { n: 2 }], (row) => row.n) // 6
+ * ```
+ */
+export declare function sumBy<C extends Collection>(collection: C, valueOf: CollectionCallback<C, number>): number;
+/**
+ * The mean of the numbers `valueOf` returns for the entries of `collection`; `NaN` when empty.
+ * @param collection The collection to average.
+ * @param valueOf Returns the number of one entry.
+ * @returns The mean.
+ * @throws {TypeError} when `valueOf` returns anything but a number.
+ * @example
+ * ```ts
+ * meanBy([{ n: 4 }, { n: 2 }], (row) => row.n) // 3
+ * ```
+ */
+export declare function meanBy<C extends Collection>(collection: C, valueOf: CollectionCallback<C, number>): number;

package/dist/collections/group.js

@@ -0,0 +1,241 @@
+/**
+ * Grouping and ordering by key: `groupBy`, `countBy`, `keyBy`, `partition`, `sortBy`, `orderBy`,
+ * `minBy`, `maxBy`, `sumBy`, `meanBy`.
+ */
+import { isNil } from '../is/isNil.js';
+import { compareKeys, keyKind } from './order.js';
+import { eachEntry } from './shape.js';
+/**
+ * The values of `collection` grouped under the key `keyOf` returns for each, in a
+ * `null`-prototype object, as `Object.groupBy` builds it.
+ * @param collection The collection to group.
+ * @param keyOf Returns the group key of one entry.
+ * @returns An object from each key to its values, in order of first appearance.
+ * @example
+ * ```ts
+ * groupBy([6.1, 4.2, 6.3], (n) => Math.floor(n)) // { 4: [4.2], 6: [6.1, 6.3] }
+ * ```
+ */
+export function groupBy(collection, keyOf) {
+    const fn = keyOf;
+    const out = Object.create(null);
+    eachEntry(collection, (value, key) => {
+        const group = fn(value, key, collection);
+        (out[group] ??= []).push(value);
+    });
+    return out;
+}
+/**
+ * How many values of `collection` fall under each key `keyOf` returns, in a `null`-prototype
+ * object.
+ * @param collection The collection to count.
+ * @param keyOf Returns the key of one entry.
+ * @returns An object from each key to its count.
+ * @example
+ * ```ts
+ * countBy(['one', 'two', 'three'], (s) => s.length) // { 3: 2, 5: 1 }
+ * ```
+ */
+export function countBy(collection, keyOf) {
+    const fn = keyOf;
+    const out = Object.create(null);
+    eachEntry(collection, (value, key) => {
+        const group = fn(value, key, collection);
+        out[group] = (out[group] ?? 0) + 1;
+    });
+    return out;
+}
+/**
+ * The values of `collection` under the key `keyOf` returns for each, in a `null`-prototype
+ * object; a later value replaces an earlier one with the same key.
+ * @param collection The collection to index.
+ * @param keyOf Returns the key of one entry.
+ * @returns An object from each key to the last value with it.
+ * @example
+ * ```ts
+ * keyBy([{ id: 'a', n: 1 }], (row) => row.id) // { a: { id: 'a', n: 1 } }
+ * ```
+ */
+export function keyBy(collection, keyOf) {
+    const fn = keyOf;
+    const out = Object.create(null);
+    eachEntry(collection, (value, key) => {
+        out[fn(value, key, collection)] = value;
+    });
+    return out;
+}
+export function partition(collection, predicate) {
+    const fn = predicate;
+    const pass = [];
+    const fail = [];
+    eachEntry(collection, (value, key) => {
+        ;
+        (fn(value, key, collection) ? pass : fail).push(value);
+    });
+    return [pass, fail];
+}
+function directionsOf(keyCount, orders) {
+    if (!Array.isArray(orders))
+        throw new TypeError('orders must be an array of sort orders');
+    if (orders.length > keyCount)
+        throw new TypeError(`${orders.length} sort orders given for ${keyCount} key functions`);
+    for (const order of orders) {
+        if (order !== 'asc' && order !== 'desc')
+            throw new TypeError(`unknown sort order ${String(order)}`);
+    }
+    return Array.from({ length: keyCount }, (_unused, i) => (orders[i] === 'desc' ? -1 : 1));
+}
+function sortEntries(collection, keyFns, orders) {
+    const directions = directionsOf(keyFns.length, orders);
+    const kinds = [];
+    const rows = [];
+    eachEntry(collection, (value, key) => {
+        const keys = keyFns.map((fn, i) => {
+            const k = fn(value, key, collection);
+            if (!isNil(k)) {
+                const kind = keyKind(k);
+                if (kinds[i] === undefined)
+                    kinds[i] = kind;
+                else if (kinds[i] !== kind)
+                    throw new TypeError('cannot order a string key against a number key');
+            }
+            return k;
+        });
+        rows.push({ value, keys });
+    });
+    rows.sort((x, y) => {
+        for (let i = 0; i < directions.length; i++) {
+            const c = compareKeys(x.keys[i], y.keys[i], directions[i]);
+            if (c !== 0)
+                return c;
+        }
+        return 0;
+    });
+    return rows.map((row) => row.value);
+}
+/**
+ * The values of `collection` in ascending order of the keys `keyOf` returns, compared with the
+ * default key order: numbers and bigints by value, strings by UTF-16 code units, `null` and
+ * `undefined` last. The sort is stable, and several key functions break ties in turn.
+ * @param collection The collection to sort.
+ * @param keyOf One key function, or a list of them.
+ * @returns A new sorted array.
+ * @throws {RangeError} when a key is `NaN`.
+ * @throws {TypeError} when a key is a string against a number, or of any other type.
+ * @example
+ * ```ts
+ * sortBy([{ n: 2 }, { n: 1 }], (row) => row.n) // [{ n: 1 }, { n: 2 }]
+ * ```
+ */
+export function sortBy(collection, keyOf) {
+    const fns = Array.isArray(keyOf) ? keyOf : [keyOf];
+    return sortEntries(collection, fns, []);
+}
+/**
+ * {@link sortBy} with a direction per key: `orders[i]` is `'asc'` (the default) or `'desc'` for
+ * `keyOf[i]`. `null` and `undefined` keys stay last in either direction.
+ * @param collection The collection to sort.
+ * @param keyOf The key functions, in priority order.
+ * @param orders The direction of each key.
+ * @returns A new sorted array.
+ * @throws {TypeError} when `keyOf` or `orders` is not an array, for an unknown order or more
+ *   orders than key functions, or for a key {@link sortBy} cannot order.
+ * @throws {RangeError} when a key is `NaN`.
+ * @example
+ * ```ts
+ * const users = [{ name: 'b', age: 1 }, { name: 'a', age: 2 }, { name: 'b', age: 3 }]
+ * orderBy(users, [(u) => u.name, (u) => u.age], ['asc', 'desc'])
+ * // [{ name: 'a', age: 2 }, { name: 'b', age: 3 }, { name: 'b', age: 1 }]
+ * ```
+ */
+export function orderBy(collection, keyOf, orders = []) {
+    if (!Array.isArray(keyOf))
+        throw new TypeError('keyOf must be an array of key functions');
+    return sortEntries(collection, keyOf, orders);
+}
+function extremum(collection, keyOf, direction) {
+    let best;
+    let bestKey;
+    eachEntry(collection, (value, key) => {
+        const k = keyOf(value, key, collection);
+        if (isNil(k))
+            return;
+        keyKind(k);
+        if (bestKey === undefined || compareKeys(k, bestKey, direction) < 0) {
+            best = value;
+            bestKey = k;
+        }
+    });
+    return best;
+}
+/**
+ * The value of `collection` with the smallest key, by the default key order; the first one on a
+ * tie. Entries whose key is `null` or `undefined` are skipped.
+ * @param collection The collection to search.
+ * @param keyOf Returns the key of one entry.
+ * @returns The value found, or `undefined` when no entry has a key.
+ * @throws {RangeError} for a `NaN` key; {@link sortBy} lists the `TypeError` cases.
+ * @example
+ * ```ts
+ * minBy([{ n: 2 }, { n: 1 }], (row) => row.n) // { n: 1 }
+ * ```
+ */
+export function minBy(collection, keyOf) {
+    return extremum(collection, keyOf, 1);
+}
+/**
+ * The value of `collection` with the largest key, by the default key order; the first one on a
+ * tie. Entries whose key is `null` or `undefined` are skipped.
+ * @param collection The collection to search.
+ * @param keyOf Returns the key of one entry.
+ * @returns The value found, or `undefined` when no entry has a key.
+ * @throws {RangeError} for a `NaN` key; {@link sortBy} lists the `TypeError` cases.
+ * @example
+ * ```ts
+ * maxBy({ a: 3, b: 7 }, (n) => n) // 7
+ * ```
+ */
+export function maxBy(collection, keyOf) {
+    return extremum(collection, keyOf, -1);
+}
+function total(collection, valueOf) {
+    let sum = 0;
+    let count = 0;
+    eachEntry(collection, (value, key) => {
+        const n = valueOf(value, key, collection);
+        if (typeof n !== 'number')
+            throw new TypeError(`expected a number, got ${typeof n}`);
+        sum += n;
+        count++;
+    });
+    return [sum, count];
+}
+/**
+ * The sum of the numbers `valueOf` returns for the entries of `collection`; `0` when empty.
+ * @param collection The collection to add up.
+ * @param valueOf Returns the number of one entry.
+ * @returns The sum.
+ * @throws {TypeError} when `valueOf` returns anything but a number.
+ * @example
+ * ```ts
+ * sumBy([{ n: 4 }, { n: 2 }], (row) => row.n) // 6
+ * ```
+ */
+export function sumBy(collection, valueOf) {
+    return total(collection, valueOf)[0];
+}
+/**
+ * The mean of the numbers `valueOf` returns for the entries of `collection`; `NaN` when empty.
+ * @param collection The collection to average.
+ * @param valueOf Returns the number of one entry.
+ * @returns The mean.
+ * @throws {TypeError} when `valueOf` returns anything but a number.
+ * @example
+ * ```ts
+ * meanBy([{ n: 4 }, { n: 2 }], (row) => row.n) // 3
+ * ```
+ */
+export function meanBy(collection, valueOf) {
+    const [sum, count] = total(collection, valueOf);
+    return sum / count;
+}

package/dist/collections/heap.d.ts

@@ -0,0 +1,64 @@
+/**
+ * A binary min-heap: `peek` and `pop` give the smallest item by the comparator, so a reversed
+ * comparator makes a max-heap. Iteration is in heap order, not sorted order. `has` and `delete`
+ * use SameValueZero, as `Set` does. A comparator that throws leaves the heap unchanged, and a `push`
+ * of several items then adds none of them. With the default comparator, items are numbers, bigints
+ * or strings, checked as they enter: `NaN` throws `RangeError`, and `null`, `undefined` and other
+ * values throw `TypeError`; pass a comparator to order them.
+ *
+ * @example
+ * ```ts
+ * const heap = new Heap([5, 1, 3])
+ * heap.push(2)
+ * heap.pop() // 1
+ * heap.peek() // 2
+ * ```
+ */
+export declare class Heap<T> {
+    #private;
+    /**
+     * Build a heap from `items` in linear time.
+     * @param items Initial items, copied. `null` means none.
+     * @param compareFn Comparator; the smallest item comes out first. Defaults to the primitive
+     * order (numbers, bigints and strings).
+     * @throws {TypeError} when `items` is not iterable, `compareFn` is not a function, or the default
+     * comparator cannot order an item.
+     * @throws {RangeError} when `items` is a huge sparse array, or holds `NaN` under the default
+     * comparator.
+     */
+    constructor(items?: Iterable<T> | null, compareFn?: ((a: T, b: T) => number) | null);
+    /** The number of items. */
+    get size(): number;
+    /** `'Heap'`, for `Object.prototype.toString`. */
+    get [Symbol.toStringTag](): string;
+    /**
+     * Add one or more items. When the comparator throws, none of them is added.
+     * @returns The new size.
+     * @throws {TypeError} when the default comparator cannot order an item.
+     * @throws {RangeError} when an item is `NaN` under the default comparator.
+     */
+    push(...items: T[]): number;
+    /** Remove and return the smallest item, or `undefined` when empty. */
+    pop(): T | undefined;
+    /** The smallest item without removing it, or `undefined` when empty. */
+    peek(): T | undefined;
+    /** Whether `item` is in the heap (SameValueZero). */
+    has(item: T): boolean;
+    /**
+     * Remove one occurrence of `item` (SameValueZero).
+     * @returns Whether it was present.
+     */
+    delete(item: T): boolean;
+    /** Remove every item. */
+    clear(): void;
+    /** The items, in heap order. */
+    values(): IteratorObject<T>;
+    /** The items, in heap order, as `Set.prototype.keys` gives them. */
+    keys(): IteratorObject<T>;
+    /** `[item, item]` pairs, in heap order, as `Set.prototype.entries` gives them. */
+    entries(): IteratorObject<[T, T]>;
+    /** Call `callback(item, item, heap)` for each item, in heap order. */
+    forEach(callback: (value: T, key: T, heap: this) => void, thisArg?: unknown): void;
+    /** The items, in heap order. */
+    [Symbol.iterator](): IteratorObject<T>;
+}