@nlozgachev/pipekit 0.1.6

package/esm/src/Core/TaskResult.js

@@ -0,0 +1,63 @@
+import { Result } from "./Result.js";
+import { Task } from "./Task.js";
+export var TaskResult;
+(function (TaskResult) {
+    /**
+     * Wraps a value in a successful TaskResult.
+     */
+    TaskResult.of = (value) => Task.of(Result.toOk(value));
+    /**
+     * Creates a failed TaskResult with the given error.
+     */
+    TaskResult.fail = (error) => Task.of(Result.toErr(error));
+    /**
+     * Creates a TaskResult from a function that may throw.
+     * Catches any errors and transforms them using the onError function.
+     *
+     * @example
+     * ```ts
+     * const parseJson = (s: string): TaskResult<string, unknown> =>
+     *   TaskResult.tryCatch(
+     *     async () => JSON.parse(s),
+     *     (e) => `Parse error: ${e}`
+     *   );
+     * ```
+     */
+    TaskResult.tryCatch = (f, onError) => () => f()
+        .then(Result.toOk)
+        .catch((e) => Result.toErr(onError(e)));
+    /**
+     * Transforms the success value inside a TaskResult.
+     */
+    TaskResult.map = (f) => (data) => Task.map(Result.map(f))(data);
+    /**
+     * Transforms the error value inside a TaskResult.
+     */
+    TaskResult.mapError = (f) => (data) => Task.map(Result.mapError(f))(data);
+    /**
+     * Chains TaskResult computations. If the first succeeds, passes the value to f.
+     * If the first fails, propagates the error.
+     */
+    TaskResult.chain = (f) => (data) => Task.chain((result) => Result.isOk(result) ? f(result.value) : Task.of(Result.toErr(result.error)))(data);
+    /**
+     * Extracts the value from a TaskResult by providing handlers for both cases.
+     */
+    TaskResult.fold = (onErr, onOk) => (data) => Task.map(Result.fold(onErr, onOk))(data);
+    /**
+     * Pattern matches on a TaskResult, returning a Task of the result.
+     */
+    TaskResult.match = (cases) => (data) => Task.map(Result.match(cases))(data);
+    /**
+     * Recovers from an error by providing a fallback TaskResult.
+     */
+    TaskResult.recover = (fallback) => (data) => Task.chain((result) => Result.isErr(result) ? fallback(result.error) : Task.of(result))(data);
+    /**
+     * Returns the success value or a default value if the TaskResult is an error.
+     */
+    TaskResult.getOrElse = (defaultValue) => (data) => Task.map(Result.getOrElse(defaultValue))(data);
+    /**
+     * Executes a side effect on the success value without changing the TaskResult.
+     * Useful for logging or debugging.
+     */
+    TaskResult.tap = (f) => (data) => Task.map(Result.tap(f))(data);
+})(TaskResult || (TaskResult = {}));

package/esm/src/Core/Validation.js

