@opensourcekd/ng-common-libs 1.1.8

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 OpensourceKD
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,437 @@
+# ng-common-libs
+
+Angular 18 shareable utility library with framework-agnostic core and Angular wrappers for event handling, authorization, storage management, logging, and HTTP operations.
+
+## 🎯 Dual-Layer Architecture
+
+This library features a **dual-layer architecture**:
+
+- **Core Layer** (`@opensourcekd/ng-common-libs/core`): Framework-agnostic utilities using only RxJS and browser APIs. Use these in React, Vue, Svelte, or vanilla JavaScript projects.
+- **Angular Layer** (`@opensourcekd/ng-common-libs` or `/angular`): Angular-specific wrappers with dependency injection, plus guards and interceptors that require Angular.
+
+## 🚀 Features
+
+- **Event Bus**: Centralized event communication (framework-agnostic)
+- **Token Manager**: JWT token management and validation (framework-agnostic)
+- **Storage Manager**: Type-safe localStorage/sessionStorage wrapper (framework-agnostic)
+- **Logger**: Configurable logging with multiple levels (framework-agnostic)
+- **Authorization**: Angular guards, interceptors, and permission handling
+- **HTTP Utilities**: Error handling, caching, and retry logic for Angular HTTP requests
+
+## 📦 Installation
+
+```bash
+npm install @opensourcekd/ng-common-libs
+```
+
+## 🔧 Usage
+
+### For Angular Projects
+
+Use the Angular-specific imports that provide dependency injection:
+
+```typescript
+import { Component, OnInit, inject } from '@angular/core';
+import { NgEventEmitter } from '@opensourcekd/ng-common-libs';
+
+@Component({
+  selector: 'app-example',
+  template: `...`
+})
+export class ExampleComponent implements OnInit {
+  private eventEmitter = inject(NgEventEmitter);
+
+  ngOnInit() {
+    // Subscribe to events
+    this.eventEmitter.on('user:login').subscribe(data => {
+      console.log('User logged in:', data);
+    });
+  }
+
+  login() {
+    // Emit events
+    this.eventEmitter.emit('user:login', { 
+      userId: '123', 
+      username: 'john' 
+    });
+  }
+}
+```
+
+### Authorization
+
+#### Token Service
+
+Manage authentication tokens with ease:
+
+```typescript
+import { inject } from '@angular/core';
+import { TokenService } from '@opensourcekd/ng-common-libs';
+
+export class AuthService {
+  private tokenService = inject(TokenService);
+
+  login(token: string) {
+    this.tokenService.setToken(token);
+  }
+
+  logout() {
+    this.tokenService.clearTokens();
+  }
+
+  isAuthenticated(): boolean {
+    return this.tokenService.isAuthenticated();
+  }
+
+  getUserData() {
+    return this.tokenService.getUserFromToken();
+  }
+}
+```
+
+#### Auth Guard
+
+Protect routes with authentication guards:
+
+```typescript
+import { Routes } from '@angular/router';
+import { authGuard, createRoleGuard } from '@opensourcekd/ng-common-libs';
+
+export const routes: Routes = [
+  {
+    path: 'dashboard',
+    component: DashboardComponent,
+    canActivate: [authGuard]
+  },
+  {
+    path: 'admin',
+    component: AdminComponent,
+    canActivate: [createRoleGuard(['admin'], { redirectUrl: '/unauthorized' })]
+  }
+];
+```
+
+#### Auth Interceptor
+
+Automatically add authentication tokens to HTTP requests:
+
+```typescript
+import { ApplicationConfig } from '@angular/core';
+import { provideHttpClient, withInterceptors } from '@angular/common/http';
+import { authInterceptor, configureAuthInterceptor } from '@opensourcekd/ng-common-libs';
+
+// Configure the interceptor (optional)
+configureAuthInterceptor({
+  headerName: 'Authorization',
+  tokenPrefix: 'Bearer',
+  excludedUrls: ['/auth/login', '/auth/register']
+});
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideHttpClient(
+      withInterceptors([authInterceptor])
+    )
+  ]
+};
+```
+
+#### Permission Service
+
+Check user permissions and roles:
+
+```typescript
+import { inject } from '@angular/core';
+import { PermissionService } from '@opensourcekd/ng-common-libs';
+
+export class MyComponent {
+  private permissionService = inject(PermissionService);
+
+  canEditPost(): boolean {
+    return this.permissionService.hasPermission('posts:edit');
+  }
+
+  isAdmin(): boolean {
+    return this.permissionService.hasRole('admin');
+  }
+}
+```
+
+### Storage Service
+
+Type-safe storage operations with JSON serialization:
+
+```typescript
+import { inject } from '@angular/core';
+import { StorageService } from '@opensourcekd/ng-common-libs';
+
+export class UserPreferencesService {
+  private storage = inject(StorageService);
+
+  savePreferences(prefs: UserPreferences) {
+    this.storage.setLocal('user-prefs', prefs);
+  }
+
+  getPreferences(): UserPreferences | null {
+    return this.storage.getLocal<UserPreferences>('user-prefs');
+  }
+
+  // With expiration (1 hour)
+  saveTempData(data: any) {
+    this.storage.setWithExpiration('temp-data', data, 3600000);
+  }
+
+  getTempData() {
+    return this.storage.getWithExpiration('temp-data');
+  }
+}
+```
+
+### Logger Service
+
+Centralized logging with configurable levels:
+
+```typescript
+import { inject } from '@angular/core';
+import { LoggerService, LogLevel } from '@opensourcekd/ng-common-libs';
+
+export class MyService {
+  private logger = inject(LoggerService);
+
+  constructor() {
+    // Configure logger
+    this.logger.configure({
+      level: LogLevel.DEBUG,
+      enableTimestamp: true,
+      prefix: 'MyApp'
+    });
+  }
+
+  doSomething() {
+    this.logger.debug('Debug message');
+    this.logger.info('Info message');
+    this.logger.warn('Warning message');
+    this.logger.error('Error message', new Error('Something went wrong'));
+
+    // Measure execution time
+    this.logger.time('fetchData', async () => {
+      return await this.fetchData();
+    });
+  }
+}
+```
+
+### HTTP Utilities
+
+#### Error Handling Interceptor
+
+Handle HTTP errors with automatic retry:
+
+```typescript
+import { ApplicationConfig } from '@angular/core';
+import { provideHttpClient, withInterceptors } from '@angular/common/http';
+import { errorHandlingInterceptor, configureErrorHandling } from '@opensourcekd/ng-common-libs';
+
+// Configure error handling
+configureErrorHandling({
+  enableLogging: true,
+  retryAttempts: 3,
+  retryDelay: 1000,
+  retryStatusCodes: [500, 502, 503, 504]
+});
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideHttpClient(
+      withInterceptors([errorHandlingInterceptor])
+    )
+  ]
+};
+```
+
+#### Caching Interceptor
+
+Cache HTTP responses:
+
+```typescript
+import { ApplicationConfig } from '@angular/core';
+import { provideHttpClient, withInterceptors } from '@angular/common/http';
+import { cachingInterceptor, configureCaching } from '@opensourcekd/ng-common-libs';
+
+// Configure caching
+configureCaching({
+  enabled: true,
+  maxAge: 300000, // 5 minutes
+  cacheableUrls: ['/api/users', '/api/products']
+});
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideHttpClient(
+      withInterceptors([cachingInterceptor])
+    )
+  ]
+};
+```
+
+### For Non-Angular Projects (React, Vue, Svelte, Vanilla JS)
+
+Use the framework-agnostic core utilities:
+
+```typescript
+// Import from /core
+import { EventBus, TokenManager, StorageManager, Logger, LogLevel } from '@opensourcekd/ng-common-libs/core';
+
+// Event Bus
+const eventBus = new EventBus();
+eventBus.emit('user:login', { userId: '123' });
+eventBus.on('user:login').subscribe(data => {
+  console.log('User logged in:', data);
+});
+
+// Token Manager
+const tokenManager = new TokenManager();
+tokenManager.setToken('your-jwt-token');
+if (tokenManager.isAuthenticated()) {
+  const user = tokenManager.getUserFromToken();
+}
+
+// Storage Manager
+const storage = new StorageManager();
+storage.setLocal('preferences', { theme: 'dark' });
+const prefs = storage.getLocal('preferences');
+
+// Logger
+const logger = new Logger();
+logger.configure({ level: LogLevel.DEBUG, prefix: 'MyApp' });
+logger.info('Application started');
+```
+
+#### React Example
+
+```typescript
+import { useEffect } from 'react';
+import { EventBus } from '@opensourcekd/ng-common-libs/core';
+
+const eventBus = new EventBus();
+
+function MyComponent() {
+  useEffect(() => {
+    const subscription = eventBus.on('user:login').subscribe(data => {
+      console.log('User logged in:', data);
+    });
+    return () => subscription.unsubscribe();
+  }, []);
+
+  const handleLogin = () => {
+    eventBus.emit('user:login', { userId: '123' });
+  };
+
+  return <button onClick={handleLogin}>Login</button>;
+}
+```
+
+#### Vue Example
+
+```typescript
+import { onMounted, onUnmounted } from 'vue';
+import { EventBus } from '@opensourcekd/ng-common-libs/core';
+
+const eventBus = new EventBus();
+
+export default {
+  setup() {
+    let subscription;
+
+    onMounted(() => {
+      subscription = eventBus.on('user:login').subscribe(data => {
+        console.log('User logged in:', data);
+      });
+    });
+
+    onUnmounted(() => {
+      subscription?.unsubscribe();
+    });
+
+    const handleLogin = () => {
+      eventBus.emit('user:login', { userId: '123' });
+    };
+
+    return { handleLogin };
+  }
+};
+```
+
+## 📚 Documentation
+
+- **[Usage Guide](./docs/USAGE.md)** - Complete usage examples for all utilities
+- **[API Reference](./docs/API.md)** - Detailed API documentation
+- **[Deployment Guide](./docs/DEPLOYMENT.md)** - Publishing, versioning, and consumption
+- **[Architecture Decisions](./ARCHITECTURE_DECISIONS.md)** - Detailed architecture and design decisions
+
+## 📝 API Documentation
+
+### NgEventEmitter
+
+- `emit<T>(eventType: string, data?: T): void` - Emit an event
+- `on<T>(eventType: string): Observable<T>` - Subscribe to an event
+- `onMultiple(eventTypes: string[]): Observable<EventPayload>` - Subscribe to multiple events
+- `onAll(): Observable<EventPayload>` - Subscribe to all events
+
+### TokenService
+
+- `setToken(token: string): void` - Store authentication token
+- `getToken(): string | null` - Retrieve authentication token
+- `removeToken(): void` - Remove authentication token
+- `clearTokens(): void` - Clear all tokens
+- `isAuthenticated(): boolean` - Check if user is authenticated
+- `isTokenExpired(token?: string): boolean` - Check if token is expired
+- `getUserFromToken(token?: string): any` - Extract user data from token
+
+### StorageService
+
+- `setLocal<T>(key: string, value: T): boolean` - Set item in localStorage
+- `getLocal<T>(key: string, defaultValue?: T): T | null` - Get item from localStorage
+- `removeLocal(key: string): void` - Remove item from localStorage
+- `setSession<T>(key: string, value: T): boolean` - Set item in sessionStorage
+- `getSession<T>(key: string, defaultValue?: T): T | null` - Get item from sessionStorage
+- `setWithExpiration<T>(key, value, expirationMs, useSession?): boolean` - Set item with expiration
+- `getWithExpiration<T>(key, useSession?): T | null` - Get item with expiration check
+
+### LoggerService
+
+- `debug(message: string, ...args: any[]): void` - Log debug message
+- `info(message: string, ...args: any[]): void` - Log info message
+- `warn(message: string, ...args: any[]): void` - Log warning message
+- `error(message: string, error?: any, ...args: any[]): void` - Log error message
+- `time<T>(label: string, fn: () => Promise<T> | T): Promise<T>` - Measure execution time
+
+## 🛠️ Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build the library
+npm run build
+
+# Run linter
+npm run lint
+```
+
+## 📄 License
+
+MIT
+
+## 👤 Author
+
+Koustubh Desai <jobs.koustubh@gmail.com>
+
+## 🤝 Contributing
+
+Contributions, issues, and feature requests are welcome!
+
+## ⭐ Show your support
+
+Give a ⭐️ if this project helped you!
+