Containers

Creating a container

The dependency injection (DI) container will keep track of all bindings and hold the actual instances of your services. To create it, simply construct one:

import { Container } from "@needle-di/core";

const container = new Container();

Every DI container keeps track of its own service instances separately.

Binding services

You can bind services using the .bind() or .bindAll() methods:

container
  .bind(FooService)
  .bind({
    provide: BarService,
    useFactory: () => new BarService(),
  });

container.bindAll(
  {
    provide: Logger,
    useFactory: () => new FileLogger(),
  },
  {
    provide: AppConfig,
    useValue: someConfig,
  },
);

Learn more about the different types of providers you can use for binding.

Constructing services

To obtain something from the container, you can use container.get(token):

const fooService = container.get(FooService);
//    ^? Type will be inferred as `FooService`

This will create a new FooService, or return the existing one if it was requested before.

NOTE

To inject dependencies into classes, use constructor injection instead.

bootstrap() shorthand

If you don't need to interact with the DI container at all, you can also use the bootstrap() shorthand function instead. This will internally create a new container and return the requested service directly:

import { bootstrap } from "@needle-di/core";

const barService = bootstrap(BarService);

This is useful if you solely depend on auto-binding and/or tree-shakeable injection tokens and therefore don't need to register anything manually into your container.

Similarly, there is a bootstrapAsync() method when using async providers.

WARNING

Calling bootstrap() or bootstrapAsync() creates a new container everytime, leading to the creation of new instances for your singleton services. Make sure to only call it once in the lifecycle of your application to use it efficiently.

Creating child containers

You can also create a child container, which can be used to override a provider without affecting its parent.

To do so, use the .createChild() method:

const parent = new Container();
parent.bind({ provide: LOGGER, useClass: MyLogger });

const child = parent.createChild();
child.bind({ provide: LOGGER, useClass: OtherLogger });

See child containers for more information.