@@ -0,0 +1,215 @@
+import { isNonEmptyList } from "../Types/NonEmptyList.js";
+export var Validation;
+(function (Validation) {
+    /**
+     * Wraps a value in a valid Validation.
+     *
+     * @example
+     * ```ts
+     * Validation.of(42); // Valid(42)
+     * ```
+     */
+    Validation.of = (value) => ({
+        kind: "Valid",
+        value,
+    });
+    /**
+     * Creates a valid Validation with the given value.
+     */
+    Validation.toValid = (value) => ({ kind: "Valid", value });
+    /**
+     * Type guard that checks if a Validation is valid.
+     */
+    Validation.isValid = (data) => data.kind === "Valid";
+    /**
+     * Creates an invalid Validation with the given errors.
+     *
+     * @example
+     * ```ts
+     * Validation.toInvalid(["Email is invalid", "Password too short"]);
+     * ```
+     */
+    Validation.toInvalid = (errors) => ({
+        kind: "Invalid",
+        errors,
+    });
+    /**
+     * Type guard that checks if a Validation is invalid.
+     */
+    Validation.isInvalid = (data) => data.kind === "Invalid";
+    /**
+     * Creates an invalid Validation from a single error.
+     *
+     * @example
+     * ```ts
+     * Validation.fail("Invalid input");
+     * ```
+     */
+    Validation.fail = (error) => Validation.toInvalid([error]);
+    /**
+     * Transforms the success value inside a Validation.
+     *
+     * @example
+     * ```ts
+     * pipe(Validation.of(5), Validation.map(n => n * 2)); // Valid(10)
+     * pipe(Validation.fail("oops"), Validation.map(n => n * 2)); // Invalid(["oops"])
+     * ```
+     */
+    Validation.map = (f) => (data) => Validation.isValid(data) ? Validation.of(f(data.value)) : data;
+    /**
+     * Chains Validation computations. If the first is Valid, passes the value to f.
+     * If the first is Invalid, propagates the errors.
+     *
+     * Note: chain short-circuits on first error. Use `ap` to accumulate errors.
+     *
+     * @example
+     * ```ts
+     * const validatePositive = (n: number): Validation<string, number> =>
+     *   n > 0 ? Validation.of(n) : Validation.fail("Must be positive");
+     *
+     * pipe(Validation.of(5), Validation.chain(validatePositive)); // Valid(5)
+     * pipe(Validation.of(-1), Validation.chain(validatePositive)); // Invalid(["Must be positive"])
+     * ```
+     */
+    Validation.chain = (f) => (data) => Validation.isValid(data) ? f(data.value) : data;
+    /**
+     * Applies a function wrapped in a Validation to a value wrapped in a Validation.
+     * Accumulates errors from both sides.
+     *
+     * @example
+     * ```ts
+     * const add = (a: number) => (b: number) => a + b;
+     * pipe(
+     *   Validation.of(add),
+     *   Validation.ap(Validation.of(5)),
+     *   Validation.ap(Validation.of(3))
+     * ); // Valid(8)
+     *
+     * pipe(
+     *   Validation.of(add),
+     *   Validation.ap(Validation.fail<string, number>("bad a")),
+     *   Validation.ap(Validation.fail<string, number>("bad b"))
+     * ); // Invalid(["bad a", "bad b"])
+     * ```
+     */
+    Validation.ap = (arg) => (data) => {
+        if (Validation.isValid(data) && Validation.isValid(arg))
+            return Validation.of(data.value(arg.value));
+        const errors = [
+            ...(Validation.isInvalid(data) ? data.errors : []),
+            ...(Validation.isInvalid(arg) ? arg.errors : []),
+        ];
+        return isNonEmptyList(errors) ? Validation.toInvalid(errors) : Validation.of(data);
+    };
+    /**
+     * Extracts the value from a Validation by providing handlers for both cases.
+     *
+     * @example
+     * ```ts
+     * pipe(
+     *   Validation.of(42),
+     *   Validation.fold(
+     *     errors => `Errors: ${errors.join(", ")}`,
+     *     value => `Value: ${value}`
+     *   )
+     * );
+     * ```
+     */
+    Validation.fold = (onInvalid, onValid) => (data) => Validation.isValid(data) ? onValid(data.value) : onInvalid(data.errors);
+    /**
+     * Pattern matches on a Validation, returning the result of the matching case.
+     *
+     * @example
+     * ```ts
+     * pipe(
+     *   validation,
+     *   Validation.match({
+     *     valid: value => `Got ${value}`,
+     *     invalid: errors => `Failed: ${errors.join(", ")}`
+     *   })
+     * );
+     * ```
+     */
+    Validation.match = (cases) => (data) => Validation.isValid(data) ? cases.valid(data.value) : cases.invalid(data.errors);
+    /**
+     * Returns the success value or a default value if the Validation is invalid.
+     *
+     * @example
+     * ```ts
+     * pipe(Validation.of(5), Validation.getOrElse(0)); // 5
+     * pipe(Validation.fail("oops"), Validation.getOrElse(0)); // 0
+     * ```
+     */
+    Validation.getOrElse = (defaultValue) => (data) => Validation.isValid(data) ? data.value : defaultValue;
+    /**
+     * Executes a side effect on the success value without changing the Validation.
+     *
+     * @example
+     * ```ts
+     * pipe(
+     *   Validation.of(5),
+     *   Validation.tap(n => console.log("Value:", n)),
+     *   Validation.map(n => n * 2)
+     * );
+     * ```
+     */
+    Validation.tap = (f) => (data) => {
+        if (Validation.isValid(data))
+            f(data.value);
+        return data;
+    };
+    /**
+     * Recovers from an Invalid state by providing a fallback Validation.
+     */
+    Validation.recover = (fallback) => (data) => Validation.isValid(data) ? data : fallback();
+    /**
+     * Recovers from an Invalid state unless the errors contain any of the blocked errors.
+     */
+    Validation.recoverUnless = (blockedErrors, fallback) => (data) => Validation.isInvalid(data) &&
+        !data.errors.some((err) => blockedErrors.includes(err))
+        ? fallback()
+        : data;
+    /**
+     * Combines two Validation instances, accumulating errors from both.
+     * If both are Valid, returns the second valid value.
+     * If either is Invalid, combines their errors into a single Invalid.
+     *
+     * @example
+     * ```ts
+     * Validation.combine(
+     *   Validation.fail("Error 1"),
+     *   Validation.fail("Error 2")
+     * ); // Invalid(["Error 1", "Error 2"])
+     *
+     * Validation.combine(
+     *   Validation.of("a"),
+     *   Validation.of("b")
+     * ); // Valid("b")
+     * ```
+     */
+    Validation.combine = (first, second) => {
+        if (Validation.isValid(first) && Validation.isValid(second)) {
+            return second;
+        }
+        const errors = [
+            ...(Validation.isInvalid(first) ? first.errors : []),
+            ...(Validation.isInvalid(second) ? second.errors : []),
+        ];
+        return isNonEmptyList(errors) ? Validation.toInvalid(errors) : second;
+    };
+    /**
+     * Combines multiple Validation instances, accumulating all errors.
+     * If all are Valid, returns the last valid value.
+     * Returns undefined for an empty array.
+     *
+     * @example
+     * ```ts
+     * Validation.combineAll([
+     *   validateName(name),
+     *   validateEmail(email),
+     *   validateAge(age)
+     * ]);
+     * ```
+     */
+    Validation.combineAll = (data) => data.length === 0 ? undefined : data.reduce((acc, v) => Validation.combine(acc, v));
+})(Validation || (Validation = {}));

