Forem: Rex

TypeWire 0.1.0 — Explicit, Transparent DI for TypeScript

Rex — Mon, 21 Apr 2025 18:13:37 +0000

TL;DR: TypeWire is a small DI library for TypeScript — no decorators, no magic, just typed wires and explicit registration. Designed for clarity and composability as your system scales.

In recent posts, I’ve been writing about architectural clarity — how good boundaries come from assigning clear ownership and avoiding ambient behaviors. That doesn’t just apply to services or classes — it also applies to how we wire them together.
Constructors and factories are part of your system’s behavior. They may not drive core business logic directly, but they shape how that logic can be composed and reused.

When we manually stitch them together across files and modules, boundaries blur.
It’s not always obvious at first — but as the system grows, that blur often becomes expensive over time.

We already have solutions to this problem — DI frameworks and libraries. But many come with known challenges and friction in practice.

Given these known problems, TypeWire, is my attempt to experiment on
solution to the problem.

TypeWire is a small, transparent DI library for TypeScript — designed to formalize those boundaries.

🚀 TypeWire 0.1.0 is now live

📦 @typewirets/core
📦 @typewirets/inversify
📦 @typewirets/react
📝 Release Notes
📘 GitHub

Why Another DI library

Frankly, just for fun, but also to validate my hypothesis while having fun.

Most TypeScript DI systems borrow heavily from large enterprise-style frameworks. This often results in heavy decorator usage, with steep learning curve,
and difficulties in tracing actual implementations. These DI frameworks also creates very tight coupling to the framework itself.

None of them are usually the problem, if you're fully committed to the framework. For those who are looking for lightweight solution without wanting to tie oneself to a framework, or for those who are working with libraries that should not be tied into specific framework can be very challenging.

TypeWire attempts to address above issues:

Declarative TypeWire Definition:
- Required dependencies - or could be delegated further.
- A unique symbol representing the wire.
- A factory or constructor on how to instantiate an instance of any type.
Each wire exposes two key methods - getInstance and apply - that abstract container interactions
- Allows these TypeWire declarations to be used in compatible DI framework of choice (limited though)

These declarations shift ownership of construction and dependency resolution to each wire — rather than centralizing it in the container or framework.

Combined with explicit symbol registration, there’s no guessing, no tagging, and no inference via decorators. Just types and functions.

This makes DI feel like a natural modeling tool — not an abstract mechanism.

You get:

Explicit, self-contained registration
Clear boundaries between resolution, behavior, and configuration
Decoupling from framework-specific conventions

🛠 Example

Usual code example

import { typeWireOf, TypeWireContainer } from '@typewirets/core';

export interface UserService {
  getById(id: string): Promise<User | undefined>;
}

const userServiceWire = typeWireOf({
  token: 'UserService',
  async createWith() {
    const staticUsers: Record<string, User> = {};
    // or use class
    // the factory function clearly states what we are creating
    // We don't have to make this inline.
    return {
      async getById(id: string) {
        return staticUsers[id];
      },
    } satisfies UserService;
  },
});

const userControllerWire = typeWireOf({
  token: 'UserController',
  imports: {
    userService: userServiceWire,
  },
  createWith({ userService }) {
    return {
      async handle(req: express.Request, res: express.Response) {
        const user = await userService.getById(req.params.userId);
        if (!user) {
          res.status(404).end();
          return;
        }

        res.json(user);
      }
    }
  }
})

async function main() {
  const container = new TypeWireContainer();

  // loads all dependant wires as well
  await userControllerWire.apply(container);

  // more settings
  ...
  ///

  // Core business logic section
  const userService = await userService.getInstance(container);
  const user = await userService.getById('admin');

  const userController = await userControllerWire.getInstance(container);
  // ... etc
}

Override someone else's wire

import { typeWireOf, TypeWireContainer, typeWireGroupOf } from '@typewirets/core';

// from the example above

async function main2() {
  const container = new TypeWireContainer();

  const wireGroup = typeWireGroupOf([
    userControllerWire,
    // overrides while keeping the original type token
    userServiceWire.withCreator((ctx) => {
      // returned value must match type of the original wire.
      return {
        async getById(id: string): Promise<User | undefined> {
           throw Error("UserService is not in a good vibe");
        }
      };
    });
  ])

  // loads all dependant wires as well await wireGroup.apply(container);

  // more settings
  ...
  ///

  // Core business logic section
  const userService = await userService.getInstance(container);
  const user = await userService.getById('admin');

  const userController = await userControllerWire.getInstance(container);
  // ... etc
}

Testing

