@med1802/repository-manager 2.2.2 → 3.0.0

package/README.md

@@ -1,87 +1,166 @@
-# 🔄 Repository Manager
+# 🔄 Repository Manager v3
 
-A lightweight, type-safe repository manager with dependency injection, lifecycle management, and multi-workspace support for TypeScript/JavaScript applications.
+A lightweight, type-safe repository manager with dependency injection, scope management, lifecycle management, and multi-workspace support for TypeScript/JavaScript applications.
 
-## Features
+## ✨ Features
 
 - ✅ **Dependency Injection** - Inject infrastructure dependencies into repositories
+- ✅ **Scope Management** - Runtime scoped state management
 - ✅ **Lifecycle Management** - Automatic connection/disconnection with reference counting
 - ✅ **Multi-Workspace Support** - Manage multiple isolated workspaces with different dependencies
 - ✅ **Type Safety** - Full TypeScript support with generics
 - ✅ **Lazy Initialization** - Repository instances are created only when needed
-- ✅ **Imperative API** - Define workspaces and repositories as needed
+- ✅ **Workspace Pattern** - `createApp` pattern for clean API
 - ✅ **Logging** - Built-in logging with colored console output
 - ✅ **Memory Efficient** - Automatic cleanup when no connections remain
 - ✅ **Middleware Support** - Intercept and modify repository method calls
 
-## Installation
+## 📦 Installation
 
 ```bash
 npm install @med1802/repository-manager
 ```
 
-## Quick Start
+## 🚀 Quick Start
 
 ```typescript
 import { repositoryManager } from "@med1802/repository-manager";
 
-// Define your dependencies interface
-interface IDependencies {
-  httpClient: {
-    get(url: string): Promise<any>;
-    post(url: string, data: any): Promise<any>;
-  };
+// Define your repository interface
+interface IUserRepository {
+  getUsers(): Promise<User[]>;
+  createUser(user: User): Promise<User>;
 }
 
 // Create manager instance
 const manager = repositoryManager();
 
 // Define infrastructure dependencies
-const infrastructure: IDependencies = {
+const infrastructure = {
   httpClient: {
-    get: async (url) => fetch(url).then((r) => r.json()),
-    post: async (url, data) =>
+    get: async (url: string) => fetch(url).then((r) => r.json()),
+    post: async (url: string, data: any) =>
       fetch(url, { method: "POST", body: JSON.stringify(data) }),
   },
 };
 
-// Create a workspace and define repositories
-const { defineRepository } = manager.workspace(infrastructure, {
-  id: "app",
-  logging: true,
-});
+// Create workspace (entry point for all operations)
+const { defineRepository, queryRepository, createScope } = manager.workspace(
+  infrastructure,
+  {
+    id: "app",
+    logging: true,
+  }
+);
 
-// Define repositories
-defineRepository("userRepo", (infrastructure) => ({
-  async getUsers() {
-    return infrastructure.httpClient.get("/api/users");
+// Define repository
+defineRepository<IUserRepository>({
+  id: "user-repo",
+  install({ instance }) {
+    const { infrastructure } = instance;
+    return {
+      async getUsers() {
+        return infrastructure.httpClient.get("/api/users");
+      },
+      async createUser(user) {
+        return infrastructure.httpClient.post("/api/users", user);
+      },
+    };
   },
-  async createUser(user: any) {
-    return infrastructure.httpClient.post("/api/users", user);
+  onConnect: () => {
+    console.log("User repository initialized");
   },
-}));
-
-defineRepository("postRepo", (infrastructure) => ({
-  async getPosts() {
-    return infrastructure.httpClient.get("/api/posts");
+  onDisconnect: () => {
+    console.log("User repository cleaned up");
   },
-}));
+});
 
-// Use repositories with path format: "workspaceId/repositoryId"
-const { repository: userRepo, disconnect } = manager.query("app/userRepo");
+// Query and use repository
+const { repository: userRepo, disconnect } =
+  queryRepository<IUserRepository>("user-repo");
 const users = await userRepo.getUsers();
 
 // Cleanup when done
 disconnect();
 ```
 
