atomic-fns 0.3.3 → 0.3.5

package/core/collections/deque.js

@@ -4,36 +4,39 @@ import { eq } from '../operators/index.js';
 import { Sequence } from './abc.js';
 /**
  * Fixed capacity double-ended queue implemented as ring deque.
- *
- * @constructor
+ * @template T
  */
 export class Deque extends Sequence {
     items;
     start = 0;
     count = 0;
     capacity;
-    ArrayClass;
-    constructor(ArrayClass = [], capacity = 1024) {
+    ArrayConstructor;
+    /**
+     * Creates a new `Deque` instance of a fixed size.
+     * @param {Array} [arrType = []] The initial elements or array type to use (accepts any kind of typed array).
+     * @param {number} [capacity=1024] The fixed size of the deque. Defaults to `1024`.
+     */
+    constructor(arrType = [], capacity = 1024) {
         super();
         if (typeof capacity !== 'number' || capacity <= 0)
             throw new ValueError(`Deque capacity should be a positive integer.`);
-        this.ArrayClass = ArrayClass.constructor;
+        this.ArrayConstructor = arrType.constructor;
         this.capacity = capacity;
-        this.items = new this.ArrayClass(ArrayClass.length || this.capacity);
+        this.items = new this.ArrayConstructor(arrType.length || this.capacity);
         this.clear();
-        if (ArrayClass.length) {
-            for (const item of ArrayClass) {
+        if (arrType.length) {
+            for (const item of arrType) {
                 this.append(item);
             }
         }
     }
+    /** Returns the total number of elements in the deque. */
     get size() {
         return this.count;
     }
     /**
      * Method used to clear the structure.
-     *
-     * @return {undefined}
      */
     clear() {
         // Properties
@@ -42,18 +45,16 @@ export class Deque extends Sequence {
     }
     /**
      * Alias of {@link Deque.append}
-     *
-     * @param  {any}    item - Item to append.
-     * @return {number}      - Returns the new size of the deque.
+     * @param {T} item Item to append.
+     * @returns {number} Returns the new size of the deque.
      */
     add(item) {
         return this.append(item);
     }
     /**
-     * Method used to append a value to the deque.
-     *
-     * @param  {any}    item - Item to append.
-     * @return {number}      - Returns the new size of the deque.
+     * Appends a new element to the end of the deque.
+     * @param {T} item Item to append.
+     * @returns {number} Returns the new size of the deque.
      */
     append(item) {
         if (this.count === this.capacity)
@@ -63,10 +64,9 @@ export class Deque extends Sequence {
         return ++this.count;
     }
     /**
-     * Method used to prepend a value to the deque.
-     *
-     * @param  {any}    item - Item to prepend.
-     * @return {number}      - Returns the new size of the deque.
+     * Appends a new element to the beginning of the deque.
+     * @param {T} item Item to prepend.
+     * @returns {number} Returns the new size of the deque.
      */
     appendleft(item) {
         if (this.count === this.capacity)
@@ -79,9 +79,8 @@ export class Deque extends Sequence {
         return ++this.count;
     }
     /**
-     * Method used to pop the deque.
-     *
-     * @return {any} - Returns the popped item.
+     * Removes and returns the element at the end of the deque.
+     * @returns {?T} Returns the popped item.
      */
     pop() {
         if (this.count === 0)
@@ -92,14 +91,14 @@ export class Deque extends Sequence {
     }
     /**
      * Alias of {@link Deque.pop}
+     * @returns {?T} Returns the popped item.
      */
     remove() {
         return this.pop();
     }
     /**
-     * Method used to shift the deque.
-     *
-     * @return {any} - Returns the shifted item.
+     * Removes and returns the element at the beginning of the deque.
+     * @returns {?T} Returns the removed deque element.
      */
     popleft() {
         if (this.count === 0)
@@ -112,9 +111,8 @@ export class Deque extends Sequence {
         return this.items[index];
     }
     /**
-     * Method used to peek the first value of the deque.
-     *
-     * @return {any}
+     * Returns the element at the beginning of the deque.
+     * @returns {?T} The element if exists
      */
     first() {
         if (this.count === 0)
@@ -122,10 +120,9 @@ export class Deque extends Sequence {
         return this.items[this.start];
     }
     /**
-     * Method used to get the desired value of the deque.
-     *
-     * @param  {number} index
-     * @return {any}
+     * Returns the element at a specified index position in the deque.
+     * @param {number} index The given index
+     * @returns {?T} The element if exists
      */
     get(index) {
         if (this.count === 0)
@@ -138,9 +135,8 @@ export class Deque extends Sequence {
         return this.items[index];
     }
     /**
-     * Update the value at a given `index`.
-     * @param index The given index
-     * @param value The new value to set at `index`.
+     * Update the element at a given `index`.
+     * @param {number} index The given index
      */
     set(index, value) {
         if (index < 0)
@@ -149,6 +145,11 @@ export class Deque extends Sequence {
             throw new KeyError(`Invalid index: ${index} not in Deque.`);
         this.items[index] = value;
     }
+    /**
+     * Check if a given element is in the deque.
+     * @param {T} x The value to find
+     * @returns {boolean} `true` if the value is found
+     */
     contains(x) {
         for (const value of this.values()) {
             if (eq(x, value))
@@ -156,6 +157,11 @@ export class Deque extends Sequence {
         }
         return false;
     }
+    /**
+     * Returns the first element that matches the `iteratee` function.
+     * @param {Iteratee<T>} iteratee A function that will be invoked per element
+     * @returns {?T} The element if exists
+     */
     find(iteratee) {
         for (const [key, value] of this.entries()) {
             if (iteratee(value, key, this))
@@ -163,11 +169,8 @@ export class Deque extends Sequence {
         }
     }
     /**
-     * Method used to iterate over the deque.
-     *
-     * @param  {function}  iteratee - Function to call for each item.
-     * @param  {object}    scope    - Optional scope.
-     * @return {undefined}
+     * Calls `iteratee` function for every element in the deque.
+     * @param {Iteratee<T>} iteratee A function that will be invoked per element
      */
     forEach(iteratee) {
         const c = this.capacity;
@@ -182,20 +185,23 @@ export class Deque extends Sequence {
                 i = 0;
         }
     }
+    /**
+     * Returns a new array with all the elements in reverse order.
+     * @returns {Array<T>} The elements reversed
+     */
     reversed() {
         return this.toArray().reverse();
     }
     /**
-     * Method used to convert the deque to a JavaScript array.
-     *
-     * @return {array}
+     * Returns a new array with all the elements in the order they were added to the deque.
+     * @returns {Array<T>} The elements array
      */
     toArray() {
         // Optimization
         const offset = this.start + this.count;
         if (offset < this.capacity)
             return this.items.slice(this.start, offset);
-        const array = new this.ArrayClass(this.count);
+        const array = new this.ArrayConstructor(this.count);
         const c = this.capacity;
         const l = this.count;
         let i = this.start;
@@ -210,9 +216,8 @@ export class Deque extends Sequence {
         return array;
     }
     /**
-     * Method used to create an iterator over the deque's values.
-     *
-     * @return {Iterator}
+     * Returns an iterator over the deque's values.
+     * @returns {Iterator}
      */
     values() {
         const items = this.items;
@@ -236,13 +241,15 @@ export class Deque extends Sequence {
             };
         });
     }
+    /**
+     * Alias of {@link Deque.values}. Returns iterator of values.
+     */
     keys() {
         return this.values();
     }
     /**
-     * Method used to create an iterator over the deque's entries.
-     *
-     * @return {Iterator}
+     * Creates an iterator of `[index, value]` pairs for all elements in the deque.
+     * @returns {Iterator}
      */
     entries() {
         const items = this.items;
@@ -271,9 +278,10 @@ export class Deque extends Sequence {
     [Symbol.for('nodejs.util.inspect.custom')]() {
         return this.inspect();
     }
+    // This is just for debugging in nodejs
     inspect() {
         const array = this.toArray();
-        array.type = this.ArrayClass.name;
+        array.type = this.ArrayConstructor.name;
         array.capacity = this.capacity;
         // Trick so that node displays the name of the constructor
         Object.defineProperty(array, 'constructor', {

package/core/collections/deque.ts

@@ -5,40 +5,44 @@ import { Sequence } from './abc.js'
 
 /**
  * Fixed capacity double-ended queue implemented as ring deque.
- *
- * @constructor
+ * @template T
  */
-export class Deque<T> extends Sequence<T> {
+export class Deque<T = any> extends Sequence<T> {
   items: T[]
   start: number = 0
   count: number = 0
   capacity: number
-  ArrayClass: any
+  ArrayConstructor: any
 
-  constructor(ArrayClass = [] as T[], capacity = 1024) {
+  /**
+   * Creates a new `Deque` instance of a fixed size.
+   * @param {Array} [arrType = []] The initial elements or array type to use (accepts any kind of typed array).
+   * @param {number} [capacity=1024] The fixed size of the deque. Defaults to `1024`.
+   */
+  constructor(arrType = [] as T[], capacity = 1024) {
     super()
     if (typeof capacity !== 'number' || capacity <= 0)
       throw new ValueError(`Deque capacity should be a positive integer.`)
 
-    this.ArrayClass = ArrayClass.constructor
+    this.ArrayConstructor = arrType.constructor
     this.capacity = capacity
-    this.items = new this.ArrayClass(ArrayClass.length || this.capacity)
+    this.items = new this.ArrayConstructor(arrType.length || this.capacity)
     this.clear()
-    if (ArrayClass.length) {
-      for (const item of ArrayClass) {
+
+    if (arrType.length) {
+      for (const item of arrType) {
         this.append(item)
       }
     }
   }
 
+  /** Returns the total number of elements in the deque. */
   get size() {
     return this.count
   }
 
   /**
    * Method used to clear the structure.
-   *
-   * @return {undefined}
    */
   clear() {
     // Properties
@@ -48,19 +52,17 @@ export class Deque<T> extends Sequence<T> {
 
   /**
    * Alias of {@link Deque.append}
-   *
-   * @param  {any}    item - Item to append.
-   * @return {number}      - Returns the new size of the deque.
+   * @param {T} item Item to append.
+   * @returns {number} Returns the new size of the deque.
    */
   add(item) {
     return this.append(item)
   }
 
   /**
-   * Method used to append a value to the deque.
-   *
-   * @param  {any}    item - Item to append.
-   * @return {number}      - Returns the new size of the deque.
+   * Appends a new element to the end of the deque.
+   * @param {T} item Item to append.
+   * @returns {number} Returns the new size of the deque.
    */
   append(item) {
     if (this.count === this.capacity) this.popleft()
@@ -73,10 +75,9 @@ export class Deque<T> extends Sequence<T> {
   }
 
   /**
-   * Method used to prepend a value to the deque.
-   *
-   * @param  {any}    item - Item to prepend.
-   * @return {number}      - Returns the new size of the deque.
+   * Appends a new element to the beginning of the deque.
+   * @param {T} item Item to prepend.
+   * @returns {number} Returns the new size of the deque.
    */
   appendleft(item) {
     if (this.count === this.capacity) this.pop()
@@ -92,9 +93,8 @@ export class Deque<T> extends Sequence<T> {
   }
 
   /**
-   * Method used to pop the deque.
-   *
-   * @return {any} - Returns the popped item.
+   * Removes and returns the element at the end of the deque.
+   * @returns {?T} Returns the popped item.
    */
   pop() {
     if (this.count === 0) return
@@ -108,15 +108,15 @@ export class Deque<T> extends Sequence<T> {
 
   /**
    * Alias of {@link Deque.pop}
+   * @returns {?T} Returns the popped item.
    */
   remove() {
     return this.pop()
   }
 
   /**
-   * Method used to shift the deque.
-   *
-   * @return {any} - Returns the shifted item.
+   * Removes and returns the element at the beginning of the deque.
+   * @returns {?T} Returns the removed deque element.
    */
   popleft() {
     if (this.count === 0) return
@@ -132,9 +132,8 @@ export class Deque<T> extends Sequence<T> {
   }
 
   /**
-   * Method used to peek the first value of the deque.
-   *
-   * @return {any}
+   * Returns the element at the beginning of the deque.
+   * @returns {?T} The element if exists
    */
   first() {
     if (this.count === 0) return
@@ -143,10 +142,9 @@ export class Deque<T> extends Sequence<T> {
   }
 
   /**
-   * Method used to get the desired value of the deque.
-   *
-   * @param  {number} index
-   * @return {any}
+   * Returns the element at a specified index position in the deque.
+   * @param {number} index The given index
+   * @returns {?T} The element if exists
    */
   get(index) {
     if (this.count === 0) return
@@ -160,9 +158,8 @@ export class Deque<T> extends Sequence<T> {
   }
 
   /**
-   * Update the value at a given `index`.
-   * @param index The given index
-   * @param value The new value to set at `index`.
+   * Update the element at a given `index`.
+   * @param {number} index The given index
    */
   set(index: number, value: T) {
     if (index < 0) index += this.count
@@ -170,6 +167,11 @@ export class Deque<T> extends Sequence<T> {
     this.items[index] = value
   }
 
+  /**
+   * Check if a given element is in the deque.
+   * @param {T} x The value to find
+   * @returns {boolean} `true` if the value is found
+   */
   contains(x) {
     for (const value of this.values()) {
       if (eq(x, value)) return true
@@ -177,6 +179,11 @@ export class Deque<T> extends Sequence<T> {
     return false
   }
 
+  /**
+   * Returns the first element that matches the `iteratee` function.
+   * @param {Iteratee<T>} iteratee A function that will be invoked per element
+   * @returns {?T} The element if exists
+   */
   find(iteratee: Iteratee<T>) {
     for (const [key, value] of this.entries()) {
       if (iteratee(value, key, this)) return value
@@ -184,11 +191,8 @@ export class Deque<T> extends Sequence<T> {
   }
 
   /**
-   * Method used to iterate over the deque.
-   *
-   * @param  {function}  iteratee - Function to call for each item.
-   * @param  {object}    scope    - Optional scope.
-   * @return {undefined}
+   * Calls `iteratee` function for every element in the deque.
+   * @param {Iteratee<T>} iteratee A function that will be invoked per element
    */
   forEach(iteratee) {
     const c = this.capacity
@@ -205,14 +209,17 @@ export class Deque<T> extends Sequence<T> {
     }
   }
 
+  /**
+   * Returns a new array with all the elements in reverse order.
+   * @returns {Array<T>} The elements reversed
+   */
   reversed() {
     return this.toArray().reverse()
   }
 
   /**
-   * Method used to convert the deque to a JavaScript array.
-   *
-   * @return {array}
+   * Returns a new array with all the elements in the order they were added to the deque.
+   * @returns {Array<T>} The elements array
    */
   toArray() {
     // Optimization
@@ -220,7 +227,7 @@ export class Deque<T> extends Sequence<T> {
 
     if (offset < this.capacity) return this.items.slice(this.start, offset)
 
-    const array = new this.ArrayClass(this.count)
+    const array = new this.ArrayConstructor(this.count)
     const c = this.capacity
     const l = this.count
     let i = this.start
@@ -238,9 +245,8 @@ export class Deque<T> extends Sequence<T> {
   }
 
   /**
-   * Method used to create an iterator over the deque's values.
-   *
-   * @return {Iterator}
+   * Returns an iterator over the deque's values.
+   * @returns {Iterator}
    */
   values(): Iterable<T> {
     const items = this.items
@@ -269,14 +275,16 @@ export class Deque<T> extends Sequence<T> {
     })
   }
 
+  /**
+   * Alias of {@link Deque.values}. Returns iterator of values.
+   */
   keys() {
     return this.values()
   }
 
   /**
-   * Method used to create an iterator over the deque's entries.
-   *
-   * @return {Iterator}
+   * Creates an iterator of `[index, value]` pairs for all elements in the deque.
+   * @returns {Iterator}
    */
   entries() {
     const items = this.items
@@ -312,10 +320,11 @@ export class Deque<T> extends Sequence<T> {
     return this.inspect()
   }
 
+  // This is just for debugging in nodejs
   inspect() {
     const array = this.toArray()
 
-    array.type = this.ArrayClass.name
+    array.type = this.ArrayConstructor.name
     array.capacity = this.capacity
 
     // Trick so that node displays the name of the constructor

package/core/collections/index.d.ts

@@ -110,6 +110,8 @@ export declare function findRight(arr: any, fn: Iteratee | PropertyKey | Object)
 /**
  * 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`.

package/core/collections/index.js

@@ -4,7 +4,7 @@
  * @module Collections
  */
 import { partial } from '../functools/index.js';
-import { call, get, isArray, isArrayLike, isBool, isEmpty, isFunc, isIterable, isNull, isNumber, isObject, isString, isSymbol, keys, set } from '../globals/index.js';
+import { call, get, isArray, isArrayLike, isBool, isEmpty, isFunction, isIterable, isNull, isNumber, isObject, isString, isSymbol, keys, set } from '../globals/index.js';
 import { enumerate } from '../itertools/index.js';
 import { compare, eq, id } from '../operators/index.js';
 export * from './abc.js';
@@ -81,7 +81,7 @@ filter(users, 'active')
  */
 export function filter(arr, fn = isNull) {
     if (Array.isArray(arr)) {
-        if (isFunc(fn))
+        if (isFunction(fn))
             return arr.filter(fn);
         if (isNumber(fn) || isString(fn) || isSymbol(fn))
             return arr.filter((x) => get(fn, x));
@@ -117,7 +117,7 @@ find(users, 'active')
  */
 export function find(arr, fn) {
     if (Array.isArray(arr)) {
-        if (isFunc(fn))
+        if (isFunction(fn))
             return arr.find(fn);
         if (isNumber(fn) || isString(fn) || isSymbol(fn))
             return arr.find((x) => x?.[fn]);
@@ -159,6 +159,8 @@ 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`.
@@ -642,7 +644,7 @@ export function clone(value, deep = false) {
         return cloneArray(value, deep);
     }
     if (isObject(value)) {
-        if (isFunc(value.clone)) {
+        if (isFunction(value.clone)) {
             return value.clone();
         }
         const copy = {};
@@ -974,7 +976,7 @@ export function remove(arr, func) {
     return arr.filter((x, i) => {
         if (isArray(func))
             return !func.includes(x);
-        else if (isFunc(func))
+        else if (isFunction(func))
             return !func(x, i, arr);
         return x !== func;
     });

package/core/collections/index.ts

@@ -12,7 +12,7 @@ import {
   isArrayLike,
   isBool,
   isEmpty,
-  isFunc,
+  isFunction,
   isIterable,
   isNull,
   isNumber,
@@ -114,7 +114,7 @@ filter(users, 'active')
  */
 export function filter(arr, fn: Iteratee | PropertyKey | Object = isNull) {
   if (Array.isArray(arr)) {
-    if (isFunc(fn)) return arr.filter(fn)
+    if (isFunction(fn)) return arr.filter(fn)
     if (isNumber(fn) || isString(fn) || isSymbol(fn)) return arr.filter((x) => get(fn, x))
     if (isObject(fn)) return arr.filter(matches(fn))
   }
@@ -148,7 +148,7 @@ find(users, 'active')
  */
 export function find(arr, fn: Iteratee | PropertyKey | Object) {
   if (Array.isArray(arr)) {
-    if (isFunc(fn)) return arr.find(fn)
+    if (isFunction(fn)) return arr.find(fn)
     if (isNumber(fn) || isString(fn) || isSymbol(fn)) return arr.find((x) => x?.[fn])
     if (isObject(fn)) return arr.find(matches(fn))
   }
@@ -183,6 +183,8 @@ export function findRight(arr, fn: Iteratee | PropertyKey | Object) {
 /**
  * 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`.
@@ -670,7 +672,7 @@ export function clone(value, deep = false) {
     return cloneArray(value, deep)
   }
   if (isObject(value)) {
-    if (isFunc(value.clone)) {
+    if (isFunction(value.clone)) {
       return value.clone()
     }
     const copy = {}
@@ -1013,7 +1015,7 @@ export function groupByMap<K = any, V = any>(
 export function remove<T>(arr: T[], func: any) {
   return arr.filter((x, i) => {
     if (isArray(func)) return !func.includes(x)
-    else if (isFunc(func)) return !func(x, i, arr)
+    else if (isFunction(func)) return !func(x, i, arr)
     return x !== func
   })
 }

package/core/functools/index.d.ts

@@ -47,7 +47,7 @@ export declare const compose: (...args: any[]) => (x: any) => any;
  * @param {Function} [resolver] The function to resolve the cache key.
  * @return {Function} Returns the new memoized function.
  */
-export declare function memoize(func: Function, resolver?: Function): Function;
+export declare function memoize<T>(func: Function<T>, resolver?: Function): Function<ReturnType<typeof func>>;
 export declare function cache(target: any, name: any, descriptor: any): any;
 /**
  * Creates a debounced function that delays invoking `func` until after `wait` milliseconds have elapsed since the last time the debounced function was invoked. Subsequent calls to the debounced function return the result of the last successful invocation. Provide options to set the `maxWait` milliseconds, regardless of when the function was last invoked.
@@ -84,9 +84,10 @@ single(3) // => 1
 // => `func` is invoked only once.
 ```
  */
-export declare function once(func: Function): (...args: any[]) => any;
+export declare function once<T>(func: Function<T>): (...args: any[]) => T;
 export declare type Maybe<T> = T | undefined;
 export declare type Result<T, E = any> = [Maybe<T>, Maybe<E>];
+export declare type Optional<T> = Maybe<T>;
 /**
  * Wraps a function to catch any exceptions inside and return a `go` style error-return type {@link Result}.
  *