Dependency Management in TypeScript: From Manual DI to an IoC Container

AgentRuntime
  -> TaskEngine
  -> ContextBuilder
  -> ModelProvider
TaskEngine
  -> AgentRegistry
  -> ToolRunner
  -> EventBus
  -> SessionStore
ToolRunner
  -> SkillRegistry
  -> PermissionChecker
  -> EventBus
ContextBuilder
  -> SkillRegistry
  -> ToolRunner
  -> HistoryStore

// 没有 IoC：自己管理依赖
class UserService {
  private repo = new PostgresUserRepo()
}

// 有 IoC：依赖从外部来
class UserService {
  constructor(private readonly repo: UserRepo) {}
}

container.register(UserRepoToken, () => new PostgresUserRepo(db))
container.register(UserServiceToken, () => new UserService(container.resolve(UserRepoToken)))

依赖组织
├── 对象创建与注入（DI 实现方式）
│   ├── 全局单例
│   ├── 手写 DI / Composition Root
│   ├── 显式 IoC Container
│   └── Decorator-based DI
│
├── 容器的使用方式
│   ├── DI 风格：装配层 resolve → 注入业务对象
│   └── Service Locator 风格：业务对象自己调 inject()
│
└── 模块组织方式
    ├── Plugin / Module Registry
    └── Functional Core + Imperative Shell

const db = createDb()
const userRepo = new PostgresUserRepo(db)
export const userService = new UserService(userRepo)

// 使用
import { userService } from "./user-service"
await userService.getUser("u_123")

// 业务层——只声明依赖
class OrderService {
  constructor(
    private readonly orderRepo: OrderRepo,
    private readonly paymentClient: PaymentClient,
    private readonly eventBus: EventBus,
  ) {}
}

// 入口层——装配依赖
export function createAppDeps() {
  const db = createDb()
  const orderRepo = new PostgresOrderRepo(db)
  const paymentClient = new StripeClient(config)
  const eventBus = new InMemoryEventBus()
  const orderService = new OrderService(orderRepo, paymentClient, eventBus)
  return { db, orderRepo, paymentClient, eventBus, orderService }
}

const UserRepoToken = token<UserRepo>("app.userRepo")
const UserServiceToken = token<UserService>("app.userService")

container.register(UserRepoToken, () => new PostgresUserRepo(db))
container.register(UserServiceToken, () =>
  new UserService(container.resolve(UserRepoToken))
)

// 入口层
const userService = container.resolve(UserServiceToken)

class Container {
  private providers = new Map<Token<unknown>, Provider<unknown>>()
  private instances = new Map<Token<unknown>, unknown>()

  register<T>(token: Token<T>, provider: Provider<T>) {
    this.providers.set(token, provider)
  }

  resolve<T>(token: Token<T>): T {
    if (this.instances.has(token)) return this.instances.get(token) as T
    const provider = this.providers.get(token)
    if (!provider) throw new Error(`Provider not registered: ${String(token)}`)
    const instance = provider()
    this.instances.set(token, instance)
    return instance as T
  }
}

@startuml
title AsyncLocalStorage Context Isolation
participant "HTTP Request" as req
participant "ALS Store" as als
participant "Container" as c
participant "UserService" as svc

req -> als: run(container, handler)
activate als
als -> req: handler()
req -> c: resolve(UserServiceToken)
c -> svc: new UserService(repo)
svc --> c: instance
c --> req: userService
deactivate als

note right of als
  Each request runs in its own async context
  Different requests receive different container instances
end note
@enduml

@Injectable()
class UserService {
  constructor(
    @Inject(UserRepoToken) private readonly userRepo: UserRepo,
  ) {}
}

@Module({ providers: [UserService, PostgresUserRepo] })
class UserModule {}

@startuml
package "DI Style" {
  [Composition Root] as cr
  [Container] as c1
  [OrderService] as os1
  
  cr -> c1: resolve dependencies
  cr -> os1: new OrderService(deps)
  note right of os1: Unaware of the container
}

package "Service Locator Style" {
  [Container] as c2
  [OrderService] as os2
  
  os2 -> c2: inject(EventBusToken)
  note right of os2: Explicitly requests dependencies from the container
}
@enduml

container.register(OrderServiceToken, () =>
  new OrderService(
    container.resolve(UserServiceToken),
    container.resolve(EventBusToken),
  )
)

class OrderService {
  constructor(
    private readonly userService: UserService,
    private readonly eventBus: EventBus,
  ) {}
}

class OrderService {
  private readonly userService = inject(UserServiceToken)
  private readonly eventBus = inject(EventBusToken)
}

interface AppModule {
  name: string
  register(container: Container): void
}

export const userModule: AppModule = {
  name: "user",
  register(container) {
    container.register(UserRepoToken, () => new PostgresUserRepo())
    container.register(UserServiceToken, () =>
      new UserService(container.resolve(UserRepoToken))
    )
  },
}

// 启动
for (const mod of modules) {
  mod.register(container)
}

@startuml
title Functional Core + Imperative Shell

package "Imperative Shell" {
  [HTTP Handler] as http
  [DB Query] as db
  [External API] as api
  [File IO] as io
}

package "Functional Core" {
  [Price Calculator] as calc
  [Permission Checker] as perm
  [Context Builder] as ctx
  [State Machine] as sm
}

http --> calc
http --> perm
http --> ctx
http --> sm

