@open-core/framework 1.0.2-beta.1 → 1.0.5-beta.1

package/dist/kernel/logger/transports/console.transport.js

@@ -0,0 +1,121 @@
+import { LogDomain, LogDomainLabels, LogLevel, LogLevelLabels, } from '../logger.types';
+/**
+ * Color codes for console output.
+ * Uses ANSI escape codes compatible with most terminals.
+ */
+const COLORS = {
+    reset: '\x1b[0m',
+    dim: '\x1b[2m',
+    bold: '\x1b[1m',
+    cyan: '\x1b[36m',
+    green: '\x1b[32m',
+    yellow: '\x1b[33m',
+    red: '\x1b[31m',
+    magenta: '\x1b[35m',
+    white: '\x1b[37m',
+    blue: '\x1b[34m',
+    bgRed: '\x1b[41m',
+    bgYellow: '\x1b[43m',
+    bgBlue: '\x1b[44m',
+    bgMagenta: '\x1b[45m',
+};
+const LEVEL_COLORS = {
+    [LogLevel.TRACE]: COLORS.dim,
+    [LogLevel.DEBUG]: COLORS.cyan,
+    [LogLevel.INFO]: COLORS.green,
+    [LogLevel.WARN]: COLORS.yellow,
+    [LogLevel.ERROR]: COLORS.red,
+    [LogLevel.FATAL]: COLORS.magenta,
+    [LogLevel.OFF]: COLORS.white,
+};
+/**
+ * Domain colors - distinctive to quickly identify log origin.
+ */
+const DOMAIN_COLORS = {
+    [LogDomain.FRAMEWORK]: COLORS.magenta,
+    [LogDomain.SERVER]: COLORS.blue,
+    [LogDomain.CLIENT]: COLORS.cyan,
+    [LogDomain.EXTERNAL]: COLORS.yellow,
+};
+/**
+ * Default transport that outputs logs to the console.
+ * Supports colored output and configurable formatting.
+ *
+ * @example
+ * ```typescript
+ * const transport = new ConsoleTransport({
+ *   minLevel: LogLevel.DEBUG,
+ *   colors: true,
+ *   timestamps: true
+ * })
+ * ```
+ */
+export class ConsoleTransport {
+    name = 'console';
+    minLevel;
+    colors;
+    timestamps;
+    constructor(options = {}) {
+        this.minLevel = options.minLevel ?? LogLevel.DEBUG;
+        this.colors = options.colors ?? true;
+        this.timestamps = options.timestamps ?? true;
+    }
+    write(entry) {
+        const { level, domain, message, timestamp, context, error } = entry;
+        const levelLabel = LogLevelLabels[level].padEnd(5);
+        const domainLabel = LogDomainLabels[domain];
+        const levelColor = this.colors ? LEVEL_COLORS[level] : '';
+        const domainColor = this.colors ? DOMAIN_COLORS[domain] : '';
+        const reset = this.colors ? COLORS.reset : '';
+        const dim = this.colors ? COLORS.dim : '';
+        const bold = this.colors ? COLORS.bold : '';
+        // Build the log line
+        const parts = [];
+        if (this.timestamps) {
+            const time = timestamp.split('T')[1]?.slice(0, 12) ?? timestamp;
+            parts.push(`${dim}[${time}]${reset}`);
+        }
+        // Domain tag - always shown for context
+        parts.push(`${domainColor}${bold}[${domainLabel}]${reset}`);
+        // Level
+        parts.push(`${levelColor}${levelLabel}${reset}`);
+        // Source module/controller
+        if (context?.source) {
+            parts.push(`${dim}[${context.source}]${reset}`);
+        }
+        parts.push(message);
+        // Output the main log line
+        const logLine = parts.join(' ');
+        // Choose the appropriate console method
+        switch (level) {
+            case LogLevel.TRACE:
+            case LogLevel.DEBUG:
+                console.debug(logLine);
+                break;
+            case LogLevel.INFO:
+                console.info(logLine);
+                break;
+            case LogLevel.WARN:
+                console.warn(logLine);
+                break;
+            case LogLevel.ERROR:
+            case LogLevel.FATAL:
+                console.error(logLine);
+                break;
+            default:
+                console.log(logLine);
+        }
+        // Output context if present (excluding source and domain which are already shown)
+        if (context) {
+            // eslint-disable-next-line @typescript-eslint/no-unused-vars
+            const { source, domain: _, ...rest } = context;
+            if (Object.keys(rest).length > 0) {
+                console.debug(`${dim}  └─ context:${reset}`, rest);
+            }
+        }
+        // Output error stack if present
+        if (error?.stack) {
+            console.error(`${dim}  └─ stack:${reset}`, error.stack);
+        }
+    }
+}

