Forem: Mykola Haliullin

Encapsulated Collaboration: Using Closures to Extend Class Behavior Without Violating Interface Boundaries

Mykola Haliullin — Tue, 05 Aug 2025 13:33:41 +0000

This article is part of a broader discussion in my book Safe by Design: Explorations in Software Architecture and Expressiveness. If you like it, you might enjoy the full read for free on GitHub.

Introduction: The Hidden Cost of Interface Changes

In software architecture, one of the most subtle forms of technical debt comes not from what we write - but from what we expose.

It often starts with a small, well-meaning change: we want to add access to a private field or internal method of an important class. But we only need that access in one very specific client - a test, a legacy integration, a specialized handler. And so we think: maybe we should just extend the interface a little?

But this decision, while easy to justify in the moment, has long-lasting consequences. Every extension to an interface creates a new public contract. And public contracts are sticky. Other developers start to rely on it. The internal detail becomes external behavior. You've added surface area - and lost encapsulation.

This article explores a practical architectural technique to solve such cases elegantly: using closures to provide internal access without exposing internal state, and without bloating your interface. We'll walk through the problem, naive solutions, and then land on a design pattern that preserves encapsulation, keeps dependencies clean, and minimizes ripple effects in your codebase.

Let's dive in.

The Problem: One Class, One Secret, One Needy Client

Imagine you're working with a critical class in your codebase - let's call it ImportantService. It's well-designed, well-tested, and widely used across the system. Somewhere deep inside, it holds a private detail - say, a cache map or a connection state - that is intentionally hidden from the outside world.

Now suppose you have a very specific client - maybe a migration job, a diagnostic tool, or an adapter - that needs to interact with that internal detail just once, in one specific place. It doesn't need full control over the class. It doesn't even need to know how the field works. It just needs to use it once, responsibly.

But there's a problem: that field isn't accessible. The only way to reach it is by modifying ImportantService's public interface. And that feels wrong.

You hesitate, and rightfully so. Because modifying a public interface means opening a door that was previously closed. And once that door is open, it rarely gets closed again. Even if your intention was to use it just once, you can't stop other parts of the codebase from wandering through it later.

So you're stuck:

You don't want to break encapsulation.
You do need access in one place.
And you're not sure how to solve this cleanly.

That's the problem we're going to tackle.

Naïve Solution: Just Expose the Field

The most straightforward way to solve this is deceptively simple:

Just add a new method to the public interface.

For example, you might write:

class ImportantService {
    private val cache = mutableMapOf<String, String>()
    fun getCache(): MutableMap<String, String> {
        return cache
    }
}

Now your client can interact with the internal cache freely. Problem solved?

Not quite.

You've just violated the principle of encapsulation - and done so permanently. What was once an implementation detail is now a public API. Even if your intention was to use this method in only one place, you've effectively told every other developer:

"Hey, feel free to reach into this internal structure whenever you like."

This creates three major problems:

Fragility - The internal structure can no longer change freely. If you swap cache for a different mechanism later, you'll break all clients relying on getCache().
Misuse Risk - Other parts of the codebase might start using the exposed method in ways you didn't anticipate - maybe even mutating shared state.
Interface Pollution - The class's public interface becomes bloated with methods that serve niche needs, making it harder to understand and harder to maintain.

This approach works in the short term but almost always causes regret later. It's a technical shortcut with long-term cost.

And most importantly: it introduces a contract where none was meant to exist. The moment you expose something, you own it - forever.

Better But Clumsy: Interface Splitting and Casting

If exposing a private field directly is too risky, a slightly better solution might be to split the interface. That is, define two interfaces:

A public interface that contains only the safe, general-purpose methods used by the majority of the system.
A specialized interface that includes access to the internal detail - used only where truly needed.

It could look like this:

