Domain-Driven Design TypeScript Utilities / Container

Manifest-driven IoC container for PJTS applications. One scope (singleton), no tokens, no bindings: every dependency is resolved from the constructor parameter type names recorded in the wiring that pjts-wiring (@pjts/schema) generates from the TypeScript program.

Installation

npm install @pjts/container

Usage

import { Container } from '@pjts/container'
import wiring from './pjts.wiring'

const container = new Container(wiring, {
  storage: 'pg',                      // 'memory' keeps in-memory adapters only
  profiles: ['claude'],               // @Adapter({ profile }) names in effect
  instances: { PostgresDbClient: db },
  factories: { NatsJetStreamClient: () => natsJetStreamConnect(url) },
})
const service = await container.get(MessageService)

Resolution of a parameter type name, first hit wins, anything ambiguous throws with the full path:

1. instances[name]
2. factories[name] — evaluated once
3. the class named name
4. the one adapter implementing the port name: storage profile (memory vs the rest) → composite rule (an adapter that implements T and takes T[] wins and receives the others) → active profile
5. the provider whose return type is name: a static method of a module or group class (CalendarModule.calendarFeedConfig) or a shared function under common/config/**

Port[] parameters receive every surviving adapter. getAll(predicate) instantiates every class entry matching a predicate (lifecycle ports). enabledGroups / isClassOn implement APPS gating with the <MODULE>_API / <MODULE>_MESSAGE_HANDLERS / <MODULE>_WORKERS defaults.

Boot-time errors (ContainerError.code): INVALID_WIRING, DUPLICATE_NAME, UNKNOWN_REFERENCE, CYCLE, NO_ADAPTER, AMBIGUOUS_ADAPTER, UNRESOLVABLE. The wiring is validated in the constructor; everything else (get, resolve, resolveAll, getAll) returns a promise and reports failures by rejecting, including an unknown class.

Semantics worth knowing

• Singletons, built once. Every class, adapter, provider and factory is constructed at most once per container, on first request; concurrent requests for the same key share the pending promise. A construction that fails is not cached: the next request builds again, so a dependency that was not reachable yet does not poison the container for its lifetime.
• getAll is parallel. It resolves every matching class with Promise.all, so constructors of unrelated classes run concurrently (each class is still built once). What a caller does with the instances afterwards is sequential if the caller makes it so; @pjts/server's ApplicationContext awaits lifecycle hooks one after another, in wiring order.
• Port[] has no priority. resolveAll and a T[] constructor parameter receive the surviving adapters in wiring order, which pjts-wiring sorts by kind, module and name. There is no mechanism to rank adapters; a fallback chain that cares about order belongs in a composite adapter that takes T[] and orders them itself.
• Storage worlds. memory and everything else are the two worlds. Under memory an InMemory* double outranks a storage-less adapter of the same port; under a persistent storage a storage-less adapter is as real as a pg/ one, and two survivors are AMBIGUOUS_ADAPTER rather than a silent pick.
• No request scope. There is one scope. Per-request data (actor, correlation id, transaction) travels as method arguments or through the HTTP layer's @Middleware parameters, not through the container.

How it compares

Most TypeScript containers register dependencies at runtime: tsyringe and inversify with @injectable plus tokens (interfaces erase, so a port needs a string or symbol token), NestJS with module metadata and providers arrays, Awilix with a registration API and name-based resolution. @pjts/container has no registration step at all: pjts-wiring reads the TypeScript program and writes a manifest, and the container resolves by the type names written in constructors, which is why an interface can be a port without a token and why emitDecoratorMetadata is not needed for injection. The trade-offs are the ones that follow from that choice: one scope, resolution by name (two classes with one name are rejected), conventions for adapter selection instead of explicit bindings, and a generation step that must run when constructors change (pjts-wiring --check in a pre-commit hook keeps it honest).

License

MIT