package/dist/kernel/logger/transports/dev-transport.factory.d.ts

@@ -0,0 +1,75 @@
+import { LogLevel } from '../logger.types';
+import { HttpLogTransport, type HttpTransportOptions } from './http.transport';
+import { LogTransport } from './transport.interface';
+import { WebSocketLogTransport, type WebSocketTransportOptions } from './websocket.transport';
+/**
+ * Runtime environment detection.
+ */
+export type RuntimeEnvironment = 'cfx' | 'node';
+/**
+ * Options for creating a dev transport.
+ */
+export interface DevTransportOptions {
+    /** HTTP endpoint URL for Cfx mode */
+    httpUrl: string;
+    /** WebSocket URL for Node.js mode */
+    wsUrl?: string;
+    /** Force a specific transport type */
+    forceTransport?: 'http' | 'websocket';
+    /** Minimum log level */
+    minLevel?: LogLevel;
+    /** HTTP transport specific options */
+    httpOptions?: Partial<Omit<HttpTransportOptions, 'url'>>;
+    /** WebSocket transport specific options */
+    wsOptions?: Partial<Omit<WebSocketTransportOptions, 'url'>>;
+}
+/**
+ * Detects the current runtime environment.
+ *
+ * @returns 'cfx' if running in CitizenFX, 'node' otherwise
+ */
+export declare function detectEnvironment(): RuntimeEnvironment;
+/**
+ * Checks if WebSocket is available in the current environment.
+ */
+export declare function isWebSocketAvailable(): boolean;
+/**
+ * Creates the appropriate log transport based on the runtime environment.
+ *
+ * - In Cfx: Uses HttpLogTransport (Node.js http module)
+ * - In Node.js: Uses WebSocketLogTransport if available, otherwise HttpLogTransport
+ *
+ * @param options - Transport configuration
+ * @returns Configured log transport
+ *
+ * @example
+ * ```typescript
+ * const transport = createDevTransport({
+ *   httpUrl: 'http://localhost:3847/logs',
+ *   wsUrl: 'ws://localhost:3848',
+ * })
+ *
+ * if ('start' in transport) {
+ *   transport.start() // HTTP transport
+ * } else if ('connect' in transport) {
+ *   await transport.connect() // WebSocket transport
+ * }
+ * ```
+ */
+export declare function createDevTransport(options: DevTransportOptions): LogTransport;
+/**
+ * Type guard to check if transport is HttpLogTransport.
+ */
+export declare function isHttpTransport(transport: LogTransport): transport is HttpLogTransport;
+/**
+ * Type guard to check if transport is WebSocketLogTransport.
+ */
+export declare function isWebSocketTransport(transport: LogTransport): transport is WebSocketLogTransport;
+/**
+ * Starts the transport (handles both HTTP and WebSocket).
+ */
+export declare function startDevTransport(transport: LogTransport): Promise<void>;
+/**
+ * Stops the transport (handles both HTTP and WebSocket).
+ */
+export declare function stopDevTransport(transport: LogTransport): Promise<void>;

package/dist/kernel/logger/transports/dev-transport.factory.js

