atomic-fns 1.1.6 → 1.2.0

package/dist/decimal/index.js

@@ -3,7 +3,10 @@
  *
  * @module decimal
  */
-const NUMBER_REGEX = /^(-?)([0-9]+)(\.([0-9]+))?$/;
+import { ValueError } from '../globals/index.js';
+const NUMBER_REGEX = /^\s*([+-]?)(?=\.?[0-9])([0-9]*)(\.([0-9]*))?(?:[eE]([+-]?[0-9]+))?\s*$/;
+/** Largest power of ten an exponent may reach, so a short string cannot freeze the page. */
+const MAX_EXPONENT = 10_000;
 /**
  * Casts the given value as a {@link Decimal}.
  */
@@ -23,6 +26,8 @@ export class Decimal {
      * Returns a new `Decimal` instance from the value or `0`.
      * @param {*} value
      * @returns {Decimal}
+     * @throws {ValueError} if the value is not numeric.
+     * @throws {RangeError} if the value is infinite or its exponent is past 10,000.
      */
     constructor(value) {
         if (value == null) {
@@ -35,7 +40,8 @@ export class Decimal {
             this._normalize();
             return this;
         }
-        const result = NUMBER_REGEX.exec(value.toString());
+        const text = value.toString();
+        const result = NUMBER_REGEX.exec(text);
         if (result) {
             // console.log(result);
             // Construct from string if possible
@@ -45,11 +51,22 @@ export class Decimal {
             if (typeof result[4] === 'undefined')
                 result[4] = '';
             this.i = BigInt(result[1] + result[2] + result[4]);
-            this.e = result[4] ? -result[4].length : 0;
+            this.e = Number(result[5] ?? 0) - result[4].length;
             this._normalize();
+            if (result[5]) {
+                const magnitude = this.e + (this.i < 0n ? -this.i : this.i).toString().length - 1;
+                if (this.i === 0n)
+                    this.e = 0;
+                else if (Math.abs(magnitude) > MAX_EXPONENT)
+                    throw new RangeError('exponent out of range');
+            }
         }
         else {
             // Conversion to string failed, so construct from number
+            value = Number(value);
+            if (Number.isNaN(value) || (value === 0 && text.trim() === '')) {
+                throw new ValueError('Decimal value must be numeric');
+            }
             let m = 1n;
             if (value < 0) {
                 value = -value;
@@ -63,7 +80,7 @@ export class Decimal {
                 // Multiply the number by 10 until it is an integer
                 let e = -Math.floor(Math.log10(value));
                 if (e > 0) {
-                    value *= Math.pow(10, e);
+                    value *= 10 ** e;
                 }
                 else {
                     e = 0;
@@ -169,7 +186,7 @@ export class Decimal {
   ```js
   let a = decimal('1')
   let b = decimal('3')
-  a.div(b)  // 0.333333333333333333333333333333
+  a.div(b)  // 0.33333333333333333333
   ```
      * @returns {Decimal}
      */
@@ -179,8 +196,8 @@ export class Decimal {
         // We need to increase the number of digits of a and b so that a / b will have the desired precision.
         // In order for the integer quotient to have the correct precision, a.e - b.e must be greater than that precision.
         // So we need only to increase a.e.
-        // TODO: Revisit the value of increaseA. Is it correct in every circumstance?
-        const increaseA = Math.max(Decimal.precision - (a.e + b.e), 0);
+        // The quotient needs precision + a.e - b.e, and a negative a.e keeps the digits it always had
+        const increaseA = Math.max(Decimal.precision + Math.abs(a.e) - b.e, 0);
         const intIncrease = new Decimal();
         intIncrease.i = exp(a.i, increaseA);
         const quotient = new Decimal();
@@ -192,14 +209,17 @@ export class Decimal {
     }
     /**
      * Returns the square root of this `Decimal`.
-     * @returns {TDecimal}
+     * @returns {Decimal}
+     * @throws {ValueError} if this value is negative.
      */
     sqrt() {
+        if (this.i < 0n)
+            throw new ValueError('square root of a negative number');
         Decimal.PRECISION++;
-        // Let the guess value be 10^(e/2), where e is this.e
+        // Let the guess value be 10^(m/2), where m is the magnitude of this value
         let x = new Decimal();
         x.i = 1n;
-        x.e = Math.floor(this.e / 2);
+        x.e = Math.floor((this.e + this.i.toString().length) / 2);
         const onehalf = new Decimal('0.5');
         let xt = x.clone();
         xt._truncate();
@@ -221,6 +241,13 @@ export class Decimal {
         Decimal.PRECISION--;
         xt._truncate();
         xt._normalize();
+        // Rounding twice can leave the last digit one too high, so check it against the exact square
+        const half = new Decimal();
+        half.i = 5n;
+        half.e = -Decimal.PRECISION - 1;
+        const low = xt.sub(half);
+        if (low.gt(0) && low.mul(low).gt(this))
+            return low.sub(half);
         return xt;
     }
     /** Returns a new copy of this Decimal value. */
@@ -234,10 +261,16 @@ export class Decimal {
      * Remove zeroes in the least-significant digit of this `Decimal`
      */
     _normalize() {
-        while (this.i % 10n === 0n && this.i !== 0n) {
-            this.i /= 10n;
-            this.e++;
-        }
+        if (this.i === 0n)
+            this.e = Math.min(this.e, 0);
+        if (this.i === 0n || this.i % 10n !== 0n)
+            return this;
+        const digits = this.i.toString();
+        let end = digits.length;
+        while (digits[end - 1] === '0')
+            end--;
+        this.i = BigInt(digits.slice(0, end));
+        this.e += digits.length - end;
         return this;
     }
     /**
@@ -264,7 +297,6 @@ export class Decimal {
     }
     /**
      * Returns a string representation of this decimal.
-     * @returns {Decimal}
      */
     toString() {
         let s = this.i.toString();
@@ -278,9 +310,9 @@ export class Decimal {
         }
         else if (this.e < 0) {
             if (-this.e >= s.length) {
-                return m + '0.' + '0'.repeat(-this.e - s.length) + s;
+                return `${m}0.${'0'.repeat(-this.e - s.length)}${s}`;
             }
-            return m + s.slice(0, s.length + this.e) + '.' + s.slice(s.length + this.e, s.length);
+            return `${m}${s.slice(0, s.length + this.e)}.${s.slice(s.length + this.e, s.length)}`;
         }
         else {
             return m + s;
@@ -308,8 +340,16 @@ export class Decimal {
      * @returns {boolean}
      */
     eq(x) {
-        const other = decimal(x);
-        return this.i === other.i && this.e === other.e;
+        if (x == null || typeof x === 'boolean')
+            return false;
+        let other;
+        try {
+            other = decimal(x);
+        }
+        catch {
+            return false;
+        }
+        return this.i === other.i && (this.e === other.e || this.i === 0n);
     }
     /**
      * Returns `true` if this value is less than the value of `x`, otherwise `false`.
@@ -335,9 +375,10 @@ export class Decimal {
      * @returns {number}
      */
     compare(x) {
-        if (this.eq(x))
+        const other = x == null || typeof x === 'boolean' ? decimal(x) : x;
+        if (this.eq(other))
             return 0;
-        if (this.lt(x))
+        if (this.lt(other))
             return -1;
         return 1;
     }
@@ -368,11 +409,5 @@ export class Decimal {
 }
 /** Returns a BigInt that is equal to `i` times `10^e` */
 function exp(i, e) {
-    // TODO: Make this better
-    // The implementation is faster than 10n ** BigInt(e). But could we make it faster still?
-    let ii = i;
-    for (let j = 0; j < e; j++) {
-        ii *= 10n;
-    }
-    return ii;
+    return i * 10n ** BigInt(e);
 }

package/dist/functools/index.d.ts

@@ -3,36 +3,27 @@
  *
  * @module functools
  */
-import { Function } from '../globals/index.js';
+import type { Function } from '../globals/index.js';
 /**
- * Creates a function that invokes `fn` with the this binding of `thisArg` and `partials` as partially applied arguments.
- * @param {Function} fn The function to bind.
- * @param {*} thisArg The `this` value of `fn`.
- * @param {...*} [partials] The arguments to prepend to `fn`.
- * @returns {Function} Returns the new bound function.
- * @see {@link partial}
- */
-export declare function bind(fn: Function, thisArg: any, ...partials: any[]): any;
-/**
- * Creates a function that accepts arguments of `func` and either invokes `func` returning its result, if at least arity number of arguments have been provided, or returns a function that accepts the remaining `func` arguments, and so on. The arity of `func` may be specified if `func.length` is not sufficient.
+ * Creates a function that accepts arguments of `func` and either invokes `func` returning its result, if at least `func.length` arguments have been provided, or returns a function that accepts the remaining `func` arguments, and so on.
  * @param {Function} func The function to curry.
  * @returns Returns the new curried function.
  */
-export declare function curry(func: Function): (...args: any[]) => any;
+export declare function curry(func: Function): Function<ReturnType<typeof func>>;
 /**
  * Creates a function that invokes `fn` with partials prepended to the arguments it receives.
- * **Note:** The given function will have `this` bound to `undefined`. If using `this` inside `fn`, consider {@link bind} instead.
+ * **Note:** The given function will have `this` bound to `undefined`. If using `this` inside `fn`, consider `Function.prototype.bind` instead.
  * @param {Function} fn The function to bind.
  * @param {...*} [args] The arguments to apply to `fn`.
  * @returns {Function} Returns the new partially applied function
  */
-export declare function partial(fn: any, ...args: any[]): any;
+export declare function partial(fn: Function, ...args: any[]): Function<ReturnType<typeof fn>>;
 /**
  * Creates a function composition from a given set of functions that will be each applied on the result of the previous one from left to right.
  * @param {...*} [args] The set of functions to apply.
  * @returns {Function} A new function that applies each given function on the result of the previous one.
  */
-export declare function flow(...args: any[]): (x: any) => any;
+export declare function flow(...args: Function[]): Function;
 /**
  * This is just an alias for the {@link flow} function.
  * @see {@link flow}
@@ -43,7 +34,7 @@ export declare const pipe: typeof flow;
  * @param {...*} [args] The set of functions to apply.
  * @returns {Function} A new function that applies each given function on the result of the previous step.
  */
-export declare function compose(...args: any[]): (x: any) => any;
+export declare function compose(...args: Function[]): Function;
 /**
  * Creates a function that memoizes the result of `func`. If `resolver` is provided, it determines the cache key for storing the result based on the arguments provided to the memoized function. By default, the first argument provided to the memoized function is used as the map cache key.
  *
@@ -52,15 +43,6 @@ export declare function compose(...args: any[]): (x: any) => any;
  * @return {Function} Returns the new memoized function.
  */
 export declare function memoize<T>(func: Function<T>, resolver?: Function): Function<T>;
-/**
- * Can be used as a decorator on any function or method to memoize its results.
- * **NOTE:** By default the given function is memoized using it's first argument, regardless of others.
- * @param target
- * @param name
- * @param descriptor
- * @returns A memoized version of the given function
- */
-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.
  *
@@ -97,9 +79,9 @@ single(3) // 1
 ```
  */
 export declare function once<T>(func: Function<T>): Function<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>;
+export type Maybe<T> = T | undefined;
+export type Result<T, E = any> = [Maybe<T>, Maybe<E>];
+export type Optional<T> = Maybe<T>;
 /**
  * Wraps a function to catch any exceptions inside and return a {@link Result} tuple with the value and error, if any.
  * @template T,E
@@ -122,9 +104,3 @@ export declare function resultAsync<T = any, E = unknown>(fn: Function<Promise<T
  * @returns {Function<Promise<T>>} A function that wraps `fun` and returns a `Promise`.
  */
 export declare function promisify<T>(fun: Function, thisArg?: any): Function<Promise<T>>;
-/**
- * Invokes a given function that accepts callback arguments for success, error and returns a `Promise` of the results.
- * @param {Function} fn A function that accepts callback arguments for success, error.
- * @returns {Promise<T>} A `Promise` that will be resolved when `successCallback` is called or rejected when `errorCallback` is called.
- */
-export declare function callAsync<T = any>(fn: (successCallback: (data: T) => any, errorCallback: Function) => any): Promise<T>;

package/dist/functools/index.js

@@ -4,18 +4,7 @@
  * @module functools
  */
 /**
- * Creates a function that invokes `fn` with the this binding of `thisArg` and `partials` as partially applied arguments.
- * @param {Function} fn The function to bind.
- * @param {*} thisArg The `this` value of `fn`.
- * @param {...*} [partials] The arguments to prepend to `fn`.
- * @returns {Function} Returns the new bound function.
- * @see {@link partial}
- */
-export function bind(fn, thisArg, ...partials) {
-    return fn.bind(thisArg, ...partials);
-}
-/**
- * Creates a function that accepts arguments of `func` and either invokes `func` returning its result, if at least arity number of arguments have been provided, or returns a function that accepts the remaining `func` arguments, and so on. The arity of `func` may be specified if `func.length` is not sufficient.
+ * Creates a function that accepts arguments of `func` and either invokes `func` returning its result, if at least `func.length` arguments have been provided, or returns a function that accepts the remaining `func` arguments, and so on.
  * @param {Function} func The function to curry.
  * @returns Returns the new curried function.
  */
@@ -31,13 +20,13 @@ export function curry(func) {
 }
 /**
  * Creates a function that invokes `fn` with partials prepended to the arguments it receives.
- * **Note:** The given function will have `this` bound to `undefined`. If using `this` inside `fn`, consider {@link bind} instead.
+ * **Note:** The given function will have `this` bound to `undefined`. If using `this` inside `fn`, consider `Function.prototype.bind` instead.
  * @param {Function} fn The function to bind.
  * @param {...*} [args] The arguments to apply to `fn`.
  * @returns {Function} Returns the new partially applied function
  */
 export function partial(fn, ...args) {
-    return bind(fn, undefined, ...args);
+    return fn.bind(undefined, ...args);
 }
 /**
  * Creates a function composition from a given set of functions that will be each applied on the result of the previous one from left to right.
@@ -63,7 +52,7 @@ export const pipe = flow;
  * @returns {Function} A new function that applies each given function on the result of the previous step.
  */
 export function compose(...args) {
-    return flow(args.reverse());
+    return flow(...args.reverse());
 }
 /**
  * Creates a function that memoizes the result of `func`. If `resolver` is provided, it determines the cache key for storing the result based on the arguments provided to the memoized function. By default, the first argument provided to the memoized function is used as the map cache key.
@@ -74,31 +63,15 @@ export function compose(...args) {
  */
 export function memoize(func, resolver) {
     const cache = new Map();
-    return (...args) => {
-        const key = resolver ? resolver(...args) : args[0];
-        const prev = cache.get(key);
-        if (prev !== undefined)
-            return prev;
-        const value = func(...args);
+    return function (...args) {
+        const key = resolver ? resolver.apply(this, args) : args[0];
+        if (cache.has(key))
+            return cache.get(key);
+        const value = func.apply(this, args);
         cache.set(key, value);
         return value;
     };
 }
-/**
- * Can be used as a decorator on any function or method to memoize its results.
- * **NOTE:** By default the given function is memoized using it's first argument, regardless of others.
- * @param target
- * @param name
- * @param descriptor
- * @returns A memoized version of the given function
- */
-export function cache(target, name, descriptor) {
-    const original = descriptor.value;
-    if (typeof original === 'function') {
-        descriptor.value = memoize(original);
-    }
-    return descriptor;
-}
 /**
  * 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.
  *
@@ -108,20 +81,21 @@ export function cache(target, name, descriptor) {
  * @returns Returns the new debounced function.
  */
 export function debounce(func, wait, { maxWait } = {}) {
-    let timer, maxTimer, lastResult;
-    return (...args) => {
+    let timer, maxTimer, lastResult, latestCall;
+    return function (...args) {
+        latestCall = () => func.apply(this, args);
         if (timer)
             clearTimeout(timer);
         timer = setTimeout(() => {
             clearTimeout(maxTimer);
             maxTimer = null;
-            lastResult = func(...args);
+            lastResult = func.apply(this, args);
         }, wait);
         if (maxWait && !maxTimer) {
             maxTimer = setTimeout(() => {
                 clearTimeout(timer);
                 maxTimer = null;
-                lastResult = func(...args);
+                lastResult = latestCall();
             }, maxWait);
         }
         return lastResult;
@@ -136,14 +110,16 @@ export function debounce(func, wait, { maxWait } = {}) {
  */
 export function throttle(func, wait) {
     let pending = false;
-    return (...args) => {
+    let lastResult;
+    return function (...args) {
         if (pending)
-            return;
-        func(...args);
+            return lastResult;
+        lastResult = func.apply(this, args);
         pending = true;
         setTimeout(() => {
             pending = false;
         }, wait);
+        return lastResult;
     };
 }
 /**
@@ -164,9 +140,9 @@ single(3) // 1
  */
 export function once(func) {
     let result, isCalled;
-    return (...args) => {
+    return function (...args) {
         if (!isCalled) {
-            result = func(...args);
+            result = func.apply(this, args);
             isCalled = true;
         }
         return result;
@@ -179,10 +155,10 @@ export function once(func) {
  * @returns {Function} A new function that wraps `fn` and returns the result tuple.
  */
 export function result(fn) {
-    return (...args) => {
+    return function (...args) {
         let value, err;
         try {
-            value = fn(...args);
+            value = fn.apply(this, args);
         }
         catch (error) {
             err = error;
@@ -197,10 +173,10 @@ export function result(fn) {
  * @returns {Function<Promise<Result<T, E>>>} A new function that awaits the given function and returns the result tuple.
  */
 export function resultAsync(fn) {
-    return async (...args) => {
+    return async function (...args) {
         let value, err;
         try {
-            value = await fn(...args);
+            value = await fn.apply(this, args);
         }
         catch (error) {
             err = error;
@@ -225,11 +201,3 @@ export function promisify(fun, thisArg) {
         }));
     };
 }
-/**
- * Invokes a given function that accepts callback arguments for success, error and returns a `Promise` of the results.
- * @param {Function} fn A function that accepts callback arguments for success, error.
- * @returns {Promise<T>} A `Promise` that will be resolved when `successCallback` is called or rejected when `errorCallback` is called.
- */
-export async function callAsync(fn) {
-    return await new Promise(fn);
-}

package/dist/globals/index.d.ts

@@ -6,7 +6,7 @@
 /**
  * A generic function type with arbitrary arguments and return.
  */
-export declare type Function<TReturn = any> = (...args: any) => TReturn;
+export type Function<TReturn = any> = (...args: any) => TReturn;
 /** This is just a noop function. */
 export declare function noop(): void;
 /** A function that always returns `true`. */
@@ -22,9 +22,10 @@ export declare class CustomError extends Error {
     /**
      * Returns a new CustomError with the specified message.
      * @param {string} message
+     * @param {ErrorOptions} [options] Standard error options such as `cause`.
      * @constructor
      */
-    constructor(message?: string);
+    constructor(message?: string, options?: ErrorOptions);
 }
 /**
  * Custom error to signal an invalid index access.
@@ -76,7 +77,7 @@ export declare function type(value: any): string;
  * @returns `obj.toString()` or `''` if `obj` is `null` or `undefined`.
  * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/toString | Object.toString }
  */
-export declare function str(obj: any): any;
+export declare function str(obj: any): string;
 /** Check if value is a boolean type. */
 export declare function isBool(x: any): x is boolean;
 /** Check if value is an `Error` type. */
@@ -89,8 +90,6 @@ export declare function isDate(x: any): x is Date;
 export declare function isObject(x: any): x is Object;
 /** Check if value is a string type. */
 export declare function isString(x: any): x is string;
-/** Check if value is an Array type. */
-export declare function isArray(x: any): x is any[];
 /**
  * Check if value is Array-like type.
  * A value is considered array-like if it's not a function and has a `.length` number property.
@@ -98,8 +97,6 @@ export declare function isArray(x: any): x is any[];
 export declare function isArrayLike(x: any): boolean;
 /** Check if value is a number type. */
 export declare function isNumber(x: any): x is number;
-/** Check if value is an integer number type. */
-export declare function isInteger(x: any): x is number;
 /** Check if value is a bigint type. */
 export declare function isBigint(x: any): x is BigInt;
 /** Check if value is a Promise type. */
@@ -170,25 +167,11 @@ export declare function uuid(): string;
  * @param {...any[]} args
  * @return `obj.key(...args)` or `undefined`.
  */
-export declare function call(obj: any, key: PropertyKey, ...args: any[]): any;
+export declare function call<T = any>(obj: any, key: PropertyKey, ...args: any[]): T;
 /** Convert number to unicode character */
 export declare function chr(x: number): string;
 /** Convert character to Unicode code point */
 export declare function ord(x: string): number;
-/**
- * Returns an array of the own enumerable property names of `object`.
- * @param object The given object.
- * @returns The array of object keys.
- * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/keys Object.keys()}
- */
-export declare function keys<T>(object: T): (keyof T)[];
-/**
- * Returns an array of the own enumerable property values of `object`.
- * @param object The given object.
- * @returns The array of object keys.
- * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/values Object.values()}
- */
-export declare function values(object: any): unknown[];
 /**
  * Check if a given property is present in a given object.
  * @param obj The object to check.