DEV Community: Raif Harik

I argued IoC was pointless in JavaScript, forgetting I'd published my own container to npm.

Raif Harik — Tue, 20 Oct 2026 18:12:05 +0000

Why I built ioc-manifest: convention-based DI codegen for TypeScript and Awilix.

Some weeks ago I had a job interview.

We were chatting away — this is the tech stack we use, and this lib and that lib, and we use Awilix for IoC.

"Really," I said. "You use IoC?"

Inversion of control. In JavaScript.

"Nobody uses IoC in JavaScript. What would you even use it for? You've got that delightful ES6 modules implementation that almost does some of what you wish it did. I mean, I get why you might want to use it. But nobody does. You'll be fighting every engineer you come across."

What a dunce, I thought.

"Yes, we use IoC, and every developer I know uses it. If they don't use a library they at least wire up a poor man's container."

What a dunce, he thought.

Well. That interview went really well.

When I started using Node about ten years ago I came from C#, where I'd used IoC heavily. In Node I found not just little appetite for it but open hostility — the very notion that JavaScript might have the same concerns and patterns as, say, any other language was contemptible. So I wrote my own container. Screw 'em. Eventually, once I finally accepted I was never going to win this me-against-the-whole-world battle, I quietly succumbed.

By the time I was sitting in that room I'd licked my wounds into well-worn calluses. But somewhere in my primordial brain I could still hear, or smell, the memory of why IoC was worth having in the first place. So when this guy told me he was using it, my ears perked up.

I looked up Awilix.

Hm. Not bad. Lets me use functions instead of classes ( don't get me started on classes in JS ) and basically wrap a module in a factory and feed it the dependencies.

Wait a minute!

That's what I wrote almost a decade ago! It was called dagon and it's still pulling eight downloads a week on npm.

Awilix is better than dagon no doubt. Mine was pretty naive. Errors surfaced at runtime, dependencies resolved by filename, magic strings abounded -- and nothing checked any of it, because there was nothing to check it with. I mean TypeScript existed but I didn't know what the hell it was back then.

Awilix has TypeScript. Sort of. It has types for its APIs. But the container itself is a bag of strings, and the graph inside it is invisible to the compiler. You still find out what's wrong by running the program and reading a stack trace. Which, to be fair, is what every container in this ecosystem does.

So I decided to give it a try.

It wasn't long before the old muscle memory started to kick in and the joy of design to interfaces and other patterns started to return. But one thing I just couldn't get past was writing the same dependency name over and over to configure it. And I soon started running into problems around packages in my mono-repo. Registrations split across packages, no way to express that one supplies what another demands — so you find out you’ve broken the contract when the app that composes them fails to boot.

One thing I really loved about StructureMap in C# was how it was configured mostly by convention with configuration only for the edge cases. Awilix has loadModules. But in C#, convention-based registration is safe because the consumer side is typed independently of the container. A constructor taking ILogger is checked by the compiler whether StructureMap wired it or I did. In TypeScript, a factory destructuring { logger } from a cradle has no type of its own — so convention-based loading means giving up the only check you had. You can have conventions or you can have types. Not both. Again things break at runtime not at design time.

It seemed to me that a lot of this and more could be handled with a quick codegen step. A lot of libraries require codegen these days e.g. graphql with ts, prisma. Adding one more especially if the payoff is really high seemed an easy decision. So I created what I considered an optimal configuration scenario. Largely stolen from StructureMap :).

I wanted modules to be as container-agnostic as possible, while still being discoverable, but I also needed to distinguish between what goes in a container and what doesn't. Adopting a configurable naming convention was the easiest and best solution for that. So I decided a declared function should look like this:

type AddUserDeps = {
  db: Database;
  logger: Logger;
};

export type AddUser = (user: NewUser) => Promise<void>;

export const build__addUser =
  ({ db, logger }: AddUserDeps): AddUser =>
  async (user) => {
    ...
  };

Here the build__ prefix is what marks a function as container-eligible. I started with just build, but I kept writing buildQuery and buildPath for things that had no business in a container. The double underscore made the distinction unambiguous — and visually obvious at a glance. You can configure it to whatever you like.