@@ -0,0 +1,101 @@
+import { LogLevel } from '../logger.types';
+import { HttpLogTransport } from './http.transport';
+import { WebSocketLogTransport } from './websocket.transport';
+/**
+ * Detects the current runtime environment.
+ *
+ * @returns 'cfx' if running in CitizenFX, 'node' otherwise
+ */
+export function detectEnvironment() {
+    // Check for CitizenFX globals
+    if (typeof GetCurrentResourceName === 'function') {
+        return 'cfx';
+    }
+    return 'node';
+}
+/**
+ * Checks if WebSocket is available in the current environment.
+ */
+export function isWebSocketAvailable() {
+    return typeof WebSocket !== 'undefined';
+}
+/**
+ * Creates the appropriate log transport based on the runtime environment.
+ *
+ * - In Cfx: Uses HttpLogTransport (Node.js http module)
+ * - In Node.js: Uses WebSocketLogTransport if available, otherwise HttpLogTransport
+ *
+ * @param options - Transport configuration
+ * @returns Configured log transport
+ *
+ * @example
+ * ```typescript
+ * const transport = createDevTransport({
+ *   httpUrl: 'http://localhost:3847/logs',
+ *   wsUrl: 'ws://localhost:3848',
+ * })
+ *
+ * if ('start' in transport) {
+ *   transport.start() // HTTP transport
+ * } else if ('connect' in transport) {
+ *   await transport.connect() // WebSocket transport
+ * }
+ * ```
+ */
+export function createDevTransport(options) {
+    const env = detectEnvironment();
+    const minLevel = options.minLevel ?? LogLevel.DEBUG;
+    // If forced transport type is specified, use it
+    if (options.forceTransport === 'http') {
+        return new HttpLogTransport({ url: options.httpUrl, ...options.httpOptions }, minLevel);
+    }
+    if (options.forceTransport === 'websocket') {
+        const wsUrl = options.wsUrl ?? options.httpUrl.replace('http', 'ws');
+        return new WebSocketLogTransport({ url: wsUrl, ...options.wsOptions }, minLevel);
+    }
+    // Auto-detect based on environment
+    if (env === 'cfx') {
+        // Cfx runtime: Always use HTTP (WebSocket not available in game runtime)
+        return new HttpLogTransport({ url: options.httpUrl, ...options.httpOptions }, minLevel);
+    }
+    // Node.js: Prefer WebSocket if available, otherwise use HTTP
+    if (isWebSocketAvailable() && options.wsUrl) {
+        return new WebSocketLogTransport({ url: options.wsUrl, ...options.wsOptions }, minLevel);
+    }
+    // Fallback to HTTP
+    return new HttpLogTransport({ url: options.httpUrl, ...options.httpOptions }, minLevel);
+}
+/**
+ * Type guard to check if transport is HttpLogTransport.
+ */
+export function isHttpTransport(transport) {
+    return transport.name === 'http';
+}
+/**
+ * Type guard to check if transport is WebSocketLogTransport.
+ */
+export function isWebSocketTransport(transport) {
+    return transport.name === 'websocket';
+}
+/**
+ * Starts the transport (handles both HTTP and WebSocket).
+ */
+export async function startDevTransport(transport) {
+    if (isHttpTransport(transport)) {
+        transport.start();
+    }
+    else if (isWebSocketTransport(transport)) {
+        await transport.connect();
+    }
+}
+/**
+ * Stops the transport (handles both HTTP and WebSocket).
+ */
+export async function stopDevTransport(transport) {
+    if (isHttpTransport(transport)) {
+        await transport.stop();
+    }
+    else if (isWebSocketTransport(transport)) {
+        transport.destroy();
+    }
+}

package/dist/kernel/logger/transports/http.transport.d.ts