-## API Reference
+## 📖 Core Concepts
+
+### 1. Manager → Workspace → Repository
+
+Repository Manager follows a hierarchical pattern `createApp`:
+
+```typescript
+const manager = repositoryManager();              // Global manager
+const workspace = manager.workspace(infrastructure, config);  // Workspace instance
+workspace.defineRepository({...});                // Define repositories
+workspace.queryRepository("repo-id");             // Query repositories
+```
+
+### 2. Workspace Pattern
+
+Workspace is the **entry point** for all operations. It encapsulates:
+
+- Infrastructure dependencies
+- Repository definitions
+- Scope management
+- Logging configuration
+
+```typescript
+const { defineRepository, queryRepository, createScope } = manager.workspace(
+  infrastructure,
+  {
+    id: "app-workspace",
+    logging: true,
+  }
+);
+```
+
+### 3. Scope Management
+
+Scopes provide **runtime scoped state management** :
+
+```typescript
+// Create scope
+const userScope = createScope({
+  userId: null,
+  permissions: [],
+});
+
+// Use in repository
+defineRepository({
+  id: "auth-repo",
+  install({ instance }) {
+    const { useScope } = instance;
+    return {
+      checkPermission(action: string) {
+        const user = useScope(userScope);
+        return user.permissions.includes(action);
+      },
+    };
+  },
+});
+
+// Provide scope value
+userScope.provider({
+  value: {
+    userId: "123",
+    permissions: ["read", "write"],
+  },
+  children() {
+    const { repository } = queryRepository("auth-repo");
+    repository.checkPermission("write"); // Has access to scoped value
+  },
+});
+```
+
+## 📚 API Reference
 
 ### `repositoryManager()`
 
 Creates a repository manager instance.
 
-**Returns:** Manager object with `workspace` and `query` methods
+**Returns:** Manager object with `workspace` method
 
 **Example:**
 
@@ -91,398 +170,402 @@ const manager = repositoryManager();
 
 ### `manager.workspace<I>(infrastructure, config)`
 
-Creates a workspace with infrastructure dependencies and returns a `defineRepository` function.
+Creates a workspace with infrastructure dependencies.
 
 **Parameters:**
 
 - `infrastructure: I` - Infrastructure dependencies to inject into repositories
-- `config: IConfiguration` - Workspace configuration
+- `config: IConfiguration`
   - `id: string` - Unique identifier for the workspace
   - `logging?: boolean` - Enable/disable logging (default: `false`)
 
-**Returns:** Object with `defineRepository` method
+**Returns:** Object with workspace methods:
+
+- `defineRepository` - Define repositories
+- `queryRepository` - Query repositories
+- `createScope` - Create scoped state
 
 **Example:**
 
 ```typescript
-const { defineRepository } = manager.workspace(infrastructure, {
-  id: "app",
-  logging: true,
-});
+const { defineRepository, queryRepository, createScope } = manager.workspace(
+  infrastructure,
+  {
+    id: "app",
+    logging: true,
+  }
+);
 ```
 
-### `defineRepository(id, factory, config?)`
+### `defineRepository<R>(config)`
 
 Defines a repository within the workspace.
 
 **Parameters:**
 
-- `id: string` - Unique identifier for the repository
-- `factory: (infrastructure: I) => R` - Factory function that receives infrastructure and returns repository instance
-- `config?: IRepositoryConfig` - Optional repository configuration
-  - `lifecycle?: ILifeCycle` - Lifecycle hooks
-    - `onConnect?: () => void` - Called when repository is first connected (when connections go from 0 to 1)
-    - `onDisconnect?: () => void` - Called when repository is last disconnected (when connections go from 1 to 0)
-  - `middlewares?: Middleware[]` - Array of middleware functions to intercept method calls
+- `config: IRepositoryPlugin<I, R>`
+  - `id: string` - Unique identifier for the repository
+  - `install: ({ instance }) => R` - Factory function that returns repository instance
+    - `instance.infrastructure` - Injected infrastructure
+    - `instance.useScope` - Function to access scoped state
+  - `onConnect?: () => void` - Called when repository is first connected
+  - `onDisconnect?: () => void` - Called when repository is last disconnected
+  - `middlewares?: Middleware[]` - Array of middleware functions
 
 **Example:**
 
 ```typescript
-defineRepository("userRepo", (infrastructure) => ({
-  getUsers: () => infrastructure.httpClient.get("/users"),
-}));
-
-// With lifecycle hooks
-defineRepository(
-  "userRepo",
-  (infrastructure) => ({
-    getUsers: () => infrastructure.httpClient.get("/users"),
-  }),
-  {
-    lifecycle: {
-      onConnect: () => {
-        console.log("User repository initialized");
-      },
-      onDisconnect: () => {
-        console.log("User repository cleaned up");
+defineRepository<IUserRepository>({
+  id: "user-repo",
+  install({ instance }) {
+    const { infrastructure, useScope } = instance;
+    return {
+      getUsers() {
+        return infrastructure.httpClient.get("/users");
       },
-    },
-  }
-);
+    };
+  },
+  onConnect: () => console.log("Connected"),
+  onDisconnect: () => console.log("Disconnected"),
+});
 ```
 
