or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-lodash--flatmap

The lodash method flatMap exported as a Node.js module for creating flattened arrays from mapped collections

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/lodash.flatmap@4.5.x

To install, run

npx @tessl/cli install tessl/npm-lodash--flatmap@4.5.0

index.mddocs/

Lodash FlatMap

The lodash method flatMap exported as a Node.js module. Creates an array of flattened values by running each element in collection through iteratee and concating its result to the other mapped values. Part of lodash's modularized package series for selective imports.

Package Information

  • Package Name: lodash.flatmap
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install lodash.flatmap

Core Imports

const flatMap = require('lodash.flatmap');

For ES modules:

import flatMap from 'lodash.flatmap';

Basic Usage

const flatMap = require('lodash.flatmap');

// Transform and flatten array elements
function duplicate(n) {
  return [n, n];
}

const result = flatMap([1, 2], duplicate);
// => [1, 1, 2, 2]

// With objects
const users = [
  { name: 'alice', tags: ['admin', 'user'] },
  { name: 'bob', tags: ['user', 'guest'] }
];

const allTags = flatMap(users, user => user.tags);
// => ['admin', 'user', 'user', 'guest']

Capabilities

FlatMap Function

Creates an array of flattened values by running each element in collection through iteratee and concating its result to the other mapped values.

/**
 * Creates an array of flattened values by running each element in collection
 * through iteratee and concating its result to the other mapped values.
 * The iteratee is invoked with three arguments: (value, index|key, collection).
 * 
 * @param {Array|Object} collection - The collection to iterate over
 * @param {Function|string|Object} [iteratee=_.identity] - The function invoked per iteration
 * @returns {Array} Returns the new flattened array
 */
function flatMap(collection, iteratee);

Parameters:

  • collection {Array|Object} - The collection to iterate over. Can be arrays, array-like objects, or plain objects. Falsey values are treated as empty collections. Numeric values are treated as empty collections.
  • iteratee {Function|string|Object} - The function invoked per iteration. Can be:
    • Function: (value, index|key, collection) => any - Custom transformation function receiving three arguments
    • string: Property path for extracting values (e.g., 'tags' to extract obj.tags)
    • Object: Plain object to match properties against using deep equality
    • Default: _.identity if not provided (returns the values as-is)

Return Value:

  • Type: Array
  • Description: Returns a new flattened array with results from mapping each element and flattening by one level

Iteratee Function Signature:

When providing a function as the iteratee:

/**
 * @param {*} value - The current element being processed
 * @param {number|string} index - The index of the element (for arrays) or key (for objects)  
 * @param {Array|Object} collection - The collection being iterated over
 * @returns {*} The transformed value(s) to be flattened
 */
function iteratee(value, index, collection);

Usage Examples:

const flatMap = require('lodash.flatmap');

// Basic array transformation
const numbers = flatMap([1, 2, 3], n => [n, n * 2]);
// => [1, 2, 2, 4, 3, 6]

// Object collection
const data = { a: [1, 2], b: [3, 4] };
const result = flatMap(data, arr => arr);
// => [1, 2, 3, 4]

// String property extraction
const objects = [
  { values: ['a', 'b'] },
  { values: ['c', 'd'] }
];
const extracted = flatMap(objects, 'values');
// => ['a', 'b', 'c', 'd']

// Object matching (iteratee as Object)
const users = [
  { name: 'alice', active: true, roles: ['admin'] },
  { name: 'bob', active: false, roles: ['user'] },
  { name: 'charlie', active: true, roles: ['user', 'moderator'] }
];
const activeUserRoles = flatMap(users, { active: true });
// => [{ name: 'alice', active: true, roles: ['admin'] }, { name: 'charlie', active: true, roles: ['user', 'moderator'] }]

// Empty collections and edge cases
const empty = flatMap([], n => [n, n]);
// => []

const nullish = flatMap(null);
// => []

const undefinedValue = flatMap(undefined);
// => []

const numeric = flatMap(1);
// => []

// Nested arrays (only flattens one level)
const nested = flatMap([[1, [2]], [3, [4]]], arr => arr);
// => [1, [2], 3, [4]]

// Object with length property (treated as object, not array-like)
const objWithLength = { length: [1, 2], other: [3, 4] };
const objResult = flatMap(objWithLength, val => val);
// => [1, 2, 3, 4]

Error Handling:

  • Does not throw explicit errors for invalid inputs
  • Handles null, undefined, and empty collections gracefully by returning empty arrays
  • Numeric values for collection are treated as empty and return empty arrays
  • Non-array-like return values from iteratee are treated as single elements
  • Objects with non-number length properties are iterated as objects, not arrays
  • Uses internal lodash type checking for safe operations

Performance Characteristics:

  • Time Complexity: O(n * m) where n is collection size and m is average result size per element
  • Space Complexity: O(result_size) for the flattened output array
  • Flattening Depth: Only flattens one level deep (not recursive)
  • Single-pass iteration with immediate flattening