Readable Configuration Builders

Configuration has a reputation problem. It tends toward verbosity — deeply nested structures, arrays of arrays, keys that reference other keys. A simple data source configuration can become difficult to read after a few additions, and difficult to read means difficult to maintain.

Swifty's configuration builders address this with a fluent, chainable syntax that reads almost like a sentence.

What a Builder Looks Like

Rather than writing out a data source as a raw configuration array, you compose it through method calls that express intent:

DataSource::object('invoice')
    ->filter('status', 'issued')
    ->sortBy('dueDate', 'asc')
    ->columns(['number', 'customer', 'amount', 'dueDate'])
    ->paginate(25)

Each method call adds one piece of configuration. The result reads as: "a data source of invoices, filtered to issued status, sorted by due date ascending, showing these columns, with 25 per page."

The same approach works for screens, forms, navigation, and other structural definitions. Each builder exposes methods that correspond to the concepts of that structure, using terminology that matches the domain.

Why Readability Matters

Code is read far more often than it's written. A definition that was clear to write last month should be clear to read next month, potentially by someone who didn't write it. Readability isn't a cosmetic concern — it's a maintenance concern.

Builders enforce a kind of structure that raw arrays don't. Each method has a name that describes what it does. The chaining pattern ensures related configuration is grouped together. The result is more scannable than an equivalent array representation.

Autocomplete and Type Checking

Builders integrate with developer tooling. Method names autocomplete in editors. Invalid configurations — referencing a sort field that doesn't exist on the object, or calling a method with the wrong argument type — surface as errors before the definition is ever applied.

This is a meaningful improvement over raw array configuration, where a typo in a key name silently produces incorrect behavior rather than an error.

Generators Under the Hood

Builders are a convenience layer. They generate the same underlying definition structures that raw configuration would produce. The builder output can be inspected, serialized, and stored. Nothing in the platform treats builder-generated definitions differently from manually crafted ones.

This means builders are fully interoperable with the rest of the definition system. Mix builder-generated and manually written definitions freely. Export and import definitions built with builders alongside any other definitions.

The goal is simple: configuration that experienced developers find efficient to write, and that anyone on the team can understand later.