interface PublicAPI {
    fun doSomething()
}
interface InternalAPI : PublicAPI {
    fun getCache(): MutableMap<String, String>
}
class ImportantService : InternalAPI {
    private val cache = mutableMapOf<String, String>()
    override fun doSomething() {
        // ...
    }
    override fun getCache(): MutableMap<String, String> = cache
}

In your codebase, you expose ImportantService only as PublicAPI. But in the one place that needs getCache(), you can do a cast:

val service: PublicAPI = getImportantService()
val internal = service as? InternalAPI
internal?.getCache()?.put("debug", "value")

This approach does preserve encapsulation to an extent - the getCache() method isn't visible unless you explicitly cast to InternalAPI.

But it comes with its own set of problems:

Unsafe Type Casting - Even though you "know" the type at runtime, you're opting out of compile-time safety. That's a slippery slope and a code smell in most modern systems.
Leaky Abstractions - You've now introduced multiple views of the same object. If other developers find and misuse the InternalAPI, you're back to polluting your architecture.
Refactoring Overhead - You've complicated your class hierarchy and added extra interfaces to maintain, all to solve a one-off case.

In theory, interface segregation is a clean architectural practice. But in this scenario - where the need is rare, isolated, and very specific - it can feel like overkill. Worse, the as? cast becomes a tacit admission:

"We broke the type system a little, but it's probably fine."
There must be a better way.

If you're enjoying this so far, there's a lot more in the book - same tone, just deeper. It's right here if you want to peek.

Elegant Trick: Using Closures to Encapsulate Access

Instead of modifying the interface or relying on unsafe casts, we can flip the problem:

What if we don't expose the internal detail, but instead expose a controlled interaction with it?

This is where closures (or lambdas) come in.

Rather than letting the client access the internal field, we let the internal field access the client logic - but only in a very narrow and safe way.

Let's take the same ImportantService, but this time, we give it a method that accepts a function:

class ImportantService {
    private val cache = mutableMapOf<String, String>()
    fun <R> withCache(action: (MutableMap<String, String>) -> R): R {
        return action(cache)
    }
}

Now in the client:

val service = ImportantService()
service.withCache { cache ->
    cache["debug"] = "value"
}

This looks similar to accessing the cache directly, but it's a different animal architecturally.

Why is this better?

Controlled Exposure The internal detail is still private. You're only giving clients a momentary, scoped interaction with it - and only when you choose to.
No Interface Pollution You didn't add a new getter. You didn't expand your public API. The class's surface area remains tight.
No Type Leaks No casting, no subclassing, no interface proliferation. Everything is encapsulated within the boundary of the method.
Clear Intent By naming the method withCache, you signal that this is a controlled and intentional handoff - not an invitation to poke around.

Bonus: Functional Composition

You can combine this pattern with other functional tools - mapping, chaining, filtering - to do expressive work with internal state without ever revealing it.

This is already a much cleaner solution. But it has a hidden cost we'll explore next - and it involves dependency direction.

But Wait: Inverted Dependencies

At first glance, the closure-based approach seems perfect: it keeps your internal field private, avoids interface pollution, and provides clients with just enough power to get their job done.

But there's a subtle shift happening here - one that could quietly violate a key architectural principle: dependency direction.
Let's look again at the method:

fun <R> withCache(action: (MutableMap<String, String>) -> R): R {
    return action(cache)
}

Who's in control here?

The client defines the action, i.e. the logic that operates on the cache.
The ImportantService receives and executes that logic.

This means the core class - the thing we want to keep stable and authoritative - is now depending on a function provided by an external client.

That's an inversion of control. And not the good kind.
In traditional architecture, the stable component should not depend on the volatile one. That's the essence of the Stable Dependencies Principle. And here, we just flipped that - the ImportantService now calls out to a client-defined function.

Why is that a problem?

Hidden Coupling - Now the core class indirectly relies on logic defined elsewhere. This creates temporal and behavioral coupling that's hard to trace.
Change Fragility - If the client's closure changes in a way that breaks assumptions, it can affect the core class, even if its own code hasn't changed.
Harder to Test in Isolation - Testing the core class now requires mocking or simulating the injected closure logic, which might not be desirable.