package/esm/src/Core/index.js

@@ -0,0 +1,8 @@
+export * from "./Arr.js";
+export * from "./Option.js";
+export * from "./Rec.js";
+export * from "./RemoteData.js";
+export * from "./Result.js";
+export * from "./Task.js";
+export * from "./TaskResult.js";
+export * from "./Validation.js";

package/esm/src/Types/NonEmptyList.js

@@ -0,0 +1,14 @@
+/**
+ * Type guard that checks if an array is non-empty.
+ *
+ * @example
+ * ```ts
+ * const items: string[] = getItems();
+ *
+ * if (isNonEmptyList(items)) {
+ *   // TypeScript knows items has at least one element
+ *   const first = items[0]; // string, not string | undefined
+ * }
+ * ```
+ */
+export const isNonEmptyList = (list) => list.length > 0;

package/esm/src/Types/index.js

@@ -0,0 +1 @@
+export * from "./NonEmptyList.js";

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@nlozgachev/pipekit",
+  "version": "0.1.6",
+  "description": "Simple functional programming toolkit for TypeScript",
+  "keywords": [
+    "functional",
+    "fp",
+    "typescript",
+    "composition",
+    "pipe"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nlozgachev/pipekit"
+  },
+  "license": "MIT",
+  "types": "./types/mod.d.ts",
+  "exports": {
+    "./Composition": {
+      "import": {
+        "types": "./types/src/Composition/index.d.ts",
+        "default": "./esm/src/Composition/index.js"
+      },
+      "require": {
+        "types": "./types/src/Composition/index.d.ts",
+        "default": "./script/src/Composition/index.js"
+      }
+    },
+    "./Core": {
+      "import": {
+        "types": "./types/src/Core/index.d.ts",
+        "default": "./esm/src/Core/index.js"
+      },
+      "require": {
+        "types": "./types/src/Core/index.d.ts",
+        "default": "./script/src/Core/index.js"
+      }
+    },
+    "./Types": {
+      "import": {
+        "types": "./types/src/Types/index.d.ts",
+        "default": "./esm/src/Types/index.js"
+      },
+      "require": {
+        "types": "./types/src/Types/index.d.ts",
+        "default": "./script/src/Types/index.js"
+      }
+    }
+  },
+  "scripts": {},
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    "esm",
+    "script",
+    "types"
+  ]
+}

package/script/mod.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (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 });
+__exportStar(require("./src/Composition/index.js"), exports);
+__exportStar(require("./src/Core/index.js"), exports);
+__exportStar(require("./src/Composition/index.js"), exports);

