inversify-typesafe-spring-like 0.5.10 → 0.5.11

package/README.md

@@ -65,11 +65,16 @@ class ArticleQueryService implements GetArticleUseCase {
   }
 }
 
-type Beans = {
+type UseCaseBeans = {
   GetArticleUseCase: GetArticleUseCase; // interface (class is also possible)
+}
+
+type InfraBeans = {
   ArticleOutgoingPort: ArticleOutgoingPort; // interface (class is also possible)
 }
 
+type Beans = UseCaseBeans & InfraBeans
+
 const beanConfig: BeanConfig<Beans> = {
   // compile error if ArticleQueryService is not compatible with GetArticleUseCase.
   GetArticleUseCase: (bind) => bind().to(ArticleQueryService),
@@ -79,26 +84,53 @@ const beanConfig: BeanConfig<Beans> = {
 
 const applicationContext = ApplicationContext(beanConfig);
 
-const getArticleUseCase = applicationContext.get("GetArticleUseCase")
+function getUseCase<TUseCaseName extends keyof UseCaseBeans>(
+  useCaseName: TUseCaseName,
+): UseCaseBeans[TUseCaseName] {
+  return applicationContext.get(useCaseName)
+}
+
+// Only use-case beans can be resolved from application entry points.
+const getArticleUseCase = getUseCase("GetArticleUseCase")
 
 getArticleUseCase.execute(1).then(console.log)
 ```
 
 ## TL;DR
 
-`inversify-typesafe-spring-like` is a Spring-flavored add-on for `inversify-typesafe`. Define a `Beans` map, register every bean with `BeanConfig`, create an `Autowired` decorator with `returnAutowired`, and initialize the container with `ApplicationContext`. Bean names are checked and return types are inferred at compile time, while beans use singleton scope by default.
+`inversify-typesafe-spring-like` is a Spring-flavored add-on for `inversify-typesafe`. Define separate `UseCaseBeans` and `InfraBeans` maps, combine them into `Beans`, register every bean with `BeanConfig`, and create an `Autowired` decorator with `returnAutowired`. Initialize the container with `ApplicationContext`, and resolve only use cases through a `getUseCase` helper at application entry points. Bean names are checked and return types are inferred at compile time, while beans use singleton scope by default.
+
+See the packaged [use-case beans guide](./docs/use-case-beans.md) for the complete recommended structure.
+
+## AI Agent Setup
+
+Add the following block to the consuming project's `AGENTS.md` or `CLAUDE.md` so coding agents read this library's guidance before changing dependency-injection code. Installing this library does not create or modify either file automatically.
+
+```md
+<!-- BEGIN:inversify-typesafe-spring-like-agent-rules -->
+# `inversify-typesafe-spring-like` rules
+
+Before adding or changing dependency-injection code, read `node_modules/inversify-typesafe-spring-like/docs/index.md` and the guide that matches the task.
+
+- Use `UseCaseBeans` and `InfraBeans` as separate maps. Combine them for container setup, and expose use cases through `getUseCase` at application entry points.
+- Read `node_modules/inversify-typesafe-spring-like/docs/lazy-application-context.md` when container creation should be deferred, such as in serverless applications.
+- Read `node_modules/inversify-typesafe-spring-like/docs/domain-specific-bean-config.md` when a domain owns its own bean configuration while sharing common beans.
+- Read `node_modules/inversify-typesafe-spring-like/docs/to-resolved-value.md` when one instance must be exposed through multiple bean keys.
+- Do not bypass bean-key or resolved-value type checking with casts. Keep bean maps, `BeanConfig`, `Autowired`, and `getUseCase` definitions synchronized when bean names change.
+<!-- END:inversify-typesafe-spring-like-agent-rules -->
+```
 
 <details>
 <summary><strong>For AI Agents Using This Library</strong></summary>
 
-- Define one `Beans` map whose string keys are bean names and whose values are the types returned for those names.
-- Declare a `BeanConfig<Beans>` containing every key in `Beans`, and bind each key to a compatible implementation with the provided `bind()` function.
+- Define `UseCaseBeans` for application entry points and `InfraBeans` for infrastructure dependencies, then combine them as `type Beans = UseCaseBeans & InfraBeans`.
+- Declare a `BeanConfig<Beans>` containing every key in the combined map, and bind each key to a compatible implementation with the provided `bind()` function.
 - Create a project-local decorator by destructuring `const { Autowired } = returnAutowired<Beans>()`, then use `@Autowired("BeanName")` for constructor injection.
 - Pass the bean config to `ApplicationContext`; let TypeScript infer the context type instead of adding a generic argument manually.
-- Resolve beans with `applicationContext.get("BeanName")`. Do not cast bean names or result types, because doing so bypasses compile-time checks.
+- Expose a `getUseCase<T extends keyof UseCaseBeans>` helper that calls `applicationContext.get`; use it at application entry points so infrastructure beans cannot be resolved there.
 - Assume singleton scope unless an explicit `ContainerOptions` argument passed to `ApplicationContext` overrides `defaultScope`.
 - Use the underlying `inversify-typesafe` capabilities for advanced bindings and the original InversifyJS API. `BeanConfig`, `ApplicationContext`, and `returnAutowired` correspond to `TypesafeServiceConfig`, `createTypesafeContainer`, and `returnTypesafeInject` respectively.
-- Keep the `Beans` map, bean config, `get` calls, and `Autowired` decorators synchronized whenever a bean is added, removed, or renamed.
+- Keep the bean maps, bean config, `getUseCase` helper, and `Autowired` decorators synchronized whenever a bean is added, removed, or renamed.
 
 </details>
 
@@ -150,6 +182,8 @@ For complete usage documentation and advanced features, please refer to the [inv
 
 ### Lazy ApplicationContext Initialization
 
+For a self-contained reference, see the packaged [lazy ApplicationContext guide](./docs/lazy-application-context.md).
+
 In production applications, you may want to defer the initialization of the ApplicationContext until it's actually needed. This is especially useful in serverless environments or when you want to avoid initialization overhead during module loading.
 
 **The `lazy` utility function:**
@@ -225,6 +259,8 @@ const useCase = applicationContext().get("GetArticleUseCase");
 
 ### Domain-Specific BeanConfig
 
+For a self-contained reference, see the packaged [domain-specific BeanConfig guide](./docs/domain-specific-bean-config.md).
+
 As your application grows, you may want to organize beans by domain. This pattern allows each domain module to define its own beans while extending a common configuration.
 
 ```ts
@@ -297,6 +333,8 @@ class ArticleQueryService implements GetArticleUseCase {
 
 ### Reusing a Single Class for Multiple Interfaces with `toResolvedValue`
 
+For a self-contained reference, see the packaged [`toResolvedValue` guide](./docs/to-resolved-value.md).
+
 When a single class implements multiple interfaces (e.g., both `QueryPort` and `CommandPort`), you can use `toResolvedValue` to register the same instance under different bean names. This avoids creating separate instances and ensures consistency.
 
 ```ts

package/docs/domain-specific-bean-config.md

@@ -0,0 +1,57 @@
+# Domain-specific BeanConfig
+
+Let a domain extend common bean definitions when it owns its application services but shares cross-cutting infrastructure such as logging.
+
+```ts
+import {
+  BeanConfig,
+  returnAutowired,
+} from "inversify-typesafe-spring-like";
+
+interface LoggingPort {
+  log(message: string): void;
+}
+
+class ConsoleLogger implements LoggingPort {
+  log(message: string): void {
+    console.log(message);
+  }
+}
+
+type CommonBeans = {
+  LoggingPort: LoggingPort;
+};
+
+const commonBeanConfig: BeanConfig<CommonBeans> = {
+  LoggingPort: (bind) => bind().to(ConsoleLogger),
+};
+
+interface GetArticleUseCase {
+  execute(id: number): string;
+}
+
+type ArticleBeans = CommonBeans & {
+  GetArticleUseCase: GetArticleUseCase;
+};
+
+const { Autowired: ArticleAutowired } = returnAutowired<ArticleBeans>();
+
+class ArticleQueryService implements GetArticleUseCase {
+  constructor(
+    @ArticleAutowired("LoggingPort")
+    private readonly loggingPort: LoggingPort,
+  ) {}
+
+  execute(id: number): string {
+    this.loggingPort.log(`Loading article ${id}`);
+    return `Article #${id}`;
+  }
+}
+
+export const articleBeanConfig: BeanConfig<ArticleBeans> = {
+  ...commonBeanConfig,
+  GetArticleUseCase: (bind) => bind().to(ArticleQueryService),
+};
+```
+
+The domain map must include every common key that its services inject. Keep the domain's own bean names and bindings near the domain; compose the resulting config at the application composition root.

package/docs/index.md

@@ -0,0 +1,12 @@
+# `inversify-typesafe-spring-like` guides
+
+Use these guides when configuring dependency injection in an application. They are shipped with the package, so installed copies are available at `node_modules/inversify-typesafe-spring-like/docs/`.
+
+| Need | Guide |
+| --- | --- |
+| Define application and infrastructure boundaries | [Use-case beans](./use-case-beans.md) |
+| Defer container initialization | [Lazy ApplicationContext](./lazy-application-context.md) |
+| Compose common and domain-specific beans | [Domain-specific BeanConfig](./domain-specific-bean-config.md) |
+| Expose one instance through multiple bean keys | [`toResolvedValue`](./to-resolved-value.md) |
+
+Start with [Use-case beans](./use-case-beans.md) unless the application already has an established dependency-injection structure.

package/docs/lazy-application-context.md

@@ -0,0 +1,42 @@
+# Lazy ApplicationContext initialization
+
+Create the container on first use when eager initialization would add unnecessary startup work, such as in serverless handlers. The lazy function caches the first container instance.
+
+```ts
+import "reflect-metadata";
+import {
+  ApplicationContext,
+  BeanConfig,
+} from "inversify-typesafe-spring-like";
+
+const lazy = <T>(factory: () => T) => {
+  let value: T | undefined;
+  return (): T => value ?? (value = factory());
+};
+
+interface HealthCheckUseCase {
+  execute(): { status: "ok" };
+}
+
+class HealthCheckService implements HealthCheckUseCase {
+  execute() {
+    return { status: "ok" } as const;
+  }
+}
+
+type Beans = {
+  HealthCheckUseCase: HealthCheckUseCase;
+};
+
+const beanConfig: BeanConfig<Beans> = {
+  HealthCheckUseCase: (bind) => bind().to(HealthCheckService),
+};
+
+export const applicationContext = lazy(() => ApplicationContext(beanConfig));
+
+export function handleHealthCheck() {
+  return applicationContext().get("HealthCheckUseCase").execute();
+}
+```
+
+Use this pattern at the composition root. Call `applicationContext()` only when a request or job needs a bean; subsequent calls reuse the same `ApplicationContext` and its singleton bindings.

package/docs/to-resolved-value.md

@@ -0,0 +1,58 @@
+# Reusing one instance with `toResolvedValue`
+
+Use `toResolvedValue` when one implementation must be exposed through multiple bean keys without creating multiple instances. Bind the concrete implementation once, then derive each additional bean from the resolved dependency.
+
+```ts
+import {
+  ApplicationContext,
+  BeanConfig,
+} from "inversify-typesafe-spring-like";
+
+interface Stay {
+  id: number;
+  name: string;
+}
+
+interface StayQueryPort {
+  findById(id: number): Promise<Stay | undefined>;
+}
+
+interface StayCommandPort {
+  save(stay: Stay): Promise<Stay>;
+}
+
+class StayPersistenceAdapter implements StayQueryPort, StayCommandPort {
+  private readonly stays = new Map<number, Stay>();
+
+  async findById(id: number): Promise<Stay | undefined> {
+    return this.stays.get(id);
+  }
+
+  async save(stay: Stay): Promise<Stay> {
+    this.stays.set(stay.id, stay);
+    return stay;
+  }
+}
+
+type Beans = {
+  StayQueryPort: StayQueryPort;
+  StayCommandPort: StayCommandPort;
+};
+
+const beanConfig: BeanConfig<Beans> = {
+  StayQueryPort: (bind) => bind().to(StayPersistenceAdapter),
+  StayCommandPort: (bind) =>
+    bind().toResolvedValue(
+      (queryPort) => queryPort as StayCommandPort,
+      ["StayQueryPort"],
+    ),
+};
+
+const applicationContext = ApplicationContext(beanConfig);
+const queryPort = applicationContext.get("StayQueryPort");
+const commandPort = applicationContext.get("StayCommandPort");
+
+console.log(queryPort === commandPort); // true
+```
+
+The dependency array is resolved before the transform function runs. The transform function receives those resolved values and returns the value for the new bean key. Use this for aliases, derived values, or a single adapter that fulfills multiple interfaces. Keep the cast localized to the transform only when TypeScript cannot infer that the resolved implementation satisfies the second interface.

package/docs/use-case-beans.md

@@ -0,0 +1,74 @@
+# Use-case and infrastructure beans
+
+Use separate maps for application entry points and infrastructure dependencies. Combine them only when configuring the container, and expose a `getUseCase` helper so controllers and handlers cannot resolve infrastructure beans directly.
+
+```ts
+import "reflect-metadata";
+import {
+  ApplicationContext,
+  BeanConfig,
+  returnAutowired,
+} from "inversify-typesafe-spring-like";
+
+interface Article {
+  id: number;
+  title: string;
+}
+
+interface ArticleOutgoingPort {
+  getById(id: number): Promise<Article>;
+}
+
+interface GetArticleUseCase {
+  execute(id: number): Promise<Article>;
+}
+
+class ArticleRepository implements ArticleOutgoingPort {
+  async getById(id: number): Promise<Article> {
+    return { id, title: `Article #${id}` };
+  }
+}
+
+type UseCaseBeans = {
+  GetArticleUseCase: GetArticleUseCase;
+};
+
+type InfraBeans = {
+  ArticleOutgoingPort: ArticleOutgoingPort;
+};
+
+type Beans = UseCaseBeans & InfraBeans;
+
+const { Autowired } = returnAutowired<Beans>();
+
+class ArticleQueryService implements GetArticleUseCase {
+  constructor(
+    @Autowired("ArticleOutgoingPort")
+    private readonly articleOutgoingPort: ArticleOutgoingPort,
+  ) {}
+
+  execute(id: number): Promise<Article> {
+    return this.articleOutgoingPort.getById(id);
+  }
+}
+
+const beanConfig: BeanConfig<Beans> = {
+  GetArticleUseCase: (bind) => bind().to(ArticleQueryService),
+  ArticleOutgoingPort: (bind) => bind().to(ArticleRepository),
+};
+
+const applicationContext = ApplicationContext(beanConfig);
+
+export function getUseCase<TUseCaseName extends keyof UseCaseBeans>(
+  useCaseName: TUseCaseName,
+): UseCaseBeans[TUseCaseName] {
+  return applicationContext.get(useCaseName);
+}
+
+const useCase = getUseCase("GetArticleUseCase");
+useCase.execute(1).then(console.log);
+```
+
+`Beans` is the complete container contract, so application services can inject infrastructure ports. `getUseCase` accepts only `keyof UseCaseBeans`, which keeps infrastructure resolution inside composition code instead of application entry points.
+
+Do not call `applicationContext.get` from controllers or cast bean keys to bypass this boundary.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "inversify-typesafe-spring-like",
   "type": "module",
-  "version": "0.5.10",
+  "version": "0.5.11",
   "description": "Add-On Library for inversify-typesafe to make it more like Spring.",
   "source": "src/index.ts",
   "exports": {
@@ -25,7 +25,8 @@
   "unpkg": "dist/index.umd.js",
   "files": [
     "dist/**/*",
-    "package.json"
+    "package.json",
+    "docs/**/*.md"
   ],
   "scripts": {
     "preinstall": "npx only-allow pnpm",
@@ -61,7 +62,7 @@
   "author": "Myeongjae Kim",
   "license": "MIT",
   "dependencies": {
-    "inversify-typesafe": "^0.5.10"
+    "inversify-typesafe": "^0.5.11"
   },
   "devDependencies": {
     "inversify": "^8.1.3",