@nlozgachev/pipelined 0.12.0 → 0.13.0

package/dist/composition.d.ts

@@ -0,0 +1,495 @@
+/**
+ * Composes functions from right to left, returning a new function.
+ * This is the traditional mathematical function composition: (f . g)(x) = f(g(x))
+ *
+ * Unlike `flow` which reads left-to-right, `compose` reads right-to-left,
+ * matching how nested function calls would be written.
+ *
+ * @example
+ * ```ts
+ * const addOne = (n: number) => n + 1;
+ * const double = (n: number) => n * 2;
+ *
+ * // compose: right-to-left (double first, then addOne)
+ * const composed = compose(addOne, double);
+ * composed(5); // 11 (5 * 2 + 1)
+ *
+ * // flow: left-to-right (addOne first, then double)
+ * const flowed = flow(addOne, double);
+ * flowed(5); // 12 ((5 + 1) * 2)
+ * ```
+ *
+ * @see {@link flow} for left-to-right composition
+ */
+declare function compose<A, B>(ab: (a: A) => B): (a: A) => B;
+declare function compose<A, B, C>(bc: (b: B) => C, ab: (a: A) => B): (a: A) => C;
+declare function compose<A, B, C, D>(cd: (c: C) => D, bc: (b: B) => C, ab: (a: A) => B): (a: A) => D;
+declare function compose<A, B, C, D, E>(de: (d: D) => E, cd: (c: C) => D, bc: (b: B) => C, ab: (a: A) => B): (a: A) => E;
+declare function compose<A, B, C, D, E, F>(ef: (e: E) => F, de: (d: D) => E, cd: (c: C) => D, bc: (b: B) => C, ab: (a: A) => B): (a: A) => F;
+declare function compose<A, B, C, D, E, F, G>(fg: (f: F) => G, ef: (e: E) => F, de: (d: D) => E, cd: (c: C) => D, bc: (b: B) => C, ab: (a: A) => B): (a: A) => G;
+declare function compose<A, B, C, D, E, F, G, H>(gh: (g: G) => H, fg: (f: F) => G, ef: (e: E) => F, de: (d: D) => E, cd: (c: C) => D, bc: (b: B) => C, ab: (a: A) => B): (a: A) => H;
+declare function compose<A, B, C, D, E, F, G, H, I>(hi: (h: H) => I, gh: (g: G) => H, fg: (f: F) => G, ef: (e: E) => F, de: (d: D) => E, cd: (c: C) => D, bc: (b: B) => C, ab: (a: A) => B): (a: A) => I;
+declare function compose<A, B, C, D, E, F, G, H, I, J>(ij: (i: I) => J, hi: (h: H) => I, gh: (g: G) => H, fg: (f: F) => G, ef: (e: E) => F, de: (d: D) => E, cd: (c: C) => D, bc: (b: B) => C, ab: (a: A) => B): (a: A) => J;
+
+/**
+ * Applies an input to several transformer functions independently, then passes all results to a
+ * combining function.
+ *
+ * @example
+ * ```ts
+ * const toNameRecord = converge(
+ *   (trimmed: string, initials: string) => ({ trimmed, initials }),
+ *   [
+ *     (name: string) => name.trim(),
+ *     (name: string) => name.split(" ").map((w) => w[0]).join(""),
+ *   ],
+ * );
+ *
+ * toNameRecord("  Alice Bob  "); // { trimmed: "Alice Bob", initials: "AB" }
+ * ```
+ */
+declare function converge<A, B, C, R>(f: (b: B, c: C) => R, transformers: [(a: A) => B, (a: A) => C]): (a: A) => R;
+declare function converge<A, B, C, D, R>(f: (b: B, c: C, d: D) => R, transformers: [(a: A) => B, (a: A) => C, (a: A) => D]): (a: A) => R;
+declare function converge<A, B, C, D, E, R>(f: (b: B, c: C, d: D, e: E) => R, transformers: [(a: A) => B, (a: A) => C, (a: A) => D, (a: A) => E]): (a: A) => R;
+
+/**
+ * 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
+ */
+declare const curry: <A, B, C>(f: (a: A, b: B) => C) => (a: A) => (b: B) => C;
+/**
+ * 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
+ * ```
+ */
+declare const curry3: <A, B, C, D>(f: (a: A, b: B, c: C) => D) => (a: A) => (b: B) => (c: C) => D;
+/**
+ * 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
+ * ```
+ */
+declare const curry4: <A, B, C, D, E>(f: (a: A, b: B, c: C, d: D) => E) => (a: A) => (b: B) => (c: C) => (d: D) => E;
+
+/**
+ * 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
+ */
+declare const flip: <A, B, C>(f: (a: A) => (b: B) => C) => (b: B) => (a: A) => C;
+
+/**
+ * Composes functions from left to right, returning a new function.
+ * Unlike `pipe`, `flow` doesn't take an initial value - it creates
+ * a reusable pipeline that can be called later with arguments.
+ *
+ * Use `flow` when you want to create a named, reusable transformation.
+ * Use `pipe` when you want to immediately transform a value.
+ *
+ * @example
+ * ```ts
+ * // Create a reusable transformation
+ * const processUser = flow(
+ *   (user: User) => user.name,
+ *   name => name.toUpperCase(),
+ *   name => `Hello, ${name}!`
+ * );
+ *
+ * processUser({ name: "Alice" }); // "Hello, ALICE!"
+ * processUser({ name: "Bob" }); // "Hello, BOB!"
+ *
+ * // Compare with pipe (one-time use):
+ * pipe(
+ *   user,
+ *   u => u.name,
+ *   name => name.toUpperCase()
+ * );
+ *
+ * // flow creates a function, pipe applies immediately:
+ * const double = flow((n: number) => n * 2);
+ * double(5); // 10
+ *
+ * pipe(5, n => n * 2); // 10 (immediate result)
+ * ```
+ *
+ * @see {@link pipe} for immediate value transformation
+ */
+declare function flow<A extends ReadonlyArray<unknown>, B>(ab: (...a: A) => B): (...a: A) => B;
+declare function flow<A extends ReadonlyArray<unknown>, B, C>(ab: (...a: A) => B, bc: (b: B) => C): (...a: A) => C;
+declare function flow<A extends ReadonlyArray<unknown>, B, C, D>(ab: (...a: A) => B, bc: (b: B) => C, cd: (c: C) => D): (...a: A) => D;
+declare function flow<A extends ReadonlyArray<unknown>, B, C, D, E>(ab: (...a: A) => B, bc: (b: B) => C, cd: (c: C) => D, de: (d: D) => E): (...a: A) => E;
+declare function flow<A extends ReadonlyArray<unknown>, B, C, D, E, F>(ab: (...a: A) => B, bc: (b: B) => C, cd: (c: C) => D, de: (d: D) => E, ef: (e: E) => F): (...a: A) => F;
+declare function flow<A extends ReadonlyArray<unknown>, B, C, D, E, F, G>(ab: (...a: A) => B, bc: (b: B) => C, cd: (c: C) => D, de: (d: D) => E, ef: (e: E) => F, fg: (f: F) => G): (...a: A) => G;
+declare function flow<A extends ReadonlyArray<unknown>, B, C, D, E, F, G, H>(ab: (...a: A) => B, bc: (b: B) => C, cd: (c: C) => D, de: (d: D) => E, ef: (e: E) => F, fg: (f: F) => G, gh: (g: G) => H): (...a: A) => H;
+declare function flow<A extends ReadonlyArray<unknown>, B, C, D, E, F, G, H, I>(ab: (...a: A) => B, bc: (b: B) => C, cd: (c: C) => D, de: (d: D) => E, ef: (e: E) => F, fg: (f: F) => G, gh: (g: G) => H, hi: (h: H) => I): (...a: A) => I;
+declare function flow<A extends ReadonlyArray<unknown>, B, C, D, E, F, G, H, I, J>(ab: (...a: A) => B, bc: (b: B) => C, cd: (c: C) => D, de: (d: D) => E, ef: (e: E) => F, fg: (f: F) => G, gh: (g: G) => H, hi: (h: H) => I, ij: (i: I) => J): (...a: A) => J;
+declare function flow<A extends ReadonlyArray<unknown>, B, C, D, E, F, G, H, I, J, K>(ab: (...a: A) => B, bc: (b: B) => C, cd: (c: C) => D, de: (d: D) => E, ef: (e: E) => F, fg: (f: F) => G, gh: (g: G) => H, hi: (h: H) => I, ij: (i: I) => J, jk: (j: J) => K): (...a: A) => K;
+declare function flow<A extends ReadonlyArray<unknown>, B, C, D, E, F, G, H, I, J, K, L>(ab: (...a: A) => B, bc: (b: B) => C, cd: (c: C) => D, de: (d: D) => E, ef: (e: E) => F, fg: (f: F) => G, gh: (g: G) => H, hi: (h: H) => I, ij: (i: I) => J, jk: (j: J) => K, kl: (k: K) => L): (...a: A) => L;
+declare function flow<A extends ReadonlyArray<unknown>, B, C, D, E, F, G, H, I, J, K, L, M>(ab: (...a: A) => B, bc: (b: B) => C, cd: (c: C) => D, de: (d: D) => E, ef: (e: E) => F, fg: (f: F) => G, gh: (g: G) => H, hi: (h: H) => I, ij: (i: I) => J, jk: (j: J) => K, kl: (k: K) => L, lm: (l: L) => M): (...a: A) => M;
+declare function flow<A extends ReadonlyArray<unknown>, B, C, D, E, F, G, H, I, J, K, L, M, N>(ab: (...a: A) => B, bc: (b: B) => C, cd: (c: C) => D, de: (d: D) => E, ef: (e: E) => F, fg: (f: F) => G, gh: (g: G) => H, hi: (h: H) => I, ij: (i: I) => J, jk: (j: J) => K, kl: (k: K) => L, lm: (l: L) => M, mn: (m: M) => N): (...a: A) => N;
+declare function flow<A extends ReadonlyArray<unknown>, B, C, D, E, F, G, H, I, J, K, L, M, N, O>(ab: (...a: A) => B, bc: (b: B) => C, cd: (c: C) => D, de: (d: D) => E, ef: (e: E) => F, fg: (f: F) => G, gh: (g: G) => H, hi: (h: H) => I, ij: (i: I) => J, jk: (j: J) => K, kl: (k: K) => L, lm: (l: L) => M, mn: (m: M) => N, no: (n: N) => O): (...a: A) => O;
+declare function flow<A extends ReadonlyArray<unknown>, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P>(ab: (...a: A) => B, bc: (b: B) => C, cd: (c: C) => D, de: (d: D) => E, ef: (e: E) => F, fg: (f: F) => G, gh: (g: G) => H, hi: (h: H) => I, ij: (i: I) => J, jk: (j: J) => K, kl: (k: K) => L, lm: (l: L) => M, mn: (m: M) => N, no: (n: N) => O, op: (o: O) => P): (...a: A) => P;
+declare function flow<A extends ReadonlyArray<unknown>, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q>(ab: (...a: A) => B, bc: (b: B) => C, cd: (c: C) => D, de: (d: D) => E, ef: (e: E) => F, fg: (f: F) => G, gh: (g: G) => H, hi: (h: H) => I, ij: (i: I) => J, jk: (j: J) => K, kl: (k: K) => L, lm: (l: L) => M, mn: (m: M) => N, no: (n: N) => O, op: (o: O) => P, pq: (p: P) => Q): (...a: A) => Q;
+declare function flow<A extends ReadonlyArray<unknown>, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R>(ab: (...a: A) => B, bc: (b: B) => C, cd: (c: C) => D, de: (d: D) => E, ef: (e: E) => F, fg: (f: F) => G, gh: (g: G) => H, hi: (h: H) => I, ij: (i: I) => J, jk: (j: J) => K, kl: (k: K) => L, lm: (l: L) => M, mn: (m: M) => N, no: (n: N) => O, op: (o: O) => P, pq: (p: P) => Q, qr: (q: Q) => R): (...a: A) => R;
+declare function flow<A extends ReadonlyArray<unknown>, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S>(ab: (...a: A) => B, bc: (b: B) => C, cd: (c: C) => D, de: (d: D) => E, ef: (e: E) => F, fg: (f: F) => G, gh: (g: G) => H, hi: (h: H) => I, ij: (i: I) => J, jk: (j: J) => K, kl: (k: K) => L, lm: (l: L) => M, mn: (m: M) => N, no: (n: N) => O, op: (o: O) => P, pq: (p: P) => Q, qr: (q: Q) => R, rs: (r: R) => S): (...a: A) => S;
+declare function flow<A extends ReadonlyArray<unknown>, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T>(ab: (...a: A) => B, bc: (b: B) => C, cd: (c: C) => D, de: (d: D) => E, ef: (e: E) => F, fg: (f: F) => G, gh: (g: G) => H, hi: (h: H) => I, ij: (i: I) => J, jk: (j: J) => K, kl: (k: K) => L, lm: (l: L) => M, mn: (m: M) => N, no: (n: N) => O, op: (o: O) => P, pq: (p: P) => Q, qr: (q: Q) => R, rs: (r: R) => S, st: (s: S) => T): (...a: A) => T;
+
+/**
+ * Returns the value unchanged. The identity function.
+ *
+ * @example
+ * ```ts
+ * identity(42); // 42
+ * pipe(Option.some(5), Option.fold(() => 0, identity)); // 5
+ * ```
+ */
+declare const identity: <A>(a: A) => A;
+/**
+ * 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"]
+ * ```
+ */
+declare const constant: <A>(a: A) => () => A;
+/** Always returns `true`. */
+declare const constTrue: () => true;
+/** Always returns `false`. */
+declare const constFalse: () => false;
+/** Always returns `null`. */
+declare const constNull: () => null;
+/** Always returns `undefined`. */
+declare const constUndefined: () => undefined;
+/** Always returns `void`. */
+declare const constVoid: () => void;
+/**
+ * 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
+ * ```
+ */
+declare const and: <A extends ReadonlyArray<unknown>>(p1: (...args: A) => boolean, p2: (...args: A) => boolean) => (...args: A) => boolean;
+/**
+ * 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
+ * ```
+ */
+declare const or: <A extends ReadonlyArray<unknown>>(p1: (...args: A) => boolean, p2: (...args: A) => boolean) => (...args: A) => boolean;
+/**
+ * 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)
+ * ```
+ */
+declare const once: <A>(f: () => A) => () => A;
+
+/**
+ * Applies an input to an array of functions and collects the results into a tuple.
+ *
+ * @example
+ * ```ts
+ * const nameParts = juxt([
+ *   (name: string) => name.split(" ")[0],
+ *   (name: string) => name.split(" ").slice(1).join(" "),
+ * ]);
+ *
+ * nameParts("Alice Smith"); // ["Alice", "Smith"]
+ * ```
+ */
+declare function juxt<A, B, C>(fns: [(a: A) => B, (a: A) => C]): (a: A) => [B, C];
+declare function juxt<A, B, C, D>(fns: [(a: A) => B, (a: A) => C, (a: A) => D]): (a: A) => [B, C, D];
+declare function juxt<A, B, C, D, E>(fns: [(a: A) => B, (a: A) => C, (a: A) => D, (a: A) => E]): (a: A) => [B, C, D, E];
+declare function juxt<A, B>(fns: ReadonlyArray<(a: A) => B>): (a: A) => B[];
+
+/**
+ * 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
+ * );
+ * ```
+ */
+declare const memoize: <A, B>(f: (a: A) => B, keyFn?: (a: A) => unknown) => (a: A) => B;
+/**
+ * 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
+ * ```
+ */
+declare const memoizeWeak: <A extends object, B>(f: (a: A) => B) => (a: A) => B;
+
+/**
+ * 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)
+ * );
+ * ```
+ */
+declare const not: <A extends ReadonlyArray<unknown>>(predicate: (...args: A) => boolean) => (...args: A) => boolean;
+
+/**
+ * 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"]
+ * ```
+ */
+declare const on: <A, B, C>(f: (b1: B, b2: B) => C, g: (a: A) => B) => (a: A, b: A) => C;
+
+/**
+ * Pipes a value through a series of functions from left to right.
+ * Each function receives the output of the previous function.
+ *
+ * `pipe` is the primary way to compose operations in this library.
+ * It makes code read top-to-bottom, left-to-right, which is more
+ * intuitive for developers coming from imperative backgrounds.
+ *
+ * @example
+ * ```ts
+ * // Basic usage
+ * const result = pipe(
+ *   5,
+ *   n => n * 2,
+ *   n => n + 1
+ * ); // 11
+ *
+ * // With library functions
+ * const greeting = pipe(
+ *   Option.some("Alice"),
+ *   Option.map(name => name.toUpperCase()),
+ *   Option.map(name => `Hello, ${name}!`),
+ *   Option.getOrElse("Hello!")
+ * ); // "Hello, ALICE!"
+ *
+ * // Error handling with Result
+ * const result = pipe(
+ *   Result.tryCatch(() => JSON.parse(input), e => "Invalid JSON"),
+ *   Result.map(data => data.value),
+ *   Result.getOrElse(null)
+ * );
+ * ```
+ *
+ * @see {@link flow} for creating reusable pipelines without an initial value
+ */
+declare function pipe<A>(a: A): A;
+declare function pipe<A, B>(a: A, ab: (a: A) => B): B;
+declare function pipe<A, B, C>(a: A, ab: (a: A) => B, bc: (b: B) => C): C;
+declare function pipe<A, B, C, D>(a: A, ab: (a: A) => B, bc: (b: B) => C, cd: (c: C) => D): D;
+declare function pipe<A, B, C, D, E>(a: A, ab: (a: A) => B, bc: (b: B) => C, cd: (c: C) => D, de: (d: D) => E): E;
+declare function pipe<A, B, C, D, E, F>(a: A, ab: (a: A) => B, bc: (b: B) => C, cd: (c: C) => D, de: (d: D) => E, ef: (e: E) => F): F;
+declare function pipe<A, B, C, D, E, F, G>(a: A, ab: (a: A) => B, bc: (b: B) => C, cd: (c: C) => D, de: (d: D) => E, ef: (e: E) => F, fg: (f: F) => G): G;
+declare function pipe<A, B, C, D, E, F, G, H>(a: A, ab: (a: A) => B, bc: (b: B) => C, cd: (c: C) => D, de: (d: D) => E, ef: (e: E) => F, fg: (f: F) => G, gh: (g: G) => H): H;
+declare function pipe<A, B, C, D, E, F, G, H, I>(a: A, ab: (a: A) => B, bc: (b: B) => C, cd: (c: C) => D, de: (d: D) => E, ef: (e: E) => F, fg: (f: F) => G, gh: (g: G) => H, hi: (h: H) => I): I;
+declare function pipe<A, B, C, D, E, F, G, H, I, J>(a: A, ab: (a: A) => B, bc: (b: B) => C, cd: (c: C) => D, de: (d: D) => E, ef: (e: E) => F, fg: (f: F) => G, gh: (g: G) => H, hi: (h: H) => I, ij: (i: I) => J): J;
+declare function pipe<A, B, C, D, E, F, G, H, I, J, K>(a: A, ab: (a: A) => B, bc: (b: B) => C, cd: (c: C) => D, de: (d: D) => E, ef: (e: E) => F, fg: (f: F) => G, gh: (g: G) => H, hi: (h: H) => I, ij: (i: I) => J, jk: (j: J) => K): K;
+declare function pipe<A, B, C, D, E, F, G, H, I, J, K, L>(a: A, ab: (a: A) => B, bc: (b: B) => C, cd: (c: C) => D, de: (d: D) => E, ef: (e: E) => F, fg: (f: F) => G, gh: (g: G) => H, hi: (h: H) => I, ij: (i: I) => J, jk: (j: J) => K, kl: (k: K) => L): L;
+declare function pipe<A, B, C, D, E, F, G, H, I, J, K, L, M>(a: A, ab: (a: A) => B, bc: (b: B) => C, cd: (c: C) => D, de: (d: D) => E, ef: (e: E) => F, fg: (f: F) => G, gh: (g: G) => H, hi: (h: H) => I, ij: (i: I) => J, jk: (j: J) => K, kl: (k: K) => L, lm: (l: L) => M): M;
+declare function pipe<A, B, C, D, E, F, G, H, I, J, K, L, M, N>(a: A, ab: (a: A) => B, bc: (b: B) => C, cd: (c: C) => D, de: (d: D) => E, ef: (e: E) => F, fg: (f: F) => G, gh: (g: G) => H, hi: (h: H) => I, ij: (i: I) => J, jk: (j: J) => K, kl: (k: K) => L, lm: (l: L) => M, mn: (m: M) => N): N;
+declare function pipe<A, B, C, D, E, F, G, H, I, J, K, L, M, N, O>(a: A, ab: (a: A) => B, bc: (b: B) => C, cd: (c: C) => D, de: (d: D) => E, ef: (e: E) => F, fg: (f: F) => G, gh: (g: G) => H, hi: (h: H) => I, ij: (i: I) => J, jk: (j: J) => K, kl: (k: K) => L, lm: (l: L) => M, mn: (m: M) => N, no: (n: N) => O): O;
+declare function pipe<A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P>(a: A, ab: (a: A) => B, bc: (b: B) => C, cd: (c: C) => D, de: (d: D) => E, ef: (e: E) => F, fg: (f: F) => G, gh: (g: G) => H, hi: (h: H) => I, ij: (i: I) => J, jk: (j: J) => K, kl: (k: K) => L, lm: (l: L) => M, mn: (m: M) => N, no: (n: N) => O, op: (o: O) => P): P;
+declare function pipe<A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q>(a: A, ab: (a: A) => B, bc: (b: B) => C, cd: (c: C) => D, de: (d: D) => E, ef: (e: E) => F, fg: (f: F) => G, gh: (g: G) => H, hi: (h: H) => I, ij: (i: I) => J, jk: (j: J) => K, kl: (k: K) => L, lm: (l: L) => M, mn: (m: M) => N, no: (n: N) => O, op: (o: O) => P, pq: (p: P) => Q): Q;
+declare function pipe<A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R>(a: A, ab: (a: A) => B, bc: (b: B) => C, cd: (c: C) => D, de: (d: D) => E, ef: (e: E) => F, fg: (f: F) => G, gh: (g: G) => H, hi: (h: H) => I, ij: (i: I) => J, jk: (j: J) => K, kl: (k: K) => L, lm: (l: L) => M, mn: (m: M) => N, no: (n: N) => O, op: (o: O) => P, pq: (p: P) => Q, qr: (q: Q) => R): R;
+declare function pipe<A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S>(a: A, ab: (a: A) => B, bc: (b: B) => C, cd: (c: C) => D, de: (d: D) => E, ef: (e: E) => F, fg: (f: F) => G, gh: (g: G) => H, hi: (h: H) => I, ij: (i: I) => J, jk: (j: J) => K, kl: (k: K) => L, lm: (l: L) => M, mn: (m: M) => N, no: (n: N) => O, op: (o: O) => P, pq: (p: P) => Q, qr: (q: Q) => R, rs: (r: R) => S): S;
+declare function pipe<A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T>(a: A, ab: (a: A) => B, bc: (b: B) => C, cd: (c: C) => D, de: (d: D) => E, ef: (e: E) => F, fg: (f: F) => G, gh: (g: G) => H, hi: (h: H) => I, ij: (i: I) => J, jk: (j: J) => K, kl: (k: K) => L, lm: (l: L) => M, mn: (m: M) => N, no: (n: N) => O, op: (o: O) => P, pq: (p: P) => Q, qr: (q: Q) => R, rs: (r: R) => S, st: (s: S) => T): T;
+
+/**
+ * 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
+ */
+declare const tap: <A>(f: (a: A) => void) => (a: A) => A;
+
+/**
+ * Converts a curried function into a multi-argument function.
+ * Useful when you want to call a curried function with all arguments at once.
+ *
+ * Handles functions with 0, 1, or 2 curried arguments.
+ *
+ * @example
+ * ```ts
+ * // Thunks: () => () => C becomes () => C
+ * const nested = () => () => 42;
+ * uncurry(nested)(); // 42
+ *
+ * // Original curried function
+ * Option.map(n => n * 2)(Option.some(5)); // Some(10)
+ *
+ * // Uncurried - all arguments at once
+ * const mapUncurried = uncurry(Option.map);
+ * mapUncurried(n => n * 2, Option.some(5)); // Some(10)
+ *
+ * // Combined with flip for data-first uncurried
+ * const mapDataFirst = uncurry(flip(Option.map));
+ * mapDataFirst(Option.some(5), n => n * 2); // Some(10)
+ * ```
+ *
+ * @see {@link flip} for reversing curried argument order
+ * @see {@link uncurry3} for 3-argument curried functions
+ * @see {@link uncurry4} for 4-argument curried functions
+ */
+declare function uncurry<C>(f: () => () => C): () => C;
+declare function uncurry<A, C>(f: (a: A) => () => C): (a: A) => C;
+declare function uncurry<A, B, C>(f: (a: A) => (b: B) => C): (a: A, b: B) => C;
+/**
+ * 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
+ * ```
+ */
+declare const uncurry3: <A, B, C, D>(f: (a: A) => (b: B) => (c: C) => D) => (a: A, b: B, c: C) => D;
+/**
+ * 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
+ * ```
+ */
+declare const uncurry4: <A, B, C, D, E>(f: (a: A) => (b: B) => (c: C) => (d: D) => E) => (a: A, b: B, c: C, d: D) => E;
+
+export { and, compose, constFalse, constNull, constTrue, constUndefined, constVoid, constant, converge, curry, curry3, curry4, flip, flow, identity, juxt, memoize, memoizeWeak, not, on, once, or, pipe, tap, uncurry, uncurry3, uncurry4 };