package/script/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

package/script/src/Composition/compose.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.compose = compose;
+function compose(...fns) {
+    return (arg) => fns.reduceRight((acc, fn) => fn(acc), arg);
+}

package/script/src/Composition/curry.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.curry4 = exports.curry3 = exports.curry = void 0;
+/**
+ * Converts a multi-argument function into a curried function.
+ * The inverse of `uncurry`.
+ *
+ * @example
+ * ```ts
+ * const add = (a: number, b: number) => a + b;
+ * const curriedAdd = curry(add);
+ * curriedAdd(1)(2); // 3
+ *
+ * // Partial application
+ * const addTen = curriedAdd(10);
+ * addTen(5); // 15
+ * ```
+ *
+ * @see {@link uncurry} for the inverse operation
+ * @see {@link curry3} for 3-argument functions
+ * @see {@link curry4} for 4-argument functions
+ */
+const curry = (f) => (a) => (b) => f(a, b);
+exports.curry = curry;
+/**
+ * Converts a 3-argument function into a curried function.
+ *
+ * @example
+ * ```ts
+ * const add3 = (a: number, b: number, c: number) => a + b + c;
+ * const curriedAdd3 = curry3(add3);
+ * curriedAdd3(1)(2)(3); // 6
+ * ```
+ */
+const curry3 = (f) => (a) => (b) => (c) => f(a, b, c);
+exports.curry3 = curry3;
+/**
+ * Converts a 4-argument function into a curried function.
+ *
+ * @example
+ * ```ts
+ * const add4 = (a: number, b: number, c: number, d: number) => a + b + c + d;
+ * const curriedAdd4 = curry4(add4);
+ * curriedAdd4(1)(2)(3)(4); // 10
+ * ```
+ */
+const curry4 = (f) => (a) => (b) => (c) => (d) => f(a, b, c, d);
+exports.curry4 = curry4;

package/script/src/Composition/flip.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.flip = void 0;
+/**
+ * Flips the order of arguments for a curried binary function.
+ * Converts a data-last function to data-first.
+ *
+ * @example
+ * ```ts
+ * // Original data-last (for pipe)
+ * pipe(
+ *   Option.of(5),
+ *   Option.map(n => n * 2)
+ * ); // Some(10)
+ *
+ * // Flipped to data-first
+ * const mapFirst = flip(Option.map);
+ * mapFirst(Option.of(5))(n => n * 2); // Some(10)
+ * ```
+ *
+ * @see {@link uncurry} for converting curried functions to multi-argument functions
+ */
+const flip = (f) => (b) => (a) => f(a)(b);
+exports.flip = flip;

package/script/src/Composition/flow.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.flow = flow;
+function flow(...fns) {
+    return (...args) => {
+        if (fns.length === 0)
+            return args[0];
+        const [first, ...rest] = fns;
+        return rest.reduce((acc, fn) => fn(acc), first(...args));
+    };
+}

package/script/src/Composition/fn.js

