filter

The filter utility creates a new array with all elements that pass the test implemented by the provided predicate function.

Implementation

View Source Code

import { assert } from '../function/assert';
import { IS_ARRAY_ERROR_MSG, isArray } from '../typed/isArray';
import type { Predicate } from '../types';

/**
 * Filters an array based on a predicate function.
 *
 * @example
 * ```ts
 * const arr = [1, 2, 3, 4, 5];
 * const isEven = (num) => num % 2 === 0;
 * filter(arr, isEven); // [2, 4]
 * ```
 *
 * @param array - The array to filter.
 * @param predicate - The predicate function to test each element.
 *
 * @returns A new array with elements that pass the predicate test.
 *
 * @throws {TypeError} If the provided array is not an array.
 */
export function filter<T>(array: T[], predicate: Predicate<T>) {
  assert(isArray(array), IS_ARRAY_ERROR_MSG, { args: { array }, type: TypeError });

  const result: T[] = [];

  for (let index = 0; index < array.length; index++) {
    if (predicate(array[index], index, array)) {
      result.push(array[index]);
    }
  }

  return result;
}

filter.fp = true;

Features

• Isomorphic: Works in both Browser and Node.js.
• Type-safe: Properly infers the resulting array type.
• Async Support: If the predicate returns a Promise, filter will return a Promise that resolves to the new array once all elements are processed.

API

function filter<T>(
  array: T[],
  predicate: (item: T, index: number, array: T[]) => boolean | Promise<boolean>,
): T[] | Promise<T[]>;

Parameters

• array: The array to filter.
• predicate: The function called for every element. It receives:
  • item: The current element.
  • index: The index of the current element.
  • array: The original array.

Returns

• A new array with elements that pass the test.
• A Promise<T[]> if the predicate is asynchronous.

Examples

Basic Filtering

import { filter } from '@vielzeug/toolkit';

const numbers = [1, 2, 3, 4, 5, 6];
const evens = filter(numbers, (x) => x % 2 === 0); // [2, 4, 6]

Filtering Objects

import { filter } from '@vielzeug/toolkit';

const users = [
  { id: 1, name: 'Alice', active: true },
  { id: 2, name: 'Bob', active: false },
  { id: 3, name: 'Charlie', active: true },
];

const activeUsers = filter(users, (u) => u.active);
// [{ id: 1, ... }, { id: 3, ... }]

Asynchronous Filtering

import { filter, delay } from '@vielzeug/toolkit';

const ids = [1, 2, 3, 4];
const validIds = await filter(ids, async (id) => {
  await delay(100); // Simulate external validation
  return id % 2 !== 0;
}); // [1, 3]

Implementation Notes

• Throws TypeError if the first argument is not an array.
• When using async predicates, all tests are initiated concurrently.

See Also

• map: Transform elements of an array.
• reduce: Reduce an array to a single value.
• select: Alias for filter in some contexts.