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

package/dist/kernel/logger/logger.service.js

@@ -0,0 +1,301 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { inject, injectable } from 'tsyringe';
+import { createLoggerConfig } from './logger.config';
+import { LogDomain, LogLevel } from './logger.types';
+/**
+ * Central logging service for the framework.
+ *
+ * Provides structured logging with support for multiple transports,
+ * log levels, and contextual metadata for traceability.
+ *
+ * @example
+ * ```typescript
+ * // Using with dependency injection
+ * @injectable()
+ * class MyController {
+ *   constructor(private logger: LoggerService) {}
+ *
+ *   doSomething() {
+ *     this.logger.info('Operation started', { source: 'MyController' })
+ *     this.logger.debug('Processing data', { playerId: 123 })
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Manual instantiation with custom config
+ * const logger = new LoggerService({
+ *   minLevel: LogLevel.INFO,
+ *   transports: [new ConsoleTransport(), new FileTransport()]
+ * })
+ * ```
+ */
+let LoggerService = class LoggerService {
+    config;
+    constructor(config) {
+        this.config = createLoggerConfig(config ?? {});
+    }
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Log Methods
+    // ─────────────────────────────────────────────────────────────────────────────
+    /**
+     * Log a TRACE level message. Most verbose, for deep debugging.
+     */
+    trace(message, context) {
+        this.log(LogLevel.TRACE, message, context);
+    }
+    /**
+     * Log a DEBUG level message. Development-time information.
+     */
+    debug(message, context) {
+        this.log(LogLevel.DEBUG, message, context);
+    }
+    /**
+     * Log an INFO level message. General operational information.
+     */
+    info(message, context) {
+        this.log(LogLevel.INFO, message, context);
+    }
+    /**
+     * Log a WARN level message. Something unexpected but not necessarily wrong.
+     */
+    warn(message, context) {
+        this.log(LogLevel.WARN, message, context);
+    }
+    /**
+     * Log an ERROR level message. Something went wrong but the app can continue.
+     */
+    error(message, context, error) {
+        this.log(LogLevel.ERROR, message, context, error);
+    }
+    /**
+     * Log a FATAL level message. Critical error, the app may need to stop.
+     */
+    fatal(message, context, error) {
+        this.log(LogLevel.FATAL, message, context, error);
+    }
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Transport Management
+    // ─────────────────────────────────────────────────────────────────────────────
+    /**
+     * Add a new transport to receive log entries.
+     *
+     * @example
+     * ```typescript
+     * logger.addTransport(new FileTransport({ path: './logs/app.log' }))
+     * ```
+     */
+    addTransport(transport) {
+        this.config.transports.push(transport);
+    }
+    /**
+     * Remove a transport by name.
+     */
+    removeTransport(name) {
+        const index = this.config.transports.findIndex((t) => t.name === name);
+        if (index === -1)
+            return false;
+        const [removed] = this.config.transports.splice(index, 1);
+        removed?.destroy?.();
+        return true;
+    }
+    /**
+     * Get all registered transports.
+     */
+    getTransports() {
+        return this.config.transports;
+    }
+    /**
+     * Clear all transports.
+     */
+    clearTransports() {
+        for (const transport of this.config.transports) {
+            transport.destroy?.();
+        }
+        this.config.transports = [];
+    }
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Configuration
+    // ─────────────────────────────────────────────────────────────────────────────
+    /**
+     * Update the global minimum log level.
+     */
+    setMinLevel(level) {
+        this.config.minLevel = level;
+    }
+    /**
+     * Get the current minimum log level.
+     */
+    getMinLevel() {
+        return this.config.minLevel;
+    }
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Domain-specific Loggers
+    // ─────────────────────────────────────────────────────────────────────────────
+    /**
+     * Create a server-level logger for server-side application code.
+     * These logs will be tagged with [SERVER] domain.
+     *
+     * @example
+     * ```typescript
+     * const authLogger = logger.server('AuthController')
+     * authLogger.info('User logged in') // [SERVER] INFO [AuthController] User logged in
+     * ```
+     */
+    server(source) {
+        return new ChildLogger(this, source, LogDomain.SERVER);
+    }
+    /**
+     * Create a framework-level logger for internal OpenCore logging.
+     * These logs will be tagged with [CORE] domain.
+     *
+     * @example
+     * ```typescript
+     * const coreLogger = logger.framework('Bootstrap')
+     * coreLogger.error('Missing config') // [CORE] ERROR [Bootstrap] Missing config
+     * ```
+     */
+    framework(source) {
+        return new ChildLogger(this, source, LogDomain.FRAMEWORK);
+    }
+    /**
+     * Create a client-level logger for client-side code.
+     * These logs will be tagged with [CLIENT] domain.
+     *
+     * @example
+     * ```typescript
+     * const hudLogger = logger.client('HUD')
+     * hudLogger.debug('Rendering') // [CLIENT] DEBUG [HUD] Rendering
+     * ```
+     */
+    client(source) {
+        return new ChildLogger(this, source, LogDomain.CLIENT);
+    }
+    /**
+     * Create an external services logger for third-party APIs, databases, etc.
+     * These logs will be tagged with [EXTERNAL] domain.
+     *
+     * @example
+     * ```typescript
+     * const stripeLogger = logger.external('StripeAPI')
+     * stripeLogger.warn('Rate limit') // [EXTERNAL] WARN [StripeAPI] Rate limit
+     * ```
+     */
+    external(source) {
+        return new ChildLogger(this, source, LogDomain.EXTERNAL);
+    }
+    /**
+     * Create a child logger with custom domain.
+     * Use this when you need a specific domain not covered by the convenience methods.
+     *
+     * @example
+     * ```typescript
+     * const customLogger = logger.child('MyModule', LogDomain.EXTERNAL)
+     * ```
+     */
+    child(source, domain) {
+        return new ChildLogger(this, source, domain);
+    }
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Internal
+    // ─────────────────────────────────────────────────────────────────────────────
+    /**
+     * Internal logging logic.
+     *
+     * @remarks
+     * This method performs a two-stage filtering process:
+     * 1. **Global Filtering**: Messages below the `config.minLevel` are ignored immediately.
+     * 2. **Transport Filtering**: Each transport can have its own `minLevel`. The message
+     *    is only sent to transports where `level >= transport.minLevel`.
+     *
+     * @param level - Severity of the log
+     * @param message - Content to log
+     * @param context - Metadata
+     * @param error - Optional error object
+     */
+    log(level, message, context, error) {
+        // Stage 1: Global minimum level filtering
+        if (level < this.config.minLevel)
+            return;
+        const entry = {
+            level,
+            domain: context?.domain ?? this.config.defaultDomain,
+            message,
+            timestamp: new Date().toISOString(),
+            context: {
+                source: context?.source ?? this.config.defaultSource,
+                ...context,
+            },
+            error,
+        };
+        // Stage 2: Individual transport level filtering
+        for (const transport of this.config.transports) {
+            if (level >= transport.minLevel) {
+                try {
+                    transport.write(entry);
+                }
+                catch (err) {
+                    // Avoid infinite loops - just console.error transport failures
+                    console.error(`[Logger] Transport "${transport.name}" failed:`, err);
+                }
+            }
+        }
+    }
+};
+LoggerService = __decorate([
+    injectable(),
+    __param(0, inject('LoggerConfig')),
+    __metadata("design:paramtypes", [Object])
+], LoggerService);
+export { LoggerService };
+/**
+ * A lightweight logger wrapper with a preset source and domain context.
+ * Created via LoggerService.child(), .framework(), .client(), or .external()
+ */
+export class ChildLogger {
+    parent;
+    source;
+    domain;
+    constructor(parent, source, domain) {
+        this.parent = parent;
+        this.source = source;
+        this.domain = domain;
+    }
+    buildContext(context) {
+        return {
+            ...context,
+            source: this.source,
+            ...(this.domain && { domain: this.domain }),
+        };
+    }
+    trace(message, context) {
+        this.parent.trace(message, this.buildContext(context));
+    }
+    debug(message, context) {
+        this.parent.debug(message, this.buildContext(context));
+    }
+    info(message, context) {
+        this.parent.info(message, this.buildContext(context));
+    }
+    warn(message, context) {
+        this.parent.warn(message, this.buildContext(context));
+    }
+    error(message, context, error) {
+        this.parent.error(message, this.buildContext(context), error);
+    }
+    fatal(message, context, error) {
+        this.parent.fatal(message, this.buildContext(context), error);
+    }
+}

