atomic-fns 0.2.3 → 0.3.1

package/.firebaserc

@@ -0,0 +1,5 @@
+{
+  "projects": {
+    "default": "atomic-fns"
+  }
+}

package/README.md

@@ -1,5 +1,7 @@
 # atomic-fns
 
+[Read the Docs](https://atomic-fns.dev)
+
 ## Like Lodash, but for ESNext and with types.
 
 Stop shipping code built for browsers from 2015. Really though, look at the [issues](https://github.com/lodash/lodash/issues/2930).
@@ -9,7 +11,8 @@ You may prefer this because it's:
 * **Modular**: Pick what you need. Works with all bundlers and also supports tree-shaking.
 * **ESNext**: Uses modern idiomatic syntax, data structures, and control flow techniques.
 * **Lazy**: Leverage generators, iterators, and functional composition.
-* **Fluent**: Pure functions and abstract classes. Include only what you need.
+* **Zero deps**: Built from scratch with no dependencies whatsoever.
+* **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.
 
 ## Get Started
@@ -39,7 +42,7 @@ uniqueId('user_')
 
 ## Docs
 
-🚢 Coming soon at [atomic-fns.dev](https://atomic-fns.dev)
+📖 Available on [atomic-fns.dev](https://atomic-fns.dev)
 
 💡 See the `src` directory for comments.
 

package/firebase.json

@@ -0,0 +1,10 @@
+{
+  "hosting": {
+    "public": "docs",
+    "ignore": [
+      "firebase.json",
+      "**/.*",
+      "**/node_modules/**"
+    ]
+  }
+}

package/package.json

@@ -1,14 +1,15 @@
 {
   "name": "atomic-fns",
   "description": "Like Lodash, but for ESNext and with types. Stop shipping code built for browsers from 2015.",
-  "version": "0.2.3",
+  "version": "0.3.1",
   "main": "src/index.js",
   "type": "module",
+  "types": "src/index.d.ts",
+  "module": "src/index.js",
+  "sideEffects": false,
   "devDependencies": {
     "@types/jasmine": "^4.3.0",
     "@typescript-eslint/eslint-plugin": "^5.39.0",
-    "esdoc": "^1.1.0",
-    "esdoc-standard-plugin": "^1.0.0",
     "eslint": "^8.25.0",
     "eslint-config-prettier": "^8.5.0",
     "eslint-config-standard-with-typescript": "^23.0.0",
@@ -65,7 +66,10 @@
     "es2022",
     "es2023",
     "lodash",
+    "lodash-es",
+    "itertools",
     "lazy",
+    "module",
     "modules",
     "stdlib",
     "core-js",

package/src/collections/index.d.ts

@@ -595,6 +595,20 @@ merge(object, other)
 ```
  */
 export declare function merge(object: any, ...sources: any[]): Object;
+/**
+ * Assigns own and inherited enumerable string keyed properties of source objects to the destination object for all destination properties that resolve to `undefined`. Source objects are applied from left to right. Once a property is set, additional values of the same property are ignored.
+ * **Note:** This method mutates `object`.
+
+ * @param {Object} object The destination object.
+ * @param {...Object} [sources] The source objects.
+ * @returns Returns `object`.
+ * @example
+```js
+defaults({ 'a': 1 }, { 'b': 2 }, { 'a': 3 })
+// => { 'a': 1, 'b': 2 }
+```
+ */
+export declare function defaults(object: Object, ...sources: Object[]): Object;
 /**
  * Returns a generator of array values not included in the other given arrays using a `Set` for equality comparisons. The order and references of result values are not guaranteed.
  * @param args The initial arrays

package/src/collections/index.js

@@ -944,6 +944,29 @@ export function merge(object, ...sources) {
     }
     return object;
 }
+/**
+ * Assigns own and inherited enumerable string keyed properties of source objects to the destination object for all destination properties that resolve to `undefined`. Source objects are applied from left to right. Once a property is set, additional values of the same property are ignored.
+ * **Note:** This method mutates `object`.
+
+ * @param {Object} object The destination object.
+ * @param {...Object} [sources] The source objects.
+ * @returns Returns `object`.
+ * @example
+```js
+defaults({ 'a': 1 }, { 'b': 2 }, { 'a': 3 })
+// => { 'a': 1, 'b': 2 }
+```
+ */
+export function defaults(object, ...sources) {
+    for (const source of sources) {
+        for (const key in source) {
+            if (object[key] === undefined) {
+                object[key] = source[key];
+            }
+        }
+    }
+    return object;
+}
 /**
  * Returns a generator of array values not included in the other given arrays using a `Set` for equality comparisons. The order and references of result values are not guaranteed.
  * @param args The initial arrays

package/src/collections/index.ts

@@ -1033,6 +1033,30 @@ export function merge(object, ...sources): Object {
   return object
 }
 
+/**
+ * Assigns own and inherited enumerable string keyed properties of source objects to the destination object for all destination properties that resolve to `undefined`. Source objects are applied from left to right. Once a property is set, additional values of the same property are ignored.
+ * **Note:** This method mutates `object`.
+
+ * @param {Object} object The destination object.
+ * @param {...Object} [sources] The source objects.
+ * @returns Returns `object`.
+ * @example
+```js
+defaults({ 'a': 1 }, { 'b': 2 }, { 'a': 3 })
+// => { 'a': 1, 'b': 2 }
+```
+ */
+export function defaults(object: Object, ...sources: Object[]) {
+  for (const source of sources) {
+    for (const key in source) {
+      if (object[key] === undefined) {
+        object[key] = source[key]
+      }
+    }
+  }
+  return object
+}
+
 /**
  * Returns a generator of array values not included in the other given arrays using a `Set` for equality comparisons. The order and references of result values are not guaranteed.
  * @param args The initial arrays

package/src/functools/index.d.ts

@@ -4,38 +4,104 @@
  * @module Functions
  */
 import { Function } from '../globals/index.js';
-export declare const bind: (fn: any, self: any, ...args: any[]) => any;
-export declare const partial: (fn: any, ...args: any[]) => any;
+/**
+ * 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 const bind: (fn: Function, thisArg: any, ...partials: any[]) => (...args: 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.
+ * @param {Function} func The function to curry.
+ * @param {number} [arity=func.length]
+ * @returns Returns the new curried function.
+ */
+export declare const curry: (func: Function, arity?: number) => Function<any>;
+/**
+ * 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 declare const partial: (fn: any, ...args: any[]) => (...args: any[]) => any;
+/**
+ * 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 const flow: (...args: any[]) => (x: any) => any;
+/**
+ * This is just an alias for the {@link flow} function.
+ * @see {@link flow}
+ */
 export declare const pipe: (...args: any[]) => (x: any) => any;
 export declare const compose: (...args: any[]) => (x: any) => any;
 /**
  * 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.
  */
 export declare function memoize(func: Function, resolver?: Function): 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.
  *
- *
- * @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 declare function debounce(func: Function, wait: number, { maxWait }: {
-    maxWait: number;
+export declare function debounce(func: Function, wait: number, { maxWait }?: {
+    maxWait?: number;
 }): Function;
 /**
  * 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 declare function throttle(func: Function, time: number): Function;
+export declare function throttle(func: Function, wait: number): Function;
+/**
+ * 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 declare function once(func: Function): (...args: any[]) => any;
+export declare type Maybe<T> = T | undefined;
+export declare 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 declare function result<T = any, E = unknown>(fun: Function<T>, onFinally?: (err: E, res: T) => any): (...args: any[]) => Result<T, E>;
+/**
+ * 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 declare function resultAsync<T = any, E = unknown>(awaitable: Promise<T> | Function<Promise<T>>, onFinally?: (err: E, res: T) => any): (...args: any[]) => Promise<Result<T, E>>;

package/src/functools/index.js

@@ -3,20 +3,76 @@
  *
  * @module Functions
  */
-export const bind = (fn, self, ...args) => fn.bind(self, ...args);
-export const partial = (fn, ...args) => bind(fn, {}, ...args);
+import { isPromise } 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 const bind = (fn, 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, arity) => {
+    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.');
+    }
+};
+/**
+ * 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) => {
     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());
 /**
  * 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.
@@ -33,16 +89,23 @@ export function memoize(func, resolver) {
         return value;
     };
 }
+// 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, wait, { maxWait }) {
+export function debounce(func, wait, { maxWait } = {}) {
     let timer, maxTimer, lastResult;
     return (...args) => {
         if (timer)
@@ -65,12 +128,11 @@ export function debounce(func, wait, { maxWait }) {
 /**
  * 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, time) {
+export function throttle(func, wait) {
     let pending = false;
     return (...args) => {
         if (pending)
@@ -79,6 +141,79 @@ export function throttle(func, time) {
         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) {
+    let result, isCalled;
+    return (...args) => {
+        if (!isCalled) {
+            result = func(...args);
+            isCalled = true;
+        }
+        return result;
+    };
+}
+/**
+ * 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(fun, onFinally) {
+    return (...args) => {
+        let value, err;
+        try {
+            value = fun(...args);
+        }
+        catch (error) {
+            err = error;
+        }
+        finally {
+            onFinally?.(err, value);
+        }
+        return [value, 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(awaitable, onFinally) {
+    return async (...args) => {
+        let value, err;
+        try {
+            const promise = isPromise(awaitable) ? awaitable : awaitable(...args);
+            value = await promise;
+        }
+        catch (error) {
+            err = error;
+        }
+        finally {
+            onFinally?.(err, value);
+        }
+        return [value, err];
     };
 }