note right of calc
  Pure functions: same input = same output
  No database reads, network requests, or file writes
end note
@enduml

// 核心：纯函数，不碰 IO
function calculatePrice(input: PriceInput, rules: PricingRules): PriceResult {
  // pure logic
}

// 外壳：处理 IO
const rules = await repo.loadRules()
const result = calculatePrice(input, rules)
await repo.savePrice(result)

@startuml
title Choosing a Dependency Strategy by Project Size
start
:Start the project;
if (Fewer than 5 modules?) then (Yes)
  :Manual DI;
  note right: Explicit dependencies, no magic
else (No)
  if (Is wiring code growing too large?) then (Yes)
    if (Need dynamic extensions?) then (Yes)
      :Plugin Registry + IoC Container;
    else (No)
      :Explicit IoC Container;
    endif
  else (No)
    if (Using NestJS?) then (Yes)
      :Decorator-based DI;
    else (No)
      :Continue with manual DI;
    endif
  endif
endif
stop
@enduml

@startuml
top to bottom direction

node "AgentRuntime" as rt {
  node "TaskEngine" as te
  node "ContextBuilder" as cb
}

node "Infrastructure" as infra {
  node "AgentRegistry" as ar
  node "SkillRegistry" as sr
  node "ToolRunner" as tr
  node "EventBus" as eb
  node "SessionStore" as ss
}

te --> ar
te --> tr
te --> eb
te --> ss
cb --> sr
cb --> tr
tr --> sr
tr --> eb

note right of rt
  All modules need logger and config
  Different kernels need separate instances
end note
@enduml

import { AsyncLocalStorage } from "node:async_hooks";

export type ClassToken<T> = abstract new (...args: never[]) => T;
export type SymbolToken<T> = symbol & { readonly __type?: T };
export type Token<T> = ClassToken<T> | SymbolToken<T>;

type Provider<T> = () => T;

const als = new AsyncLocalStorage<IocContainer>();

export class IocContainer {
  private instances = new Map<Token<unknown>, unknown>();
  private providers = new Map<Token<unknown>, Provider<unknown>>();

  set<T>(token: Token<T>, instance: T): void {
    this.instances.set(token, instance);
  }

  register<T>(token: Token<T>, factory?: Provider<T>): void {
    if (factory === undefined) {
      if (typeof token === "symbol") {
        throw new Error(
          `Cannot auto-register symbol token "${String(token)}" without a factory.`,
        );
      }
      // 抽象类作为 token 时，自动推断构造函数
      this.providers.set(token, () => new (token as new () => T)());
      return;
    }
    this.providers.set(token, factory);
  }

  resolve<T>(token: Token<T>): T {
    if (this.instances.has(token)) return this.instances.get(token) as T;
    const factory = this.providers.get(token);
    if (!factory)
      throw new Error(`Provider for token ${String(token)} not registered`);
    const instance = factory();
    this.set(token, instance);
    return instance as T;
  }

  /** 一次性解析所有已注册的 provider，确保所有单例在启动时即构建完毕 */
  resolveAll(): void {
    for (const token of this.providers.keys()) this.resolve(token);
  }
}

export function token<T>(name: string): SymbolToken<T> {
  return Symbol.for(name) as SymbolToken<T>;
}

export function runWithContainer<T>(
  container: IocContainer,
  callback: () => T,
): T {
  return als.run(container, callback);
}

function getContainer(): IocContainer {
  const container = als.getStore();
  if (!container)
    throw new Error("No active IoC container in current async context");
  return container;
}

export const register: IRegistrar = <T>(
  token: Token<T>,
  factory?: Provider<T>,
): void => {
  getContainer().register(token, factory);
};

export const inject: IInject = (<T>(token: Token<T>): T => {
  return getContainer().resolve(token);
}) as IInject;

inject.lazy = function lazy<T extends object>(token: Token<T>): T {
  let instance: T | undefined;
  let resolved = false;
  const container = als.getStore();
  if (!container) throw new Error("inject.lazy() requires an active container");
  return new Proxy({} as T, {
    get(_, prop) {
      if (!resolved) {
        instance = container.resolve(token);
        resolved = true;
      }
      const value = Reflect.get(instance!, prop);
      return typeof value === "function" ? value.bind(instance) : value;
    },
  }) as T;
};

export const bootstrap = (options: KernelOptions): IAgentKernel => {
  const container = new IocContainer();
  container.set(KernelOptionsToken, options);

  let logger: ILogger;
  let router: RequestRouter;

  runWithContainer(container, () => {
    registerProviders();    // 注册所有模块的 provider
    container.resolveAll(); // 一次性构建所有单例
    logger = inject(Logger).child("Bootstrap");
    logger.info("Bootstrapping Agent Kernel");
    router = inject(RequestRouter);
    registerRoutes();
  });

  const handleRequest = async (request: RpcRequest): Promise<RpcResponse> => {
    return runWithContainer(container, async () => {
      const { id, method, params } = request;
      logger.debug(`Received request: ${method} with id: ${id}`, params);
      try {
        return router.handle(request);
      } catch (error) {
        let msg = "unknown error";
        if (error instanceof Error) msg = error.message;
        return ErrorRspSchema.parse({ id, method, msg });
      }
    });
  };

  return { handleRequest };
};

registerProviders()    →  声明"有哪些模块、怎么创建"
resolveAll()           →  一次性把整棵树建好
handleRequest()        →  只使用，不再创建