@nlozgachev/pipelined 0.47.0 → 0.48.0

package/dist/composition.d.ts

@@ -1,5 +1,5 @@
-import { A as Awaitable, T as Thenable } from './InternalTypes-Mssktd7z.js';
-import { Duration } from './types.js';
+import { A as Awaitable, T as Thenable } from './InternalTypes-LdhLQx3N.js';
+import { D as Duration } from './Duration-B8joKzro.js';
 
 /**
  * Composes functions from right to left, returning a new function.
@@ -156,6 +156,8 @@ declare function async$1<A, B, C, D, E, F, G, H, I, J, K>(ab: (a: A) => Awaitabl
  *
  * @example
  * ```ts
+ * type User = { name: string };
+ *
  * // Create a reusable transformation
  * const processUser = flow(
  *   (user: User) => user.name,
@@ -228,22 +230,73 @@ declare namespace flow {
 interface flow {
     /**
      * Executes a function on the piped value if a predicate is met, otherwise returns the value unchanged.
+     *
+     * @example
+     * ```ts
+     * const doubleIfEven = flow.when(
+     *   (n: number) => n % 2 === 0,
+     *   n => n * 2
+     * );
+     * doubleIfEven(4); // 8
+     * doubleIfEven(5); // 5
+     * ```
      */
     readonly when: <A>(predicate: (a: A) => boolean, onTrue: (a: A) => A) => (a: A) => A;
     /**
      * Executes a function on the piped value if a predicate is NOT met, otherwise returns the value unchanged.
+     *
+     * @example
+     * ```ts
+     * const doubleIfOdd = flow.unless(
+     *   (n: number) => n % 2 === 0,
+     *   n => n * 2
+     * );
+     * doubleIfOdd(5); // 10
+     * doubleIfOdd(4); // 4
+     * ```
      */
     readonly unless: <A>(predicate: (a: A) => boolean, onFalse: (a: A) => A) => (a: A) => A;
     /**
      * Executes one of two functions based on a predicate, acting as a functional if-else/ternary helper.
+     *
+     * @example
+     * ```ts
+     * const formatNumber = flow.either(
+     *   (n: number) => n >= 0,
+     *   n => `+${n}`,
+     *   n => `${n}`
+     * );
+     * formatNumber(5);  // "+5"
+     * formatNumber(-3); // "-3"
+     * ```
      */
     readonly either: <A, B>(predicate: (a: A) => boolean, onTrue: (a: A) => B, onFalse: (a: A) => B) => (a: A) => B;
     /**
      * Creates a pipeline step that wraps a throwing function in a try/catch, returning a fallback value if an error occurs.
+     *
+     * @example
+     * ```ts
+     * const safeParse = flow.try(
+     *   (s: string) => JSON.parse(s),
+     *   (_err, _s) => null
+     * );
+     * safeParse('{"a":1}'); // { a: 1 }
+     * safeParse('invalid'); // null
+     * ```
      */
     readonly try: <A, B, C>(f: (a: A) => B, onError: (error: unknown, value: A) => C) => (a: A) => B | C;
     /**
      * Builds an object by applying a record of field-level transformer functions to the piped input.
+     *
+     * @example
+     * ```ts
+     * type User = { name: string; age: number };
+     * const summarizeUser = flow.struct<User, { name: string; isAdult: boolean }>({
+     *   name: u => u.name,
+     *   isAdult: u => u.age >= 18,
+     * });
+     * summarizeUser({ name: "Alice", age: 25 }); // { name: "Alice", isAdult: true }
+     * ```
      */
     readonly struct: <A, R extends Record<string, unknown>>(fields: {
         [K in keyof R]: (a: A) => R[K];
@@ -251,10 +304,30 @@ interface flow {
     /**
      * Pipes a value through a sequence of operations, short-circuiting and propagating
      * null or undefined immediately if any intermediate step evaluates to nil.
+     *
+     * @example
+     * ```ts
+     * const getCityLength = flow.safe(
+     *   (user: { address?: { city?: string } }) => user.address,
+     *   address => address.city,
+     *   city => city.length
+     * );
+     * getCityLength({ address: { city: "Paris" } }); // 5
+     * getCityLength({});                            // undefined
+     * ```
      */
     readonly safe: typeof safe$1;
     /**
      * Pipes a value through a sequence of operations, supporting asynchronous transitions at any step.
+     *
+     * @example
+     * ```ts
+     * const processId = flow.async(
+     *   (id: number) => Promise.resolve(`user-${id}`),
+     *   name => name.toUpperCase()
+     * );
+     * await processId(42); // "USER-42"
+     * ```
      */
     readonly async: typeof async$1;
 }
@@ -280,15 +353,50 @@ declare const identity: <A>(a: A) => A;
  * ```
  */
 declare const constant: <A>(a: A) => () => A;
-/** Always returns `true`. */
+/**
+ * Always returns `true`.
+ *
+ * @example
+ * ```ts
+ * constTrue(); // true
+ * ```
+ */
 declare const constTrue: () => true;
-/** Always returns `false`. */
+/**
+ * Always returns `false`.
+ *
+ * @example
+ * ```ts
+ * constFalse(); // false
+ * ```
+ */
 declare const constFalse: () => false;
-/** Always returns `null`. */
+/**
+ * Always returns `null`.
+ *
+ * @example
+ * ```ts
+ * constNull(); // null
+ * ```
+ */
 declare const constNull: () => null;
-/** Always returns `undefined`. */
+/**
+ * Always returns `undefined`.
+ *
+ * @example
+ * ```ts
+ * constUndefined(); // undefined
+ * ```
+ */
 declare const constUndefined: () => undefined;
-/** Always returns `void`. */
+/**
+ * Always returns `void`.
+ *
+ * @example
+ * ```ts
+ * constVoid(); // undefined
+ * ```
+ */
 declare const constVoid: () => void;
 /**
  * Combines two predicates with logical AND.
@@ -343,11 +451,33 @@ declare const once: <A>(f: () => A) => () => A;
  * const getName = flow(
  *   (u: { name?: string | null }) => u.name,
  *   defaultTo("Guest"),
- *   name => name.toUpperCase()
+ *   (name: string) => name.toUpperCase()
  * ); // returns string
  * ```
  */
 declare const defaultTo: <B>(fallback: B) => <A>(a: A) => NonNullable<A> | B;
+/**
+ * Converts a function taking multiple arguments into a function taking a single tuple argument.
+ *
+ * @example
+ * ```ts
+ * const add = (a: number, b: number) => a + b;
+ * const addTuple = tuple(add);
+ * addTuple([2, 3]); // 5
+ * ```
+ */
+declare const tuple: <Args extends readonly unknown[], R>(f: (...args: Args) => R) => (args: Args) => R;
+/**
+ * Converts a function taking a single tuple argument into a function taking multiple arguments.
+ *
+ * @example
+ * ```ts
+ * const addTuple = ([a, b]: readonly [number, number]) => a + b;
+ * const add = untuple(addTuple);
+ * add(2, 3); // 5
+ * ```
+ */
+declare const untuple: <Args extends readonly unknown[], R>(f: (args: Args) => R) => (...args: Args) => R;
 
 /**
  * Applies an input to an array of functions and collects the results into a tuple.
@@ -389,11 +519,13 @@ declare function juxt<A, B>(fns: ReadonlyArray<(a: A) => B>): (a: A) => B[];
  * // With custom key function for objects
  * const fetchUser = memoize(
  *   (opts: { id: string }) => fetch(`/users/${opts.id}`),
- *   opts => opts.id
+ *   { key: (opts) => opts.id }
  * );
  * ```
  */
-declare const memoize: <A, B>(f: (a: A) => B, keyFn?: (a: A) => unknown) => (a: A) => B;
+declare const memoize: <A, B>(f: (a: A) => B, options?: {
+    readonly key?: (a: A) => unknown;
+}) => (a: A) => B;
 /**
  * Creates a memoized version of a function using WeakMap.
  * Only works with object arguments, but allows garbage collection
@@ -401,6 +533,9 @@ declare const memoize: <A, B>(f: (a: A) => B, keyFn?: (a: A) => unknown) => (a:
  *
  * @example
  * ```ts
+ * type User = { id: number; name: string };
+ * const expensiveOperation = (u: User) => u.name.toUpperCase();
+ *
  * const processUser = memoizeWeak((user: User) => {
  *   return expensiveOperation(user);
  * });
@@ -430,10 +565,12 @@ declare const memoizeWeak: <A extends object, B>(f: (a: A) => B) => (a: A) => B;
  * numbers.filter(not(isEven)); // [1, 3, 5]
  *
  * // In pipelines
+ * const users = [{ name: "Alice", isAdmin: false }, { name: "Bob", isAdmin: true }];
+ * const isAdmin = (u: { name: string; isAdmin: boolean }) => u.isAdmin;
  * pipe(
  *   users,
- *   Array.filter(not(isAdmin)),
- *   Array.map(u => u.name)
+ *   Arr.filter(not(isAdmin)),
+ *   Arr.map((u: { name: string; isAdmin: boolean }) => u.name)
  * );
  * ```
  */
@@ -504,7 +641,7 @@ declare function async<A, B, C, D, E, F, G, H, I, J, K>(a: Awaitable<A>, ab: (a:
  *
  * // Error handling with Result
  * const parsed = pipe(
- *   Result.tryCatch(() => JSON.parse('{"value": 42}'), () => "Invalid JSON"),
+ *   Result.tryCatch(() => JSON.parse('{"value": 42}'), { onError: () => "Invalid JSON" }),
  *   Result.map((data: { value: number }) => data.value),
  *   Result.getOrElse(() => null)
  * ); // 42
@@ -560,22 +697,65 @@ declare namespace pipe {
 interface pipe {
     /**
      * Executes a function on the piped value if a predicate is met, otherwise returns the value unchanged.
+     *
+     * @example
+     * ```ts
+     * pipe(
+     *   4,
+     *   pipe.when(n => n % 2 === 0, n => n * 2)
+     * ); // 8
+     * ```
      */
     readonly when: <A>(predicate: (a: A) => boolean, onTrue: (a: A) => A) => (a: A) => A;
     /**
      * Executes a function on the piped value if a predicate is NOT met, otherwise returns the value unchanged.
+     *
+     * @example
+     * ```ts
+     * pipe(
+     *   5,
+     *   pipe.unless(n => n % 2 === 0, n => n * 2)
+     * ); // 10
+     * ```
      */
     readonly unless: <A>(predicate: (a: A) => boolean, onFalse: (a: A) => A) => (a: A) => A;
     /**
      * Executes one of two functions based on a predicate, acting as a functional if-else/ternary helper.
+     *
+     * @example
+     * ```ts
+     * pipe(
+     *   5,
+     *   pipe.either(n => n >= 0, n => `+${n}`, n => `${n}`)
+     * ); // "+5"
+     * ```
      */
     readonly either: <A, B>(predicate: (a: A) => boolean, onTrue: (a: A) => B, onFalse: (a: A) => B) => (a: A) => B;
     /**
      * Creates a pipeline step that wraps a throwing function in a try/catch, returning a fallback value if an error occurs.
+     *
+     * @example
+     * ```ts
+     * pipe(
+     *   '{"a":1}',
+     *   pipe.try(s => JSON.parse(s), () => null)
+     * ); // { a: 1 }
+     * ```
      */
     readonly try: <A, B, C>(f: (a: A) => B, onError: (error: unknown, value: A) => C) => (a: A) => B | C;
     /**
      * Builds an object by applying a record of field-level transformer functions to the piped input.
+     *
+     * @example
+     * ```ts
+     * pipe(
+     *   { name: "Alice", age: 25 },
+     *   pipe.struct({
+     *     name: u => u.name,
+     *     isAdult: u => u.age >= 18
+     *   })
+     * ); // { name: "Alice", isAdult: true }
+     * ```
      */
     readonly struct: <A, R extends Record<string, unknown>>(fields: {
         [K in keyof R]: (a: A) => R[K];
@@ -583,10 +763,29 @@ interface pipe {
     /**
      * Pipes a value through a sequence of operations, short-circuiting and propagating
      * null or undefined immediately if any intermediate step evaluates to nil.
+     *
+     * @example
+     * ```ts
+     * pipe.safe(
+     *   { address: { city: "Paris" } },
+     *   user => user.address,
+     *   address => address.city,
+     *   city => city.length
+     * ); // 5
+     * ```
      */
     readonly safe: typeof safe;
     /**
      * Pipes a value through a sequence of operations, supporting asynchronous transitions at any step.
+     *
+     * @example
+     * ```ts
+     * await pipe.async(
+     *   42,
+     *   n => Promise.resolve(`user-${n}`),
+     *   name => name.toUpperCase()
+     * ); // "USER-42"
+     * ```
      */
     readonly async: typeof async;
 }
@@ -603,7 +802,7 @@ interface pipe {
  *   tap(x => console.log("Before map:", x)),
  *   Maybe.map(n => n * 2),
  *   tap(x => console.log("After map:", x)),
- *   Maybe.getOrElse(0)
+ *   Maybe.getOrElse(() => 0)
  * );
  * // logs: "Before map: { kind: 'Some', value: 5 }"
  * // logs: "After map: { kind: 'Some', value: 10 }"
@@ -713,6 +912,10 @@ declare namespace tap {
      *
      * @example
      * ```ts
+     * const user = { id: 1 };
+     * const saveToDatabase = async (u: typeof user) => {};
+     * const logError = (err: unknown) => console.error(err);
+     *
      * pipe(
      *   user,
      *   tap.async(async (u) => {
@@ -729,6 +932,11 @@ declare namespace tap {
      *
      * @example
      * ```ts
+     * const data = [1, 2, 3];
+     * const processData = (d: typeof data) => d.map(n => n * 2);
+     * const fetchData = async (d: typeof data) => d.length;
+     * const metrics = { histogram: (name: string, ms: number) => {} };
+     *
      * // Time a synchronous computation
      * pipe(
      *   data,
@@ -760,15 +968,15 @@ declare namespace tap {
  * uncurry(nested)(); // 42
  *
  * // Original curried function
- * Maybe.map(n => n * 2)(Maybe.make.some(5)); // Some(10)
+ * Maybe.map((n: number) => n * 2)(Maybe.make.some(5)); // Some(10)
  *
  * // Uncurried - all arguments at once
  * const mapUncurried = uncurry(Maybe.map);
- * mapUncurried(n => n * 2, Maybe.make.some(5)); // Some(10)
+ * mapUncurried((n: number) => n * 2, Maybe.make.some(5)); // Some(10)
  *
  * // Combined with flip for data-first uncurried
  * const mapDataFirst = uncurry(flip(Maybe.map));
- * mapDataFirst(Maybe.make.some(5), n => n * 2); // Some(10)
+ * mapDataFirst(Maybe.make.some(5), (n: number) => n * 2); // Some(10)
  * ```
  *
  * @see {@link flip} for reversing curried argument order
@@ -801,4 +1009,4 @@ declare const uncurry3: <A, B, C, D>(f: (a: A) => (b: B) => (c: C) => D) => (a:
  */
 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, defaultTo, flip, flow, identity, juxt, memoize, memoizeWeak, not, on, once, or, pipe, tap, uncurry, uncurry3, uncurry4 };
+export { and, compose, constFalse, constNull, constTrue, constUndefined, constVoid, constant, converge, curry, curry3, curry4, defaultTo, flip, flow, identity, juxt, memoize, memoizeWeak, not, on, once, or, pipe, tap, tuple, uncurry, uncurry3, uncurry4, untuple };

package/dist/composition.js

@@ -45,9 +45,11 @@ __export(Composition_exports, {
   or: () => or,
   pipe: () => pipe,
   tap: () => tap,
+  tuple: () => tuple,
   uncurry: () => uncurry,
   uncurry3: () => uncurry3,
-  uncurry4: () => uncurry4
+  uncurry4: () => uncurry4,
+  untuple: () => untuple
 });
 module.exports = __toCommonJS(Composition_exports);
 
@@ -249,6 +251,8 @@ var once = (f) => {
   };
 };
 var defaultTo = (fallback) => (a) => a === null || a === void 0 ? fallback : a;
+var tuple = (f) => (args) => f(...args);
+var untuple = (f) => (...args) => f(args);
 
 // src/Composition/juxt.ts
 function juxt(fns) {
@@ -256,8 +260,9 @@ function juxt(fns) {
 }
 
 // src/Composition/memoize.ts
-var memoize = (f, keyFn = (a) => a) => {
+var memoize = (f, options) => {
   const cache = /* @__PURE__ */ new Map();
+  const keyFn = options?.key ?? ((a) => a);
   return (a) => {
     const key = keyFn(a);
     if (cache.has(key)) {
@@ -520,7 +525,9 @@ var uncurry4 = (f) => (a, b, c, d) => f(a)(b)(c)(d);
   or,
   pipe,
   tap,
+  tuple,
   uncurry,
   uncurry3,
-  uncurry4
+  uncurry4,
+  untuple
 });

package/dist/composition.mjs

@@ -24,11 +24,13 @@ import {
   or,
   pipe,
   tap,
+  tuple,
   uncurry,
   uncurry3,
-  uncurry4
-} from "./chunk-KOYYDQH4.mjs";
-import "./chunk-XTVF5R6R.mjs";
+  uncurry4,
+  untuple
+} from "./chunk-5OFVS5UZ.mjs";
+import "./chunk-DENXUTKL.mjs";
 export {
   and,
   compose,
@@ -55,7 +57,9 @@ export {
   or,
   pipe,
   tap,
+  tuple,
   uncurry,
   uncurry3,
-  uncurry4
+  uncurry4,
+  untuple
 };