@open-core/framework 0.1.0-alpha.1

package/dist/shared/logger/logger.service.js

@@ -0,0 +1,279 @@
+"use strict";
+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);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ChildLogger = exports.LoggerService = void 0;
+const tsyringe_1 = require("tsyringe");
+const logger_config_1 = require("./logger.config");
+const logger_types_1 = require("./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 {
+    constructor(config) {
+        this.config = (0, logger_config_1.createLoggerConfig)(config !== null && config !== void 0 ? config : {});
+    }
+    // ─────────────────────────────────────────────────────────────────────────────
+    // Log Methods
+    // ─────────────────────────────────────────────────────────────────────────────
+    /**
+     * Log a TRACE level message. Most verbose, for deep debugging.
+     */
+    trace(message, context) {
+        this.log(logger_types_1.LogLevel.TRACE, message, context);
+    }
+    /**
+     * Log a DEBUG level message. Development-time information.
+     */
+    debug(message, context) {
+        this.log(logger_types_1.LogLevel.DEBUG, message, context);
+    }
+    /**
+     * Log an INFO level message. General operational information.
+     */
+    info(message, context) {
+        this.log(logger_types_1.LogLevel.INFO, message, context);
+    }
+    /**
+     * Log a WARN level message. Something unexpected but not necessarily wrong.
+     */
+    warn(message, context) {
+        this.log(logger_types_1.LogLevel.WARN, message, context);
+    }
+    /**
+     * Log an ERROR level message. Something went wrong but the app can continue.
+     */
+    error(message, context, error) {
+        this.log(logger_types_1.LogLevel.ERROR, message, context, error);
+    }
+    /**
+     * Log a FATAL level message. Critical error, the app may need to stop.
+     */
+    fatal(message, context, error) {
+        this.log(logger_types_1.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) {
+        var _a;
+        const index = this.config.transports.findIndex((t) => t.name === name);
+        if (index === -1)
+            return false;
+        const [removed] = this.config.transports.splice(index, 1);
+        (_a = removed === null || removed === void 0 ? void 0 : removed.destroy) === null || _a === void 0 ? void 0 : _a.call(removed);
+        return true;
+    }
+    /**
+     * Get all registered transports.
+     */
+    getTransports() {
+        return this.config.transports;
+    }
+    /**
+     * Clear all transports.
+     */
+    clearTransports() {
+        var _a;
+        for (const transport of this.config.transports) {
+            (_a = transport.destroy) === null || _a === void 0 ? void 0 : _a.call(transport);
+        }
+        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, logger_types_1.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, logger_types_1.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, logger_types_1.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, logger_types_1.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
+    // ─────────────────────────────────────────────────────────────────────────────
+    log(level, message, context, error) {
+        var _a, _b;
+        // Check global minimum level
+        if (level < this.config.minLevel)
+            return;
+        const entry = {
+            level,
+            domain: (_a = context === null || context === void 0 ? void 0 : context.domain) !== null && _a !== void 0 ? _a : this.config.defaultDomain,
+            message,
+            timestamp: new Date().toISOString(),
+            context: Object.assign({ source: (_b = context === null || context === void 0 ? void 0 : context.source) !== null && _b !== void 0 ? _b : this.config.defaultSource }, context),
+            error,
+        };
+        // Dispatch to all transports that accept this level
+        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);
+                }
+            }
+        }
+    }
+};
+exports.LoggerService = LoggerService;
+exports.LoggerService = LoggerService = __decorate([
+    (0, tsyringe_1.injectable)(),
+    __metadata("design:paramtypes", [Object])
+], LoggerService);
+/**
+ * A lightweight logger wrapper with a preset source and domain context.
+ * Created via LoggerService.child(), .framework(), .client(), or .external()
+ */
+class ChildLogger {
+    constructor(parent, source, domain) {
+        this.parent = parent;
+        this.source = source;
+        this.domain = domain;
+    }
+    buildContext(context) {
+        return Object.assign(Object.assign(Object.assign({}, 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);
+    }
+}
+exports.ChildLogger = ChildLogger;

package/dist/shared/logger/logger.types.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Log severity levels ordered from most verbose to most critical.
+ * The numeric values allow for easy comparison and filtering.
+ */
+export declare enum LogLevel {
+    TRACE = 0,
+    DEBUG = 1,
+    INFO = 2,
+    WARN = 3,
+    ERROR = 4,
+    FATAL = 5,
+    OFF = 6
+}
+/**
+ * Human-readable labels for each log level.
+ */
+export declare const LogLevelLabels: Record<LogLevel, string>;
+/**
+ * Domain/origin of the log entry.
+ * Helps identify where the log originates from for better traceability.
+ */
+export declare enum LogDomain {
+    /**
+     * Internal framework logs (OpenCore internals).
+     * Used for core errors, bootstrap messages, decorator processing, etc.
+     */
+    FRAMEWORK = "framework",
+    /**
+     * Server-side application logs.
+     * Used by resource developers for their server logic.
+     */
+    SERVER = "server",
+    /**
+     * Client-side application logs.
+     * Used by resource developers for their client logic.
+     */
+    CLIENT = "client",
+    /**
+     * External service logs.
+     * Used for third-party APIs, databases, HTTP requests, etc.
+     */
+    EXTERNAL = "external"
+}
+/**
+ * Human-readable labels for each log domain.
+ */
+export declare const LogDomainLabels: Record<LogDomain, string>;
+/**
+ * Additional contextual information that can be attached to any log entry.
+ * Useful for tracing, debugging, and correlation.
+ */
+export interface LogContext {
+    /** Domain/origin of the log (framework, server, client, external) */
+    domain?: LogDomain;
+    /** Source module, controller or service name */
+    source?: string;
+    /** Unique identifier for tracing related operations */
+    traceId?: string;
+    /** Player ID if the log is related to a player action */
+    playerId?: number;
+    /** Any additional metadata */
+    [key: string]: unknown;
+}
+/**
+ * Represents a single log entry with all its metadata.
+ * This is what gets passed to transports for processing.
+ */
+export interface LogEntry {
+    /** Severity level of this log */
+    level: LogLevel;
+    /** Domain/origin of the log */
+    domain: LogDomain;
+    /** The main log message */
+    message: string;
+    /** ISO 8601 timestamp when the log was created */
+    timestamp: string;
+    /** Optional contextual data */
+    context?: LogContext;
+    /** Optional error object if logging an error */
+    error?: Error;
+}
+/**
+ * Configuration for parsing log level from string (useful for env vars).
+ */
+export declare function parseLogLevel(value: string): LogLevel;

package/dist/shared/logger/logger.types.js

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LogDomainLabels = exports.LogDomain = exports.LogLevelLabels = exports.LogLevel = void 0;
+exports.parseLogLevel = parseLogLevel;
+/**
+ * Log severity levels ordered from most verbose to most critical.
+ * The numeric values allow for easy comparison and filtering.
+ */
+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 || (exports.LogLevel = LogLevel = {}));
+/**
+ * Human-readable labels for each log level.
+ */
+exports.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.
+ */
+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 || (exports.LogDomain = LogDomain = {}));
+/**
+ * Human-readable labels for each log domain.
+ */
+exports.LogDomainLabels = {
+    [LogDomain.FRAMEWORK]: 'CORE',
+    [LogDomain.SERVER]: 'SERVER',
+    [LogDomain.CLIENT]: 'CLIENT',
+    [LogDomain.EXTERNAL]: 'EXTERNAL',
+};
+/**
+ * Configuration for parsing log level from string (useful for env vars).
+ */
+function parseLogLevel(value) {
+    const upper = value.toUpperCase();
+    const level = LogLevel[upper];
+    return level !== undefined ? level : LogLevel.INFO;
+}

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

