@nlozgachev/pipelined 0.6.4

package/esm/src/Types/Brand.js

@@ -0,0 +1,28 @@
+export var Brand;
+(function (Brand) {
+    /**
+     * Returns a constructor that wraps a value of type T in brand K.
+     * The resulting function performs an unchecked cast — only use when the raw
+     * value is known to satisfy the brand's invariants.
+     *
+     * @example
+     * ```ts
+     * type PositiveNumber = Brand<"PositiveNumber", number>;
+     * const toPositiveNumber = Brand.wrap<"PositiveNumber", number>();
+     *
+     * const n: PositiveNumber = toPositiveNumber(42);
+     * ```
+     */
+    Brand.wrap = () => (value) => value;
+    /**
+     * Strips the brand and returns the underlying value.
+     * Since Brand<K, T> extends T this is rarely needed, but can improve readability.
+     *
+     * @example
+     * ```ts
+     * const userId: UserId = toUserId("user-123");
+     * const raw: string = Brand.unwrap(userId); // "user-123"
+     * ```
+     */
+    Brand.unwrap = (branded) => branded;
+})(Brand || (Brand = {}));

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,2 @@
+export * from "./Brand.js";
+export * from "./NonEmptyList.js";

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@nlozgachev/pipelined",
+  "version": "0.6.4",
+  "description": "Simple functional programming toolkit for TypeScript",
+  "keywords": [
+    "functional",
+    "fp",
+    "typescript",
+    "composition",
+    "pipe"
+  ],
+  "homepage": "https://pipelined.lozgachev.dev",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nlozgachev/pipelined"
+  },
+  "license": "BSD-3-Clause",
+  "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/converge.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.converge = converge;
+function converge(f, transformers) {
+    return (a) => f(...transformers.map((t) => t(a)));
+}

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.some(5),
+ *   Option.map(n => n * 2)
+ * ); // Some(10)
+ *
+ * // Flipped to data-first
+ * const mapFirst = flip(Option.map);
+ * mapFirst(Option.some(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.some(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,29 @@
+"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("./converge.js"), exports);
+__exportStar(require("./curry.js"), exports);
+__exportStar(require("./flip.js"), exports);
+__exportStar(require("./fn.js"), exports);
+__exportStar(require("./flow.js"), exports);
+__exportStar(require("./juxt.js"), exports);
+__exportStar(require("./memoize.js"), exports);
+__exportStar(require("./not.js"), exports);
+__exportStar(require("./on.js"), exports);
+__exportStar(require("./pipe.js"), exports);
+__exportStar(require("./tap.js"), exports);
+__exportStar(require("./uncurry.js"), exports);

package/script/src/Composition/juxt.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.juxt = juxt;
+function juxt(fns) {
+    return (a) => fns.map((f) => f(a));
+}

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;

package/script/src/Composition/not.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.not = void 0;
+/**
+ * Negates a predicate function.
+ * Returns a new predicate that returns true when the original returns false, and vice versa.
+ *
+ * @example
+ * ```ts
+ * const isEven = (n: number) => n % 2 === 0;
+ * const isOdd = not(isEven);
+ *
+ * isOdd(3); // true
+ * isOdd(4); // false
+ *
+ * // With array methods
+ * const numbers = [1, 2, 3, 4, 5];
+ * numbers.filter(not(isEven)); // [1, 3, 5]
+ *
+ * // In pipelines
+ * pipe(
+ *   users,
+ *   Array.filter(not(isAdmin)),
+ *   Array.map(u => u.name)
+ * );
+ * ```
+ */
+const not = (predicate) => (...args) => !predicate(...args);
+exports.not = not;

package/script/src/Composition/on.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.on = void 0;
+/**
+ * Applies a projection to both arguments of a binary function before calling it.
+ * Most useful for building comparators and equality checks over projected values.
+ *
+ * @example
+ * ```ts
+ * const byLength = on((a: number, b: number) => a - b, (s: string) => s.length);
+ *
+ * ["banana", "fig", "apple"].sort(byLength); // ["fig", "apple", "banana"]
+ * ```
+ */
+const on = (f, g) => (a, b) => f(g(a), g(b));
+exports.on = on;

package/script/src/Composition/pipe.js

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

package/script/src/Composition/tap.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tap = void 0;
+/**
+ * Executes a side effect function and returns the original value unchanged.
+ * Useful for logging, debugging, or other side effects within a pipeline.
+ *
+ * @example
+ * ```ts
+ * // Debugging a pipeline
+ * pipe(
+ *   Option.some(5),
+ *   tap(x => console.log("Before map:", x)),
+ *   Option.map(n => n * 2),
+ *   tap(x => console.log("After map:", x)),
+ *   Option.getOrElse(0)
+ * );
+ * // logs: "Before map: { kind: 'Some', value: 5 }"
+ * // logs: "After map: { kind: 'Some', value: 10 }"
+ * // returns: 10
+ *
+ * // Collecting intermediate values
+ * const values: number[] = [];
+ * pipe(
+ *   [1, 2, 3],
+ *   arr => arr.map(n => n * 2),
+ *   tap(arr => values.push(...arr))
+ * );
+ * ```
+ *
+ * @see {@link Option.tap} for Option-specific tap that only runs on Some
+ */
+const tap = (f) => (a) => {
+    f(a);
+    return a;
+};
+exports.tap = tap;

package/script/src/Composition/uncurry.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.uncurry4 = exports.uncurry3 = void 0;
+exports.uncurry = uncurry;
+// deno-lint-ignore no-explicit-any
+function uncurry(f) {
+    // f.length determines the outer arity; inner.length determines the inner arity.
+    // The typed overloads guarantee these are 0, 1, or 2 total args.
+    // deno-lint-ignore no-explicit-any
+    return (...args) => {
+        const inner = f(...args.slice(0, f.length));
+        return inner.length === 0 ? inner() : inner(...args.slice(f.length));
+    };
+}
+/**
+ * Converts a curried 3-argument function into a multi-argument function.
+ *
+ * @example
+ * ```ts
+ * const curriedAdd3 = (a: number) => (b: number) => (c: number) => a + b + c;
+ * const add3 = uncurry3(curriedAdd3);
+ * add3(1, 2, 3); // 6
+ * ```
+ */
+const uncurry3 = (f) => (a, b, c) => f(a)(b)(c);
+exports.uncurry3 = uncurry3;
+/**
+ * Converts a curried 4-argument function into a multi-argument function.
+ *
+ * @example
+ * ```ts
+ * const curriedAdd4 = (a: number) => (b: number) => (c: number) => (d: number) => a + b + c + d;
+ * const add4 = uncurry4(curriedAdd4);
+ * add4(1, 2, 3, 4); // 10
+ * ```
+ */
+const uncurry4 = (f) => (a, b, c, d) => f(a)(b)(c)(d);
+exports.uncurry4 = uncurry4;