So while closures give us encapsulation, they come at the cost of reversing the dependency graph.

To keep things clean, we need to restore the direction - without losing the flexibility. And that's exactly what we'll tackle next.

The Final Abstraction: A Dedicated Closure Carrier

To resolve the dependency inversion without giving up the elegance of closures, we introduce a new architectural element:

a small, dedicated abstraction that acts as a neutral carrier of logic.

Instead of passing the closure from the client directly into the ImportantService, we wrap that logic inside a purpose-built object - let's call it CacheAction.

fun interface CacheAction<R> {
    fun execute(cache: MutableMap<String, String>): R
}

This interface does one thing: defines a contract for interacting with the internal cache. It is not the client, and it is not the service - it's an abstraction between them.

Now, the ImportantService depends on CacheAction, not on an arbitrary client-provided lambda:

class ImportantService {
    private val cache = mutableMapOf<String, String>()
    fun <R> perform(action: CacheAction<R>): R {
        return action.execute(cache)
    }
}

And on the client side:

val action = CacheAction<String> { cache ->
    cache["debug"] = "value"
    "done"
}
val result = service.perform(action)

Why is this better?

Dependency Flow is Restored The service depends only on the abstraction (CacheAction), which is stable and controlled. It doesn't care where the implementation comes from.
Encapsulation is Preserved The cache is still private. No getters, no leaks.
Interface is Clean and Intention-Revealing The method name perform + the typed parameter make the intent explicit: you're performing an action on behalf of the service, using its private parts.
Testability is Improved You can now test ImportantService with stub CacheActions, or test different CacheAction implementations independently.
Optional Reuse and Registry In larger systems, you can even register reusable CacheActions - or compose them - giving you plugin-like extensibility without ever exposing internals.

This pattern gives you the power of closures, the safety of clean dependencies, and the expressiveness of functional composition - all while keeping your architecture tidy.
We've now solved the original problem without polluting the interface, without unsafe casts, and without inverting control in the wrong direction.
Let's wrap it up.

Summary: Extend Without Breaking

Let's recap the journey. We started with a simple but frustrating problem:

How do you give a specific client access to a private part of a class without compromising the design of the system?

We explored several options:

Exposing a getter - quick but harmful. It breaks encapsulation and pollutes the interface.
Splitting interfaces and casting - safer in theory, but clunky and error-prone in practice.
Using closures - elegant and concise, but introduces inverted dependencies.
Introducing a dedicated abstraction - the best of all worlds: encapsulated behavior, clean dependency flow, and composability.

When to use this pattern

This isn't a tool for every situation. But it's a great fit when:

You need to access internal state in a very limited scope.
You want to avoid expanding the public API.
You care about preserving architectural boundaries and avoiding coupling.
You prefer explicit contracts over ad hoc conventions.

It's especially useful in large codebases or long-lived systems, where interface cleanliness and dependency direction have real consequences.

Closing thought

Architecture is about trade-offs. But sometimes, with a bit of creativity, we can have our cake and eat it too - extending functionality without breaking design, hiding complexity without losing power, and building systems that are both flexible and principled.

Closures, when used thoughtfully, are one of those quiet superpowers.

If you enjoyed this article, you might like my book Safe by Design: Explorations in Software Architecture and Expressiveness. It dives deeper into topics like this one - contracts, type safety, architectural clarity, and the philosophy behind better code.

👉 Check it out on GitHub

Designing a Flexible Ability System for Games

Mykola Haliullin — Fri, 01 Aug 2025 13:41:04 +0000

✨ This article is part of a broader discussion in my book Safe by Design: Explorations in Software Architecture and Expressiveness. If you like it, you might enjoy the full read for free on GitHub.