@@ -0,0 +1,67 @@
+import { type LogEntry, LogLevel } from '../logger.types';
+import { LogTransport } from './transport.interface';
+/**
+ * Configuration for HTTP log transport.
+ */
+export interface HttpTransportOptions {
+    /** HTTP endpoint URL (e.g., 'http://localhost:3847/logs') */
+    url: string;
+    /** Request timeout in milliseconds */
+    timeout?: number;
+    /** Batch size - number of logs to send per request */
+    batchSize?: number;
+    /** Flush interval in milliseconds */
+    flushInterval?: number;
+    /** Maximum buffer size */
+    maxBufferSize?: number;
+}
+/**
+ * HTTP-based log transport for streaming logs to external tools.
+ *
+ * Compatible with FiveM's Node.js runtime. Uses batched HTTP POST requests
+ * instead of WebSocket for environments where WebSocket is unavailable.
+ *
+ * @example
+ * ```typescript
+ * const transport = new HttpLogTransport({
+ *   url: 'http://localhost:3847/logs',
+ *   batchSize: 10,
+ *   flushInterval: 1000,
+ * })
+ * transport.start()
+ * ```
+ */
+export declare class HttpLogTransport implements LogTransport {
+    readonly name = "http";
+    minLevel: LogLevel;
+    private buffer;
+    private options;
+    private flushTimer;
+    private isSending;
+    private parsedUrl;
+    constructor(options: HttpTransportOptions, minLevel?: LogLevel);
+    /**
+     * Starts the flush timer for periodic log sending.
+     */
+    start(): void;
+    /**
+     * Stops the transport and flushes remaining logs.
+     */
+    stop(): Promise<void>;
+    /**
+     * Writes a log entry to the buffer.
+     */
+    write(entry: LogEntry): void;
+    /**
+     * Flushes buffered logs to the server.
+     */
+    flush(): Promise<void>;
+    /**
+     * Sends logs via HTTP POST.
+     */
+    private sendLogs;
+    /**
+     * Destroys the transport and clears resources.
+     */
+    destroy(): void;
+}

package/dist/kernel/logger/transports/http.transport.js

