or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-lodash--flatten

Array flattening utilities with single-level, deep, and depth-controlled flattening capabilities

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

To install, run

npx @tessl/cli install tessl/npm-lodash--flatten@4.4.0

index.mddocs/

Lodash Array Flattening Functions

The lodash library provides comprehensive array flattening utilities that enable developers to work with nested array structures more effectively. This Knowledge Tile documents the three complementary flattening functions: flatten, flattenDeep, and flattenDepth, which offer different levels of flattening depth control.

Package Information

  • Package Name: lodash
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install lodash
  • Version Documented: 4.4.0

Core Imports

CommonJS (primary module format for lodash v4.4.0):

const _ = require("lodash");
// Use as _.flatten(), _.flattenDeep(), _.flattenDepth()

ES6 modules (if using a bundler that supports lodash ES modules):

import _ from "lodash";
// Use as _.flatten(), _.flattenDeep(), _.flattenDepth()

Individual function imports (for tree-shaking with compatible bundlers):

const { flatten, flattenDeep, flattenDepth } = require("lodash");

Basic Usage

const _ = require("lodash");

// Single level flattening
const singleLevel = _.flatten([1, [2, [3, [4]], 5]]);
// Result: [1, 2, [3, [4]], 5]

// Deep flattening (all levels)
const deepFlattened = _.flattenDeep([1, [2, [3, [4]], 5]]);
// Result: [1, 2, 3, 4, 5]

// Controlled depth flattening
const twoLevels = _.flattenDepth([1, [2, [3, [4]], 5]], 2);
// Result: [1, 2, 3, [4], 5]

Capabilities

Single Level Flattening

Flattens an array exactly one level deep, converting direct sub-arrays into individual elements while preserving deeper nesting.

/**
 * Flattens `array` a single level deep.
 * @static
 * @memberOf _
 * @category Array
 * @param {Array} array The array to flatten.
 * @returns {Array} Returns the new flattened array.
 */
function flatten(array);

Usage Examples:

const _ = require("lodash");

// Basic single-level flattening
_.flatten([1, [2, 3], [4, [5]]]);
// => [1, 2, 3, 4, [5]]

// With mixed data types
_.flatten(['a', ['b', 'c'], ['d', ['e']]]);
// => ['a', 'b', 'c', 'd', ['e']]

// Handles empty arrays
_.flatten([[], [1, 2], []]);
// => [1, 2]

// Arguments objects are flattened
function example() {
  return _.flatten([arguments, [arguments]]);
}
example(1, 2, 3);
// => [1, 2, 3, Arguments(3)]

Deep Flattening

Recursively flattens an array to any depth, completely removing all nested array structures.

/**
 * Recursively flattens `array`.
 * @static
 * @memberOf _
 * @category Array
 * @param {Array} array The array to flatten.
 * @returns {Array} Returns the new flattened array.
 */
function flattenDeep(array);

Usage Examples:

const _ = require("lodash");

// Complete deep flattening
_.flattenDeep([1, [2, [3, [4]], 5]]);
// => [1, 2, 3, 4, 5]

// Complex nested structures
_.flattenDeep([[1, 2], [3, [4, [5, 6]]], [7, 8]]);
// => [1, 2, 3, 4, 5, 6, 7, 8]

// Arguments objects deeply flattened
function example() {
  return _.flattenDeep([arguments, [arguments]]);
}
example(1, 2, 3);
// => [1, 2, 3, 1, 2, 3]

Controlled Depth Flattening

Recursively flattens an array up to a specified depth level, providing precise control over the flattening process.

/**
 * Recursively flatten `array` up to `depth` times.
 * @static
 * @memberOf _
 * @category Array
 * @param {Array} array The array to flatten.
 * @param {number} [depth=1] The maximum recursion depth.
 * @returns {Array} Returns the new flattened array.
 */
function flattenDepth(array, depth);

Usage Examples:

const _ = require("lodash");

const nested = [1, [2, [3, [4]], 5]];

// Depth of 1 (same as flatten)
_.flattenDepth(nested, 1);
// => [1, 2, [3, [4]], 5]

// Depth of 2
_.flattenDepth(nested, 2);
// => [1, 2, 3, [4], 5]

// Depth of 3 (complete flattening for this example)
_.flattenDepth(nested, 3);
// => [1, 2, 3, 4, 5]

// Depth of 0 (shallow clone, no flattening)
_.flattenDepth(nested, 0);
// => [1, [2, [3, [4]], 5]]

// Negative depth treated as 0
_.flattenDepth(nested, -1);
// => [1, [2, [3, [4]], 5]]

Error Handling

All flatten functions handle edge cases gracefully by returning empty arrays for invalid inputs:

const _ = require("lodash");

// Empty arrays
_.flatten([]) // => []
_.flattenDeep([]) // => []
_.flattenDepth([], 2) // => []

// null and undefined inputs return empty arrays
_.flatten(null) // => []
_.flatten(undefined) // => []
_.flattenDeep(null) // => []
_.flattenDepth(undefined, 2) // => []

// Non-array-like objects return empty arrays
_.flatten({ a: 1 }) // => []
_.flatten("string") // => []
_.flatten(42) // => []

// Sparse arrays preserve their structure
_.flatten([[1, 2, 3], Array(3)]);
// => [1, 2, 3, undefined, undefined, undefined]

// Negative or zero depth in flattenDepth
_.flattenDepth([1, [2, [3]]], 0); // => [1, [2, [3]]] (no flattening)
_.flattenDepth([1, [2, [3]]], -1); // => [1, [2, [3]]] (treated as 0)

// Very large arrays are supported (up to call stack limits)
const largeArray = [Array(500000)];
_.flatten(largeArray); // Works without issues

Technical Details

  • Deep Flattening Implementation: flattenDeep uses INFINITY as the depth parameter internally, allowing unlimited recursion depth
  • Depth Parameter: flattenDepth converts undefined depth to 1, and uses toInteger() to sanitize numeric inputs
  • Base Implementation: All functions use the internal baseFlatten(array, depth) utility for consistent behavior
  • Length Check: Functions return empty arrays immediately when input has no length property or length is 0

Performance Characteristics

  • Memory Efficient: Creates new arrays without modifying input
  • Call Stack Aware: Deep recursion may hit stack limits on extremely nested structures
  • Type Agnostic: Works with any array-like objects including Arguments objects
  • Sparse Array Handling: Treats sparse arrays as dense, filling gaps with undefined
  • Large Array Support: Optimized for arrays up to 500,000 elements

Chaining Support

All flatten functions work with lodash's chainable API:

const _ = require("lodash");

const result = _([1, [2, [3, [4]], 5]])
  .flatten()
  .map(x => x * 2)
  .value();
// => [2, 4, NaN, NaN, 10] (NaN from nested arrays)

// Better with flattenDeep for chaining
const better = _([1, [2, [3, [4]], 5]])
  .flattenDeep()
  .map(x => x * 2)
  .value();
// => [2, 4, 6, 8, 10]