atomic-fns 0.3.1 → 0.3.3-beta

package/core/collections/frozenset.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Returns a new immutable Set object with elements from `iterable`. Its contents cannot be altered after it's created.
+ *
+ *
+ * @class FrozenSet
+ * @extends {Set<T>}
+ * @template T
+ */
+export declare class FrozenSet<T = any> extends Set<T> {
+    constructor(iterable: Iterable<T>);
+    /** @private */
+    add(): this;
+    /** @private */
+    delete(): boolean;
+    /** @private */
+    clear(): this;
+    /** @private */
+    freeze(): Readonly<this>;
+}

package/core/collections/frozenset.js

@@ -0,0 +1,33 @@
+/**
+ * Returns a new immutable Set object with elements from `iterable`. Its contents cannot be altered after it's created.
+ *
+ *
+ * @class FrozenSet
+ * @extends {Set<T>}
+ * @template T
+ */
+export class FrozenSet extends Set {
+    constructor(iterable) {
+        super(iterable);
+        return this.freeze();
+    }
+    /** @private */
+    add() {
+        throw TypeError('FrozenSet cannot be modified.');
+        return this; // eslint-disable-line
+    }
+    /** @private */
+    delete() {
+        throw TypeError('FrozenSet cannot be modified.');
+        return false; // eslint-disable-line
+    }
+    /** @private */
+    clear() {
+        throw TypeError('FrozenSet cannot be modified.');
+        return this; // eslint-disable-line
+    }
+    /** @private */
+    freeze() {
+        return Object.freeze(this);
+    }
+}

package/core/collections/frozenset.ts

@@ -0,0 +1,37 @@
+/**
+ * Returns a new immutable Set object with elements from `iterable`. Its contents cannot be altered after it's created.
+ *
+ *
+ * @class FrozenSet
+ * @extends {Set<T>}
+ * @template T
+ */
+export class FrozenSet<T = any> extends Set<T> {
+  constructor(iterable: Iterable<T>) {
+    super(iterable)
+    return this.freeze()
+  }
+
+  /** @private */
+  add() {
+    throw TypeError('FrozenSet cannot be modified.')
+    return this // eslint-disable-line
+  }
+
+  /** @private */
+  delete() {
+    throw TypeError('FrozenSet cannot be modified.')
+    return false // eslint-disable-line
+  }
+
+  /** @private */
+  clear() {
+    throw TypeError('FrozenSet cannot be modified.')
+    return this // eslint-disable-line
+  }
+
+  /** @private */
+  freeze() {
+    return Object.freeze(this)
+  }
+}

package/{src → core}/collections/index.d.ts

@@ -4,167 +4,18 @@
  * @module Collections
  */
 import { Iteratee } from '../globals/index.js';