describe('Test Controller', () => {
   test("should use mock service", () => {
     const container = new TypeWireContainer();
     const wireGroup = typeWireGroupOf([
        userControllerWire,
        userServiceWire.withCreator((ctx) => {
          // explicit mocking!!!
          // no more dancing with jest.mock or vi.mock with complicated hoisting.
          return {
            async getById(id: string): Promise<User | undefined> {
              if (id === 'knownValue') {
                return someExpectedUser
              }

              throw Error("Not in a good test vibe")
            }
          };
        });
     ]);


      // loads all dependant wires as well
      await wireGroup.apply(container);

      // do the test
   });
});

You can use classes, factory functions, or async constructors — TypeWire doesn’t impose a pattern. It just helps formalize the glue once your system has enough moving parts that manual wiring becomes a bottleneck.

🔍 Related Articles

TypeWire builds on themes from my recent architecture series:

Clarity in Architecture: Not OOP vs FP https://dev.to/myungsunrex/clarity-in-architecture-not-oop-vs-fp-2mhf
Constructing Boundaries (Not Just Using Classes) https://dev.to/myungsunrex/part-2-constructing-boundaries-not-just-using-classes-5gh9
Internal State: Not Evil, Just Misplaced https://dev.to/myungsunrex/internal-state-not-evil-just-misplaced-20dh
Dependency Injection Without Magic https://dev.to/myungsunrex/dependency-injection-without-magic-39k4
Functional Principles Still Matter https://dev.to/myungsunrex/functional-principles-still-matter-2onh

If you've ever struggled with messy construction logic, blurry service boundaries, or DI that makes your app harder to reason about — this might help.

⚠️ Still Early — But Stable

This is version 0.1.0. The container system and resolution APIs are stable, and real-world ready (I think 😉).

💬 Feedback Welcome

If you’re building something in TypeScript — especially in a monorepo or layered architecture — and want to keep things transparent as they scale, try it out.

Would love to hear thoughts, issues, or improvements from others thinking about these problems too.

http://github.com/typewirets/typewirets/

Functional Principles Still Matter

Rex — Thu, 17 Apr 2025 22:06:43 +0000

There’s a wide range of opinions when it comes to functional principles. Out of the many points people debate, I tend to value the following:

Declarativeness
Immutability
Composition
Purity

However, humans perceive the real world through side effects and imperative steps. Describing real-world problems purely through functional abstractions can be challenging — or at least requires a significant shift in perspective.

Building a world full of functional declarativeness often demands multiple layers of indirection, which may not always be intuitive or practical.

Consider some common realities:

Configuration pulled from the environment
APIs that fail
User input that mutates internal state
Business logic that depends on time, randomness, or context

Despite these constraints, certain problems are better described — and understood — when a few functional principles are applied.

So rather than force the world to fit a functional model, I’ve landed on a middle ground.

I primarily strive for predictability and composability in my systems, and I’ll use whatever principles — functional or otherwise — that help me get there.

And functional principles do help me get there.

Purity and Composition

As we briefly touched on earlier, it's nearly impossible — and not particularly practical — to achieve 100% purity in most functions. But we can still define boundaries such that the behaviors feel pure, even if the environment around them is not.

Let’s start with a simple validator:

function validate(
  schemaService: SchemaService, 
  schemaId: string, 
  value: unknown,
): void {
  // schemaService invokes side effects, so the function is not pure
}

This function isn’t pure — it depends on schemaService, which might fetch or mutate data behind the scenes. But just like in mathematics, we can often reason about complex systems by introducing constraints.

If we constrain the behavior of schemaService — say, through interface boundaries, mocks, or scoped inputs — then validate() becomes more predictable. That’s often good enough.

In testing, we already do this implicitly: we mock schemaService to make the function behave in a controlled way.

But now consider composability:

Use in Another Function

function validateSchemaAndDoMore(metadata: Map<string, string>) {
  validate(
    schemaService, // where should it come from?
    metadata["schemaId"],
    metadata["value"],
  );
}

When using validate() elsewhere, we need to provide schemaService. In practice, that leaves us with a few choices:

Pass dependencies down through injection chains
Import them directly as singletons (tight coupling)
Pass a container or context to retrieve dependencies

Extend the Function to Include Notification

Here’s two ways to compose validate() with a notification system:

Option 1: Fully Injected

function validateAndNotify(
  notificationService: NotificationService,
  schemaService: SchemaService, 
  schemaId: string, 
  value: unknown,
) {
  try {
    validate(schemaService, schemaId, value);
    notificationService.ok();
  } catch (err: unknown) {
    notificationService.err(err);
  }
}

Option 2: Fully Imported

import schemaService from './schema-service';
import notificationService from './notification-service';

function validateAndNotify(
  schemaId: string, 
  value: unknown,
) {
  try {
    validate(schemaService, schemaId, value);
    notificationService.ok();
  } catch (err: unknown) {
    notificationService.err(err);
  }
}

Each has trade-offs:

One pushes dependencies through the call chain (verbose, but explicit)
The other hides them behind module imports (convenient, but tightly coupled)

This is where objects or classes come into play — not because we want to model the world with objects, but because they help structure the environment around behaviors.


