atomic-fns 0.3.2 → 0.3.3-beta

package/README.md

@@ -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/index.d.ts

@@ -107,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
@@ -501,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
@@ -514,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/core/collections/index.js

@@ -156,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
@@ -898,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
@@ -921,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.

package/core/collections/index.ts

@@ -180,6 +180,22 @@ 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`.
+ * @returns {Array<*>} The given array.
+ */
+export function insert(arr: any[], index: number, 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
@@ -933,7 +949,7 @@ export function* union(...args: Array<Iterable<any>>) {
  *
  * @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
@@ -957,6 +973,39 @@ export function groupBy(arr: Iterable<any> | Object, func: Iteratee | PropertyKe
   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<K = any, V = any>(
+  arr: Iterable<any> | Object,
+  func: Iteratee | PropertyKey = id
+): Map<K, V[]> {
+  const results = new Map<K, V[]>()
+  const useKey = typeof func === 'function' ? func : partial(get, func)
+  forEach(arr, (value: V) => {
+    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.

package/core/index.d.ts

@@ -1,5 +1,4 @@
 export * from './collections/index.js';
-export * from './datetime/index.js';
 export * from './functools/index.js';
 export * from './globals/index.js';
 export * from './itertools/index.js';

package/core/index.js

@@ -1,5 +1,4 @@
 export * from './collections/index.js';
-export * from './datetime/index.js';
 export * from './functools/index.js';
 export * from './globals/index.js';
 export * from './itertools/index.js';

package/core/index.ts

@@ -1,5 +1,4 @@
 export * from './collections/index.js'
-export * from './datetime/index.js'
 export * from './functools/index.js'
 export * from './globals/index.js'
 export * from './itertools/index.js'

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "atomic-fns",
   "description": "Like Lodash, but for ESNext and with types. Stop shipping code built for browsers from 2015.",
-  "version": "0.3.2",
+  "version": "0.3.3-beta",
   "main": "core/index.js",
   "type": "module",
   "types": "core/index.d.ts",

package/core/datetime/index.d.ts

@@ -1,6 +0,0 @@
-/**
- * This module includes classes and functions to work with Date types.
- *
- * @module Date
- */
-export declare const now: number;

package/core/datetime/index.js

@@ -1,6 +0,0 @@
-/**
- * This module includes classes and functions to work with Date types.
- *
- * @module Date
- */
-export const now = new Date().getTime();

package/core/datetime/index.ts

@@ -1,7 +0,0 @@
-/**
- * This module includes classes and functions to work with Date types.
- *
- * @module Date
- */
-
-export const now = new Date().getTime()