orcas-angular 1.0.0

package/localization/localization.service.ts

@@ -0,0 +1,131 @@
+import { computed, inject, Injectable, signal } from '@angular/core';
+import { HttpClient } from '@angular/common/http';
+import { ILocalizationService } from './localization.interface';
+
+@Injectable({
+  providedIn: 'root'
+})
+export class LocalizationService implements ILocalizationService {
+  private defaultLanguage = 'en';
+  private storageKey = 'orcas-language';
+
+  private translations: any = {};
+  private loaded = false;
+
+  private $language: ReturnType<typeof signal<string>>;
+  public $currentLang = computed(() => this.$language());
+
+  private http = inject(HttpClient);
+
+  constructor() {
+    this.$language = signal(this.getStoredLanguage());
+  }
+
+  public async init(
+    jsonPath: string = 'assets/translations.json',
+    defaultLanguage: string = 'en',
+    storageKey: string = 'orcas-language'
+  ): Promise<void> {
+    this.defaultLanguage = defaultLanguage;
+    this.storageKey = storageKey;
+    this.$language.set(this.getStoredLanguage());
+
+    try {
+      this.translations = await this.http.get(jsonPath).toPromise();
+      this.loaded = true;
+    }
+    catch (err) {
+      console.error('Failed to load translations:', err);
+    }
+  }
+
+  getLanguage(): string {
+    return this.$language();
+  }
+
+  getDefaultLanguage(): string {
+    return this.defaultLanguage;
+  }
+
+  setActiveLanguage(lang: string): void {
+    if (lang !== this.$language()) {
+      localStorage.setItem(this.storageKey, lang);
+      this.$language.set(lang);
+    }
+  }
+
+  translate(key: string, params?: any, language?: string): string {
+    const lang = language || this.getLanguage();
+
+    if (!this.loaded) {
+      console.error('Localization: Translations not loaded yet!');
+      return key;
+    }
+
+    let translation = null;
+
+    // Handle pluralization: try singular suffix __1 first if count is 1
+    if (params && params.count === 1)
+      translation = this.resolveKey(`${key}__1`);
+
+    if (!translation)
+      translation = this.resolveKey(key);
+
+    if (!translation) {
+      console.warn(`Localization: Key not found for "${key}".`);
+      return key;
+    }
+
+    let translatedText = translation[lang];
+
+    if (!translatedText) {
+      console.warn(`Localization: Key "${key}" not found for language "${lang}". Falling back to default language.`);
+      translatedText = translation[this.defaultLanguage];
+    }
+
+    if (!translatedText) {
+      console.error(`Localization: Key "${key}" not found for default language "${this.defaultLanguage}".`);
+      return key;
+    }
+
+    if (params) {
+      if (Array.isArray(params))
+        return this.replaceArrayParams(translatedText, params);
+      else
+        return this.replaceObjectParams(translatedText, params);
+    }
+
+    return translatedText;
+  }
+
+  private resolveKey(key: string): any {
+    const keys = key.split('.');
+    let translation = this.translations;
+    for (const k of keys) {
+      if (!translation[k])
+        return null;
+      translation = translation[k];
+    }
+    return translation;
+  }
+
+  private getStoredLanguage(): string {
+    return localStorage.getItem(this.storageKey) || this.defaultLanguage;
+  }
+
+  private replaceArrayParams(text: string, params: any[]): string {
+    let result = text;
+    params.forEach((param, index) => {
+      result = result.replace(new RegExp(`\\{\\{${index}\\}\\}`, 'g'), param.toString());
+    });
+    return result;
+  }
+
+  private replaceObjectParams(text: string, params: any): string {
+    let result = text;
+    Object.keys(params).forEach(key => {
+      result = result.replace(new RegExp(`\\{\\{${key}\\}\\}`, 'g'), params[key].toString());
+    });
+    return result;
+  }
+}

package/localization/localize.pipe.ts

@@ -0,0 +1,30 @@
+import {Pipe, PipeTransform} from '@angular/core';
+import {LocalizationService} from './localization.service';
+
+@Pipe({
+    name: 'localize',
+    standalone: true,
+    pure: false
+})
+export class LocalizePipe implements PipeTransform {
+    private lastLanguage: string = '';
+    private lastKey: string = '';
+    private lastParams: any;
+    private lastResult: string = '';
+
+    constructor(private localizationService: LocalizationService) {
+    }
+
+    transform(key: string, params?: any): string {
+        if (this.localizationService.$currentLang() !== this.lastLanguage
+            || key !== this.lastKey
+            || params !== this.lastParams) {
+            this.lastLanguage = this.localizationService.$currentLang();
+            this.lastKey = key;
+            this.lastParams = params;
+            this.lastResult = this.localizationService.translate(key, params);
+        }
+
+        return this.lastResult;
+    }
+}