interface Schema {
  validate(value: unknown): void;
}

function KnownSchemaValidator(worldAroundMe: any) {
  const schemaId = "knownSchemaId";
  const schemaService = worldAroundMe.schemaService;

  return {
    validate(value: unknown) {
      // validation logic here
    }
  };
}

function CoreBusinessValidator(worldAroundMe: any) {
  const validator = KnownSchemaValidator(worldAroundMe);
  const notificationService = worldAroundMe.notificationService;

  return {
    validate(value: unknown) {
      // core business validation + notification
    }
  };
}

By injecting “the world around me,” we isolate external dependencies while preserving pure-ish behavior contracts.
In other words: we separate what we control (function parameters) from what we manage (injected services), creating the illusion of purity within well-defined constraints.
Of course, if a function can be truly pure — that’s ideal. But wrapping it in a factory or an object to inject external context isn’t about over-engineering for every possible future.
It’s a small, intentional step that makes extension easier later.
And if my assumptions turn out wrong, I can revisit the boundary and rethink the contract — no sunk cost, just an adaptation.
As long as we maintain good boundaries and clear contracts, we can reason about and test these functions as if they were pure — even when they’re not.

I’ve found far more success in structuring for purity than in chasing purity for its own sake.

This mindset applies across the board — whether I’m shaping business rules, transforming data, or designing system behaviors.

Immutability

Immutability is a great tool to use to improve predictability.

If a value is declared as immutable and never changes, great — that’s easy to reason about.
But if a value is mutable, and that’s clearly declared and understood — that’s fine too.

The real problem isn’t mutation — it’s unexpected mutation.

Some languages help you with this through the type system (like TypeScript, Rust, or Elm).
Others, like JavaScript or Python, leave it to convention and discipline.

Either way, the goal is the same:

Declare your intent.
Stick to that intent.
The intent itself is a contract.
That’s usually good enough.

Build Behavior from Small Pieces

Functional thinking isn’t just about functions — it’s about how we structure systems.

I’ve found the most success in systems that are composed from focused units — each owning a clear behavior or decision. This works better than trying to centralize everything into one orchestrator or “God class.”

Some patterns I lean on:

Keep orchestration shallow — let domain logic live in reusable units
Group behavior by cohesion, not inheritance
Compose systems by layering contracts, not hard-coded call chains

It’s about making change easier — and more localized — when the system grows.

Functional Principles Aren’t the Opposite of OOP

Functional and object-oriented principles can (and often should) coexist.

Use classes to own lifecycle and boundaries
Use functions to express clear, testable logic
Use DI to wire them together without magic

In the end, all of this is in service of one thing: clarity.

Conclusion

Functional programming offers some great tools — but the value comes from how we apply them, not whether we follow the paradigm perfectly.

Purity gives us control over behavior.
Immutability gives us clarity over data.
Composition gives us structure and scalability.

Code can be structured in a way that achieves all of the above — even if, underneath, it’s not written in a purely functional style.

With clear boundaries and well-defined contracts, systems become easier to understand, test, and extend.

And whether I’m working in a class-heavy codebase or a function-first one, those principles still apply.

🧩 Dependency Injection Without Magic

Rex — Wed, 16 Apr 2025 19:26:19 +0000

Dependency Injection has a reputation problem. Between bloated frameworks and decorator-heavy configs, it often feels like “too much magic.”

But at its core, DI is simple: It’s simply the act of injecting dependencies via a factory or constructor. It can be done manually, or with some library or framework support. At the end of the day, it’s an essential technique for creating clear boundaries between components.

For example, following code is using DI:

function createUserService(userApi: UserAPIClient) {
  return {
    async getUserById(id: string): Promise<User | undefined> {
      try {
        return userApi.fetch(`/users/${id}`);
      } catch (err: unknown) {
        if (err.name === 'NotFound') {
          return;
        }

        throw err;
      }
    }
  }
}

// The second example also uses DI via function parameters — but it doesn’t encapsulate behavior, making it slightly harder to extend.
// slightly more diffcult to extend
async function getUserById(userApi: UserAPIClient, id: string): Promise<User | undefined> {
  try { 
    return userApi.fetch(`/users/${id}`);
  } catch (err: unknown) {
    if (err.name === 'NotFound') {
      return;
    }

    throw err;
  }
}

While DI is a simple technique for drawing clear boundaries, I’ve found it helpful to separate its use for shared singleton behavior vs context-specific behavior.

Used thoughtfully, DI helps you write code that’s:

Easy to test
Easy to understand
Easy to refactor

The Role of DI: Composing Services, Not Context

Dependency Injection shines when handling long-lived, shared, and reusable logic:

Logging
Configuration
API clients
Business rules

While DI can technically be used for things like per-request data, frontend context, or React hooks — I’ve found a few constraints that work consistently well in practice:

⚙️ Scoped behaviors are better passed as function parameters to long-lived services.
🧱 Avoid stateful scoped behavior when possible — represent it as dry data.
🧩 If unavoidable, contain scoped state behind clear behavioral boundaries.

When using a DI framework, I avoid injecting scoped or contextual values into factory functions or constructors. Instead:

I deliberately keep DI focused on constructing long-lived behavioral components,
and pass context-specific values as arguments to their methods —
even if that means wiring things manually.

This separation of concerns keeps my boundaries clean, and avoids ambiguity about where state lives or how it's scoped.

Structured Side Effects

Apps have side effects. They need to:

Log things
Call APIs
Persist data

These are all side effects — and they’re essential. Trying to remove them entirely is impractical. But what we can do is structure them intentionally.

That’s where DI fits in:

Dependency Injection doesn’t eliminate side effects — it isolates them.
It gives them clear entry points, makes them swappable, and keeps them from leaking into pure logic.

This isn't in conflict with functional principles — it's complementary.

Functional core, imperative shell — and DI lives in the shell.

By pushing side-effectful behavior to the edges of your system, and injecting it explicitly into behavioral units, you get:

More predictable flows
Cleaner separation of concerns
Easier testability without mocks or global stubbing
Even if you’re not writing "pure functional code," DI helps keep impurity structured, not scattered.

DI and Testing: You Get Control

Once you’ve drawn clear boundaries between behavior and side effects, testing becomes a lot easier.

You can replace side-effectful parts with test doubles.
You can isolate core behavior without mocks or globals.
You can preload or stub behavior deterministically.

The key is knowing where the impurity lives — and keeping it out of the core logic.

It’s not about mocking everything — it’s about not needing to mock most things (if not all).

Internal State: Not Evil, Just Misplaced

Rex — Tue, 15 Apr 2025 18:48:21 +0000

State is everywhere. And that’s not a problem — unless you pretend it isn’t.

In real-world systems, especially those that span multiple scopes like backend applications, state is inevitable. The key isn’t to eliminate it — it’s to manage it deliberately.

While building a new dependency injection library for TypeScript called TypeWire, I applied the same architectural principles I’ve long followed — particularly around clarity in boundaries and ownership of state.

This article shares lessons learned from that experience, using the internal evolution of TypeWire to illustrate how state can be structured, isolated, and owned with confidence — without becoming ambient or unpredictable.

Internal State in Practice

I’ve been crafting a project called TypeWire, a DI library for TypeScript, and along the way I’ve learned a lot about designing internal state with strong boundaries.

TypeWire started with a simple container class that handled everything — bindings, singleton caches, and resolution state — all internally.

class TypeWireContainer implements ResolutionContext, BindingContext {
  private readonly bindings = new Map<symbol, TypeWire<unknown>>();
  private readonly singletons = new Map<symbol, unknown>();
  private readonly resolutions = new Map<symbol, Promise<unknown>>();

  async get<T>(typeSymbol: TypeSymbol<T>): Promise<T> {
    // Resolution logic lived here
  }
}

This worked until I began hitting concurrency issues during parallel resolutions, particularly false positives in the circular dependency monitor. This pushed me toward isolating resolution per request.

To fix that, I created a ScopedResolutionContext — an ephemeral context that owns each resolution lifecycle:

class ScopedResolutionContext implements ResolutionContext {
  constructor(
    private readonly bindings: Map<symbol, TypeWire<unknown>>,
    private readonly singletons: Map<symbol, unknown>,
    private readonly resolutionMonitor: ResolutionMonitor,
  ) {}
}

This made things easier to reason about and brought clear ownership to resolution-time behavior. But resolution-specific mutable state still lived in this class.

So I extracted that too — into ResolutionState, whose sole job is to track in-flight data during resolution.

class ResolutionState {
  readonly resolutions = new Map<symbol, Promise<unknown>>();
}

This gave me three clear layers:

TypeWireContainer: orchestrates the lifecycle
ScopedResolutionContext: owns per-resolution behavior
ResolutionState: holds mutable state, tightly scoped and invisible elsewhere
These decisions were made iteratively — each step clarified boundaries and reduced ambiguity
State can be refined gradually
Ownership boundaries can evolve toward clarity
Internal structure matters as much as public API
A well-abstracted public API makes this evolution possible — since behavior remains stable while internals improve

Scoped State and Behavioral Boundaries

Short-lived or request-bound state can be tricky to manage — especially when it spreads into shared objects or global modules.

In my own work, I try to construct state on demand and ensure it’s owned by a tightly scoped boundary.

In the same system, transient resolution data — like in-flight dependency graphs — is encapsulated inside a ResolutionState class. This class lives only during resolution, and is owned by a ScopedResolutionContext wrapper:

class ScopedResolutionContext {
  constructor(private readonly resolutionState: ResolutionState, ...) {}
}

