atomic-fns 0.1.0 → 0.2.0

package/src/functools.ts

@@ -20,7 +20,7 @@ export const compose = (...args) => 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.
  *
- * @export
+ *
  * @param {Function} func The function to have its output memoized.
  * @param {Function} [resolver] The function to resolve the cache key.
  * @return {Function} Returns the new memoized function.
@@ -40,7 +40,7 @@ export function memoize(func: Function, resolver?: Function): Function {
 /**
  * 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.
  *
- * @export
+ *
  * @param {Function} func The function to debounce.
  * @param {number} wait The number of milliseconds to delay.
  * @param {{ maxWait: number }} { maxWait } The maximum time `func` is allowed to be delayed before it's invoked.
@@ -71,7 +71,7 @@ export function debounce(func: Function, wait: number, { maxWait }: { maxWait: n
 /**
  * Creates a throttled function that only invokes `func` at most once per every `wait` milliseconds. Subsequent calls to the throttled function return the result of the last successful invocation.
  *
- * @export
+ *
  * @param {Function} func The function to throttle.
  * @param {number} time The number of milliseconds to throttle invocations to.
  * @return {Function} Returns the new throttled function.

package/src/globals.d.ts

@@ -1,5 +1,175 @@
-interface ErrorConstructor {
-  /** See https://v8.dev/docs/stack-trace-api#stack-trace-collection-for-custom-exceptions. */
-  // eslint-disable-next-line @typescript-eslint/ban-types
-  captureStackTrace(error: Object, constructor?: Function): void
+export declare type Comp = (x: any, y: any) => number;
+export declare type Function = (...args: any[]) => any;
+export declare type Iteratee = (value: any, key?: any, arr?: any) => any;
+export declare const True: () => boolean;
+export declare const False: () => boolean;
+/**
+ * A custom error class that inherits from the Error object.
+ *
+ *
+ * @class CustomError
+ * @extends {Error}
+ */
+export declare class CustomError extends Error {
+    /**
+     * Returns a new CustomError with the specified message.
+     * @param message
+     * @constructor
+     */
+    constructor(message?: any);
 }
+/**
+ * Custom error to signal an invalid index access.
+ * @extends {CustomError}
+ */
+export declare class IndexError extends CustomError {
+}
+/**
+ * Raised when a system function returns an I/O failure such as "file not found"
+ * or "disk full".
+ * @extends {CustomError}
+ */
+export declare class IOError extends CustomError {
+}
+/**
+ * Custom error to signal an invalid key access.
+ * @extends {CustomError}
+ */
+export declare class KeyError extends CustomError {
+}
+/**
+ * Custom error to signal an invalid operation.
+ * @extends {CustomError}
+ */
+export declare class NotImplementedError extends CustomError {
+}
+/**
+ * Custom error to signal an invalid value.
+ * @extends {CustomError}
+ */
+export declare class ValueError extends CustomError {
+}
+/**
+ * Raised when the second argument of a division or modulo operation is zero.
+ * @extends {CustomError}
+ */
+export declare class ZeroDivisionError extends CustomError {
+}
+/**
+ * Returns the true type of any value with correct detection for null, Array,
+ * Object, Promise, Symbol, and NaN.
+ *
+ *
+ * @param {*} value
+ * @return
+ */
+export declare function type(value: any): "string" | "number" | "bigint" | "boolean" | "symbol" | "undefined" | "object" | "function" | "array" | "promise" | "null" | "NaN";
+/** Same as `x.toString()`. Returns `''` when x is null or undefined */
+export declare const str: (x: any) => any;
+/** Check if value is a boolean type */
+export declare const isBool: (x: any) => boolean;
+/** Check if value is an object type */
+export declare const isObject: (x: any) => boolean;
+/** Check if value is a string type */
+export declare const isString: (x: any) => boolean;
+/** Check if value is an Array type */
+export declare const isArray: (x: any) => boolean;
+/** 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.
+ */
+export declare const isArrayLike: (x: any) => boolean;
+/** Check if value is a function type */
+export declare const isFunc: (x: any) => boolean;
+/** Check if value is a number type */
+export declare const isNumber: (x: any) => boolean;
+/** Check if value is a Bigint type */
+export declare const isBigint: (x: any) => boolean;
+/** Check if value is NaN based on `Number.isNaN` */
+export declare const isNaN: (x: any) => boolean;
+/** Check if value is a Promise type */
+export declare const isPromise: (x: any) => boolean;
+/** Check if value is an async function type */
+export declare const isAsync: (x: any) => boolean;
+/** Check if value is a generator function type */
+export declare const isGenerator: (x: any) => boolean;
+/** Check if value is null or undefined */
+export declare const isNull: (x: any) => boolean;
+/** Check if value is not null or undefined */
+export declare const notNull: (x: any) => boolean;
+export declare function len(x: any): any;
+/** Returns true for objects without length or falsey values. */
+export declare const isEmpty: (x: any) => boolean;
+/** Check if value is a Symbol type */
+export declare const isSymbol: (x: any) => boolean;
+/**
+ * Generates a unique ID using random numbers.
+ * If prefix is given, the ID is appended to it
+ */
+export declare const uniqueId: (pre?: string) => any;
+/**
+ * Checks if `obj.key` is a function, and calls it with any `args`.
+ *
+ *
+ * @param {*} obj
+ * @param {PropertyKey} key
+ * @param {...any[]} args
+ * @return `obj.key(...args)`
+ */
+export declare function call(obj: any, key: PropertyKey, ...args: any[]): any;
+/** Convert number to unicode character */
+export declare const chr: (x: number) => string;
+/** Convert character to Unicode code point */
+export declare const ord: (x: string) => number;
+/** `Object.keys(x)` */
+export declare const keys: (x: any) => string[];
+/** `Object.values(x)` */
+export declare const values: (x: any) => unknown[];
+/**
+ * Round `x` to the number of digits after the decimal point. If `digits` is
+ * omitted, it returns the nearest integer to x.
+ *
+ * @param {number} x
+ * @param {number} [digits=0]
+ */
+export declare function round(x: number, digits?: number): number;
+export declare const floor: (x: number) => number;
+export declare const ceil: (x: number) => number;
+/**
+ * Yields elements like [index, item] from an iterable.
+ *
+ *
+ * @template T
+ * @param {Iterable<T>} iterable
+ */
+export declare function enumerate<T = unknown>(iterable: Iterable<T>): Generator<(number | T)[], void, unknown>;
+export declare const has: (obj: any, attr: PropertyKey) => any;
+/**
+ * Check if the attribute is present in the object, or return optional default.
+ *
+ *
+ * @param {*} obj
+ * @param {PropertyKey} key
+ * @param {*} [value=undefined]
+ * @return The property value or default value
+ */
+export declare function get(obj: any, key: PropertyKey | PropertyKey[], value?: any): any;
+export declare function del(x: any, attr: any): any;
+export declare function set(self: any, attr: PropertyKey, value: any, writable?: boolean, enumerable?: boolean): any;
+export declare const HASH_KEY: unique symbol;
+export declare function hash(obj: any): any;
+/**
+ * A hash value generator for strings
+ *
+ * @param {string} str
+ * @return {number}
+ * @see http://isthe.com/chongo/tech/comp/fnv/
+ */
+export declare function hashCode(str: string): number;
+export declare const bin: (n: number) => string;
+export declare const hex: (n: number) => string;
+export declare const oct: (n: number) => string;
+export declare const float: (x: any) => number;
+export declare const int: (x: any, base?: number) => number;
+export declare const list: (arr?: any) => unknown[];
+export declare const next: (iter: Iterator<unknown>) => any;

package/{build → src}/globals.js

@@ -3,7 +3,7 @@ export const False = () => false;
 /**
  * A custom error class that inherits from the Error object.
  *
- * @export
+ *
  * @class CustomError
  * @extends {Error}
  */
@@ -65,7 +65,7 @@ export class ZeroDivisionError extends CustomError {
  * Returns the true type of any value with correct detection for null, Array,
  * Object, Promise, Symbol, and NaN.
  *
- * @export
+ *
  * @param {*} value
  * @return
  */
@@ -141,12 +141,8 @@ export function type(value) {
         return 'NaN';
     return result;
 }
-/** Same as calling toString() */
-export const str = (x) => {
-    if (isNull(x))
-        return '';
-    return x.toString?.() ?? String(x);
-};
+/** Same as `x.toString()`. Returns `''` when x is null or undefined */
+export const str = (x) => (x != null ? x.toString() : '');
 /** Check if value is a boolean type */
 export const isBool = (x) => type(x) === 'boolean';
 /** Check if value is an object type */
@@ -174,20 +170,22 @@ export const isNaN = (x) => Number.isNaN(x);
 /** Check if value is a Promise type */
 export const isPromise = (x) => type(x) === 'promise';
 /** Check if value is an async function type */
-export const isAsync = (x) => x?.constructor.name === 'AsyncFunction';
+export const isAsync = (x) => get(x, 'constructor.name') === 'AsyncFunction';
 /** Check if value is a generator function type */
 export const isGenerator = (x) => {
-    return x?.constructor.constructor?.name === 'GeneratorFunction';
+    return get(x, 'constructor.constructor.name') === 'GeneratorFunction';
 };
 /** Check if value is null or undefined */
 export const isNull = (x) => x == null;
 /** Check if value is not null or undefined */
 export const notNull = (x) => x != null;
 export function len(x) {
-    if (isNumber(x?.length)) {
+    if (x == null)
+        return;
+    if (x.length !== undefined) {
         return x.length;
     }
-    if (isFunc(x?.size)) {
+    if (isFunc(x.size)) {
         return x.size();
     }
     if (isObject(x)) {
@@ -208,7 +206,7 @@ export const uniqueId = (pre = '') =>
 /**
  * Checks if `obj.key` is a function, and calls it with any `args`.
  *
- * @export
+ *
  * @param {*} obj
  * @param {PropertyKey} key
  * @param {...any[]} args
@@ -230,7 +228,7 @@ export const values = (x) => Object.values(x);
 /**
  * Round `x` to the number of digits after the decimal point. If `digits` is
  * omitted, it returns the nearest integer to x.
- * @export
+ *
  * @param {number} x
  * @param {number} [digits=0]
  */
@@ -243,7 +241,7 @@ export const ceil = (x) => Math.ceil(x);
 /**
  * Yields elements like [index, item] from an iterable.
  *
- * @export
+ *
  * @template T
  * @param {Iterable<T>} iterable
  */
@@ -257,16 +255,15 @@ export const has = (obj, attr) => obj && attr in obj;
 /**
  * Check if the attribute is present in the object, or return optional default.
  *
- * @export
+ *
  * @param {*} obj
  * @param {PropertyKey} key
  * @param {*} [value=undefined]
  * @return The property value or default value
  */
 export function get(obj, key, value = undefined) {
-    if (obj == null) {
-        return value ?? obj;
-    }
+    if (obj == null)
+        return value;
     let paths = Array.isArray(key) ? key : [key];
     if (typeof key === 'string') {
         paths = key.split('.');
@@ -276,7 +273,7 @@ export function get(obj, key, value = undefined) {
         for (const k of paths) {
             result = result[k];
         }
-        return result ?? value;
+        return result === undefined ? value : result;
     }
     catch (error) {
         return value;
@@ -309,7 +306,7 @@ export function hash(obj) {
 }
 /**
  * A hash value generator for strings
- * @export
+ *
  * @param {string} str
  * @return {number}
  * @see http://isthe.com/chongo/tech/comp/fnv/

package/src/globals.ts

@@ -11,7 +11,7 @@ export const False = () => false
 /**
  * A custom error class that inherits from the Error object.
  *
- * @export
+ *
  * @class CustomError
  * @extends {Error}
  */
@@ -73,7 +73,7 @@ export class ZeroDivisionError extends CustomError {}
  * Returns the true type of any value with correct detection for null, Array,
  * Object, Promise, Symbol, and NaN.
  *
- * @export
+ *
  * @param {*} value
  * @return
  */
@@ -144,11 +144,8 @@ export function type(value) {
   return result
 }
 
-/** Same as calling toString() */
-export const str = (x): string => {
-  if (isNull(x)) return ''
-  return x.toString?.() ?? String(x)
-}
+/** Same as `x.toString()`. Returns `''` when x is null or undefined */
+export const str = (x) => (x != null ? x.toString() : '')
 
 /** Check if value is a boolean type */
 export const isBool = (x) => type(x) === 'boolean'
@@ -187,11 +184,11 @@ export const isNaN = (x) => Number.isNaN(x)
 export const isPromise = (x) => type(x) === 'promise'
 
 /** Check if value is an async function type */
-export const isAsync = (x) => x?.constructor.name === 'AsyncFunction'
+export const isAsync = (x) => get(x, 'constructor.name') === 'AsyncFunction'
 
 /** Check if value is a generator function type */
 export const isGenerator = (x) => {
-  return x?.constructor.constructor?.name === 'GeneratorFunction'
+  return get(x, 'constructor.constructor.name') === 'GeneratorFunction'
 }
 
 /** Check if value is null or undefined */
@@ -201,10 +198,11 @@ export const isNull = (x) => x == null
 export const notNull = (x) => x != null
 
 export function len(x) {
-  if (isNumber(x?.length)) {
+  if (x == null) return
+  if (x.length !== undefined) {
     return x.length
   }
-  if (isFunc(x?.size)) {
+  if (isFunc(x.size)) {
     return x.size()
   }
   if (isObject(x)) {
@@ -229,7 +227,7 @@ export const uniqueId = (pre: string = '') =>
 /**
  * Checks if `obj.key` is a function, and calls it with any `args`.
  *
- * @export
+ *
  * @param {*} obj
  * @param {PropertyKey} key
  * @param {...any[]} args
@@ -256,7 +254,7 @@ export const values = (x) => Object.values(x)
 /**
  * Round `x` to the number of digits after the decimal point. If `digits` is
  * omitted, it returns the nearest integer to x.
- * @export
+ *
  * @param {number} x
  * @param {number} [digits=0]
  */
@@ -272,7 +270,7 @@ export const ceil = (x: number) => Math.ceil(x)
 /**
  * Yields elements like [index, item] from an iterable.
  *
- * @export
+ *
  * @template T
  * @param {Iterable<T>} iterable
  */
@@ -288,16 +286,14 @@ export const has = (obj, attr: PropertyKey) => obj && attr in obj
 /**
  * Check if the attribute is present in the object, or return optional default.
  *
- * @export
+ *
  * @param {*} obj
  * @param {PropertyKey} key
  * @param {*} [value=undefined]
  * @return The property value or default value
  */
 export function get(obj: any, key: PropertyKey | PropertyKey[], value: any = undefined) {
-  if (obj == null) {
-    return value ?? obj
-  }
+  if (obj == null) return value
 
   let paths = Array.isArray(key) ? key : [key]
   if (typeof key === 'string') {
@@ -309,7 +305,7 @@ export function get(obj: any, key: PropertyKey | PropertyKey[], value: any = und
     for (const k of paths) {
       result = result[k]
     }
-    return result ?? value
+    return result === undefined ? value : result
   } catch (error) {
     return value
   }
@@ -347,7 +343,7 @@ export function hash(obj) {
 
 /**
  * A hash value generator for strings
- * @export
+ *
  * @param {string} str
  * @return {number}
  * @see http://isthe.com/chongo/tech/comp/fnv/

package/{build → src}/itertools.js

@@ -35,7 +35,7 @@ export function reversed(iterable) {
  *
  * If `args` is an Object, returns the sorted keys.
  *
- * @export
+ *
  * @param {(Array | Object)} args
  * @param {(boolean | Function)} [key]
  * @param {(boolean | Comp)} [reverse]
@@ -56,7 +56,7 @@ export function sorted(args, key, reverse, compareFn) {
         key = id;
     }
     const copy = Array.from(args);
-    const _compare = compKey(compareFn ?? comp, key ?? id);
+    const _compare = compKey(compareFn || comp, key || id);
     copy.sort(_compare);
     if (reverse)
         copy.reverse();
@@ -67,19 +67,18 @@ export function sorted(args, key, reverse, compareFn) {
  *   - sort([...], true) => reverse order
  *   - sort([...], (x, y) => number) => using custom compare
  *   - sort([...], true, (x, y) => number) => reverse and using custom compare
- * @export
+ *
  * @param {any[]} args
  * @param {(boolean | Comp)} [reverse]
  * @param {Comp} [compareFn]
  * @return
  */
 export function sort(args, reverse, compareFn) {
-    compareFn ??= comp;
     if (typeof reverse === 'function') {
         compareFn = reverse;
         reverse = false;
     }
-    args.sort(compareFn);
+    args.sort(compareFn || comp);
     if (reverse === true)
         args.reverse();
     return args;

package/src/itertools.ts

@@ -43,7 +43,7 @@ export function sorted(args: any[], key: Function, reverse: boolean): any[]
  *
  * If `args` is an Object, returns the sorted keys.
  *
- * @export
+ *
  * @param {(Array | Object)} args
  * @param {(boolean | Function)} [key]
  * @param {(boolean | Comp)} [reverse]
@@ -62,7 +62,7 @@ export function sorted(args, key?: boolean | Function, reverse?: boolean | Comp,
     key = id
   }
   const copy = Array.from(args)
-  const _compare = compKey(compareFn ?? comp, key ?? id)
+  const _compare = compKey(compareFn || comp, key || id)
   copy.sort(_compare)
   if (reverse) copy.reverse()
   return copy
@@ -78,19 +78,18 @@ export function sort(args: any[], reverse: boolean, compareFn: Comp): any[]
  *   - sort([...], true) => reverse order
  *   - sort([...], (x, y) => number) => using custom compare
  *   - sort([...], true, (x, y) => number) => reverse and using custom compare
- * @export
+ *
  * @param {any[]} args
  * @param {(boolean | Comp)} [reverse]
  * @param {Comp} [compareFn]
  * @return
  */
 export function sort(args: any[], reverse?: boolean | Comp, compareFn?: Comp) {
-  compareFn ??= comp
   if (typeof reverse === 'function') {
     compareFn = reverse
     reverse = false
   }
-  args.sort(compareFn)
+  args.sort(compareFn || comp)
   if (reverse === true) args.reverse()
   return args
 }

package/{build → src}/math.d.ts

@@ -1,7 +1,7 @@
 export declare function abs(x: number): any;
 /**
  * Returns a tuple like (x / y, x % y)
- * @export
+ *
  * @param {number} x
  * @param {number} y
  * @return {number[]}

package/{build → src}/math.js

@@ -8,7 +8,7 @@ export function abs(x) {
 }
 /**
  * Returns a tuple like (x / y, x % y)
- * @export
+ *
  * @param {number} x
  * @param {number} y
  * @return {number[]}

package/src/math.ts

@@ -9,7 +9,7 @@ export function abs(x: number) {
 
 /**
  * Returns a tuple like (x / y, x % y)
- * @export
+ *
  * @param {number} x
  * @param {number} y
  * @return {number[]}

package/{build → src}/operators.d.ts

@@ -21,7 +21,7 @@ export declare function mod(x: any, y: any): any;
 /**
  * Calculates `x` to the power of `y`. If `x` implements a custom `pow` operator
  * it will return `x.pow(y)`.
- * @export
+ *
  * @param {*} x
  * @param {*} y
  * @return `x` raised to the power `y`

package/{build → src}/operators.js

@@ -115,7 +115,7 @@ export function mod(x, y) {
 /**
  * Calculates `x` to the power of `y`. If `x` implements a custom `pow` operator
  * it will return `x.pow(y)`.
- * @export
+ *
  * @param {*} x
  * @param {*} y
  * @return `x` raised to the power `y`

package/src/operators.ts

@@ -114,7 +114,7 @@ export function mod(x, y) {
 /**
  * Calculates `x` to the power of `y`. If `x` implements a custom `pow` operator
  * it will return `x.pow(y)`.
- * @export
+ *
  * @param {*} x
  * @param {*} y
  * @return `x` raised to the power `y`

package/src/random.d.ts

@@ -0,0 +1,22 @@
+/** Returns a random float between a [min, max) value (max exclusive). */
+export declare const random: (min?: number, max?: number) => number;
+/** Returns a random integer between a [min, max] value (inclusive). */
+export declare const randomInt: (min?: number, max?: number) => number;
+/** Returns the item at some random index in a sequence. */
+export declare const choice: (arr: any[]) => any;
+/**
+ * Returns a random sample of size k from a list of items.
+ *
+ * @export
+ * @param {any[]} arr
+ * @param {number} k
+ * @return
+ */
+export declare function sample(arr: any[], k: number): any[] | undefined;
+/**
+ * Shuffles a collection elements in-place. Uses the Fisher-Yates algorithm for uniform shuffling. If collection is an Object it returns shuffled `Object.values()`.
+ *
+ * @param {*} arr
+ * @return
+ */
+export declare function shuffle(arr: any): any;

package/src/random.js

@@ -0,0 +1,48 @@
+import { isObject } from './globals';
+/** Returns a random float between a [min, max) value (max exclusive). */
+export const random = (min = 0, max = 1) => Math.random() * (max - min) + min;
+/** Returns a random integer between a [min, max] value (inclusive). */
+export const randomInt = (min = 0, max = 1) => Math.round(random(min, max));
+/** Returns the item at some random index in a sequence. */
+export const choice = (arr) => {
+    if (!arr || !arr.length)
+        return;
+    return arr[randomInt(0, arr.length - 1)];
+};
+/**
+ * Returns a random sample of size k from a list of items.
+ *
+ * @export
+ * @param {any[]} arr
+ * @param {number} k
+ * @return
+ */
+export function sample(arr, k) {
+    if (!arr || !arr.length || arr.length < k)
+        return;
+    const result = [];
+    for (let i = 0; i < k; i++) {
+        result.push(choice(arr));
+    }
+    return result;
+}
+/**
+ * Shuffles a collection elements in-place. Uses the Fisher-Yates algorithm for uniform shuffling. If collection is an Object it returns shuffled `Object.values()`.
+ *
+ * @param {*} arr
+ * @return
+ */
+export function shuffle(arr) {
+    if (!arr || !arr.length)
+        return;
+    if (isObject(arr))
+        arr = Object.values(arr);
+    const n = arr.length - 1;
+    for (let i = n; i > 0; i--) {
+        const j = randomInt(0, i);
+        const temp = arr[j];
+        arr[j] = arr[i];
+        arr[i] = temp;
+    }
+    return arr;
+}