atomic-fns 0.2.3 → 0.3.1

package/src/functools/index.ts

@@ -4,21 +4,89 @@
  * @module Functions
  */
 
-import { Function } from '../globals/index.js'
+import { Function, isPromise } from '../globals/index.js'
 
-export const bind = (fn, self, ...args) => fn.bind(self, ...args)
+/**
+ * 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 const bind = (fn: Function, thisArg, ...partials) => 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.
+ * @param {Function} func The function to curry.
+ * @param {number} [arity=func.length]
+ * @returns Returns the new curried function.
+ */
+export const curry = (func: Function, arity?: number) => {
+  if (typeof func !== 'function' || func.length < 2) return func
+  if (typeof arity !== 'number') arity = func.length
+  switch (arity) {
+    case 2:
+      return (arg0) => (arg1) => func(arg0, arg1)
+    case 3:
+      return (arg0) => (arg1) => (arg2) => func(arg0, arg1, arg2)
+    case 4:
+      return (arg0) => (arg1) => (arg2) => (arg3) => func(arg0, arg1, arg2, arg3)
+    case 5:
+      return (arg0) => (arg1) => (arg2) => (arg3) => (arg4) => func(arg0, arg1, arg2, arg3, arg4)
+    case 6:
+      return (arg0) => (arg1) => (arg2) => (arg3) => (arg4) => (arg5) =>
+        func(arg0, arg1, arg2, arg3, arg4, arg5)
+    case 7:
+      return (arg0) => (arg1) => (arg2) => (arg3) => (arg4) => (arg5) => (arg6) =>
+        func(arg0, arg1, arg2, arg3, arg4, arg5, arg6)
+    case 8:
+      return (arg0) => (arg1) => (arg2) => (arg3) => (arg4) => (arg5) => (arg6) => (arg7) =>
+        func(arg0, arg1, arg2, arg3, arg4, arg5, arg6, arg7)
+    case 9:
+      return (arg0) =>
+        (arg1) =>
+        (arg2) =>
+        (arg3) =>
+        (arg4) =>
+        (arg5) =>
+        (arg6) =>
+        (arg7) =>
+        (arg8) =>
+          func(arg0, arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8)
+
+    default:
+      throw Error('The specified function uses too many arguments. Consider refactoring it.')
+  }
+}
 
