pp-command-bus 1.0.0

package/README.md

@@ -0,0 +1,522 @@
+# PP Command Bus
+
+Distributed Command Bus library supporting RPC and job queuing with BullMQ for Redis/DragonflyDB.
+
+## Opis
+
+**pp-command-bus** to biblioteka do obsługi rozproszonych komend zgodna ze wzorcem **CQRS (Command Query Responsibility Segregation)**. Wspiera:
+
+- ✅ **Fire-and-forget commands** - wysyłanie komend bez oczekiwania na wynik
+- ✅ **RPC (Remote Procedure Call)** - synchroniczne wywołania z oczekiwaniem na odpowiedź
+- ✅ **Job queuing** - kolejkowanie zadań z retry, backoff i delayed execution
+- ✅ **BullMQ integration** - wydajna kolejka zadań na Redis/DragonflyDB
+- ✅ **TypeScript** - pełne wsparcie typów i strict mode
+- ✅ **Memory leak protection** - zaawansowana diagnostyka i cleanup
+- ✅ **Command logging** - opcjonalne logowanie komend do plików
+
+## Instalacja
+
+```bash
+npm install pp-command-bus
+```
+
+### Wymagania
+
+- Node.js >= 14
+- Redis >= 5 lub DragonflyDB
+- TypeScript >= 4.5 (opcjonalnie)
+
+## Szybki start
+
+### 1. Konfiguracja
+
+```typescript
+import { CommandBus, CommandBusConfig, Command } from 'pp-command-bus';
+
+// Konfiguracja CommandBus
+const config = new CommandBusConfig({
+  redis: {
+    host: 'localhost',
+    port: 6379,
+  },
+  logger: console, // ILogger interface
+  concurrency: 5,
+  maxAttempts: 3,
+});
+
+// Utwórz instancję CommandBus
+const commandBus = new CommandBus(config);
+
+// Poczekaj na gotowość (opcjonalnie)
+await commandBus.waitUntilReady();
+```
+
+### 2. Definiowanie komend
+
+```typescript
+class CreateUserCommand extends Command {
+  constructor(
+    public readonly email: string,
+    public readonly name: string,
+  ) {
+    super();
+  }
+}
+```
+
+### 3. Rejestracja handlerów
+
+```typescript
+commandBus.handle(CreateUserCommand, async (command) => {
+  console.log(`Creating user: ${command.name} (${command.email})`);
+
+  // Twoja logika biznesowa
+  const user = await createUser(command.email, command.name);
+
+  // Zwróć wynik (opcjonalnie)
+  return { userId: user.id };
+});
+```
+
+### 4. Wysyłanie komend (Fire-and-forget)
+
+```typescript
+const command = new CreateUserCommand('jan.kowalski@example.com', 'Jan Kowalski');
+
+// Wyślij komendę bez oczekiwania na wynik
+await commandBus.dispatch(command);
+```
+
+### 5. RPC - wywołania synchroniczne
+
+```typescript
+// Wywołaj komendę i poczekaj na wynik
+const result = await commandBus.call<{ userId: string }>(command, 5000); // timeout 5s
+
+console.log(`User created with ID: ${result.userId}`);
+```
+
+## Konfiguracja zaawansowana
+
+### Opcje Redis
+
+```typescript
+const config = new CommandBusConfig({
+  redis: {
+    host: 'localhost',
+    port: 6379,
+    password: 'your-password',
+    db: 0,
+    maxRetriesPerRequest: 3,
+    enableReadyCheck: true,
+    enableOfflineQueue: true,
+  },
+  // ... pozostałe opcje
+});
+```
+
+### RPC Persistence
+
+Zapisywanie pending RPC calls do Redis dla odporności na restarty:
+
+```typescript
+const config = new CommandBusConfig({
+  // ... redis config
+  rpcPersistence: true, // Włącz persistence
+});
+```
+
+### Command Logging
+
+Logowanie komend do plików w formacie JSON:
+
+```typescript
+const config = new CommandBusConfig({
+  // ... redis config
+  commandLog: {
+    enabled: true,
+    directory: './command-logs',
+    rotationInterval: 3600000, // 1 godzina
+    maxFiles: 24, // Zachowaj 24 pliki
+  },
+});
+```
+
+### Concurrency i Retry
+
+```typescript
+const config = new CommandBusConfig({
+  // ... redis config
+  concurrency: 10, // Liczba równoległych workerów
+  maxAttempts: 5, // Maksymalna liczba prób
+  replyWorkerConcurrency: 3, // Concurrency dla reply workera
+});
+```
+
+### Custom Logger
+
+```typescript
+import type { ILogger } from 'pp-command-bus';
+
+class MyLogger implements ILogger {
+  log(message: string, ...args: unknown[]): void {
+    // Twoja implementacja
+  }
+
+  error(message: string, ...args: unknown[]): void {
+    // Twoja implementacja
+  }
+
+  warn(message: string, ...args: unknown[]): void {
+    // Twoja implementacja
+  }
+
+  debug(message: string, ...args: unknown[]): void {
+    // Twoja implementacja
+  }
+}
+
+const config = new CommandBusConfig({
+  // ... redis config
+  logger: new MyLogger(),
+  logLevel: 'info', // debug | info | warn | error
+});
+```
+
+## API Reference
+
+### CommandBus
+
+#### `dispatch(command: Command): Promise<void>`
+
+Wysyła komendę do kolejki bez oczekiwania na wynik (fire-and-forget).
+
+#### `call<T>(command: Command, timeout?: number): Promise<T>`
+
+Wywołuje komendę synchronicznie i czeka na odpowiedź (RPC). Domyślny timeout: 30s.
+
+#### `handle<T>(commandClass, handler): void`
+
+Rejestruje handler dla określonej klasy komendy.
+
+#### `waitUntilReady(timeout?: number): Promise<void>`
+
+Czeka aż CommandBus zakończy inicjalizację. Domyślny timeout: 30s.
+
+#### `getMemoryStats(): MemoryStats`
+
+Zwraca statystyki pamięci i wewnętrznego stanu (diagnostyka memory leaków).
+
+#### `close(): Promise<void>`
+
+Zamyka wszystkie połączenia i workery.
+
+### Command
+
+Klasa bazowa dla wszystkich komend. Każda komenda dziedziczy po `Command`:
+
+```typescript
+class MyCommand extends Command {
+  constructor(public readonly data: string) {
+    super();
+  }
+}
+```
+
+Każda komenda ma:
+- `__id` - unikalny UUID
+- `__name` - nazwa klasy komendy
+- `__timestamp` - timestamp utworzenia
+
+### CommandBusConfig
+
+Konfiguracja CommandBus z opcjami:
+
+```typescript
+interface CommandBusConfigOptions {
+  redis: RedisOptions; // Opcje połączenia Redis
+  logger: ILogger; // Logger (console lub custom)
+  logLevel?: 'debug' | 'info' | 'warn' | 'error'; // Poziom logowania
+  concurrency?: number; // Liczba workerów (domyślnie 5)
+  maxAttempts?: number; // Maksymalna liczba prób (domyślnie 3)
+  replyWorkerConcurrency?: number; // Concurrency reply workera (domyślnie 1)
+  rpcPersistence?: boolean; // RPC persistence (domyślnie false)
+  commandLog?: CommandLogConfig; // Konfiguracja logowania komend
+}
+```
+
+## Migracja z pp-event-bus 1.x
+
+Jeśli używałeś Command Bus z pakietu `pp-event-bus` w wersji 1.x:
+
+### Przed:
+
+```typescript
+import { CommandBus, Command, CommandBusConfig } from 'pp-event-bus';
+```
+
+### Po:
+
+```bash
+npm install pp-command-bus
+```
+
+```typescript
+import { CommandBus, Command, CommandBusConfig } from 'pp-command-bus';
+```
+
+**Pełna zgodność API** - jedyna zmiana to źródło importu.
+
+## Best Practices
+
+### 1. Używaj TypeScript
+
+Biblioteka jest napisana w TypeScript z strict mode. Wykorzystaj typy dla lepszego DX:
+
+```typescript
+interface UserCreatedResult {
+  userId: string;
+  createdAt: Date;
+}
+
+const result = await commandBus.call<UserCreatedResult>(command);
+```
+
+### 2. Idempotentne handlery
+
+Handlery powinny być idempotentne (wielokrotne wykonanie = ten sam rezultat):
+
+```typescript
+commandBus.handle(CreateUserCommand, async (command) => {
+  // Sprawdź czy użytkownik już istnieje
+  const existing = await findUserByEmail(command.email);
+  if (existing) {
+    return { userId: existing.id }; // Zwróć istniejącego
+  }
+
+  // Utwórz nowego
+  const user = await createUser(command.email, command.name);
+  return { userId: user.id };
+});
+```
+
+### 3. Obsługa błędów
+
+```typescript
+commandBus.handle(CreateUserCommand, async (command) => {
+  try {
+    const user = await createUser(command.email, command.name);
+    return { userId: user.id };
+  } catch (error) {
+    // Loguj błąd
+    console.error('Failed to create user:', error);
+
+    // Rzuć błąd - BullMQ spróbuje ponownie (maxAttempts)
+    throw error;
+  }
+});
+```
+
+### 4. Graceful shutdown
+
+```typescript
+process.on('SIGTERM', async () => {
+  console.log('Shutting down CommandBus...');
+  await commandBus.close();
+  process.exit(0);
+});
+```
+
+### 5. Memory leak monitoring
+
+```typescript
+setInterval(() => {
+  const stats = commandBus.getMemoryStats();
+
+  console.log('CommandBus memory stats:', {
+    pendingRpcCalls: stats.rpc.pendingCallsCount,
+    queueCount: stats.queues.commandQueuesCount,
+    replyQueuesCacheSize: stats.queues.replyQueuesCacheSize,
+    activeWorkers: stats.workers.activeWorkersCount,
+  });
+}, 60000); // Co minutę
+```
+
+## Testing
+
+### Unit testy
+
+```typescript
+import { CommandBus, CommandBusConfig, Command } from 'pp-command-bus';
+
+describe('User Commands', () => {
+  let commandBus: CommandBus;
+
+  beforeAll(async () => {
+    const config = new CommandBusConfig({
+      redis: { host: 'localhost', port: 6379 },
+      logger: console,
+    });
+
+    commandBus = new CommandBus(config);
+    await commandBus.waitUntilReady();
+  });
+
+  afterAll(async () => {
+    await commandBus.close();
+  });
+
+  it('should create user', async () => {
+    const command = new CreateUserCommand('test@example.com', 'Test User');
+    const result = await commandBus.call<{ userId: string }>(command);
+
+    expect(result.userId).toBeDefined();
+  });
+});
+```
+
+## Troubleshooting
+
+### Connection refused (Redis)
+
+Upewnij się że Redis działa:
+
+```bash
+redis-cli ping
+# Powinno zwrócić: PONG
+```
+
+### Timeout na RPC call
+
+Zwiększ timeout lub sprawdź czy handler został zarejestrowany:
+
+```typescript
+// Zwiększ timeout
+const result = await commandBus.call(command, 60000); // 60s
+
+// Sprawdź zarejestrowane handlery
+const stats = commandBus.getMemoryStats();
+console.log('Registered handlers:', stats.handlers.handlerNames);
+```
+
+### Memory leaks
+
+Użyj `getMemoryStats()` do diagnostyki:
+
+```typescript
+const stats = commandBus.getMemoryStats();
+
+// Sprawdź pending RPC calls
+if (stats.rpc.pendingCallsCount > 100) {
+  console.warn('Too many pending RPC calls!', stats.rpc.pendingCallsDetails);
+}
+
+// Sprawdź reply queues cache
+if (stats.queues.replyQueuesCacheSize > 50) {
+  console.warn('Reply queues cache too large!');
+}
+```
+
+## Licencja
+
+MIT
+
+## Autorzy
+- Mariusz Lejkowski <m.lejkowski@polskiepolisy.pl>
+
+## Wersjonowanie i Releases
+
+Projekt używa [Semantic Versioning](https://semver.org/lang/pl/) oraz automatycznych release'ów dzięki [semantic-release](https://github.com/semantic-release/semantic-release).
+
+### Konwencja commitów
+
+Używamy [Conventional Commits](https://www.conventionalcommits.org/):
+
+```bash
+# Nowa funkcjonalność (minor release)
+feat: dodano wsparcie dla delayed commands
+
+# Poprawka błędu (patch release)
+fix: naprawiono memory leak w RPC
+
+# Breaking change (major release)
+feat!: zmieniono API CommandBusConfig
+
+# Inne typy (patch release)
+docs: zaktualizowano dokumentację API
+perf: zoptymalizowano przetwarzanie komend
+refactor: uproszczono kod RPC handler
+test: dodano testy dla command logging
+```
+
+### Typy commitów
+
+- `feat:` - nowa funkcjonalność (→ minor release)
+- `fix:` - poprawka błędu (→ patch release)
+- `perf:` - optymalizacja wydajności (→ patch release)
+- `docs:` - zmiany w dokumentacji (→ patch release)
+- `style:` - formatowanie kodu (→ patch release)
+- `refactor:` - refaktoryzacja (→ patch release)
+- `test:` - dodanie/poprawka testów (→ patch release)
+- `build:` - zmiany w buildzie/zależnościach (→ patch release)
+- `ci:` - zmiany w CI/CD (→ patch release)
+- `chore:` - inne zmiany (bez release)
+- `!` lub `BREAKING CHANGE:` - breaking change (→ major release)
+
+### Proces release
+
+1. **Commituj zgodnie z konwencją** - husky sprawdzi format commita
+2. **Merge do master** - GitLab CI automatycznie:
+   - Uruchomi testy i linting
+   - Zbuduje projekt
+   - Wygeneruje nową wersję (semantic-release)
+   - Zaktualizuje CHANGELOG.md
+   - Opublikuje do npm
+   - Utworzy GitLab release
+
+### Branch model
+
+- `master` - branch produkcyjny (→ release do npm)
+- `beta` - branch pre-release (→ beta release do npm)
+- feature branches - tworzenie nowych funkcjonalności
+
+### CI/CD Pipeline
+
+GitLab CI wykonuje następujące etapy:
+
+**Quality Stage:**
+- `lint` - sprawdzenie jakości kodu (ESLint + Prettier)
+- `test` - testy jednostkowe i coverage
+
+**Build Stage:**
+- `build` - kompilacja TypeScript do JavaScript
+
+**Release Stage:**
+- `release:production` - automatyczny release z master
+- `release:beta` - automatyczny release z beta
+- `release:dry-run` - podgląd zmian (manual trigger)
+
+### Zmienne środowiskowe w GitLab
+
+Aby pipeline działał, skonfiguruj w GitLab CI/CD Settings → Variables:
+
+- `NPM_TOKEN` - token do publikacji w npm (z scope publish)
+- `GITLAB_TOKEN` - token do tworzenia release'ów w GitLab
+
+### Testowanie release lokalnie
+
+```bash
+# Podgląd co zostanie wypuszczone
+npm run semantic-release:dry-run
+
+# Sprawdzenie ostatniego release
+git tag --sort=-v:refname | head -n 1
+```
+
+## Linki
+
+- [GitLab Repository](https://gitlab.polskiepolisy.pl/lib/pp-command-bus)
+- [Issue Tracker](https://gitlab.polskiepolisy.pl/lib/pp-command-bus/issues)
+- [BullMQ Documentation](https://docs.bullmq.io/)
+- [Semantic Versioning](https://semver.org/lang/pl/)
+- [Conventional Commits](https://www.conventionalcommits.org/)

package/dist/command-bus/command-bus.spec.d.ts

@@ -0,0 +1 @@
+export {};