@@ -0,0 +1,88 @@
+import { LogLevel, type LogEntry } from '../logger.types';
+import type { 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/shared/logger/transports/buffered.transport.js

@@ -0,0 +1,174 @@
+"use strict";
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BufferedTransport = void 0;
+const logger_types_1 = require("../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')
+ * ```
+ */
+class BufferedTransport {
+    constructor(options = {}) {
+        var _a, _b;
+        this.name = 'buffered';
+        this.buffer = [];
+        this.minLevel = (_a = options.minLevel) !== null && _a !== void 0 ? _a : logger_types_1.LogLevel.DEBUG;
+        this.maxEntries = (_b = options.maxEntries) !== null && _b !== void 0 ? _b : 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();
+            case 'text':
+            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) => {
+            var _a;
+            return ({
+                timestamp: entry.timestamp,
+                level: logger_types_1.LogLevelLabels[entry.level],
+                domain: logger_types_1.LogDomainLabels[entry.domain],
+                source: (_a = entry.context) === null || _a === void 0 ? void 0 : _a.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) => {
+            var _a, _b;
+            const time = entry.timestamp.replace('T', ' ').slice(0, 23);
+            const level = logger_types_1.LogLevelLabels[entry.level].padEnd(5);
+            const domain = logger_types_1.LogDomainLabels[entry.domain].padEnd(8);
+            const source = ((_a = entry.context) === null || _a === void 0 ? void 0 : _a.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 ((_b = entry.error) === null || _b === void 0 ? void 0 : _b.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) => {
+            var _a, _b, _c, _d;
+            return [
+                entry.timestamp,
+                logger_types_1.LogLevelLabels[entry.level],
+                logger_types_1.LogDomainLabels[entry.domain],
+                (_b = (_a = entry.context) === null || _a === void 0 ? void 0 : _a.source) !== null && _b !== void 0 ? _b : '',
+                `"${entry.message.replace(/"/g, '""')}"`,
+                JSON.stringify(this.cleanContext(entry.context)),
+                (_d = (_c = entry.error) === null || _c === void 0 ? void 0 : _c.message) !== null && _d !== void 0 ? _d : '',
+            ];
+        });
+        return [headers.join(','), ...rows.map((row) => row.join(','))].join('\n');
+    }
+    cleanContext(context) {
+        if (!context)
+            return {};
+        const { source, domain } = context, rest = __rest(context, ["source", "domain"]);
+        return rest;
+    }
+    destroy() {
+        this.clear();
+    }
+}
+exports.BufferedTransport = BufferedTransport;