-### `manager.query<R>(path)`
+### `queryRepository<R>(id)`
 
-Queries a repository from a workspace using path format: `"workspaceId/repositoryId"`.
+Queries a repository from the workspace.
 
 **Parameters:**
 
-- `path: string` - Path to repository in format `"workspaceId/repositoryId"`
+- `id: string` - Repository identifier
 
 **Returns:** Object with:
 
 - `repository: R` - The repository instance
 - `disconnect: () => void` - Function to disconnect and cleanup
 
-**Throws:** `Error` if workspace or repository is not found
+**Throws:** `Error` if repository is not found
 
 **Example:**
 
 ```typescript
-const { repository, disconnect } = manager.query<IUserRepo>("app/userRepo");
+const { repository, disconnect } =
+  queryRepository<IUserRepository>("user-repo");
 await repository.getUsers();
 disconnect();
 ```
 
-## Advanced Usage
+### `createScope<V>(defaultValue)`
 
-### Multiple Workspaces
+Creates a scope for runtime state management.
 
-You can create multiple isolated workspaces with different dependencies:
+**Parameters:**
 
-```typescript
-const manager = repositoryManager();
+- `defaultValue: V` - Default value for the scope
 
-// API workspace
-const { defineRepository: defineApiRepo } = manager.workspace(
-  {
-    httpClient: apiHttpClient,
-    cache: redisCache,
-  },
-  {
-    id: "api",
-    logging: true,
-  }
-);
+**Returns:** Scope object with:
 
-defineApiRepo("userRepo", (infrastructure) => ({
-  getUsers: () => infrastructure.httpClient.get("/users"),
-}));
+- `provider: (options) => void` - Provide scoped value
+- `currentValue: V` - Current scoped value (getter)
 
-// Database workspace
-const { defineRepository: defineDbRepo } = manager.workspace(
-  {
-    db: postgresClient,
-    logger: winstonLogger,
-  },
-  {
-    id: "database",
-    logging: false,
-  }
-);
+**Example:**
 
-defineDbRepo("orderRepo", (infrastructure) => ({
-  getOrders: () => infrastructure.db.query("SELECT * FROM orders"),
-}));
+```typescript
+const userScope = createScope({
+  userId: null,
+  role: "guest",
+});
 
-// Access repositories from different workspaces
-const { repository: userRepo } = manager.query("api/userRepo");
-const { repository: orderRepo } = manager.query("database/orderRepo");
+// Provide value
+userScope.provider({
+  value: { userId: "123", role: "admin" },
+  children() {
+    // Code that runs with scoped value
+  },
+});
 ```
 
-### TypeScript Interfaces
+### `useScope<V>(scope)`
 
-Define clear interfaces for better type safety:
+Access scoped state within repository methods.
 
-```typescript
-interface IUserRepo {
-  getUsers(): Promise<User[]>;
-  createUser(user: User): Promise<User>;
-  updateUser(id: string, user: Partial<User>): Promise<User>;
-  deleteUser(id: string): Promise<void>;
-}
+**Parameters:**
 
-interface IDependencies {
-  httpClient: IHttpClient;
-  cache: ICache;
-}
+- `scope: IScope<V>` - Scope to access
 
-const manager = repositoryManager();
+**Returns:** Current scoped value
 
-const { defineRepository } = manager.workspace<IDependencies>(
-  {
-    httpClient: myHttpClient,
-    cache: myCache,
-  },
-  {
-    id: "app",
-  }
-);
-
-defineRepository<IUserRepo>(
-  "userRepo",
-  (infrastructure): IUserRepo => ({
-    async getUsers() {
-      /* ... */
-    },
-    async createUser(user) {
-      /* ... */
-    },
-    async updateUser(id, user) {
-      /* ... */
-    },
-    async deleteUser(id) {
-      /* ... */
-    },
-  })
-);
+**Example:**
 