@@ -0,0 +1,98 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.once = exports.or = exports.and = exports.constVoid = exports.constUndefined = exports.constNull = exports.constFalse = exports.constTrue = exports.constant = exports.identity = void 0;
+/**
+ * Returns the value unchanged. The identity function.
+ *
+ * @example
+ * ```ts
+ * identity(42); // 42
+ * pipe(Option.of(5), Option.fold(() => 0, identity)); // 5
+ * ```
+ */
+const identity = (a) => a;
+exports.identity = identity;
+/**
+ * Creates a function that always returns the given value, ignoring its argument.
+ *
+ * @example
+ * ```ts
+ * const always42 = constant(42);
+ * always42(); // 42
+ * [1, 2, 3].map(constant("x")); // ["x", "x", "x"]
+ * ```
+ */
+const constant = (a) => () => a;
+exports.constant = constant;
+/** Always returns `true`. */
+const constTrue = () => true;
+exports.constTrue = constTrue;
+/** Always returns `false`. */
+const constFalse = () => false;
+exports.constFalse = constFalse;
+/** Always returns `null`. */
+const constNull = () => null;
+exports.constNull = constNull;
+/** Always returns `undefined`. */
+const constUndefined = () => undefined;
+exports.constUndefined = constUndefined;
+/** Always returns `void`. */
+const constVoid = () => { };
+exports.constVoid = constVoid;
+/**
+ * Combines two predicates with logical AND.
+ *
+ * @example
+ * ```ts
+ * const isPositive = (n: number) => n > 0;
+ * const isEven = (n: number) => n % 2 === 0;
+ * const isPositiveEven = and(isPositive, isEven);
+ *
+ * isPositiveEven(4); // true
+ * isPositiveEven(-2); // false
+ * isPositiveEven(3); // false
+ * ```
+ */
+const and = (p1, p2) => (...args) => p1(...args) && p2(...args);
+exports.and = and;
+/**
+ * Combines two predicates with logical OR.
+ *
+ * @example
+ * ```ts
+ * const isNegative = (n: number) => n < 0;
+ * const isZero = (n: number) => n === 0;
+ * const isNonPositive = or(isNegative, isZero);
+ *
+ * isNonPositive(-1); // true
+ * isNonPositive(0); // true
+ * isNonPositive(1); // false
+ * ```
+ */
+const or = (p1, p2) => (...args) => p1(...args) || p2(...args);
+exports.or = or;
+/**
+ * Creates a function that executes at most once.
+ * Subsequent calls return the cached result from the first execution.
+ *
+ * @example
+ * ```ts
+ * let count = 0;
+ * const initOnce = once(() => { count++; return "initialized"; });
+ *
+ * initOnce(); // "initialized", count === 1
+ * initOnce(); // "initialized", count === 1 (not called again)
+ * ```
+ */
+const once = (f) => {
+    let called = false;
+    let result;
+    return () => {
+        if (!called) {
+            result = f();
+            called = true;
+        }
+        return result;
+    };
+};
+exports.once = once;

package/script/src/Composition/index.js

@@ -0,0 +1,26 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (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 });
+__exportStar(require("./compose.js"), exports);
+__exportStar(require("./curry.js"), exports);
+__exportStar(require("./flip.js"), exports);
+__exportStar(require("./fn.js"), exports);
+__exportStar(require("./flow.js"), exports);
+__exportStar(require("./memoize.js"), exports);
+__exportStar(require("./not.js"), exports);
+__exportStar(require("./pipe.js"), exports);
+__exportStar(require("./tap.js"), exports);
+__exportStar(require("./uncurry.js"), exports);

package/script/src/Composition/memoize.js

@@ -0,0 +1,71 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.memoizeWeak = exports.memoize = void 0;
+/**
+ * Creates a memoized version of a function that caches results.
+ * Subsequent calls with the same argument return the cached result.
+ *
+ * By default, uses the argument directly as the cache key.
+ * For complex arguments, provide a custom `keyFn` to generate cache keys.
+ *
+ * @example
+ * ```ts
+ * // Basic usage
+ * const expensive = memoize((n: number) => {
+ *   console.log("Computing...");
+ *   return n * 2;
+ * });
+ *
+ * expensive(5); // logs "Computing...", returns 10
+ * expensive(5); // returns 10 (cached, no log)
+ * expensive(3); // logs "Computing...", returns 6
+ *
+ * // With custom key function for objects
+ * const fetchUser = memoize(
+ *   (opts: { id: string }) => fetch(`/users/${opts.id}`),
+ *   opts => opts.id
+ * );
+ * ```
+ */
+const memoize = (f, keyFn = (a) => a) => {
+    const cache = new Map();
+    return (a) => {
+        const key = keyFn(a);
+        if (cache.has(key)) {
+            return cache.get(key);
+        }
+        const result = f(a);
+        cache.set(key, result);
+        return result;
+    };
+};
+exports.memoize = memoize;
+/**
+ * Creates a memoized version of a function using WeakMap.
+ * Only works with object arguments, but allows garbage collection
+ * of cached values when keys are no longer referenced.
+ *
+ * @example
+ * ```ts
+ * const processUser = memoizeWeak((user: User) => {
+ *   return expensiveOperation(user);
+ * });
+ *
+ * const user = { id: 1, name: "Alice" };
+ * processUser(user); // computed
+ * processUser(user); // cached
+ * // When `user` is garbage collected, cached result is too
+ * ```
+ */
+const memoizeWeak = (f) => {
+    const cache = new WeakMap();
+    return (a) => {
+        if (cache.has(a)) {
+            return cache.get(a);
+        }
+        const result = f(a);
+        cache.set(a, result);
+        return result;
+    };
+};
+exports.memoizeWeak = memoizeWeak;