@@ -0,0 +1,168 @@
+import { LogLevel } from '../logger.types';
+// Lazy-loaded http module (only loaded at runtime, not bundled)
+let httpModule = null;
+// Use variable to prevent esbuild from statically analyzing the require
+const HTTP_MODULE = 'http';
+function getHttpSync() {
+    if (!httpModule) {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        httpModule = require(HTTP_MODULE);
+    }
+    return httpModule;
+}
+/**
+ * HTTP-based log transport for streaming logs to external tools.
+ *
+ * Compatible with FiveM's Node.js runtime. Uses batched HTTP POST requests
+ * instead of WebSocket for environments where WebSocket is unavailable.
+ *
+ * @example
+ * ```typescript
+ * const transport = new HttpLogTransport({
+ *   url: 'http://localhost:3847/logs',
+ *   batchSize: 10,
+ *   flushInterval: 1000,
+ * })
+ * transport.start()
+ * ```
+ */
+export class HttpLogTransport {
+    name = 'http';
+    minLevel;
+    buffer = [];
+    options;
+    flushTimer = null;
+    isSending = false;
+    parsedUrl;
+    constructor(options, minLevel = LogLevel.DEBUG) {
+        this.minLevel = minLevel;
+        this.options = {
+            url: options.url,
+            timeout: options.timeout ?? 5000,
+            batchSize: options.batchSize ?? 20,
+            flushInterval: options.flushInterval ?? 500,
+            maxBufferSize: options.maxBufferSize ?? 500,
+        };
+        this.parsedUrl = new URL(this.options.url);
+    }
+    /**
+     * Starts the flush timer for periodic log sending.
+     */
+    start() {
+        if (this.flushTimer)
+            return;
+        this.flushTimer = setInterval(() => {
+            void this.flush();
+        }, this.options.flushInterval);
+    }
+    /**
+     * Stops the transport and flushes remaining logs.
+     */
+    async stop() {
+        if (this.flushTimer) {
+            clearInterval(this.flushTimer);
+            this.flushTimer = null;
+        }
+        await this.flush();
+    }
+    /**
+     * Writes a log entry to the buffer.
+     */
+    write(entry) {
+        this.buffer.push(entry);
+        // Prevent buffer overflow
+        if (this.buffer.length > this.options.maxBufferSize) {
+            this.buffer.shift();
+        }
+        // Flush immediately if batch size reached
+        if (this.buffer.length >= this.options.batchSize) {
+            void this.flush();
+        }
+    }
+    /**
+     * Flushes buffered logs to the server.
+     */
+    async flush() {
+        if (this.isSending || this.buffer.length === 0)
+            return;
+        this.isSending = true;
+        const logsToSend = this.buffer.splice(0, this.options.batchSize);
+        try {
+            await this.sendLogs(logsToSend);
+        }
+        catch {
+            // On error, put logs back at the front of the buffer
+            this.buffer.unshift(...logsToSend);
+            // But limit buffer size
+            if (this.buffer.length > this.options.maxBufferSize) {
+                this.buffer.length = this.options.maxBufferSize;
+            }
+        }
+        finally {
+            this.isSending = false;
+        }
+    }
+    /**
+     * Sends logs via HTTP POST.
+     */
+    sendLogs(logs) {
+        return new Promise((resolve, reject) => {
+            const http = getHttpSync();
+            const payload = JSON.stringify({
+                type: 'logs',
+                payload: logs.map((entry) => ({
+                    level: entry.level,
+                    domain: entry.domain,
+                    message: entry.message,
+                    timestamp: entry.timestamp,
+                    context: entry.context,
+                    error: entry.error
+                        ? {
+                            name: entry.error.name,
+                            message: entry.error.message,
+                            stack: entry.error.stack,
+                        }
+                        : undefined,
+                })),
+            });
+            const options = {
+                hostname: this.parsedUrl.hostname,
+                port: this.parsedUrl.port || 80,
+                path: this.parsedUrl.pathname,
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'Content-Length': Buffer.byteLength(payload),
+                },
+                timeout: this.options.timeout,
+            };
+            const req = http.request(options, (res) => {
+                // Consume response to free up memory
+                res.resume();
+                if (res.statusCode && res.statusCode >= 200 && res.statusCode < 300) {
+                    resolve();
+                }
+                else {
+                    reject(new Error(`HTTP ${res.statusCode}`));
+                }
+            });
+            req.on('error', reject);
+            req.on('timeout', () => {
+                req.destroy();
+                reject(new Error('Request timeout'));
+            });
+            req.write(payload);
+            req.end();
+        });
+    }
+    /**
+     * Destroys the transport and clears resources.
+     */
+    destroy() {
+        if (this.flushTimer) {
+            clearInterval(this.flushTimer);
+            this.flushTimer = null;
+        }
+        this.buffer = [];
+    }
+}

package/dist/kernel/logger/transports/index.d.ts

@@ -0,0 +1,7 @@
+export * from './buffered.transport';
+export { ConsoleTransport } from './console.transport';
+export { createDevTransport, type DevTransportOptions, detectEnvironment, isHttpTransport, isWebSocketTransport, type RuntimeEnvironment, startDevTransport, stopDevTransport, } from './dev-transport.factory';
+export { HttpLogTransport, type HttpTransportOptions } from './http.transport';
+export { SimpleConsoleTransport } from './simple-console.transport';
+export * from './transport.interface';
+export { WebSocketLogTransport, type WebSocketTransportOptions } from './websocket.transport';

package/dist/kernel/logger/transports/index.js

@@ -0,0 +1,7 @@
+export * from './buffered.transport';
+export { ConsoleTransport } from './console.transport';
+export { createDevTransport, detectEnvironment, isHttpTransport, isWebSocketTransport, startDevTransport, stopDevTransport, } from './dev-transport.factory';
+export { HttpLogTransport } from './http.transport';
+export { SimpleConsoleTransport } from './simple-console.transport';
+export * from './transport.interface';
+export { WebSocketLogTransport } from './websocket.transport';

package/dist/kernel/logger/transports/simple-console.transport.d.ts