-/**
- * A container type that provides contains().
- *
- *
- * @interface Container
- */
-export interface Container {
-    contains: (x: any) => boolean;
-}
-/**
- * These are the "rich comparison" methods, inspired by Python operators.
- *
- *
- * @interface Comparable
- */
-export interface Comparable {
-    /** x < y: calls this.lt(other) reflection. */
-    lt?: (other: any) => boolean;
-    /** x ≤ y: calls this.le(other) reflection. */
-    le?: (other: any) => boolean;
-    /** x == y: calls this.eq(other) reflection. */
-    eq: (other: any) => boolean;
-    /** x != y: calls this.ne(other) reflection. */
-    ne: (other: any) => boolean;
-    /** x > y: calls this.gt(other) reflection. */
-    gt?: (other: any) => boolean;
-    /** x ≥ y: calls this.ge(other) reflection. */
-    ge?: (other: any) => boolean;
-}
-/**
- * A `Collection` is an iterable {@link Container} type.
- * This is an abstract base class for user-defined collection types.
- *
- *
- * @abstract
- * @class Collection
- * @implements {Container}
- */
-export declare abstract class Collection implements Container {
-    /**
-     * Returns an iterator for the container items
-     * @return {Iterator}
-     */
-    [Symbol.iterator](): this;
-    /**
-     * Implements the iterator protocol and returns the next item in the iterable.
-     */
-    next(): void;
-    /**
-     * Adds a new item to the container.
-     * @param item - The item to add to the collection.
-     */
-    add(item: any): void;
-    /**
-     * Checks if item is present in the container.
-     * @param item - The item to search for in the collection.
-     * @returns `true` when the element is found, else `false`
-     */
-    contains(item: any): boolean;
-    /**
-     * Returns the total number of elements in the container.
-     */
-    size(): number;
-    /**
-     * Remove the first item from the container where `item == x`
-     * @returns `true` when the element is found and removed, else `false`
-     */
-    remove(x: any): boolean;
-    /**
-     * Retrieve and remove the item at index `i`.
-     * @returns the item or undefined if not found.
-     */
-    pop(i: any): void;
-    /**
-     * Remove all items from the container
-     */
-    clear(): void;
-}
-/**
- * Implements an iterable that allows backward iteration.
- * @interface Reversible
- */
-export interface Reversible<T = unknown> {
-    reversed: () => Iterator<T>;
-}
-/**
- * A sequence is an iterable {@link Collection} type with efficient index-based access.
- * @abstract
- * @class Sequence
- * @extends {Collection}
- * @template T
- */
-export declare abstract class Sequence<T> extends Collection implements Reversible<T> {
-    /**
-     * Return the item at the given key or index
-     * @param {*} key
-     * @memberof Sequence
-     */
-    get(key: any): T | undefined;
-    /**
-     * Set a new value at the given key or index
-     *
-     * @param {*} key
-     * @param {T} val
-     * @memberof Sequence
-     */
-    set(key: any, val: T): void;
-    /**
-     * Deletes the given key or index, and its value.
-     * Raises ValueError if not key is found.
-     *
-     * @param {*} key
-     * @memberof Sequence
-     */
-    delete(key: any): void;
-    /**
-     * Adds a new item to the end of the sequence.
-     *
-     * @param {T} x
-     * @memberof Sequence
-     */
-    append(x: T): void;
-    /**
-     * Append all the items to the sequence.
-     *
-     * @param {Iterable<T>} iter
-     * @memberof Sequence
-     */
-    extend(iter: Iterable<T>): void;
-    /**
-     * Return the index of x in the sequence, or undefined if not found.
-     *
-     * @param {T} item
-     * @return {(number | undefined)}
-     * @memberof Sequence
-     */
-    indexOf(item: T): number | undefined;
-    size(): number;
-    reversed(): Iterator<T>;
-}
-/**
- * Returns a new immutable Set object with elements from `iterable`. Its contents cannot be altered after it's created.
- *
- *
- * @class FrozenSet
- * @extends {Set<T>}
- * @template T
- */
-export declare class FrozenSet<T = any> extends Set<T> {
-    constructor(iterable: Iterable<T>);
-    /** @private */
-    add(): this;
-    /** @private */
-    delete(): boolean;
-    /** @private */
-    clear(): this;
-    /** @private */
-    freeze(): Readonly<this>;
-}
-/**
- * Creates a new array with all `falsey` and empty values removed.
+export * from './abc.js';
+export * from './BTree.js';
+export * from './deque.js';
+export * from './frozenset.js';
+export * from './Heap.js';
+export * from './LRUCache.js';
+export * from './SortedSet.js';
+export * from './SortedMap.js';
+export * from './SortedTree.js';
+export * from './SplayTree.js';
+/**
+ * Creates a new array with all falsy and empty values removed.
  * @param arr The array to compact
  * @returns A new array with the filtered values.
  * @example
@@ -256,6 +107,17 @@ findRight([1, 2, 3, 4], (n) => n % 2 === 1)
  * @see {@link find}
  */
 export declare function findRight(arr: any, fn: Iteratee | PropertyKey | Object): any;
+/**
+ * Performs an efficient array insert operation in the given array. If the index or the array is invalid, it just returns the given array.
+ *
+ * **Note:** Uses the same behavior as `Array.splice`.
+ *
+ * @param {Array<*>} arr The given array to insert into
+ * @param {number} index The index of the array insert operation.
+ * @param {*} value The value to insert in the array at the given `index`.
+ * @returns {Array<*>} The given array.
+ */
+export declare function insert(arr: any[], index: number, value: any): any[];
 /**
  * Creates a function that performs a partial deep comparison between a given object and `shape`, returning `true` if the given object has equivalent property values, else `false`.
  * @example
@@ -650,7 +512,7 @@ export declare function union(...args: Array<Iterable<any>>): Generator<unknown,
  *
  * @param arr The collection to iterate over.
  * @param [func=id] The iteratee to transform keys.
- * @returns Returns the composed aggregate object.
+ * @returns Returns the aggregated object.
  *
  * @example
 ```js
@@ -663,6 +525,25 @@ groupBy(['one', 'two', 'three'], 'length')
 ```
  */
 export declare function groupBy(arr: Iterable<any> | Object, func?: Iteratee | PropertyKey): Object;