-// TypeScript knows the exact return type
-const { repository } = manager.query<IUserRepo>("app/userRepo");
-// repository has all IUserRepo methods with correct types
+```typescript
+defineRepository({
+  id: "auth-repo",
+  install({ instance }) {
+    const { useScope } = instance;
+    return {
+      getCurrentUser() {
+        return useScope(userScope);
+      },
+    };
+  },
+});
 ```
 
-### Lifecycle Management with Reference Counting
-
-Repositories use reference counting for automatic lifecycle management:
+## 🎯 Advanced Usage
 
-```typescript
-// First query creates the repository instance
-const conn1 = manager.query("app/userRepo"); // Connections: 1
-const conn2 = manager.query("app/userRepo"); // Connections: 2 (reuses instance)
-const conn3 = manager.query("app/userRepo"); // Connections: 3 (reuses instance)
+### Multiple Scopes
 
-conn1.disconnect(); // Connections: 2 (still active)
-conn2.disconnect(); // Connections: 1 (still active)
-conn3.disconnect(); // Connections: 0 (instance destroyed)
+You can create and use multiple scopes:
 
-// Next query will create a new instance
-const conn4 = manager.query("app/userRepo"); // Connections: 1 (new instance)
+```typescript
+const userScope = createScope({ userId: null });
+const companyScope = createScope({ companyId: null });
+const featureFlagsScope = createScope({ features: [] });
+
+defineRepository({
+  id: "billing-repo",
+  install({ instance }) {
+    const { useScope } = instance;
+    return {
+      getBillingInfo() {
+        const user = useScope(userScope);
+        const company = useScope(companyScope);
+        const flags = useScope(featureFlagsScope);
+
+        // Use all scopes
+        return { user, company, flags };
+      },
+    };
+  },
+});
 ```
 
-### Lifecycle Hooks
+### Nested Scopes
 
-You can define lifecycle hooks that are called at specific points in the repository lifecycle:
+Scopes can be nested and override outer values:
+
+```typescript
+userScope.provider({
+  value: { userId: "outer" },
+  children() {
+    // Inner scope overrides outer
+    userScope.provider({
+      value: { userId: "inner" },
+      children() {
+        const { repository } = queryRepository("user-repo");
+        // useScope(userScope) returns "inner"
+      },
+    });
+  },
+});
+```
 
-- **`onConnect`** - Called only when the repository is first connected (when connections go from 0 to 1)
-- **`onDisconnect`** - Called only when the repository is last disconnected (when connections go from 1 to 0)
+### Multiple Workspaces
 
-**Example:**
+Create multiple isolated workspaces with different dependencies:
 
 ```typescript
-defineRepository(
-  "userRepo",
-  (infrastructure) => ({
-    getUsers: () => infrastructure.httpClient.get("/api/users"),
-  }),
+// API workspace
+const apiWorkspace = manager.workspace(
   {
-    lifecycle: {
-      onConnect: () => {
-        console.log("User repository initialized");
-        // Perform initialization tasks (e.g., setup cache, establish connection)
-      },
-      onDisconnect: () => {
-        console.log("User repository cleaned up");
-        // Perform cleanup tasks (e.g., clear cache, close connections)
-      },
-    },
-  }
+    httpClient: apiClient,
+    cache: redisCache,
+  },
+  { id: "api" }
 );
 
-// Usage
-const conn1 = manager.query("app/userRepo"); // onConnect called (first connection)
-const conn2 = manager.query("app/userRepo"); // onConnect NOT called (reusing instance)
+// Database workspace
+const dbWorkspace = manager.workspace(
+  {
+    db: postgresClient,
+    logger: winstonLogger,
+  },
+  { id: "database" }
+);
 
-conn1.disconnect(); // onDisconnect NOT called (still has connections)
-conn2.disconnect(); // onDisconnect called (last connection removed)
+// Each workspace has isolated repositories
+apiWorkspace.defineRepository({...});
+dbWorkspace.defineRepository({...});
 ```
 
-**Use Cases:**
+### TypeScript Best Practices
 
-- **Initialization**: Setup cache, establish database connections, initialize state
-- **Cleanup**: Clear cache, close connections, release resources
-- **Analytics**: Track repository usage and lifecycle events
-- **Debugging**: Monitor when repositories are created and destroyed
+Define clear interfaces for type safety:
 
-### Middleware
+```typescript
+// Infrastructure interface
+interface IInfrastructure {
+  httpClient: IHttpClient;
+  cache: ICache;
+  logger: ILogger;
+}
 
