When File Handling Finally Felt Right in Luma

Language design often moves quietly. There are no fireworks when something finally clicks - just a moment when you reread a piece of code and realize you no longer feel uneasy about it.

That’s exactly what happened recently with file handling in Luma.

At first glance, nothing dramatic changed. Files can be read, written, copied, moved. Logs can be appended. Metadata can be queried. All things you’d expect.

But internally, one small conceptual shift changed everything.

The moment things broke

Early on, the file() constructor tried to be helpful. It opened the file immediately, returning a real file handle underneath. That’s what many languages do, and it seemed sensible at the time.

Until it wasn’t.

f: file = file("examples/logger.log")
f.create()

This code looks innocent. In fact, it reads exactly how a human would describe the task: “Here is a file. Create it.”

But it failed - because the file didn’t exist yet. The constructor had already tried (and failed) to open it.

That was the moment we realized something important: we were forcing mechanics too early.

Files are not actions — they’re values

In Luma, values are meant to be safe to create. They describe intent. They don’t immediately cause side effects just by existing.

A file path fits that idea perfectly.

So we changed the meaning of file().

Instead of opening anything, it now simply creates a reference - a value that remembers a path. Nothing more.

f: file = file("examples/logger.log")

This line can never fail. It doesn’t touch the filesystem. It just says: “This is the file I’m talking about.”

Actual work happens only when you ask for it.

When behavior becomes obvious

Once files became references instead of handles, everything else started to feel natural.

Creating a file works the way you expect:

f: file = file("examples/logger.log")
f.create()

Writing to it feels straightforward:

f.write("First log entry")
f.add("Second log entry")
f.add("Third log entry")

And reading it back is just as simple:

content: str = f.read()
print(content)

Each operation opens the file, does its job, and closes it again. No lifecycle management. No hidden state. No surprises.

This matches how most programs actually use files - short, atomic operations that don’t need a long-lived handle.

A file that doesn’t exist is still useful

One of the biggest benefits of this model is that it allows you to talk about files that don’t exist yet.

You can check for existence:

if f.exists() {
    print("File already exists")
}

You can create it conditionally:

if !f.exists() {
    f.create()
}

You can even move or delete it - all without ever having opened it manually.

The file value stays the same. Only the operations change.

Everyday tasks feel lighter

Logging is a great example of how this simplicity pays off.

fn log(message: str) {
    f: file = file("app.log")
    f.add("${now()}: ${message}")
}

There’s no setup code. No explicit open or close. Just intent.

And because each operation is atomic, this works reliably even if the function is called many times.

Learning from a wrong assumption

None of this required adding new features. There was no new syntax. No clever abstractions.

The improvement came from removing a single wrong assumption: that file() should open something.

Once that assumption was gone, the API aligned naturally with Luma’s philosophy:

• values are cheap
• intent comes first
• common cases should be frictionless

More advanced features - streaming, walking through large files, globbing - will build on top of this foundation. But they’ll do so without reintroducing handles, cursors, or hidden state.

Quiet progress is still progress

This change might look small from the outside, but it marks an important moment for Luma. File handling no longer feels borrowed from other languages. It feels like it belongs.

And that’s often how the best design decisions arrive - not loudly, but with a sense of calm certainty that this is finally right.