+/**
+ * Similar to {@link groupBy} but it returns a {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map Map} object with the results.
+ *
+ * @param arr The collection to iterate over.
+ * @param {Function | PropertyKey} [func=id] The iteratee to transform keys.
+ * @returns {Map} Returns the aggregated map object.
+ * @template K, V
+ *
+ * @example
+```js
+groupByMap([6.1, 4.2, 6.3], Math.floor)
+// => Map { 4: [4.2], 6: [6.1, 6.3] }
+
+// The `property` iteratee shorthand.
+groupByMap(['one', 'two', 'three'], 'length')
+// => Map { 3: ['one', 'two'], 5: ['three'] }
+```
+ */
+export declare function groupByMap<K = any, V = any>(arr: Iterable<any> | Object, func?: Iteratee | PropertyKey): Map<K, V[]>;
 /**
  * Removes all elements from array that `func` returns truthy for and returns an array of the removed elements.
  * @param arr The array to remove from.

package/{src → core}/collections/index.js

@@ -4,166 +4,19 @@
  * @module Collections
  */
 import { partial } from '../functools/index.js';
-import { call, get, isArray, isArrayLike, isBool, isEmpty, isFunc, isIterable, isNull, isNumber, isObject, isString, isSymbol, keys, NotImplementedError, set } from '../globals/index.js';
+import { call, get, isArray, isArrayLike, isBool, isEmpty, isFunc, isIterable, isNull, isNumber, isObject, isString, isSymbol, keys, set } from '../globals/index.js';
 import { enumerate } from '../itertools/index.js';
-import { comp, eq, id } from '../operators/index.js';
-/**
- * A `Collection` is an iterable {@link Container} type.
- * This is an abstract base class for user-defined collection types.
- *
- *
- * @abstract
- * @class Collection
- * @implements {Container}
- */
-export class Collection {
-    /**
-     * Returns an iterator for the container items
-     * @return {Iterator}
-     */
-    [Symbol.iterator]() {
-        return this;
-    }
-    /**
-     * Implements the iterator protocol and returns the next item in the iterable.
-     */
-    next() { }
-    /**
-     * Adds a new item to the container.
-     * @param item - The item to add to the collection.
-     */
-    add(item) { }
-    /**
-     * Checks if item is present in the container.
-     * @param item - The item to search for in the collection.
-     * @returns `true` when the element is found, else `false`
-     */
-    contains(item) {
-        return false;
-    }
-    /**
-     * Returns the total number of elements in the container.
-     */
-    size() {
-        throw new NotImplementedError();
-    }
-    /**
-     * Remove the first item from the container where `item == x`
-     * @returns `true` when the element is found and removed, else `false`
-     */
-    remove(x) {
-        return false;
-    }
-    /**
-     * Retrieve and remove the item at index `i`.
-     * @returns the item or undefined if not found.
-     */
-    pop(i) { }
-    /**
-     * Remove all items from the container
-     */
-    clear() { }
-}
-/**
- * A sequence is an iterable {@link Collection} type with efficient index-based access.
- * @abstract
- * @class Sequence
- * @extends {Collection}
- * @template T
- */
-export class Sequence extends Collection {
-    /**
-     * Return the item at the given key or index
-     * @param {*} key
-     * @memberof Sequence
-     */
-    get(key) {
-        throw new NotImplementedError();
-    }
-    /**
-     * Set a new value at the given key or index
-     *
-     * @param {*} key
-     * @param {T} val
-     * @memberof Sequence
-     */
-    set(key, val) {
-        throw new NotImplementedError();
-    }
-    /**
-     * Deletes the given key or index, and its value.
-     * Raises ValueError if not key is found.
-     *
-     * @param {*} key
-     * @memberof Sequence
-     */
-    delete(key) {
-        throw new NotImplementedError();
-    }
-    /**
-     * Adds a new item to the end of the sequence.
-     *
-     * @param {T} x
-     * @memberof Sequence
-     */
-    append(x) { }
-    /**
-     * Append all the items to the sequence.
-     *
-     * @param {Iterable<T>} iter
-     * @memberof Sequence
-     */
-    extend(iter) { }
-    /**
-     * Return the index of x in the sequence, or undefined if not found.
-     *
-     * @param {T} item
-     * @return {(number | undefined)}
-     * @memberof Sequence
-     */
-    indexOf(item) {
-        throw new NotImplementedError();
-    }
-    size() {
-        return 0;
-    }
-    reversed() {
-        throw new NotImplementedError();
-    }
-}
-/**
- * Returns a new immutable Set object with elements from `iterable`. Its contents cannot be altered after it's created.
- *
- *
- * @class FrozenSet
- * @extends {Set<T>}
- * @template T
- */
-export class FrozenSet extends Set {
-    constructor(iterable) {
-        super(iterable);
-        return this.freeze();
-    }
-    /** @private */
-    add() {
-        throw TypeError('FrozenSet cannot be modified.');
-        return this; // eslint-disable-line
-    }
-    /** @private */
-    delete() {
-        throw TypeError('FrozenSet cannot be modified.');
-        return false; // eslint-disable-line
-    }
-    /** @private */
-    clear() {
-        throw TypeError('FrozenSet cannot be modified.');
-        return this; // eslint-disable-line
-    }
-    /** @private */
-    freeze() {
-        return Object.freeze(this);
-    }
-}
+import { compare, eq, id } from '../operators/index.js';
+export * from './abc.js';
+export * from './BTree.js';
+export * from './deque.js';
+export * from './frozenset.js';
+export * from './Heap.js';
+export * from './LRUCache.js';
+export * from './SortedSet.js';
+export * from './SortedMap.js';
+export * from './SortedTree.js';
+export * from './SplayTree.js';
 export function compact(arr) {
     if (arr == null)
         return;
@@ -303,6 +156,22 @@ export function findRight(arr, fn) {
         }
     }
 }
