@bodil/monkey-business 0.3.3 → 0.3.5

package/src/index.ts

@@ -1,37 +1,27 @@
-/* eslint-disable jsdoc/no-undefined-types */
-/* eslint-disable @typescript-eslint/no-this-alias */
-// deno-lint-ignore-file no-this-alias
-
-import { None, Option, Some } from "@bodil/opt";
-import { type OrderFn, bisectHigh, bisectLow } from "@bodil/core/order";
+import type { OrderFn } from "@bodil/core/order";
 import type { Present } from "@bodil/core/types";
-import { assert } from "@bodil/core/assert";
+import type { Option } from "@bodil/opt";
 import defineProperties from "define-properties";
 import shimUnscopables from "es-shim-unscopables";
 
-import "es-iterator-helpers/Iterator.concat/auto";
-import "es-iterator-helpers/Iterator.zip/auto";
-import "es-iterator-helpers/Iterator.zipKeyed/auto";
+import * as array from "./array";
+import * as iterator from "./iterator";
+import * as map from "./map";
+import * as object from "./object";
+import * as weakmap from "./weakmap";
 
 declare global {
     /**
      * Added methods on the {@link Object} global object.
      */
     interface ObjectConstructor {
-        /**
-         * Checked key lookup. Returns {@link None} if a key isn't present.
-         * Returns a {@link Some} if the key is present, even if the value is
-         * `undefined`.
-         */
+        /** {@inheritDoc object.get} */
         get<O extends object, K extends keyof O>(obj: O, key: K): Option<O[K]>;
 
-        /**
-         * Create a new object by mapping an existing object's `Object.entries`
-         * through a function.
-         */
+        /** {@inheritDoc object.mapEntries} */
         mapEntries<A, B>(
             obj: Record<string, A>,
-            fn: (entry: [key: string, value: A]) => [string, B]
+            fn: (entry: [key: string, value: A]) => [string, B],
         ): Record<string, B>;
     }
 
@@ -39,19 +29,13 @@ declare global {
      * Added methods on {@link Map}s.
      */
     interface Map<K, V> {
-        /**
-         * If `key` exists in the map, return the value associated with it.
-         * Otherwise, call `defaultValue()` to create a new value, insert that
-         * into the map under `key`, and return it.
-         */
+        /** {@inheritDoc map.getOrInsertComputed} */
         getOrInsertComputed(key: K, defaultValue: (key: K) => V): V;
 
-        /**
-         * If `key` exists in the map, remove the key/value pair from the map
-         * and return the removed value. Otherwise, return {@link None}.
-         *
-         * @see {@link Map.delete}
-         */
+        /** {@inheritDoc map.getOrSet} */
+        getOrSet(key: K, defaultValue: (key: K) => V): V;
+
+        /** {@inheritDoc map.remove} */
         remove(key: K): Option<V>;
     }
 
@@ -59,19 +43,13 @@ declare global {
      * Added methods on {@link WeakMap}s.
      */
     interface WeakMap<K extends WeakKey, V> {
-        /**
-         * If `key` exists in the map, return the value associated with it.
-         * Otherwise, call `defaultValue()` to create a new value, insert that
-         * into the map under `key`, and return it.
-         */
+        /** {@inheritDoc weakmap.getOrInsertComputed} */
         getOrInsertComputed(key: K, defaultValue: (key: K) => V): V;
 
-        /**
-         * If `key` exists in the map, remove the key/value pair from the map
-         * and return the removed value. Otherwise, return {@link None}.
-         *
-         * @see {@link WeakMap.delete}
-         */
+        /** {@inheritDoc weakmap.getOrSet} */
+        getOrSet(key: K, defaultValue: (key: K) => V): V;
+
+        /** {@inheritDoc weakmap.remove} */
         remove(key: K): Option<V>;
     }
 
@@ -79,69 +57,31 @@ declare global {
      * Added methods on {@link Array}s.
      */
     interface Array<T> {
-        /**
-         * Insert `value` at `index` in the array.
-         */
+        /** {@inheritDoc array.insert} */
         insert(value: T, index: number): Array<T>;
 
-        /**
-         * Insert `value` into the array at the correct position according to
-         * the ordering function `cmp`. The array must already be ordered
-         * accordingly.
-         *
-         * If `duplicates` is `"low"`, the correct position in case of
-         * duplicates is considered to be the index of the first occurrence of a
-         * duplicate. If it is `"high"`, which is the default, the correct
-         * position is considered to be the index after the last occurrence of a
-         * duplicate.
-         */
+        /** {@inheritDoc array.insertOrdered} */
         insertOrdered(value: T, cmp: OrderFn<T>, duplicates?: "low" | "high"): Array<T>;
 
-        /**
-         * Remove the first occurrence of a given value from an array.
-         *
-         * Returns an {@link Option} containing the removed value, or {@link None} if
-         * no matches were found.
-         */
+        /** {@inheritDoc array.remove} */
         remove(value: T): Option<T>;
 
-        /**
-         * Remove the first value for which the provided predicate function
-         * returns `true` from the array.
-         *
-         * Returns an {@link Option} containing the removed value, or {@link None} if
-         * no matches were found.
-         */
+        /** {@inheritDoc array.removeFn} */
         removeFn(predicate: (value: T, index: number, obj: Array<T>) => boolean): Option<T>;
 
-        /**
-         * Remove the value at the given index from the array.
-         *
-         * Returns an {@link Option} containing the removed value, or {@link None} if
-         * the index was out of bounds.
-         */
+        /** {@inheritDoc array.removeIndex} */
         removeIndex(index: number): Option<T>;
 
-        /**
-         * Return a copy of the array with any `undefined` values removed.
-         */
+        /** {@inheritDoc array.present} */
         present(): Array<Present<T>>;
 
-        /**
-         * Return a copy of the array with any `null` or `undefined` values removed.
-         */
+        /** {@inheritDoc array.nonNullable} */
         nonNullable(): Array<NonNullable<T>>;
 
-        /**
-         * Checked index operator. Returns {@link None} if an index isn't
-         * present, even for sparse arrays. Returns a {@link Some} if the index
-         * is present, even if the value is `undefined`.
-         */
+        /** {@inheritDoc array.get} */
         get(index: number): Option<T>;
 
-        /**
-         * Test whether a value is an array with the same contents as this one.
-         */
+        /** {@inheritDoc array.equals} */
         equals<U = unknown>(other: unknown, equalsFn?: (a: T, b: U) => boolean): other is Array<T>;
     }
 
@@ -149,22 +89,13 @@ declare global {
      * Added methods on the {@link Iterator} global object.
      */
     interface IteratorConstructor {
-        /**
-         * Construct an empty iterator.
-         */
+        /** {@inheritDoc iterator.empty} */
         empty<T>(): IteratorObject<T>;
-        /**
-         * Sequence multiple iterators into a single one.
-         * @see https://github.com/tc39/proposal-iterator-sequencing
-         */
+        /** {@inheritDoc iterator.concat} */
         concat<T>(...inputs: Array<Iterable<T>>): IteratorObject<T>;
-        /**
-         * @see https://github.com/tc39/proposal-joint-iteration
-         */
+        /** {@inheritDoc iterator.zip} */
         zip<T>(inputs: Iterable<Iterable<T>>): IteratorObject<Array<T>>;
-        /**
-         * @see https://github.com/tc39/proposal-joint-iteration
-         */
+        /** {@inheritDoc iterator.zipKeyed} */
         zipKeyed<T>(inputs: Record<string, Iterable<T>>): IteratorObject<Record<string, T>>;
     }
 
@@ -173,61 +104,32 @@ declare global {
      */
     // eslint-disable-next-line @typescript-eslint/no-unused-vars
     interface IteratorObject<T, TReturn, TNext> {
-        /**
-         * Get the next value from the iterator, wrapped in an {@link Option}
-         * type. If the iterator has no more values, return {@link None}.
-         */
+        /** {@inheritDoc iterator.takeOne} */
         takeOne(): Option<T>;
-        /**
-         * Take items from the iterator only until the first time `predicate` returns false.
-         */
+        /** {@inheritDoc iterator.takeWhile} */
         takeWhile<S extends T>(
-            predicate: (value: T, index: number) => value is S
+            predicate: (value: T, index: number) => value is S,
         ): IteratorObject<S, undefined>;
         /** @ignore */
         takeWhile(predicate: (value: T, index: number) => boolean): IteratorObject<T, undefined>;
-        /**
-         * Ignore all items matching `predicate` until the first item that
-         * doesn't match.
-         */
+        /** {@inheritDoc iterator.skipWhile} */
         skipWhile(predicate: (value: T, index: number) => boolean): IteratorObject<T, undefined>;
-        /**
-         * Iterate until calling `mapFn` on an item returns a value, then return
-         * that value. Return `undefined` if `mapFn` never returns a value.
-         */
+        /** {@inheritDoc iterator.findMap} */
         findMap<U>(mapFn: (value: T) => NonNullable<U> | undefined): NonNullable<U> | undefined;
-        /**
-         * Split the input up into arrays of at most `size` items.
-         */
+        /** {@inheritDoc iterator.chunks} */
+        chunks(size: number): IteratorObject<Array<T>, undefined>;
+        /** {@inheritDoc iterator.partition} */
         partition(size: number): IteratorObject<Array<T>, undefined>;
-        /**
-         * As {@link IteratorObject#partition}, but if the input length isn't
-         * divisible by `size`, ensure the *first* array is the shortest one
-         * rather than the last.
-         *
-         * Be warned that this requires the entire input iterable to be read up
-         * front to decide its length, so this function is not lazy.
-         */
+        /** {@inheritDoc iterator.frontBiasedPartition} */
         frontBiasedPartition(size: number): Array<Array<T>>;
-        /**
-         * Filter out any items which are `undefined`.
-         */
+        /** {@inheritDoc iterator.present} */
         present(): IteratorObject<Present<T>, undefined>;
-        /**
-         * Filter out any items which are `null` or `undefined`.
-         */
+        /** {@inheritDoc iterator.nonNullable} */
         nonNullable(): IteratorObject<NonNullable<T>, undefined>;
-        /**
-         * Test whether the given Iterable has the same contents as this
-         * iterator.
-         *
-         * Note that this will consume this iterator up to the point
-         * where the values diverge. You should not rely on any particular state
-         * of the iterator afterwards, but consider it spent.
-         */
+        /** {@inheritDoc iterator.equals} */
         equals<T = unknown, U = unknown>(
             value: Iterable<U>,
-            equalsFn?: (a: T, b: U) => boolean
+            equalsFn?: (a: T, b: U) => boolean,
         ): boolean;
     }
 }
@@ -235,133 +137,38 @@ declare global {
 // Object
 
 defineProperties(Object, {
-    get<O extends object, K extends keyof O>(obj: O, key: K): Option<O[K]> {
-        return Object.hasOwn(obj, key) ? Some(obj[key]) : None;
-    },
-
-    mapEntries<A, B>(
-        obj: Record<string, A>,
-        fn: (entry: [key: string, value: A]) => [string, B]
-    ): Record<string, B> {
-        return Object.fromEntries(Object.entries(obj).map(fn));
-    },
+    get: object.get,
+    mapEntries: object.mapEntries,
 });
 
 // Map
 
 defineProperties(Map.prototype, {
-    getOrInsertComputed<K, V>(
-        this: Map<K, NonNullable<V>>,
-        key: K,
-        defaultValue: (key: K) => NonNullable<V>
-    ): V {
-        const result = this.get(key);
-        if (result !== undefined) {
-            return result;
-        }
-        const newValue = defaultValue(key);
-        this.set(key, newValue);
-        return newValue;
-    },
-    remove<K, V>(this: Map<K, V>, key: K): Option<V> {
-        const result = this.get(key);
-        return this.delete(key) ? Some(result!) : None;
-    },
+    getOrInsertComputed: map.getOrInsertComputed,
+    getOrSet: map.getOrSet,
+    remove: map.remove,
 });
 
 // WeakMap
 
 defineProperties(WeakMap.prototype, {
-    getOrInsertComputed<K extends WeakKey, V>(
-        this: WeakMap<K, NonNullable<V>>,
-        key: K,
-        defaultValue: (key: K) => NonNullable<V>
-    ): V {
-        const result = this.get(key);
-        if (result !== undefined) {
-            return result;
-        }
-        const newValue = defaultValue(key);
-        this.set(key, newValue);
-        return newValue;
-    },
-    remove<K extends WeakKey, V>(this: WeakMap<K, V>, key: K): Option<V> {
-        const result = this.get(key);
-        return this.delete(key) ? Some(result!) : None;
-    },
+    getOrInsertComputed: weakmap.getOrInsertComputed,
+    getOrSet: weakmap.getOrSet,
+    remove: weakmap.remove,
 });
 
 // Array
 
 defineProperties(Array.prototype, {
-    remove<T>(this: Array<T>, value: T): Option<T> {
-        return this.removeIndex(this.indexOf(value));
-    },
-
-    removeFn<T>(
-        this: Array<T>,
-        predicate: (value: T, index: number, obj: Array<T>) => boolean
-    ): Option<T> {
-        return this.removeIndex(this.findIndex(predicate as () => boolean));
-    },
-
-    removeIndex<T>(this: Array<T>, index: number): Option<T> {
-        if (!Number.isInteger(index)) {
-            throw new TypeError(`Array.removeIndex(): index ${index} is not an integer`);
-        }
-        if (index < 0 || index >= this.length) {
-            return None;
-        }
-        const removed = this.splice(index, 1).pop();
-        return Option.from(removed);
-    },
-
-    insert<T>(this: Array<T>, value: T, index: number): Array<T> {
-        if (!Number.isInteger(index)) {
-            throw new TypeError(`Array.insert(): index ${index} is not an integer`);
-        }
-        if (index > this.length || index < 0) {
-            throw new RangeError(`Array.insert: index ${index} out of bounds`);
-        }
-        this.splice(index, 0, value);
-        return this;
-    },
-
-    insertOrdered<T>(
-        this: Array<T>,
-        value: T,
-        cmp: OrderFn<T>,
-        duplicates: "low" | "high" = "high"
-    ): Array<T> {
-        return this.insert(
-            value,
-            (duplicates === "low" ? bisectLow : bisectHigh)(cmp, this, value)
-        );
-    },
-
-    present<T>(this: Array<T>): Array<Present<T>> {
-        return this.filter((value: T): value is Present<T> => value !== undefined);
-    },
-
-    nonNullable<T>(this: Array<T>): Array<NonNullable<T>> {
-        return this.filter((value: T): value is NonNullable<T> => value !== undefined);
-    },
-
-    get<T>(this: Array<T>, index: number): Option<T> {
-        return Object.get(this, index);
-    },
-
-    equals<T, U = unknown>(
-        this: Array<T>,
-        other: unknown,
-        equalsFn?: (a: T, b: U) => boolean
-    ): other is Array<T> {
-        return (
-            Array.isArray(other) &&
-            this.length === other.length &&
-            Iterator.from(this).equals(other, equalsFn)
-        );
-    },
+    remove: array.remove,
+    removeFn: array.removeFn,
+    removeIndex: array.removeIndex,
+    insert: array.insert,
+    insertOrdered: array.insertOrdered,
+    present: array.present,
+    nonNullable: array.nonNullable,
+    get: array.get,
+    equals: array.equals,
 });
 
 shimUnscopables("remove");
@@ -377,158 +184,22 @@ shimUnscopables("equals");
 // Iterator
 
 defineProperties(Iterator, {
-    empty<T>(): IteratorObject<T> {
-        return Iterator.from([]);
-    },
+    empty: iterator.empty,
+    concat: iterator.concat,
+    zip: iterator.zip,
+    zipKeyed: iterator.zipKeyed,
 });
 
 defineProperties(Iterator.prototype, {
-    takeOne<T>(this: Iterator<T>): Option<T> {
-        const result = this.next();
-        return result.done === true ? None : Some(result.value);
-    },
-
-    takeWhile<T>(
-        this: IteratorObject<T, undefined>,
-        predicate: (value: T, index: number) => boolean
-    ): IteratorObject<T, undefined> {
-        const iter = this;
-        let index = 0;
-        let done = false;
-        return Iterator.from<T>({
-            next(): IteratorResult<T, undefined> {
-                if (!done) {
-                    const result = iter.next();
-                    if (result.done === true) {
-                        return result;
-                    }
-                    if (predicate(result.value, index++)) {
-                        return result;
-                    }
-                }
-                done = true;
-                return { done: true, value: undefined };
-            },
-        });
-    },
-
-    skipWhile<T>(
-        this: IteratorObject<T, undefined>,
-        predicate: (value: T, index: number) => boolean
-    ): IteratorObject<T, undefined> {
-        const iter = this;
-        let index = 0;
-        let skipped = false;
-        return Iterator.from<T>({
-            next(): IteratorResult<T, undefined> {
-                if (skipped) {
-                    return iter.next();
-                }
-                while (true) {
-                    const result = iter.next();
-                    if (result.done === true) {
-                        return result;
-                    }
-                    if (!predicate(result.value, index++)) {
-                        skipped = true;
-                        return result;
-                    }
-                }
-            },
-        });
-    },
-
-    findMap<T, U>(
-        this: IteratorObject<T, undefined>,
-        mapFn: (value: T, index: number) => NonNullable<U> | undefined
-    ): NonNullable<U> | undefined {
-        let index = 0;
-        while (true) {
-            const result = this.next();
-            if (result.done === true) {
-                return undefined;
-            }
-            const mapped = mapFn(result.value, index++);
-            if (mapped !== undefined) {
-                return mapped;
-            }
-        }
-    },
-
-    partition<T>(
-        this: IteratorObject<T, undefined>,
-        size: number
-    ): IteratorObject<Array<T>, undefined> {
-        const iter = this;
-        let done = false;
-        return Iterator.from<Array<T>>({
-            next(): IteratorResult<Array<T>, undefined> {
-                if (done) {
-                    return { done: true, value: undefined };
-                }
-                const part = [];
-                while (true) {
-                    const result = iter.next();
-                    if (result.done === true) {
-                        done = true;
-                        return part.length > 0
-                            ? { done: false, value: part }
-                            : { done: true, value: undefined };
-                    }
-                    part.push(result.value);
-                    if (part.length === size) {
-                        return { done: false, value: part };
-                    }
-                }
-            },
-        });
-    },
-
-    frontBiasedPartition<T>(this: IteratorObject<T, undefined>, size: number): Array<Array<T>> {
-        const input = this.toArray();
-        let inputPos = 0;
-        const firstLength = input.length % size;
-        const output: Array<Array<T>> = [];
-        if (firstLength > 0) {
-            output.push(input.slice(0, firstLength));
-            inputPos = firstLength;
-        }
-        while (inputPos < input.length) {
-            output.push(input.slice(inputPos, inputPos + size));
-            inputPos += size;
-        }
-        assert(inputPos === input.length);
-        return output;
-    },
-
-    present<T>(this: IteratorObject<T, undefined>): IteratorObject<Present<T>, undefined> {
-        return Iterator.from(this.filter((item): item is Present<T> => item !== undefined));
-    },
-
-    nonNullable<T>(this: IteratorObject<T, undefined>): IteratorObject<NonNullable<T>, undefined> {
-        return Iterator.from(
-            this.filter((item): item is NonNullable<T> => item !== undefined && item !== null)
-        );
-    },
-
-    equals(
-        this: IteratorObject<unknown, undefined>,
-        value: Iterable<unknown>,
-        equalsFn: (a: unknown, b: unknown) => boolean = Object.is
-    ): boolean {
-        const other = Iterator.from(value);
-        while (true) {
-            const a = this.next();
-            const b = other.next();
-            if (
-                a.done !== b.done ||
-                (a.done === false && b.done === false && !equalsFn(a.value, b.value as any))
-            ) {
-                return false;
-            }
-            if (a.done === true && b.done === true) {
-                return true;
-            }
-        }
-    },
+    chunks: iterator.chunks,
+    takeOne: iterator.takeOne,
+    takeWhile: iterator.takeWhile,
+    skipWhile: iterator.skipWhile,
+    findMap: iterator.findMap,
+    // eslint-disable-next-line @typescript-eslint/no-deprecated
+    partition: iterator.partition,
+    frontBiasedPartition: iterator.frontBiasedPartition,
+    present: iterator.present,
+    nonNullable: iterator.nonNullable,
+    equals: iterator.equals,
 });