before

Creates a new function that limits the number of times the given function (func) can be called.

Signature

function before<F extends (...args: any[]) => any>(
  n: number,
  func: F
): (...args: Parameters<F>) => ReturnType<F> | undefined;

Parameters

• n (number): The number of times the returned function is allowed to call func before stopping.
  • If n is 0, func will not be called.
  • If n is a positive integer, func will be called up to n-1 times.
• func (F): The function to be called with the limit applied.

Returns

((...args: Parameters<F>) => ReturnType<F> | undefined): A new function that:

• Tracks the number of calls.
• Invokes func until the n-1-th call.
• Returns undefined if the number of calls reaches or exceeds n, stopping further calls.

Error

Throws an error if n is negative.

Example

import { before } from 'es-toolkit/function';

const beforeFn = before(3, () => {
  console.log('called');
});

// Will log 'called'.
beforeFn();

// Will log 'called'.
beforeFn();

// Will not log anything.
beforeFn();

Lodash Compatibility

Import before from es-toolkit/compat for full compatibility with lodash.

• before does not throw an error when n is negative.
• before throws an error if func is not a function.
• before returns the last result of func when the number of calls reaches or exceeds n.

import { before } from 'es-toolkit/compat';

let count = 0;

const before3 = before(3, () => {
  console.log('Incrementing count...');
  return ++count;
});

console.log(before3()); // Incrementing count... => 1
console.log(before3()); // Incrementing count... => 2
console.log(before3()); //                       => 2