atomic-fns 0.3.3 → 0.3.5

package/README.md

@@ -21,7 +21,7 @@ You may prefer this because it's:
 
 ## Get Started
 
-This library is available as an npm package.
+This library is available as an [npm package](https://www.npmjs.com/package/atomic-fns).
 
 To install the package you need to have [npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) (or [yarn](https://yarnpkg.com/getting-started/install)) and then run:
 
@@ -52,7 +52,7 @@ You could also import any individual module directly from an html page like this
 ```html
 <script type="module">
   import {
-    namedtuple, Deque, Heap, SortedSet, SortedMap
+    namedtuple, FrozenSet, SortedSet, SortedMap
   } from 'https://unpkg.com/atomic-fns/core/collections';
   // your code goes here...
 </script>
@@ -66,7 +66,7 @@ This library features a data model similar to [Python](https://docs.python.org/3
 For example in Python collections `size()` is a method while in JS its just a property. So this library uses `size` property instead of methods. Similarly, the `len` function implementation checks for both `length` and `size` since many JS objects have a `length` property.
 
 ## Special method names
-This library adds support for operators via object methods like:
+This library adds support for operators using object methods such as:
   - `obj.eq(other)`  adds custom `obj == other`.
   - `obj.lt(other)`  adds custom `obj < other`.
   - `obj.lte(other)`  adds custom `obj <= other`.
@@ -76,11 +76,25 @@ This library adds support for operators via object methods like:
 
 When you implement those, you can also apply operators to values like `eq(x, y), lte(x, y), compare(x, y)`, etc. to get the result of `x.<operator>(y)`.
 
-Some new base types introduced: `Collection, Sequence, Mapping, FrozenSet, IterableIterator`.
+## New Types
+
+Introduces some common base interfaces and typing patterns you may have seen like `Optional`, `Result`, `Comparable`, `Iterator`, and others.
+
+### Sorted Containers
+  - [SortedSet](https://atomic-fns.dev/classes/Collections.SortedSet.html)
+  - [SortedMap](https://atomic-fns.dev/classes/Collections.SortedMap.html)
+  - [SortedTree](https://atomic-fns.dev/classes/Collections.SortedTree.html)
+
+### Other Containers
+  - [Deque](https://atomic-fns.dev/classes/Collections.Deque.html)
+  - [FrozenSet](https://atomic-fns.dev/classes/Collections.FrozenSet.html)
+  - [LRUCache](https://atomic-fns.dev/classes/Collections.LRUCache.html)
+
 
 ## Contributing
 If you want to contribute to the project and make it better, your help is very welcome. Contributing is also a great way to learn more about social coding on Github, new technologies and and their ecosystems and how to make constructive, helpful bug reports, feature requests and the noblest of all contributions: a good, clean pull request. You will be listed as a **Champion** on the official site as well.
 
+
 ## License
 
 [Apache License 2.0](http://www.apache.org/licenses/LICENSE-2.0)

package/core/collections/LRUCache.d.ts

@@ -1,7 +1,9 @@
 import { Iteratee } from '../globals/index.js';
 import { Mapping } from './abc.js';
 /**
- * Base append-only Cache collection.
+ * Base append-only Cache collection that supports adding and accessing keys in O(1).
+ * The collection has a fixed given size (default 1024) and when full, it evicts keys using LRU approach. This operation is also O(1).
+ * @template K, V
  */
 export declare class Cache<K, V = any> extends Mapping<K, V> {
     capacity: number;
@@ -13,6 +15,12 @@ export declare class Cache<K, V = any> extends Mapping<K, V> {
     protected backward: Uint8Array | Uint16Array | Uint32Array;
     protected K: K[];
     protected V: V[];
+    /**
+     * Create a new cache object of fixed size.
+     * @param {number} [capacity=1024] The maximum number of keys to keep in cache.
+     * @param {Function} [Keys=Array] The constructor to use for the Keys array. When using numeric values, a TypedArray constructor can be used.
+     * @param {Function} [Values=Array] The constructor to use for the Values array. When using numeric values, a TypedArray constructor can be used.
+     */
     constructor(capacity?: number, Keys?: ArrayConstructor, Values?: ArrayConstructor);
     /**
      * This is just an alias of {@link Cache.set}.
@@ -30,6 +38,9 @@ export declare class Cache<K, V = any> extends Mapping<K, V> {
      * Method used to clear the structure.
      */
     clear(): void;
+    /**
+     * Returns the number of keys in the cache.
+     */
     get size(): number;
     /**
      * Method used to splay a value on top.
@@ -101,10 +112,20 @@ export declare class Cache<K, V = any> extends Mapping<K, V> {
      */
     inspect(): Map<any, any>;
 }
+/**
+ * Implements a Least Recently Used fixed-capacity cache which supports updating, removing, and accessing keys in O(1).
+ */
 export declare class LRUCache<K, V> extends Cache<K, V> {
     deletedSize: number;
     deleted: Uint8Array | Uint16Array | Uint32Array;
+    /**
+     * Create a new LRU cache object of fixed size.
+     * @param {number} [capacity=1024] The maximum number of keys to keep in cache.
+     * @param {Function} [Keys=Array] The constructor to use for the Keys array. When using numeric values, a TypedArray constructor can be used.
+     * @param {Function} [Values=Array] The constructor to use for the Values array. When using numeric values, a TypedArray constructor can be used.
+     */
     constructor(capacity?: number, Keys?: ArrayConstructor, Values?: ArrayConstructor);
+    /** Remove all elements in the cache. */
     clear(): void;
     /**
      * Method used to set the value for the given key in the cache.

package/core/collections/LRUCache.js

@@ -3,7 +3,9 @@ import { IterableIterator } from '../itertools/index.js';
 import { Mapping } from './abc.js';
 import { getPointerArray } from './typedArrays.js';
 /**
- * Base append-only Cache collection.
+ * Base append-only Cache collection that supports adding and accessing keys in O(1).
+ * The collection has a fixed given size (default 1024) and when full, it evicts keys using LRU approach. This operation is also O(1).
+ * @template K, V
  */
 export class Cache extends Mapping {
     capacity;
@@ -15,6 +17,12 @@ export class Cache extends Mapping {
     backward;
     K;
     V;
+    /**
+     * Create a new cache object of fixed size.
+     * @param {number} [capacity=1024] The maximum number of keys to keep in cache.
+     * @param {Function} [Keys=Array] The constructor to use for the Keys array. When using numeric values, a TypedArray constructor can be used.
+     * @param {Function} [Values=Array] The constructor to use for the Values array. When using numeric values, a TypedArray constructor can be used.
+     */
     constructor(capacity = 1024, Keys = Array, Values = Array) {
         super();
         this.capacity = capacity;
@@ -53,6 +61,9 @@ export class Cache extends Mapping {
         this.tail = 0;
         this.items = new Map();
     }
+    /**
+     * Returns the number of keys in the cache.
+     */
     get size() {
         return this.count;
     }
@@ -264,14 +275,24 @@ export class Cache extends Mapping {
         return this.inspect();
     }
 }
+/**
+ * Implements a Least Recently Used fixed-capacity cache which supports updating, removing, and accessing keys in O(1).
+ */
 export class LRUCache extends Cache {
     deletedSize = 0;
     deleted;
+    /**
+     * Create a new LRU cache object of fixed size.
+     * @param {number} [capacity=1024] The maximum number of keys to keep in cache.
+     * @param {Function} [Keys=Array] The constructor to use for the Keys array. When using numeric values, a TypedArray constructor can be used.
+     * @param {Function} [Values=Array] The constructor to use for the Values array. When using numeric values, a TypedArray constructor can be used.
+     */
     constructor(capacity = 1024, Keys = Array, Values = Array) {
         super(capacity, Keys, Values);
         const PointerArray = getPointerArray(capacity);
         this.deleted = new PointerArray(capacity);
     }
+    /** Remove all elements in the cache. */
     clear() {
         super.clear();
         this.deletedSize = 0;

package/core/collections/LRUCache.ts

@@ -4,7 +4,9 @@ import { Mapping } from './abc.js'
 import { getPointerArray } from './typedArrays.js'
 
 /**
- * Base append-only Cache collection.
+ * Base append-only Cache collection that supports adding and accessing keys in O(1).
+ * The collection has a fixed given size (default 1024) and when full, it evicts keys using LRU approach. This operation is also O(1).
+ * @template K, V
  */
 export class Cache<K, V = any> extends Mapping<K, V> {
   capacity: number
@@ -17,6 +19,12 @@ export class Cache<K, V = any> extends Mapping<K, V> {
   protected K: K[]
   protected V: V[]
 
+  /**
+   * Create a new cache object of fixed size.
+   * @param {number} [capacity=1024] The maximum number of keys to keep in cache.
+   * @param {Function} [Keys=Array] The constructor to use for the Keys array. When using numeric values, a TypedArray constructor can be used.
+   * @param {Function} [Values=Array] The constructor to use for the Values array. When using numeric values, a TypedArray constructor can be used.
+   */
   constructor(capacity = 1024, Keys = Array, Values = Array) {
     super()
     this.capacity = capacity
@@ -61,6 +69,9 @@ export class Cache<K, V = any> extends Mapping<K, V> {
     this.items = new Map()
   }
 
+  /**
+   * Returns the number of keys in the cache.
+   */
   get size() {
     return this.count
   }
@@ -315,16 +326,26 @@ export class Cache<K, V = any> extends Mapping<K, V> {
   }
 }
 
+/**
+ * Implements a Least Recently Used fixed-capacity cache which supports updating, removing, and accessing keys in O(1).
+ */
 export class LRUCache<K, V> extends Cache<K, V> {
   deletedSize = 0
   deleted: Uint8Array | Uint16Array | Uint32Array
 
+  /**
+   * Create a new LRU cache object of fixed size.
+   * @param {number} [capacity=1024] The maximum number of keys to keep in cache.
+   * @param {Function} [Keys=Array] The constructor to use for the Keys array. When using numeric values, a TypedArray constructor can be used.
+   * @param {Function} [Values=Array] The constructor to use for the Values array. When using numeric values, a TypedArray constructor can be used.
+   */
   constructor(capacity = 1024, Keys = Array, Values = Array) {
     super(capacity, Keys, Values)
     const PointerArray = getPointerArray(capacity)
     this.deleted = new PointerArray(capacity)
   }
 
+  /** Remove all elements in the cache. */
   clear() {
     super.clear()
     this.deletedSize = 0

package/core/collections/SortedMap.d.ts

@@ -1,6 +1,6 @@
 import { Mapping } from './abc.js';
 /**
- * A `SortedMap` is a map that holds key value pairs in sorted orders of keys. Any primitive value (and objects that implement a `compare` or `lt` methods) can be used as keys or values.
+ * A `SortedMap` is a map that holds key value pairs ordered by keys. Any primitive value (and objects that implement {@link Comparable} or {@link Ordered} interfaces) can be used as keys or values.
  * @see {@link Operators.compare}
  * @see {@link Operators.lt}
  * @template K, V

package/core/collections/SortedMap.js

@@ -1,7 +1,7 @@
 import { Mapping } from './abc.js';
 import { SplayTree } from './SplayTree.js';
 /**
- * A `SortedMap` is a map that holds key value pairs in sorted orders of keys. Any primitive value (and objects that implement a `compare` or `lt` methods) can be used as keys or values.
+ * A `SortedMap` is a map that holds key value pairs ordered by keys. Any primitive value (and objects that implement {@link Comparable} or {@link Ordered} interfaces) can be used as keys or values.
  * @see {@link Operators.compare}
  * @see {@link Operators.lt}
  * @template K, V

package/core/collections/SortedMap.ts

@@ -2,7 +2,7 @@ import { Mapping } from './abc.js'
 import { SplayTree } from './SplayTree.js'
 
 /**
- * A `SortedMap` is a map that holds key value pairs in sorted orders of keys. Any primitive value (and objects that implement a `compare` or `lt` methods) can be used as keys or values.
+ * A `SortedMap` is a map that holds key value pairs ordered by keys. Any primitive value (and objects that implement {@link Comparable} or {@link Ordered} interfaces) can be used as keys or values.
  * @see {@link Operators.compare}
  * @see {@link Operators.lt}
  * @template K, V

package/core/collections/SortedSet.d.ts

@@ -1,4 +1,10 @@
 import { Collection } from './abc.js';
+/**
+ * A `SortedSet` is a set that holds values in order. Any primitive value (and objects that implement {@link Comparable} or {@link Ordered} interfaces) can be used as values.
+ * @see {@link Compare}
+ * @see {@link Ordered}
+ * @template K, V
+ */
 export declare class SortedSet<T> extends Collection {
     private readonly store;
     /**

package/core/collections/SortedSet.js

@@ -1,5 +1,11 @@
 import { Collection } from './abc.js';
 import { SplayTree } from './SplayTree.js';
+/**
+ * A `SortedSet` is a set that holds values in order. Any primitive value (and objects that implement {@link Comparable} or {@link Ordered} interfaces) can be used as values.
+ * @see {@link Compare}
+ * @see {@link Ordered}
+ * @template K, V
+ */
 export class SortedSet extends Collection {
     store;
     /**

package/core/collections/SortedSet.ts

@@ -1,6 +1,12 @@
 import { Collection } from './abc.js'
 import { SplayTree } from './SplayTree.js'
 
+/**
+ * A `SortedSet` is a set that holds values in order. Any primitive value (and objects that implement {@link Comparable} or {@link Ordered} interfaces) can be used as values.
+ * @see {@link Compare}
+ * @see {@link Ordered}
+ * @template K, V
+ */
 export class SortedSet<T> extends Collection {
   private readonly store: SplayTree<T>
   /**

package/core/collections/SortedTree.d.ts

@@ -1,9 +1,9 @@
 import { Comparer } from '../operators/index.js';
 import { Mapping } from './abc.js';
 /**
- * A `SortedTree` is a map that holds key value pairs in sorted orders of keys. Any primitive value (and objects that implement a `compare` or `lt` methods) can be used as keys or values.
- * @see {@link Operators.compare}
- * @see {@link Operators.lt}
+ * A `SortedTree` is a map that holds key value pairs ordered by keys. Any primitive value (and objects that implement {@link Comparable} or {@link Ordered} interfaces) can be used as keys or values.
+ * @see {@link Compare}
+ * @see {@link Ordered}
  * @template K, V
  */
 export declare class SortedTree<K, V> extends Mapping<K, V> {

package/core/collections/SortedTree.js

@@ -1,9 +1,9 @@
 import { Mapping } from './abc.js';
 import { BTree } from './BTree.js';
 /**
- * A `SortedTree` is a map that holds key value pairs in sorted orders of keys. Any primitive value (and objects that implement a `compare` or `lt` methods) can be used as keys or values.
- * @see {@link Operators.compare}
- * @see {@link Operators.lt}
+ * A `SortedTree` is a map that holds key value pairs ordered by keys. Any primitive value (and objects that implement {@link Comparable} or {@link Ordered} interfaces) can be used as keys or values.
+ * @see {@link Compare}
+ * @see {@link Ordered}
  * @template K, V
  */
 export class SortedTree extends Mapping {

package/core/collections/SortedTree.ts

@@ -3,9 +3,9 @@ import { Mapping } from './abc.js'
 import { BTree } from './BTree.js'
 
 /**
- * A `SortedTree` is a map that holds key value pairs in sorted orders of keys. Any primitive value (and objects that implement a `compare` or `lt` methods) can be used as keys or values.
- * @see {@link Operators.compare}
- * @see {@link Operators.lt}
+ * A `SortedTree` is a map that holds key value pairs ordered by keys. Any primitive value (and objects that implement {@link Comparable} or {@link Ordered} interfaces) can be used as keys or values.
+ * @see {@link Compare}
+ * @see {@link Ordered}
  * @template K, V
  */
 export class SortedTree<K, V> extends Mapping<K, V> {

package/core/collections/abc.d.ts

@@ -32,7 +32,7 @@ export interface Ordered<T> {
  * Implements an iterable that allows backward iteration.
  * @interface Reversible
  */
-export interface Reversible<T = unknown> {
+export interface Reversible<T = any> {
     reversed: () => Iterable<T>;
 }
 /**

package/core/collections/abc.ts

@@ -36,7 +36,7 @@ export interface Ordered<T> {
  * Implements an iterable that allows backward iteration.
  * @interface Reversible
  */
-export interface Reversible<T = unknown> {
+export interface Reversible<T = any> {
   reversed: () => Iterable<T>
 }
 

package/core/collections/deque.d.ts

@@ -2,107 +2,114 @@ import { Iteratee } from '../globals/index.js';
 import { Sequence } from './abc.js';
 /**
  * Fixed capacity double-ended queue implemented as ring deque.
- *
- * @constructor
+ * @template T
  */
-export declare class Deque<T> extends Sequence<T> {
+export declare class Deque<T = any> extends Sequence<T> {
     items: T[];
     start: number;
     count: number;
     capacity: number;
-    ArrayClass: any;
-    constructor(ArrayClass?: T[], capacity?: number);
+    ArrayConstructor: any;
+    /**
+     * 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?: T[], capacity?: number);
+    /** Returns the total number of elements in the deque. */
     get size(): number;
     /**
      * Method used to clear the structure.
-     *
-     * @return {undefined}
      */
     clear(): void;
     /**
      * 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: any): number;
     /**
-     * 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: any): number;
     /**
-     * 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: any): number;
     /**
-     * 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(): T | undefined;
     /**
      * Alias of {@link Deque.pop}
+     * @returns {?T} Returns the popped item.
      */
     remove(): T | undefined;
     /**
-     * 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(): T | undefined;
     /**
-     * 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(): T | undefined;
     /**
-     * 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: any): T | undefined;
     /**
-     * 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): void;
+    /**
+     * 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: any): boolean;
+    /**
+     * 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>): T | undefined;
     /**
-     * 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: any): void;
+    /**
+     * Returns a new array with all the elements in reverse order.
+     * @returns {Array<T>} The elements reversed
+     */
     reversed(): any;
     /**
-     * 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(): any;
     /**
-     * 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>;
+    /**
+     * Alias of {@link Deque.values}. Returns iterator of values.
+     */
     keys(): Iterable<T>;
     /**
-     * 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(): Iterator<[number, T], any, undefined> & Iterable<[number, T]>;
     [Symbol.iterator](): Iterable<T>;