-export const partial = (fn, ...args) => bind(fn, {}, ...args)
+/**
+ * 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.
+ * @param {Function} fn The function to bind.
+ * @param {...*} [args] The arguments to apply to `fn`.
+ * @returns {Function} Returns the new partially applied function
+ */
+export const partial = (fn, ...args) => bind(fn, 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.
+ * @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 const flow =
   (...args) =>
-  (x: any) => {
+  (x) => {
     for (const fn of args) {
       x = fn(x)
     }
     return x
   }
 
+/**
+ * This is just an alias for the {@link flow} function.
+ * @see {@link flow}
+ */
 export const pipe = flow
 
 export const compose = (...args) => flow(args.reverse())
@@ -26,7 +94,6 @@ 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.
  *
- *
  * @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.
@@ -43,16 +110,28 @@ export function memoize(func: Function, resolver?: Function): Function {
   }
 }
 
+// TODO: also sized lru_cache
+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.
  *
- *
- * @param func The function to debounce.
- * @param  wait The number of milliseconds to delay.
- * @param maxWait The maximum time `func` is allowed to be delayed before it's invoked.
+ * @param {Function} func The function to debounce.
+ * @param {number} wait The number of milliseconds to delay.
+ * @param {{ maxWait: number }} [opts] The maximum time `func` is allowed to be delayed before it's invoked.
  * @returns Returns the new debounced function.
  */
-export function debounce(func: Function, wait: number, { maxWait }: { maxWait: number }): Function {
+export function debounce(
+  func: Function,
+  wait: number,
+  { maxWait }: { maxWait?: number } = {}
+): Function {
   let timer, maxTimer, lastResult
   return (...args) => {
     if (timer) clearTimeout(timer)
@@ -77,12 +156,11 @@ 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.
  *
- *
  * @param {Function} func The function to throttle.
- * @param {number} time The number of milliseconds to throttle invocations to.
+ * @param {number} wait The number of milliseconds to throttle invocations to.
  * @return {Function} Returns the new throttled function.
  */
-export function throttle(func: Function, time: number): Function {
+export function throttle(func: Function, wait: number): Function {
   let pending = false
   return (...args) => {
     if (pending) return
@@ -90,6 +168,88 @@ export function throttle(func: Function, time: number): Function {
     pending = true
     setTimeout(() => {
       pending = false
-    }, time)
+    }, wait)
+  }
+}
+
+/**
+ * Creates a function that is restricted to invoking `func` once. Repeat calls to the function return the value of the first invocation. The `func` is invoked with the arguments of the created function.
+ *
+ * @param {Function} func The function to restrict
+ * @returns {Function} Returns the new restricted function.
+ * @example
+```js
+let func = x => x
+let single = once(func)
+single(1) // => 1
+single(2) // => 1
+single(3) // => 1
+// ...
+// => `func` is invoked only once.
+```
+ */
+export function once(func: Function) {
+  let result, isCalled
+  return (...args) => {
+    if (!isCalled) {
+      result = func(...args)
+      isCalled = true
+    }
+    return result
+  }
+}
+
+export type Maybe<T> = T | undefined
+
+export type Result<T, E = any> = [Maybe<T>, Maybe<E>]
+
+/**
+ * Wraps a function to catch any exceptions inside and return a `go` style error-return type.
+ *
+ * @param {Function} fun The function to wrap and catch if it throws.
+ * @param {?function(err: E, res: T): *} [onFinally] Optional callback that will be called on the `finally` clause if given.
+ * @returns {Function} A new function that wraps `fun`.
+ * @template T,E
+ */
+export function result<T = any, E = unknown>(
+  fun: Function<T>,
+  onFinally?: (err: E, res: T) => any
+) {
+  return (...args): Result<T, E> => {
+    let value, err
+    try {
+      value = fun(...args)
+    } catch (error) {
+      err = error
+    } finally {
+      onFinally?.(err, value)
+    }
+    return [value as T, err]
+  }
+}
+
+/**
+ * Wraps a function or promise to catch any exceptions inside and return a `go` style error-return type. This is like {@link result} but it deals with async functions or promises.
+ *
+ * @param {Function|Promise} awaitable The function or promise to await.
+ * @param {?function(err: E, res: T): *} [onFinally] Optional callback that will be called on the `finally` clause if given.
+ * @returns {Function} A new function that awaits the `awaitable` param and returns a return type.
+ * @template T,E
+ */
+export function resultAsync<T = any, E = unknown>(
+  awaitable: Promise<T> | Function<Promise<T>>,
+  onFinally?: (err: E, res: T) => any
+) {
+  return async (...args): Promise<Result<T, E>> => {
+    let value, err
+    try {
+      const promise = isPromise(awaitable) ? awaitable : awaitable(...args)
+      value = await promise
+    } catch (error) {
+      err = error
+    } finally {
+      onFinally?.(err, value)
+    }
+    return [value as T, err]
   }
 }

package/src/globals/index.d.ts

@@ -5,25 +5,27 @@
  */
 /** Describes a function used to compare two values.
  *
- * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort#description}
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort#description Array.sort()}
  */
 export declare type Comp = (x: any, y: any) => -1 | 0 | 1;
+/** This is just a noop function. */
+export declare const _: () => void;
 /**
  * A generic function type with arbitrary arguments and return.
  */
-export declare type Function = (...args: any[]) => any;
+export declare type Function<T = any> = (...args: any) => T;
 /**
  * An iteratee function used for collection methods.
- * @see {@link filter}
- * @see {@link find}
- * @see {@link forEach}
- * @see {@link index}
- * @see {@link map}
- * @see {@link pick}
- * @see {@link omit}
- * @see {@link uniq}
- * @see {@link sortedUniq}
- * @see {@link groupBy}
+ * @see {@link Collections.filter}
+ * @see {@link Collections.find}
+ * @see {@link Collections.forEach}
+ * @see {@link Collections.index}
+ * @see {@link Collections.map}
+ * @see {@link Collections.pick}
+ * @see {@link Collections.omit}
+ * @see {@link Collections.uniq}
+ * @see {@link Collections.sortedUniq}
+ * @see {@link Collections.groupBy}
  */
 export declare type Iteratee<T = any> = (value: T, key?: any, arr?: any) => any;
 export declare type Predicate<T = any> = (value: T) => any;
@@ -111,7 +113,7 @@ export declare const isArray: (x: any) => x is any[];
  */
 export declare const isArrayLike: (x: any) => boolean;
 /** Check if value is a function type. */
-export declare const isFunc: (x: any) => x is Function;
+export declare const isFunc: (x: any) => x is Function<any>;
 /** Check if value is a number type. */
 export declare const isNumber: (x: any) => x is number;
 /** Check if value is a bigint type. */
@@ -142,10 +144,29 @@ export declare const isSymbol: (x: any) => x is symbol;
  */
 export declare function len(value: any): any;
 /**
- * Generates a unique ID using random numbers.
- * If prefix is given, the ID is appended to it.
+ * Generates a unique ID using random numbers. If a prefix is given, the ID is appended to it and returned as a string.
+ * @param {string} [pre=''] The id prefix.
+ * @returns {number|string} Returns the numeric or string ID.
+ * @example
+```js
+uniqueId()
+// => 3445556877
+
+uniqueId('user_')
+// => 'user_1033763188'
+```
  */
 export declare const uniqueId: (pre?: string) => any;
+/**
+ * Generates a monotonically increasing, pseudo-random based uuid-v4 string. These are sortable, url-friendly and are 100% unique if the IDs are generated more than 1 millisecond apart. If two IDs are generated at the same millisecond, the chance of collision is still pretty low (1 in 10^15).
+ * @returns Returns a GUID formatted string.
+ * @example
+```js
+uuid()
+// => '183f8ef3-b8f0-4000-81f5-89234c836d00'
+```
+ */
+export declare const uuid: () => string;
 /**
  * Checks if `obj.key` is a function, and calls it with any given `args`.
  * @param {*} obj
@@ -172,32 +193,6 @@ export declare const keys: (object: Object) => string[];
  * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/values Object.values()}
  */
 export declare const values: (object: 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]
- *
- * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/round Math.round()}
- */
-export declare function round(x: number, digits?: number): number;
-/**
- * Rounds down and returns the largest integer less than or equal to a given number.
- * @param x A number.
- * @returns Nearest integer less than or equal to number.
- *
- * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/floor Math.floor()}
- */
-export declare const floor: (x: number) => number;
-/**
- * Rounds up and returns the largest integer greater than or equal to a given number.
- * @param x A number.
- * @returns Nearest integer greater than or equal to number.
- *
- * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/ceil Math.ceil()}
- */
-export declare const ceil: (x: number) => number;
 /**
  * Check if a given property is present in a given object.
  * @param obj The object to check.

package/src/globals/index.js

@@ -3,6 +3,8 @@
  *
  * @module Globals
  */
+/** This is just a noop function. */
+export const _ = () => { };
 /** A function that always returns `true`. */
 export const True = () => true;
 /** A function that always returns `false`. */
@@ -84,6 +86,8 @@ export function type(value) {
                 return 'function';
             if (value instanceof Array)
                 return 'array';
+            if (value instanceof Error)
+                return 'error';
             if (value[Symbol.toStringTag])
                 return value[Symbol.toStringTag];
             const className = str(value);
@@ -186,12 +190,34 @@ export function len(value) {
     }
 }
 /**
- * Generates a unique ID using random numbers.
- * If prefix is given, the ID is appended to it.
+ * Generates a unique ID using random numbers. If a prefix is given, the ID is appended to it and returned as a string.
+ * @param {string} [pre=''] The id prefix.
+ * @returns {number|string} Returns the numeric or string ID.
+ * @example
+```js
+uniqueId()
+// => 3445556877
+
+uniqueId('user_')
+// => 'user_1033763188'
+```
  */
 export const uniqueId = (pre = '') => 
 // @ts-expect-error
 (pre || 0) + ((Math.random() * 1e10) >>> 0);
+/**
+ * Generates a monotonically increasing, pseudo-random based uuid-v4 string. These are sortable, url-friendly and are 100% unique if the IDs are generated more than 1 millisecond apart. If two IDs are generated at the same millisecond, the chance of collision is still pretty low (1 in 10^15).
+ * @returns Returns a GUID formatted string.
+ * @example
+```js
+uuid()
+// => '183f8ef3-b8f0-4000-81f5-89234c836d00'
+```
+ */
+export const uuid = () => {
+    const u = Date.now().toString(16) + Math.random().toString(16) + '0'.repeat(16);
+    return [u.substr(0, 8), u.substr(8, 4), '4000-8' + u.substr(13, 3), u.substr(16, 12)].join('-');
+};
 /**
  * Checks if `obj.key` is a function, and calls it with any given `args`.
  * @param {*} obj
@@ -222,35 +248,6 @@ export const keys = (object) => Object.keys(object);
  * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/values Object.values()}
  */
 export const values = (object) => Object.values(object);
-/**
- * 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]
- *
- * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/round Math.round()}
- */
-export function round(x, digits = 0) {
-    const base = 10 ** digits;
-    return Math.round(x * base) / base;
-}
-/**
- * Rounds down and returns the largest integer less than or equal to a given number.
- * @param x A number.
- * @returns Nearest integer less than or equal to number.
- *
- * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/floor Math.floor()}
- */
-export const floor = (x) => Math.floor(x);
-/**
- * Rounds up and returns the largest integer greater than or equal to a given number.
- * @param x A number.
- * @returns Nearest integer greater than or equal to number.
- *
- * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/ceil Math.ceil()}
- */
-export const ceil = (x) => Math.ceil(x);
 /**
  * Check if a given property is present in a given object.
  * @param obj The object to check.

package/src/globals/index.ts

@@ -6,27 +6,30 @@
 
 /** Describes a function used to compare two values.
  *
- * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort#description}
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort#description Array.sort()}
  */
 export type Comp = (x, y) => -1 | 0 | 1
 
+/** This is just a noop function. */
+export const _ = () => {}
+
 /**
  * A generic function type with arbitrary arguments and return.
  */
-export type Function = (...args) => any
+export type Function<T = any> = (...args: any) => T
 
 /**
  * An iteratee function used for collection methods.
- * @see {@link filter}
- * @see {@link find}
- * @see {@link forEach}
- * @see {@link index}
- * @see {@link map}
- * @see {@link pick}
- * @see {@link omit}
- * @see {@link uniq}
- * @see {@link sortedUniq}
- * @see {@link groupBy}
+ * @see {@link Collections.filter}
+ * @see {@link Collections.find}
+ * @see {@link Collections.forEach}
+ * @see {@link Collections.index}
+ * @see {@link Collections.map}
+ * @see {@link Collections.pick}
+ * @see {@link Collections.omit}
+ * @see {@link Collections.uniq}
+ * @see {@link Collections.sortedUniq}
+ * @see {@link Collections.groupBy}
  */
 export type Iteratee<T = any> = (value: T, key?, arr?) => any
 
@@ -111,6 +114,7 @@ export function type(value) {
       if (value instanceof Boolean) return 'boolean'
       if (value instanceof Function) return 'function'
       if (value instanceof Array) return 'array'
+      if (value instanceof Error) return 'error'
       if (value[Symbol.toStringTag]) return value[Symbol.toStringTag]
 
       const className = str(value)
@@ -228,13 +232,36 @@ export function len(value) {
 }
 
 /**
- * Generates a unique ID using random numbers.
- * If prefix is given, the ID is appended to it.
+ * Generates a unique ID using random numbers. If a prefix is given, the ID is appended to it and returned as a string.
+ * @param {string} [pre=''] The id prefix.
+ * @returns {number|string} Returns the numeric or string ID.
+ * @example
+```js
+uniqueId()
+// => 3445556877
+
+uniqueId('user_')
+// => 'user_1033763188'
+```
  */
 export const uniqueId = (pre: string = '') =>
   // @ts-expect-error
   (pre || 0) + ((Math.random() * 1e10) >>> 0)
 
+/**
+ * Generates a monotonically increasing, pseudo-random based uuid-v4 string. These are sortable, url-friendly and are 100% unique if the IDs are generated more than 1 millisecond apart. If two IDs are generated at the same millisecond, the chance of collision is still pretty low (1 in 10^15).
+ * @returns Returns a GUID formatted string.
+ * @example
+```js
+uuid()
+// => '183f8ef3-b8f0-4000-81f5-89234c836d00'
+```
+ */
+export const uuid = () => {
+  const u = Date.now().toString(16) + Math.random().toString(16) + '0'.repeat(16)
+  return [u.substr(0, 8), u.substr(8, 4), '4000-8' + u.substr(13, 3), u.substr(16, 12)].join('-')
+}
+
 /**
  * Checks if `obj.key` is a function, and calls it with any given `args`.
  * @param {*} obj
@@ -270,38 +297,6 @@ export const keys = (object: Object) => Object.keys(object)
  */
 export const values = (object) => Object.values(object)
 
-/**
- * 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]
- *
- * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/round Math.round()}
- */
-export function round(x: number, digits = 0) {
-  const base = 10 ** digits
-  return Math.round(x * base) / base
-}
-
-/**
- * Rounds down and returns the largest integer less than or equal to a given number.
- * @param x A number.
- * @returns Nearest integer less than or equal to number.
- *
- * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/floor Math.floor()}
- */
-export const floor = (x: number) => Math.floor(x)
-
-/**
- * Rounds up and returns the largest integer greater than or equal to a given number.
- * @param x A number.
- * @returns Nearest integer greater than or equal to number.
- *
- * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/ceil Math.ceil()}
- */
-export const ceil = (x: number) => Math.ceil(x)
-
 /**
  * Check if a given property is present in a given object.
  * @param obj The object to check.

package/src/itertools/index.d.ts

@@ -72,7 +72,7 @@ contains('abcd', 'bc')
 // => true
 ```
  *
- * @see {@link collections.find}
+ * @see {@link Collections.find}
  */
 export declare function contains(collection: Iterable<any>, value: any): any;
 /**
@@ -141,20 +141,6 @@ export declare function itake<T>(n: number, iterable: Iterable<T>): Generator<un
  */
 export declare function iter<T>(obj: any): Iterator<T>;
 export declare function partition<T>(iterable: Iterable<T>, predicate: Predicate<T>): T[][];
-/**
- * Returns the smallest element in an iterable. The optional `key` argument specifies a transform on the elements before comparing them. If the elements in the iterable are objects that implement a custom `le` method, this will be called to compare.
- * @param iterable The iterable to inspect.
- * @param key Optional key function to transform the elements (default `id`).
- * @returns The smallest element in the iterable.
- */
-export declare function min<T>(iterable: Iterable<T>, key?: (x: any) => any): any;
-/**
- * Returns the largest element in an iterable. The optional `key` argument specifies a transform on the elements before comparing them. If the elements in the iterable are objects that implement a custom `gt` method, this will be called to compare.
- * @param iterable The iterable to inspect.
- * @param key Optional key function to transform the elements (default `id`).
- * @returns The largest element in the iterable.
- */
-export declare function max<T>(iterable: Iterable<T>, key?: (x: any) => any): any;
 /**
  * Returns a generator for a sequence of numbers in the given range, starting from `start` (default 0) to `stop` (not-inclusive) in increments of `step` (default 1).
  *
@@ -208,21 +194,6 @@ export declare function sort(args: any[]): any[];
 export declare function sort(args: any[], reverse: boolean): any[];
 export declare function sort(args: any[], compareFn: Comp): any[];
 export declare function sort(args: any[], reverse: boolean, compareFn: Comp): any[];
-/**
- * Sums `initial` and the items of an iterable and returns the total.
- * @param args The elements to add to `initial`.
- * @param initial The initial value to add to (default `0`).
- * @returns The total sum of initial and iterable elements.
- * @example
-```js
-sum([1, 2, 3, 4])
-// => 10
-
-sum([1, 2, 3, 4], 5)
-// => 15
-```
- */
-export declare function sum(args: Iterable<number>, initial?: number): number;
 export declare function take<T>(n: number, iterable: Iterable<T>): unknown[];
 /**
  * Returns a generator that takes elements from the iterable as long as the predicate is `true`.