Introduction: Why Ability Systems Must Be Flexible

In game development, the ability system is often one of the most demanding components in terms of flexibility. At the design stage, it’s nearly impossible to predict what spells, abilities, or skills will exist in the final version — or what updates will introduce in the future.

This article is about how I approached this uncertainty by abstracting the process of executing abilities.

At its core, an ability is nothing more than a set of actions. A minimalistic ability interface might consist of a single method like apply(). But in practice, things are rarely that simple. The complexity doesn't lie in calling the ability — it lies in determining whether the ability can or should be used at all.

In order to manage this complexity and allow for future expansion, we need a flexible, modular approach that decouples ability execution from the conditions under which it may or may not proceed. This leads us to rethink how to structure ability logic from the ground up.

The First Layer: Ability Checks as Chainable Components

Every ability begins with a series of checks that determine whether it can be used. These checks are usually things like:

Is the ability off cooldown?
Does the character have enough mana?
Is the target within range?

Right away, it becomes obvious that not every ability needs every check. For instance, some abilities might not require mana, or may be usable at any distance.

This means different abilities require different sets of preconditions. However, many of these checks are reused across multiple abilities. Cooldown, mana, and range checks are common across dozens of spells. If these checks are duplicated everywhere, any change to their logic must be applied in many places — creating fragility.

To avoid duplication and enable flexibility, we can extract each check into its own object implementing a shared interface. Then, we link them together in a single, ordered chain.

This is the classic Chain of Responsibility pattern.

Here’s what such an interface might look like:

interface CastChecker {
    CastChecker nextChecker { get; set; }
    bool check();
}

And here’s an example of a simple chain:

CooldownChecker → ManaChecker → CastRangeChecker
Each checker performs a specific validation and, if successful, passes control to the next in the chain.

This structure allows for reuse, recombination, and centralized changes — the foundation of a truly flexible system.

Executing the Chain: Sequential Validation and Error Handling

Once we’ve assembled a chain of CastChecker objects, the system can process them sequentially to validate whether an ability can be used.

Each checker in the chain follows the same logic:

If its own condition fails, it stops the chain and reports an error (e.g. “Not enough mana”).
If the condition passes, it calls the next checker, continuing the validation process.

Here’s a simple implementation outline:

bool CastChecker.check() {
    if (!thisConditionIsMet()) {
        showErrorMessageToPlayer();
        return false;
    } else if (nextChecker != null) {
        return nextChecker.check();
    } else {
        return true;
    }
}

This design introduces a few key benefits:

✅ 1. Composable and Maintainable Checks
You can build a custom validation pipeline per ability without rewriting shared logic. For example:

A fireball might need mana, cooldown, and range.
A healing spell might only need cooldown and line of sight.
✅ 2. Readable Flow
Since each check is self-contained, its logic stays focused and understandable. The CastChecker interface allows adding new conditions without modifying existing ones.

✅ 3. Centralized Error Handling
Each checker can report its own failure reason — giving clear, targeted feedback to the player.

This modularity is what sets the system apart from ad hoc validation logic. We’re no longer writing giant if statements or switch-cases. Instead, we assemble abilities like LEGO blocks — combining reusable, testable pieces.

Abstraction via SkillCastRequest

Now that we’ve covered how to validate an ability using a chain of checkers, we need to think about how the ability actually gets executed — and more importantly, how to represent that execution as an abstract, independent process.

Let’s introduce a new interface: SkillCastRequest.

This interface doesn’t care whether the ability is an instant fireball or a multi-phase ritual. It simply represents “a request to perform an action,” and exposes a standard way to start or cancel it:

interface SkillCastRequest {
    void startRequest();
    void cancelRequest();
}

This abstraction lets us treat the execution logic as a first-class citizen in our architecture.

Instead of having every ability directly embed its own complex execution logic (animations, delays, input windows, etc.), we separate that into a reusable request object.

Benefits of this approach:

Reusability: The same request logic (e.g., a charging bar or input sequence) can be used for multiple skills.
Interruptibility: Requests can be paused, canceled, or restarted independently from the ability system.
Asynchronicity: Since startRequest() doesn’t return anything, it can easily support coroutine-like or event-driven flows.

In essence, this abstraction decouples what the skill does from how it gets initiated — a critical distinction for building flexible gameplay systems.

TerminalChecker and Executing the Skill

We now have two powerful tools in our toolbox:

A chain of CastCheckers that validates whether a skill can be used.
A SkillCastRequest that encapsulates the process of executing that skill.
But how do we tie them together in a way that guarantees execution only happens if all checks pass?

That’s where the TerminalChecker comes in.

It’s a special node in the chain — always placed at the end — whose job is to trigger the actual startRequest() call when all prior checks succeed.

Example:

class TerminalChecker implements CastChecker {
    CastChecker nextChecker = null;
    SkillCastRequest request;

    bool check() {
        request.startRequest();
        return true;
    }
}

In a full chain, it might look like this:

CooldownChecker → ManaChecker → RangeChecker → TerminalChecker
Only if the first three validations pass will the request begin.

Why separate the final execution?

Keeps responsibilities clean. Each checker only checks; only the final node triggers execution.
Easier to reuse. You can create different TerminalCheckers for different types of execution (e.g., networked requests, instant local effects, delayed effects).
Supports asynchronous operations. For example, some skills might involve charging, targeting, or waiting for input before resolving. The request object can handle that without polluting the checker logic.
This final step bridges the gap between should the ability run and go ahead and run it.

📘 If you’re enjoying this so far, there’s a lot more in the book — same tone, just deeper. It’s right here if you want to peek.

Binding the Skill and the Request

We’ve now split ability logic into two distinct domains:

Validation logic — handled by the CastChecker chain
Execution logic — encapsulated in a SkillCastRequest

But how do we represent an actual skill — something the player can activate?

Simple: we bind both parts together under a unified interface.

Defining the Skillinterface:

interface Skill {
    string name;
    SkillCastRequest request;
    CastChecker checker;

    bool cast() {
        return checker.check();
    }
}

When the player tries to use a skill:

The cast() method is called.
The checker chain is executed.
If the final TerminalChecker is reached, it starts the SkillCastRequest. This design gives us complete separation of concerns:
The ability’s name and metadata live in the Skill object.
Validation logic lives in its checker chain.
Execution logic lives in the request. Why this is powerful:
You can reuse checkers and requests across multiple skills.
You can dynamically assemble or swap out parts at runtime.
You can subclass or wrap Skill objects to add logging, cooldown tracking, analytics, or multiplayer synchronization — without changing the base structure. This turns your skills into pure data + behavior composition, making them ideal for designers, modders, and procedural generation.

Example and Conclusion: A Universal Execution Framework

Let’s put it all together with a concrete example: the TeleportationSkill.

Teleportation is a perfect case because it breaks common assumptions:

It doesn’t require mana.
It can’t be used in combat.
It requires the player to stand on a teleportation pad.
It has a long cooldown.
It must wait for the player to confirm the destination.

Using our architecture, this complex behavior is no problem.

We assemble it like this:

Checkers:

CooldownChecker
InCombatChecker (custom logic: player must be out of combat)
SurfaceChecker (verifies player is on correct surface)
TerminalChecker (starts the request)

Request:

TeleportationRequest, which:
Opens a destination selection UI
Waits for confirmation
Moves the character

Skill object:

Skill teleport = new Skill(
    name = "Teleport",
    checker = new CooldownChecker(
        next = new InCombatChecker(
            next = new SurfaceChecker(
                next = new TerminalChecker(request = teleportationRequest)
            )
        )
    ),
    request = teleportationRequest
);

This entire skill is fully declarative and composable. No tight coupling, no duplicated logic. If we later want to use the same teleportation behavior for enemies or items — we just plug in the same request.

