fp

The fp utility enables "Functional Programming" mode for compatible toolkit functions. It converts a standard utility (where the array is usually the first argument) into a partially applied function where the data argument is moved to the end.

Implementation

View Source Code

import type { Fn } from '../types';
import { assert } from './assert';

// biome-ignore lint/suspicious/noExplicitAny: -
type RemoveFirstParameter<T extends Fn> = T extends (first: any, ...rest: infer R) => any ? R : never;

/**
 * Creates a function that can be used in functional programming mode.
 * This function is a wrapper around the original function, allowing you to pass the first argument as an array.
 *
 * @example
 * ```ts
 * import { fp } from './fp';
 * import { map } from './map';
 *
 * const double = (num: number) => num * 2;
 * const doubleArray = fp(map, double);
 *
 * doubleArray([1, 2, 3]) // [2, 4, 6]
 * ```
 *
 * @param callback - The function to be wrapped.
 * @param args - The arguments to be passed to the function.
 *
 * @returns A function that takes an array and applies the original function to it.
 *
 * @throws {TypeError} If the function cannot be used in functional programming mode.
 */
export const fp = <T, F extends Fn = Fn>(callback: F, ...args: RemoveFirstParameter<F>) => {
  assert(
    // biome-ignore lint/suspicious/noExplicitAny: -
    (callback as any).fp,
    `"${callback.name}" cannot be used in functional programming mode. Please use the original function.`,
  );
  return (array: T[]) => callback(array, ...args);
};

Features

• Isomorphic: Works in both Browser and Node.js.
• Auto-Currying: Pre-binds transformation logic and waits for the data.
• Composition Friendly: Perfect for use with pipe, compose, or native .map()/.filter() calls.
• Type-safe: Properly narrows types for the resulting unary function.

API

function fp<T, R>(callback: (...args: any[]) => any, ...args: any[]): (data: T[]) => R;

Parameters

• callback: A toolkit function that supports FP mode (most array/collection utilities).
• ...args: The configuration arguments for the callback (excluding the data array).

Returns

• A new function that accepts a single argument: the data array to be processed.

Examples

Reusable Transformations

import { fp, map, chunk } from '@vielzeug/toolkit';

// Create a reusable 'doubler' function
const doubleAll = fp(map, (n: number) => n * 2);

doubleAll([1, 2, 3]); // [2, 4, 6]
doubleAll([10, 20]); // [20, 40]

Within a Pipeline

import { fp, pipe, map, filter } from '@vielzeug/toolkit';

const process = pipe(
  fp(filter, (n: number) => n > 10),
  fp(map, (n: number) => n * n),
);

process([5, 12, 8, 20]); // [144, 400]

Implementation Notes

• Only functions that have been specifically prepared for FP mode will work (they must support being called with ...args first).
• Throws TypeError if the callback is not a function.
• Performance is nearly identical to calling the original utility directly.

See Also

• pipe: Compose multiple FP functions together.
• curry: Manual currying for any custom function.
• map: The standard version of the map utility.