Classes work the same way. implements declares the contract, the constructor’s deps object declares the demands, and the codegen reads both. The convention is about what gets registered, not how you write it.

The beauty is that this is how I’d define the module anyway. You have to declare your inputs. You have to declare your outputs. The codegen reads both and builds the container from them. Nothing is declared twice. The type is the registration.

And here's the payoff:

type UserServiceDeps = {
  addUser: AddUser;
};

export type UserService = (input: SomeInput) => Promise<void>;

export const build__userService =
  ({ addUser }: UserServiceDeps): UserService =>
  async (input) => {
    ...
  };

addUser is wired. Not written into a registration, not added to a cradle interface. Just declared as the type that it is.

I also spent considerable effort on how errors are expressed. A cryptic error at runtime makes me crazy. Because we can accrue so much information from the AST walk while building the graph, the error messages can be very explicit.

[externals] Unsatisfied: nothing supplies "logger", which @apps/api expects the container to already have.
  key:       "logger"  demanded by @apps/api
  demanded:  Logger
  No composed manifest offers this key in its IocGeneratedCradle.
  Suggested fix: Register a factory for Logger under key "logger" in this app, or compose another manifest that supplies it.
  → docs: https://reharik.github.io/ioc-manifest/monorepo/composition#externals

And this error comes during the build, not at runtime. Missing dependencies, cyclic references, and lifetime violations are all caught and reported with the file, the line and the fix.

A runtime-only container can’t come close to this. It has keys and nothing else — no file, no line, no idea which package expected what. Furthermore, runtime errors only show up when they happen, one at a time. With in-depth build-time analysis you get all the errors up front whether they are exercised or not.

The build-time graph doesn't just catch things early, it makes the runtime errors legible too. If your code does make it to runtime with an issue:

[ioc] Cannot resolve dependency "readRepository".

Resolution chain:
Server (server) [src/server.ts]
  -> KoaServer (koaServer) [src/koaServer.ts]
    -> GraphQLServer (graphQLServer) [.../createGraphQLServer.ts]
      -> readRepository ✖ no registered implementation

So here I am, ten years later, having written the same library twice.

dagon walked a directory and named things after their files. It worked, for the most part, until it threw at startup with an error message that was barely comprehensible. I knew what I wanted — convention over configuration, modules that don’t know a container exists, functionality with a decent DX. I just didn't have the tools or the Node experience to really make it happen.

Many years later, knowing the language much better, I find that TypeScript’s AST knows what every module declares and what every module demands. ioc-manifest just reads it and hands Awilix a container it couldn’t have built for itself — one the compiler can see, and complain about, before anything runs.

It may not have been my finest hour or best interview, but I'm now happily back in the land of IOC.

npm install ioc-manifest

Your status enum lives in five files

Raif Harik — Thu, 13 Aug 2026 20:50:11 +0000

You need to add one value to a status. PENDING, AWAITING_PAYMENT, ACTIVE, SUSPENDED — and now ARCHIVED.

So you go looking for where statuses live. Here's what you find:

constants.ts — a frozen const object, ORDER_STATUS, screaming case.
types.ts — a union of string literals, written by someone else, with the same members in a different order.
orderService.ts — a switch with the literals inlined, because whoever wrote it didn't find either of the above.
migrations/0031_orders.ts — a CHECK constraint listing the values a third time, in SQL.
OrderFilter.tsx — a <select> with hardcoded <option> elements, and display labels — someone typed Awaiting payment by hand — that exist nowhere else in the codebase.

Five representations. None of them is the source of truth.

The problem isn't which of the five you pick. It's that there's no canonical place or shape for this kind of data, so the concept gets re-invented every time someone needs it, and none of the copies know about each other.

That hurts in three ways, and they get worse.

It's tedious. Adding ARCHIVED means touching all five, and nothing — not the compiler, not a test — will tell you when you've found four.

It's undiscoverable. Six months ago someone needed this same concept, searched for OrderStatus, found nothing, and added OrderState in a different file. Now there are six. Nobody knows. It'll surface as a bug in about a year.