package/dist/kernel/logger/logger.types.js

@@ -0,0 +1,70 @@
+/**
+ * Log severity levels ordered from most verbose to most critical.
+ * The numeric values allow for easy comparison and filtering.
+ */
+export var LogLevel;
+(function (LogLevel) {
+    LogLevel[LogLevel["TRACE"] = 0] = "TRACE";
+    LogLevel[LogLevel["DEBUG"] = 1] = "DEBUG";
+    LogLevel[LogLevel["INFO"] = 2] = "INFO";
+    LogLevel[LogLevel["WARN"] = 3] = "WARN";
+    LogLevel[LogLevel["ERROR"] = 4] = "ERROR";
+    LogLevel[LogLevel["FATAL"] = 5] = "FATAL";
+    LogLevel[LogLevel["OFF"] = 6] = "OFF";
+})(LogLevel || (LogLevel = {}));
+/**
+ * Human-readable labels for each log level.
+ */
+export const LogLevelLabels = {
+    [LogLevel.TRACE]: 'TRACE',
+    [LogLevel.DEBUG]: 'DEBUG',
+    [LogLevel.INFO]: 'INFO',
+    [LogLevel.WARN]: 'WARN',
+    [LogLevel.ERROR]: 'ERROR',
+    [LogLevel.FATAL]: 'FATAL',
+    [LogLevel.OFF]: 'OFF',
+};
+/**
+ * Domain/origin of the log entry.
+ * Helps identify where the log originates from for better traceability.
+ */
+export var LogDomain;
+(function (LogDomain) {
+    /**
+     * Internal framework logs (OpenCore internals).
+     * Used for core errors, bootstrap messages, decorator processing, etc.
+     */
+    LogDomain["FRAMEWORK"] = "framework";
+    /**
+     * Server-side application logs.
+     * Used by resource developers for their server logic.
+     */
+    LogDomain["SERVER"] = "server";
+    /**
+     * Client-side application logs.
+     * Used by resource developers for their client logic.
+     */
+    LogDomain["CLIENT"] = "client";
+    /**
+     * External service logs.
+     * Used for third-party APIs, databases, HTTP requests, etc.
+     */
+    LogDomain["EXTERNAL"] = "external";
+})(LogDomain || (LogDomain = {}));
+/**
+ * Human-readable labels for each log domain.
+ */
+export const LogDomainLabels = {
+    [LogDomain.FRAMEWORK]: 'CORE',
+    [LogDomain.SERVER]: 'SERVER',
+    [LogDomain.CLIENT]: 'CLIENT',
+    [LogDomain.EXTERNAL]: 'EXTERNAL',
+};
+/**
+ * Configuration for parsing log level from string (useful for env vars).
+ */
+export function parseLogLevel(value) {
+    const upper = value.toUpperCase();
+    const level = LogLevel[upper];
+    return level !== undefined ? level : LogLevel.INFO;
+}

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