package/dist/composition.js

@@ -0,0 +1,188 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/Composition/index.ts
+var Composition_exports = {};
+__export(Composition_exports, {
+  and: () => and,
+  compose: () => compose,
+  constFalse: () => constFalse,
+  constNull: () => constNull,
+  constTrue: () => constTrue,
+  constUndefined: () => constUndefined,
+  constVoid: () => constVoid,
+  constant: () => constant,
+  converge: () => converge,
+  curry: () => curry,
+  curry3: () => curry3,
+  curry4: () => curry4,
+  flip: () => flip,
+  flow: () => flow,
+  identity: () => identity,
+  juxt: () => juxt,
+  memoize: () => memoize,
+  memoizeWeak: () => memoizeWeak,
+  not: () => not,
+  on: () => on,
+  once: () => once,
+  or: () => or,
+  pipe: () => pipe,
+  tap: () => tap,
+  uncurry: () => uncurry,
+  uncurry3: () => uncurry3,
+  uncurry4: () => uncurry4
+});
+module.exports = __toCommonJS(Composition_exports);
+
+// src/Composition/compose.ts
+function compose(...fns) {
+  return (arg) => fns.reduceRight((acc, fn) => fn(acc), arg);
+}
+
+// src/Composition/converge.ts
+function converge(f, transformers) {
+  return (a) => f(...transformers.map((t) => t(a)));
+}
+
+// src/Composition/curry.ts
+var curry = (f) => (a) => (b) => f(a, b);
+var curry3 = (f) => (a) => (b) => (c) => f(a, b, c);
+var curry4 = (f) => (a) => (b) => (c) => (d) => f(a, b, c, d);
+
+// src/Composition/flip.ts
+var flip = (f) => (b) => (a) => f(a)(b);
+
+// src/Composition/flow.ts
+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));
+  };
+}
+
+// src/Composition/fn.ts
+var identity = (a) => a;
+var constant = (a) => () => a;
+var constTrue = () => true;
+var constFalse = () => false;
+var constNull = () => null;
+var constUndefined = () => void 0;
+var constVoid = () => {
+};
+var and = (p1, p2) => (...args) => p1(...args) && p2(...args);
+var or = (p1, p2) => (...args) => p1(...args) || p2(...args);
+var once = (f) => {
+  let called = false;
+  let result;
+  return () => {
+    if (!called) {
+      result = f();
+      called = true;
+    }
+    return result;
+  };
+};
+
+// src/Composition/juxt.ts
+function juxt(fns) {
+  return (a) => fns.map((f) => f(a));
+}
+
+// src/Composition/memoize.ts
+var memoize = (f, keyFn = (a) => a) => {
+  const cache = /* @__PURE__ */ 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;
+  };
+};
+var memoizeWeak = (f) => {
+  const cache = /* @__PURE__ */ new WeakMap();
+  return (a) => {
+    if (cache.has(a)) {
+      return cache.get(a);
+    }
+    const result = f(a);
+    cache.set(a, result);
+    return result;
+  };
+};
+
+// src/Composition/not.ts
+var not = (predicate) => (...args) => !predicate(...args);
+
+// src/Composition/on.ts
+var on = (f, g) => (a, b) => f(g(a), g(b));
+
+// src/Composition/pipe.ts
+function pipe(a, ...fns) {
+  return fns.reduce((acc, fn) => fn(acc), a);
+}
+
+// src/Composition/tap.ts
+var tap = (f) => (a) => {
+  f(a);
+  return a;
+};
+
+// src/Composition/uncurry.ts
+function uncurry(f) {
+  return (...args) => {
+    const inner = f(...args.slice(0, f.length));
+    return inner.length === 0 ? inner() : inner(...args.slice(f.length));
+  };
+}
+var uncurry3 = (f) => (a, b, c) => f(a)(b)(c);
+var uncurry4 = (f) => (a, b, c, d) => f(a)(b)(c)(d);
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  and,
+  compose,
+  constFalse,
+  constNull,
+  constTrue,
+  constUndefined,
+  constVoid,
+  constant,
+  converge,
+  curry,
+  curry3,
+  curry4,
+  flip,
+  flow,
+  identity,
+  juxt,
+  memoize,
+  memoizeWeak,
+  not,
+  on,
+  once,
+  or,
+  pipe,
+  tap,
+  uncurry,
+  uncurry3,
+  uncurry4
+});