@med1802/repository-manager 3.0.2 → 3.1.0

package/README.md

@@ -1,19 +1,20 @@
 # 🔄 Repository Manager
 
-A lightweight, type-safe repository manager with dependency injection, scope management, lifecycle management, and multi-workspace support for TypeScript/JavaScript applications.
+A lightweight, type-safe repository manager with dependency injection, event-driven architecture, lifecycle management, and multi-workspace support for TypeScript/JavaScript applications.
 
 ## ✨ Features
 
 - ✅ **Dependency Injection** - Inject infrastructure dependencies into repositories
-- ✅ **Scope Management** - Runtime scoped state management
+- ✅ **Event-Driven Architecture** - Built-in observer pattern for inter-repository communication
 - ✅ **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
-- ✅ **Workspace Pattern** - `createApp` pattern for clean API
+- ✅ **Workspace Pattern** - Clean API with `createWorkspace`
 - ✅ **Logging** - Built-in logging with colored console output
 - ✅ **Memory Efficient** - Automatic cleanup when no connections remain
 - ✅ **Middleware Support** - Intercept and modify repository method calls
+- ✅ **Scoped Observer** - Hierarchical event system for organized communication
 
 ## 📦 Installation
 
@@ -45,25 +46,30 @@ const infrastructure = {
 };
 
 // Create workspace (entry point for all operations)