-Middleware allows you to intercept and modify repository method calls before and after execution. Middleware functions are executed in sequence, allowing you to add cross-cutting concerns like logging, caching, validation, and more.
+// Repository interface
+interface IUserRepository {
+  getUsers(): Promise<User[]>;
+  createUser(user: User): Promise<User>;
+}
 
-**Middleware Signature:**
+// Workspace with typed infrastructure
+const { defineRepository, queryRepository } =
+  manager.workspace<IInfrastructure>(infrastructure, { id: "app" });
+
+// Repository with typed interface
+defineRepository<IUserRepository>({
+  id: "user-repo",
+  install({ instance }) {
+    const { infrastructure } = instance;
+    return {
+      async getUsers() {
+        // TypeScript knows infrastructure type
+        return infrastructure.httpClient.get("/users");
+      },
+      async createUser(user) {
+        // TypeScript validates User type
+        return infrastructure.httpClient.post("/users", user);
+      },
+    };
+  },
+});
 
-```typescript
-type Middleware = (
-  method: string,
-  args: any[],
-  next: (...nextArgs: any[]) => any
-) => any;
+// Query with typed repository
+const { repository } = queryRepository<IUserRepository>("user-repo");
+// TypeScript knows all repository methods
 ```
 
-**Parameters:**
-
-- `method: string` - The name of the method being called
-- `args: any[]` - The arguments passed to the method
-- `next: (...nextArgs: any[]) => any` - Function to call the next middleware or the original method
+### Lifecycle Management
 
-**Example:**
+Repositories use reference counting for automatic lifecycle:
 
 ```typescript
-// Define middleware functions
-const loggingMiddleware: Middleware = (method, args, next) => {
-  console.log(`[${new Date().toISOString()}] Calling ${method}`, args);
-  const result = next();
-  console.log(`[${new Date().toISOString()}] ${method} returned:`, result);
-  return result;
-};
+// First query creates instance (onConnect called)
+const conn1 = queryRepository("user-repo"); // Connections: 1
 
-const performanceMiddleware: Middleware = (method, args, next) => {
-  const start = performance.now();
-  const result = next();
-  const duration = performance.now() - start;
+// Subsequent queries reuse instance (onConnect NOT called)
+const conn2 = queryRepository("user-repo"); // Connections: 2
+const conn3 = queryRepository("user-repo"); // Connections: 3
 
-  if (duration > 1000) {
-    console.warn(`Slow call: ${method} took ${duration}ms`);
-  }
-
-  return result;
-};
+// Disconnect reduces count
+conn1.disconnect(); // Connections: 2
+conn2.disconnect(); // Connections: 1
 
-// Apply middleware to repository
-defineRepository(
-  "userRepo",
-  (infrastructure) => ({
-    getUsers: () => infrastructure.httpClient.get("/api/users"),
-    createUser: (user) => infrastructure.httpClient.post("/api/users", user),
-  }),
-  {
-    middlewares: [loggingMiddleware, performanceMiddleware],
-  }
-);
-
-// When you call repository methods, middleware intercepts them
-const { repository } = manager.query("app/userRepo");
-await repository.getUsers(); // Middleware logs and measures performance
+// Last disconnect destroys instance (onDisconnect called)
+conn3.disconnect(); // Connections: 0, instance destroyed
 ```
 
-**Middleware Execution Flow:**
-
-```typescript
-// When you call: repository.getUsers("filter")
-// 1. loggingMiddleware - logs "Calling getUsers"
-// 2. performanceMiddleware - starts timer
-// 3. repository.getUsers("filter") - original method executes
-// 4. performanceMiddleware - ends timer, logs if slow
-// 5. loggingMiddleware - logs result
-// 6. Returns result to caller
-```
-
-**Common Use Cases:**
-
-- **Logging**: Log all method calls and their results
-- **Performance Monitoring**: Measure execution time and warn about slow calls
-- **Caching**: Cache method results to avoid redundant calls
-- **Validation**: Validate arguments before method execution
-- **Error Handling**: Centralized error handling and retry logic
-- **Data Transformation**: Transform arguments or results
-- **Authentication**: Check permissions before method execution
-- **Rate Limiting**: Limit the number of calls per method
+### Middleware
 