This pattern reflects a broader principle:

Internal state isn't just hidden — it's delegated further to the layer that truly owns its lifecycle
Mutability is minimized and localized
Behavior is centralized around one interface

When I work with contextual and temporary state, I try to give it a dedicated layer — and let behavior encapsulate its usage.

Long-Lived vs Contextual State

Some state lives for the lifecycle of the application (e.g., configuration caches, connection pools). Others live per request, per resolution, or per session.

Issues can emerge when long-lived objects inadvertently hold onto short-lived context.

In our example, singleton values are stored only once and safely. Meanwhile, contextual logic — like what’s needed during one resolution flow — is dynamically built per call and discarded afterward.

The structure makes ownership obvious:

Global state lives in a global container
Resolution-specific state lives inside ResolutionState
Nothing is ambient, and nothing crosses boundaries without intent

Preventing Scope Bleed

Architecture fails when context-sensitive state (like user identity or feature flags) leaks into shared objects.

Even with a container, this can happen:

A singleton accesses a value that changes every request
Transient logic is accidentally shared

What helps in these situations isn't a tool — it’s careful structure:

Pass context explicitly
Use factory functions for delayed evaluation
Avoid injecting context into globally-shared constructs

The container pattern can help, but only if the boundaries are respected.

Encapsulation and Ownership

State is not the enemy. Unowned state is.

What makes the TypeWire container safe is not the lack of state — it’s the clarity of ownership:

The container owns global state
The resolution context owns transient state
No one else touches either

In your own system:

Choose who owns the cache
Decide where request-scoped values live
Expose behavior — not state

If a Map or a flag is being read and written by multiple layers, I consider it no longer internal. That’s when I try to wrap it, abstract it, and assign clear ownership.

Reflection: Does This Cover It?

Let’s recap what good internal state management looks like — and whether our example matches up:

Principle	Reflected in TypeWire?
Scoped state is owned	✅ ScopedResolutionContext + ResolutionState
Long-lived state is isolated	✅ Singletons live in the container only
Nothing is ambient or implicit	✅ No global context injection
Access is through behavior	✅ All state hidden behind `get`, `bind`
Mutable state is not shared	✅ Encapsulated in internal maps
Contextual resolution is explicit	✅ Built per-call, never reused

Even internal constructs like ResolutionState are a reminder that internal state can benefit from layered ownership — and I’ve found that layering it often helps clarify intent.

Conclusion

State isn’t evil. But pretending your system doesn’t have any — or letting it sprawl uncontrolled — is.

In TypeWire, we embraced internal state:

Singleton caches exist — but behind a behavioral interface
Transient resolution is scoped — not ambient
Contextual state is passed or constructed — never injected blindly

This wasn’t solved all at once. These boundaries — and the state ownership behind them — were clarified over time. Each change made the next one easier, precisely because earlier decisions respected separation of concerns.

When internal state is well-scoped and behaviorally owned, it enables iterative improvements without ripple effects.

The result is a system that uses state effectively, safely, and transparently.

And that’s the goal for any architecture: not to be stateless, but to be clear about where state lives, who owns it, and what it supports.

Part 2 – Constructing Boundaries (Not Just Using Classes)

Rex — Thu, 10 Apr 2025 17:18:13 +0000

The debate over classes vs functions is one of the internet's favorite distractions. But in practice, the real question isn’t “OOP vs FP” — it’s “How do we define and construct clear boundaries around behavior and dependencies?”

This isn’t a debate about keywords — it’s a conversation about intentional construction.

🧱 Constructed Boundaries > Singleton Modules

I often see patterns where modules default-export ambient objects:

// logger.ts
export const logger = {
  log: (msg: string) => console.log(msg),
};

As I’ve worked in larger-scale codebases, I tend to avoid this approach. Instead, I prefer to define a constructor — either a function or class — as a way to defer construction and inject dependencies.

This style allows clearer boundaries around configuration and collaborators, leading to more testable and maintainable systems.

🔁 Composable Construction

Let’s start with a simple, practical example of dependency injection — a logger that receives configuration as a parameter, not from a global module or static value.

import { z } from "zod";

export const LoggerConfigSchema = z.object({
  prefix: z.string(),
  level: z.number().optional(),
});

export type LoggerConfig = z.infer<typeof LoggerConfigSchema>;


export const LogLevelDebug = 0;
export const LogLevelInfo = 1;
export const LogLevelWarn = 2;
export const LogLevelError = 3;

Now, here are two ways to define a logger that consumes this config:

Both of the following examples define an explicit, testable, dependency-injected logger — one with a class, one with a function.

Class-Based Logger

class ConsoleLogger {
  constructor(private config: LoggerConfig) {}