-const { defineRepository, queryRepository, createScope } = manager.workspace(
+const { defineRepository, queryRepository } = manager.createWorkspace({
+  id: "app",
+  logging: true,
   infrastructure,
-  {
-    id: "app",
-    logging: true,
-  }
-);
+});
 
 // Define repository
 defineRepository<IUserRepository>({
   id: "user-repo",
   install({ instance }) {
-    const { infrastructure } = instance;
+    const { infrastructure, observer } = instance;
     return {
       async getUsers() {
         return infrastructure.httpClient.get("/api/users");
       },
       async createUser(user) {
-        return infrastructure.httpClient.post("/api/users", user);
+        const result = await infrastructure.httpClient.post("/api/users", user);
+        // Notify other repositories about new user
+        observer.dispatch({
+          type: "user.created",
+          repositoryId: "user-repo",
+          message: result,
+        });
+        return result;
       },
     };
   },
@@ -88,13 +94,17 @@ disconnect();
 
 ### 1. Manager → Workspace → Repository
 
-Repository Manager follows a hierarchical pattern `createApp`:
+Repository Manager follows a hierarchical pattern:
 
 ```typescript
-const manager = repositoryManager();              // Global manager
-const workspace = manager.workspace(infrastructure, config);  // Workspace instance
-workspace.defineRepository({...});                // Define repositories
-workspace.queryRepository("repo-id");             // Query repositories
+const manager = repositoryManager();                    // Global manager
+const workspace = manager.createWorkspace({             // Workspace instance
+  id: "app",
+  infrastructure,
+  logging: true
+});
+workspace.defineRepository({...});                      // Define repositories
+workspace.queryRepository("repo-id");                   // Query repositories
 ```
 
 ### 2. Workspace Pattern
@@ -103,53 +113,62 @@ Workspace is the **entry point** for all operations. It encapsulates:
 
 - Infrastructure dependencies
 - Repository definitions
-- Scope management
+- Observer system for events
 - Logging configuration
 
 ```typescript
-const { defineRepository, queryRepository, createScope } = manager.workspace(
-  infrastructure,
-  {
-    id: "app-workspace",
-    logging: true,
-  }
-);
+const { defineRepository, queryRepository } = manager.createWorkspace({
+  id: "app-workspace",
+  logging: true,
+  infrastructure: {
+    httpClient: myHttpClient,
+    cache: myCache,
+  },
+});
 ```
 
-### 3. Scope Management
+### 3. Observer System
 
-Scopes provide **runtime scoped state management** :
+The built-in observer enables **event-driven inter-repository communication**:
 
 ```typescript
-// Create scope
-const userScope = createScope({
-  userId: null,
-  permissions: [],
-});
-
-// Use in repository
+// Define repository that dispatches events
 defineRepository({
-  id: "auth-repo",
+  id: "user-repo",
   install({ instance }) {
-    const { useScope } = instance;
+    const { observer } = instance;
     return {
-      checkPermission(action: string) {
-        const user = useScope(userScope);
-        return user.permissions.includes(action);
+      async createUser(user) {
+        const result = await saveUser(user);
+        // Notify other repositories
+        observer.dispatch({
+          type: "user.created",
+          repositoryId: "user-repo",
+          message: result,
+        });
+        return result;
       },
     };
   },
 });
 
-// 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
+// Another repository can subscribe to these events
+defineRepository({
+  id: "notification-repo",
+  install({ instance }) {
+    const { observer } = instance;
+
+    // Subscribe to user events
+    observer.subscribe((payload) => {
+      if (payload.type === "user.created") {
+        console.log("New user:", payload.message);
+        // Send welcome email, etc.
+      }
+    });
+
+    return {
+      // repository methods...
+    };
   },
 });
 ```
@@ -168,33 +187,33 @@ Creates a repository manager instance.
 const manager = repositoryManager();
 ```
 
-### `manager.workspace<I>(infrastructure, config)`
+### `manager.createWorkspace<I>(config)`
 
 Creates a workspace with infrastructure dependencies.
 
 **Parameters:**
 
-- `infrastructure: I` - Infrastructure dependencies to inject into repositories
-- `config: IConfiguration`
+- `config: IConfiguration<I>`
   - `id: string` - Unique identifier for the workspace
+  - `infrastructure: I` - Infrastructure dependencies to inject into repositories
   - `logging?: boolean` - Enable/disable logging (default: `false`)
 
 **Returns:** Object with workspace methods:
 
 - `defineRepository` - Define repositories
 - `queryRepository` - Query repositories
-- `createScope` - Create scoped state
 
 **Example:**
 
 ```typescript
-const { defineRepository, queryRepository, createScope } = manager.workspace(
-  infrastructure,
-  {
-    id: "app",
-    logging: true,
-  }
-);
+const { defineRepository, queryRepository } = manager.createWorkspace({
+  id: "app",
+  infrastructure: {
+    httpClient: myHttpClient,
+    database: myDb,
+  },
+  logging: true,
+});
 ```
 
 ### `defineRepository<R>(config)`
@@ -207,7 +226,7 @@ Defines a repository within the workspace.
   - `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
+    - `instance.observer` - Observer for event-driven communication
   - `onConnect?: () => void` - Called when repository is first connected
   - `onDisconnect?: () => void` - Called when repository is last disconnected
   - `middlewares?: Middleware[]` - Array of middleware functions
@@ -218,10 +237,23 @@ Defines a repository within the workspace.
 defineRepository<IUserRepository>({
   id: "user-repo",
   install({ instance }) {
-    const { infrastructure, useScope } = instance;
+    const { infrastructure, observer } = instance;
+
+    // Subscribe to events
+    observer.subscribe((payload) => {
+      console.log("Event received:", payload);
+    });
+
     return {
-      getUsers() {
-        return infrastructure.httpClient.get("/users");
+      async createUser(user) {
+        const result = await infrastructure.httpClient.post("/users", user);
+        // Dispatch event
+        observer.dispatch({
+          type: "user.created",
+          repositoryId: "user-repo",
+          message: result,
+        });
+        return result;
       },
     };
   },
@@ -254,107 +286,142 @@ await repository.getUsers();
 disconnect();
 ```
 
-### `createScope<V>(defaultValue)`
+### `observer.dispatch<P>(payload)`
 
-Creates a scope for runtime state management.
+Dispatch an event to notify other repositories.
 
 **Parameters:**
 
-- `defaultValue: V` - Default value for the scope
-
-**Returns:** Scope object with:
-
-- `provider: (options) => void` - Provide scoped value
-- `currentValue: V` - Current scoped value (getter)
+- `payload: IObserverDispatch<P>`
+  - `type: string` - Event type identifier
+  - `repositoryId: string` - Source repository identifier
+  - `message?: P` - Optional payload data
 
 **Example:**
 
 ```typescript
-const userScope = createScope({
-  userId: null,
-  role: "guest",
-});
-
-// Provide value
-userScope.provider({
-  value: { userId: "123", role: "admin" },
-  children() {
-    // Code that runs with scoped value
-  },
+observer.dispatch({
+  type: "user.created",
+  repositoryId: "user-repo",
+  message: { userId: "123", email: "user@example.com" },
 });
 ```
 
-### `useScope<V>(scope)`
+### `observer.subscribe<P>(callback)`
 
-Access scoped state within repository methods.
+Subscribe to events from other repositories.
 
 **Parameters:**
 
-- `scope: IScope<V>` - Scope to access
-
-**Returns:** Current scoped value
+- `callback: (payload: IObserverSubscribePayload<P>) => void` - Callback function
+  - `payload.type: string` - Event type
+  - `payload.source: string` - Source repository
+  - `payload.message: P` - Event payload
 
 **Example:**
 
 ```typescript
-defineRepository({
-  id: "auth-repo",
-  install({ instance }) {
-    const { useScope } = instance;
-    return {
-      getCurrentUser() {
-        return useScope(userScope);
-      },
-    };
-  },
+observer.subscribe((payload) => {
+  if (payload.type === "user.created") {
+    console.log("User created:", payload.message);
+    console.log("From repository:", payload.source);
+  }
 });
 ```
 
 ## 🎯 Advanced Usage
 
-### Multiple Scopes
+### Observer System Benefits
 
-You can create and use multiple scopes:
+The built-in observer system enables decoupled communication between repositories:
 
-```typescript
-const userScope = createScope({ userId: null });
-const companyScope = createScope({ companyId: null });
-const featureFlagsScope = createScope({ features: [] });
+**Benefits:**
+
+- **Loose Coupling** - Repositories don't need to know about each other
+- **Scalability** - Easy to add new listeners without modifying existing code
+- **Event Sourcing** - Track all events in your system
+- **Side Effects** - Handle cross-cutting concerns (logging, analytics, notifications)
+
+**When to Use:**
 
+- Cross-repository notifications
+- Audit logging
+- Analytics tracking
+- Email/SMS notifications
+- Cache invalidation
+- Webhook triggers
+
+### Event-Driven Communication
+
+Repositories can communicate through the observer system:
+
+```typescript
+// User repository dispatches events
 defineRepository({
-  id: "billing-repo",
+  id: "user-repo",
   install({ instance }) {
-    const { useScope } = instance;
+    const { infrastructure, observer } = instance;
     return {
-      getBillingInfo() {
-        const user = useScope(userScope);
-        const company = useScope(companyScope);
-        const flags = useScope(featureFlagsScope);
-
-        // Use all scopes
-        return { user, company, flags };
+      async createUser(user) {
+        const result = await infrastructure.httpClient.post("/users", user);
+        observer.dispatch({
+          type: "user.created",
+          repositoryId: "user-repo",
+          message: result,
+        });
+        return result;
+      },
+      async deleteUser(userId) {
+        await infrastructure.httpClient.delete(`/users/${userId}`);
+        observer.dispatch({
+          type: "user.deleted",
+          repositoryId: "user-repo",
+          message: { userId },
+        });
       },
     };
   },
 });
-```
 
-### Nested Scopes
+// Notification repository subscribes to user events
+defineRepository({
+  id: "notification-repo",
+  install({ instance }) {
+    const { observer, infrastructure } = instance;
+
+    observer.subscribe((payload) => {
+      if (payload.type === "user.created") {
+        infrastructure.emailService.send({
+          to: payload.message.email,
+          subject: "Welcome!",
+        });
+      }
+      if (payload.type === "user.deleted") {
+        console.log("User deleted:", payload.message.userId);
+      }
+    });
 
-Scopes can be nested and override outer values:
+    return {
+      // notification methods...
+    };
+  },
+});
 
-```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"
-      },
+// Analytics repository also subscribes
+defineRepository({
+  id: "analytics-repo",
+  install({ instance }) {
+    const { observer } = instance;
+
+    observer.subscribe((payload) => {
+      if (payload.type === "user.created") {
+        console.log("Track new user:", payload.message);
+      }
     });
+
+    return {
+      // analytics methods...
+    };
   },
 });
 ```
@@ -365,24 +432,26 @@ Create multiple isolated workspaces with different dependencies:
 
 ```typescript
 // API workspace
-const apiWorkspace = manager.workspace(
-  {
+const apiWorkspace = manager.createWorkspace({
+  id: "api",
+  infrastructure: {
     httpClient: apiClient,
     cache: redisCache,
   },
-  { id: "api" }
-);
+  logging: true,
+});
 
 // Database workspace
-const dbWorkspace = manager.workspace(
-  {
+const dbWorkspace = manager.createWorkspace({
+  id: "database",
+  infrastructure: {
     db: postgresClient,
     logger: winstonLogger,
   },
-  { id: "database" }
-);
+  logging: false,
+});
 
-// Each workspace has isolated repositories
+// Each workspace has isolated repositories and observers
 apiWorkspace.defineRepository({...});
 dbWorkspace.defineRepository({...});
 ```
@@ -407,7 +476,11 @@ interface IUserRepository {
 
 // Workspace with typed infrastructure
 const { defineRepository, queryRepository } =
-  manager.workspace<IInfrastructure>(infrastructure, { id: "app" });
+  manager.createWorkspace<IInfrastructure>({
+    id: "app",
+    infrastructure,
+    logging: true,
+  });
 
 // Repository with typed interface
 defineRepository<IUserRepository>({
@@ -493,105 +566,16 @@ defineRepository({
 - **Error Handling** - Centralized error handling and retry logic
 - **Authentication** - Check permissions before execution
 
-### Real-World Example: User Management
-
-```typescript
-// Define scopes
-const authScope = createScope({ token: null, user: null });
-const featureFlagsScope = createScope({ features: [] });
-
-// 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(),
-};
-
-// Create workspace
-const { defineRepository, queryRepository } = manager.workspace(
-  infrastructure,
-  { id: "app", logging: true }
-);
-
-// 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"),
-});
-
-// 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
 
-Enable logging to see connection lifecycle:
+Enable logging to see connection lifecycle and events:
 
 ```typescript
-const { defineRepository } = manager.workspace(infrastructure, {
+const { defineRepository } = manager.createWorkspace({
   id: "app",
+  infrastructure,
   logging: true, // Enables colored console output
 });
-
-// Console output will show:
-// repository.define (user-repo)
-// ┌─────────┬───────────┐
-// │ (index) │repository │
-// ├─────────┼───────────┤
-// │    0    │ user-repo │
-// └─────────┴───────────┘
-//
-// repository.connect (user-repo)
-// ┌─────────┬───────────┬─────────────┐
-// │ (index) │repository │ connections │
-// ├─────────┼───────────┼─────────────┤
-// │    0    │ user-repo │      1      │
-// └─────────┴───────────┴─────────────┘
 ```
 
 ## 🏗️ Design Patterns
@@ -602,23 +586,6 @@ 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** - Vue-like pattern for managing dependencies and lifecycle
-- **Provider Pattern** - Scope management similar to React Context
-
-## ⚠️ Error Handling
-
-```typescript
-try {
-  const { repository } = queryRepository("non-existent-repo");
-} catch (error) {
-  console.error(error.message); // Repository "non-existent-repo" not found
-}
-
-// With scope
-try {
-  const user = useScope(userScope);
-  if (!user) throw new Error("No user in scope");
-} catch (error) {
-  console.error("Scope error:", error);
-}
-```
+- **Observer Pattern** - Event-driven communication between repositories
+- **Workspace Pattern** - Clean API for managing dependencies and lifecycle
+- **Pub/Sub Pattern** - Repositories can publish and subscribe to events

package/dist/core/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./repository";
+export * from "./types";
+//# sourceMappingURL=index.d.ts.map

package/dist/core/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,SAAS,CAAC"}

package/dist/{workspace/modules → core}/index.js

@@ -1 +1,2 @@
 export * from "./repository";
+export * from "./types";

package/dist/core/middleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../../src/core/middleware.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAE1C,wBAAgB,eAAe,CAAC,UAAU,EAAE,GAAG,EAAE,WAAW,EAAE,UAAU,EAAE,OAkCzE"}

package/dist/core/repository.d.ts

@@ -0,0 +1,10 @@
+import type { scopedObserverType } from "../infrastructure";
+import type { IRepositoryPlugin } from "./types";
+declare function createRepository<I>(infrastructure: I, repositoryPlugin: IRepositoryPlugin<I, any>, observer: scopedObserverType): {
+    readonly repository: unknown;
+    readonly connections: number;
+    connect(): void;
+    disconnect(): void;
+};
+export { createRepository };
+//# sourceMappingURL=repository.d.ts.map

package/dist/core/repository.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"repository.d.ts","sourceRoot":"","sources":["../../src/core/repository.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAE5D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAEjD,iBAAS,gBAAgB,CAAC,CAAC,EACzB,cAAc,EAAE,CAAC,EACjB,gBAAgB,EAAE,iBAAiB,CAAC,CAAC,EAAE,GAAG,CAAC,EAC3C,QAAQ,EAAE,kBAAkB;;;;;EAgF7B;AAED,OAAO,EAAE,gBAAgB,EAAE,CAAC"}