Dependency Injection in Wheels 4.0: services.cfm, Scopes, and Auto-Wiring

[bpamiri]

You've written the same EmailService three times this week — once new'd in a controller, once in a model callback, once passed down through two function arguments to reach a place three layers deep. Wheels 4.0 ships a first-party DI container, wheelsdi, that ends that. Register a service once, give it a lifetime, resolve it anywhere.

This post is a user-facing how-to — not the internals or boot-sequence story (that's the earlier From WireBox to wheelsdi post). It stays on the surface you actually touch.

Read: https://blog.wheels.dev/posts/dependency-injection-services-scopes

What it covers

Registration. A fresh Wheels app has no config/services.cfm — the scaffold doesn't write one, and wheels.Bindings only registers internal framework interfaces. You author the file. Inside it, injector() returns the live container, and the fluent chain does the rest:

var di = injector();
di.map("emailService").to("app.lib.EmailService").asSingleton();
di.bind("INotifier").to("app.lib.SlackNotifier").asSingleton();
di.map("currentUser").to("app.lib.CurrentUserResolver").asRequestScoped();
di.map("pdfBuilder").to("app.lib.PdfBuilder");   // transient — the default

Three lifetimes. Transient (the default — no verb), .asSingleton() (one per app, must be thread-safe), .asRequestScoped() (one per HTTP request). The verbs are exactly asSingleton() / asRequestScoped() — there's no .transient() or .scope("..."); transient is what omission gives you.

Resolving. The service("name") global helper works in controllers, models, and views, and honors the registered scope. It throws Wheels.DI.ServiceNotFound (with a message pointing at services.cfm) rather than returning null — guard optional services with injector().containsInstance("name").

Controller injection. inject("emailService, currentUser") in config() declares dependencies at the class level; the framework resolves them per controller instance and attaches them as this.<serviceName>. Class-declare / instance-resolve is precisely what makes request-scoped services correct inside controllers.

Auto-wiring. An init() parameter named after a registered mapping is resolved and injected automatically — when no explicit initArguments are passed. Pass an initArguments struct and auto-wiring is skipped entirely; your struct wins. That's the override hook for test fakes. Auto-wiring also walks the extends chain and matches against live mappings on each resolve.

The sharp edges (the part that saves you a debugging session)

• Transient is the default. No scope verb = a fresh instance every resolve. The most common "why is my singleton not shared" bug is a missing .asSingleton().
• Singletons cache by mapping name, not component path. map("a").to("X").asSingleton() and map("b").to("X").asSingleton() give two distinct X objects.
• Scope verbs flag the mapping you just completed, not whichever key sorts last in the backing struct — relevant because ~20 framework bindings are already registered when your file runs.
• Auto-wiring only fires with empty initArguments, and matches on parameter name.
• service() / injector() throw, never return null — Wheels.DI.NotInitialized (too early) or Wheels.DI.ServiceNotFound.
• Circular constructor deps throw Wheels.DI.CircularDependency with the full chain; the resolving guard is request-scoped, so concurrent cold-start requests don't trip a false self-loop.
• Use mapInstance() instead of map() inside a plugin ServiceProvider — on Lucee/Adobe, map() on an any-typed injector can resolve to CFML's built-in struct.map() and silently no-op your registrations.

Discuss

• What are you registering as singletons today, and are they actually thread-safe? (If they hold mutable state, you own the locking.)
• Has anyone hit the "two aliases, same path, two instances" surprise in the wild?
• Do you prefer controller inject() or explicit service() calls in actions — and why?

Feedback on the post — what's unclear, what you'd want a follow-up to cover — welcome in this thread.