arr-flatten

arr-flatten provides a high-performance recursive array flattening utility that converts nested arrays into a single flat array. It offers a simple, focused API with minimal overhead, making it suitable for performance-critical applications that need to process nested array structures.

Package Information

• Package Name: arr-flatten
• Package Type: npm
• Language: JavaScript (ES5 compatible)
• Installation: npm install arr-flatten
• Node.js Compatibility: >=0.10.0

Core Imports

var flatten = require('arr-flatten');

For ES6 modules (with transpilation):

import flatten from 'arr-flatten';

Basic Usage

var flatten = require('arr-flatten');

// Simple nested array
flatten(['a', ['b', ['c']], 'd', ['e']]);
//=> ['a', 'b', 'c', 'd', 'e']

// Deeply nested array
flatten(['a', [[[[[[[['b', [['c']]]]]], 'd', ['e']]]]]]);
//=> ['a', 'b', 'c', 'd', 'e']

// Mixed content types
flatten([1, [2, [3, 4]], 5]);
//=> [1, 2, 3, 4, 5]

Capabilities

Array Flattening

Recursively flattens an array of arbitrary nesting depth into a single flat array while preserving element order.

/**
 * Recursively flatten an array or arrays
 * @param {Array} arr - The array to flatten, may contain nested arrays at any depth
 * @returns {Array} A new flattened array containing all elements from nested structures
 */
function flatten(arr)

Parameters:

• arr (Array): The input array to flatten. Can contain nested arrays at any depth along with primitive values.

Returns:

• Array: A new flat array containing all elements from the input array and its nested arrays in sequential order.

Behavior:

• Recursively processes arrays at any nesting level
• Preserves the original order of elements
• Does not modify the original input array
• Returns a new array instance
• Non-array elements are preserved as-is in their original positions

Usage Examples:

var flatten = require('arr-flatten');

// Basic flattening
var result = flatten([1, [2, 3], 4]);
console.log(result); // [1, 2, 3, 4]

// Deep nesting
var deep = flatten([1, [2, [3, [4, [5]]]]]);
console.log(deep); // [1, 2, 3, 4, 5]

// Mixed types
var mixed = flatten(['hello', [42, ['world', true]], null]);
console.log(mixed); // ['hello', 42, 'world', true, null]

// Empty arrays
var withEmpty = flatten([1, [], [2, []], 3]);
console.log(withEmpty); // [1, 2, 3]

Performance Characteristics:

• Optimized recursive implementation with minimal overhead
• Uses internal result array to avoid multiple array creation
• Suitable for performance-critical applications
• Memory efficient - creates only one result array

Error Handling:

• The function expects an array as input
• Non-array inputs may cause runtime errors as the function attempts to access .length property and iterate
• No explicit input validation is performed for maximum performance