We’re excited to announce that the initial design of Luma's List API has been approved and is now part of the core language direction!

This milestone brings powerful, expressive, and intuitive list operations to Luma, crafted with care to remain true to our core goals of clarity, consistency, and developer comfort.

Why It Matters

Luma lists now support a range of built-in capabilities, making data manipulation both safe and ergonomic, without reaching for helper libraries or verbose boilerplate.

Let’s highlight a few key wins.

Highlights of the List API

Dual Access: list[0] and list.get(0)

We had long discussions about whether both access styles should be supported. In the end, we embraced developer familiarity and flexibility:

nums: [int] = [10, 20, 30]
val = nums[1]       // familiar indexing
val = nums.get(1)   // safe, returns ?int
val = nums.get(99)  // returns nil

get() adds null-safety, while [] remains concise and readable.

No More Loops to Find Common Items: intersect()

One of the standout additions is .intersect(). No need for awkward nested loops when comparing list overlaps:

a: [int] = [1, 2, 3, 4]
b: [int] = [3, 4, 5]
common = a.intersect(b)    // [3, 4]

Clear
Efficient
Expressive

Clean Add & Remove APIs

Both mutable and immutable styles are supported:

nums: [int] = [1, 2]
nums.add(3)              // mutable → [1, 2, 3]
new_list = nums + [4]    // immutable → [1, 2, 3, 4]

nums.remove(2)           // true (if found)
nums.remove_at(0)        // removes index 0

All operations are designed to fail gracefully and return appropriate booleans or optionals.

Full List API

.len()
.get(index)
.index_of(value)
.add(value)
.add_all(list)
.remove(value)
.remove_at(index)
.remove_all(list)
.intersect(other)
.filter(fn)
.sort()
+ and - for immutable add/remove
Slicing: list[1..3]

Example

nums: [int] = [1, 2, 3]
nums.add(4)
slice = nums[1..2]           // [2, 3]
filtered = nums.filter(x -> x > 2)  // [3, 4]
common = nums.intersect([3, 5])     // [3]

Design Philosophy Recap

Consistency: All methods use snake_case
Null-Safety: get() and index_of() return optionals
Flexibility: Choose between mutation or pure expressions
Performance-Conscious: Intersections and filters return new lists to avoid side effects
Readability First: Familiar and expressive code

What’s Next?

Sets
Maps
.group_by() and .reduce() patterns
Generics-based utility extensions

Stay tuned — this is just the beginning.

The full List API documentation is already available at:

https://luma.hashnode.space/default-guide/collections/lists-1-2-3

Luma List API: First Official Design Approved!