inversify-typesafe-spring-like 0.5.5 → 0.5.6

package/README.md

@@ -84,6 +84,24 @@ const getArticleUseCase = applicationContext.get("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.
+
+<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.
+- 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.
+- 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.
+
+</details>
+
 ## Introduction
 
 This library extends [inversify-typesafe](https://github.com/myeongjae-kim/inversify-typesafe) to provide a development experience similar to [Spring Framework](https://spring.io/).
@@ -128,6 +146,229 @@ The API is designed to mirror Spring's terminology:
 
 For complete usage documentation and advanced features, please refer to the [inversify-typesafe documentation](https://github.com/myeongjae-kim/inversify-typesafe/tree/main?tab=readme-ov-file#usage).
 
+## Advanced Patterns
+
+### Lazy ApplicationContext Initialization
+
+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:**
+
+```ts
+// core/common/util/lazy.ts
+export const lazy = <T>(fn: () => T) => {
+  let value: T | undefined;
+  return () => value ?? (value = fn());
+};
+```
+
+**Usage with ApplicationContext:**
+
+```ts
+// core/config/applicationContext.ts
+import 'reflect-metadata';
+import { ApplicationContext } from 'inversify-typesafe-spring-like';
+import { beanConfig } from './beanConfig';
+import { lazy } from '../common/util/lazy';
+
+// Lazy initialization - ApplicationContext is created only when first accessed
+export const applicationContext = lazy(() => ApplicationContext(beanConfig));
+```
+
+**Using in controllers or services:**
+
+```ts
+// app/api/articles/GetArticleController.ts
+import { applicationContext } from '@/core/config/applicationContext';
+
+export default async function handler(req: Request) {
+  // ApplicationContext is initialized on first call, then reused
+  const useCase = applicationContext().get("GetArticleUseCase");
+  const article = await useCase.execute(req.params.id);
+  return Response.json(article);
+}
+```
+
+**Why use lazy initialization?**
+
+| Benefit | Description |
+|---------|-------------|
+| Faster cold starts | Module loading doesn't trigger DI container initialization |
+| On-demand creation | Container is only created when actually needed |
+| Singleton guarantee | Multiple calls return the same instance |
+| Testability | Easy to mock or replace in tests |
+
+**Without lazy (eager initialization):**
+
+```ts
+// ❌ Container is created immediately when module is imported
+export const applicationContext = ApplicationContext(beanConfig);
+
+// Every import of this module triggers initialization
+import { applicationContext } from './applicationContext';
+```
+
+**With lazy (deferred initialization):**
+
+```ts
+// ✅ Container is created only when applicationContext() is called
+export const applicationContext = lazy(() => ApplicationContext(beanConfig));
+
+// Import doesn't trigger initialization
+import { applicationContext } from './applicationContext';
+
+// Initialization happens here, on first use
+const useCase = applicationContext().get("GetArticleUseCase");
+```
+
+**Note:** The `lazy` function ensures the initialization function is called exactly once, and subsequent calls return the cached value.
+
+### Domain-Specific BeanConfig
+
+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
+// core/config/CommonBeanConfig.ts
+import { BeanConfig } from "inversify-typesafe-spring-like";
+
+interface LoggingPort {
+  log(message: string): void;
+}
+
+class ConsoleLogger implements LoggingPort {
+  log(message: string): void {
+    console.log(`[LOG] ${message}`);
+  }
+}
+
+export type CommonBeans = {
+  LoggingPort: LoggingPort;
+};
+
+export const commonBeanConfig: BeanConfig<CommonBeans> = {
+  LoggingPort: (bind) => bind().to(ConsoleLogger),
+};
+```
+
+```ts
+// core/article/config/ArticleBeanConfig.ts
+import { BeanConfig, returnAutowired } from "inversify-typesafe-spring-like";
+import { CommonBeans, commonBeanConfig } from "../config/CommonBeanConfig";
+
+interface ArticleQueryPort { /* ... */ }
+interface ArticleCommandPort { /* ... */ }
+interface GetArticleUseCase { /* ... */ }
+
+// Extend CommonBeans with domain-specific beans
+export type ArticleBeans = CommonBeans & {
+  ArticleQueryPort: ArticleQueryPort;
+  ArticleCommandPort: ArticleCommandPort;
+  GetArticleUseCase: GetArticleUseCase;
+};
+
+// Domain-specific Autowired decorator
+export const { Autowired: ArticleAutowired } = returnAutowired<ArticleBeans>();
+
+export const articleBeanConfig: BeanConfig<ArticleBeans> = {
+  ...commonBeanConfig,  // Include common beans
+  ArticleQueryPort: (bind) => bind().to(ArticlePersistenceAdapter),
+  ArticleCommandPort: (bind) => bind().to(ArticlePersistenceAdapter),
+  GetArticleUseCase: (bind) => bind().to(ArticleQueryService),
+};
+```
+
+```ts
+// Usage in domain service
+class ArticleQueryService implements GetArticleUseCase {
+  constructor(
+    @ArticleAutowired("ArticleQueryPort")  // Type-safe within ArticleBeans
+    private readonly articleQueryPort: ArticleQueryPort,
+    @ArticleAutowired("LoggingPort")  // Common beans are also available
+    private readonly loggingPort: LoggingPort,
+  ) { }
+}
+```
+
+**Benefits:**
+- Each domain owns its bean configuration
+- Common beans (logging, transactions, etc.) are shared across domains
+- Type safety is maintained within each domain's scope
+- Easy to identify which beans belong to which domain
+
+### Reusing a Single Class for Multiple Interfaces with `toResolvedValue`
+
+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
+import { ApplicationContext, BeanConfig, returnAutowired } from "inversify-typesafe-spring-like";
+
+// Interfaces
+interface StayQueryPort {
+  findById(id: number): Promise<Stay | null>;
+  findAll(): Promise<Stay[]>;
+}
+
+interface StayCommandPort {
+  save(stay: Stay): Promise<Stay>;
+  delete(id: number): Promise<void>;
+}
+
+// Single class implementing both interfaces
+class StayPersistenceAdapter implements StayQueryPort, StayCommandPort {
+  async findById(id: number): Promise<Stay | null> { /* ... */ }
+  async findAll(): Promise<Stay[]> { /* ... */ }
+  async save(stay: Stay): Promise<Stay> { /* ... */ }
+  async delete(id: number): Promise<void> { /* ... */ }
+}
+
+type Beans = {
+  StayQueryPort: StayQueryPort;
+  StayCommandPort: StayCommandPort;
+};
+
+const { Autowired } = returnAutowired<Beans>();
+
+const beanConfig: BeanConfig<Beans> = {
+  // Register the class for the first interface
+  StayQueryPort: (bind) => bind().to(StayPersistenceAdapter),
+
+  // Reuse the same instance for the second interface
+  StayCommandPort: (bind) =>
+    bind().toResolvedValue(
+      (queryPort) => queryPort as StayCommandPort,  // Transform function
+      ['StayQueryPort']  // Dependencies to resolve first
+    ),
+};
+
+const applicationContext = ApplicationContext(beanConfig);
+
+// Both return the same instance
+const queryPort = applicationContext.get("StayQueryPort");
+const commandPort = applicationContext.get("StayCommandPort");
+
+console.log(queryPort === commandPort);  // true (same instance)
+```
+
+**How `toResolvedValue` works:**
+
+```ts
+bind().toResolvedValue(transformFn, dependencies)
+```
+
+- `transformFn`: A function that receives the resolved dependencies and returns the value to bind
+- `dependencies`: An array of bean names to resolve before calling the transform function
+
+**Use cases:**
+- Single class implementing multiple interfaces (CQRS pattern)
+- Creating derived beans from existing beans
+- Aliasing beans under different names
+- Lazy transformation of resolved dependencies
+
+**Benefits:**
+- Avoids duplicate instances when the same class serves multiple roles
+- Maintains singleton behavior across interface boundaries
+- Clear dependency declaration for complex wiring scenarios
+
 ## License
 
-MIT © [Myeongjae Kim](https://myeongjae.kim)
+MIT © [Myeongjae Kim](https://myeongjae.kim)

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs","sources":["../src/index.ts"],"sourcesContent":["import { ContainerOptions } from \"inversify\";\nimport { TypesafeServiceConfig as BeanConfig, createTypesafeContainer, returnTypesafeInject } from \"inversify-typesafe\";\n\nexport const returnAutowired = <S extends Record<string, unknown>>() => ({ Autowired: returnTypesafeInject<S>() });\n\nexport type { BeanConfig };\n\nexport const ApplicationContext = <S extends Record<string, unknown>>(beanConfig: BeanConfig<S>, options?: ContainerOptions) =>\n  createTypesafeContainer(beanConfig, { defaultScope: \"Singleton\", ...options });"],"names":["beanConfig","options","createTypesafeContainer","_extends","defaultScope","Autowired","returnTypesafeInject"],"mappings":"uRAOkC,SAAoCA,EAA2BC,GAC/F,OAAAC,EAAuBA,wBAACF,EAAUG,EAAIC,CAAAA,aAAc,aAAgBH,GAAU,0BALjD,WAAH,MAA6C,CAAEI,UAAWC,EAAAA,uBAA2B"}
+{"version":3,"file":"index.cjs","sources":["../src/index.ts"],"sourcesContent":["import { ContainerOptions } from \"inversify\";\nimport { TypesafeServiceConfig as BeanConfig, createTypesafeContainer, returnTypesafeInject, TypesafeContainer } from \"inversify-typesafe\";\n\nexport const returnAutowired = <S extends Record<string, unknown>>(): { Autowired: ReturnType<typeof returnTypesafeInject<S>> } =>\n  ({ Autowired: returnTypesafeInject<S>() });\n\nexport type { BeanConfig };\n\nexport const ApplicationContext = <S extends Record<string, unknown>>(beanConfig: BeanConfig<S>, options?: ContainerOptions): TypesafeContainer<S> =>\n  createTypesafeContainer(beanConfig, { defaultScope: \"Singleton\", ...options });"],"names":["beanConfig","options","createTypesafeContainer","_extends","defaultScope","Autowired","returnTypesafeInject"],"mappings":"uRAQkC,SAAoCA,EAA2BC,GAC/F,OAAAC,EAAuBA,wBAACF,EAAUG,EAAIC,CAAAA,aAAc,aAAgBH,GAAU,0BANjD,WAAH,MACzB,CAAEI,UAAWC,EAAAA,uBAA2B"}

package/dist/index.d.cts

@@ -1,7 +1,7 @@
 import { ContainerOptions } from "inversify";
-import { TypesafeServiceConfig as BeanConfig } from "inversify-typesafe";
+import { TypesafeServiceConfig as BeanConfig, returnTypesafeInject, TypesafeContainer } from "inversify-typesafe";
 export declare const returnAutowired: <S extends Record<string, unknown>>() => {
-    Autowired: (name: Extract<keyof S, string>) => MethodDecorator & ParameterDecorator & PropertyDecorator;
+    Autowired: ReturnType<typeof returnTypesafeInject<S>>;
 };
 export type { BeanConfig };
-export declare const ApplicationContext: <S extends Record<string, unknown>>(beanConfig: BeanConfig<S>, options?: ContainerOptions) => import("inversify-typesafe").TypesafeContainer<S>;
+export declare const ApplicationContext: <S extends Record<string, unknown>>(beanConfig: BeanConfig<S>, options?: ContainerOptions) => TypesafeContainer<S>;

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { ContainerOptions } from "inversify";
-import { TypesafeServiceConfig as BeanConfig } from "inversify-typesafe";
+import { TypesafeServiceConfig as BeanConfig, returnTypesafeInject, TypesafeContainer } from "inversify-typesafe";
 export declare const returnAutowired: <S extends Record<string, unknown>>() => {
-    Autowired: (name: Extract<keyof S, string>) => MethodDecorator & ParameterDecorator & PropertyDecorator;
+    Autowired: ReturnType<typeof returnTypesafeInject<S>>;
 };
 export type { BeanConfig };
-export declare const ApplicationContext: <S extends Record<string, unknown>>(beanConfig: BeanConfig<S>, options?: ContainerOptions) => import("inversify-typesafe").TypesafeContainer<S>;
+export declare const ApplicationContext: <S extends Record<string, unknown>>(beanConfig: BeanConfig<S>, options?: ContainerOptions) => TypesafeContainer<S>;

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":["../src/index.ts"],"sourcesContent":["import { ContainerOptions } from \"inversify\";\nimport { TypesafeServiceConfig as BeanConfig, createTypesafeContainer, returnTypesafeInject } from \"inversify-typesafe\";\n\nexport const returnAutowired = <S extends Record<string, unknown>>() => ({ Autowired: returnTypesafeInject<S>() });\n\nexport type { BeanConfig };\n\nexport const ApplicationContext = <S extends Record<string, unknown>>(beanConfig: BeanConfig<S>, options?: ContainerOptions) =>\n  createTypesafeContainer(beanConfig, { defaultScope: \"Singleton\", ...options });"],"names":["returnAutowired","Autowired","returnTypesafeInject","ApplicationContext","beanConfig","options","createTypesafeContainer","_extends","defaultScope"],"mappings":"+SAGa,MAAAA,EAAkBA,KAA0C,CAAEC,UAAWC,MAIzEC,EAAqBA,CAAoCC,EAA2BC,IAC/FC,EAAwBF,EAAUG,GAAIC,aAAc,aAAgBH"}
+{"version":3,"file":"index.js","sources":["../src/index.ts"],"sourcesContent":["import { ContainerOptions } from \"inversify\";\nimport { TypesafeServiceConfig as BeanConfig, createTypesafeContainer, returnTypesafeInject, TypesafeContainer } from \"inversify-typesafe\";\n\nexport const returnAutowired = <S extends Record<string, unknown>>(): { Autowired: ReturnType<typeof returnTypesafeInject<S>> } =>\n  ({ Autowired: returnTypesafeInject<S>() });\n\nexport type { BeanConfig };\n\nexport const ApplicationContext = <S extends Record<string, unknown>>(beanConfig: BeanConfig<S>, options?: ContainerOptions): TypesafeContainer<S> =>\n  createTypesafeContainer(beanConfig, { defaultScope: \"Singleton\", ...options });"],"names":["returnAutowired","Autowired","returnTypesafeInject","ApplicationContext","beanConfig","options","createTypesafeContainer","_extends","defaultScope"],"mappings":"+SAGa,MAAAA,EAAkBA,KAC5B,CAAEC,UAAWC,MAIHC,EAAqBA,CAAoCC,EAA2BC,IAC/FC,EAAwBF,EAAUG,GAAIC,aAAc,aAAgBH"}

package/dist/index.umd.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.umd.js","sources":["../src/index.ts"],"sourcesContent":["import { ContainerOptions } from \"inversify\";\nimport { TypesafeServiceConfig as BeanConfig, createTypesafeContainer, returnTypesafeInject } from \"inversify-typesafe\";\n\nexport const returnAutowired = <S extends Record<string, unknown>>() => ({ Autowired: returnTypesafeInject<S>() });\n\nexport type { BeanConfig };\n\nexport const ApplicationContext = <S extends Record<string, unknown>>(beanConfig: BeanConfig<S>, options?: ContainerOptions) =>\n  createTypesafeContainer(beanConfig, { defaultScope: \"Singleton\", ...options });"],"names":["beanConfig","options","createTypesafeContainer","_extends","defaultScope","Autowired","returnTypesafeInject"],"mappings":"2iBAOkC,SAAoCA,EAA2BC,GAC/F,OAAAC,EAAuBA,wBAACF,EAAUG,EAAIC,CAAAA,aAAc,aAAgBH,GAAU,oBALjD,WAAH,MAA6C,CAAEI,UAAWC,EAAAA,uBAA2B"}
+{"version":3,"file":"index.umd.js","sources":["../src/index.ts"],"sourcesContent":["import { ContainerOptions } from \"inversify\";\nimport { TypesafeServiceConfig as BeanConfig, createTypesafeContainer, returnTypesafeInject, TypesafeContainer } from \"inversify-typesafe\";\n\nexport const returnAutowired = <S extends Record<string, unknown>>(): { Autowired: ReturnType<typeof returnTypesafeInject<S>> } =>\n  ({ Autowired: returnTypesafeInject<S>() });\n\nexport type { BeanConfig };\n\nexport const ApplicationContext = <S extends Record<string, unknown>>(beanConfig: BeanConfig<S>, options?: ContainerOptions): TypesafeContainer<S> =>\n  createTypesafeContainer(beanConfig, { defaultScope: \"Singleton\", ...options });"],"names":["beanConfig","options","createTypesafeContainer","_extends","defaultScope","Autowired","returnTypesafeInject"],"mappings":"2iBAQkC,SAAoCA,EAA2BC,GAC/F,OAAAC,EAAuBA,wBAACF,EAAUG,EAAIC,CAAAA,aAAc,aAAgBH,GAAU,oBANjD,WAAH,MACzB,CAAEI,UAAWC,EAAAA,uBAA2B"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "inversify-typesafe-spring-like",
   "type": "module",
-  "version": "0.5.5",
+  "version": "0.5.6",
   "description": "Add-On Library for inversify-typesafe to make it more like Spring.",
   "source": "src/index.ts",
   "exports": {
@@ -61,6 +61,7 @@
   "author": "Myeongjae Kim",
   "license": "MIT",
   "dependencies": {
-    "inversify-typesafe": "^0.5.4"
+    "inversify": "^7.10.8",
+    "inversify-typesafe": "^0.5.6"
   }
 }