+/**
+ * Performs an efficient array insert operation in the given array. If the index or the array is invalid, it just returns the given array.
+ *
+ * **Note:** Uses the same behavior as `Array.splice`.
+ *
+ * @param {Array<*>} arr The given array to insert into
+ * @param {number} index The index of the array insert operation.
+ * @param {*} value The value to insert in the array at the given `index`.
+ * @returns {Array<*>} The given array.
+ */
+export function insert(arr, index, value) {
+    if (!arr || arr.length <= index || index < 0)
+        return arr;
+    arr.splice(index, 0, value);
+    return arr;
+}
 /**
  * Creates a function that performs a partial deep comparison between a given object and `shape`, returning `true` if the given object has equivalent property values, else `false`.
  * @example
@@ -852,7 +721,7 @@ uniq([2, 1, 2])
  */
 export function sortedUniq(arr, fn = id) {
     const values = uniq(arr, fn);
-    values.sort(comp);
+    values.sort(compare);
     return values;
 }
 function baseMergeDeep(obj, source, key, stack) {
@@ -1045,7 +914,7 @@ export function* union(...args) {
  *
  * @param arr The collection to iterate over.
  * @param [func=id] The iteratee to transform keys.
- * @returns Returns the composed aggregate object.
+ * @returns Returns the aggregated object.
  *
  * @example
 ```js
@@ -1068,6 +937,35 @@ export function groupBy(arr, func = id) {
     });
     return results;
 }
+/**
+ * Similar to {@link groupBy} but it returns a {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map Map} object with the results.
+ *
+ * @param arr The collection to iterate over.
+ * @param {Function | PropertyKey} [func=id] The iteratee to transform keys.
+ * @returns {Map} Returns the aggregated map object.
+ * @template K, V
+ *
+ * @example
+```js
+groupByMap([6.1, 4.2, 6.3], Math.floor)
+// => Map { 4: [4.2], 6: [6.1, 6.3] }
+
+// The `property` iteratee shorthand.
+groupByMap(['one', 'two', 'three'], 'length')
+// => Map { 3: ['one', 'two'], 5: ['three'] }
+```
+ */
+export function groupByMap(arr, func = id) {
+    const results = new Map();
+    const useKey = typeof func === 'function' ? func : partial(get, func);
+    forEach(arr, (value) => {
+        const groupKey = useKey(value);
+        const values = results.get(groupKey) || [];
+        values.push(value);
+        results.set(groupKey, values);
+    });
+    return results;
+}
 /**
  * Removes all elements from array that `func` returns truthy for and returns an array of the removed elements.
  * @param arr The array to remove from.
@@ -1084,8 +982,4 @@ export function remove(arr, func) {
     });
 }
 // TODO: binary search utils
-// TODO: heap/heapify
-// TODO: deque
 // TODO: Counter
-// TODO: Skip list
-// TODO: BST (BTree)