atomic-fns 0.4.3 → 1.1.2

package/README.md

@@ -2,18 +2,18 @@
 
 [Read the Docs](https://atomic-fns.dev)
 
-## Like Lodash, but for ESNext and with types.
+## Like Lodash, but in TypeScript and for ESNext.
 
-Stop shipping code built for browsers from *2015*. Really though, look at all the [issues](https://github.com/lodash/lodash/issues/2930).
+Stop shipping code built for browsers from 2015. Really though, look at all the [issues](https://github.com/lodash/lodash/issues/2930).
 
 You may prefer this because it's:
 
-* **Modular**: Pick what you need. Supports tree-shaking, no side effects and works with all bundlers.
+* **TypeScript & docs**: Includes type declaration files and js with JSDocs for best in class experience.
+* **Zero deps**: Built from scratch with no runtime dependencies or polyfills.
 * **ESNext**: Uses modern idiomatic syntax, data structures, and control flow techniques.
+* **Modular**: Pick what you need. Supports tree-shaking, no side effects, and works with all bundlers.
 * **Lazy**: Leverage generators, iterators, and functional composition.
-* **Zero deps**: Built from scratch with no runtime dependencies or polyfills.
-* **Well tested**: All modules have comprehensive test suites aiming for 100% coverage.
-* **TypeScript & docs**: Includes type declaration files and js with JSDocs for best in class experience.
+* **Tests**: All modules have comprehensive test suites and public apis are 100% covered.
 
 ## Docs
 
@@ -52,7 +52,7 @@ See the full list of [modules](https://atomic-fns.dev/modules.html).
 ## Data model
 This library features a data model similar to [Python](https://docs.python.org/3/reference/datamodel.html#special-method-names) but not always. Only the missing parts have been implemented, while respecting the JS standards.
 
-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.
+For example, in Python collections, `size()` is a method, while in JS it's just a property. So this library uses `size` property instead of method. 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 using object methods such as:
@@ -63,11 +63,13 @@ This library adds support for operators using object methods such as:
   - `obj.gte(other)`  adds custom `obj >= other`.
   - `obj.compare(other)`  overloads sorting operations.
 
-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)`.
+When working with objects, functions in this library use these custom operators for equality and sorting. You can also apply operators to values like `eq(x, y)`, `lte(x, y)`, `compare(x, y)`, etc.
 
 ## New Types
 
-Introduces some common base interfaces and typing patterns you may have seen like `Optional`, `Result`, `Comparable`, `Iterator`, and others.
+[`Decimal`](https://atomic-fns.dev/classes/decimal.Decimal.html) provides support for correct rounded floating point arithmetic, with arbitrary precision.
+
+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)

package/dist/collections/BTree.d.ts

@@ -1,6 +1,6 @@
-import { Iteratee } from '../globals/index.js';
 import { Comparer } from '../operators/index.js';
 import { Mapping } from './abc.js';
+import { Iteratee } from '../types';
 export declare class BTree<K = any, V = any> extends Mapping<K, V> {
     private root;
     count: number;

package/dist/collections/SortedMap.d.ts

@@ -1,8 +1,8 @@
 import { Mapping } from './abc.js';
 /**
  * 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}
+ * @see {@link operators.compare}
+ * @see {@link operators.lt}
  * @template K, V
  */
 export declare class SortedMap<K, V> extends Mapping<K, V> {

package/dist/collections/SortedMap.js

@@ -2,8 +2,8 @@ import { Mapping } from './abc.js';
 import { SplayTree } from './SplayTree.js';
 /**
  * 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}
+ * @see {@link operators.compare}
+ * @see {@link operators.lt}
  * @template K, V
  */
 export class SortedMap extends Mapping {

package/dist/collections/Trie.d.ts

@@ -0,0 +1,42 @@
+import { Collection } from './abc.js';
+/**
+ * A Trie is a tree for efficient storing and retrieval of strings such as words in a dictionary. They are useful for checking all the strings that have a common prefix.
+ * Insertions, lookups and removals in `O(s)` where `s` is the search term.
+ * @see {@link https://en.wikipedia.org/wiki/Trie Trie}
+ */
+export declare class Trie extends Collection {
+    private root;
+    private count;
+    constructor(words?: string[]);
+    /**
+     * Adds the given string to the tree.
+     * @param word A string
+     */
+    add(word: string): this;
+    /**
+     * Removes the given string from the tree.
+     * @param word The string to remove
+     * @returns {boolean} Returns `true` if the string was found and removed.
+     */
+    remove(word: string): boolean;
+    private findNode;
+    /**
+     * Generates all results that start with the given string.
+     * @param word A prefix string
+     * @param {number} [limit=20] The number of results to return.
+     */
+    matches: (word: string, limit?: number) => Generator<any, void, any>;
+    /**
+     * Returns `true` if the given string is found in the tree.
+     * @param {string} word
+     */
+    contains(word: string): boolean;
+    /**
+     * Removes all strings from the tree.
+     */
+    clear(): void;
+    /**
+     * Returns the total number of strings in the tree.
+     */
+    get size(): number;
+}

package/dist/collections/Trie.js

@@ -0,0 +1,104 @@
+import { Collection } from './abc.js';
+function* traverse(node, path, total = 20, count = 0) {
+    if (node.isWord) {
+        count++;
+        yield path;
+    }
+    for (const key of Object.keys(node)) {
+        yield* traverse(node[key], path + key, total, count);
+    }
+}
+/**
+ * A Trie is a tree for efficient storing and retrieval of strings such as words in a dictionary. They are useful for checking all the strings that have a common prefix.
+ * Insertions, lookups and removals in `O(s)` where `s` is the search term.
+ * @see {@link https://en.wikipedia.org/wiki/Trie Trie}
+ */
+export class Trie extends Collection {
+    root = {};
+    count = 0;
+    constructor(words) {
+        super();
+        if (words) {
+            for (const word of words) {
+                this.add(word);
+            }
+        }
+    }
+    /**
+     * Adds the given string to the tree.
+     * @param word A string
+     */
+    add(word) {
+        let current = this.root;
+        for (let i = 0; i < word.length; i++) {
+            const c = word[i];
+            if (!current[c])
+                current[c] = {};
+            current = current[c];
+        }
+        // Set as end of the word
+        Object.defineProperty(current, 'isWord', {
+            value: true,
+            enumerable: false,
+            writable: true
+        });
+        this.count++;
+        return this;
+    }
+    /**
+     * Removes the given string from the tree.
+     * @param word The string to remove
+     * @returns {boolean} Returns `true` if the string was found and removed.
+     */
+    remove(word) {
+        for (let i = 0, node = this.root; i < word.length && node; i++) {
+            node = node[word[i]];
+            if (i === word.length - 1 && node.isWord) {
+                node.isWord = false;
+                this.count--;
+                return true;
+            }
+        }
+        return false;
+    }
+    findNode(word) {
+        let node = this.root;
+        for (let i = 0; i < word.length && node; i++) {
+            const letter = word[i];
+            node = node[letter];
+        }
+        return node;
+    }
+    /**
+     * Generates all results that start with the given string.
+     * @param word A prefix string
+     * @param {number} [limit=20] The number of results to return.
+     */
+    matches = function* (word, limit = 20) {
+        const node = this.findNode(word);
+        if (node) {
+            yield* traverse(node, word, limit);
+        }
+    };
+    /**
+     * Returns `true` if the given string is found in the tree.
+     * @param {string} word
+     */
+    contains(word) {
+        const node = this.findNode(word);
+        return node?.isWord;
+    }
+    /**
+     * Removes all strings from the tree.
+     */
+    clear() {
+        this.root = {};
+        this.count = 0;
+    }
+    /**
+     * Returns the total number of strings in the tree.
+     */
+    get size() {
+        return this.count;
+    }
+}

package/dist/collections/deque.d.ts

@@ -1,4 +1,4 @@
-import { Iteratee } from '../globals/index.js';
+import { Iteratee } from '../types.js';
 import { Sequence } from './abc.js';
 /**
  * Fixed capacity double-ended queue implemented as ring deque.

package/dist/collections/index.d.ts

@@ -1,10 +1,10 @@
 /**
  * This module includes classes and functions to work with Container types.
  *
- * @module Collections
+ * @module collections
  */
-import { Iteratee } from '../globals/index.js';
 import { compare } from '../operators/index.js';
+import { Iteratee } from '../types';
 export * from './abc.js';
 export * from './BTree.js';
 export * from './deque.js';
@@ -15,6 +15,7 @@ export * from './SortedMap.js';
 export * from './SortedSet.js';
 export * from './SortedTree.js';
 export * from './SplayTree.js';
+export * from './Trie.js';
 /**
  * Creates a new array with all falsy and empty values removed.
  * @param arr The array to compact

package/dist/collections/index.js

@@ -1,7 +1,7 @@
 /**
  * This module includes classes and functions to work with Container types.
  *
- * @module Collections
+ * @module collections
  */
 import { call, get, isArray, isArrayLike, isBool, isEmpty, isFunction, isIterable, isNull, isNumber, isObject, isString, keys, set } from '../globals/index.js';
 import { enumerate } from '../itertools/index.js';
@@ -16,6 +16,7 @@ export * from './SortedMap.js';
 export * from './SortedSet.js';
 export * from './SortedTree.js';
 export * from './SplayTree.js';
+export * from './Trie.js';
 export function compact(arr) {
     if (!arr)
         return;

package/dist/decimal/index.d.ts

@@ -0,0 +1,149 @@
+/**
+ * `Decimal` provides support for correct rounded floating point arithmetic.
+ *
+ * @module decimal
+ */
+/**
+ * Casts the given value as a {@link Decimal}.
+ */
+export declare function decimal(x: any): Decimal;
+/**
+ * `Decimal` provides support for correct rounded floating point arithmetic, unlike the standard
+ * `Number` type. It also supports user-defined precision (default is 20 decimal places), which
+ * can be as large as needed.
+ */
+export declare class Decimal {
+    static PRECISION: number;
+    private i;
+    private e;
+    /**
+     * Returns a new `Decimal` instance from the value or `0`.
+     * @param {*} value
+     * @returns {Decimal}
+     */
+    constructor(value?: any);
+    /**
+     * Returns a new `Decimal` that has the opposite sign of this `Decimal`.
+     * @example
+  ```js
+  let a = decimal('5')
+  a.negated()  // -5
+  ```
+     * @returns {Decimal}
+     */
+    negated(): Decimal;
+    /**
+     * Returns a new `Decimal` that is the sum of this and `x`.
+     * @param x
+     * @example
+  ```js
+  let a = decimal('50000000000')
+  let b = decimal('0.000000005')
+  a.add(b)  // 50000000000.000000005
+  ```
+     * @returns {Decimal}
+     */
+    add(x: any): Decimal;
+    /**
+     * Returns a new `Decimal` that is the difference between this and `x`.
+     * @param x
+     * @example
+  ```js
+  let a = decimal('1')
+  let b = decimal('0.0000000000000000001')
+  a.sub(b)  // 0.9999999999999999999
+  ```
+     * @returns {Decimal}
+     */
+    sub(x: any): Decimal;
+    /**
+     * Returns a new `Decimal` that is the product of this and `x`.
+     * @param x
+     * @example
+  ```js
+  let a = decimal('0.0000000000000000000025')
+  let b = decimal('400000000000000000000')
+  a.mul(b)  // 1
+  ```
+     * @returns {Decimal}
+     */
+    mul(x: any): Decimal;
+    /**
+     * Returns a new `Decimal` that is the quotient of this and `x`
+     * @param x
+     * @example
+  ```js
+  let a = decimal('1')
+  let b = decimal('3')
+  a.div(b)  // 0.333333333333333333333333333333
+  ```
+     * @returns {Decimal}
+     */
+    div(x: any): Decimal;
+    /**
+     * Returns the square root of this `Decimal`.
+     * @returns {TDecimal}
+     */
+    sqrt(): Decimal;
+    /** Returns a new copy of this Decimal value. */
+    clone(): Decimal;
+    /**
+     * Remove zeroes in the least-significant digit of this `Decimal`
+     */
+    private _normalize;
+    /**
+     * Truncate this `Decimal` to the configured precision
+     */
+    private _truncate;
+    /**
+     * Returns a string representation of this decimal.
+     * @returns {Decimal}
+     */
+    toString(): string;
+    /**
+     * Converts this decimal to the `Number` value
+     * @returns {number}
+     */
+    toNumber(): number;
+    static get precision(): number;
+    static set precision(value: number);
+    /**
+     * Returns `true` if this value is equal to the value of `x`, otherwise `false`.
+     * @param {*} x other
+     * @returns {boolean}
+     */
+    eq(x: any): boolean;
+    /**
+     * Returns `true` if this value is less than the value of `x`, otherwise `false`.
+     * @param {*} x
+     * @returns {boolean}
+     */
+    lt(x: any): boolean;
+    /**
+     * Returns a comparison value representing the ordering of this value in respect to `x`.
+     *   * `-1` if this < x
+     *   * `1` if this > x
+     *   * `0` if this == x
+     * @param {*} x
+     * @returns {number}
+     */
+    compare(x: any): 1 | -1 | 0;
+    /**
+     * Returns `true` if this value is greater than the value of `x`, otherwise `false`.
+     * @param {*} x
+     * @returns {boolean}
+     */
+    gt(x: any): boolean;
+    /**
+     * Returns `true` if this value is less than or equal to the value of `x`, otherwise `false`.
+     * @param {*} x
+     * @returns {boolean}
+     */
+    lte(x: any): boolean;
+    /**
+     * Returns `true` if this value is greater than or equal to the value of `x`, otherwise `false`.
+     * @param {*} x
+     * @returns {boolean}
+     */
+    gte(x: any): boolean;
+}