  #shouldLog(level: LogLevel): boolean {
    if (this.config.level === undefined) {
      return LogLevelInfo >= level;
    }
    return this.config.level >= level;
  }

  #format(level: string, message: string): string {
    return `[${this.config.prefix}] ${level.toUpperCase()}: ${message}`;
  }

  log(msg: string) {
    if (this.#shouldLog(LogLevelInfo)) {
      console.log(this.#format('log', msg));
    }
  }

  error(msg: string) {
    if (this.#shouldLog(LogLevelError)) {
      console.error(this.#format('error', msg));
    }
  }

  withContext(ctx: string) {
    return new ConsoleLogger({
      ...this.config,
      prefix: `${this.config.prefix}:${ctx}`,
    });
  }
}

Factory-Based Logger

function createLogger(config: LoggerConfig) {
  function shouldLog(level: LogLevel): boolean {
    return (config.level ?? LogLevelInfo) >= level;
  }

  function format(level: string, msg: string): string {
    return `[${config.prefix}] ${level.toUpperCase()}: ${msg}`;
  }

  return {
    log(msg: string) {
      if (shouldLog(LogLevelInfo)) {
        console.log(format('log', msg));
      }
    },
    error(msg: string) {
      if (shouldLog(LogLevelError)) {
        console.error(format('error', msg));
      }
    },
    withContext(ctx: string) {
      return createLogger({
        ...config,
        prefix: `${config.prefix}:${ctx}`,
      });
    },
  };
}

Why It Matters

Both are great — because both:

Are constructed explicitly
Accept config and collaborators
Expose a clean, testable public API
Allow the consumer to decide whether the instance should be singleton, transient, or context-bound
Enable environment-specific wiring of dependencies rather than hardwiring them through static linkage

This flexibility is especially valuable in testing and modular architectures. And despite what it might look like at a glance — setting up these patterns doesn’t take much longer than writing the static version.

In fact, many engineers agree with the idea of composition and clean separation — yet we often spend more time debating whether it’s too much boilerplate than it would take to actually implement it. Setting up patterns like these — a simple constructor, an injectable utility, a boundary-aware service — typically takes no more than 5–10 minutes each, and even less as you get more fluent with the pattern. This isn't extra ceremony; it's optionality you can afford. It's a small investment that pays off in flexibility, clarity, and ease of change — especially as your system grows.

🧩 And while only one of them uses the class keyword, both are conceptually defining a class. The presence of new or prototype isn’t what matters. What matters is the boundary — and whether you construct it cleanly.

Personally, I prefer using class for most of my production code. I find it helps clearly separate dependencies, internal state, and external behavior. It also allows me to group private helpers in a natural way, and IDEs tend to provide better support — from navigation to inline documentation — when using classes.

Now let’s revisit the idea of configuration itself being injected — not globally loaded.

// config.ts
export class ConfigService {
  constructor(private readonly record: Record<string, any>) {}

  private getAnyValue(keys: string[]): any | undefined {
    let cur: any | undefined = this.record;
    const keySize = keys.length;
    for (let idx = 0; idx < keySize; idx++) {
      if (Array.isArray(cur)) {
        if (idx < keySize - 1) {
          return;
        }
      }

      if (typeof cur === "object") {
        const key = keys[idx] as string;
        cur = cur[key];
      }
    }
    return cur;
  }

  get<T>(key: string): T {
    if (!key) throw Error("empty key is not allowed");
    return this.getAnyValue(key.split(".")) as T;
  }

  getSlice<T>(key: string): T[] {
    if (!key) throw Error("empty key is not allowed");
    return this.getAnyValue(key.split(".")) as T[];
  }
}

// config-loader.jsonc.ts
export async function loadJsoncConfig(): Promise<Record<string, any>> {
  const configPath = path.join(process.cwd(), "config.jsonc");
  // This could also be injected. We're leaving it hardcoded for this example to keep the focus on
  // demonstrating how different parts can be composed and swapped later.
  const configContent = await fs.readFile(configPath, "utf-8");
  return JSONC.parse(configContent) as Record<string, any>;
}

Finally, here’s how we wire that config service into our logger:

async function main() {
  const rawConfig = await loadJsoncConfig();
  const configService = new ConfigService(rawConfig);
  // This separation makes it easy to swap different file formats or config loading mechanisms —
  // whether it's JSON, env vars, remote endpoints, or CLI flags.
  const rawLoggerConfig = configService.get("logger");
  const loggerConfig = LoggerConfigSchema.parse(rawLoggerConfig);

  const logger = new ConsoleLogger(loggerConfig);


  // continue application setup...
  // e.g., pass logger into your server, router, or DI container
}

This highlights the pattern: you can defer construction, inject dependencies, and compose behavior cleanly — without relying on global state or static linkage.

This isn’t just a pattern for enterprise-scale systems. Even in small prototypes, defining boundaries early makes it easier to stub things, swap implementations, or integrate with evolving environments. The upfront cost is low — and the downstream flexibility is real.

Here’s a quick comparison of the two approaches:

Pattern	Characteristics	Pros	Cons
Singleton / Ambient Module	Shared instance via global import	Simple, fast for small projects	Hard to test, inflexible
Constructed Component	Built via constructor or factory, passed explicitly	Composable, testable, modular — even in prototypes	Slightly more setup upfront (usually 5–10 mins max, or instance if you have a good vibe😉)

☕ Java & Go Comparison: You're Already Doing This

Before we dive into the structured, interface-based versions, it’s worth noting that Java and Go also have ambient-style patterns — the equivalent of a default-exported singleton in JavaScript:

Java – Static Logger

public class StaticLogger {
    public static void log(String msg) {
        System.out.println(msg);
    }
}

Go – Package-Level Function

package logger

import "fmt"

func Log(msg string) {
    fmt.Println(msg)
}

These work for small programs, but they tend to leak dependencies and make configuration or testing harder — much like ambient modules in JavaScript.

If you're writing Java, you're already familiar with this pattern:

public interface Logger {
    void log(String msg);
    Logger withContext(String ctx);
}

public class ConsoleLogger implements Logger {
    private final String prefix;

    public ConsoleLogger(String prefix) {
        this.prefix = prefix;
    }

    public void log(String msg) {
        System.out.println("[" + prefix + "] " + msg);
    }

    public Logger withContext(String ctx) {
        return new ConsoleLogger(prefix + ":" + ctx);
    }
}

In Go, you'd write something very similar:

type Logger interface {
    Log(msg string)
    WithContext(ctx string) Logger
}

type ConsoleLogger struct {
    Prefix string
}

func (l *ConsoleLogger) Log(msg string) {
    fmt.Printf("[%s] %s\n", l.Prefix, msg)
}

func (l *ConsoleLogger) WithContext(ctx string) Logger {
    return ConsoleLogger{Prefix: l.Prefix + ":" + ctx}
}

In both cases, you're constructing with dependencies, and explicitly wiring in behavior. You avoid ambient state and expose a small surface area for consumers.

You never default-export a global Logger instance in Java or Go. You construct, inject, and isolate. That’s the same idea we’re advocating here — just with different syntax.

🚪 A Word on Object-Oriented Discipline

As complexity grows, classes can offer some ergonomic benefits:

Grouping behavior and helpers using private or # methods
Better IDE discoverability and navigation
Easier organization of lifecycle-bound internal state

However, it’s important not to over-apply OOP conventions. I generally avoid subclassing and prefer composition over inheritance — not because inheritance is inherently wrong, but because it often introduces tight coupling and fragile hierarchies. When behavior needs to be shared, I favor helpers, delegates, or injected collaborators.

Likewise, I avoid protected methods. I find it cleaner to stick with public and private, keeping the object interface clear and the internals encapsulated.

The takeaway here isn’t that classes win — it’s that clarity wins. Whether you’re using class syntax or a factory function, the important part is that you’re being deliberate about boundaries and dependencies.

And once again, the key isn't the class keyword — it's the pattern of construction.

🧭 Conclusion: Construct, Don’t Just Declare

Use a class. Use a factory. Use a struct in Go or a POJO in Java.

The real question is:

Are you constructing your boundaries, or leaking them via ambient state?

That’s what makes your codebase adaptable — not the presence of class, but the presence of intention. (Or struct, if you're using Go. Or table, if you're writing Lua 😉)

Start small. Inject later. Boundaries give you leverage.

This isn’t about trying to predict every possible future feature — it’s about shaping your code so that the behavior you define is easily composable, and composed behaviors are much easier to reason about. There’s a meaningful difference between designing for flexibility and overengineering for speculation.

Clarity in Architecture: Not OOP vs FP

Rex — Wed, 09 Apr 2025 17:15:56 +0000

Clarity in Architecture: Not OOP vs FP

As a polyglot full stack engineer who's worked across both frontend and backend — in Java, Kotlin, Python, Go, JavaScript, TypeScript, Ruby, Lua, and PHP — I’ve worked through both fully object-oriented and fully functional phases in my career — and I’ve found that architecture debates often miss the real problem. The tension isn’t between paradigms. It’s between clarity and ambiguity. Too often, discussions get stuck in ideological traps — OOP means classes, DI is bad, FP isn’t practical, SOLID is sacred — or on the other end of the spectrum, some advocate for having no structure at all. These positions end up dominating the conversation instead of leading to a productive exchange.

The best systems I built — or helped evolve — weren’t purely object-oriented or strictly functional. They were clear. Their boundaries made sense. And once those boundaries were in place, it became much easier to reason about the system, understand how everything fit together, and extend it without fear of unexpected consequences.

This first article kicks off a series that doesn’t argue for a paradigm — it argues for architectural clarity. It’s about how we reason through systems, how we approach problems, and how we make structural decisions that help code grow cleanly. I’m not offering a universal formula — just sharing patterns and principles that have consistently helped me evolve real systems with less friction and more confidence.

The Real Question: Where Does This Go?

Forget OOP vs FP — or any single paradigm. What I kept running into was the difficulty of seeing the big picture when small decisions piled up. The real challenge is simplifying the system enough to reason about it clearly — and that often starts with asking:

Where does this code belong?

A factory function? A class? A context object? A singleton? A reducer?

When we make the wrong call, it spreads ambiguity: unclear ownership, unpredictable effects, and brittle testability. When we get it right, the system flows.

So instead of taking sides in OOP vs FP, this series focuses on practical boundaries:

When does a class help?
When is internal state okay?
What belongs in dependency injection — and what doesn’t?
How do you keep functional principles in an effectful system?

Let’s reframe the discussion.

Classes for Behavior

The word “class” triggers a lot of baggage — inheritance, over-engineering, Java boilerplate. But at its core, a class (or in Go, a struct paired with interfaces) is just a way to encapsulate behavior with shared internal logic. I emphasize composition over inheritance — the value of classes comes not from hierarchies, but from the ability to clearly group related behavior.

Use a class when:

You have multiple methods that coordinate shared state or logic
You need a clear lifecycle or ownership boundary
You want to separate dependency construction from behavior

Avoid it when:

You’re just grouping utilities or data
There’s no internal cohesion
You only need a couple of flat methods
You have persistent data that belongs in a database, API, or external system

Classes make it easy to separate the act of wiring dependencies (in the constructor) from the internal business logic (in the methods).

Personally, I avoid storing long-lived data in classes. Instead, I treat them as coordinators — not sources of truth. When I need to persist data like user info or logs, I reach for a proper database, API, or storage layer.

I’m more interested in how classes compose than how they inherit — and I often pair them with interfaces to keep things flexible. We’ll unpack that further in the next part of the series.

Internal State: Not Evil, Just Misplaced

Functional programming taught us to fear state. But the truth is, state is fine — when it’s owned.

The key is cohesion. State should live in objects that:

Have a clear lifecycle
Own their behavior
Don’t leak into the rest of the system
Are managing ephemeral data, not persistent records

In game development, for example, many objects manage both internal state and behavior tied to a well-defined lifecycle — a natural fit for class-based encapsulation.

Ephemeral or short-lived data belongs inside classes that directly control that lifecycle. Long-lived or persistent data should reside in a database, cache, or external API. Classes can read and write that data, but shouldn’t try to own or retain it.

Contextual values — like session data, request scope, or frontend state — are also better constructed where they’re needed. They’re often tied to a specific user, time, or flow, and don’t belong in global DI containers. Treating them as contextual inputs keeps the boundaries clean and avoids accidental state leaks.

We’ll dive into practical examples of these patterns in the next part of the series.

Dependency Injection Should Be Explicit

Some might argue that global singletons are fine for things like config files, loggers, or telemetry clients. After all, they’re used everywhere and often initialized once. But in practice, they’re rarely as simple or harmless as they seem.

These so-called singletons almost always involve side effects:

Config often pulls from dynamic environments or remote sources.
Logging requires runtime setup, formatting, and transports.
Feature flags often start as a simple in-memory key-value store, but over time evolve into complex rule engines that evaluate conditions dynamically — sometimes even requiring server-side calls.
Telemetry clients rely on side-loaded credentials and context.

Wiring dependencies manually — whether via DI frameworks or localized injection — makes them explicit and traceable. You can see what’s being used, where, and why. This isn’t about evangelizing any one tool — it’s about reinforcing clarity and testability through visibility.

Dependency Injection (DI) tends to provoke strong reactions — it's either misused as a magic context grab-bag, or religiously avoided altogether. But when used intentionally, DI gives you a system-wide service map, not an ambient variable soup.

Use DI for:

Long-lived shared services (Logger, DB, API clients)
Config or feature flags
Composable business logic

Avoid DI for:

Anything contextual (Session data, request-specific data)

A good way to think about DI is as a system-wide service map — not a place to store request- or user-specific context.

The rule of thumb: inject services, construct context.

Functional Principles Still Matter

The best systems I worked on still lean heavily on functional ideas:

Immutable definitions
Composability
Strong typing
Isolation of effects

But real-world applications need side effects — logging, config loading, HTTP calls, and more. DI and OOP give you structure around those effects without making the system impure everywhere.

The goal isn’t functional purity — it’s having clear, controlled side effects with minimal confusion about where they happen and why.

Wrapping Up

This series is about clarity in architecture — not purity, not paradigm loyalty. If you’ve ever felt unsure where a piece of logic belongs, or struggled to keep code testable and understandable as it grows, this series is for you.

Next up: we’ll look deeper at when to use a class, when not to, and how to make the boundary between dependencies and behavior sharp.