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

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

@@ -1,279 +0,0 @@
-"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.js

@@ -1,74 +0,0 @@
-"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

@@ -1,88 +0,0 @@
-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

@@ -1,174 +0,0 @@
-"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;

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

@@ -1,37 +0,0 @@
-import { LogLevel, type LogEntry } from '../logger.types';
-import type { 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;
-}