@bodil/monkey-business 0.3.3 → 0.3.5

package/src/iterator.ts

@@ -0,0 +1,223 @@
+/* eslint-disable @typescript-eslint/no-this-alias */
+// deno-lint-ignore-file no-this-alias
+
+import { assert } from "@bodil/core/assert";
+import type { Present } from "@bodil/core/types";
+import { None, type Option, Some } from "@bodil/opt";
+import getConcatPolyfill from "es-iterator-helpers/Iterator.concat/polyfill";
+import getChunksPolyfill from "es-iterator-helpers/Iterator.prototype.chunks/polyfill";
+import getZipPolyfill from "es-iterator-helpers/Iterator.zip/polyfill";
+import getZipKeyedPolyfill from "es-iterator-helpers/Iterator.zipKeyed/polyfill";
+
+/**
+ * Sequence multiple iterators into a single one.
+ * @see https://github.com/tc39/proposal-iterator-sequencing
+ * @function
+ */
+export const concat: <T>(...inputs: Array<Iterable<T>>) => IteratorObject<T> = getConcatPolyfill();
+
+/**
+ * @see https://github.com/tc39/proposal-joint-iteration
+ * @function
+ */
+export const zip: <T>(inputs: Iterable<Iterable<T>>) => IteratorObject<Array<T>> = getZipPolyfill();
+
+/**
+ * @see https://github.com/tc39/proposal-joint-iteration
+ * @function
+ */
+export const zipKeyed: <T>(
+    inputs: Record<string, Iterable<T>>,
+) => IteratorObject<Record<string, T>> = getZipKeyedPolyfill();
+
+/**
+ * Split the input up into arrays of at most `size` items.
+ * @function
+ */
+export const chunks: <T>(
+    this: Iterator<T>,
+    size: number,
+) => IteratorObject<Array<T>, undefined> = getChunksPolyfill();
+
+/**
+ * Construct an empty iterator.
+ */
+export function empty<T>(): IteratorObject<T> {
+    return Iterator.from([]);
+}
+
+/**
+ * Get the next value from the iterator, wrapped in an {@link Option}
+ * type. If the iterator has no more values, return {@link None}.
+ */
+export function takeOne<T>(this: Iterator<T>): Option<T> {
+    const result = this.next();
+    return result.done === true ? None : Some(result.value);
+}
+
+/**
+ * Take items from the iterator only until the first time `predicate` returns false.
+ */
+export function 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 };
+        },
+    });
+}
+
+/**
+ * Ignore all items matching `predicate` until the first item that
+ * doesn't match.
+ */
+export function 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;
+                }
+            }
+        },
+    });
+}
+
+/**
+ * Iterate until calling `mapFn` on an item returns a value, then return
+ * that value. Return `undefined` if `mapFn` never returns a value.
+ */
+export function 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;
+        }
+    }
+}
+
+/**
+ * Split the input up into arrays of at most `size` items.
+ *
+ * @deprecated This has been standardised as {@link IteratorObject#chunks}.
+ */
+export function partition<T>(
+    this: IteratorObject<T, undefined>,
+    size: number,
+): IteratorObject<Array<T>, undefined> {
+    return (chunks<T>).call(this, size);
+}
+
+/**
+ * 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.
+ */
+export function 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;
+}
+
+/**
+ * Filter out any items which are `undefined`.
+ */
+export function present<T>(
+    this: IteratorObject<T, undefined>,
+): IteratorObject<Present<T>, undefined> {
+    return Iterator.from(this.filter((item): item is Present<T> => item !== undefined));
+}
+
+/**
+ * Filter out any items which are `null` or `undefined`.
+ */
+export function nonNullable<T>(
+    this: IteratorObject<T, undefined>,
+): IteratorObject<NonNullable<T>, undefined> {
+    return Iterator.from(
+        this.filter((item): item is NonNullable<T> => item !== undefined && item !== null),
+    );
+}
+
+/**
+ * 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.
+ */
+export function 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))
+        ) {
+            return false;
+        }
+        if (a.done === true && b.done === true) {
+            return true;
+        }
+    }
+}

package/src/map.ts

@@ -0,0 +1,37 @@
+import { None, type Option, Some } from "@bodil/opt";
+
+/**
+ * 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.
+ */
+export function 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;
+}
+
+/**
+ * Alias for {@link getOrInsertComputed}.
+ * @function
+ */
+export const getOrSet = getOrInsertComputed;
+
+/**
+ * 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}
+ */
+export function remove<K, V>(this: Map<K, V>, key: K): Option<V> {
+    const result = this.get(key);
+    return this.delete(key) ? Some(result!) : None;
+}

package/src/object.ts

@@ -0,0 +1,21 @@
+import { None, type Option, Some } from "@bodil/opt";
+
+/**
+ * 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`.
+ */
+export function get<O extends object, K extends keyof O>(obj: O, key: K): Option<O[K]> {
+    return Object.hasOwn(obj, key) ? Some(obj[key]) : None;
+}
+
+/**
+ * Create a new object by mapping an existing object's `Object.entries`
+ * through a function.
+ */
+export function 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));
+}

package/src/weakmap.ts

@@ -0,0 +1,37 @@
+import { None, type Option, Some } from "@bodil/opt";
+
+/**
+ * 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.
+ */
+export function 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;
+}
+
+/**
+ * Alias for {@link getOrInsertComputed}.
+ * @function
+ */
+export const getOrSet = getOrInsertComputed;
+
+/**
+ * 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}
+ */
+export function 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;
+}