-**Example: Caching Middleware**
+Intercept and modify repository method calls:
 
 ```typescript
-const cache = new Map<string, any>();
+const loggingMiddleware: Middleware = (method, args, next) => {
+  console.log(`Calling ${method}`, args);
+  const result = next();
+  console.log(`${method} returned:`, result);
+  return result;
+};
 
 const cacheMiddleware: Middleware = (method, args, next) => {
   const cacheKey = `${method}-${JSON.stringify(args)}`;
+  if (cache.has(cacheKey)) return cache.get(cacheKey);
 
-  if (cache.has(cacheKey)) {
-    return cache.get(cacheKey); // Return cached result, skip method execution
-  }
-
-  const result = next(); // Execute method
-  cache.set(cacheKey, result); // Cache result
+  const result = next();
+  cache.set(cacheKey, result);
   return result;
 };
 
-defineRepository(
-  "userRepo",
-  (infrastructure) => ({
-    getUsers: () => infrastructure.httpClient.get("/api/users"),
-  }),
-  {
-    middlewares: [cacheMiddleware],
-  }
-);
+defineRepository({
+  id: "user-repo",
+  install({ instance }) {
+    return {
+      getUsers: () => instance.infrastructure.httpClient.get("/users"),
+    };
+  },
+  middlewares: [loggingMiddleware, cacheMiddleware],
+});
 ```
 
-**Example: Validation Middleware**
+**Common Middleware Use Cases:**
 
-```typescript
-const validationMiddleware: Middleware = (method, args, next) => {
-  if (method === "createUser" && (!args[0] || typeof args[0] !== "object")) {
-    throw new Error("Invalid user data");
-  }
-  return next();
-};
+- **Logging** - Log all method calls and results
+- **Caching** - Cache method results
+- **Validation** - Validate arguments before execution
+- **Performance Monitoring** - Measure execution time
+- **Error Handling** - Centralized error handling and retry logic
+- **Authentication** - Check permissions before execution
 
-defineRepository(
-  "userRepo",
-  (infrastructure) => ({
-    createUser: (user) => infrastructure.httpClient.post("/api/users", user),
-  }),
-  {
-    middlewares: [validationMiddleware],
-  }
-);
-```
-
-### Using with React
+### Real-World Example: User Management
 
 ```typescript
-import { useEffect } from "react";
+// Define scopes
+const authScope = createScope({ token: null, user: null });
+const featureFlagsScope = createScope({ features: [] });
 
-function UserList() {
-  useEffect(() => {
-    const { repository, disconnect } = manager.query<IUserRepo>("app/userRepo");
+// Infrastructure
+const infrastructure = {
+  httpClient: {
+    get: async (url) =>
+      fetch(url, {
+        headers: { Authorization: `Bearer ${useScope(authScope).token}` },
+      }).then((r) => r.json()),
+    post: async (url, data) =>
+      fetch(url, {
+        method: "POST",
+        headers: { Authorization: `Bearer ${useScope(authScope).token}` },
+        body: JSON.stringify(data),
+      }).then((r) => r.json()),
+  },
+  cache: new Map(),
+};
 
-    repository.getUsers().then(setUsers);
+// Create workspace
+const { defineRepository, queryRepository } = manager.workspace(
+  infrastructure,
+  { id: "app", logging: true }
+);
 
-    // Cleanup on unmount
-    return disconnect;
-  }, []);
+// Define repositories
+defineRepository<IUserRepository>({
+  id: "user-repo",
+  install({ instance }) {
+    const { infrastructure, useScope } = instance;
+    return {
+      async getUsers() {
+        const auth = useScope(authScope);
+        if (!auth.token) throw new Error("Not authenticated");
+        return infrastructure.httpClient.get("/api/users");
+      },
+      async createUser(user) {
+        const flags = useScope(featureFlagsScope);
+        if (!flags.features.includes("create-user")) {
+          throw new Error("Feature not enabled");
+        }
+        return infrastructure.httpClient.post("/api/users", user);
+      },
+    };
+  },
+  onConnect: () => console.log("User repo connected"),
+  onDisconnect: () => console.log("User repo disconnected"),
+});
 
-  return <div>{/* ... */}</div>;
-}
+// Use with authentication
+authScope.provider({
+  value: { token: "abc123", user: { id: "1", name: "John" } },
+  children() {
+    featureFlagsScope.provider({
+      value: { features: ["create-user", "delete-user"] },
+      async children() {
+        const { repository, disconnect } =
+          queryRepository<IUserRepository>("user-repo");
+
+        // Has access to auth and feature flags
+        const users = await repository.getUsers();
+        await repository.createUser({ name: "Jane" });
+
+        disconnect();
+      },
+    });
+  },
+});
 ```
 
 ### Logging