@@ -0,0 +1,38 @@
+import { type LogEntry, LogLevel } from '../logger.types';
+import { LogTransport } from './transport.interface';
+export interface SimpleConsoleTransportOptions {
+    /**
+     * Minimum log level to output. Defaults to INFO.
+     */
+    minLevel?: LogLevel;
+    /**
+     * Whether to include timestamp in output. Defaults to true.
+     */
+    timestamps?: boolean;
+    /**
+     * Whether to show context data. Defaults to false for cleaner output.
+     */
+    showContext?: boolean;
+}
+/**
+ * Simple console transport without ANSI color codes.
+ * Designed for FiveM client console which doesn't support ANSI formatting.
+ *
+ * Output format: [HH:MM:SS.mmm] [DOMAIN] LEVEL [Source] Message
+ *
+ * @example
+ * ```typescript
+ * const transport = new SimpleConsoleTransport({
+ *   minLevel: LogLevel.INFO,
+ *   timestamps: true
+ * })
+ * ```
+ */
+export declare class SimpleConsoleTransport implements LogTransport {
+    readonly name = "simple-console";
+    minLevel: LogLevel;
+    private timestamps;
+    private showContext;
+    constructor(options?: SimpleConsoleTransportOptions);
+    write(entry: LogEntry): void;
+}

package/dist/kernel/logger/transports/simple-console.transport.js

@@ -0,0 +1,79 @@
+import { LogDomainLabels, LogLevel, LogLevelLabels } from '../logger.types';
+/**
+ * Simple console transport without ANSI color codes.
+ * Designed for FiveM client console which doesn't support ANSI formatting.
+ *
+ * Output format: [HH:MM:SS.mmm] [DOMAIN] LEVEL [Source] Message
+ *
+ * @example
+ * ```typescript
+ * const transport = new SimpleConsoleTransport({
+ *   minLevel: LogLevel.INFO,
+ *   timestamps: true
+ * })
+ * ```
+ */
+export class SimpleConsoleTransport {
+    name = 'simple-console';
+    minLevel;
+    timestamps;
+    showContext;
+    constructor(options = {}) {
+        this.minLevel = options.minLevel ?? LogLevel.INFO;
+        this.timestamps = options.timestamps ?? true;
+        this.showContext = options.showContext ?? false;
+    }
+    write(entry) {
+        const { level, domain, message, timestamp, context, error } = entry;
+        const levelLabel = LogLevelLabels[level].padEnd(5);
+        const domainLabel = LogDomainLabels[domain];
+        // Build the log line without ANSI codes
+        const parts = [];
+        if (this.timestamps) {
+            const time = timestamp.split('T')[1]?.slice(0, 12) ?? timestamp;
+            parts.push(`[${time}]`);
+        }
+        // Domain tag
+        parts.push(`[${domainLabel}]`);
+        // Level
+        parts.push(levelLabel);
+        // Source module/controller
+        if (context?.source) {
+            parts.push(`[${context.source}]`);
+        }
+        parts.push(message);
+        // Output the main log line
+        const logLine = parts.join(' ');
+        // Choose the appropriate console method
+        switch (level) {
+            case LogLevel.TRACE:
+            case LogLevel.DEBUG:
+                console.debug(logLine);
+                break;
+            case LogLevel.INFO:
+                console.info(logLine);
+                break;
+            case LogLevel.WARN:
+                console.warn(logLine);
+                break;
+            case LogLevel.ERROR:
+            case LogLevel.FATAL:
+                console.error(logLine);
+                break;
+            default:
+                console.log(logLine);
+        }
+        // Output context only if enabled and present
+        if (this.showContext && context) {
+            // eslint-disable-next-line @typescript-eslint/no-unused-vars
+            const { source, domain: _, ...rest } = context;
+            if (Object.keys(rest).length > 0) {
+                console.debug('  context:', JSON.stringify(rest));
+            }
+        }
+        // Output error stack if present
+        if (error?.stack) {
+            console.error('  stack:', error.stack);
+        }
+    }
+}