Final Thoughts

By separating validation, execution, and composition:

We gain modularity: each component is testable and replaceable.
We gain extensibility: adding new checks or execution styles is trivial.
We gain clarity: game logic becomes declarative, not imperative. Summary Diagram

Skill
 ├── name: "Teleport"
 ├── checker:
 │    └── CooldownChecker
 │         └── InCombatChecker
 │              └── SurfaceChecker
 │                   └── TerminalChecker → request.startRequest()
 └── request: TeleportationRequest

This is a universal framework not just for spells or attacks, but for any game mechanic where action depends on conditions.

You can use this to build skill trees, item usage systems, interaction mechanics — anything where “can I do this?” must be evaluated before “do this.”

If you enjoyed this article, you might like my book Safe by Design: Explorations in Software Architecture and Expressiveness. It dives deeper into topics like this one — contracts, type safety, architectural clarity, and the philosophy behind better code.

👉 Check it out on GitHub

What’s Wrong with Data Validation — and How It Relates to the Liskov Substitution Principle

Mykola Haliullin — Tue, 29 Jul 2025 14:03:02 +0000

✨ This article is part of a broader discussion in my book Safe by Design: Explorations in Software Architecture and Expressiveness. If you like it, you might enjoy the full read for free on GitHub.

Introduction: When You Don’t Know if You Should Validate

In everyday software development, many engineers find themselves asking the same question: “Do I need to validate this data again, or can I assume it’s already valid?”

Sometimes, the answer feels uncertain. One part of the code performs validation “just in case,” while another trusts the input, leading to either redundant checks or dangerous omissions. This situation creates tension between performance and safety, and often results in code that is both harder to maintain and more error-prone.

In this article, I want to examine this common problem from a design perspective and show how it’s related to a deeper architectural issue: a violation of the Liskov Substitution Principle (LSP), one of the core tenets of object-oriented design.

But beyond that, I will propose a structural solution — based on leveraging types as contracts of validity — that shifts the responsibility of validation from the developer to the system itself.

The Trouble with Data Validation

When designing a system, it’s common to introduce validation logic to ensure that a given data structure meets certain constraints. Formally, we might say: we receive some input, validate that its values fall within a defined domain of acceptable values, and then proceed. Later in the program, the same structure may be validated again, either defensively or out of uncertainty. If the data hasn’t changed, this revalidation is redundant.

While validation may impact performance, the more significant issue is ambiguity: Who is responsible for ensuring that the data is valid at any given point in the program?

This uncertainty creates friction in both directions:

Some developers may repeat validations unnecessarily, slowing down the system and cluttering the code.
Others may skip validations, wrongly assuming the input has already been checked.

Both scenarios result in fragile systems. A function may receive data that violates preconditions, not because the validation failed, but because it was silently omitted. Over time, this inconsistency becomes a source of bugs and unreliable behavior.

What seems like a minor technical detail — “just a simple check” — is actually a structural weakness in how the program models trust and correctness.

The Liskov Violation

This ambiguity around validation responsibility is more than just a code hygiene problem — it’s a design flaw. More precisely, it often leads to a violation of the Liskov Substitution Principle (LSP), one of the foundational ideas in object-oriented programming.

LSP states that objects of a subclass should be substitutable for objects of a superclass without altering the correctness of the program. That is, if a method expects an instance of class Parent, it should work correctly with any Child : Parent, without needing to know the exact type.

Now consider the following pattern, which may look familiar:

class Parent { ... }
class Child : Parent { ... }
...
// somewhere
void processValidObject(Parent parent) {
    if (parent is Child) {
        // process
    } else {
        // error
    }
}

This is a textbook LSP violation. The method claims to accept any Parent, but in reality, it only works if the object is a Child. The contract implied by the method signature is broken, and the type system no longer tells the truth.

