@open-core/framework 0.1.0-alpha.1

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

@@ -0,0 +1,37 @@
+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;
+}

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

@@ -0,0 +1,134 @@
+"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.ConsoleTransport = void 0;
+const logger_types_1 = require("../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 = {
+    [logger_types_1.LogLevel.TRACE]: COLORS.dim,
+    [logger_types_1.LogLevel.DEBUG]: COLORS.cyan,
+    [logger_types_1.LogLevel.INFO]: COLORS.green,
+    [logger_types_1.LogLevel.WARN]: COLORS.yellow,
+    [logger_types_1.LogLevel.ERROR]: COLORS.red,
+    [logger_types_1.LogLevel.FATAL]: COLORS.magenta,
+    [logger_types_1.LogLevel.OFF]: COLORS.white,
+};
+/**
+ * Domain colors - distinctive to quickly identify log origin.
+ */
+const DOMAIN_COLORS = {
+    [logger_types_1.LogDomain.FRAMEWORK]: COLORS.magenta,
+    [logger_types_1.LogDomain.SERVER]: COLORS.blue,
+    [logger_types_1.LogDomain.CLIENT]: COLORS.cyan,
+    [logger_types_1.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
+ * })
+ * ```
+ */
+class ConsoleTransport {
+    constructor(options = {}) {
+        var _a, _b, _c;
+        this.name = 'console';
+        this.minLevel = (_a = options.minLevel) !== null && _a !== void 0 ? _a : logger_types_1.LogLevel.DEBUG;
+        this.colors = (_b = options.colors) !== null && _b !== void 0 ? _b : true;
+        this.timestamps = (_c = options.timestamps) !== null && _c !== void 0 ? _c : true;
+    }
+    write(entry) {
+        var _a, _b;
+        const { level, domain, message, timestamp, context, error } = entry;
+        const levelLabel = logger_types_1.LogLevelLabels[level].padEnd(5);
+        const domainLabel = logger_types_1.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 = (_b = (_a = timestamp.split('T')[1]) === null || _a === void 0 ? void 0 : _a.slice(0, 12)) !== null && _b !== void 0 ? _b : 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 === null || context === void 0 ? void 0 : 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 logger_types_1.LogLevel.TRACE:
+            case logger_types_1.LogLevel.DEBUG:
+                console.debug(logLine);
+                break;
+            case logger_types_1.LogLevel.INFO:
+                console.info(logLine);
+                break;
+            case logger_types_1.LogLevel.WARN:
+                console.warn(logLine);
+                break;
+            case logger_types_1.LogLevel.ERROR:
+            case logger_types_1.LogLevel.FATAL:
+                console.error(logLine);
+                break;
+            default:
+                console.log(logLine);
+        }
+        // Output context if present (excluding source and domain which are already shown)
+        if (context) {
+            const { source, domain: _ } = context, rest = __rest(context, ["source", "domain"]);
+            if (Object.keys(rest).length > 0) {
+                console.debug(`${dim}  └─ context:${reset}`, rest);
+            }
+        }
+        // Output error stack if present
+        if (error === null || error === void 0 ? void 0 : error.stack) {
+            console.error(`${dim}  └─ stack:${reset}`, error.stack);
+        }
+    }
+}
+exports.ConsoleTransport = ConsoleTransport;

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

@@ -0,0 +1,3 @@
+export * from './transport.interface';
+export * from './console.transport';
+export * from './buffered.transport';

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

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./transport.interface"), exports);
+__exportStar(require("./console.transport"), exports);
+__exportStar(require("./buffered.transport"), exports);

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

@@ -0,0 +1,40 @@
+import type { LogEntry, LogLevel } from '../logger.types';
+/**
+ * Contract that all log transports must implement.
+ *
+ * A transport is responsible for delivering log entries to a specific destination
+ * (console, file, database, external service, etc.).
+ *
+ * @example
+ * ```typescript
+ * class FileTransport implements LogTransport {
+ *   name = 'file'
+ *   minLevel = LogLevel.WARN
+ *
+ *   write(entry: LogEntry): void {
+ *     fs.appendFileSync('app.log', JSON.stringify(entry) + '\n')
+ *   }
+ * }
+ * ```
+ */
+export interface LogTransport {
+    /**
+     * Unique identifier for this transport.
+     * Used for debugging and transport management.
+     */
+    readonly name: string;
+    /**
+     * Minimum log level this transport will handle.
+     * Entries below this level will be ignored by this transport.
+     */
+    minLevel: LogLevel;
+    /**
+     * Process and deliver a log entry to its destination.
+     * @param entry - The log entry to process
+     */
+    write(entry: LogEntry): void;
+    /**
+     * Optional cleanup method called when the transport is removed or the logger is destroyed.
+     */
+    destroy?(): void;
+}

package/dist/shared/logger/transports/transport.interface.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/system/class-constructor.d.ts

@@ -0,0 +1 @@
+export type ClassConstructor<T = any> = new (...args: any[]) => T;

package/dist/system/class-constructor.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/system/decorator-processor.d.ts

@@ -0,0 +1,4 @@
+export interface DecoratorProcessor {
+    readonly metadataKey: string;
+    process(target: any, methodName: string, metadata: any): void;
+}

package/dist/system/decorator-processor.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/system/metadata.scanner.d.ts

@@ -0,0 +1,7 @@
+import { DecoratorProcessor } from './decorator-processor';
+import { ClassConstructor } from './class-constructor';
+export declare class MetadataScanner {
+    private processors;
+    constructor(processors: DecoratorProcessor[]);
+    scan(registry: ClassConstructor[]): void;
+}

package/dist/system/metadata.scanner.js

@@ -0,0 +1,45 @@
+"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);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MetadataScanner = void 0;
+const tsyringe_1 = require("tsyringe");
+const logger_1 = require("../shared/logger");
+let MetadataScanner = class MetadataScanner {
+    constructor(processors) {
+        this.processors = processors;
+    }
+    scan(registry) {
+        logger_1.loggers.scanner.info(`Scanning ${registry.length} controllers with ${this.processors.length} processors`);
+        for (const ControllerClass of registry) {
+            const instance = tsyringe_1.container.resolve(ControllerClass);
+            const prototype = Object.getPrototypeOf(instance);
+            const methods = Object.getOwnPropertyNames(prototype).filter((m) => m !== 'constructor' && typeof instance[m] === 'function');
+            for (const methodName of methods) {
+                for (const processor of this.processors) {
+                    const metadata = Reflect.getMetadata(processor.metadataKey, prototype, methodName);
+                    if (metadata) {
+                        processor.process(instance, methodName, metadata);
+                    }
+                }
+            }
+        }
+        logger_1.loggers.scanner.debug(`Metadata scan complete`);
+    }
+};
+exports.MetadataScanner = MetadataScanner;
+exports.MetadataScanner = MetadataScanner = __decorate([
+    (0, tsyringe_1.injectable)(),
+    __param(0, (0, tsyringe_1.injectAll)('DecoratorProcessor')),
+    __metadata("design:paramtypes", [Array])
+], MetadataScanner);

package/dist/utils/errors.d.ts

@@ -0,0 +1,14 @@
+import type { SecurityAction } from '../server/types/security.types';
+export type FrameworkErroCode = 'PLAYER_NOT_FOUND' | 'INSUFFICIENT_FUNDS' | 'VALIDATION_ERROR' | 'API_ERROR' | 'NETWORK_ERROR' | 'UNAUTHORIZED' | 'PERMISSION_DENIED' | 'NOT_IMPLEMENTED' | 'NO_RANK_IN_PRINCIPAL' | 'UNKNOWN' | 'GAME_STATE_ERROR';
+export type ErrorOrigin = 'client' | 'server' | 'core' | 'external';
+export declare class AppError extends Error {
+    readonly code: FrameworkErroCode;
+    readonly details?: unknown;
+    readonly origin: ErrorOrigin;
+    constructor(code: FrameworkErroCode, message: string, origin: ErrorOrigin, details?: unknown);
+}
+export declare function isAppError(error: unknown): error is AppError;
+export declare class SecurityError extends AppError {
+    readonly action: SecurityAction;
+    constructor(action: SecurityAction, message: string, details?: unknown);
+}

package/dist/utils/errors.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SecurityError = exports.AppError = void 0;
+exports.isAppError = isAppError;
+class AppError extends Error {
+    constructor(code, message, origin, details) {
+        super(message);
+        this.code = code;
+        this.details = details;
+        this.origin = origin;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+exports.AppError = AppError;
+function isAppError(error) {
+    return error instanceof AppError;
+}
+class SecurityError extends AppError {
+    constructor(action, message, details) {
+        super('NETWORK_ERROR', message, 'core', details);
+        this.action = action;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+exports.SecurityError = SecurityError;

package/dist/utils/index.d.ts

@@ -0,0 +1,4 @@
+export * from './errors';
+export * from './result';
+export * from './vector3';
+export * from './rgb';

package/dist/utils/index.js

@@ -0,0 +1,20 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./errors"), exports);
+__exportStar(require("./result"), exports);
+__exportStar(require("./vector3"), exports);
+__exportStar(require("./rgb"), exports);

package/dist/utils/result.d.ts

@@ -0,0 +1,12 @@
+import type { AppError } from './errors';
+export interface Ok<T> {
+    ok: true;
+    value: T;
+}
+export interface Err<E = AppError> {
+    ok: false;
+    error: E;
+}
+export type Result<T, E = AppError> = Ok<T> | Err<E>;
+export declare function ok<T>(value: T): Ok<T>;
+export declare function err<E>(error: E): Err<E>;

package/dist/utils/result.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ok = ok;
+exports.err = err;
+function ok(value) {
+    return { ok: true, value };
+}
+function err(error) {
+    return { ok: false, error };
+}

package/dist/utils/rgb.d.ts

@@ -0,0 +1,5 @@
+export interface RGB {
+    r: number;
+    g: number;
+    b: number;
+}

package/dist/utils/rgb.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/utils/vector3.d.ts

@@ -0,0 +1,13 @@
+export type Vector3 = {
+    x: number;
+    y: number;
+    z: number;
+};
+export declare class Vec3 {
+    static create(x: number, y: number, z: number): Vector3;
+    static clone(v: Vector3): Vector3;
+    static add(a: Vector3, b: Vector3): Vector3;
+    static sub(a: Vector3, b: Vector3): Vector3;
+    static distance(a: Vector3, b: Vector3): number;
+    static equals(a: Vector3, b: Vector3): boolean;
+}

package/dist/utils/vector3.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Vec3 = void 0;
+class Vec3 {
+    static create(x, y, z) {
+        return { x, y, z };
+    }
+    static clone(v) {
+        return { x: v.x, y: v.y, z: v.z };
+    }
+    static add(a, b) {
+        return { x: a.x + b.x, y: a.y + b.y, z: a.z + b.z };
+    }
+    static sub(a, b) {
+        return { x: a.x - b.x, y: a.y - b.y, z: a.z - b.z };
+    }
+    static distance(a, b) {
+        const dx = a.x - b.x;
+        const dy = a.y - b.y;
+        const dz = a.z - b.z;
+        return Math.sqrt(dx * dx + dy * dy + dz * dz);
+    }
+    static equals(a, b) {
+        return a.x === b.x && a.y === b.y && a.z === b.z;
+    }
+}
+exports.Vec3 = Vec3;

package/package.json

@@ -0,0 +1,98 @@
+{
+  "name": "@open-core/framework",
+  "version": "0.1.0-alpha.1",
+  "description": "Secure, Event-Driven, OOP Engine for FiveM. Stop scripting, start engineering.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "commonjs",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/newcore-network/opencore.git"
+  },
+  "homepage": "https://github.com/newcore-network/opencore",
+  "bugs": {
+    "url": "https://github.com/newcore-network/opencore/issues"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/server/index.d.ts",
+      "import": "./dist/server/index.js",
+      "require": "./dist/server/index.js"
+    },
+    "./client": {
+      "types": "./dist/client/index.d.ts",
+      "import": "./dist/client/index.js",
+      "require": "./dist/client/index.js"
+    },
+    "./shared": {
+      "types": "./dist/shared/index.d.ts",
+      "import": "./dist/shared/index.js",
+      "require": "./dist/shared/index.js"
+    },
+    "./utils": {
+      "types": "./dist/utils/index.d.ts",
+      "import": "./dist/utils/index.js",
+      "require": "./dist/utils/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "watch": "tsc -p tsconfig.build.json --watch",
+    "lint": "eslint . --ext .ts",
+    "lint:fix": "eslint . --ext .ts --fix",
+    "format": "prettier --write .",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:unit": "vitest run --project unit",
+    "test:integration": "vitest run --project integration",
+    "test:coverage": "vitest run --coverage",
+    "bench": "tsx benchmark/index.ts",
+    "bench:core": "tsx benchmark/index.ts --core",
+    "bench:load": "vitest run --project benchmark",
+    "bench:all": "tsx benchmark/index.ts --all"
+  },
+  "keywords": [
+    "framework",
+    "opencore",
+    "fivem",
+    "typescript",
+    "roleplay"
+  ],
+  "author": "OpenCore Team",
+  "license": "MPL-2.0",
+  "packageManager": "pnpm@10.13.1",
+  "dependencies": {
+    "reflect-metadata": "^0.2.2",
+    "tsyringe": "^4.10.0",
+    "uuid": "^13.0.0",
+    "zod": "^4.1.13"
+  },
+  "devDependencies": {
+    "@citizenfx/client": "2.0.22443-1",
+    "@citizenfx/server": "2.0.22443-1",
+    "@types/node": "^24.10.1",
+    "@typescript-eslint/eslint-plugin": "^8.48.1",
+    "@typescript-eslint/parser": "^8.48.1",
+    "@vitest/coverage-v8": "^4.0.15",
+    "eslint": "^9.39.1",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-import": "^2.32.0",
+    "eslint-plugin-prettier": "^5.5.4",
+    "prettier": "3.7.1",
+    "tinybench": "^2.7.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.15"
+  }
+}