@@ -490,73 +573,28 @@ function UserList() {
 Enable logging to see connection lifecycle:
 
 ```typescript
-const manager = repositoryManager();
-
 const { defineRepository } = manager.workspace(infrastructure, {
   id: "app",
   logging: true, // Enables colored console output
 });
 
 // Console output will show:
-// repository.connect (app/userRepo)
-// ┌─────────┬──────────┬─────────────┐
-// │ (index) │    id    │ connections │
-// ├─────────┼──────────┼─────────────┤
-// │    0    │ userRepo │      1      │
-// └─────────┴──────────┴─────────────┘
+// repository.define (user-repo)
+// ┌─────────┬───────────┐
+// │ (index) │repository │
+// ├─────────┼───────────┤
+// │    0    │ user-repo │
+// └─────────┴───────────┘
+//
+// repository.connect (user-repo)
+// ┌─────────┬───────────┬─────────────┐
+// │ (index) │repository │ connections │
+// ├─────────┼───────────┼─────────────┤
+// │    0    │ user-repo │      1      │
+// └─────────┴───────────┴─────────────┘
 ```
 
-## Dependency Injection Pattern
-
-This package follows the **Dependency Inversion Principle (DIP)**:
-
-- **High-level modules** (repositories) depend on abstractions (dependencies interface)
-- **Low-level modules** (infrastructure implementations) are injected
-- Easy to test with mock dependencies
-- Easy to swap implementations
-
-```typescript
-// Define abstractions
-interface IDatabase {
-  query(sql: string): Promise<any>;
-}
-
-interface ICache {
-  get(key: string): Promise<any>;
-  set(key: string, value: any): Promise<void>;
-}
-
-interface IDependencies {
-  database: IDatabase;
-  cache: ICache;
-}
-
-// Inject concrete implementations
-const manager = repositoryManager();
-
-const { defineRepository } = manager.workspace<IDependencies>(
-  {
-    database: new PostgreSQLClient(),
-    cache: new RedisCache(),
-  },
-  {
-    id: "prod",
-  }
-);
-
-// Easy to test with mocks
-const { defineRepository: defineTestRepo } = manager.workspace<IDependencies>(
-  {
-    database: new MockDatabase(),
-    cache: new MockCache(),
-  },
-  {
-    id: "test",
-  }
-);
-```
-
-## Design Patterns
+## 🏗️ Design Patterns
 
 This library implements several design patterns:
 
@@ -564,20 +602,31 @@ This library implements several design patterns:
 - **Factory Pattern** - Repositories are created using factory functions
 - **Singleton Pattern** - Each repository is a singleton per workspace (with reference counting)
 - **Repository Pattern** - Abstracts data access logic
-- **Workspace Pattern** - Manages dependencies and lifecycle
+- **Workspace Pattern** - Vue-like pattern for managing dependencies and lifecycle
+- **Provider Pattern** - Scope management similar to React Context
 
-## Error Handling
+## ⚠️ Error Handling
 
 ```typescript
 try {
-  const { repository } = manager.query("non-existent/repo");
+  const { repository } = queryRepository("non-existent-repo");
 } catch (error) {
-  console.error(error.message); // Container "non-existent" not found
+  console.error(error.message); // Repository "non-existent-repo" not found
 }
 
+// With scope
 try {
-  const { repository } = manager.query("app/non-existent");
+  const user = useScope(userScope);
+  if (!user) throw new Error("No user in scope");
 } catch (error) {
-  console.error(error.message); // Repository "non-existent" not found
+  console.error("Scope error:", error);
 }
 ```
+
+## 📝 License
+
+MIT
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.