In validation terms, the same mistake is often made implicitly: a method declares that it accepts a generic structure (e.g., User, InputData, Request), but silently assumes that this structure has already passed some validation process — without enforcing it or expressing it in the type system.

As a result, invalid inputs creep into places where they were never meant to go, and the program becomes reliant on undocumented, non-local assumptions.

📘 If you’re enjoying this so far, there’s a lot more in the book — same tone, just deeper. It’s right here if you want to peek.

A Better Way: Validity Contracts and Subtypes

Instead of relying on documentation or developer discipline to enforce validation, we can model validity explicitly in the type system. The core idea is simple:

If a certain structure can be either valid or invalid, then the type representing the “valid” version should be distinct and separate.

For example, imagine you have a generic InputData type. Rather than passing it around and hoping it's valid, you can define a subtype — say, ValidatedInput — which represents data that has already passed all checks. The only way to obtain an instance of ValidatedInput is through a dedicated validation function or factory.

This creates a contract of validity:

ValidatedInput guarantees invariants such as non-null fields, correct formats, and logical consistency.
Any function that accepts ValidatedInput can trust that these preconditions are already satisfied.
If the data is not valid, the caller cannot construct the object — the compiler will prevent misuse.

This approach shifts responsibility:

From “every method should validate”
To “only the constructor (or factory) can validate — and once it does, the value is safe forever.”

It’s the same principle behind concepts like non-nullable references, refined types, or units of measure. But here, we’re applying it to domain logic: using the type system to separate raw input from trusted data.

By doing so, we eliminate both redundant validation and unsafe assumptions. We no longer ask, “Should I validate this again?” — because the type system enforces the answer.

Real-World Examples: Files, Access, and the Danger of Assumptions

To illustrate how this principle works in practice, let’s consider a common example: file access.

Imagine a function that takes a File object and is supposed to read from it. Simple enough — but what does the File object really represent? Is it:

A path on disk, regardless of whether it exists?
A file that has been checked to exist?
A file that is guaranteed to be readable?

If the type is just File, all of these interpretations are possible, and developers may start adding conditional logic like:

fun processFile(file: File) {
    if (file.exists() && file.canRead()) {
        // read file
    } else {
        // log or throw
    }
}

Once again, the function is claiming to handle any File, but actually assumes a subset of files that are already valid for reading. This leads to repeated checks, unclear responsibilities, and potentially missed edge cases.

Now consider an alternative: introduce a type ReadableFile that can only be created by a factory method like:

fun tryMakeReadable(file: File): ReadableFile?
This factory encapsulates all the necessary validation (existence, permissions, etc.). Any function that receives a ReadableFile can proceed without additional checks, because the precondition has been promoted to the type level.

This approach scales naturally to more complex systems:

A User that is already authenticated.
A Document that has passed schema validation.
A Request that has been rate-limited and sanitized.

Each of these becomes a type whose very existence guarantees a set of invariants, eliminating entire classes of bugs caused by misplaced trust.

Engineering Lessons and Takeaways

The problem of repeated or missing validation is not just a nuisance — it’s a sign that the system doesn’t express its assumptions clearly. When validity is implicit, every part of the code must remain paranoid, constantly checking and re-checking conditions that may or may not be satisfied.

By elevating validity to a type-level concern, we give ourselves a powerful tool:

Functions no longer need to perform defensive checks.
Invalid data is rejected at the boundary, not passed around inside.
The compiler enforces correctness by construction.

This design pattern is applicable across languages and paradigms. Whether implemented through sealed classes, wrapper types, smart constructors, or dependent types, the goal is the same: encode the program’s invariants in the types themselves.

And in doing so, we honor the Liskov Substitution Principle — not by remembering to follow it, but by making it impossible to break accidentally.

Ultimately, good software design is not just about correctness. It’s about making the right thing easy and the wrong thing hard. Using types to model validation is one of the most effective ways to achieve that goal.

👉 Check it out on GitHub