@@ -0,0 +1,88 @@
+import { type LogEntry, LogLevel } from '../logger.types';
+import { LogTransport } from './transport.interface';
+/**
+ * Output format for exported logs.
+ */
+export type LogOutputFormat = 'json' | 'text' | 'csv';
+export interface BufferedTransportOptions {
+    /**
+     * Minimum log level to buffer. Defaults to DEBUG.
+     */
+    minLevel?: LogLevel;
+    /**
+     * Maximum number of entries to keep in buffer.
+     * Older entries are removed when limit is reached (FIFO).
+     * @default 1000
+     */
+    maxEntries?: number;
+    /**
+     * Callback triggered when buffer reaches maxEntries.
+     * Useful for auto-flushing to external storage.
+     */
+    onBufferFull?: (entries: LogEntry[]) => void;
+}
+/**
+ * A transport that buffers log entries in memory for later export.
+ *
+ * Use this when you need to:
+ * - Export logs to a file via FiveM's SaveResourceFile
+ * - Send logs to an external API in batches
+ * - Display logs in a UI
+ *
+ * @example
+ * ```typescript
+ * const buffered = new BufferedTransport({
+ *   minLevel: LogLevel.INFO,
+ *   maxEntries: 500,
+ *   onBufferFull: (entries) => {
+ *     // Auto-save when buffer is full
+ *     const content = buffered.export('text')
+ *     SaveResourceFile(GetCurrentResourceName(), 'logs/app.log', content, -1)
+ *     buffered.clear()
+ *   }
+ * })
+ *
+ * logger.addTransport(buffered)
+ *
+ * // Later, export manually
+ * const jsonLogs = buffered.export('json')
+ * const textLogs = buffered.export('text')
+ * ```
+ */
+export declare class BufferedTransport implements LogTransport {
+    readonly name = "buffered";
+    minLevel: LogLevel;
+    private buffer;
+    private maxEntries;
+    private onBufferFull?;
+    constructor(options?: BufferedTransportOptions);
+    write(entry: LogEntry): void;
+    /**
+     * Get all buffered entries.
+     */
+    getEntries(): readonly LogEntry[];
+    /**
+     * Get the current buffer size.
+     */
+    size(): number;
+    /**
+     * Clear the buffer.
+     */
+    clear(): void;
+    /**
+     * Export buffered logs in the specified format.
+     *
+     * @param format - Output format: 'json', 'text', or 'csv'
+     * @returns Formatted string ready for saving
+     */
+    export(format?: LogOutputFormat): string;
+    /**
+     * Export and clear buffer in one operation.
+     */
+    flush(format?: LogOutputFormat): string;
+    private exportJson;
+    private exportText;
+    private exportCsv;
+    private cleanContext;
+    destroy(): void;
+}

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

