Build your first container

In this tutorial, you will define typed dependencies, connect them with providers, and resolve a service from a container. You only need a TypeScript project and the package installed.

1. Define typed tokens

   A token is a unique runtime key that also carries the TypeScript type of its value.

   const CONFIG = createToken<Config>("CONFIG");
   const LOGGER = createToken<Logger>("LOGGER");
   const USERS = createToken<UserService>("USERS");

2. Describe construction with providers

   Use a value provider for existing values and a factory provider for services. Dependency names are inferred in useFactory.

   provideValue(CONFIG, { logPrefix: "users" });
   
   provideFactory(LOGGER, {
     deps: { config: CONFIG },
     useFactory: ({ config }) => new Logger(config.logPrefix),
   });

3. Create a container and resolve at the edge

   const container = createContainer(providers);
   const users = container.get(USERS);

Keep the container at the composition root

Inject the resolved dependencies into domain code. Passing the container itself through the application hides dependencies and turns injection into service location.

Complete example

This source file is type-checked with the documentation workspace, so the published example stays aligned with the package API.

examples/core/basic.ts

import {
  createContainer,
  createToken,
  type Provider,
  provideFactory,
  provideValue,
} from "di-craft";

type Config = {
  readonly logPrefix: string;
};

class Logger {
  private readonly prefix: string;

  constructor(prefix: string) {
    this.prefix = prefix;
  }

  info(message: string): string {
    return `${this.prefix}: ${message}`;
  }
}

class UserService {
  private readonly logger: Logger;

  constructor(logger: Logger) {
    this.logger = logger;
  }

  list(): readonly string[] {
    this.logger.info("list users");
    return ["Ada", "Grace"];
  }
}

const CONFIG = createToken<Config>("CONFIG");
const LOGGER = createToken<Logger>("LOGGER");
const USERS = createToken<UserService>("USERS");

const providers: readonly Provider[] = [
  provideValue(CONFIG, { logPrefix: "users" }),
  provideFactory(LOGGER, {
    deps: { config: CONFIG },
    useFactory: ({ config }) => new Logger(config.logPrefix),
  }),
  provideFactory(USERS, {
    deps: { logger: LOGGER },
    useFactory: ({ logger }) => new UserService(logger),
  }),
];

const container = createContainer(providers);
const users = container.get(USERS);

users.list();

Continue with tokens and providers, or browse the generated API reference.