fnts 1.2.0 → 1.3.0

package/README.md

@@ -1,6 +1,6 @@
 <p align="center">
   <img src="https://raw.githubusercontent.com/drizzer14/fnts/main/logo.svg" height="64" />
-  <h1 align="center">fnts</h1>
+  <h1 align="center">λ fnts</h1>
 </p>
 
 <p align="center">
@@ -24,62 +24,16 @@ TypeScript / JavaScript functional programming utilities inspired by the
 **TypeScript 4.2.2 is required for this package's typings to work properly.**
 
 ```shell
-λ npm i fnts typescript@4.2.2
+npm i fnts
 ```
 
 ```shell
-λ yarn add fnts typescript@4.2.2
+yarn add fnts
 ```
 
 ## Usage
 
-Every function comes with its own module providing the named export of every public API 
-and default export of the function itself:
-
-```typescript
-import compose from 'fnts/compose'
-import maybe, { Maybe } from 'fnts/maybe'
-```
-
-Also, it is possible to import everything from the root by name:
-
-```typescript
-import { compose, maybe, identity } from 'fnts'
-```
-
-### Currying
-
-The [curry](src/curry.ts) function is an attempt to create 
-a generic currying without relying on overloads.
-It supports the currying of functions with a set amount of arguments, 
-as well as variadic functions or the functions with optional arguments.
-The last two, though, require you to set the threshold upon which to curry them,
-as JavaScript does not supply the information about the number of arguments
-in those kinds of functions.
-
-### Composition and pipelines
-
-[Compose](src/compose.ts) and [pipe](src/pipe.ts) functions you'll encounter
-here are pretty unique in their implementation, as they also are described 
-generically rather than through overloads. 
-If you encounter any unexpected behaviour in them, 
-please feel free to create an [issue](https://github.com/drizzer14/fnts/issues).
-
-### Monads
-
-There are two commonly used monads in this package: 
-[Maybe](src/maybe/maybe.ts) and [Either](src/either/either.ts).
-
-Both have their own set of constructors, which rely upon special tags
-represented through symbols – this way the "operators" know you pass them
-the objects related to those monads 
-(e.g. [just](src/maybe/maybe.ts) and [nothing](src/maybe/maybe.ts) from `Maybe` monad).
-
-For both monads there are aforementioned operators, 
-which can perform different transformations on their monads.
-These operators look just like plain functions, so, 
-if you are familiar with Haskell or RxJS, 
-you should quickly get a grasp on them.
+Please, visit the [documentation](https://drizzer14.github.io/fnts) to obtain the information about the usage and API of `fnts`.
 
 ## Motivation
 

package/cjs/compose.js

@@ -0,0 +1,25 @@
+"use strict";
+/**
+ * @module Composition
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Applies all of the provided `functions` one-by-one in right-to-left order
+ * starting from the `argument`.
+ */
+function compose() {
+    var functions = [];
+    for (var _i = 0; _i < arguments.length; _i++) {
+        functions[_i] = arguments[_i];
+    }
+    return function (arg) {
+        var length = functions.length;
+        var composition = arg;
+        for (var index = length - 1; index >= 0; index -= 1) {
+            var current = functions[index];
+            composition = current(composition);
+        }
+        return composition;
+    };
+}
+exports.default = compose;

package/cjs/curry.js

@@ -0,0 +1,37 @@
+"use strict";
+/**
+ * @module Curry
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Creates an auto-curried function from the one provided.
+ * Until the curried function receives an expected number of arguments,
+ * defined by either its `length` property or the `length` argument of `curry`,
+ * it will return new function which receives from one to the remaining amount
+ * of arguments.
+ * Any excess arguments will not be applied.
+ */
+function curry(fn, length) {
+    if (length === void 0) { length = fn.length; }
+    return function () {
+        var args = [];
+        for (var _i = 0; _i < arguments.length; _i++) {
+            args[_i] = arguments[_i];
+        }
+        var argsLength = args.length;
+        if (argsLength === length) {
+            return fn.apply(void 0, args);
+        }
+        if (argsLength > length) {
+            return fn.apply(void 0, args.slice(0, length));
+        }
+        return curry(function () {
+            var nextArgs = [];
+            for (var _i = 0; _i < arguments.length; _i++) {
+                nextArgs[_i] = arguments[_i];
+            }
+            return fn.apply(void 0, args.concat(nextArgs));
+        }, length - argsLength);
+    };
+}
+exports.default = curry;

package/cjs/either/either-sync.js

@@ -0,0 +1,21 @@
+"use strict";
+/**
+ * @module Either
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+var left_1 = require("./left");
+var right_1 = require("./right");
+/**
+ * Type constructor for `Either`.
+ * Creates either `Right` of the value provided,
+ * or `Left` of the thrown error.
+ */
+function eitherSync(value) {
+    try {
+        return right_1.default(value());
+    }
+    catch (error) {
+        return left_1.default(error);
+    }
+}
+exports.default = eitherSync;

package/cjs/either/either.js

@@ -0,0 +1,18 @@
+"use strict";
+/**
+ * @module Either
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+var left_1 = require("./left");
+var right_1 = require("./right");
+/**
+ * Type constructor for `Either`.
+ * Creates either `Right` of the value provided,
+ * or `Left` of the error thrown.
+ */
+function either(value) {
+    return value()
+        .then(right_1.default)
+        .catch(left_1.default);
+}
+exports.default = either;

package/cjs/either/index.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.eitherSync = exports.right = exports.left = exports.default = void 0;
+var either_1 = require("./either");
+Object.defineProperty(exports, "default", { enumerable: true, get: function () { return either_1.default; } });
+var left_1 = require("./left");
+Object.defineProperty(exports, "left", { enumerable: true, get: function () { return left_1.default; } });
+var right_1 = require("./right");
+Object.defineProperty(exports, "right", { enumerable: true, get: function () { return right_1.default; } });
+var either_sync_1 = require("./either-sync");
+Object.defineProperty(exports, "eitherSync", { enumerable: true, get: function () { return either_sync_1.default; } });

package/cjs/either/left.js

@@ -0,0 +1,22 @@
+"use strict";
+/**
+ * @module Either
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.lid = void 0;
+/**
+ * Internal unique identifier for `Left`.
+ */
+exports.lid = Symbol.for('@@functional/left');
+/**
+ * Constructor function for `Left`.
+ * Creates the special object with one property, represented as unique symbol
+ * key, holding the provided value.
+ */
+function left(value) {
+    var _a;
+    return _a = {},
+        _a[exports.lid] = value,
+        _a;
+}
+exports.default = left;

package/cjs/either/operators/bifold/bifold.js

@@ -0,0 +1,15 @@
+"use strict";
+/**
+ * @module Either Operators
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+var bifoldl_1 = require("./bifoldl");
+var bifoldr_1 = require("./bifoldr");
+/**
+ * Unwraps either the left or the right value of the provided `monad`.
+ */
+function bifold(monad) {
+    var _a;
+    return (_a = bifoldl_1.default(monad)) !== null && _a !== void 0 ? _a : bifoldr_1.default(monad);
+}
+exports.default = bifold;

package/cjs/either/operators/bifold/bifoldl.js

@@ -0,0 +1,17 @@
+"use strict";
+/**
+ * @module Either Operators
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+var guards_1 = require("../guards");
+var left_1 = require("../../left");
+/**
+ * Returns the left value of the provided `monad`.
+ * If the `monad` is `Right`, returns `undefined`.
+ */
+function bifoldl(monad) {
+    return guards_1.isLeft(monad)
+        ? monad[left_1.lid]
+        : undefined;
+}
+exports.default = bifoldl;

package/cjs/either/operators/bifold/bifoldr.js

@@ -0,0 +1,17 @@
+"use strict";
+/**
+ * @module Either Operators
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+var guards_1 = require("../guards");
+var right_1 = require("../../right");
+/**
+ * Returns the right value of the provided `monad`.
+ * If the `monad` is `Left`, returns `undefined`.
+ */
+function bifoldr(monad) {
+    return guards_1.isRight(monad)
+        ? monad[right_1.rid]
+        : undefined;
+}
+exports.default = bifoldr;

package/cjs/either/operators/bifold/index.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.bifoldr = exports.bifoldl = exports.default = void 0;
+var bifold_1 = require("./bifold");
+Object.defineProperty(exports, "default", { enumerable: true, get: function () { return bifold_1.default; } });
+var bifoldl_1 = require("./bifoldl");
+Object.defineProperty(exports, "bifoldl", { enumerable: true, get: function () { return bifoldl_1.default; } });
+var bifoldr_1 = require("./bifoldr");
+Object.defineProperty(exports, "bifoldr", { enumerable: true, get: function () { return bifoldr_1.default; } });

package/cjs/either/operators/bifold-map.js

@@ -0,0 +1,20 @@
+"use strict";
+/**
+ * @module Either Operators
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+var compose_1 = require("../../compose");
+var ternary_1 = require("../../ternary");
+var permutation_3_1 = require("../../permutation/permutation-3");
+var guards_1 = require("./guards");
+var bifold_1 = require("./bifold");
+function bifoldMap() {
+    var args = [];
+    for (var _i = 0; _i < arguments.length; _i++) {
+        args[_i] = arguments[_i];
+    }
+    return permutation_3_1.default(function (monad, mapLeft, mapRight) {
+        return ternary_1.default(guards_1.isLeft, compose_1.default(mapLeft, bifold_1.bifoldl), compose_1.default(mapRight, bifold_1.bifoldr))(monad);
+    }).apply(void 0, args);
+}
+exports.default = bifoldMap;

package/cjs/either/operators/bimap/bimap.js

@@ -0,0 +1,20 @@
+"use strict";
+/**
+ * @module Either Operators
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+var guards_1 = require("../guards");
+var ternary_1 = require("../../../ternary");
+var permutation_3_1 = require("../../../permutation/permutation-3");
+var first_1 = require("./first");
+var second_1 = require("./second");
+function bimap() {
+    var args = [];
+    for (var _i = 0; _i < arguments.length; _i++) {
+        args[_i] = arguments[_i];
+    }
+    return permutation_3_1.default(function (monad, mapLeft, mapRight) {
+        return ternary_1.default(guards_1.isLeft, first_1.default(mapLeft), second_1.default(mapRight))(monad);
+    }).apply(void 0, args);
+}
+exports.default = bimap;

package/cjs/either/operators/bimap/first.js

@@ -0,0 +1,22 @@
+"use strict";
+/**
+ * @module Either Operators
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+var guards_1 = require("../guards");
+var bifold_1 = require("../bifold");
+var compose_1 = require("../../../compose");
+var left_1 = require("../../left");
+var identity_1 = require("../../../identity");
+var ternary_1 = require("../../../ternary");
+var permutation_2_1 = require("../../../permutation/permutation-2");
+function first() {
+    var args = [];
+    for (var _i = 0; _i < arguments.length; _i++) {
+        args[_i] = arguments[_i];
+    }
+    return permutation_2_1.default(function (monad, mapLeft) {
+        return ternary_1.default(guards_1.isLeft, compose_1.default(left_1.default, mapLeft, bifold_1.bifoldl), identity_1.default)(monad);
+    }).apply(void 0, args);
+}
+exports.default = first;

package/cjs/either/operators/bimap/index.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.second = exports.first = exports.default = void 0;
+var bimap_1 = require("./bimap");
+Object.defineProperty(exports, "default", { enumerable: true, get: function () { return bimap_1.default; } });
+var first_1 = require("./first");
+Object.defineProperty(exports, "first", { enumerable: true, get: function () { return first_1.default; } });
+var second_1 = require("./second");
+Object.defineProperty(exports, "second", { enumerable: true, get: function () { return second_1.default; } });

package/cjs/either/operators/bimap/second.js

@@ -0,0 +1,22 @@
+"use strict";
+/**
+ * @module Either Operators
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+var bifold_1 = require("../bifold");
+var guards_1 = require("../guards");
+var compose_1 = require("../../../compose");
+var identity_1 = require("../../../identity");
+var right_1 = require("../../right");
+var ternary_1 = require("../../../ternary");
+var permutation_2_1 = require("../../../permutation/permutation-2");
+function second() {
+    var args = [];
+    for (var _i = 0; _i < arguments.length; _i++) {
+        args[_i] = arguments[_i];
+    }
+    return permutation_2_1.default(function (monad, mapRight) {
+        return ternary_1.default(guards_1.isRight, compose_1.default(right_1.default, mapRight, bifold_1.bifoldr), identity_1.default)(monad);
+    }).apply(void 0, args);
+}
+exports.default = second;

package/cjs/either/operators/guards.js

@@ -0,0 +1,22 @@
+"use strict";
+/**
+ * @module Either Operators
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isRight = exports.isLeft = void 0;
+var left_1 = require("../left");
+var right_1 = require("../right");
+/**
+ * Type guard function to tell if the provided `monad` is `Left`.
+ */
+function isLeft(monad) {
+    return Object.prototype.hasOwnProperty.call(monad, left_1.lid);
+}
+exports.isLeft = isLeft;
+/**
+ * Type guard function to tell if the provided `monad` is `Right`.
+ */
+function isRight(monad) {
+    return Object.prototype.hasOwnProperty.call(monad, right_1.rid);
+}
+exports.isRight = isRight;

package/cjs/either/operators/index.js

@@ -0,0 +1,24 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    Object.defineProperty(o, k2, { enumerable: true, get: function() { return m[k]; } });
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.second = exports.first = exports.bimap = exports.bifoldMap = exports.bifold = exports.bifoldr = exports.bifoldl = void 0;
+var bifold_1 = require("./bifold");
+Object.defineProperty(exports, "bifoldl", { enumerable: true, get: function () { return bifold_1.bifoldl; } });
+Object.defineProperty(exports, "bifoldr", { enumerable: true, get: function () { return bifold_1.bifoldr; } });
+Object.defineProperty(exports, "bifold", { enumerable: true, get: function () { return bifold_1.default; } });
+__exportStar(require("./guards"), exports);
+var bifold_map_1 = require("./bifold-map");
+Object.defineProperty(exports, "bifoldMap", { enumerable: true, get: function () { return bifold_map_1.default; } });
+var bimap_1 = require("./bimap");
+Object.defineProperty(exports, "bimap", { enumerable: true, get: function () { return bimap_1.default; } });
+Object.defineProperty(exports, "first", { enumerable: true, get: function () { return bimap_1.first; } });
+Object.defineProperty(exports, "second", { enumerable: true, get: function () { return bimap_1.second; } });

package/cjs/either/right.js

@@ -0,0 +1,22 @@
+"use strict";
+/**
+ * @module Either
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rid = void 0;
+/**
+ * Internal unique identifier for `Right`.
+ */
+exports.rid = Symbol.for('@@functional/right');
+/**
+ * Constructor function for `Right`.
+ * Creates the special object with one property, represented as unique symbol
+ * key, holding the provided value.
+ */
+function right(value) {
+    var _a;
+    return _a = {},
+        _a[exports.rid] = value,
+        _a;
+}
+exports.default = right;

package/cjs/guard.js

@@ -0,0 +1,37 @@
+"use strict";
+/**
+ * @module Guard
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * A function which accepts the pairs of guards:
+ * the first one is the `validator`, expected to return a boolean value.
+ *
+ * If the value is `true`, it's `executor` should run with the provided `args`
+ * and return from the `guards` function.
+ * If the value is `false`, the process continues to the next `validator`.
+ *
+ * When no `validator` succeeds, the default executor is run.
+ */
+function guard() {
+    var qualifiers = [];
+    for (var _i = 0; _i < arguments.length; _i++) {
+        qualifiers[_i] = arguments[_i];
+    }
+    return function () {
+        var args = [];
+        for (var _i = 0; _i < arguments.length; _i++) {
+            args[_i] = arguments[_i];
+        }
+        var length = qualifiers.length - 1;
+        var defaultExpression = qualifiers[length];
+        for (var index = 0; index < length; index += 1) {
+            var _a = qualifiers[index], validator = _a[0], expression = _a[1];
+            if (validator.apply(void 0, args)) {
+                return expression.apply(void 0, args);
+            }
+        }
+        return defaultExpression.apply(void 0, args);
+    };
+}
+exports.default = guard;

package/cjs/identity.js

@@ -0,0 +1,12 @@
+"use strict";
+/**
+ * @module Identity
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * A function which returns the provided value.
+ */
+function identity(x) {
+    return x;
+}
+exports.default = identity;

package/cjs/index.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.identity = exports.ternary = exports.rethrow = exports.compose = exports.inject = exports.match = exports.curry = exports.pipe = exports.tap = void 0;
+var tap_1 = require("./tap");
+Object.defineProperty(exports, "tap", { enumerable: true, get: function () { return tap_1.default; } });
+var pipe_1 = require("./pipe");
+Object.defineProperty(exports, "pipe", { enumerable: true, get: function () { return pipe_1.default; } });
+var curry_1 = require("./curry");
+Object.defineProperty(exports, "curry", { enumerable: true, get: function () { return curry_1.default; } });
+var guard_1 = require("./guard");
+Object.defineProperty(exports, "match", { enumerable: true, get: function () { return guard_1.default; } });
+var inject_1 = require("./inject");
+Object.defineProperty(exports, "inject", { enumerable: true, get: function () { return inject_1.default; } });
+var compose_1 = require("./compose");
+Object.defineProperty(exports, "compose", { enumerable: true, get: function () { return compose_1.default; } });
+var rethrow_1 = require("./rethrow");
+Object.defineProperty(exports, "rethrow", { enumerable: true, get: function () { return rethrow_1.default; } });
+var ternary_1 = require("./ternary");
+Object.defineProperty(exports, "ternary", { enumerable: true, get: function () { return ternary_1.default; } });
+var identity_1 = require("./identity");
+Object.defineProperty(exports, "identity", { enumerable: true, get: function () { return identity_1.default; } });

package/cjs/inject.js

@@ -0,0 +1,23 @@
+"use strict";
+/**
+ * @module Side Effects
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+var permutation_2_1 = require("./permutation/permutation-2");
+function inject() {
+    var args = [];
+    for (var _i = 0; _i < arguments.length; _i++) {
+        args[_i] = arguments[_i];
+    }
+    return permutation_2_1.default(function (fn, effect) {
+        return (function () {
+            var args = [];
+            for (var _i = 0; _i < arguments.length; _i++) {
+                args[_i] = arguments[_i];
+            }
+            effect.apply(void 0, args);
+            return fn.apply(void 0, args);
+        });
+    }).apply(void 0, args);
+}
+exports.default = inject;

package/cjs/maybe/index.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.nothing = exports.just = exports.default = void 0;
+var maybe_1 = require("./maybe");
+Object.defineProperty(exports, "default", { enumerable: true, get: function () { return maybe_1.default; } });
+var just_1 = require("./just");
+Object.defineProperty(exports, "just", { enumerable: true, get: function () { return just_1.default; } });
+var nothing_1 = require("./nothing");
+Object.defineProperty(exports, "nothing", { enumerable: true, get: function () { return nothing_1.default; } });

package/cjs/maybe/just.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.jid = void 0;
+/**
+ * @module Maybe
+ */
+/**
+ * Internal unique identifier for `Just`.
+ */
+exports.jid = Symbol.for('@@functional/just');
+/**
+ * Constructor function for `Just`.
+ * Creates the special object with one property, represented as unique symbol
+ * key, holding the provided value.
+ */
+function just(value) {
+    var _a;
+    return _a = {},
+        _a[exports.jid] = value,
+        _a;
+}
+exports.default = just;

package/cjs/maybe/maybe.js

@@ -0,0 +1,17 @@
+"use strict";
+/**
+ * @module Maybe
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+var just_1 = require("./just");
+var nothing_1 = require("./nothing");
+/**
+ * Constructor function for `Maybe`.
+ * Creates either `just` of a provided value, or `nothing`.
+ */
+function maybe(value) {
+    return value === null || value === undefined
+        ? nothing_1.default()
+        : just_1.default(value);
+}
+exports.default = maybe;

package/cjs/maybe/nothing.js

@@ -0,0 +1,22 @@
+"use strict";
+/**
+ * @module Maybe
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.nid = void 0;
+/**
+ * Internal unique identifier for `Nothing`.
+ */
+exports.nid = Symbol.for('@@functional/nothing');
+/**
+ * Constructor function for `Nothing`.
+ * Creates the special object with one property, represented as unique symbol
+ * key, holding the `null` value.
+ */
+function nothing() {
+    var _a;
+    return _a = {},
+        _a[exports.nid] = null,
+        _a;
+}
+exports.default = nothing;

package/cjs/maybe/operators/bind.js

@@ -0,0 +1,21 @@
+"use strict";
+/**
+ * @module Maybe Operators
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+var compose_1 = require("../../compose");
+var ternary_1 = require("../../ternary");
+var identity_1 = require("../../identity");
+var permutation_2_1 = require("../../permutation/permutation-2");
+var fold_1 = require("./fold");
+var guards_1 = require("./guards");
+function bind() {
+    var args = [];
+    for (var _i = 0; _i < arguments.length; _i++) {
+        args[_i] = arguments[_i];
+    }
+    return permutation_2_1.default(function (monad, transition) {
+        return ternary_1.default(guards_1.isJust, compose_1.default(transition, fold_1.default), identity_1.default)(monad);
+    }).apply(void 0, args);
+}
+exports.default = bind;