@@ -0,0 +1,154 @@
+import { LogDomainLabels, LogLevel, LogLevelLabels } from '../logger.types';
+/**
+ * A transport that buffers log entries in memory for later export.
+ *
+ * Use this when you need to:
+ * - Export logs to a file via FiveM's SaveResourceFile
+ * - Send logs to an external API in batches
+ * - Display logs in a UI
+ *
+ * @example
+ * ```typescript
+ * const buffered = new BufferedTransport({
+ *   minLevel: LogLevel.INFO,
+ *   maxEntries: 500,
+ *   onBufferFull: (entries) => {
+ *     // Auto-save when buffer is full
+ *     const content = buffered.export('text')
+ *     SaveResourceFile(GetCurrentResourceName(), 'logs/app.log', content, -1)
+ *     buffered.clear()
+ *   }
+ * })
+ *
+ * logger.addTransport(buffered)
+ *
+ * // Later, export manually
+ * const jsonLogs = buffered.export('json')
+ * const textLogs = buffered.export('text')
+ * ```
+ */
+export class BufferedTransport {
+    name = 'buffered';
+    minLevel;
+    buffer = [];
+    maxEntries;
+    onBufferFull;
+    constructor(options = {}) {
+        this.minLevel = options.minLevel ?? LogLevel.DEBUG;
+        this.maxEntries = options.maxEntries ?? 1000;
+        this.onBufferFull = options.onBufferFull;
+    }
+    write(entry) {
+        this.buffer.push(entry);
+        // Check buffer limit
+        if (this.buffer.length >= this.maxEntries) {
+            if (this.onBufferFull) {
+                this.onBufferFull([...this.buffer]);
+            }
+            // Remove oldest entries to make room
+            this.buffer = this.buffer.slice(-Math.floor(this.maxEntries * 0.8));
+        }
+    }
+    /**
+     * Get all buffered entries.
+     */
+    getEntries() {
+        return this.buffer;
+    }
+    /**
+     * Get the current buffer size.
+     */
+    size() {
+        return this.buffer.length;
+    }
+    /**
+     * Clear the buffer.
+     */
+    clear() {
+        this.buffer = [];
+    }
+    /**
+     * Export buffered logs in the specified format.
+     *
+     * @param format - Output format: 'json', 'text', or 'csv'
+     * @returns Formatted string ready for saving
+     */
+    export(format = 'text') {
+        switch (format) {
+            case 'json':
+                return this.exportJson();
+            case 'csv':
+                return this.exportCsv();
+            default:
+                return this.exportText();
+        }
+    }
+    /**
+     * Export and clear buffer in one operation.
+     */
+    flush(format = 'text') {
+        const content = this.export(format);
+        this.clear();
+        return content;
+    }
+    exportJson() {
+        const entries = this.buffer.map((entry) => ({
+            timestamp: entry.timestamp,
+            level: LogLevelLabels[entry.level],
+            domain: LogDomainLabels[entry.domain],
+            source: entry.context?.source,
+            message: entry.message,
+            context: this.cleanContext(entry.context),
+            error: entry.error
+                ? {
+                    name: entry.error.name,
+                    message: entry.error.message,
+                    stack: entry.error.stack,
+                }
+                : undefined,
+        }));
+        return JSON.stringify(entries, null, 2);
+    }
+    exportText() {
+        return this.buffer
+            .map((entry) => {
+            const time = entry.timestamp.replace('T', ' ').slice(0, 23);
+            const level = LogLevelLabels[entry.level].padEnd(5);
+            const domain = LogDomainLabels[entry.domain].padEnd(8);
+            const source = entry.context?.source ? `[${entry.context.source}]` : '';
+            let line = `${time} | ${domain} | ${level} | ${source} ${entry.message}`;
+            const ctx = this.cleanContext(entry.context);
+            if (Object.keys(ctx).length > 0) {
+                line += ` | ctx: ${JSON.stringify(ctx)}`;
+            }
+            if (entry.error?.stack) {
+                line += `\n    └─ ${entry.error.stack.replace(/\n/g, '\n    ')}`;
+            }
+            return line;
+        })
+            .join('\n');
+    }
+    exportCsv() {
+        const headers = ['timestamp', 'level', 'domain', 'source', 'message', 'context', 'error'];
+        const rows = this.buffer.map((entry) => [
+            entry.timestamp,
+            LogLevelLabels[entry.level],
+            LogDomainLabels[entry.domain],
+            entry.context?.source ?? '',
+            `"${entry.message.replace(/"/g, '""')}"`,
+            JSON.stringify(this.cleanContext(entry.context)),
+            entry.error?.message ?? '',
+        ]);
+        return [headers.join(','), ...rows.map((row) => row.join(','))].join('\n');
+    }
+    cleanContext(context) {
+        if (!context)
+            return {};
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+        const { source, domain, ...rest } = context;
+        return rest;
+    }
+    destroy() {
+        this.clear();
+    }
+}

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

@@ -0,0 +1,37 @@
+import { type LogEntry, LogLevel } from '../logger.types';
+import { LogTransport } from './transport.interface';
+export interface ConsoleTransportOptions {
+    /**
+     * Minimum log level to output. Defaults to DEBUG.
+     */
+    minLevel?: LogLevel;
+    /**
+     * Whether to use colors in output. Defaults to true.
+     */
+    colors?: boolean;
+    /**
+     * Whether to include timestamp in output. Defaults to true.
+     */
+    timestamps?: boolean;
+}
+/**
+ * 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 declare class ConsoleTransport implements LogTransport {
+    readonly name = "console";
+    minLevel: LogLevel;
+    private colors;
+    private timestamps;
+    constructor(options?: ConsoleTransportOptions);
+    write(entry: LogEntry): void;
+}