How does List compare to Immutable.js for functional programming?

List focuses solely on lists with a Ramda-compatible API, offering better tree-shaking and performance for sequence operations, while Immutable.js provides multiple data structures but with a larger bundle size. List's benchmarks show it often outperforms in functional transformations, but Immutable.js might be better for diverse collection needs.

How to update an element at a specific index in List?

Use the `update` or `adjust` functions, which take an index and return a new list—for example, `update(2, 'X', list('a', 'b', 'c'))` replaces the third element. This is O(log(n)) and immutable, unlike native array's mutable assignment.

Does List work with React state management like Redux?

Yes, List is ideal for Redux or React state where immutability is key, as it ensures safe updates without mutations. You can store lists in state and use functions like `map` or `filter` to create new states, but remember to convert to arrays if UI libraries expect them.

What's the bundle size impact of adding List to a project?

List is tree-shaking friendly, with core under 1KB and functions added only as used—importing the whole library adds about 10KB gzipped. For small projects, native arrays might be lighter, but for functional-heavy code, the performance gains can justify the size.

How to handle side-effects like logging with List?

Use the `forEach` function for side-effects, as it's optimized for this purpose without constructing a new list. The README warns against overusing `for..of` loops, which are slower and less idiomatic in functional contexts.

Can List sort objects by a property efficiently?

Yes, use `sortBy` with a function that extracts the property—it performs a stable sort in O(n*log(n)) time. For example, `sortBy(o => o.n, list({n:3}, {n:1}))` returns a sorted list, similar to Ramda but with List's immutable performance.

List — Fast Immutable JS List Structure

What is List?

List is a fast, immutable list data structure for JavaScript that serves as a purely functional alternative to native arrays. It solves the problem of accidental mutations in functional programming by providing a persistent sequence with optimized performance for operations like map, filter, and reduce. The library offers a comprehensive functional API, seamless integration with Ramda, and support for multiple coding styles including curried functions and chainable methods.

Target Audience

JavaScript and TypeScript developers practicing functional programming, especially those using libraries like Ramda or seeking immutable data structures for safer state management. It's also suitable for performance-sensitive applications where functional operations on sequences are frequent.

Value Proposition

Developers choose List over native arrays or other immutable libraries because it combines immutability with high performance, a familiar functional API, and excellent tree-shaking support. Its seamless Ramda integration allows easy adoption for existing Ramda users, while its focus on being a single, optimized data structure ensures reliability and efficiency.

🐆 An immutable list with unmatched performance and a comprehensive functional API.

Use Cases

Best For

Functional programming in JavaScript with immutable data structures
Replacing native arrays in Ramda-based codebases for better performance
Building applications where accidental mutation of arrays is a concern
Performance-critical operations on sequences with functional transformations
TypeScript projects needing fully typed immutable collections
Libraries that require tree-shaking friendly utility functions for lists

Not Ideal For

Projects relying heavily on imperative array mutations like in-place sorting or frequent push/pop operations
Teams prioritizing minimal bundle size over functional benefits, as native arrays have zero overhead
Codebases deeply integrated with libraries expecting native Array instances without conversion glue
Environments where quick prototyping without learning functional patterns is essential

Pros & Cons

Pros

Immutable Safety

Guarantees no accidental mutations, making state predictable in functional code—the README emphasizes this prevents bugs from imperative temptations.

Performance Optimization

Uses relaxed radix balanced trees for persistent operations, with benchmarks showing it often outperforms native arrays in functional use cases like map and filter.

Flexible API Styles

Offers chainable methods, curried functions, and plain imports, catering to different coding preferences while maintaining TypeScript support.

Seamless Ramda Integration

Implements 61 out of 76 Ramda array functions, allowing easy migration for existing Ramda users without API changes.

Cons

Incomplete Ramda Coverage

Missing 15 Ramda functions like `uniq` and `transpose`, which may force users to implement workarounds or stick with arrays for those operations.

Conversion Boilerplate

Requires explicit `toArray` and `from` calls for interoperability with native arrays, adding extra steps in mixed codebases.

FP Learning Curve

The immutable, functional API and concepts like Fantasy Land can be overwhelming for developers accustomed to imperative JavaScript, slowing adoption.

Memory Overhead Risk

Persistent data structures can increase memory usage for large lists compared to mutable arrays, though the README doesn't address this trade-off directly.

Frequently Asked Questions

What is List?

Target Audience

Value Proposition

Use Cases

Best For

Functional programming in JavaScript with immutable data structures
Replacing native arrays in Ramda-based codebases for better performance
Building applications where accidental mutation of arrays is a concern
Performance-critical operations on sequences with functional transformations
TypeScript projects needing fully typed immutable collections
Libraries that require tree-shaking friendly utility functions for lists

Not Ideal For

Projects relying heavily on imperative array mutations like in-place sorting or frequent push/pop operations
Teams prioritizing minimal bundle size over functional benefits, as native arrays have zero overhead
Codebases deeply integrated with libraries expecting native Array instances without conversion glue
Environments where quick prototyping without learning functional patterns is essential

Pros & Cons

Pros

Immutable Safety

Guarantees no accidental mutations, making state predictable in functional code—the README emphasizes this prevents bugs from imperative temptations.

Performance Optimization

Uses relaxed radix balanced trees for persistent operations, with benchmarks showing it often outperforms native arrays in functional use cases like map and filter.

Flexible API Styles

Offers chainable methods, curried functions, and plain imports, catering to different coding preferences while maintaining TypeScript support.

Seamless Ramda Integration

Implements 61 out of 76 Ramda array functions, allowing easy migration for existing Ramda users without API changes.

Cons

Incomplete Ramda Coverage

Missing 15 Ramda functions like `uniq` and `transpose`, which may force users to implement workarounds or stick with arrays for those operations.

Conversion Boilerplate

Requires explicit `toArray` and `from` calls for interoperability with native arrays, adding extra steps in mixed codebases.

FP Learning Curve

The immutable, functional API and concepts like Fantasy Land can be overwhelming for developers accustomed to imperative JavaScript, slowing adoption.

Memory Overhead Risk

Persistent data structures can increase memory usage for large lists compared to mutable arrays, though the README doesn't address this trade-off directly.

Frequently Asked Questions

List

What is List?

Overview

Use Cases

Best For

Not Ideal For

Pros & Cons

Pros

Cons

Frequently Asked Questions

Related Projects

Found a gem we're missing?

List

What is List?

Overview

Use Cases

Best For

Not Ideal For

Pros & Cons

Pros

Cons

Frequently Asked Questions

Related Projects

Found a gem we're missing?