Or alternatively you're the one adding it fresh. You know the concept doesn't exist yet. You also know that whichever form you pick, the next person won't find it, and you'll be back here. So you sit there for four minutes deciding between a const object and a union and an actual enum, aware the whole time that the decision doesn't matter and the discoverability does. That friction is small and constant, and it never stops, and it is entirely self-inflicted.

It's silently wrong. This is the big one.

The migration seeds rows as 'archived'. The union says 'ARCHIVED'. The filter compares them, matches nothing, and archived orders quietly stop appearing in the list. No error. No exception. No failing test.

Postgres is satisfied: the value passes the CHECK constraint, which was written in SQL by someone reading a different file. TypeScript is satisfied: the row was cast to OrderStatus on the way in, and a cast is a promise, not a check. Both halves of the system are internally consistent, they disagree with each other, and there is no layer whose job it is to notice.

That's not just a maintenance burden. It's a bug class — two independent declarations of the same truth, in two languages, that no tool compares.

The thing everyone writes

You've written this. I've written it in every codebase I've worked in:

export const ORDER_STATUS = {
  PENDING: "PENDING",
  AWAITING_PAYMENT: "AWAITING_PAYMENT",
  ACTIVE: "ACTIVE",
  SUSPENDED: "SUSPENDED",
} as const;

export type OrderStatus = (typeof ORDER_STATUS)[keyof typeof ORDER_STATUS];

It's a good trick. It gets you a value you can iterate and a type you can annotate with, from one declaration.

Then you keep going, and watch what it doesn't cover:

// Display labels: somewhere else entirely.
const STATUS_LABELS: Record<OrderStatus, string> = { ... };

// Dropdown options: a third shape, derived by hand.
const options = Object.values(ORDER_STATUS).map(v => ({
  value: v,
  label: STATUS_LABELS[v],
}));

// Parsing a string from the database: unchecked.
const status = row.status as OrderStatus;   // 👈 a lie, and it will bite

// Exhaustiveness: only if you remember the incantation.
default: {
  const _exhaustive: never = status;
  throw new Error(`unhandled: ${status}`);
}

So the const-object trick solved one of the five places. The labels, the options, the parse boundary, and the exhaustiveness check each grew their own file. You've replaced "five representations of the values" with "one representation of the values and four satellites that drift from it."

And the drift is worse than it looks. Add ARCHIVED and STATUS_LABELS fails to compile — good. But nobody chose that. Record<OrderStatus, string> just happens to be exhaustive by construction; the safety is an accident of how the type got written. The <select> doesn't fail. The as OrderStatus cast doesn't fail. The CHECK constraint doesn't fail.

So some of your satellites break loudly and some break silently, for reasons that have nothing to do with which ones matter — and you can't tell which is which by looking. Worse, the ones that break loudly give you false confidence about the ones that don't. You add a value, something turns red, you fix it, the build goes green, and you ship the bug anyway.

One declaration, and the satellites come with it

export type OrderStatus = Enumeration<typeof OrderStatus>;
export const OrderStatus = enumeration("OrderStatus", {
  input: ["pending", "awaitingPayment", "active", "suspended"],
});

The string 'OrderStatus' isn't redundant with the variable name. JavaScript has no reflection — a function can't know what it's being assigned to — and while that drives me absolutely insane, it's only half the reason. The real reason is that this string is the wire tag. It survives JSON. It's what lets a value that crossed a process boundary be recognized as an OrderStatus when it comes back, rather than as a string that happens to look like one.

The type alias looks circular and isn't. TypeScript resolves types and values in separate namespaces, so OrderStatus is legally both. That one line is what buys you the parameter annotation further down.

Those two lines produce three representations of the concept, all derived from the one you typed:

OrderStatus.awaitingPayment.key; // 'awaitingPayment'   — code: the name you reach for
OrderStatus.awaitingPayment.value; // 'AWAITING_PAYMENT'  — persistence: the column, the wire
OrderStatus.awaitingPayment.display; // 'Awaiting payment'  — human: the label, the dropdown

Both casing conventions are defaults, and both are overrideable for when a column or a label has to be something else.

Those three are exactly what got scattered across five files. The const object and the union hold the persistence form. The switch inlines it again. The migration writes it a third time, in SQL. The <select> holds the human form, typed out by hand. And the code form — the name you actually reach for — is whatever each file happened to call it.

