@adimm/x-injection-reactjs 1.0.4 → 1.0.6

package/README.md

@@ -12,41 +12,134 @@
 <a href="https://www.npmjs.com/package/@adimm/x-injection-reactjs" target="__blank"><img src="https://badgen.net/npm/dm/@adimm/x-injection-reactjs"></a>
 </p>
 
-**Powerful dependency injection for React components using a modular architecture. Build scalable React applications with clean separation of concerns.** _(Inspired by Angular and NestJS IoC/DI)_
+**Stop wrestling with React Context and prop drilling. Build scalable React apps with clean, testable business logic separated from UI.**
+
+> **TL;DR** — Mark classes with `@Injectable()`, declare a `ProviderModule.blueprint()`, wrap your component with `provideModuleToComponent(MyModuleBp, () => { ... })`, then call `useInject(MyService)` inside. Dependencies are resolved automatically — no providers, no prop drilling, no manual wiring.
 
 ## Table of Contents
 
 - [Table of Contents](#table-of-contents)
-- [Overview](#overview)
+- [What Problems Does This Solve?](#what-problems-does-this-solve)
+  - [1. Provider Hell](#1-provider-hell)
+  - [2. Prop Drilling](#2-prop-drilling)
+  - [3. Manual Dependency Wiring](#3-manual-dependency-wiring)
+  - [4. Business Logic Mixed with UI](#4-business-logic-mixed-with-ui)
 - [Installation](#installation)
 - [Quick Start](#quick-start)
-- [The Problem](#the-problem)
-  - [Without xInjection](#without-xinjection)
-  - [With xInjection](#with-xinjection)
-- [Core Concepts](#core-concepts)
-  - [Component Modules](#component-modules)
-  - [Services](#services)
-  - [Dependency Injection](#dependency-injection)
-  - [Custom Hooks](#custom-hooks)
-- [Examples](#examples)
-  - [Zustand Integration](#zustand-integration)
-  - [Parent-Child Provider Control](#parent-child-provider-control)
-- [Advanced Usage](#advanced-usage)
+- [How It Works](#how-it-works)
+  - [1. Services: Your Business Logic](#1-services-your-business-logic)
+  - [2. Modules: Organizing Dependencies](#2-modules-organizing-dependencies)
+  - [3. Injecting Services into Components](#3-injecting-services-into-components)
+- [The Power of Component-Scoped Modules](#the-power-of-component-scoped-modules)
+  - [What Are Component-Scoped Modules?](#what-are-component-scoped-modules)
+  - [Pattern 1: Multiple Independent Instances](#pattern-1-multiple-independent-instances)
+  - [Pattern 2: Parent-Child Dependency Control](#pattern-2-parent-child-dependency-control)
+- [Why Use the HoC Approach?](#why-use-the-hoc-approach)
+  - [1. Lifecycle-Bound Isolated Containers](#1-lifecycle-bound-isolated-containers)
+  - [2. Composition and Reusability](#2-composition-and-reusability)
+- [Hierarchical Dependency Injection](#hierarchical-dependency-injection)
+  - [Creating Custom Hooks with Dependencies](#creating-custom-hooks-with-dependencies)
+  - [Parent Components Controlling Child Dependencies](#parent-components-controlling-child-dependencies)
   - [Module Imports and Exports](#module-imports-and-exports)
-  - [Multiple Dependency Injection](#multiple-dependency-injection)
-- [Unit Testing](#unit-testing)
-- [Documentation](#documentation)
+- [Real-World Examples](#real-world-examples)
+  - [Zustand Store Integration](#zustand-store-integration)
+  - [Complex Form with Shared State](#complex-form-with-shared-state)
+- [Testing Your Code](#testing-your-code)
+  - [Mocking an Entire Module](#mocking-an-entire-module)
+  - [Mocking on-the-fly](#mocking-on-the-fly)
+- [FAQ](#faq)
+  - [How do I add global services?](#how-do-i-add-global-services)
+  - [When should I use global modules vs component-scoped modules?](#when-should-i-use-global-modules-vs-component-scoped-modules)
+  - [Can I use this with Redux/MobX/Zustand?](#can-i-use-this-with-reduxmobxzustand)
+  - [How does this compare to React Context?](#how-does-this-compare-to-react-context)
+  - [If I want Angular patterns, why not just use Angular?](#if-i-want-angular-patterns-why-not-just-use-angular)
+  - [Can I migrate gradually from an existing React app?](#can-i-migrate-gradually-from-an-existing-react-app)
+  - [When do I actually need `provideModuleToComponent`?](#when-do-i-actually-need-providemoduletocomponent)
+  - [What's the performance impact?](#whats-the-performance-impact)
+  - [Why use classes for services instead of custom hooks?](#why-use-classes-for-services-instead-of-custom-hooks)
+- [Links](#links)
 - [Contributing](#contributing)
 - [License](#license)
 
-## Overview
+## What Problems Does This Solve?
+
+If you've built React apps, you've probably encountered these pain points:
+
+### 1. Provider Hell
+
+Your `App.tsx` becomes a nightmare of nested providers:
+
+```tsx
+<AuthProvider>
+  <ThemeProvider>
+    <ApiProvider>
+      <ToastProvider>
+        <UserProvider>
+          <App />
+        </UserProvider>
+      </ToastProvider>
+    </ApiProvider>
+  </ThemeProvider>
+</AuthProvider>
+```
+
+### 2. Prop Drilling
+
+You pass props through 5 levels of components just to reach the one that needs them:
+
+```tsx
+<Dashboard user={user}>
+  <Sidebar user={user}>
+    <UserMenu user={user}>
+      <UserAvatar user={user} /> {/* Finally! */}
+    </UserMenu>
+  </Sidebar>
+</Dashboard>
+```
+
+### 3. Manual Dependency Wiring
+
+When a service needs dependencies, you manually create them in the right order:
+
+```tsx
+function UserProfile() {
+  // Must create ALL dependencies manually in correct order
+  const toastService = new ToastService();
+  const apiService = new ApiService();
+  const authService = new AuthService(apiService);
+  const userProfileService = new UserProfileService(apiService, authService, toastService);
+
+  // If AuthService adds a new dependency tomorrow, THIS BREAKS!
+  return <div>{userProfileService.displayName}</div>;
+}
+```
+
+### 4. Business Logic Mixed with UI
+
+Your components become bloated with API calls, state management, and validation:
 
-xInjection for React brings dependency injection to your React components, enabling:
+```tsx
+function UserDashboard() {
+  const [user, setUser] = useState(null);
+  const [loading, setLoading] = useState(false);
+
+  useEffect(() => {
+    setLoading(true);
+    fetch('/api/user')
+      .then((res) => res.json())
+      .then((data) => {
+        setUser(data);
+        setLoading(false);
+      });
+  }, []);
+
+  // 50 more lines of business logic...
+
+  return <div>{/* Your actual UI */}</div>;
+}
+```
 
-- **Service-based architecture**: Separate business logic from UI components
-- **Modular design**: Create reusable, testable component modules
-- **State management integration**: Works seamlessly with Zustand, Redux, or any state library
-- **Parent-child provider control**: Parent components can control child component dependencies
+xInjection solves all of the above by bringing **Inversion of Control (IoC)** and **Dependency Injection (DI)** to React: instead of components creating and managing their own dependencies, they just ask for what they need and xInjection provides it — automatically, type-safely, and testably.
 
 This is the official [ReactJS](https://react.dev/) implementation of [xInjection](https://github.com/AdiMarianMutu/x-injection).
 
@@ -56,6 +149,21 @@ This is the official [ReactJS](https://react.dev/) implementation of [xInjection
 npm i @adimm/x-injection-reactjs reflect-metadata
 ```
 
+> [!IMPORTANT]
+> Import `reflect-metadata` at the very top of your app entry point:
+
+```tsx
+// main.tsx or index.tsx
+
+import 'reflect-metadata';
+
+import { createRoot } from 'react-dom/client';
+
+import App from './App';
+
+createRoot(document.getElementById('root')!).render(<App />);
+```
+
 **TypeScript Configuration**
 
 Add to your `tsconfig.json`:
@@ -69,171 +177,605 @@ Add to your `tsconfig.json`:
 }
 ```
 
+> **📚 Advanced Concepts**
+>
+> This documentation covers React-specific usage patterns. For advanced features like **lifecycle hooks** (`onReady`, `onDispose`), **injection scopes** (Singleton, Transient, Request), **middlewares**, **events**, and **dynamic module updates**, refer to the [base xInjection library documentation](https://github.com/AdiMarianMutu/x-injection).
+>
+> The base library provides the core IoC/DI engine that powers this React integration.
+
 ## Quick Start
 
+Three files, three concepts: global services declared once, a component-scoped module, and a component that injects both.
+
+**Step 1 — Declare global services** in your entry point:
+
 ```tsx
-import { Injectable, provideModuleToComponent, ProviderModule, useInject } from '@adimm/x-injection-reactjs';
+// main.tsx - Your app entry point
+
+import 'reflect-metadata';
+
+import { Injectable, ProviderModule } from '@adimm/x-injection';
+import { createRoot } from 'react-dom/client';
+
+import App from './App';
 
-// 1. Define a service
+// Global services (singletons)
 @Injectable()
-class UserService {
-  firstName = 'John';
-  lastName = 'Doe';
+class ApiService {
+  get(url: string) {
+    return fetch(url).then((r) => r.json());
+  }
 }
 
-// 2. Create a module blueprint
+@Injectable()
+class AuthService {
+  constructor(private readonly apiService: ApiService) {}
+
+  isLoggedIn = false;
+
+  login() {
+    this.isLoggedIn = true;
+  }
+}
+
+// Create global module - automatically imported into built-in AppModule
+ProviderModule.blueprint({
+  id: 'AppBootstrapModule',
+  isGlobal: true,
+  providers: [ApiService, AuthService],
+  exports: [ApiService, AuthService], // Exported services available everywhere
+});
+
+// Now render your app
+createRoot(document.getElementById('root')!).render(<App />);
+```
+
+**Step 2 — Create a component-scoped module and inject services:**
+
+```tsx
+// UserDashboard.tsx - A component with its own service
+
+import { Injectable, ProviderModule } from '@adimm/x-injection';
+import { provideModuleToComponent, useInject } from '@adimm/x-injection-reactjs';
+
+// Component-scoped service
+@Injectable()
+class UserDashboardService {
+  constructor(private readonly apiService: ApiService) {} // Gets global ApiService
+
+  async loadUser() {
+    return this.apiService.get('/user');
+  }
+}
+
+// Component-scoped module
 const UserDashboardModuleBp = ProviderModule.blueprint({
   id: 'UserDashboardModule',
-  providers: [UserService],
+  providers: [UserDashboardService],
 });
 
-// 3. Create a component with dependency injection
-const UserDashboard = provideModuleToComponent(UserDashboardModuleBp, () => {
-  const userService = useInject(UserService);
+// Component with injected service
+export const UserDashboard = provideModuleToComponent(UserDashboardModuleBp, () => {
+  const dashboardService = useInject(UserDashboardService);
+  const authService = useInject(AuthService); // Can also inject global services
 
   return (
-    <h1>
-      Hello {userService.firstName} {userService.lastName}!
-    </h1>
+    <div>
+      <h1>Dashboard</h1>
+      <p>Logged in: {authService.isLoggedIn ? 'Yes' : 'No'}</p>
+    </div>
   );
 });
 ```
 
-## The Problem
+**Step 3 — Use the component** — each instance gets its own module:
 
-React apps often suffer from **provider hell**, **prop drilling**, and **manual dependency wiring**:
+```tsx
+// App.tsx
 
-### Without xInjection
+import { UserDashboard } from './UserDashboard';
+
+export default function App() {
+  return (
+    <div>
+      <UserDashboard />
+      <UserDashboard /> {/* Each gets its own UserDashboardService */}
+    </div>
+  );
+}
+```
+
+> [!TIP] Global vs component-scoped services:
+>
+> - Global services (`ApiService`, `AuthService`): Defined in a global blueprint, automatically imported into the built-in `AppModule`
+> - Component-scoped services (`UserDashboardService`): Fresh instance per `<UserDashboard />`
+> - Component-scoped services can inject global services automatically
+
+## How It Works
+
+Let's break down the three main concepts you'll use:
+
+### 1. Services: Your Business Logic
+
+A **service** is just a class that contains your business logic. Think of it as extracting all the "smart stuff" from your component into a reusable, testable class.
 
 ```tsx
-// Problem 1: Provider Hell
-<AuthProvider>
-  <ApiProvider>
-    <ToastProvider>
-      <App />
-    </ToastProvider>
-  </ApiProvider>
-</AuthProvider>;
-
-// Problem 2: Manual Dependency Wiring
-function UserProfile() {
-  // Must manually create ALL dependencies in correct order
-  const toast = new ToastService();
-  const api = new ApiService();
-  const auth = new AuthService(api);
-  const userProfile = new UserProfileService(api, auth, toast);
-
-  // If AuthService adds a dependency, ALL consumers break!
-  return <div>{userProfile.displayName}</div>;
+@Injectable()
+class TodoService {
+  private todos: Todo[] = [];
+
+  addTodo(text: string) {
+    this.todos.push({ id: Date.now(), text, completed: false });
+  }
+
+  getTodos() {
+    return this.todos;
+  }
+
+  toggleTodo(id: number) {
+    const todo = this.todos.find((t) => t.id === id);
+    if (todo) todo.completed = !todo.completed;
+  }
 }
 ```
 
-### With xInjection
+The `@Injectable()` decorator marks this class as something that can be injected (either into components or other services/modules).
+
+**Services can depend on other services:**
 
 ```tsx
-// 1. Define global services (shared across all components) - Usually in your app entrypoint/bootstrap file.
-const AppModuleBp = ProviderModule.blueprint({
-  id: 'AppModule',
-  isGlobal: true, // Available everywhere, only created once
-  providers: [ToastService, ApiService, AuthService],
+@Injectable()
+class UserProfileService {
+  // Dependencies are automatically injected via constructor
+  constructor(
+    private readonly apiService: ApiService,
+    private readonly authService: AuthService,
+    private readonly toastService: ToastService
+  ) {}
+
+  async loadProfile() {
+    try {
+      const userId = this.authService.getCurrentUserId();
+      const profile = await this.apiService.get(`/users/${userId}`);
+      return profile;
+    } catch (error) {
+      this.toastService.error('Failed to load profile');
+      throw error;
+    }
+  }
+}
+```
+
+Notice how `UserProfileService` asks for its dependencies in the constructor? xInjection will automatically provide them.
+
+**Alternative: Property Injection**
+
+You can also use the `@Inject` decorator from the base library for property injection:
+
+```tsx
+import { Inject, Injectable } from '@adimm/x-injection';
+
+@Injectable()
+class UserProfileService {
+  @Inject(ApiService)
+  private readonly apiService!: ApiService;
+
+  @Inject(AuthService)
+  private readonly authService!: AuthService;
+
+  async loadProfile() {
+    const userId = this.authService.getCurrentUserId();
+    return this.apiService.get(`/users/${userId}`);
+  }
+}
+```
+
+Both approaches work! Constructor injection is generally preferred for better type safety and easier testing.
+
+### 2. Modules: Organizing Dependencies
+
+A **module** is a container that tells xInjection which services are available. Think of it as a "package" of services.
+
+**Modules come in two flavors:**
+
+```tsx
+// Global module: Created once, shared everywhere
+ProviderModule.blueprint({
+  id: 'AppBootstrapModule',
+  isGlobal: true,
+  providers: [ApiService, AuthService, ToastService],
+  exports: [ApiService, AuthService, ToastService], // Only exported services become globally available
 });
 
-// 2. Define component-specific services - Per component
-const UserProfileModuleBp = ProviderModule.blueprint({
-  id: 'UserProfileModule',
-  providers: [UserProfileService], // Automatically gets ApiService, AuthService, ToastService
+// Component-scoped module: Each component instance gets its own
+const TodoListModuleBp = ProviderModule.blueprint({
+  id: 'TodoListModule',
+  providers: [TodoService], // Gets a fresh TodoService per component
 });
+```
+
+> [!IMPORTANT]
+> When using `isGlobal: true`, only services listed in the `exports` array become globally available. Non-exported providers remain private to the module.
+
+> [!CAUTION] Global modules cannot be used with `provideModuleToComponent`
+> Attempting to provide a global module to a component will throw an `InjectionProviderModuleError`. Global services are accessed directly via `useInject` without the HoC.
+
+**`blueprint()` vs `create()`:**
+
+- **`blueprint()`**: A deferred module template. Each time it is imported or used with `provideModuleToComponent`, a **new independent instance** is created. Use for the global bootstrap module and for component-scoped modules. [Learn more](https://github.com/AdiMarianMutu/x-injection?tab=readme-ov-file#blueprints).
+- **`create()`**: Immediately instantiates a module. The resulting instance is a **single shared object** — every module that imports it shares the exact same instance. Use when you need a module that is instantiated once and shared across multiple other modules.
+
+See [Module Imports and Exports](#module-imports-and-exports) for examples of both.
 
-const UserProfile = provideModuleToComponent(UserProfileModuleBp, () => {
-  const userProfile = useInject(UserProfileService);
-  // IoC automatically injects: ToastService → ApiService → AuthService → UserProfileService
-  return <div>{userProfile.displayName}</div>;
+> [!CAUTION] Never import `AppModule` into other modules
+> `AppModule` is the built-in global container and importing it will throw an error. Use global blueprints with `isGlobal: true` instead, which are automatically imported into `AppModule`.
+
+### 3. Injecting Services into Components
+
+Use the `provideModuleToComponent` Higher-Order Component (HoC) to give your component access to services:
+
+```tsx
+const UserDashboard = provideModuleToComponent(UserDashboardModuleBp, () => {
+  // Inject the service you need
+  const userProfileService = useInject(UserProfileService);
+
+  return <div>{userProfileService.displayName}</div>;
 });
 ```
 
-**What You Get:**
+The HoC does two things:
 
-- **No Provider Hell** - One module replaces nested providers
-- **Auto Dependency Resolution** - IoC wires everything automatically
-- **Easy Refactoring** - Add/remove dependencies without breaking consumers
-- **Clean Separation** - Business logic in services, UI in components
-- **Fully Testable** - Mock modules or individual services
-- **Type-Safe** - Full TypeScript support
+1. Creates an instance of your module (and all its services)
+2. Makes those services available via the `useInject` hook
 
-## Core Concepts
+**You can also inject multiple services at once:**
 
-### Component Modules
+```tsx
+const MyComponent = provideModuleToComponent(MyModuleBp, () => {
+  const [userService, apiService] = useInjectMany(UserService, ApiService);
 
-Create a module blueprint that defines your component's dependencies:
+  // Use your services...
+});
+```
 
-```ts
-// user-dashboard.module.ts
-export const UserDashboardModuleBp = ProviderModule.blueprint({
-  id: 'UserDashboardModule',
-  providers: [UserService],
-  exports: [UserService],
+## The Power of Component-Scoped Modules
+
+One of the most powerful features of xInjection is **component-scoped modules**. This is something you can't easily achieve with React Context alone.
+
+### What Are Component-Scoped Modules?
+
+When you use `provideModuleToComponent`, each instance of your component gets its **own copy** of the module and all its services. This enables powerful patterns:
+
+### Pattern 1: Multiple Independent Instances
+
+```tsx
+@Injectable()
+class CounterService {
+  count = 0;
+  increment() {
+    this.count++;
+  }
+}
+
+const CounterModuleBp = ProviderModule.blueprint({
+  id: 'CounterModule',
+  providers: [CounterService],
+});
+
+const Counter = provideModuleToComponent(CounterModuleBp, () => {
+  const counterService = useInject(CounterService);
+  return (
+    <div>
+      <p>Count: {counterService.count}</p>
+      <button onClick={() => counterService.increment()}>+</button>
+    </div>
+  );
 });
+
+function App() {
+  return (
+    <div>
+      <Counter /> {/* Count: 0 */}
+      <Counter /> {/* Count: 0 (separate instance!) */}
+    </div>
+  );
+}
 ```
 
-**Blueprint vs Module:** Use a **blueprint** for reusable components (multiple instances), use a raw **module** for singleton components (single instance).
+Each `<Counter />` has its own `CounterService`, so they don't interfere with each other.
 
-### Services
+### Pattern 2: Parent-Child Dependency Control
 
-Define services using the `@Injectable()` decorator:
+Parent components can "inject" specific service instances into their children:
 
-```ts
-// user-dashboard.service.ts
+```tsx
+const ParentModuleBp = ProviderModule.blueprint({
+  id: 'ParentModule',
+  providers: [SharedService, ParentService],
+});
+
+const ChildModuleBp = ProviderModule.blueprint({
+  id: 'ChildModule',
+  providers: [SharedService, ChildService],
+});
+
+const Child = provideModuleToComponent(ChildModuleBp, () => {
+  const sharedService = useInject(SharedService);
+  return <div>{sharedService.data}</div>;
+});
+
+const Parent = provideModuleToComponent(ParentModuleBp, () => {
+  const sharedService = useInject(SharedService);
+
+  // Pass the parent's SharedService instance to the child
+  return <Child inject={[{ provide: SharedService, useValue: sharedService }]} />;
+});
+```
+
+This enables complex patterns like form components sharing validation services, or composite UI components coordinating state.
+
+## Why Use the HoC Approach?
+
+You might wonder: "Why wrap my component with `provideModuleToComponent` instead of just using `useInject` directly everywhere?"
+
+**Short answer:** You don't always need it! If you only use global services, you can just call `useInject` anywhere. But for **component-scoped modules** (where each component instance needs its own services), you need `provideModuleToComponent`.
+
+The Higher-Order Component (HoC) pattern provides several key benefits:
+
+### 1. Lifecycle-Bound Isolated Containers
+
+Each wrapped component gets its **own** dependency container, created on mount and disposed on unmount. Two instances of `<TodoList />` each get their own `TodoService` — they never share state. When the component unmounts, `onDispose` runs automatically, cleaning up only that component's services. Imported global services remain unaffected.
+
+### 2. Composition and Reusability
+
+The HoC pattern works seamlessly with React's component composition model:
+
+```tsx
+// Reusable component with its own dependencies
+const TodoList = provideModuleToComponent(TodoListModuleBp, () => {
+  const todoService = useInject(TodoService);
+  // ...
+});
+
+// Use it multiple times, each with isolated state
+function App() {
+  return (
+    <>
+      <TodoList /> {/* Gets its own TodoService */}
+      <TodoList /> {/* Gets a different TodoService */}
+    </>
+  );
+}
+```
+
+## Hierarchical Dependency Injection
+
+Every component wrapped with `provideModuleToComponent` gets its own module container. When `useInject` is called inside that component, xInjection walks a well-defined lookup chain:
+
+1. **Own module** — services declared in the component's own blueprint
+2. **Imported modules** — exported services from modules listed in `imports`
+3. **AppModule** — globally available services (from `isGlobal: true` blueprints)
+
+```
+useInject(SomeService)  ← called inside <MyComponent />
+          │
+          ▼
+┌─────────────────────────┐
+│   MyComponent's module  │  ← providers: [MyService, ...]
+│     (own container)     │
+└───────────┬─────────────┘
+            │ not found
+            ▼
+┌─────────────────────────┐
+│   Imported modules      │  ← imports: [SharedModule]
+│   (exported only)       │     SharedModule.exports: [SharedService]
+└───────────┬─────────────┘
+            │ not found
+            ▼
+┌─────────────────────────┐
+│       AppModule         │  ← AppBootstrapModule { isGlobal: true }
+│  (global services)      │     exports: [ApiService, AuthService, ...]
+└───────────┬─────────────┘
+            │ not found
+            ▼
+      throws error
+```
+
+**Component example:**
+
+```tsx
+// ① Global services — live in AppModule, available everywhere
 @Injectable()
-export class UserDashboardService {
-  firstName: string;
-  lastName: string;
+class ApiService {}
+@Injectable()
+class AuthService {}
 
-  getFullName() {
-    return `${this.firstName} ${this.lastName}`;
-  }
+ProviderModule.blueprint({
+  id: 'AppBootstrapModule',
+  isGlobal: true,
+  providers: [ApiService, AuthService],
+  exports: [ApiService, AuthService],
+});
+
+// ② Shared module — created once, imported into component blueprints
+@Injectable()
+class AnalyticsService {}
+
+const SharedModule = ProviderModule.create({
+  id: 'SharedModule',
+  providers: [AnalyticsService],
+  exports: [AnalyticsService], // ✅ visible to importers
+});
+
+// ③ Component-scoped service — private to this component
+@Injectable()
+class DashboardService {
+  constructor(
+    private readonly api: ApiService, // resolved from ③ AppModule
+    private readonly analytics: AnalyticsService // resolved from ② SharedModule
+  ) {}
 }
+
+const DashboardModuleBp = ProviderModule.blueprint({
+  id: 'DashboardModule',
+  imports: [SharedModule],
+  providers: [DashboardService], // ① own container
+});
+
+const Dashboard = provideModuleToComponent(DashboardModuleBp, () => {
+  const dashboard = useInject(DashboardService); // ✅ ① own module
+  const analytics = useInject(AnalyticsService); // ✅ ② SharedModule export
+  const auth = useInject(AuthService); // ✅ ③ AppModule (global)
+
+  // useInject(SomePrivateService)               // ❌ not found → error
+});
 ```
 
-### Dependency Injection
+> [!TIP]
+> A service that is not listed in a module's `exports` is completely invisible to any component that imports that module. This is how xInjection enforces encapsulation — only what you explicitly export crosses the module boundary.
 
-Use `useInject` to access services in your components:
+### Creating Custom Hooks with Dependencies
+
+The `hookFactory` function lets you create reusable custom hooks that automatically receive injected dependencies:
 
 ```tsx
-const UserDashboard = provideModuleToComponent(UserDashboardModuleBp, () => {
-  const userService = useInject(UserService);
+// Define a custom hook with dependencies
+const useUserProfile = hookFactory({
+  use: ({ userId, deps: [apiService, authService] }) => {
+    const [profile, setProfile] = useState(null);
 
-  return <div>{userService.getFullName()}</div>;
+    useEffect(() => {
+      apiService.get(`/users/${userId}`).then(setProfile);
+    }, [userId]);
+
+    return profile;
+  },
+  inject: [ApiService, AuthService],
+});
+
+// Use it in any component
+const UserProfile = provideModuleToComponent<{ userId: number }>(UserModuleBp, ({ userId }) => {
+  const profile = useUserProfile({ userId });
+  return <div>{profile?.name}</div>;
 });
 ```
 
-### Custom Hooks
+**Type-safe hooks with `HookWithDeps`:**
 
-Create reusable hooks with dependency injection using `hookFactory`:
+Use the `HookWithDeps<P, D>` type utility for full TypeScript support:
 
-```ts
-const useUserFullName = hookFactory({
-  use: ({ firstName, lastName, deps: [userService] }) => {
-    userService.firstName = firstName;
-    userService.lastName = lastName;
-    return userService.getFullName();
+```tsx
+import type { HookWithDeps } from '@adimm/x-injection-reactjs';
+
+// Hook with no parameters - use void as first generic
+const useTestHook = hookFactory({
+  use: ({ deps: [testService] }: HookWithDeps<void, [TestService]>) => {
+    return testService.value;
+  },
+  inject: [TestService],
+});
+
+// Hook with parameters - specify parameter type as first generic
+const useUserData = hookFactory({
+  use: ({ userId, deps: [apiService] }: HookWithDeps<{ userId: number }, [ApiService]>) => {
+    const [data, setData] = useState(null);
+    useEffect(() => {
+      apiService.get(`/users/${userId}`).then(setData);
+    }, [userId]);
+    return data;
   },
-  inject: [UserService],
+  inject: [ApiService],
 });
 
-// Use in any component
-const fullName = useUserFullName({ firstName: 'John', lastName: 'Doe' });
+// Usage:
+useTestHook(); // No parameters
+useUserData({ userId: 123 }); // With parameters
 ```
 
-## Examples
+**`HookWithDeps<P, D>` generics:**
+
+- **`P`**: Hook parameter type (use `void` if no parameters, or `{ param1: type, ... }` for parameters)
+- **`D`**: Tuple type matching your `inject` array (e.g., `[ApiService, AuthService]`)
+
+> [!TIP] Why use hookFactory?
+>
+> - Dependencies are automatically injected
+> - Hooks are reusable across components
+> - Type-safe with TypeScript
+> - Easier to test (mock dependencies)
+
+### Parent Components Controlling Child Dependencies
+
+The `inject` prop allows parent components to override child component dependencies. See [Pattern 2](#pattern-2-parent-child-dependency-control) for a basic example and the [Complex Form example](#complex-form-with-shared-state) for a real-world use case.
+
+### Module Imports and Exports
+
+Modules can import other modules. The key question is: **should the imported module be shared or duplicated per component?**
+
+**Shared module instance → `ProviderModule.create()`:**
+
+Use `create()` when a module should exist as one instance and be shared by all blueprints that import it:
+
+```tsx
+// Instantiated once — all importers share the same instance and the same singletons
+const CoreModule = ProviderModule.create({
+  id: 'CoreModule',
+  providers: [SomeSharedService],
+  exports: [SomeSharedService],
+});
 
-### Zustand Integration
+const UserModuleBp = ProviderModule.blueprint({
+  id: 'UserModule',
+  imports: [CoreModule], // every <UserComponent /> shares the same CoreModule
+  providers: [UserService],
+});
+
+const ProductModuleBp = ProviderModule.blueprint({
+  id: 'ProductModule',
+  imports: [CoreModule], // same CoreModule instance
+  providers: [ProductService],
+});
+```
 
-This example shows how to integrate Zustand store within a service, allowing the service to manipulate the store while components only subscribe to state changes.
+**Per-component isolation → blueprint imports:**
+
+Import a blueprint when each component instance should get its own independent copy of those providers:
+
+```tsx
+const UserModuleBp = ProviderModule.blueprint({
+  id: 'UserModule',
+  imports: [FormValidationModuleBp], // each <UserComponent /> gets its own FormValidationService
+  providers: [UserService],
+});
+```
+
+**Re-exporting:**
+
+```tsx
+const CoreModule = ProviderModule.create({
+  id: 'CoreModule',
+  imports: [DatabaseModule, CacheModule],
+  exports: [DatabaseModule, CacheModule], // expose both to importers
+});
+```
+
+## Real-World Examples
+
+### Zustand Store Integration
+
+xInjection works beautifully with Zustand. The pattern is simple: **encapsulate the Zustand store inside a service**. This keeps your business logic in services while using Zustand for reactive state.
+
+**Why this pattern?**
+
+- Business logic stays in services (testable, reusable)
+- Components subscribe to state reactively (optimal re-renders)
+- Store is scoped to the component (no global state pollution)
+- Type-safe and easy to test
 
 ```ts
 // counter.service.ts
 
-import { Injectable } from '@adimm/x-injection-reactjs';
+import { Injectable } from '@adimm/x-injection';
 import { create } from 'zustand';
 
 interface CounterStore {
@@ -293,7 +835,7 @@ export class CounterService {
 ```ts
 // counter.module.ts
 
-import { ProviderModule } from '@adimm/x-injection-reactjs';
+import { ProviderModule } from '@adimm/x-injection';
 
 import { CounterService } from './counter.service';
 
@@ -342,138 +884,324 @@ export default Counter;
 - **Reusability**: Services with stores can be shared across components via dependency injection
 - **Type safety**: Full TypeScript support throughout
 
-### Parent-Child Provider Control
+### Complex Form with Shared State
 
-Parent components can control child component dependencies using the `inject` prop:
+This example demonstrates a powerful pattern: a parent form component controlling the state of multiple child input components.
 
-```ts
-// Child module and service
-const ChildModuleBp = ProviderModule.blueprint({
-  id: 'ChildModule',
-  providers: [ChildService],
-  exports: [ChildService],
-});
+```tsx
+import { Inject, Injectable, InjectionScope } from '@adimm/x-injection';
 
-// Parent module
-const ParentModuleBp = ProviderModule.blueprint({
-  id: 'ParentModule',
-  providers: [ParentService, ChildService],
-  exports: [ParentService, ChildService],
-});
+// 1. Input service - manages a single input's state
+@Injectable()
+class InputService {
+  value = '';
+  error = '';
 
-// Parent component controls child's service
-const ParentComponent = provideModuleToComponent(ParentModuleBp, () => {
-  const childService = useInject(ChildService);
+  setValue(value: string) {
+    this.value = value;
+    this.validate();
+  }
 
-  // Override child's ChildService with parent's instance
-  return <ChildComponent inject={[{ provide: ChildService, useValue: childService }]} />;
-});
-```
+  validate() {
+    if (!this.value) {
+      this.error = 'Required';
+    } else if (this.value.length < 3) {
+      this.error = 'Too short';
+    } else {
+      this.error = '';
+    }
+    return !this.error;
+  }
+}
 
-This pattern is useful for:
+// 2. Form service - manages the entire form
+@Injectable()
+class FormService {
+  constructor(
+    public readonly nameInput: InputService,
+    public readonly emailInput: InputService
+  ) {
+    // Initialize with default values
+    this.nameInput.setValue('');
+    this.emailInput.setValue('');
+  }
 
-- Building composable component hierarchies
-- Sharing state between parent and child components
-- Creating flexible component APIs
+  isValid() {
+    return this.nameInput.validate() && this.emailInput.validate();
+  }
 
-## Advanced Usage
+  submit() {
+    if (this.isValid()) {
+      console.log('Submitting:', {
+        name: this.nameInput.value,
+        email: this.emailInput.value,
+      });
+    }
+  }
+}
 
-### Module Imports and Exports
+// 3. Input component
+const InputModuleBp = ProviderModule.blueprint({
+  id: 'InputModule',
+  providers: [InputService],
+  exports: [InputService],
+});
 
-Modules can import and re-export other modules:
+const Input = provideModuleToComponent<{ label: string }>(InputModuleBp, ({ label }) => {
+  const inputService = useInject(InputService);
+  const [value, setValue] = useState(inputService.value);
 
-```ts
-const DropdownModuleBp = ProviderModule.blueprint({
-  id: 'DropdownModule',
-  imports: [ListviewModuleBp], // Import ListviewModule
-  providers: [DropdownService],
-  exports: [
-    ListviewModuleBp, // Re-export imported module
-    DropdownService,
+  return (
+    <div>
+      <label>{label}</label>
+      <input
+        value={value}
+        onChange={(e) => {
+          setValue(e.target.value);
+          inputService.setValue(e.target.value);
+        }}
+      />
+      {inputService.error && <span style={{ color: 'red' }}>{inputService.error}</span>}
+    </div>
+  );
+});
+
+// 4. Form component - injects its InputService instances into child Input components
+const FormModuleBp = ProviderModule.blueprint({
+  id: 'FormModule',
+  imports: [
+    // Clone InputModuleBp and override its defaultScope to Transient for this specific use.
+    // Without Transient, both `nameInput` and `emailInput` in FormService would resolve to
+    // the same singleton — they'd share state. Transient ensures each @Inject(InputService)
+    // parameter in FormService's constructor gets its own independent instance.
+    // This is also a good showcase of blueprint dynamicity: the original InputModuleBp is
+    // left untouched, and only this consumer opts into Transient behavior.
+    InputModuleBp.clone().updateDefinition({
+      ...InputModuleBp.getDefinition(),
+      defaultScope: InjectionScope.Transient,
+    }),
   ],
+  providers: [FormService],
+  exports: [FormService],
+});
+
+const Form = provideModuleToComponent(FormModuleBp, () => {
+  const formService = useInject(FormService);
+
+  return (
+    <form>
+      {/* Pass the form's InputService instances to the inputs */}
+      <Input inject={[{ provide: InputService, useValue: formService.nameInput }]} label="Name" />
+      <Input inject={[{ provide: InputService, useValue: formService.emailInput }]} label="Email" />
+      <button type="button" onClick={() => formService.submit()}>
+        Submit
+      </button>
+    </form>
+  );
 });
 ```
 
-### Multiple Dependency Injection
+**What's happening here?**
 
-Use `useInjectMany` to inject multiple dependencies:
+1. Each `Input` component normally gets its own `InputService`
+2. The `Form` component creates two `InputService` instances in its constructor
+3. The form **overrides** the input's services using the `inject` prop
+4. All inputs share state through the parent form's services
 
-```ts
-const [userService, apiService] = useInjectMany([UserService, ApiService]);
-```
+## Testing Your Code
 
-## Unit Testing
+xInjection makes testing easy. You can mock entire modules or individual services.
 
-Mock modules easily for testing:
+### Mocking an Entire Module
 
 ```tsx
 import { act, render } from '@testing-library/react';
 
 // Original module
-const ApiModuleBp = ProviderModule.blueprint({
-  id: 'ApiModule',
+const UserModuleBp = ProviderModule.blueprint({
+  id: 'UserModule',
   providers: [UserService, ApiService],
 });
 
-// Create mocked version
-const ApiModuleBpMocked = ApiModuleBp.clone().updateDefinition({
-  id: 'ApiModuleMocked',
+// Create a mocked version
+const UserModuleMocked = UserModuleBp.clone().updateDefinition({
+  id: 'UserModuleMocked',
   providers: [
-    { provide: UserService, useClass: UserServiceMock },
+    {
+      provide: UserService,
+      useClass: UserServiceMock, // Your mock class
+    },
     {
       provide: ApiService,
       useValue: {
-        sendRequest: vi.fn().mockResolvedValue({ data: 'mocked' }),
+        get: vi.fn().mockResolvedValue({ name: 'Test User' }),
+        post: vi.fn(),
       },
     },
   ],
 });
 
-// Test with mocked module
-await act(async () => render(<MyComponent module={ApiModuleBpMocked} />));
+// Test with the mocked module
+it('should render user data', async () => {
+  await act(async () => render(<UserProfile module={UserModuleMocked} />));
+
+  // Assert...
+});
 ```
 
-**Testing with Zustand:**
+### Mocking on-the-fly
 
 ```tsx
-import { act, renderHook } from '@testing-library/react';
+import { act, render } from '@testing-library/react';
 
-import { CounterService } from './counter.service';
+it('should render user data', async () => {
+  await act(async () =>
+    render(
+      <UserProfile
+        inject={{
+          provide: ApiService,
+          useValue: {
+            get: vi.fn().mockResolvedValue({ name: 'Test User' }),
+            post: vi.fn(),
+          },
+        }}
+      />
+    )
+  );
 
-it('should increment counter via service', () => {
-  const service = new CounterService();
+  // Assert...
+});
+```
 
-  const { result } = renderHook(() => service.useStore((s) => s.count));
+## FAQ
 
-  expect(result.current).toBe(0);
+### How do I add global services?
 
-  act(() => {
-    service.increment();
-  });
+**Recommended:** Use a global blueprint with `isGlobal: true` in your entry point — see [Quick Start](#quick-start) and [Modules: Organizing Dependencies](#2-modules-organizing-dependencies) for the full pattern.
 
-  expect(result.current).toBe(1);
-});
+**For runtime additions**, use the built-in `AppModule` directly:
 
-it('should handle complex business logic', () => {
-  const service = new CounterService();
+```tsx
+import { AppModule } from '@adimm/x-injection';
 
-  act(() => {
-    service.incrementBy(10);
-  });
+AppModule.update.addProvider(ApiService, true); // true = also export
+```
 
-  expect(service.useStore.getState().count).toBe(10);
-});
+> [!WARNING]
+> The library provides a built-in `AppModule`. Don't create your own module named "AppModule"—use one of the methods above instead.
+
+### When should I use global modules vs component-scoped modules?
+
+**Global** (`isGlobal: true` + `exports`): API clients, auth state, routing, theme, toast notifications — accessed directly via `useInject` without a HoC.
+
+**Component-scoped** (blueprint without `isGlobal`): Form state, component-specific business logic, UI state — must use `provideModuleToComponent`; each instance gets its own module.
+
+### Can I use this with Redux/MobX/Zustand?
+
+Yes! xInjection is state-library agnostic. Encapsulate your state management library inside a service:
+
+```tsx
+@Injectable()
+class TodoStore {
+  private store = create<TodoState>(...);
+
+  get useStore() {
+    return this.store;
+  }
+
+  addTodo(text: string) {
+    this.store.setState(...);
+  }
+}
 ```
 
-## Documentation
+### How does this compare to React Context?
+
+| Feature                         | xInjection | React Context |
+| ------------------------------- | ---------- | ------------- |
+| Automatic dependency resolution | ✅         | ❌            |
+| Component-scoped instances      | ✅         | ❌            |
+| No provider hell                | ✅         | ❌            |
+| Parent-child dependency control | ✅         | ❌            |
+| Works with class-based logic    | ✅         | ❌            |
+| Testability                     | ✅         | ⚠️            |
+| TypeScript support              | ✅         | ⚠️            |
+
+### If I want Angular patterns, why not just use Angular?
+
+Because you want React's component model, hooks, and ecosystem — but need better architecture for complex business logic. xInjection brings IoC/DI to React without the framework lock-in.
+
+That said, if your app is simple, React Context + hooks is perfectly fine. xInjection shines in larger codebases with complex business logic, many modules, or a need for component-scoped service instances.
+
+### Can I migrate gradually from an existing React app?
+
+Absolutely! Start with one component:
+
+1. Extract business logic into a service
+2. Create a module for that service
+3. Wrap the component with `provideModuleToComponent`
+
+You can use xInjection alongside Context, Redux, or any other state management.
+
+### When do I actually need `provideModuleToComponent`?
+
+**Don't need it (just use `useInject`):** All your services are global/singleton — API client, auth service, theme service.
+
+**Need it:** You want multiple independent component instances (forms, modals, dialogs), or parent needs to control child dependencies via the `inject` prop.
+
+See [Why Use the HoC Approach?](#why-use-the-hoc-approach) for a full explanation.
+
+### What's the performance impact?
+
+Minimal. The dependency container is lightweight, and services are created lazily (only when first requested). The HoC pattern has no performance overhead compared to standard React patterns.
+
+**Runtime vs Build-time:** This library works entirely at runtime (not build-time):
+
+- Runtime DI is more flexible (dynamic module loading, testing)
+- Performance impact is negligible (container operations are fast)
+- You get runtime debugging and introspection
+- Works with all bundlers/tools without special configuration
+
+### Why use classes for services instead of custom hooks?
+
+Both approaches work! Here's when classes shine:
+
+**Classes are better for:**
+
+- Complex business logic (multiple methods, private state)
+- Dependency injection (automatic wiring)
+- Testing (easier to mock)
+- Encapsulation (private members, getters/setters)
+
+**Hooks are better for:**
+
+- Simple component logic
+- React-specific features (useState, useEffect)
+- Functional programming style
+
+**You can use both!** Use classes for services, hooks for UI logic. The `hookFactory` even lets you create hooks that inject class-based services.
+
+**Note:** Services are classes, but components are still functional! You write normal React functional components with hooks—only the business logic is in classes.
+
+## Links
 
 📚 **Full API Documentation:** [https://adimarianmutu.github.io/x-injection-reactjs](https://adimarianmutu.github.io/x-injection-reactjs/index.html)
 
-For more information about the base library, see [xInjection Documentation](https://github.com/AdiMarianMutu/x-injection#readme).
+🔧 **Base Library:** [xInjection](https://github.com/AdiMarianMutu/x-injection)
+
+💡 **Issues & Feature Requests:** [GitHub Issues](https://github.com/AdiMarianMutu/x-injection-reactjs/issues)
 
 ## Contributing
 
-Pull requests are welcome! Please ensure your contributions follow the project's code style.
+Contributions are welcome! Please:
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests
+5. Submit a pull request
+
+Please ensure your code follows the project's style and all tests pass.
 
 ## License
 
@@ -481,4 +1209,4 @@ MIT © [Adi-Marian Mutu](https://www.linkedin.com/in/mutu-adi-marian/)
 
 ---
 
-**Questions or issues?** Open an [issue on GitHub](https://github.com/AdiMarianMutu/x-injection-reactjs/issues)
+Made with ❤️ for the React community. If you find this library helpful, consider giving it a ⭐ on [GitHub](https://github.com/AdiMarianMutu/x-injection-reactjs)!

package/package.json

@@ -5,7 +5,7 @@
     "url": "https://github.com/AdiMarianMutu/x-injection-reactjs"
   },
   "description": "ReactJS integration of the `xInjection` library.",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "author": "Adi-Marian Mutu",
   "homepage": "https://github.com/AdiMarianMutu/x-injection-reactjs#readme",
   "bugs": "https://github.com/AdiMarianMutu/x-injection-reactjs/issues",
@@ -42,7 +42,7 @@
     "v:bump-major": "npm version major -m \"chore: update lib major version %s\""
   },
   "dependencies": {
-    "@adimm/x-injection": "^3.0.0",
+    "@adimm/x-injection": "^3.0.4",
     "react": ">=18.0.0"
   },
   "devDependencies": {