package/log/README.md

@@ -0,0 +1,275 @@
+# Echo TypeScript
+
+TypeScript port of the Echo.cs logging library. This is a flexible and powerful logging library with support for log levels, system-based organization, and custom log writers.
+
+## Features
+
+- Structured logging with system tags
+- Customizable log levels (per system or global)
+- String formatting with parameters (only formatted when log will be written)
+- Log-once functionality to prevent duplicate messages
+- Extensible with custom log writers
+- Console log writer with colors and timestamps included
+- TypeScript type safety
+- Performance optimized - no allocations when logs are filtered out
+
+## Installation
+
+```bash
+# Install dependencies
+npm install
+
+# Build the library
+npm run build
+```
+
+The compiled JavaScript and type definitions will be in the `dist/` folder.
+
+## Quick Start
+
+```typescript
+import { EchoConsole, LogLevel } from './dist/echo';
+
+// Create an Echo instance with default console writer
+const echo = EchoConsole.new();
+
+// Get a logger
+const logger = echo.getLogger();
+
+// Log messages
+logger.debug("System", "Debug message");
+logger.info("System", "Info message");
+logger.warn("System", "Warning message");
+logger.error("System", "Error message");
+```
+
+## Usage Examples
+
+### Basic Logging
+
+```typescript
+import { EchoConsole } from './echo';
+
+const echo = EchoConsole.new();
+const logger = echo.getLogger();
+
+// Log with different levels
+logger.debug("GUI", "This is a debug message from the GUI system.");
+logger.info("Physics", "This is an info message from the Physics system.");
+logger.warn("AI", "This is a warning message from the AI system.");
+logger.error("Rendering", "This is an error message from the Rendering system.");
+```
+
+### System Logger
+
+```typescript
+// Get a system-specific logger (cached per system)
+const animationLogger = echo.getSystemLogger("Animation");
+
+// No need to specify system in subsequent calls
+animationLogger.debug("This is a debug message from the Animation system.");
+animationLogger.info("This is an info message from the Animation system.");
+animationLogger.warn("This is a warning message from the Animation system.");
+animationLogger.error("This is an error message from the Animation system.");
+```
+
+### String Formatting
+
+```typescript
+// Use formatted strings with parameters
+// Formatting is only done IF the log will be written (performance optimization)
+const playerName = "John";
+const playerHealth = 100;
+logger.info("General", "Player {0} has {1} health.", playerName, playerHealth);
+// Output: Player John has 100 health.
+```
+
+### Log Level Management
+
+```typescript
+import { LogLevel } from './echo';
+
+// Set default log level (applies to all systems)
+echo.settings.setDefaultLevel(LogLevel.Warn); // Only Warn and Error will be logged
+
+// Set system-specific log level
+echo.settings.setSystemLevel("Physics", LogLevel.Debug); // Physics logs everything
+
+// Get current log level for a system
+const level = echo.settings.getSystemLevel("Physics");
+
+// Clear a system-specific level (reverts to default)
+echo.settings.clearSystemLevel("Physics");
+
+// Clear all system-specific levels
+echo.settings.clearSystemLevels();
+```
+
+### Log Once
+
+```typescript
+// Log a message only once, even if called multiple times
+logger.debug1("System", "This will only appear once");
+logger.debug1("System", "This will only appear once"); // Won't be logged
+logger.debug1("System", "This will only appear once"); // Won't be logged
+
+// Also works with other log levels
+logger.info1("System", "Info once");
+logger.warn1("System", "Warn once");
+logger.error1("System", "Error once");
+```
+
+### Custom Configuration
+
+```typescript
+import { LogWriterConfig, SystemColor } from './echo';
+
+const config = new LogWriterConfig();
+config.timestamp = true;           // Include timestamps (default: true)
+config.levelLabels = true;         // Include log level labels (default: true)
+config.levelColors = true;         // Use colors for log levels (default: true)
+config.systemColor = SystemColor.LabelAndMessage; // Color both label and message
+
+const echo = EchoConsole.new(config);
+```
+
+### Custom Log Writer
+
+```typescript
+import { Echo, EchoLogWriter, LogLevel } from './echo';
+
+class CustomLogWriter implements EchoLogWriter {
+    writeLog(level: LogLevel, system: string, message: string): void {
+        // Custom log writing logic here
+        const timestamp = new Date().toISOString();
+        console.log(`${timestamp} | ${level} | [${system}] ${message}`);
+    }
+}
+
+// Use custom writer
+const customWriter = new CustomLogWriter();
+const echo = new Echo(customWriter);
+```
+
+## API Reference
+
+### Echo Class
+
+Main entry point for the library.
+
+```typescript
+constructor(writer: EchoLogWriter)
+```
+
+- **getLogger()**: Returns the main logger instance (cached)
+- **getSystemLogger(system: string)**: Returns a system-specific logger (cached per system)
+- **settings**: Access to EchoSettings for configuration
+
+### EchoLogger Class
+
+Main logger with system parameter required.
+
+**Methods** (all have the same signature pattern):
+- **debug(system: string, message: string, ...params: any[])**
+- **info(system: string, message: string, ...params: any[])**
+- **warn(system: string, message: string, ...params: any[])**
+- **error(system: string, message: string, ...params: any[])**
+
+**Log-once variants** (append `1` to method name):
+- **debug1, info1, warn1, error1** - Same signatures as above
+
+### EchoSystemLogger Class
+
+System-specific logger (system is set at creation).
+
+**Methods** (no system parameter needed):
+- **debug(message: string, ...params: any[])**
+- **info(message: string, ...params: any[])**
+- **warn(message: string, ...params: any[])**
+- **error(message: string, ...params: any[])**
+
+**Log-once variants**:
+- **debug1, info1, warn1, error1** - Same signatures as above
+
+### EchoSettings Class
+
+Configuration for log levels.
+
+- **defaultLevel**: Get/set the default log level
+- **setDefaultLevel(level: LogLevel)**: Set default log level for all systems
+- **setSystemLevel(system: string, level: LogLevel)**: Set log level for specific system
+- **getSystemLevel(system: string)**: Get log level for specific system
+- **clearSystemLevel(system: string)**: Remove system-specific level
+- **clearSystemLevels()**: Remove all system-specific levels
+- **getAllSystemLevels()**: Get all system-specific levels
+- **onUpdated(callback: () => void)**: Register callback for settings updates
+
+### LogLevel Enum
+
+```typescript
+enum LogLevel {
+    None = 0,   // No logging
+    Error = 1,  // Errors only
+    Warn = 2,   // Warnings and errors
+    Info = 3,   // Info, warnings, and errors
+    Debug = 4   // All logs (most verbose)
+}
+```
+
+### LogWriterConfig Class
+
+Configuration for the console log writer.
+
+- **timestamp**: Include timestamps (default: true)
+- **levelLabels**: Include log level labels (default: true)
+- **levelColors**: Use colors for log levels (default: true)
+- **systemColor**: Control system color usage (default: SystemColor.LabelOnly)
+
+### SystemColor Enum
+
+```typescript
+enum SystemColor {
+    None,              // No color
+    LabelOnly,         // Color only the system label
+    LabelAndMessage    // Color both label and message
+}
+```
+
+### EchoConsole Helper
+
+Factory for creating Echo instances with console writer.
+
+```typescript
+EchoConsole.new(config?: LogWriterConfig): Echo
+```
+
+## Differences from C# Version
+
+The TypeScript port maintains the same API signatures as the C# version with these differences:
+
+1. **Case Convention**: TypeScript methods use camelCase (e.g., `getLogger()`) instead of PascalCase
+2. **Generic Overloads**: Instead of C# generic type parameters, TypeScript uses rest parameters (`...params: any[]`)
+3. **Events**: Instead of C# events, use `onUpdated(callback)` method to register callbacks
+4. **Properties**: C# properties become TypeScript getters/setters
+5. **No Unity**: This port excludes all Unity-specific features
+
+## Running the Demo
+
+```bash
+# Compile
+tsc echo.demo.ts
+
+# Run
+node echo.demo.js
+```
+
+## Running Tests
+
+```bash
+# Compile and run tests
+tsc && node echo.test.js
+```
+
+## License
+
+Copyright © 2025 Racso

package/log/echo-provider.ts

@@ -0,0 +1,27 @@
+/**
+ * Echo provider for Angular dependency injection.
+ * Provides a singleton Echo instance with console writer.
+ */
+import { InjectionToken, Provider } from '@angular/core';
+import { Echo, EchoConsole } from './echo';
+
+/**
+ * Injection token for Echo logger instance
+ */
+export const ECHO = new InjectionToken<Echo>('Echo Logger Instance');
+
+/**
+ * Factory function to create Echo instance
+ */
+export function echoFactory(): Echo {
+  return EchoConsole.new();
+}
+
+/**
+ * Provider for Echo logger
+ * Use this in your module providers or inject it in services
+ */
+export const ECHO_PROVIDER: Provider = {
+  provide: ECHO,
+  useFactory: echoFactory
+};