Here's the part that should bother you: the three aren't independent. awaitingPayment → AWAITING_PAYMENT → Awaiting payment is a mechanical transformation. You could write it as a function in about four lines.

Nobody does. Instead, every developer who needs one of the forms types it out themselves, in a different file, from memory. The convention lives in everyone's head and in no code — so as far as the toolchain is concerned, the AWAITING_PAYMENT in the migration and the AWAITING_PAYMENT in the union are two unrelated string literals that happen to look alike. Nothing compares them.

That's 'archived' versus 'ARCHIVED' from the top of this post. Not a hard problem solved wrong. A trivial problem solved by hand, twice, by two people who never compared notes.

Here they're one member. You can't have one representation without the others, because there's nowhere else to put them.

Everything the const-object trick left on the floor is now on the enum itself. Same list, same order:

The <select> with hardcoded options and hand-derived labels becomes:

OrderStatus.toOptions();
// [{ value: 'AWAITING_PAYMENT', label: 'Awaiting payment' }, ...]

The cast at the database boundary is now:

OrderStatus.fromValue(row.status);

A cast is a promise. This is a check — it parses, and it rejects anything that isn't a member.

And the exhaustiveness incantation — the never assignment and the throw you have to remember to write — becomes a method on the member:

const banner = status.match({
  pending: () => "Waiting to be processed",
  awaitingPayment: () => "Payment not received",
  active: () => "In progress",
  suspended: () => "On hold",
});

The arms are keyed by the code representation — awaitingPayment, the name you reach for — not the wire value. Add archived to the enum and every match that doesn't handle it turns red until you add an arm. That's the same guarantee the never incantation gave you, except you don't write it, you can't forget it, and it returns a value instead of assigning into a mutable let.

And the CHECK constraint that disagreed in a different case: there is exactly one .value, produced by the enum. The migration and the filter can't disagree, because neither of them is holding its own copy of the string.

Because the type and the value share a name, you use it the way you'd use a real enum:

const describe = (status: OrderStatus) => status.display;

describe(OrderStatus.pending);

That's four satellites collapsed. But the thing that actually mattered is duller than any of it: this is now data with a shape, so it has somewhere to live.

/enums/OrderStatus.ts

One file. Named after the concept. The next person who needs an order status finds it in one search, in one shape, with the labels already attached — and never writes OrderState.

And adding ARCHIVED? You add 'archived' to the array. That's the change. No labels file to update, no <select> to audit, no migration to keep in sync, no cast to re-verify. The edit that used to take five files and a prayer takes one file and a typecheck.

None of this is novel. The casing convention was always mechanical, the labels were always derivable, and the concept always wanted one home. All that changed is that a thing you were doing by hand in five files is now done once, by code, where nothing can disagree with it.

The library does more — a member that goes out over the wire comes back as the same member. That's the next post.

Why I wrote it

The pattern isn't mine. "Smart enum" / "rich enum" has been written about for years, mostly by people working in C# and Java. I was introduced to the concept way back in the day by Jeremy Miller and the Los Techies crew — that's where I learned that an enum could carry behavior as well as data.

The JS and TypeScript writeups I've found are good at explaining why enum is a bad fit and what you'd want instead. Then they either stop at the const-object trick, which is where the drift starts, or they show a quick roll-your-own version that whets your appetite without getting you there. The real implementation, especially with all the TypeScript goodness, is a good deal harder to write. But once you've got it, it's still lightweight and easy to use.

My first implementation was in JS, long ago, and it was simple to write and easy to use. When TypeScript came along and the code had to get serious about what it was doing — that was a lift. I learned an insane amount about TypeScript while pulling my eyes out. I've been running it in production in a real application for months, which makes me the library's author and its most annoyed user. Every capability in it exists because the app needed it and the absence hurt. Dogfooding made it very clear what was necessary, what was silliness, and where there be dragons. Those stories are worth telling on their own, and I'll get to them.

But this is the flat version: one canonical, discoverable, behavior-carrying declaration per concept, instead of five representations and four satellites.

Full documentation: smart-enum docs

npm install @reharik/smart-enum

Next in this series: what happens when a smart enum crosses a serialization boundary and === quietly starts returning false.